MTG KMS PKCS#11 Server System configuration

Context Path and port numbers of the applications

The application includes an embedded Tomcat web server that is accessible via the AJP or HTTP protocol from an Apache web server. The application has its own AJP and HTTP port numbers and context path, as follows:

Application Port number Context path

KMS-PKCS#11-Server

8804 (AJP)

kms-pkcs11-server

KMS-PKCS#11-Server

8604 (HTTP)

kms-pkcs11-server

These port numbers must be defined inside the worker.properties file.
Example for the KMS-PKCS#11-Server application: worker.kms-pkcs11-server.port=8801

Heap Size

Each application will be started with a defined heap size. The heap size is defined in the /etc/opt/mtg-kms-server directory. The following table defines for each application the size of the heap and the file where the heap size is set.

Application File The maximum heap size The initial Java heap size

KMS-PKCS#11-Server

mtg-kms-pkcs11-server.service.conf

-Xmx512M

-Xms512M
The heap size must be adapted to your requirements, especially the mtg-kms-pkcs11-server.service.conf

Starting the application

To be able to use Redisson the Java executable has to be started using the following additional arguments:

--add-opens=java.base/java.util=ALL-UNNAMED
--add-opens=java.base/java.util.concurrent=ALL-UNNAMED
--add-opens=java.base/java.time=ALL-UNNAMED

These arguments have to be added to the variable JAVA_OPTIONS in mtg-kms-pkcs11-server.service.conf.

Configuration files

There are always two configuration files, one is the application.properties for the Java-Application and the other is the logback.xml for the log configuration.

During the initial installation the application.properties and logback.xml are pre-set with default values copied from the corresponding configuration templates. All values have to be checked and if required, changed to their appropriate values.

The default configuration templates are stored in the /etc/opt/<ApplicationName> directory.

After an update installation, the package management may place a newer version of the config files beside your existing. Always compare the default configuration files in 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.
Parameters in configuration files are always case-sensitive!

Configuration file of the MTG KMS PKCS#11 Server

The MTG KMS PKCS#11 Server is a standalone Java-Application.

The applet’s application.properties is located in:

/etc/opt/<ApplicationName>/application.properties

The application configuration consists of the following parts.

Tomcat AJP properties

By default, the MTG KMS PKCS#11 Server is configured to be connected by AJP from an Apache HTTP server. Use the following properties to configure AJP for the embedded Tomcat. A description of the properties can be found on tomcat.apache.org/tomcat-9.0-doc/config/ajp.html.

tomcat.ajp.maxThreads=200 (1)
tomcat.ajp.minSpareThreads=10 (2)
tomcat.ajp.processorCache=200 (3)
tomcat.ajp.secretRequired=false (4)
tomcat.ajp.secret= (5)
1 The maximum number of request processing threads to be created, which therefore determines the maximum number of simultaneous requests that can be handled.
2 The minimum number of threads always kept running.
3 The protocol handler caches Processor objects to speed up performance. This setting dictates how many of these objects get cached.
4 If this attribute is true, the AJP Connector will only start if the secret attribute is configured with a non-null, non-zero length value. The default value is false.
5 Only requests from Apache workers with this secret keyword will be accepted. The default value is null. This attribute must be specified with a non-null, non-zero length value if secretRequired is explicitly configured to be true. Match the secret to the defined worker<worker.list.name>.secret in the worker.properties see [mod_jk configuration].

If the AJP connector of Tomcat shall not be used with Apache HTTP server, set tomcat.ajp.enabled to false to disable Tomcat AJP connector.

The default HTTP server port is 8604 and server.address is restricted to 127.0.0.1 by default. With disabled Tomcat AJP connector it may be necessary to comment out this restriction if a reverse proxy is used to accept SSL/TLS client connections on another machine or if Tomcat should accept SSL/TLS client connections itself.

In the latter case keystore and truststore have to be configured appropriately. The property server.ssl.client-auth must be set to need because a client has to authenticate by TLS Client Authentication using a certificate of a tenant of MTG KMS.

