Use KMIP secrets engine with IBM Db2

24min
|
Enterprise
Vault
Interactive

This feature requires Vault Enterprise

The KMIP secrets engine requires a Vault Enterprise Advanced Data Protection (ADP) license or HCP Vault Dedicated Plus tier cluster.

Challenge

The OASIS Key Management Interoperability Protocol (KMIP) standard is a widely adopted protocol for handling cryptographic workloads and secrets management for enterprise infrastructure such as databases, network storage, and virtual/physical servers.

Existing IBM Db2 deployments can use the KMIP protocol with a centralized key management service (KMS) to manage the keystore for Db2 native encryption to handle encrypting data at rest.

Solution

Vault Enterprise provides a KMIP secrets engine plugin that enables Vault to act as a KMIP server for IBM Db2 to manage cryptographic keys for encrypting data at rest within the database.

Vault's KMIP secrets engine enables a network listener to service KMIP requests operating on KMIP managed objects.

Vault does not enforce Access Control List (ACL) policies during these KMIP requests. Instead, the KMIP secrets engine determines the set of allowed operations the clients can perform based on roles applied to the TLS client certificate issued by Vault.

This TLS certificate role feature enables Db2 to use existing KMIP API endpoints to manage the keystore lifecycle rather than Vault API endpoints.

Persona and scenario introduction

In this tutorial scenario, you assume the role of Oliver, an engineer in operations at the fictional company HashiCups.

You have experience integrating Vault with other enterprise solutions, and your job in this scenario is to evaluate and explore the KMIP secrets engine integration with Db2.

As part of your evaluation, you need to achieve the following goals:

Enable and configure an instance of the KMIP secrets engine
Create and configure a Db2 native encryption key through KMIP
Enable the integration between Db2 and KMIP secrets engine
Enable encryption on table spaces
Enable encryption on a database
Implement key rotation
Learn how to monitor and troubleshoot the integration

You can use a terminal session, the Vault CLI, and the steps provided in this tutorial to accomplish these goals.

Prerequisites

Vault Enterprise with Advanced Data Protection (ADP) license.
Vault binary installed. (A Community Edition binary is acceptable for this tutorial)
Docker Desktop (version 4.35 or later) installed.

Confirm your Docker Desktop version

If you use an Apple Silicon Mac, ensure that you have Docker Desktop 4.35 or later, and that the Docker virtual machine manager is Docker VMM. You can confirm your configuration in the General settings in the Docker Desktop dashboard.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Set up your lab environment

If you want to follow along with the examples from this tutorial, you need to first set up your local lab environment.

You can use example code from the learn-vault-kmip-db2 repository to deploy and configure a Docker based lab with all unnecessary configuration and setup automated for your convenience.

Follow these steps to use the repository.

Open a terminal session.
Export your Vault Enterprise license string as the value of the VAULT_LICENSE_VALUE environment variable.
```
$ export VAULT_LICENSE_VALUE=<LICENSE_STRING>
```

Clone the learn-vault-kmip-db2 repository.

$ git clone https://github.com/hashicorp-education/learn-vault-kmip-db2.git

Change into the learn-vault-kmip-db2 directory.
```
$ cd learn-vault-kmip-db2
```
Deploy the container infrastructure using the docker compose command appropriate for your host computer operating system.
If your host computer runs Linux, use this command:
```
$ docker compose up -e IS_OSXFS=false -d
```
If your host computer runs macOS, use this command:
```
$ docker compose up -d
```

Tip

The infrastructure for this lab is complex enough that it needs a little time to deploy. You can check the Vault and Db2 server status to ensure service availability before you use them.

Configure Vault

Before you can prepare the Vault server, you need to export some environment variables to communicate with the server.

