Configuration of the MTG KMS PKCS#11 Library

The MTG KMS PKCS#11 Library is controlled via a configuration file. During the initial installation the system-wide configuration file kms_pkcs11.conf is initialized with default values and placeholders. Before using the MTG KMS PKCS#11 Library, all values have to be checked and if required, changed to appropriate values.

Parameters in configuration files are always case-sensitive.

Linux distributions

The configuration file kms_pkcs11.conf is located under the directory: /etc/opt/mtg-kms-pkcs11-lib/kms_pkcs11.conf

After an update installation, the package management may place a newer version of the configuration files beside your existing. Always compare the default configuration file kms_pkcs11.conf with the new version. In case an update requires additional/changed parameters, those have to be added manually to the existing configuration files. Please also check the package release notes for such additional/changed parameters.

Windows distributions

The configuration file kms_pkcs11.conf.template is located in the directory that was specified as the installation directory during installation. The configuration file kms_pkcs11.conf.template must be renamed to kms_pkcs11.conf after the initial installation and adapted accordingly.

After an update installation, the setup program will overwrite the configuration file kms_pkcs11.conf.template. Always compare the standard configuration file kms_pkcs11.conf with the new version. If an update requires additional/changed parameters, these must be added manually to the existing configuration files. Please also check the release notes of the setup program for such additional/changed parameters.

The Configuration File Location

On the first call to any PKCS#11 function the configuration file is sought for by the MTG KMS PKCS#11 Library in the following sequence:

  • If the environment variable MTG_KMS_PKCS11_LIB__CONFIG_FILE_PATH is set and contains a non-empty string, this is taken as the full path to the configuration file for the MTG KMS PKCS#11 Library. Failure to find the configuration file at this path results in an error. In this case the configuration file is not further sought for.

  • Otherwise, if the environment variable is not specified or contains an empty string, the configuration file is sought for at the following file paths:

Linux distribution

  • First at the path relative to user’s home directory $HOME/.config/mtg/mtg-kms-pkcs11-lib/kms_pkcs11.conf.

  • If it is not found at the above location, it is sought for at /etc/opt/mtg-kms-pkcs11-lib/kms_pkcs11.conf.

Windows distribution

  • First at the path %LOCALAPPDATA%\Programs\mtg\mtg-kms-pkcs11-lib\kms_pkcs11.conf.

  • If it is not found at the above location, it is sought for at %PROGRAMFILES%\mtg\mtg-kms-pkcs11-lib\kms_pkcs11.conf.

Before the configuration file is found, the library will produce log output to the console.

The Configuration File Content

The configuration file is structured into sections. Any property can specified either as

<section-name>.<property-name>=<property-name>

or by placing the property under a section specifier in the following format:

[<section-name>]
<property-name>=<property-value>

A property name may include the string $CWD as part of a file path to refer to the current working directory in which the application is executed. A valid file path specification would be for instance

logging.log_file_path=$CWD/pkcs11_log_file

security Properties

Property name Possible values Default value Description

security.allow_debug- _build

"true", "false"

N/A

Whether to allow the usage of a debug build version of the MTG KMS PKCS#11 Library with this configuration. The debug build of the library allows for more detailed logging and accordingly may introduce security risks. This option in the property file ensures that a concious decision is taken to use the debug build version. Defaults to "false".

logging Properties

Property name Possible values Default value Description

logging.log_file_path

path to a writable file

Absolute path to the log file. The path must point to file base name. The library will append date and time to this file path each time the library is initialized. At the end of the file name after a "_" character the number of the log file is appended for the log-file rotation with a 10 MB size limit. The count starts at "0". If omitted or set to an empty string, no file logging will happen. This property is optional.

logging.log_level

"trace", "debug", "info", "warning", "error", "fatal"

Minimum severity level of entries that are logged.

logging.log_to_stdout

"true", "false"

"false"

Control whether logging to stdout will be performed.

logging.log_sensitive- _data

"true", "false"

"false"

Whether to log potentially sensitive data such as HTTP requests and responses. This feature can only be activated in a debug build version of the library. Activating it for the normal library version does not have any effect.

