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 or obtained elsewhere.

Requesting SSL from the KU Leuven

The KU Leuven partners with other universities through TERENA/Géant to arrange certificates for its services, organisations and academic structures. We have permission to request free SSL/TLS certificates for student unions (kringen) recognized by LOKO or faculty representative bodies (facultaire overlegorganen) recognized by Stura body as well as organisations (vrije verenigingen) recognized by LOKO or KU Leuven.

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

• Make sure our nameservers are being used for the involved domain(s), as explained on Adding domain names
• Set up the site that needs SSL if that's not already the case
• Create a forwarder from hostmaster@yourdomain.tld to ulyssis@ulyssis.org
• Consider all subdomains (whether separate websites or not) you wish to have certificates for
• Make a list of all relevant arguments for your use of SSL/TLS certificates. It's important to consider aspects of your website where important or personal information is exchanged: registration, login pages, newsletter signup, etc.

When all steps are done, the account holder of the ULYSSIS account can send an email to ulyssis@ulyssis.org containing their name, the name of the organisation, the relevant arguments what you will use SSL for and the domain and if needed a list of subdomains that should be covered by the certificate.

Based on our previous experience and our arrangements with ICTS we will consider whether you are eligible for certificates and whether your request is well-founded. We will then generate the required cryptographic key and request and submit them on the certificate platform supplied by ICTS and its partners. Depending on the situation, the verification and delivery of the certificate can take some time. As soon as the certificate has been issued, we will install it and notify you.

For procedures to request certificates, we follow instructions from ICTS. These instructions have changed several times in the past, so it's possible for a new request or for a renewal, you may have to follow a different procedure or make changes.

Limitations

ICTS does not allow SSL requests for historic *.student.kuleuven.be and *.student.kuleuven.ac.be domains. We judge requests for username.ulyssis.be and username.studentenweb.org on an individual basis.

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

Warning: If you use a .htaccess file in the webroot of the domain name, make sure to add the following lines at the top of the file:

<IfModule mod_rewrite.c>
  RewriteRule "^.well-known/acme-challenge" - [L]
</IfModule>

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, download the acme.sh script as explained in the documentation: https://github.com/acmesh-official/acme.sh#1-how-to-install

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

If we provide an email address, for example "email@example.com", Let's Encrypt will remind us to renew our certificates when necessary. /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 -d mydomain.be

The renewed certificates will automatically be copied to the path specified in the --issue command.

After renewing certificates, you have to email us to install your renewed certificate.

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.