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

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

PRODUCT_NAME

Required. Key manager product. 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

ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP

Optional: 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. Default value: FALSE.

ALLOW_NONCRITICAL_BASIC_CONSTRAINT

Optional. 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 GSKit. This parameter was introduced in Db2 V11.1.2.2. Default value: FALSE.¹

SSL_KEYDB

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

Optional. 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. Default value: None.

SSL_KMIP_CLIENT_CERTIFICATE_LABEL

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

SSL_KMIP_CLIENT_HOSTNAME_VALIDATION

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. Default value: OFF.

DEVICE_GROUP

Name of the KMIP key manager device group containing the keys used by the Db2 server. This parameter is only required for IBM Security Key Lifecycle Manager (ISKLM).

PRIMARY_SERVER_HOST

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

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

Note: The KMIP configuration file parameters MASTER_SERVER_HOST and MASTER_SERVER_KMIP_PORT are still accepted but have been deprecated. Use PRIMARY_SERVER_HOST and PRIMARY_SERVER_KMIP_PORT instead.

CLONE_SERVER_HOST: Optional. Host name or IP address of secondary KMIP keystore. Default value: None. 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: Optional. The "KMIP TLS port" of secondary KMIP keystore. Default value: None. 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.
COMMUNICATION_ERROR_RETRY_TIME: Optional. 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. Default value: 50.
UNAVAILABLE_SERVER_BLACKOUT_PERIOD: Optional. 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. This parameter was introduced in Db2 V11.1.2.2. Default value: 300 seconds.
(Optional) ALL_SERVER_UNAVAILABLE_SLEEP: 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. This parameter was introduced in Db2 V11.1.2.2. Default value: 0 seconds.

(Optional) TLSVERSION

Indicates the TLS version to be used when connecting to a KMIP Key Manager.
Allowed values include the following:

TLSV12
TLSV13

When the TLSVERSION keyword is not set, the default behavior is to enable both TLS 1.2 and TLS 1.3

Note: Support for the TLSVERSION parameter is available in Db2 11.5.8 and later versions.

¹ Error SQL1782N is returned by the GSKit layer (manifested as error DIA3604E: The TLS function "gsk_secure_soc_init" failed with the return code "414" in "sqlccSSLSocketSetup" in the db2diag.log) in case the basic constraints extension of the certificate that is issued by the Certificate Authority (CA) does not have the 'critical' keyword asserted. Using the command "

gsk8capicmd_64 -cert -details -db <filename>
-stashed -label <localCALabel>

" you can check the basic constraints of the CA to see whether the keyword 'critical' is asserted. For a local CA the keyword 'critical' might not be set.

Example:

Extensions
    basicConstraints
        ca = true
        pathLen = 140730370034921
        critical