Export the VAULT_ADDR environment variable so the Vault command line client can reach the server.
```
$ export VAULT_ADDR=https://127.0.0.1:8200
```
The server uses self-signed TLS material. You need to export the self-signed certificate authority's certificate as the VAULT_CACERT environment variable value to avoid TLS errors.
```
$ export VAULT_CACERT=$PWD/vault/tls/ca.pem
```

Check the Vault server status to make sure it is available for use.

$ vault status
Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            1
Threshold               1
Version                 1.21.1+ent
Build Date              2025-11-18T13:05:11Z
Storage Type            raft
Cluster Name            vault-cluster-88248c4e
Cluster ID              feb880da-b5e5-23bb-5202-2636fec29a58
Removed From Cluster    false
HA Enabled              true
HA Cluster              https://127.0.0.1:8201
HA Mode                 active
Active Since            2025-12-09T18:09:49.721993137Z
Raft Committed Index    3459
Raft Applied Index      3459
Last WAL                1344

The output shows Vault initialized and unsealed. This means the server is ready for use. If your output is different, or you meet with an error, check the container status with docker ps and redeploy if necessary.

As a human user, you must authenticate with Vault to get a token before you can enable and configure the KMIP secrets engine. The token Vault gives to the oliver user after authentication has the necessary ACL policies that enable you to manage the lifecycle of the KMIP secrets engine enabled at the default path kmip/.

Use the command line and Vault's username and password auth method to authenticate with Vault as the oliver user.
```
$ vault login \
      -no-print \
      -method=userpass \
      username=oliver
```
When prompted by Vault, enter the password:
```
2Learn_Vault_secrets~
```
If the login completes without error, you authenticated with Vault and the Vault token helper has cached the token to a local file. You can confirm this by checking your token's ACL policies.
```
$ vault token lookup | grep policies
policies            [default secrets-admin]
```

You can now use this token for the command line or in Terraform.

Enable and configure KMIP secrets engine

Now that you have a suitable token, you can enable and configure the KMIP secrets engine for use with Db2.

Enable an instance of the KMIP secrets engine at the default path kmip/.

$ vault secrets enable kmip
Success! Enabled the kmip secrets engine at: kmip/

Configure the KMIP secrets engine to listen TCP port 5695 for all available interfaces, and specify the server host name values and IP addresses for the interfaces.
```
$ vault write kmip/config listen_addrs=0.0.0.0:5696 \
    server_hostnames="localhost","vault-kmip-db2" \
    server_ips="172.42.0.10" \
    default_tls_client_key_type="rsa" \
    tls_ca_key_type="rsa"
```
Example output:
```
Success! Data written to: kmip/config
```
This example also sets the default TLS client key type and TLS CA key type to the RSA algorithm.

Create a an example scope named user-acctance-testing.

$ vault write -f kmip/scope/user-acceptance-testing
Success! Data written to: kmip/scope/user-acceptance-testing

There are two pseudo-operations you can use to allow or deny all operation capabilities to a role, operation_all and operation_none. These operations are mutually exclusive to all other operations. That is, if you specify one during role creation or update, it must be the only option provided.
As a basic example for convenience, create an admin role within the user-acceptance-testing scope that allows all operations.
```
$ vault write \
    kmip/scope/user-acceptance-testing/role/admin \
    operation_all=true
```
Example output:
```
Success! Data written to: kmip/scope/user-acceptance-testing/role/admin
```

Generate a client certificate

You are ready to generate the client certificate for Db2. After you generate the certificate, you can split some of fields in the certificate output into separate files for use by the database.

Quiet commands ahead

Commands 1-5 do not produce any output.

Generate a TLS client certificate and write it to the JSON file uat-admin-credential.json within the Db2 server's /database directory.

$ vault write -format=json \
    kmip/scope/user-acceptance-testing/role/admin/credential/generate format=pem \
    > ./db2/Docker/uat-admin-credential.json

Use jq to extract the root Certificate Authority and intermediate Certificate Authority from the JSON file with some extra cleanup into a Privacy Enhanced Mail (PEM) formatted file.
```
$ jq -r '.data.ca_chain.[]' \
    < ./db2/Docker/uat-admin-credential.json \
    > ./db2/Docker/vault-kmip-ca.pem
```