Keystore and truststore have to be configured too, if a reverse proxy is used which connects to Tomcat via TLS. If there is no client certificate used to authenticate the reverse proxy, set server.ssl.client-auth to 'none'.

Do not mix up certificates of the applications’s client and client certificates which may be used by a reverse proxy!

Reverse proxy properties

If a reverse proxy is used to terminate the incoming TLS connections, it sends the received client certificates to Tomcat via HTTP header. The header field names can be configured with the following properties.

reverse-proxy.enabled=false (1)
reverse-proxy.ssl-client-cert=x-ssl-client-cert (2)
reverse-proxy.ssl-cert-chain-prefix=x-cert-chain (3)
reverse-proxy.certificate-chain-length=10 (4)
1 Enable extracting client certificates from HTTP header, if a reverse proxy is used.
2 The HTTP header field name used by the reverse proxy to send the client’s certificate.
3 The HTTP header field name prefix used by the reverse proxy to send the certificates in the certificate chain.
4 The maximum number of certificates in the certificate chain sent by the reverse proxy.
The header field names will also be used by the MTG KMS PKCS#11 Server to send the client certificates to the MTG KMS server independent on whether reverse-proxy.enabled is true or false.

kms-pkcs11-server properties

kms-pkcs11-server.return-exception-cause=false (1)
kms-pkcs11-server.return-error-messages=false (2)
kms-pkcs11-server.attribute-cache-validity-duration=1s (3)
1 If true the cause of an exception will be returned to the caller as error string within a C_RV object.
2 If true additional error messages will be returned to the caller as error string within a C_RV object.
3 The duration one entry is valid in the attribute cache (resolution: milliseconds). The default value is 1s (second), a value of 0 disables the attribute cache. A negative value is not allowed. The value can be specified using a chrono unit, e.g. 10500ms. The default chrono unit is s (seconds). See [Chrono units] for supported chrono units.

KMS properties

Properties to get access to the KMS server.

kms.host=localhost (1)
kms.port=8601 (2)
1 The host with the KMS server application running.
2 The port of the KMS server application on the host specified above. Must be greater than 0.

KMS Proxy properties (optional)

Properties for the proxy to be used to connect to the KMS server on the host specified above. If not set, no proxy will be used.

kms.proxy.host= (1)
kms.proxy.port=3128 (2)
1 The proxy host. If not set, no proxy will be used.
2 The proxy port. Must be greater than 0.

KMS Timeout properties

Properties for the timeouts for making HTTP requests to the KMS server. All values must be greater than or equal to 0. If not set, the default values will be used.

kms.timeouts.connect=10s (1)
kms.timeouts.response=30s (2)
kms.timeouts.read=30s (3)
kms.timeouts.write=30s (4)
1 The timeout for connecting to the KMS server (resolution: milliseconds). The value can be specified using a chrono unit, e.g. 10500ms. The default chrono unit is s (seconds). See [Chrono units] for supported chrono units.
2 Specifies the maximum duration allowed between each network-level read operation while reading an HTTP response (resolution: milliseconds). The value can be specified using a chrono unit. The default chrono unit is s (seconds).
3 An exception is thrown when no data was read within the specified period of time (resolution: milliseconds). The value can be specified using a chrono unit. The default chrono unit is s (seconds).
4 An exception is thrown when a write operation cannot finish in the specified period of time (resolution: milliseconds). The value can be specified using a chrono unit. The default chrono unit is s (seconds).

KMS SSL properties

The SSL properties for connections to the KMS server. If not set, connections to the KMS server will not be secured by TLS.

kms.ssl.enabled=false (1)
kms.ssl.use-insecure-trust-manager=false (2)
1 If false, connections to the KMS server will not be secured by TLS.
2 If true, all server certificates will be trusted and no hostname verification will be done. In this case no truststore is needed.

KMS SSL Truststore properties

Properties for the truststore containing at least the root certificate. If not set and "use-insecure-trust-manager" is false, the default truststore will be used. If you want to trust a self-signed certificate, add it to the truststore.

