Renew a purchased certificate

This guide describes in detail how a new SSL certificate from a certificate authority (CA) is prepared for the Relution server and then put in place for Traefik or nginx. It is intended for administrators who carry out the procedure for the first time or only rarely. An overview of all installation variants is available under Renew SSL certificate →.

At the end of the procedure, two files are available:

• server.pem – the certificate chain: the server certificate, followed by the intermediate certificates of the certificate authority.
• server.key – the private key that belongs to the server certificate.

Steps 1 to 5 apply to every installation. Step 6 refers to the guide for the reverse proxy in use, which describes placing the files, the restart and the final check.

1. Convert the certificate to PEM format #

Certificate authorities deliver certificates in different formats, often with the file extensions .crt, .cer, .pem, .p7b or .pfx. The reverse proxy (Traefik or nginx) expects the certificate in PEM format, i.e. as a text file with Base64-encoded content.

Whether the certificate is already in PEM format can be seen by looking into the file, for example with a text editor or with the following command:

head -1 certificate.crt

If the first line reads -----BEGIN CERTIFICATE-----, the certificate is already in PEM format. It is saved as server-cert.pem (for example with cp certificate.crt server-cert.pem), and the procedure continues with step 2. If the first line reads -----BEGIN PKCS7----- or the file shows unreadable characters, it is converted with OpenSSL depending on the format:

If a P7B file begins with -----BEGIN PKCS7-----, it is already in text form; the -inform der option is then omitted from the command.

In addition to the certificate, a PFX or P12 file usually also contains the private key and the intermediate certificates. After the conversion as described in Convert certificate to PEM →, server.pem and server.key are already available. Steps 2 and 3 and the combining in step 4 are skipped; the procedure continues with the chain check at the end of step 4. If intermediate certificates are missing there, they are obtained as described in step 3 and appended to server.pem. The key is then checked as described in step 5.

Lines such as subject=…, issuer=… or Bag Attributes before the certificates result from the conversion with OpenSSL. They usually do no harm and can remain in the file.

2. Check the structure of the server certificate #

After the conversion of a single certificate file (DER or PEM), the server-cert.pem file contains exactly one certificate – the server certificate:

-----BEGIN CERTIFICATE-----
MIIGfjCCBWagAwIBAgIQD7S2kpX0nBq3Wc...
(server certificate, several lines of Base64-encoded text)
...7TQxLm1Bxq2fJZ0wS9YQ==
-----END CERTIFICATE-----

The following command shows for which server name the certificate was issued, by whom and how long it is valid:

openssl x509 -in server-cert.pem -noout -subject -issuer -enddate
openssl x509 -in server-cert.pem -noout -text | grep -A1 "Subject Alternative Name"

The host name of the Relution server’s External URL must be listed as a DNS: entry under X509v3 Subject Alternative Name. The issuer line names the certificate authority whose intermediate certificate is required in the next step.

3. Obtain the intermediate certificates from the certificate authority #

The server certificate is not signed directly by the root certificate of the certificate authority, but by one or more intermediate certificates. For devices and clients to trust the server certificate, the reverse proxy must deliver these intermediate certificates as well.

The intermediate certificates can be obtained in the following ways:

• Delivery from the certificate authority: They are often already included with the certificate delivery, for example as intermediate.crt, ca-bundle.crt or chain.pem.

• Website of the certificate authority: Certificate authorities provide their intermediate certificates for download. The relevant intermediate certificate is the one whose name matches the issuer line from step 2.

• Reference in the certificate: Most server certificates contain a download address for the issuing intermediate certificate (CA Issuers):

  openssl x509 -in server-cert.pem -noout -text | grep "CA Issuers"
  

  The file downloaded this way is often in DER format and is converted to PEM as described in step 1.

The root certificate of the certificate authority is not required; it is already present on the devices.

4. Combine the server certificate and the intermediate certificates #

The server certificate and the intermediate certificates are combined into a single server.pem file. The order is crucial: first the server certificate, then the intermediate certificates. If there are several intermediate certificates, the one that issued the server certificate comes first, followed by the next higher one.

cat server-cert.pem intermediate.pem > server.pem

The finished file is structured as follows:

-----BEGIN CERTIFICATE-----
MIIGfjCCBWagAwIBAgIQD7S2kpX0nBq3Wc...
(server certificate)
...7TQxLm1Bxq2fJZ0wS9YQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEyDCCA7CgAwIBAgIQDPW9BitWAvR6uF...
(intermediate certificate)
...kXmcO7hOt9fyQXaU2Xg2Ug==
-----END CERTIFICATE-----

Each -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker is on a line of its own. If a source file does not end with a line break, -----END CERTIFICATE----------BEGIN CERTIFICATE----- ends up on a single line when the files are combined, and the reverse proxy cannot load the certificate. In this case, a line break is inserted at that position in a text editor.

Whether the chain is complete can be checked with the following command. It lists all certificates in the file in order, with owner (subject) and issuer (issuer):

openssl crl2pkcs7 -nocrl -certfile server.pem | openssl pkcs7 -print_certs -noout

The issuer of each certificate corresponds to the subject of the next one. The issuer of the last certificate is the root certificate of the certificate authority. If the root certificate itself is contained in the file (recognisable by identical subject and issuer), it is not required and can be removed in a text editor together with its block from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.

5. Check the private key #

In addition to server.pem, the private key that was generated when the certificate signing request (CSR) was created is required. If the new certificate was issued with the same CSR as the previous one, the existing server.key remains unchanged.

The private key must be in PEM format and without a password, as the reverse proxy cannot prompt for a password at startup. The first line then reads -----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY----- or -----BEGIN EC PRIVATE KEY-----. If it reads -----BEGIN ENCRYPTED PRIVATE KEY----- or the first line is followed by a line Proc-Type: 4,ENCRYPTED, the key is protected with a password. The password is then removed (it is prompted for during this step):

openssl pkey -in key.pem -out server.key

Whether the certificate and the key belong together is shown by comparing the two checksums; they must be identical:

openssl x509 -in server.pem -noout -pubkey | openssl sha256
openssl pkey -in server.key -pubout | openssl sha256

6. Put the certificate in place in the reverse proxy #

With server.pem and server.key, the certificate is put in place in the reverse proxy of the installation. Before the replacement, the existing server.pem and server.key files are backed up so that they can be restored if problems occur. Each guide describes placing the files, the restart and the final check:

• Docker with Traefik: Traefik: Renew certificate →
• Docker with nginx: nginx: Renew certificate →
• Native installation on Windows or Linux: Native installation: Renew certificate →