Installation

This guide explains how to encrypt an IBM Db2 database with a master key managed on a Securosys HSM. Learn how to configure Db2, set up the necessary credentials, connect to the Securosys KMIP Server, and enable encryption.

Prerequisites

Before you start, make sure that you have the basic components deployed:

• An IBM Db2 instance.
  • This guide was tested with Db2 v11.5.9. Native encryption is included Db2 v11.1 and later.
• A Securosys Primus HSM or CloudHSM
• A Securosys CyberVault KMS, including the Securosys KMIP Server.
  • For details, see the KMIP Server installation guide.

Additionally, you need:

• gsk8capicmd_64, the GSKit tool used to build the local keystore. It ships with Db2, typically under ~/sqllib/gskit/bin.
• Network connection between the Db2 server and the KMIP Server on port 5696 (default).
• The CyberVault KMS TLS CA certificate must be CA:TRUE + keyCertSign, digitalSignature and serverAuth.
• KMIP client credentials issued by CyberVault KMS. Download them as PKCS#12 files:
  • the client certificate
  • the client private key
  • the CA certificate that issued the client certificate.

Please note the following:

• MASTER_SERVER_HOST (to be configured in Db2 below) must match a name present in the Subject Alternative Name of the TLS server certificate of the KMIP Server.
• All certificates must be signed with a signature algorithm that uses SHA2 and use a key of at least 2048 bits. SHA1 is not supported.

In the examples below, /database/config/db2inst1/kmip is the working folder that holds the keystore and configuration file. Use an absolute path owned by the Db2 instance user, and run all commands as that user.

Build the keystore

Db2 uses a local PKCS#12 keystore for the TLS connection to the KMIP Server. It must contain the client identity (certificate plus private key), the CyberVault KMS Server CA, and the CA that issued the client certificate. All the necessary files can be downloaded from CyberVault KMS, as described in the Client credentials download.

Start by creating and initializing a fresh keystore file. The -stash option writes the password stash file alongside it.

gsk8capicmd_64 -keydb -create \
  -db /database/config/db2inst1/kmip/clientkeydb.p12 \
  -pw <keystore-password> -type pkcs12 -stash

Next, find the label of the client certificate in the PKCS#12 bundle that you downloaded from CyberVault KMS. Use the password that you set in CyberVault KMS when you downloaded the PKCS#12 file. Find the label (distinguished name) from the list.

gsk8capicmd_64 -cert -list -db ibm-db2-client.p12 -pw <bundle-password>

Import the client identity into the keystore. This command copies the identity from the PKCS#12 file downloaded from CyberVault KMS into the PKCS#12 file created locally for Db2. It also renames the client identity to a short label with -new_label.

gsk8capicmd_64 -cert -import \
  -db ibm-db2-client.p12 -pw <bundle-password> \
  -target /database/config/db2inst1/kmip/clientkeydb.p12 -target_pw <keystore-password> \
  -label "<label-from-the-list>" -new_label ibm-db2

Then add the KMS Server CA and the client's issuing CA, both as trusted signers.

gsk8capicmd_64 -cert -add \
  -db /database/config/db2inst1/kmip/clientkeydb.p12 -pw <keystore-password> \
  -label securosys-kmip-ca -file kmip-server.pem -format ascii

gsk8capicmd_64 -cert -add \
  -db /database/config/db2inst1/kmip/clientkeydb.p12 -pw <keystore-password> \
  -label kms-kmip-user-ca -file kms-user-ca.pem -format ascii

Confirm all three certificates are present.

gsk8capicmd_64 -cert -list -db /database/config/db2inst1/kmip/clientkeydb.p12 -pw <keystore-password>

The list should show the client identity as personal (-) and both CAs as trusted (!).

!       kms-kmip-user-ca
!       securosys-kmip-ca
-       ibm-db2

warning

Build the keystore with gsk8capicmd_64, not OpenSSL. GSKit cannot open a PKCS#12 written by OpenSSL and fails with GSKit error 408.

Create the KMIP configuration file

Db2 reads the KMIP settings from a dedicated configuration file. Create /database/config/db2inst1/kmip/kmip.cfg with the following content.

VERSION=1
PRODUCT_NAME=OTHER
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=false
SSL_KEYDB=/database/config/db2inst1/kmip/clientkeydb.p12
SSL_KEYDB_STASH=/database/config/db2inst1/kmip/clientkeydb.sth
SSL_KMIP_CLIENT_CERTIFICATE_LABEL=ibm-db2
ALLOW_NONCRITICAL_BASIC_CONSTRAINT=false
MASTER_SERVER_HOST=kmip-server.cloudshsm.com
MASTER_SERVER_KMIP_PORT=5696
CLONE_SERVER_HOST=
CLONE_SERVER_KMIP_PORT=

Setting	Purpose
PRODUCT_NAME	OTHER for Securosys, which is not one of IBM's named key managers
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP	Instructs Db2 to fetch (Get) a pre-existing master key on the HSM during CREATE DATABASE ENCRYPT or ADMIN_ROTATE_MASTER_KEY.
SSL_KEYDB / SSL_KEYDB_STASH	Absolute paths to the keystore and its stash file. They must share the same base name
SSL_KMIP_CLIENT_CERTIFICATE_LABEL	The label of the client certificate inside the keystore (ibm-db2 above)
ALLOW_NONCRITICAL_BASIC_CONSTRAINT	Set to true only for a CA whose basic constraints are not marked critical (GSKit error 414). It does not relax the CA:TRUE requirement
MASTER_SERVER_HOST / MASTER_SERVER_KMIP_PORT	The KMIP Server hostname and port. The hostname must appear in the server certificate's SAN
CLONE_SERVER_HOST / CLONE_SERVER_KMIP_PORT	Leave blank for standard CyberVault KMS setup. Optional failover KMIP endpoints that connects to the same Partition. Db2 tries them if the primary is unreachable.

