MTG KMS 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 number and context path, as follows:

Application Port number Context path

KMS-Server

8801 (AJP)

kms

KMS-Server

8601 (HTTP)

kms

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

Heap Size

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

Application File The maximum heap size The initial Java heap size

KMS-Server

mtg-kms-server.service.conf

-Xmx512M

-Xms512M
The heap size must be adapted to your requirements, especially the mtg-kms-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/<Application> 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 must 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!
The connection to the KeyCloak Server is optional, meaning its only needed if using the Admin- or Tenant-REST-API, in order to authenticate a user. All KeyCloak configuration parameters Keycloak (OpenID) properties can be omitted if using the KMS Server with the KMIP-API only. If the KeyCloak parameters are set, then they must hold valid values and the Keycloak Server must be available.

Audit configuration

The audit configuration is carried out via the logback.xml file, which is already preset during installation. It is possible to set your own, self-generated/defined key in sizes 128 or 192 or 256 bit for the signature. To do this, the keyword OwnSecret must be entered in the appender tag in the applicationName and enter the tag secretKey with the generated/defined key as a hexadecimal value. For example:

<applicationName>OwnSecret</applicationName>
<secretKey>12E9E00909117122FB45F77FF1930DAB</secretKey>

Configuration of the KMS-Server

Application Configuration

The kms-server is a standalone Java-Application.

The applet’s application.properties are located in:

/etc/opt/kms-server/application.properties

Possible parameters are:

Server properties

Name Description

server.address

The IP address, the server is listen on. The default value is 127.0.0.1

server.port

The HTTP port number. The default value is 8601

Tomcat properties

Name Beschreibung

tomcat.ajp.enabled

Whether AJP is enabled or not. The default value is true

tomcat.ajp.port

The AJP port number. The default value is 8801

tomcat.ajp.maxThreads

The maximum number of request processing threads to be created, which therefore determines the maximum number of simultaneous requests that can be handled.

tomcat.ajp.minSpareThreads

The minimum number of threads always kept running.

tomcat.ajp.processorCache

The protocol handler caches Processor objects to speed up performance. This setting dictates how many of these objects get cached.

tomcat.ajp.secretRequired

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.

tomcat.ajp.secret

Only requests from 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.

Database properties

Name Beschreibung

spring.datasource.url

JDBC-URL for DBMS. Default is PostgreSQL jdbc:postgresql://localhost:5432/<db-name>

Please insert the valid URL for your database.

spring.datasource.username

KMS Username DBMS

spring.datasource.password

KMS Password DBMS

spring.datasource.tomcat.initial-size

Initial number of connections that are created when the pool is started. (Default: 10)

spring.datasource.tomcat.max-active

Maximum number of active connections that can be allocated from this pool at the same time. (Default: 100)

spring.datasource.tomcat.max-idle

Maximum number of connections that should be kept in the pool at all times. (Default: 100)

spring.datasource.tomcat.min-idle

Minimum number of established connections that should be kept in the pool at all times. (Default: \{initial-size=10})

spring.datasource.tomcat.time-between-eviction-runs-millis

Number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. (Default: 5000 = 5 seconds)

spring.datasource.tomcat.min-evictable-idle-time-millis

Minimum amount of time an object may sit idle in the pool before it is eligible for eviction. (Default: 60000 = 1 minute)

spring.flyway.enabled

If this attribute is true, Flyway is enabled for automatic database migrations. The default value is true.

spring.flyway.locations

The locations for Flyway to scan for migration scripts (Default: classpath:flyway/migration/{vendor} and the vendor placeholder is replaced automatically).

HSM properties

Name Beschreibung

hsm.keystore.password

Master password for securing the file based HSM keystore.

The KeyStore entries are secured with their own tenant-specific password

hsm.pool.min-idle-per-key

Min number of sessions to keep alive per HSM-Profile (Default: 0)

hsm.pool.max-total-per-key

Max number of sessions per HSM-Profile (Default: 10)

hsm.pool.max-idle-per-key

Max number of idle sessions per HSM-Profile (Default: 10)