Extract the client certificate from the JSON file into a PEM file.

$ jq -r .data.certificate \
    < ./db2/Docker/uat-admin-credential.json \
    > ./db2/Docker/vault-kmip-cert.pem

Extract the client certificate private key from the JSON file into another PEM file.

$ jq -r .data.private_key \
    < ./db2/Docker/uat-admin-credential.json \
    > ./db2/Docker/vault-kmip-key.pem

Combine the client public and private key files into a client bundle file for use with Db2.

$ cat ./db2/Docker/vault-kmip-cert.pem \
    ./db2/Docker/vault-kmip-key.pem \
    > ./db2/Docker/vault-kmip-client.pem

Verify that the files are all present, and that none are zero bytes in length.

$ ls -l ./db2/Docker/*.pem
-rw-r--r--@ 1 user  group  2335 Dec 11 09:08 ./db2/Docker/vault-kmip-ca.pem
-rw-r--r--@ 1 user  group  1204 Dec 11 09:08 ./db2/Docker/vault-kmip-cert.pem
-rw-r--r--@ 1 user  group  2879 Dec 11 09:08 ./db2/Docker/vault-kmip-client.pem
-rw-r--r--@ 1 user  group  1675 Dec 11 09:08 ./db2/Docker/vault-kmip-key.pem

You enabled and configured the KMIP secrets engine, generated a client certificate, and made the certificate files available to the Db2 container.

Now you can proceed to configuring Db2 to use Vault KMIP secrets engine.

Configure Db2

Your goal in this section is to configure the Db2 server with a local keystore, and then simulate a database update workflow. In this workflow, you backup, drop, and restore an existing database while enabling encryption. You then migrate the local keystore to a centralized keystore based on the Vault KMIP secrets engine.

The Db2 server is running in a Docker container named db2. Check the container logs to ensure that the database is active.

$ docker logs db2 | grep 'All databases are now active'
(*) All databases are now active.

If the logs return this string, then Db2 is active and ready.

If your output is empty try waiting a moment, and executing the command again. If you notice errors, then check the db2 container status in Docker, and redeploy if necessary.

Access a shell in the Db2 container as the db2inst1 user to begin.

$ docker exec --interactive --tty db2 bash -c "su - db2inst1"

A different prompt is expected.

When you access the Db2 container, the shell prompt changes to [db2inst1@db2 ~]$. The example commands use a simplified prompt that is just $ however, so keep this in mind.

Create and use a local keystore

Begin by creating a local keystore on disk, and then configure Db2 to use the local keystore.

Use the gsk8capicmd_64 tool to create a keystore file, and assign it a password of k3yStore_Passw0rd.

$ gsk8capicmd_64 \
    -keydb \
    -create \
    -db /database/config/db2inst1/sqllib/security/ne-keystore.p12 \
    -pw k3yStore_Passw0rd \
    -type pkcs12 \
    -stash

This command produces no output.

Update the Db2 configuration to use this new keystore file.

$ db2 update dbm cfg using KEYSTORE_LOCATION  \
/database/config/db2inst1/sqllib/security/ne-keystore.p12

Example output:

DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.
SQL1362W  One or more of the parameters submitted for immediate modification
were not changed dynamically. Client changes will not be effective until the
next time the application is started or the TERMINATE command has been issued.
Server changes will not be effective until the next DB2START command.

Update the Db2 configuration for the keystore type.

$ db2 update dbm cfg using KEYSTORE_TYPE PKCS12

Example output:

DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.
SQL1362W  One or more of the parameters submitted for immediate modification
were not changed dynamically. Client changes will not be effective until the
next time the application is started or the TERMINATE command has been issued.
Server changes will not be effective until the next DB2START command.

Verify your configuration updates.

$ db2 get dbm cfg | grep -i keystore
Keystore type                           (KEYSTORE_TYPE) = PKCS12
Keystore location                   (KEYSTORE_LOCATION) = /database/config/db2inst1/sqllib/security/ne-keystore.p12

After verifying the configuration is correct, you must stop and start Db2 so that the changes take effect.
Stop Db2.
```
$ db2stop
12/11/2025 19:15:12     0   0   SQL1064N  DB2STOP processing was successful.
SQL1064N  DB2STOP processing was successful
```
Note
If you notice the message "The database manager was not stopped because databases are still active." after this step, wait a moment and try the db2stop command again.
Start Db2.
```
$ db2start
12/11/2025 19:15:37     0   0   SQL1063N  DB2START processing was successful.
SQL1063N  DB2START processing was successful.
```

Db2 now uses the local keystore for encryption operations.

Simulate updating an existing database

To continue the scenario, create a new database named uat25a that can use the local keystore you created earlier.

In this scenario, the uadt25a database serves as an example of an unencrypted database that you can update first to use the local keystore, and then later to use centralized key management with Vault.

The following workflow steps simulate updating an existing database to use encryption through back up and restoration.

Create a new database named uat25a.
```
$ db2 create database uat25a
```
Long running operation
Database creation can take a minute or more to complete depending on your Docker Desktop settings, and the available resources on your host computer.
Example output:
```
DB20000I  The CREATE DATABASE command completed successfully.
```
Create a backup of the uat25a database so that you can drop it and import it into a new database with encryption enabled and supported by the local keystore.
```
$ db2 backup database uat25a
Backup successful. The timestamp for this backup image is : 20251211191817
```
Drop the database so that you can then restore the backup into a new database with encryption enabled by default.
```
$ db2 drop database uat25a
DB20000I  The DROP DATABASE command completed successfully.
```
Restore the database backup into the new database uat25b, and activate encryption on the database.
```
$ db2 restore database uat25a into uat25b encrypt
DB20000I  The RESTORE DATABASE command completed successfully.
```
Tip
If you notice an error here like: 'SQL1728N The command or operation failed because the keystore could not be accessed. Reason code "1"', then you might have skipped stopping and starting Db2. Be sure to use db2stop and db2start before trying to use the new local keystore.

Connect to the uat25b database.

$ db2 connect to uat25b

  Database Connection Information

Database server        = DB2/LINUXX8664 12.1.2.0
SQL authorization ID   = DB2INST1
Local database alias   = UAT25B

Get the database encryption information to confirm that the local keystore encrypts the uat25b database.

$ db2pd -encryptioninfo -db uat25b

Database Member 0 -- Database UAT25B -- Active -- Up 0 days 00:00:32 -- Date 2025-12-11-19.19.41.003658

Encryption Info:
   Object Name:               UAT25B
   Object Type:               DATABASE
   Encyrption Key Info:
          Encryption Algorithm: AES
     Encryption Algorithm Mode: CBC
         Encryption Key Length: 256
              Master Key Label: DB2_SYSGEN_db2inst1_UAT25B_2025-12-11-19.18.46_05A9AD8E
 Master Key Rotation Timestamp: 2025-12-11-19.18.46.000000
   Master Key Rotation Appl ID: *LOCAL.DB2.251211191607
   Master Key Rotation Auth ID: DB2INST1
     Previous Master Key Label: DB2_SYSGEN_db2inst1_UAT25B_2025-12-11-19.18.46_05A9AD8E
   KeyStore Info:
                 KeyStore Type: PKCS12
             KeyStore Location: /database/config/db2inst1/sqllib/security/ne-keystore.p12
            KeyStore Host Name: db2
                 KeyStore Port: 0
           KeyStore IP Address: 172.42.0.20
      KeyStore IP Address Type: IPV4

Enable centralized KMIP keystore on database

Your next goal is to configure the uat25b database to use the Vault KMIP secrets engine for its keystore instead of the local keystore you just enabled.

Quiet commands ahead

Commands 2-4 do not produce any output.

Prepare for this workflow by creating a KMIP configuration file:

$ cat > /database/config/db2inst1/sqllib/security/kmip.cfg << EOF
VERSION=1
PRODUCT_NAME=OTHER
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=TRUE
ALLOW_NONCRITICAL_BASIC_CONSTRAINT=TRUE
SSL_KEYDB=/database/config/db2inst1/vault_kmip.p12
SSL_KEYDB_STASH=/database/config/db2inst1/vault_kmip.sth
SSL_KMIP_CLIENT_CERTIFICATE_LABEL=db2_client
PRIMARY_SERVER_HOST=172.42.0.10
PRIMARY_SERVER_KMIP_PORT=5696
EOF

Create a centralized KMIP keystore, and import the trusted root certificates and the client certificate including the private key issued by the KMIP secrets engine.

Create the new keystore.

$ gsk8capicmd_64 \
    -keydb \
    -create \
    -db "vault_kmip.p12" \
    -pw @another_Pa55word \
    -type pkcs12 \
    -stash

Import the KMIP CA certificate generated by the Vault KMIP secrets engine into the new keystore.

$ gsk8capicmd_64 \
    -cert \
    -add \
    -db "vault_kmip.p12" \
    -stashed \
    -file "/database/vault-kmip-ca.pem" \
    -trust enable

Import the client certificate and key generated by the Vault KMIP secrets engine into the new keystore.

$ gsk8capicmd_64 \
    -cert \
    -add \
    -db "vault_kmip.p12" \
    -stashed \
    -file "/database/vault-kmip-client.pem"

List the newly created keystore certificate details.

$ gsk8capicmd_64 \
    -cert \
    -list \
    -db "vault_kmip.p12" \
    -stashed

Example output:

* default, - personal, ! trusted, # secret key
!       CN=vault-kmip-default
!       CN=vault-kmip-default-intermediate
-       CN=jV2sQ,OU=mtgHI

The last line in this output holds some dynamically generated CN and OU values which you need for relabeling the certificate in the next step.

Capture the CN and OU values to the environment variable PERSONAL_LABEL.

$ PERSONAL_LABEL=$(gsk8capicmd_64 \
    -cert \
    -list personal \
    -db "vault_kmip.p12" \
    -stashed \
    | tail -n 1 \
    | cut -c 3-26)

This command produces no output.

Rename the label for the client certificate to db2_client.

$ gsk8capicmd_64 \
    -cert \
    -rename \
    -db "vault_kmip.p12" \
    -stashed \
    -label $PERSONAL_LABEL \
    -new_label db2_client

This command produces no output.

Confirm the client certificate label updates.

$ gsk8capicmd_64 \
    -cert \
    -list \
    -db "vault_kmip.p12" \
    -stashed

Example output:

* default, - personal, ! trusted, # secret key
!       CN=vault-kmip-default
!       CN=vault-kmip-default-intermediate
-       db2_client

Validate the KMIP keystore content; the result must be OK for each element in the keystore.

$ gsk8capicmd_64 \
    -cert \
    -validate \
    -db "vault_kmip.p12" \
    -stashed

Example output:

CN=vault-kmip-default : OK
CN=vault-kmip-default-intermediate : OK
db2_client : OK

Configure Db2 to use the centralized KMIP keystore file location.

$ db2 update dbm cfg using keystore_location \
    /database/config/db2inst1/sqllib/security/kmip.cfg

Example output:

DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.

Configure the centralized KMIP keystore type.

$ db2 update dbm cfg using keystore_type kmip
DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed
successfully.

Confirm the configuration update.

$ db2 get dbm cfg | grep -i key
SSL server keydb file                   (SSL_SVR_KEYDB) =
SSL client keydb file                  (SSL_CLNT_KEYDB) =
Keystore type                           (KEYSTORE_TYPE) = KMIP
Keystore location                   (KEYSTORE_LOCATION) = /database/config/db2inst1/sqllib/security/kmip.cfg

Migrate database to centralized KMIP keystore

Your next step is to migrate the local keystore to a centralized KMIP keystore, and then validate the migration. You need to stop and start Db2 to effect the keystore changes first.

Disconnect from the uat25b database.

$ db2 disconnect uat25b
DB20000I  The SQL DISCONNECT command completed successfully.

Stop Db2.

$ db2stop
12/11/2025 19:32:07     0   0   SQL1064N  DB2STOP processing was successful.
SQL1064N  DB2STOP processing was successful.

Start Db2.

$ db2start
12/11/2025 19:32:27     0   0   SQL1063N  DB2START processing was successful.
SQL1063N  DB2START processing was successful.

Migrate the local keystore to the Vault KMIP keystore.

$ db2p12tokmip \
    -from /database/config/db2inst1/sqllib/security/ne-keystore.p12 \
    -to /database/config/db2inst1/sqllib/security/kmip.cfg

Example output:

Migrating keys from </database/config/db2inst1/sqllib/security/ne-keystore.p12> local keystore
to external KMIP keystore at <172.42.0.10:5696>
using configuration file </database/config/db2inst1/sqllib/security/kmip.cfg>.

Migrating key: <DB2_SYSGEN_db2inst1_UAT25B_2025-12-11-21.03.12_CB49A193> ... Successful.

Out of 1 key(s): 1 key(s) inserted successfully, 0 failed.

The last line of output from this command shows that 1 key gets inserted, and 0 keys fail, representing a good migration.

Validate the configuration migration

As basic validation that Db2 can use the centralized KMIP keystore you can deactivate and activate the uat25b database.

Deactivate the database.

$ db2 deactivate db uat25b
DB20000I  The DEACTIVATE DATABASE command completed successfully.

Activate the database.

$ db2 activate db uat25b

If the activation happens without error, then Db2 is now using Vault's KMIP secrets engine for the keystore.

Tip

If you notice an error like: "SQL1781N An error occurred while parsing the configuration file." check the Troubleshooting section to learn about the cause and resolution.

This step also fails on Vault Enterprise version 1.12.2 and earlier, as earlier Vault versions do not feature the KMIP secrets engine.

Create and encrypt a new database

Here is a basic workflow for creating a new database and encrypting it with the centralized Vault KMIP secrets engine based keystore.

Create a new database named uat25e and enable encryption.
Long running operation
Database creation can take a minute or more to complete depending on your Docker Desktop settings, and the available resources on your host computer.
```
$ db2 create db uat25e encrypt
DB20000I  The CREATE DATABASE command completed successfully.
```

Connect to the uat25e database.

$ db2 connect to uat25e

  Database Connection Information

Database server        = DB2/LINUXX8664 12.1.2.0
SQL authorization ID   = DB2INST1
Local database alias   = UAT25E

Get the database encryption information to confirm that the local keystore encrypts the uat25e database.

$ db2pd -encryptioninfo -db uat25e

Database Member 0 -- Database UAT25E -- Active -- Up 0 days 00:00:23 -- Date 2025-12-11-21.50.02.667840

Encryption Info:
  Object Name:               UAT25E
  Object Type:               DATABASE
  Encyrption Key Info:
          Encryption Algorithm: AES
    Encryption Algorithm Mode: CBC
        Encryption Key Length: 256
              Master Key Label: DB2_SYSGEN_db2inst1_UAT25E_2025-12-11-21.47.16_21621B5B
Master Key Rotation Timestamp: 2025-12-11-21.47.16.000000
  Master Key Rotation Appl ID: *LOCAL.db2inst1.251211214716
  Master Key Rotation Auth ID: DB2INST1
    Previous Master Key Label: DB2_SYSGEN_db2inst1_UAT25E_2025-12-11-21.47.16_21621B5B
  KeyStore Info:
                KeyStore Type: KMIP
            KeyStore Location: /database/config/db2inst1/sqllib/security/kmip.cfg
            KeyStore Host Name: 172.42.0.10
                KeyStore Port: 5696
          KeyStore IP Address:
      KeyStore IP Address Type: Unknown IP Type

While still connected to the uat25e database, you can also try some extra operations, like encrypting the database log files, and generating a new key to store in Vault.

Encrypt log files

Follow this workflow to encrypt database logs and archive an encrypted log.

Update the database configuration to change the primary log archive method and enable log retention.

$ db2 update db cfg using LOGARCHMETH1 LOGRETAIN
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
SQL1363W  One or more of the parameters submitted for immediate modification
were not changed dynamically. For these configuration parameters, the database
must be shutdown and reactivated before the configuration parameter changes
become effective.

Force local or remote users or applications off the system to allow for maintenance.

$ db2 force application all
DB20000I  The FORCE APPLICATION command completed successfully.
DB21024I  This command is asynchronous and may not be effective immediately.

Stop the database.

$ db2stop
12/12/2025 18:50:22     0   0   SQL1064N  DB2STOP processing was successful.
SQL1064N  DB2STOP processing was successful.

Start the database.

$ db2start
12/12/2025 18:50:34     0   0   SQL1063N  DB2START processing was successful.
SQL1063N  DB2START processing was successful.

Back up the database.

$ db2 backup database uat25e
 Backup successful. The timestamp for this backup image is : 20251212185040

Archive the log.

$ db2 archive log for db uat25e
DB20000I  The ARCHIVE LOG command completed successfully.

You archived an encrypted log file. You can use the list history command to show the archive log.

$ db2 list history archive log all for uat25e
List History File for uat25e

Number of matching file entries = 1


Op Obj Timestamp+Sequence Type Dev Earliest Log Current Log  Backup ID
-- --- ------------------ ---- --- ------------ ------------ --------------
X  D  20251211185112      N                    S0000000.LOG
----------------------------------------------------------------------------

----------------------------------------------------------------------------
Comment: ARCHIVE LOG
Start Time: 20251211185112
End Time: 20251211185112
Status: A
----------------------------------------------------------------------------
EID: 2

Db2 outputs the archived log details.

Rotate the encryption key

When you need to rotate the encryption key stored in Vault, you can use sysproc.admin_rotate_master_key like this.

Connect to the database.
```
$ db2 connect to uat25e
```
Rotate the key.
```
$ db2 =>  call sysproc.admin_rotate_master_key
```
This command does not produce output.

Get the database encryption information to confirm that the local keystore encrypts the uat25e database.

$ db2pd -encryptioninfo -db uat25e

Database Member 0 -- Database UAT25E -- Active -- Up 0 days 00:11:33 -- Date 2025-12-12-19.03.20.807810

Encryption Info:
  Object Name:               UAT25E
  Object Type:               DATABASE
  Encyrption Key Info:
          Encryption Algorithm: AES
    Encryption Algorithm Mode: CBC
        Encryption Key Length: 256
              Master Key Label: DB2_SYSGEN_db2inst1_UAT25E_2025-12-12-18.47.56_E223313F
Master Key Rotation Timestamp: 2025-12-12-18.47.56.000000
  Master Key Rotation Appl ID: *LOCAL.db2inst1.251212184758
  Master Key Rotation Auth ID: DB2INST1
    Previous Master Key Label: DB2_SYSGEN_db2inst1_UAT25E_2025-12-12-18.47.56_E223313F
  KeyStore Info:
                KeyStore Type: KMIP
            KeyStore Location: /database/config/db2inst1/sqllib/security/kmip.cfg
            KeyStore Host Name: 172.42.0.10
                KeyStore Port: 5696
          KeyStore IP Address:
      KeyStore IP Address Type: Unknown IP Type

The Master Key Rotation Timestamp value reflects the point in time at which you rotated the key.

Monitor and troubleshoot the integration

If you run into trouble integrating the Vault KMIP secrets engine with Db2, you can enhance your troubleshooting efforts by enabling some helpful debug options, and use available tools to diagnose issue root causes.

Troubleshoot Vault

If you operate Vault on Linux with systemd, you can enable any or all debug options by adding these environment variables to /etc/vault.d/vault.env followed by a restart of the Vault service:

KMIP_CONNECTION_DEBUGGING=1 enables debug output for connectivity related operations.
KMIP_REQUEST_DEBUGGING=1 enables debug output for requests.
KMIP_RESPONSE_DEBUGGING=1 enables debug output for responses.
KMIP_DECODING_DEBUGGING=1 enables debug output for operations related to decoding messages.
KMIP_INDEX_DEBUGGING=1 enables debug output for message processing and indexing operations.
KMIP_DUMP_BYTE_VALUES=1 enables debug output containing raw byte values.

If your Vault deployment is not on a systemd based Linux, you can export the necessary environment variables in the process manager or shell that Vault starts from. Here are examples for every debug variable:

KMIP_CONNECTION_DEBUGGING=1
KMIP_REQUEST_DEBUGGING=1
KMIP_RESPONSE_DEBUGGING=1
KMIP_DECODING_DEBUGGING=1
KMIP_INDEX_DEBUGGING=1
KMIP_DUMP_BYTE_VALUES=1

Vault logs a greater amount of detail with the debug environment variables enabled, and this extra information can assist you with isolating an issue's root cause.

Troubleshoot Db2

If you run into to issues integrating Vault's KMIP secrets engine with Db2, you can troubleshoot Db2 with the db2diag command.

Get help for db2diag.

$ db2diag -h

Show all Severe level log entries.

$ db2diag -l severe

Get more example commands to try.

$ db2diag -h examples

Example errors and resolution tips

This table holds example errors, their potential root causes, and resolution tips which can help you when troubleshooting your Vault KMIP secrets engine and Db2 integration.

Error	Potential root cause	Resolution tips
SQL1781N An error occurred while parsing the configuration file. Configuration type: "KMIP". Reason code: "4".	A communication or certificate issue connecting to the Vault KMIP server. Reason Code 4 relates to protocol or certificate mismatch, or connectivity and unavailable listener.	Ensure the full path to your `kmip.cfg` file is correct.
ERROR: Failed to read the allow_key_insert_without_keystore_backup from the configuration file.	Incorrect paths in the kmip.cfg file	Double-check all paths in your `kmip.cfg` file.

Keystore availability

Keep in mind that the Vault server must be reachable by the Db2 server during operations that need keystore access.

The following are operations which require access to the Vault KMIP secrets engine keystore:

db2start
Create Database
Database start (for example, first connection to or activation of a database)
Transaction log file access (for example, upon first use)
Backup database
Restore database
Roll forward

Clean up

When you finish exploring the environment, you can stop the containers and remove all created artifacts.

Exit from the Db2 container by pressing CTRL + d.

In the same terminal session, stop all containers, and clean up their artifacts.

$ docker compose down
[+] down 6/6
✔ Container vault-setup                    Removed                                                                0.0s
✔ Container db2                            Removed                                                                0.9s
✔ Container vault                          Removed                                                                1.4s
✔ Container mkcert                         Removed                                                                0.0s
✔ Network learn-vault-kmip-db2_learn_vault Removed                                                                0.2s
✔ Network learn-vault-kmip-db2_default     Removed

Confirm that container cleanup.
```
$ docker ps -a
```

Help and reference

Vault as a KMIP server

HSM integration - seal wrap

This tutorial also appears in:

7 tutorials

Secrets management
Store, access, and deploy secrets for applications, systems, and infrastructure.
- Vault