Creating a PKCS #11 keystore configuration file

To store master keys in a centralized PKCS #11 keystore with Db2® native encryption, you need to create a configuration file that contains details about the PKCS #11 keystore.

About this task

Procedure

On the Db2 server, create the PKCS #11 keystore configuration file in a text editor.
Example
VERSION=1
PRODUCT_NAME=Luna
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=true
LIBRARY=/usr/safenet/lunaclient/luna6.1/lib/libCryptoki2_64.so
SLOT_LABEL=DB2Partition
NEW_OBJECT_TYPE=PRIVATE
KEYSTORE_STASH=/home/userName/sqllib/security/pkcs11_pw.sth
Keywords
VERSION
Required. Version of the configuration file. Currently, 1 is the only supported value.
PRODUCT_NAME
Optional. Use this value to override the PKCS #11 keystore type that is determined from product information returned by PKCS #11 API calls.. Supported values are:
  • Luna for SafeNet (formerly Luna) hardware security module (HSM)
  • nCipher for Entrust nShield HSM (Thales is supported for backwards compatibility)
  • Other for any other key manager that supports PKCS #11
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP
Optional. Allow the database manager to insert new keys into the centralized 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 centralized key manager, and you have an automated backup solution of your centralized 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.
LIBRARY
Required. The absolute path and name (including extension) of the centralized PKCS #11 keystore vendor-supplied shared library. The format is platform-dependent:
AIX® or Linux®:
/usr/safenet/lunaclient/luna6.1/lib/libCryptoki2_64.so
/opt/nfast/toolkits/pkcs11/libcknfast.so
Windows:
C:\safenet\lunaclient\luna6.1\lib\libCryptoki2_64.dll
C:\nfast\toolkits\pkcs11\libcknfast.dll
SLOT_LABEL
Optional. Identifies the slot in the HSM by a label. The label is a name that is defined by the application, and is assigned during token initialization. If specified, the value must be 1 - 32 characters long. This parameter cannot be specified if SLOT_ID is specified.
SLOT_ID
Optional. Identifies the slot in the HSM by an ID. Must be an integer value. This parameter cannot be specified if SLOT_LABEL is specified.
NEW_OBJECT_TYPE
Optional. Defines whether new master keys generated at the PKCS #11 keystore are created as private or public objects. The default value is PRIVATE. The supported values are:
  • PRIVATE for private objects
  • PUBLIC for public objects
KEYSTORE_STASH
Optional. Absolute path and name of the stash file that holds the PKCS #11 keystore password. The instance uses the stash file to authenticate to the PKCS #11 keystore.
Note: Starting in Db2 11.5.7.0, the following configuration options are available.
RETRY_ERROR_TYPE
Optional. If an error is encountered when attempting to open the PKCS #11 keystore, this parameter controls whether or not Db2 attempts to retry the operation depending on the type of the error. The default behavior is to retry if the keystore returns an unexpected error, the configured slot was not found, or no slots were found. Supported values are:
  • UNEXPECTED_AND_NO_SLOTS: Retry if the keystore encountered an unexpected error, the configured slot was not found, or no slots were found.
  • UNEXPECTED: Retry if the keystore encountered an unexpected error .
  • NO_SLOTS: Retry if the configured slot was not found, or no slots were found.
  • ANY: Retry if any error was encountered opening the PKCS #11 keystore.
  • NONE: Never retry if an error was encountered opening the PKCS #11 keystore.
COMMUNICATION_ERROR_RETRY_TIME
Optional. Controls the number of times Db2 will retry if an error was encountered when attempting to open the PKCS #11 keystore. The default behavior is to retry once. Setting this value to 0 will prevent Db2 from attempting to retry if an error is encountered when attempting to open the keystore.
ALL_SERVER_UNAVAILABLE_SLEEP
Optional. Controls the amount of time in milliseconds that Db2 will wait before reattempting to open the PKCS #11 keystore if an error was encountered. The default behavior is to immediately reattempt.

What to do next

Create a stash file, if you choose to store the HSM credentials in a stash file.