hsm.pool.time-between-eviction-runs-millis

How often to make an eviction/keep-alive run in milliseconds. (Default: 600000 = 10 minutes)

hsm.pool.soft-min-evictable-idle-time-millis

When to evict idle sessions in milliseconds. (Default: 1800000 = 30 minutes)

Mini-CA properties

Name Description

minica.schema

Scheme for the connection towards the Mini-CA. Either http or https. Default is https.

minica.host

IP address of the Mini-CA. Default is empty.

minica.port

Port of the Mini-CA. Default is empty.

minica.base-path

Path of the Mini-CA URL. Default is empty.

minica.username

Mini-CA client username. Default is empty.

minica.password

Mini-CA client password. Default is empty.

minica.proxy-host

Proxy hostname for the connection towards the Mini-CA. Default is empty.

minica.proxy-port

Proxy port for the connection towards the Mini-CA. Default is 3128.

minica.ssl.enabled

SSL connection towards the Mini-CA. Default is true.

minica.ssl.trust-self-signed-certificates

Connection is trusted for self-signed certificates. Default is false.

minica.ssl.allow-all-host-names

No host name verification. Default is false.

minica.ssl.truststore.path

Path inclusive name for an arbitrary truststore. Default is empty.

minica.ssl.truststore.type

Type of the truststore, e.g. JKS. Default is empty.

minica.ssl.truststore.password

Password of the truststore. Default is empty.

minica.template.tlsClient

Mini-CA template name (identifies which template to use when generating KmsClient certificates). Default is End Entity (TLS Client)

Keycloak (OpenID) properties

Name Description

openid.client.basic.client-id

The Keycloak client id associated with the MTG KMS Server.

openid.client.basic.client-secret

The Keycloak client secret associated with the MTG KMS Server.

openid.client.admin.base-url

Keycloak ADMIN REST API base url. Example: example.com/auth/admin/realms/mtg-ers

spring.security.oauth2.resourceserver.jwt.issuer-uri

Keycloak OPENID base url.

Example: example.com/auth/realms/mtg-ers

spring.security.oauth2.resourceserver.jwt.jwk-set-uri

Keycloak public key endpoint, that returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK).

Example: example.com/auth/realms/mtg-ers/protocol/openid-connect/certs

openid.client.truststore.path

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

openid.client.truststore.password

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

openid.client.truststore.type

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

openid.client.tls-version

The version of the TLS protocol to use in the connection to Keycloak. Valid values are TLSv1.2.

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.

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 apache configuration page contains information on the configuration of the Apache httpd-server.

Encryption

For the SSL connection between the components from MTG KMS and external software 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 MTG KMS 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. Otherwise, the instructions in [secure_communication] apply.

See System monitoring basic authentication properties for the possible parameters.

Info Endpoint

For retrieving information about the MTG KMS 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 MTG KMS is accessible, a Http response with HTTP/1.1 200 OK and the following JSON structure is returned.

{
  "app": {
    "version": "3.1.0"
  },
  "license": {
    "current": 19,
    "max": 20,
    "exceeded": false,
    "type": "DEMO",
    "status": "VALID"
  }
}
Name Description

app.version

The version number of the MTG KMS.

license.current

The current number of ManagedObjects, for the current licence.

license.max

The maximum number of ManagedObjects for the current licence.

license.type

The type of the current licence.

license.status

The status of the current licence.

Health Endpoint

For checking the MTG KMS, 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 MTG KMS is accessible, n Http response with HTTP/1.1 200 OK and the following JSON structure is returned.

{
  "status": "UP",
  "components": {
    "openID": {
      "status": "UP",
      "details": {
        "url": "http://localhost:8081/auth/realms/mtg-ers"
      }
    }
  }
}
Name Description

status

Status of the whole system (UP or DOWN).

components.openID.status

Status of the connection to the Keycloak server of the entire system (UP or DOWN). If Keycloak server is configured, the status is NO_CLIENT.

components.openID.details.url

The URL for the connection test to the Keycloak server.

components.openID.details.err

If the status is DOWN, an additional error message