Getting Started with X.509 Certificates

If you are not familiar with managing X.509 certificates required for Transport Layer Security (TLS), you can find some basic information on this page. It serves as a quick guide to introduce the basic workflow and the required steps to create self-signed certificates for TLS.

X.509 certificates are digital documents that are used to verify and confirm the identity of servers or websites. They are mandatory to enable a secure network communication between servers, or between servers and websites via Transport Layer Security (TLS).

The certificates are required if you want to use MERLIC on remote systems with a secure connection. They ensure an encrypted connection between the MERLIC services, for example, between MERLIC Frontend and MERLIC RTE.

To enable secure communication with Transport Layer Security (TLS) between MERLIC services, you have to provide a server certificate on all host machines and the corresponding CA certificate for all clients accessing the server.

CA Certificates and Server Certificates

CA certificates are certificates that are usually issued by a trusted Certificate Authority, for example, Let's Encrypt. They are used to sign other certificates such as server certificates. The CA certificate itself contains information on the respective Certificate Authority. CA certificates of globally recognized CAs are provided by default with the operating system. Your company might provide a company specific CA certificate, which serves as root CA certificate and is distributed by your IT department on all machines in your local network.

Server certificates identify a specific host machine. They can be requested via a certificate signing request (CSR) and are issued and signed by a CA using their private CA key. Server certificates need to be provided together with a private server key on the host machine.

Certificates for MERLIC

If you want to set up MERLIC for remote usage with Transport Layer Security (TLS), you have to provide a server certificate on the host machine running MERLIC services such as MERLIC RTE or MERLIC Creator. On all client machines, which should be able to access the host machine, you have to provide the CA certificate that was used to sign the server certificate. This means, you have to provide the CA certificate on client machines running MERLIC Frontend or MERLIC RTE Setup that should connect to MERLIC RTE or MERLIC Creator running on the host machine.

The Certificate Authority (CA) should be chosen depending on the intended client users.

Local Testing or Selected Clients

If you control all the machines running the clients that will need to be able to connect to the MERLIC service, you can create your own CA certificate and add it to the trusted certificates on those client machines. In this case, you assume the role of the CA. This is handy for testing since you can do it all on your own.

Local Company Network

If the MERLIC service should be running on machines in your local company network, you can use the root CA certificate of your company to sign the server certificate. You can submit a certificate signing request (CSR) to your IT department and ask them to sign it with the root CA certificate. If your company uses an automated process for issuing certificates, such as ACME (Automatic Certificate Management Environment), you can use the respective process to request the server certificate. This certificate should be trusted by all machines rolled out by your IT. The MERLIC service will then be accessible for all in-house users.

External Network

If the MERLIC service should be exposed to any sort of wider network, clients cannot be assumed to trust any CA other than the globally recognized CAs. Therefore, it is recommended to request a server certificate from a globally recognized CA. The server certificate will then be signed and issued by the chosen CA. The respective CA certificates are already provided by default, so you do not have to add them yourself.

It is recommended to use a reverse proxy when deploying MERLIC to a wider network. The MERLIC Directory Agent and the reverse proxy communicate in plain HTTP over a local TCP connection or a Unix domain socket. The server certificate then needs to be configured in the reverse proxy, which exposes the MERLIC service to the network.

Basic Workflow for Creating Certificates

The certificates and the corresponding private keys can be generated via the command line using the OpenSSL command line utility. Basically, you need to make sure that the server certificate, the private server key, and the corresponding CA certificate are provided on the respective systems.

The following instructions contain all information required to create the certificates yourself, for example, for testing.

All OpenSSL commands shown on this page require OpenSSL 3 or higher.

The OpenSSL CLI is available on Windows but you will likely need administrator privileges to install it. Alternatively, you can create the certificate and key on a Linux system and use them on Windows.

Providing a CA Certificate

If you want to use server certificates signed by a trusted CA, these steps will not be necessary because the respective CA certificate will most likely already be provided on the client machines.

