TLS Configuration

The communication between the Automation Engine, the Automic Web Interface, and the Java API, as well as between the Automation Engine and the Agents uses TLS through a secure WebSocket (WSS). These components establish a connection with the Java communication process (JCP) and/or the REST process (REST).

This page includes the following:

Overview

The JCP and REST processes use trusted certificates to prove their identity to other communication partners, such as Agents. To work with these certificates, the processes require a keystore, which must be created beforehand using pkcs12 format.

It is recommended to use properly signed certificates instead of self-signed certificates to ease the installation of agents or other components. Also, you must attach the whole chain of trust (intermediate and root certificate authority) to the certificate. You can use openssl to create such pkcs12 file. The files for the intermediate and root certificate authority are supplied by the owner of the certificate authority.

openssl pkcs12 -in certificate.p12 -out cert.pem -nodes -clcerts
openssl x509 -in intermediate_ca.cer -inform DER -out intermediate_ca.pem
openssl x509 -in root_ca.cer -inform DER -out root_ca.pem
cat cert.pem intermediate_ca.pem root_ca.pem >> certchain.pem
openssl pkcs12 -export -in certchain.pem -out certchain.p12

You then must define the relevant parameters relevant in the configuration (INI) file of each component.

The Java default cipher suite of the JCP is used to configure the TLS connection. You can change the supported cipher suites in the Java security policy. For more information, see https://www.java.com/en/configure_crypto.html.

Parameters - Automation Engine

Define the parameters listed below in the [TLS] section of the configuration (UCSRV.INI) file of the Automation Engine. For more information, see Automation Engine INI file.

  • keystore= Path and file where the keystore for the TLS certificate is stored

    Default value: ./httpsKeyfile

    This parameter is mandatory and must point to the correct target; otherwise, the process server will terminate.

  • keystorePassword= Password for the keystore file

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

  • keyPassword=Password for the key

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

  • keyAlias= Alias used for the key

    Default value: jetty

    If the value is not defined or is left empty, the system uses the default value.

Note: The keystorePassword and the keyPassword can be encrypted with the UCYBCRYP Utility. For more information, see Encoding Passwords.

Parameters - Agents and Java Components

All Java components as well as the Windows, UNIX and Java Agents can use different parameters in their corresponding INI file to define how to handle the certificates. This applies to the following components and Agents:

Components

Agents

All components and Agents listed above can use the trustedCertFolder= parameter in their respective configuration file to define the path to the folder where the trusted certificates are stored.

If this parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the SSL store for UNIX Agents.

Furthermore, the Agents can use the following parameters in the [AUTHORIZATION] section of the respective INI file:

  • agentSecurityFolder= Path to the folder where the agent stores security related files such as private keys, signed certificates, root certificates

  • keyPassword= Password for the key

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

    Note: The keyPassword can be encrypted with the UCYBCRYP Utility. For more information, see Encoding Passwords.

UNIX agents additionally require you to define the SSLCertDir= and SSLCertFile= parameters in the [AUTHORIZATION] section of the INI file to load the certificates from the SSL store.

  • SSLCerDir= location of the trusted CA certificates with each certificate in a separate file, for example,/etc/ssl/certs/

  • SSLCertFile= location of the .pem file with all the trusted CA certificates, for example, /etc/pki/tls/certs/ca-bundle.crt

More information:

Adding the Certificates

The JCP and REST processes use keystore as defined in the Automation Engine configuration file.

Important! We recommend using signed certificates of a trusted certificate authority only because self-signed certificates would require to be added to the trust store on every agent host. You may request a signed certificate from your IT department. The connection's encryption is the same as with a self-signed certificate. The common name that is used in the certificate must match the cp address that is used in the agent configuration.

All connecting components (Agents, AWI, etc.) must verify the identity of the JCP. This is done during the connection handshake in the TLS protocol. If the certificate does not fulfill the security requirements, the component cannot connect to the Automation Engine. A valid certificate must fulfill the following properties:

  • The common name of the certificate must match the configured endpoint address. If a different address is used, even if they are for the same machine, the certificate will be rejected by the client

  • The certificate is not expired, except if it is trusted directly in the trust store

  • The certificate is either trusted directly by the client or is signed by a trusted certificate authority. It is recommended to use a certificate that is signed by the company’s certificate authority, as those are probably trusted on the machine already. You have to ensure that the signing certificate authority or the certificate itself is part of the trust store. Depending on the component, this can be a java trust store or a folder in the agent directory.

For additional information as well as information on adding certificates, see https://www.eclipse.org/jetty/documentation/current/configuring-ssl.html.

See also: