Most secure protocols, like TLS and OPC UA use certificates to verify the identity of network servers. This is necessary to ensure that an attacker cannot spoof a server address and impersonate a service the client trusts, possibly tricking it into giving up sensitive information. A certificate can also be used to verify the identity of a network client, to ensure that an attacker cannot impersonate a trusted client, like a WebSocket-based UI client.

Certificates are also used for certificate-based authentication.

A certificate can either be self-signed, or it can be issued by a trusted certificate authority (CA). You can also use your own enterprise CA to issue certificates.

Self-signed certificates are certificates that you create yourself without any certificate authority. Instructions on how to create a self-signed certificate can be found below.

In order for a certificate to be used, it must be trusted. How the certificate is trusted, depends on what type of certificate it is:

Certificates issued by well known certificate authorities (CAs) are trusted automatically by consulting the operating system’s list of trusted certificates. The same goes for certificates issued by enterprise CAs that are themselves issued by a trusted root CA.
For certificates issued by enterprise CAs that do not have a trusted root CA, the root CA’s certificate must be known to Xentara. This means copying the certificate to the host running Xentara, and entering the certificate’s path in the relevant configuration file, for example the Xentara client certificate configuration file.
For self-signed certificates, the certificate must be known to Xentara. This means either copying the certificate to the host running Xentara and entering the certificate’s path in the relevant configuration file, or by simply entering the certificate’s fingerprint in the configuration file.

Certificate Private Keys

Each certificate is accompanied by a private key. The private key of a certificate must be kept secret, and never given out to anyone. If the private key is leaked to an attacker, that attacker can impersonate the legitimate certificate holder, and the certificate is no longer of any use.

Creating a Self-Signed Certificate

You can generate a self-signed certificate using OpenSSL. OpenSSL is generally pre-installed on most Linux installations, but must be installed manually on Windows. There are no official Windows builds of OpenSSL, but the official OpenSSL wiki lists several available distributions on their Binaries wiki page. Please note that the distributions listed on that page are not endorsed either by the OpenSSL project, or by embedded ocean GmbH.

To generate a self-signed certificate, use the following OpenSSL command:

openssl req -nodes -x509 -newkey rsa:4096 -keyout my-certificate.key.pem -out my-certificate.pem -sha256 -days 36500

This will generate a certificate file named my-certificate.pem and a private key file named my-certificate.key.pem in the current directory. The private key file will automatically have the correct access permissions describen in Certificate Private Keys.

The option -days 36500 makes the certificate valid for 36500 days, or approximately 100 years. If you use a shorter expiry time (365 days is a common choice), please remember that the certificate must then be replaced at regular intervals on both the server and the client.

Certificate And Private Key File Structure

Certificate and private key files are PEM format files. PEM stands for “Privacy Enhanced Mail” and is a common standard for storing and exchanging keys, certificates, and other cryprography-related data. PEM files are text files.

Certificate files contain either a single certificate, or a certificate chain consisting of the certificate itself, followed by all the relevant CA certificates, ending in the root certificate.

For a self-signed certificate, the certificate file only contains the certificate itself. For certificates issued by a certificate authority, the certificate file must include the entire certificate chain. The certificate chain must start with the target certificate, followed by the certificate of the issuing certificate authority. If the autority’s certificate was issued by a parent authority, the parent authority’s certificate must be next in the chain, and so on. The last certificate in the certificate chain is called the root certificate, and it must be known and trusted by the client. Since the root certificate must already be known by the client, it can be omitted from the certificate file.

A PEM encoded certificate file containing a single, self-signed certificate looks like this:

A PEM encoded certificate file containing a certificate chain with three certificates looks like this:

Private keys are also stored in PEM files. A PEM encoded private key file looks like this:

The private key file should generally not be readable by anyone but the owner. Under Linux, this can be acheived by setting the file permissions to the value “0600”:

chmod 0600 my-certificate.key.pem

Under Windows, private key files should be placed into a directory that is only readable by the user. This is generally the case for the user’s Home directory, so placing the private key file somewhere in the user’s Home directory is normally enough.

Warning: Do not share the private key file with anyone. This file contains the private signing key, and anyone who knows that key can impersonate the legitimate owner of the certificate. To install the certificate as a trusted certificate on a client, copy only the certificate file to the client, and do not copy the private key.

It is possible to place the certificate and private key into the same file, but that is not recommended, as the certificate file contains public information, where the private key file contains secret, private information.

Certificate File Location

Some configuration files allow you to specify the location of a certificate file and a corresponding private key file. The Xentara security configuration file, for example, allows you to specify custom paths for the TLS server certificate and private key.

Certificate and private key files are considered configuration files, and are searched for in the same manner as other external configuration files. There are some special considerations regarding the relationship betwen the certificates and private key paths, however, as described in the following chapters.

Specifying Absolute Paths

Like other external configuration files, the paths of the certificate and private key files can be specified using absolute paths. If absolute paths are specified, the files are loaded from exactly those paths, and the configuration directories are not searched.

If either the certificate file path or the private key path is absolute, the other path must be absolute as well. You cannot specify an absolute certificate path and a relative private key path, or vice versa.

Specifying Relative Paths

Like other external configuration files, the paths of the certificate and private key files can be specified using relative paths. If relative paths are specified, the path is appended to each of the corresponding search directories in turn, until the file is found. If one of the files is not found, an error is emitted.

Certificate files are searched using certs as configuration subdirectory. By default, the following directories are searched for certificate files, in order:

Linux:

${HOME}/.config/xentara/certs
/etc/xdg/xentara/certs

Windows:

%LOCALAPPDATA%\Xentara\Config\certs
%ProgramData%\Xentara\Config\certs

Private key files are searched using private as configuration subdirectory. By default, the following directories are searched for private key files, in order:

Linux:

${HOME}/.config/xentara/private
/etc/xdg/xentara/private

Windows:

%LOCALAPPDATA%\Xentara\Config\private
%ProgramData%\Xentara\Config\private

The private key file must be located under the same base directory as the certificate file. If the certificate is located under ${HOME}/.config, then the private key must also be located under ${HOME}/.config, for example. You cannot place the certificate file in ${HOME}/.config and the private key file in /etc/xdg, or vice versa. The same goes for %LOCALAPPDATA% and %ProgramData% under Windows.

If either the certificate file path or the private key path is relative, the other path must be relative as well. You cannot specify a relative certificate path and an absolute private key path, or vice versa.

Note: The search path can be modified using the command line option --config-dir (Linux) or -ConfigDir (Windows), or the environment variables XDG_CONFIG_HOME and XDG_CONFIG_DIRS (Linux only), as described in Standard Configuration Directories.

Table of Contents

Certificate Private Keys

Creating a Self-Signed Certificate

Certificate And Private Key File Structure

Certificate File Location

Specifying Absolute Paths

Specifying Relative Paths