kms.ssl.truststore.path=false (1)
kms.ssl.truststore.type=JKS (2)
kms.ssl.truststore.password=false (3)
1 The path of the truststore file.
2 The type of the truststore file, JKS or PKCS12.
3 The password of the truststore file. Must be set if path is set and kms.ssl.use-insecure-trust-manager is false.

Redisson properties

Properties to cache HTTP session data in Redis by using Redisson. Caching HTTP session data must be done, when multiple instances of the MTG KMS PKCS#11 Server are run as a cluster.

redisson.session-manager.enabled=false (1)
redisson.session-manager.config-path= (2)
1 If false, HTTP session data will not be cached in Redis.
2 The path of the Redisson YAML configuration file. See Redisson Configuration for the configuration options.

Important Spring properties

There is a huge amount of Spring properties. The following properties are important concerning the MTG KMS PKCS#11 Server.

server.servlet.session.timeout=30m (1)
1 The period of inactivity after a session will become invalid. If there are long living clients it may be necessary to increase this value. But take into account that the server does not know when a client has finished and therefore the session data will be deleted not before a session timeout occurs. A better way to handle long living clients is to demand keep alive calls during inactivity.

Metrics (OpenSearch) properties

Name Description

management.elastic.metrics.export.enabled

If set to true then metrics are sent to an OpenSearch server. It can be left empty.

management.elastic.metrics.export.host

Specifies the URL where the OpenSearch server can be accessed. It can be left empty.

management.elastic.metrics.export.user-name

Specifies the user who has access to the OpenSearch server. It can be left empty.

management.elastic.metrics.export.password

Specifies the password of the user of the OpenSearch server. It can be left empty.

metrics.client.truststore.path

The location of a keystore file containing certificates that are used to verify the TLS connection to Opensearch Server. This can be used to overwrite the default Java CA truststore.

metrics.client.truststore.password

The password for the truststore. Must be set if metrics.client.truststore.path is set.

metrics.client.truststore.type

The format of the truststore (see property metrics.client.trustStore.path). Valid values are JKS, JCEKS or PKCS12. Must be set if metrics.client.truststore.path is set.

Other properties

pkcs11.login.credentials.secret= (1)
1 A secret of 16 bytes encoded by Base64 used to encrypt the PKCS#11 user’s credentials before they are stored within an HTTP session for later use e.g. for a signing operation.

System monitoring basic authentication properties

Name Description

actuator.basicAuth

Defines whether basic auth should be used or not.

actuator.username

The username for BasicAuth

actuator.password

The password for BasicAuth

Apache configuration

The chapter Apache configuration contains information on the configuration of the Apache httpd-server.

Encryption

For the SSL connection between the MTG KMS PKCS#11 Server and the external caller a certificate is required. The configuration for the SSL certificate with private key and chain is contained in the apache-config.

System monitoring

General

For checking the the MTG KMS PKCS#11 Server different endpoints are provided which can be reached via the following URL:

  • <base URL>/actuator/info

  • <base URL>/actuator/health

The access to these endpoints is normally not further secured, but basic authentication can also be configured for access.

See System monitoring basic authentication properties for the possible parameters.

Info Endpoint

For retrieving information about the the MTG KMS PKCS#11 Server an endpoint is provided which can be reached via the following URL:

  • <Base URL>/actuator/info

An example call would be in the browser:

or with curl:

If the the MTG KMS PKCS#11 Server is accessible, a Http response with HTTP/1.1 200 OK and the following JSON structure is returned.

{
  "app": {
    "version": "1.2.0"
  }
}
Name Description

app.version

The version number of the the MTG KMS PKCS#11 Server .

Health Endpoint

For checking the the MTG KMS PKCS#11 Server, an endpoint is provided that can be reached via the following URL:

  • <base URL>/actuator/health

An example call would be in the browser:

or with curl:

If the the MTG KMS PKCS#11 Server is accessible, a Http response with HTTP/1.1 200 OK and the following JSON structure is returned.

{
  "status": "UP"
}