Getting SSL/TLS

ULYSSIS does not sell or offer any other SSL certificates than our self-signed certificate. We will however guide requests and install a certificate from the KU Leuven is you are eligible for one, and we will also install certificates you have bought elsewhere.

Requesting SSL from the KU Leuven

The KU Leuven partners with other universities to use free SSL for its services, organisations and employees. We have permission to request SSL for Student Unions recognized by LOKO or another official body. Organisations (Vrije Verenigingen) are required to be recognized by LOKO or another official body and need to supply a reasoning why they need SSL. Individual users can request SSL but ICTS will only grant permission with elaborate reasoning.

Before sending us a request the following steps have to be done:

• Setup the site that needs SSL
• Change the domain's organisation-attribute to KU Leuven or Katholieke Universiteit Leuven
• Create a forwarder from hostmaster@yourdomain.tld to ulyssis@ulyssis.org

Then you can send an email to ulyssis@ulyssis.org containing your name, the name of the organisation, what you will use SSL for and the domain and if needed a list of subdomains.

We will then generate the required cryptographic key and request and submit them with ICTS. It usually takes a few days before they have had time to verify both the domain and then the request for SSL itself. As soon as ICTS approves the request we will install the certificate and notify you.

External certificates

To install external certificates we require the certificate itself, the private key, and possibly the chain. We prefer you also send us (a link to) the documentation of your supplier. As certificate files, especially private keys, are a delicate matter we suggest you just email us the path in your homedirectory you've put them and we will move them over to the webserver safely. For more information concerning this procedure you can always contact us on ulyssis@ulyssis.org

Let's Encrypt

Certificate file structure

We currently do not have an automated system for renewing and deploying certificates such as those supplied by Let's Encrypt. We are however looking into automating this process in the future. Since more of our users are starting to use Let's Encrypt, and all of their certificates need to be renewed frequently, we have a specific procedure now.

When wishing to add a certificate with Let's Encrypt to your website, or renew your existing one, first create a folder letsencrypt in your home directory. Then add a folder per domain or group of domains:

mkdir letsencrypt
mkdir letsencrypt/mydomain.be

Certificates should be stored in these folders, according to the following file structure:

letsencrypt/
└── mydomain.be/
    ├── mydomain.be.chain
    ├── mydomain.be.crt
    └── mydomain.be.key

If you already possess the necessary files, renaming and copying them accordingly is sufficient. Otherwise, you can generate or renew your certificates using acme.sh:

Using acme.sh

Generating the certificates

Because the normal method of generating Let's Encrypt certificates, certbot, requires root access, it's impossible for normal users to do so on our servers. Luckily there are plenty of alternatives which implement the Let's Encrypt protocol.

In this tutorial, we'll be using the acme.sh program to generate our certificates on the ULYSSIS servers.

First of all, we download the acme.sh script and make it executable:

wget https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh
chmod +x acme.sh

Next we actually generate the certificates. Make sure to replace the necessary parts (email, webroot, domain name):

./acme.sh --issue --cert-file letsencrypt/mydomain.be/mydomain.be.crt --key-file letsencrypt/mydomain.be/mydomain.be.key --ca-file letsencrypt/mydomain.be/mydomain.be.chain --accountemail "email@example.com" -w /home/user/myusername/path/to/webroot -d mydomain.be -d www.mydomain.be

We use the "email@example.com" email address to remind us to renew our certificates. /home/user/myusername/path/to/webroot is the path to the webroot of the domain name. Note that we are issuing certificates for "mydomain.be" here. We also want to add the subdomain "www.mydomain.be" to the certificate, so we also pass it to the script. You can add additional subdomains if needed.

Renewing the certificates

To renew our certificates, we just execute:

./acme.sh --renew --cert-file letsencrypt/mydomain.be/mydomain.be.crt --key-file letsencrypt/mydomain.be/mydomain.be.key --ca-file letsencrypt/mydomain.be/mydomain.be.chain -d mydomain.be

Installing the certificates

We can check whether everything is stored correctly by executing:

ulyssis-certificate check mydomain.be

If everything looks good, you should only see lines starting with [ OK ]. Any line starting with [FAIL] or [ABRT] means a check has failed, you must correct this error before asking us to install your certificate.

Once you have placed your files in the correct folder, you can send us an email clearly stating for which domains we need to add certificates and where the files are stored. If you are renewing existing certificates, also clearly state that in your email.

We have largely automated the installation of certificates. If you do not follow these instructions, your request will be denied or you may end up with broken SSL. So make sure you follow this procedure carefully.

Logs

Due to the nature of our setup (dumb loadbalancer combined with shibboleth on webworkers), all https traffic will seem to come from our loadbalancer IP address instead of the actual originating IP address. Keep this in mind when checking log files.