warning

Db2 requires the file paths in kmip.cfg to be absolute.

Use the KMIP keystore

Set the keystore type and location, then restart the instance for the change to take effect.

db2 update dbm cfg using keystore_type kmip keystore_location /database/config/db2inst1/kmip/kmip.cfg

db2stop
db2start

warning

Set keystore_type and keystore_location in the same command. Setting them separately fails with SQL6112N, because the type and location must be valid together.

Confirm the instance picked up the settings.

db2 get dbm cfg | grep -i keystore

Keystore type       (KEYSTORE_TYPE) = KMIP
Keystore location   (KEYSTORE_LOCATION) = /database/config/db2inst1/kmip/kmip.cfg

Encrypting a database

Pre-create a key to use as master key using the Key Manager UI of CyberVault KMS.

Then run the command below to tell Db2 to encrypt the database, giving it the key label as a reference to the KMIP object.

db2 create database ENCRYPTED encrypt master key label '<kmip-name>'

tip

To encrypt an existing unencrypted database instead, use a backup and restore with the encrypt option, rather than create database. You can read more about it in this IBM Db2 tutorial.

Verification

Confirm that encryption is active from the point of view of the database config, a database query, and CyberVault KMS.

1. Confirm via database config

The database configuration should show the database to be encrypted:

db2 connect to ENCRYPTED
db2 get db cfg for ENCRYPTED | grep -i "Encrypted database"

 Encrypted database = YES

2. Confirm via database query

Alternatively, you can use a database query to check the encryption state.

The full ADMIN_GET_ENCRYPTION_INFO output is one very wide row. Select the relevant columns for a more readable result.

db2 -x "SELECT ALGORITHM, ALGORITHM_MODE, KEY_LENGTH, KEYSTORE_TYPE, KEYSTORE_HOST, MASTER_KEY_LABEL \
        FROM TABLE(SYSPROC.ADMIN_GET_ENCRYPTION_INFO())"

This should report AES, CBC, 256, KMIP, the KMIP Server host, and a master key label of the form DB2_SYSGEN_db2inst1_ENCRYPTED_<timestamp>_<id>.

You can also check with db2pd:

db2pd -db ENCRYPTED -encryptioninfo

3. Confirm via CyberVault KMS

The Securosys KMIP Server log records the fetching of the master key. For the master key label, it shows a Get operation with ResultStatus: Success.

keymanager logs kms-kmip-server | grep <master key label>

tip

Because Db2 exports the master key from the HSM to the Db2 instance memory, the key usage count shown in CyberVault KMS web UI is always zero. The usage count only counts operations performed inside the HSM.

Master key retention

Master keys are needed to access the DEKs that are stored in encrypted databases, transaction logs, and backup images. Since multiple master keys can exist over the life time of these objects, it is necessary to retain them while the encrypted data is retained. Therefore, do not delete master keys from the keystore.

Troubleshooting

Each error below is followed by its cause and fix.

SQL6112N reason code 16

keystore_type and keystore_location were set in separate commands. Set both in a single update dbm cfg command.

SQL1781N reason code 7 (SSL_KEYDB)

The SSL_KEYDB path in kmip.cfg does not match a keystore on disk. Correct the path so it points at the keystore you built, and make sure SSL_KEYDB_STASH shares its base name.

SQL1782N reason code 5, GSKit error 408

GSKit cannot open the keystore. Build the keystore with gsk8capicmd_64 rather than OpenSSL, and make sure the stash matches the keystore password.

SQL1782N reason code 5, GSKit error 8

Certificate validation failed. The KMIP Server certificate must be a CA (CA:TRUE), and MASTER_SERVER_HOST must match a name in its SAN.

SQL1782N reason code 5, "unexpected error opening the ssl keystore"

Seen together with "peer not authenticated" in the KMIP Server log. The CA that issued the client certificate is missing from the keystore. Add it as a trusted signer with gsk8capicmd_64 -cert -add.

SQL1782N reason code 5, KMIP parse error

Seen together with Register ... ResultReason: InvalidField, DENIED in the KMIP Server log. The KMIP identity is not allowed to register keys. Grant it Register (and Get, Locate, Activate, Destroy).

SQL1729N, label does not exist

Raised by MASTER KEY LABEL when Db2 cannot locate the key. The key must exist as a KMIP-managed object with a Name attribute matching the label. A key that exists only on the HSM or in the KMS is not locatable over KMIP.

info

In strict FIPS mode, Db2 disables TLS 1.2 ciphers that use RSA key exchange (TLS_RSA_*) and uses ECDHE ciphers instead. If the handshake fails on cipher negotiation, check whether strict FIPS mode is enabled via the DB2AUTH registry variable.

Next Steps

For more on operating native encryption, including master key rotation and encryption in an HADR environment, follow the Db2 native encryption documentation.