Creating a KMIP keystore configuration file

To use Db2® native encryption to store your master key or keys in a centralized keystore using KMIP, you need to create a configuration file that lists details about the keystore.

Procedure

On the Db2 server, create the KMIP keystore configuration file in a text editor.
Example
VERSION=1
PRODUCT_NAME=ISKLM
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=true
SSL_KEYDB=/home/userName/sqllib/security/keydb.p12
SSL_KEYDB_STASH=/home/userName/sqllib/security/keydb.sth
SSL_KMIP_CLIENT_CERTIFICATE_LABEL=db2_client_label
PRIMARY_SERVER_HOST=serverName.domainName
PRIMARY_SERVER_KMIP_PORT=kmipPortNumber
CLONE_SERVER_HOST=clone1.domainName
CLONE_SERVER_KMIP_PORT=kmipPortNumber
CLONE_SERVER_HOST=clone2.domainName
CLONE_SERVER_KMIP_PORT=kmipPortNumber
Keywords
VERSION
  • Parameter type: Required.
  • Supported values: 1.

Version of the configuration file. Currently, 1 is the only supported value.

PRODUCT_NAME
  • Parameter type: Required.
  • Supported values:
    • ISKLM for IBM® Security Key Lifecycle Manager.
    • KEYSECURE for SafeNet KeySecure.
    • OTHER for any other key manager that supports the Key Management Interoperability Protocol (KMIP) version 1.1 or higher.

Name of the KMIP key manager product

DEVICE_GROUP
  • Parameter type: Required (ISKLM only).

Name of the KMIP key manager device group containing the keys used by the Db2 server. Do not specify this parameter when using KeySecure or another KMIP key manager.

SSL_KEYDB
  • Parameter type: Required.

Absolute path and name of the local keystore file that holds the TLS certificates for communication between the Db2 server and the KMIP key manager.

SSL_KEYDB_STASH
  • Parameter type: Optional.
  • Default value: None.

Absolute path and name of the stash file for the local keystore that holds the TLS certificates for communication between the Db2 server and the KMIP key manager.

SSL_KMIP_CLIENT_CERTIFICATE_LABEL
  • Parameter type: Required, configurable online.

The label of the TLS certificate for authenticating the client during communication with the KMIP key manager.

PRIMARY_SERVER_HOST
  • Parameter Type: Required.

Host name or IP address of the KMIP key manager. (For ISKLM, this information is available on the Welcome tab of the web console.)

PRIMARY_SERVER_KMIP_PORT
  • Parameter type: Required.

The KMIP TLS port of the KMIP key manager. (For ISKLM, this information is available on the Welcome tab of the web console).

CLONE_SERVER_HOST
  • Parameter type: Optional.
  • Default value: None.

Host name or IP address of secondary KMIP keystore. You can specify up to five clone servers by repeating the CLONE_SERVER_HOST and CLONE_SERVER_KMIP_PORT parameter pairs in the configuration file, each host with a different value. Clone servers are considered read-only and are only used for retrieving existing master keys from the KMIP keystore. Clone servers are not used when inserting a new key, which occurs when an existing master key label has not been specified for the CREATE DATABASE ENCRYPT or ADMIN_ROTATE_MASTER_KEY commands, or for the db2p12tokmip executable.

CLONE_SERVER_KMIP_PORT
  • Parameter type: Optional.
  • Default value: None.

The KMIP TLS port of secondary KMIP keystore. You can specify up to five clone servers by repeating the CLONE_SERVER_HOST and CLONE_SERVER_KMIP_PORT parameter pairs in the configuration file, each host with a different value.

ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP
  • Parameter type: Optional, configurable online.
  • Supported values: TRUE, FALSE.
  • Default value: FALSE.

Allow the database manager to insert new keys into the KMIP key manager. New keys are inserted when the CREATE DATABASE ENCRYPT or ADMIN_ROTATE_MASTER_KEY commands are run without a specified existing master key label, or when the migration tool db2p12tokmip is run. When this parameter is set to TRUE, new keys are allowed to be inserted, if set to FALSE an error is returned if the database manager attempts to insert a new key. You should only set this to TRUE if you are not creating your master keys within the KMIP key manager, and you have an automated backup solution of your KMIP key manager for newly inserted keys. This parameter must be set to TRUE if you are migrating keys by using the db2p12tokmip command. It can be changed to FALSE after the tool has completed.

ALLOW_NONCRITICAL_BASIC_CONSTRAINT
  • Parameter type: Optional.
  • Supported values: TRUE, FALSE.
  • Default value: FALSE.

If you set the parameter to TRUE, this allows Db2 to use local Certificate Authority within KMIP server that does not have a critical keyword set and avoids 414 error that is returned by IBM Global Security Kit (GSKit).

SSL_KMIP_CLIENT_HOSTNAME_VALIDATION
  • Parameter type: Optional.
  • Supported values: BASIC, OFF.
  • Default value: OFF.

If you set this value to BASIC, Db2 validates that the hostname of the KMIP server is contained within the certificate used by the KMIP server when establishing the TLS connection. This hostname is sourced from either the MASTER_SERVER_HOST or CLONE_SERVER_HOST parameter. The validation rules follow RFC 6125 for validating the hostname in the common name or Subject Alternate Name (SAN) fields of the certificate. The KMIP server product documentation will need to be consulted to determine how to create an appropriate certificate. For more information about TLS hostname validation, see Hostname validation for Db2 11.5.6 clients. If you set this value to OFF, Db2 does not validate the hostname.

COMMUNICATION_ERROR_RETRY_TIME
  • Parameter type: Optional, configurable online.
  • Default value: 50.

The number of times the Db2 database manager cycles through the list of configured master and clone KMIP key managers if the connection fails or an error is returned from all of the KMIP key managers. A wait of a length specified in the ALL_SERVER_UNAVAILABLE_SLEEP parameter is inserted before each cycle.

UNAVAILABLE_SERVER_BLACKOUT_PERIOD
  • Parameter type: Optional, configurable online.
  • Default value: 300.

The amount of time, in seconds, to skip sending key requests to a particular master or clone KMIP key manager after a failed connection attempt or it has returned errors.

ALL_SERVER_UNAVAILABLE_SLEEP
  • Parameter type: Optional, configurable online.
  • Default value: 0.

When all master and clone KMIP key managers are unavailable and in a blackout period, this parameter is the amount of time to wait, in seconds, before removing the blackout period and reattempting connections to all KMIP key managers.

TLSVersion
  • Parameter Type: Optional
  • Supported Values: TLSV12, TLSV13
  • Default Value: TLSV12,TLSV12

Indicates the TLS version to be used when connecting to a KMIP Key Manager. When the TLSVERSION keyword is not set, the default behavior is to enable both TLS 1.2 and TLS 1.3