Create a private CA key and a CA certificate.
Add the CA certificate to the clients.

Providing the Server Certificate

If you want to use server certificates signed by a trusted CA, the CSR will be sent to the CA, which signs and issues the server certificate.

Create a private server key and a certificate signing request (CSR) for a server certificate.
Sign the CSR with the CA key to issue the server certificate.
Add the server key and server certificate to the host machine.

Enabling Transport Layer Security (TLS) for MERLIC

In the configuration file of the MERLIC Directory Agent, enable the network access and specify the location of the server certificate and the private server key. For more information, see Configuring the Directory Agent for Remote Connections.

Providing a CA Certificate

Creating a CA Certificate and Private CA Key

To create a CA certificate yourself, you can use the OpenSSL command line utility. In this case, you assume the role of the Certificate Authority (CA) and use OpenSSL to create a private CA key and a CA certificate that is signed with your CA key.

The following example shows how to create a CA certificate and private key file. The commands work in OpenSSL 3 or later.

Open a command prompt and enter the following command:
Copy
```
openssl req -new -x509 -nodes -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt
```
This command creates a CA certificate "ca.crt" and a new associated private key file named "ca.key". It uses the RSA algorithm with a key length of 2048 bits. The certificate will be valid for 365 days. You may also use different file names to make its purpose and origin more obvious.
When prompted, enter some information identifying the CA. This metadata will be user-facing at the end. For example, Mozilla Firefox shows a tooltip "Verified by" followed by name of the CA. This information is obtained from the metadata of the CA certificate.

While the CA certificate must be distributed to the clients, the private CA key should be kept protected. You should never give it to anyone. It holds the key to signing certificates in the name of the CA.

You only need to create and distribute the CA certificate once for as long as it is valid. You can sign an arbitrary number of server certificates for different hostnames, domains, etc., with this same CA certificate, as long as you hold on to the private CA key.

Adding the CA Certificate to the Clients

The CA certificate needs to be added to each client machine, which should be able to access the server. This typically means importing the CA certificate into the certificate store of the operating system or the browsers.

Be aware that this does not prevent other clients from accessing the server. Clients can always choose to skip certificate verification. Server certificates only allow the client to authenticate the server.

Windows

On Windows, you can import the file via PowerShell:

Copy

Import-Certificate -FilePath "C:\path\to\ca.crt" -CertStoreLocation Cert:\CurrentUser\Root

It is also possible to double-click the CA certificate file to install the certificate via the graphical user interface, the so-called "Certificate Import Wizard" of Windows. If you are using this option, make sure that the certificate will be installed to the list of trusted root certification authorities. You can check this in the Certificate Manager of Windows.

Linux

On Linux, you have to copy the CA certificate file to the respective system certificate store. You may want to rename the file to make its origin and purpose more obvious.

For example, on Ubuntu, copy the CA certificate file to "/usr/local/share/ca-certificates" and then update the system trust store by running the following command:

Copy

sudo update-ca-certificates

Browsers

In some cases, it might also be necessary to import the CA certificate in the browser. Browsers typically come with their own certificate store. You can import your CA certificate from the browser's settings to the trusted certificates:

Mozilla Firefox: Settings > Privacy and Security > Connection and Software Security > Certificates > Manage Certificates > Authorities > Import
Google Chrome™: Settings > Privacy and Security > Security > Manage certificates > Custom/Installed by you > Trusted Certificates > Import
Microsoft Edge: Settings > Privacy, search, and services > Security > Manage certificates > Custom/Installed by you > Trusted Certificates > Import

If you cannot find the import option mentioned above, you can search for the certificate store within the browser settings.

Custom Certificate Directory or File

If the system certificate store on the client cannot be used, you can use the environment variables SSL_CERT_DIR or SSL_CERT_FILE as an alternative method to add the CA certificate to your clients.

