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