Installation of new TLS certificates

The work described below can lead to the inaccessibility of your DRACOON may lead to inaccessibility of your DRACOON Server installation. Therefore create a backup of the current state of the installation before any work. This can be done e.g. by a snapshot. Alternatively you can also make a backup before before making the changes to the respective files described below, you can also manually manually (e.g. by creating a copy).

1Introduction

DRACOON Server uses in the standard installation the service "haproxy" as a Reverse Proxy - so to speak as the main entrance for all user requests to the DRACOON Server application.

The task of this reverse proxy service is on the one hand the distribution of the incoming user requests to the corresponding DRACOON server services (e.g. to the WebApp or to the the DRACOON Core Service for the DRACOON API). Further task of the haproxy is the provision of the transport encryption for the accesses to the DRACOON Server application - i.e. the encryption between the user clients and the DRACOON and the DRACOON server platform. For this purpose SSL/TLS certificates are used.

This tutorial is about exactly these certificates - or more precisely about the exchange of them.

2Preparation

Make sure that you have the certificate, all intermediate certificates, and the the private key in PEM format. As a rule, all of the offer a corresponding export for the issuance of such certificates. for the issuance of such certificates. I.e. if you open the certificate file with a simple text editor, it will have a content similar to the following example (format, not the actual content) the actual content):

The root certificate is explicitly not required, since this is already known to the clients by the operating system or browser. by the operating system or the browser.

3SSL certificate file

First you need to find out where in the file system the certificates for the for the haproxy service are stored.

To do this, run the following command on the server with the haproxy service:

sudo grep "bind :443" /etc/haproxy/haproxy.cfg

Option 1: A primary certificate with a directory for additional certificates

If the output looks like this, it is the default configuration from our installation instructions:

  bind :443 ssl crt /etc/pki/tls/private/haproxy_default.pem crt /etc/pki/tls/privat/haproxy/

The output contains 2 times the key "crt" each with a following path specification. In this concrete case this means that there are two places for storing of certificates in the system:

In the file /etc/pki/tls/private/haproxy_default.pem you will find the is the main certificate of haproxy. This must always be present. If the server use only one certificate, because there is only one mandantren with only with only one domain on the DRACOON Server Installtion, this must be exchanged be exchanged.
In the directory /etc/pki/tls/private/haproxy/ there may be additional certificates if required. These must have the file extension ".pem" and will be loaded additionally when haproxy is started. If directory is empty, no additional certificates will be loaded.

Option 2: Only a primary certificate

If the output looks like the following, only a defined, single certificate in the named file /etc/pki/tls/private/haproxy_default.pem is used:

  bind :443 ssl crt /etc/pki/tls/private/haproxy_default.pem

In this case, the content of this file must be replaced with the content for the new TLS certificate. must be replaced.

Option 3: Only one directory for certificates

If the output looks like the following, no default certificate has been defined and simply all certificates in this directory are read:

  bind :443 ssl crt /etc/pki/tls/privat/haproxy/

In this case, the new TLS certificate must be placed in any file in this directory with the .pem file extension. It is also recommended to delete the previous/outdated/expired certificate from this directory.

4Display the contents of the current certificate lassen

Since we now know which file or directory contains the currently used used TLS certificates are located, we can check their contents. To do this the following command:

sudo openssl x509 -in /etc/pki/tls/private/haproxy_default.pem -noout -dates

The output shows two pieces of information here:

The value of "notBefore" - i.e. the beginning of the validity of the current certificate.
The value of "notAfter" - i.e. the end of the validity of the current certificate.

The complete information (including the domain name for which the certificate was issued) can be displayed with the command was issued), can be displayed with the following command:

sudo openssl x509 -in /etc/pki/tls/private/haproxy_default.pem -noout -text

Here you can search for the value of "Subject: CN=", which contains the primary domain name of the certificate. of the certificate.

5Swap TLS certificate

Once you have found the appropriate file where the certificate is located, you can exchange it. However, make a backup of the certificate file before you do so. In the certificate file, the actual certificate is entered in the first place. Then follow all intermediate certificates (often there is only one intermediate certificate). certificate). Then comes the private key and finally optionally still the DH parameters. Note that you do not have to exchange the DH parameters. need to swap. In summary, the new certificate file will look something like this:

You can still use the following command to check whether the certificate chain is complete:

sudo openssl verify -CAfile /etc/pki/tls/cert.pem -untrusted /PATH/TO/CERT_FILE /PATH/TO/CERT_FILE

Please replace the value of "/PATH/TO/CERT_FILE" by the path of the certificate file, e.g. /etc/pki/tls/private/haproxy_default.pem

Afterwards the haproxy config must be checked:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

The result here should be "Configuration file is valid".

Finally, the haproxy service must be told to reread its configuration (including the certificates). (including the certificates):

sudo systemctl reload haproxy

6Change review

After exchanging a TLS certificate, we strongly recommend to check the the correctness of the TLS configuration to avoid errors and failures.

You can use the following online tools to do this:

With the 2nd tool, an extensive check of all TLS settings of the haproxy is carried out check of all TLS settings of the haproxy. The check takes a few minutes, but gives a very detailed result at the end. The goal is to complete the check with a green "A+" rating:

Articles in this section