What is it

Certificate Authorities (usually abbreviated "CA") sign TLS/SSL certificates which prove the identity of a server you are contacting. If a HTTPS Client fails to check a certificate presented by a server an error occurs and the connection is denied. 

Project Server uses one CA certificate bundle for all TLS/SSL connections irrespective whether they originate from the Project Server platform, a container or even a container-in-a-container (Docker-in-Docker / DinD). This bundle by default contains four CA certificate sources:

• standard a set of public CA certificates (maintained by Mozilla and provided by the CurL Project), 
• zscaler Zscaler CA certificates relevant for the msg networks
• msgcloud the CA certificate for the msg.Cloud CA
• the certificate of the local CA created during installation of your PS4 host. It issues certificates which are used between the PS4 docker containers so that the PS4 stacks can seamlessly communicate through HTTPS. (While HTTP would be almost as secure because this traffic runs on internal networks and never leaves the PS4 host, some stacks refuse to communicate over HTTP so that a properly working HTTPS infrastructure is mandatory.)

All CA certificates coming from these sources make up a CA certificate bundle. It is made available to the stacks in two ways: 

• the standard Unix/OpenSSL way: a cacert bundle file and a certificate hierarchy in /etc/ssl/certs 
• the Java way: a JKS-keystore (/etc/ssl/java/cacert).

It can happen that you need additional CA certificates, e.g. because your PS4 owns a certificate which was signed by a CA which is not contained in this CA certificate bundle. This HowTo explains how you provide these CA-certificates to your PS4 stacks (and we are really talking about CA certificates here and not regular server certificates which are issued by these CAs).

Prerequisites

The CA certificate(s) either

• as a PEM-encoded certificate in a local file
• as a PEM-encoded certificate downloadable from a URL

If there is a certificate chain between your server certificate and the CA certificate (i.e. there are "intermediate certificates" inbetween) you only need to install the top level certificate.

How to achieve it

PS4 comes with the cau(1) utility which stores certificates in a database and generates the necessary certifcate stores from it. The cau commands are integrated into the docker-stack command as docker-stack configure ca. (Have look at its manual page for details.)

Step 1: Add the certificate to the central certificate store: docker-stack configure ca source <id> <url>

• <id> is an arbitrary name for the CA to identify it later, e.g. to remove it.
• <url> is the location of the certificate:
  • If your CA certificate is in a PEM-encoded file use a file <url>: file:///absolute/path/to/certificate/file.
    Please note:
    • This file should be kept at this location as everytime you issue the following command the ca-utility will visit this path in order to read the CA certificate file.
    • If you use an absolute path there are three slashes after the file:  designator.
  • If the CA certificate is downloadable use a web URL. This is for example where to download the "Let's Encrypt" CA certificate from: https://letsencrypt.org/certs/isrgrootx1.pem.txt

If a certificate is already in the store for the provided <id> it will be replaced.

Step 2: Let cau generate the Unix/OpenSSL and Java keystores: docker-stack configure ca update. After this commands the CA certificates are immediately available in all containers. Note that the Jaca Runtime Environment caches certificates so to make a new certificate available you might need to restart your Java application.

Good to know

CA certificates are most commonly encoded in PEM-format (see RFC 7468; there exist other encodings as well). They usually use filename extensions .crt, .cer or .pem. To check whether this is in fact a certificate and to make its contents human readable use the command openssl x509 -in <filename> -text. In the output the Subject line provides the certificate authority to which the certificate belongs to.

cau(1) has more features, see its manual page.

To list the id's of all sources in the certificate store execute docker-stack configure ca source.

Containers use the CA certificates through a volume mount.