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 consultative 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:

• 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
• Make sure our nameservers are being used for the involved domain(s), as explained on Adding domain names
• 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 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

Introduction

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 -p ~/letsencrypt/mydomain.be

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

letsencrypt/
└── mydomain.be/
    ├── mydomain.be.chain (the CA file)
    ├── mydomain.be.crt (the cert file; "public key")
    └── mydomain.be.key (the key file; "private key")

If you already possess the necessary files, renaming and copying them accordingly is sufficient. You still have to email us to install your certificate. More information in the last section on this page.

Otherwise, you can generate or renew your certificates using acme.sh. This is explained in the next section.

Generating certificates

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>

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 show how to use the acme.sh program to generate certificates on the ULYSSIS servers.

Firstly, execute the following commands to download the acme.sh script in your home directory and make it executable:

curl -o ~/acme.sh https://raw.githubusercontent.com/acmesh-official/acme.sh/master/acme.sh
chmod +x ~/acme.sh

Next, determine for which domains and subdomains you want to generate a certificate. You will need to generate a single certificate for each domain and subdomain which points to the same folder on your account (in most cases this is www in your home directory).

The following example command will generate a certificate for mydomain.be and www.mydomain.be which points to the www folder in the home directory. Change the parameters as explained below before executing this command!

~/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@mydomain.be" -w ~/www -d mydomain.be -d www.mydomain.be

The explanation of these many parameters is as follows:

• --issue tells acme.sh to generate a new certificate.
• --cert-file ~/letsencrypt/mydomain.be/mydomain.be.crt tells acme.sh to store the certificate file in the letsencrypt/mydomain.be folder in your home directory, using the special file name as required by the file structure. This folder should already exist, please refer to the previous section if you have not created this folder yet.
• --key-file ~/letsencrypt/mydomain.be/mydomain.be.key tells acme.sh to store the key file in the letsencrypt/mydomain.be folder in your home directory, using the special file name as required by the file structure.
• --ca-file ~/letsencrypt/mydomain.be/mydomain.be.chain tells acme.sh to store the CA file in the letsencrypt/mydomain.be folder in your home directory, using the special file name as required by the file structure.
• -m "email@mydomain.be" tells acme.sh the email address associated with the certificate. Let's Encrypt will remind this email address (if provided) when the certificate is close to expiring.
• -w ~/www tells acme.sh where the domains in this certificate point to. Make sure to change the www part if the domains point to a different folder in your home directory.
• -d mydomain.be and -d www.mydomain.be tell acme.sh that the certificate should protect mydomain.be and www.mydomain.be. You should add all domain names pointing to the -w folder.

After generating the certificate, you have to email us to install your new certificate. More information in the last section on this page.

Renewing certificates

To renew the certificates of mydomain.be, just execute:

~/acme.sh --renew -d mydomain.be

The renewed certificates will automatically be copied to the files you provided in the command to generate the certificates (see previous section).

After renewing the certificate, you have to email us to install your certificate. More information in the last section on this page.

Installing the certificates

Check whether everything is stored correctly by executing the following command:

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.