Starting a UTM application with TLS connections

In addition to the encryption functionality, the user must also provide an openSSL library for TLS connections.

If BCAMAPPLs with T-PROT=(SOCKET,...,SECURE) are generated for a UTM application, a number of network processes of type utmnetssl are started when the application is started.

In each utmnetssl process, communication takes place via the Transport Layer Security (TLS).

When an utmnetssl process is started, the TLS environment is initialized. In addition to loading the openSSL library, the certificates and private keys required for communication are also loaded.

The following user actions are required for a successful start of a utmnetssl process:

1. Providing a suitable openSSL library
2. Setting the environment variable UTM_SSL_LIBRARY
   For details, see chapter Environment variables for using openSSL.
3. Create a UTM TLS configuration file under the <filebase> directory.

Error behaviour

If the initialization of the TLS environment is not successful, the utmnetssl process is terminated and afterwards the UTM application is also terminated abnormally.

Version of openSSL library

Details about the version of the openSSL library can be found in the release note for openUTM.

UTM TLS configuration file

In the UTM TLS configuration file, you specify options for TLS communication.

These are the file names for the file with the SSL server certificate and the file with the private SSL server key.

The content of the UTM TLS configuration file is evaluated at the start of each utmnetssl process and the certificates/keys specified there are loaded and checked.

In case of an error, the utmnetssl process is terminated.

File name

The name for the UTM TLS configuration file is fixed:

utm.ssl.conf

File format

The file is line-oriented. The first line contains a header, followed by the options. Empty lines and comment lines are also allowed.

The header - first line - has the following format:

#@(#) openUTM SSL Config File

Comment lines starts with # or *.

The specification for the certificate and the key is made in the following form

RSACertificateFile=<filename>

resp.

RSAKeyFile=<filename>

RSACertificateFile

The RSACertificateFile parameter specifies a file that contains the RSA-based X.509 server certificate in PEM format.

This file can also contain the private RSA server key. As a rule, however, the certificate and key are stored in separate files. In this case, the key file is specified using the RSAKeyFile parameter.

RSAKeyFile

The RSAKeyFile parameter specifies a file that contains the private RSA server key in PEM format.

The following maximum values and rules apply to the UTM TLS configuration file:

• The first line must be the header
• Maximum line length: 300 characters
• Blank lines and comment lines are ignored.

Example UTM TLS configuration file

A sample file for a UTM TLS configuration file is delivered under the utmpath/ssl directory.