pkcs11_server Properties

Property name Possible values Default value Description

pkcs11_server.hostname

a valid host name

Host name of the PKCS#11 Server.

pkcs11_server.port

an integer value

Port used by the PKCS#11 Server.

pkcs11_server.target

a valid URL path on the host.

"/kms-pkcs11-server/pkcs11/"

Target URL path of the PKCS#11 Server.

pkcs11_server.maximum- _number_of_connections

an integer value

100

Maximum number of parallel connections that are allowed to be built up by the MTG KMS PKCS#11 Library.

token Properties

Property name Possible values Default value Description

token.login_username

any ASCII character string excluding the "," character

The username of the user (i.e. tenant client) at the PKCS#11 server under which the application shall operate. This username will always be used when the C_Login function of the PKCS#11 interface is invoked.

tls Properties

Property name Possible values Default value Description

tls.peer_root_cert_pem- _path

a valid file path

Path to the root certificate of the TLS certificate of the PKCS#11 Server in PEM format. This certificate is used to verify the authenticity of the PKCS#11 Server.

tls.client_pkcs12_path

a valid file path

PKCS#12 File containing the certificate and secret key for client authentication. If this option contains a non-empty string, the file specified there is used for TLS client authentication. Otherwise, the certificate and secret key for client authentication must be set in the two options described below.

tls.client_cert_pem_path

a valid file path

The file containing the client certificate in PEM format. This option is not evaluated if tls.client_pkcs12_path is set to a non-empty value.

tls.client_key_pem_path

a valid file path

The private key file to the client certificate chain in client_cert_chain_pem_path. This option is not evaluated if tls.client_pkcs12_path is set to a non-empty value.

tls.client_key_secret

any ASCII character string

The password to the TLS client private key (PKCS#12 file or OpenSSL key file). This property is optional. Note that for security reasons, it is recommended to place this configuration option into a separate configuration file for secrets (see secrets Properties).

secrets Properties

Property name Possible values Default value Description

secrets.secret_config- _file

a valid file path

Path to a further configuration file that may contain the configuration property tls.client_key_secret. If any property is specified both in the normal configuration file and in the one specified by secret.secret_config_file, an error is indicated and the library initialization fails.

Configuration of Third Party Applications

This section describes the configuration of third party applications for the MTG KMS PKCS#11 Library.

OpenSSL via libp11

OpenSSL can be configured to use alternate custom cryptographic implementations via OpenSSL’s engine concept. For details see OEA-MAN, OpenSSL command line man page: openssl-engine, engine - load and query engines. OEL-MAN, and OEC-MAN. libp11 is a library that provides such an OpenSSL engine and functions as a wrapper for a PKCS#11 implementation. By the use of an appropriate engine configuration for OpenSSL for libp11 it is possible to use the MTG KMS PKCS#11 Library inside an OpenSSL engine. In order to correctly configure the MTG KMS PKCS#11 Library via libp11 as the cryptographic backend for OpenSSL, the corresponding engine section in the file openssl.cnf has to be specified as follows:

  • as the MODULE_PATH the path to the MTG KMS PKCS#11 Library has to be specified,

  • in case of using libp11 version 0.4.12 or higher, FORCE_LOGIN = EMPTY has to be specified.

Note that OpenSSL 3.0 requires libp11 version 0.4.12 or higher, since earlier versions of libp11 have compatibility issues with OpenSSL 3.0.

An example of such an engine section is given in the following listing:

[pkcs11_section]
    engine_id = pkcs11
    dynamic_path = /usr/lib/x86_64-linux-gnu/engines-1.1/pkcs11.so
    MODULE_PATH =  /etc/mtg-kms-pkcs11-lib/libkmspkcs11.so
    FORCE_LOGIN = EMPTY
    init = 0

Note that in order for this specification to take effect, the named section has to be referenced as an engine section appropriately in the configuration file openssl.cnf as described in OEC-MAN.

References

  • [] PKCS #11 Cryptographic Token Interface Base Specification, Version 3.0, OASIS Standard, 15 June 2020