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.1
- SSL_KMIP_CLIENT_HOSTNAME_VALIDATION
- Parameter type: Optional.
- 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
Note: Support for the TLSVERSION parameter is available in Db2 11.5.8 and later versions.
1 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.