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
MASTER_SERVER_HOST=serverName.domainName
MASTER_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 SSL 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 SSL 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 SSL certificate for authenticating the client during communication with the KMIP key manager.

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).

MASTER_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.)

MASTER_SERVER_KMIP_PORT

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

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 SSL 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.

ALL_SERVER_UNAVAILABLE_SLEEP

Optional. 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.

¹ Error SQL1782N is returned by the GSKit layer (manifested as error DIA3604E: The SSL 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