Environment variable	Description
SSL_CERT_DIR	This variable can be used to specify a different default directory for CA certificates. You can specify multiple directories, separated by a colon (Linux) or semicolon (Windows). After moving the CA certificate into one of the specified directories, you have to hash its content using the following OpenSSL command: Copy `openssl rehash <PATH_TO_DIRECTORY>` This command must be executed every time the certificate in the directory has changed. It creates a symlink pointing to the certificate, allowing OpenSSL to find the CA certificate quickly when verifying a server certificate.
SSL_CERT_FILE	This variable can be used to define a specific CA certificate file that should be used to verify the server certificate.

Environment variable

Description

SSL_CERT_DIR

This variable can be used to specify a different default directory for CA certificates. You can specify multiple directories, separated by a colon (Linux) or semicolon (Windows).

After moving the CA certificate into one of the specified directories, you have to hash its content using the following OpenSSL command:

Copy

openssl rehash <PATH_TO_DIRECTORY>

This command must be executed every time the certificate in the directory has changed. It creates a symlink pointing to the certificate, allowing OpenSSL to find the CA certificate quickly when verifying a server certificate.

SSL_CERT_FILE

This variable can be used to define a specific CA certificate file that should be used to verify the server certificate.

Creating a Server Certificate

Creating a Certificate Signing Request (CSR) and Private Server Key

To create a server certificate, you first have to create a certificate signing request (CSR) and a private server key for the server certificate. The CSR will then be verified and signed by the chosen Certificate Authority (CA). The CSR is usually created by the server operator.

The following example shows how to create a CSR and the corresponding private server key. The commands work in OpenSSL 3 or later.

Copy

openssl req -new -subj "/C=DE/CN=merlic-server" -addext "subjectAltName = IP:127.0.0.1, DNS:localhost, DNS:merlic-server" -newkey rsa:2048 -nodes -keyout server.key -out server.csr

This command creates a private server key file "server.key" and a certificate signing request (CSR) "server.csr". The CSR file is only an intermediate file. Once the CSR is signed by the CA, the file is not needed anymore.

Make sure to adjust the command line arguments accordingly to fit the intended server. You can also omit the subject option "‑subj" to be prompted interactively for additional certificate metadata.

C: Defines the country code. In our example, it is set to Germany ("C=DE").
CN: Defines the hostname of the intended server. In our example, we use the hostname "merlic-server".
subjectAltName: Defines one or multiple "Subject Alternative Names" (SANs), for which the certificate should be valid. These can be IP addresses ("IP:") or domain names ("DNS:"). It is required to specify at least one SAN for which the certificate should be valid. One of the SANs must match the hostname or domain name used to access the server. For local testing, 127.0.0.1 and "localhost" are useful to include.

The private server key should be kept protected. You should never give it to anyone. This includes the CA because they only require the CSR.

Signing the CSR with the CA Key

The final server certificate is created by signing the CSR with the CA key. If you assume the role of the CA, you can sign the CSR yourself with your private CA key.

The following example shows how to sign a CSR with your CA key. The commands work in OpenSSL 3 or later.

Copy

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 90 -sha256 -copy_extensions copyall

This command uses the CSR file "server.csr" and the private CA key "ca.key" as input and creates the server certificate "server.crt". The server certificate is valid for 90 days. The option "‑copy_extensions copyall" ensures that the SANs are carried over from the CSR.

If you want a server certificate signed by a trusted CA, you have to send them the CSR file. The CA will verify the CSR, confirm your identity, and send you the signed server certificate.

The resulting server certificate "server.crt" can then be used in conjunction with the private key "server.key" to operate the server.

Adding the Server Certificate and Private Server Key to the Host Machines

The server certificate and the corresponding private server key must be provided on the host machine for which the certificate was created. The path to both files must be specified in the configuration file of the MERLIC Directory Agent when setting up MERLIC for remote connections via Transport Layer Security (TLS). For more information, see Configuring the Directory Agent for Remote Connections.