Skip to content

Certificates

This document describes how the server manages PKI material such as certificates and private keys and the related configuration options like Server private key password and PKI storage path.

CertificatesOptions

PKI storage path

The server stores the PKI material like its certificate and private key and the trusted client certificates in a particular folder structure.

The PKI storage path option sets the the root of this structure. In order to avoid conflicts, the PKI material will not be stored directly in the specified location, but each server instance will create a subfolder in PKI storage path named after its pid.

For example, assume that you install two different components called Server1 and Server2 and leave the default value /var/lib/com.eurotech.framework.opcua.server/ as the PKI path for both. Automatically, the server certificate folder will be set as /var/lib/com.eurotech.framework.opcua.server/Server1/ and /var/lib/com.eurotech.framework.opcua.server/Server2/, respectively.

Folder structure

The certificates folder is composed by different subfolders, each one representing the possible validation result, the user token of the client or the validator used:

var
└─ lib
   └─ com.eurotech.framework.opcua.server
      └─ customPidName
         ├─ crl
         ├─ issuers
         │  ├─ crl
         │  ├─ rejected
         │  └─ trusted
         ├─ private
         ├─ rejected
         ├─ trusted
         └─ users
            ├─ crl
            ├─ issuers
            │  ├─ crl
            │  ├─ rejected
            │  └─ trusted
            ├─ rejected
            └─ trusted

The first three folders follow the PKI storage path option, and the customPidName represents the applicationPid pasted after the option. Then some folders are automatically added:

  • private: stores the server own certificate and private key files (see the Server Certificate and Private Key section)
  • crl: stores .crl Certificate Revocation List, that contains the list of certificates issued by a Certification Authority that are no longer trusted
  • rejected: stores the received certificates rejected by the server
  • trusted: stores the received certificates trusted by the server
  • users: stores the certificates of clients that try to connect with Certificate token; the next folders have the same aim of the ones described before
  • issuers: stores certificates of Certification Authorities; the next folders have the same aim of the ones described before

In the folder tree it is possible to notice, that the crl, rejected and trusted folder are present in both the customPidName and users directories: the difference is that in the first ones are stored the certificates of clients connected with the User and Password token, while the second ones those that accessed with Certificate token.

The folder structure is useful to better understand the process of certificate trusting explained in the usage section of this documentation.

Server Private Key

When a server is instantiated it will attempt to load its certificate and private key from the following files in the private directory, where Server Application Name is the value of the corresponding configuration parameter:

  • <Server Application Name>_2048.der: The server certificate encoded in DER format
  • <Server Application Name>_2048.pem: A 2048-bit RSA private key associated with the server certificate, encoded in encrypted PEM format. The PEM encryption passphrase is the value of the Server private key password configuration parameter.

The server will autogenerate a new certificate and private key if the files do not exist.

It is highly reccomended to modify the Server private key password parameter, and set a strong password, to ensure the highest security level.

An user can also use its own custom ceritifcate and private key, replacing the autogenerated ones. The only constraints to follow are:

  • use a 2048-bit RSA private key
  • apply the same nomenclature of the autogenerated files: they must be called with a name composed by the Server Application Name driver option followed by the _2048.EXTENSION words

So, for example, if the application name is "MyOwnServer", the files must be called MyOwnServer_2048.pem and MyOwnServer_2048.der.