Using Fortanix Data Security Manager with IBM DB2

1.0 Introduction

This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with IBM Db2 Using KMIP.

It also contains the information that a user requires to:

• Configuration on IBM Db2

• Rotating Master Key in Fortanix DSM with Db2

IBM Db2® is a family of hybrid data management products offering a complete suite of AI-empowered capabilities designed to help you manage both structured and unstructured data on-premises as well as in private and public cloud environments. Db2 is built on an intelligent common SQL engine designed for scalability and flexibility.

2.0 Why use Fortanix Data Security Manager (DSM) with IBM DB2?

Db2® native encryption uses a two-tier approach to data encryption. Data is encrypted with a Data Encryption Key (DEK), which is in turn encrypted with a Master Key (MK). The encrypted DEK is stored with the data while the MK is stored in a keystore external to Db2.

Db2 native encryption ensures that the DEK is never exposed outside of the encrypted database, transaction log, or backup file. There are no interfaces provided to access the DEK in either its clear text or encrypted forms. As the MK is stored in a different location from the encrypted data, the chance of the encrypted DEK being concurrently exposed with the MK used to encrypt it is very unlikely. Since the risk of the DEK being exposed is extremely low, the need to rotate it is negligible. The rotation of the MK, which is used to protect the DEK, can be done efficiently without the need to decrypt and re-encrypt the data.

The Db2 database system supports SSL, which means that a Db2 client application that also supports SSL can connect to a Db2 database by using an SSL socket. CLI, CLP, and .Net Data Provider client applications and applications that use the IBM® Data Server Driver for JDBC and SQLJ (type 4 connections) support SSL.

3.0 Prerequisites

Ensure the following:

• Fortanix DSM

• IBM Db2 11.5 and higher

• Access to create a certificate for the KMIP Server

4.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

4.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

4.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

4.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

4.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 4.3: Creating a Group from the list.

3. Click the SAVE button to add the new application.

The new application has been added to the Fortanix DSM successfully.

4.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the app created in the Section 4.4: Creating an Application to go to the detailed view of the app.

2. From the top of the app’s page, copy the app UUID to be used in Section 5.4: Add Client Certificate and Key to SSL Keystore as the value of Common Name (CN) to generate the self-signed certificate and a private key.

4.6 Updating the Authentication Method

Perform the following steps to change the authentication method:

1. Go to the detailed view of the app created in Section 4.4: Creating an Application and click the Change authentication method button and select the Certificate option to change the authentication method to Certificate.

2. Click the SAVE button.

3. On the Add certificate dialog box, click the UPLOAD NEW CERTIFICATE button to upload the certificate file or paste the content of the certificate generated in Section 5.4: Add Client Certificate and Key to SSL Keystore.

4. Select both the check boxes to confirm your understanding about the action.

5. Click the UPDATE button to save the changes.

5.0 Configuration on IBM DB2

5.1 Create Folders for Certificates and Config File

Perform the following steps to create the folder for certificates and configuration files:

1. Log in to the IBM Db2 machine and log in as the DB user as shown in the following screenshot.  

   

2. Next, create folders so as to bifurcate the certificates and config file.

   1. KMIP (For config file)

   2. SDKMS_Certs (For all the certificates)

3. Create a self-signed certificate and make sure that you should have the app ID handy as we need to update the Common Name for the self-signed certificate.

   • Run the following command to change directory to SDKMS_Certs:

   openssl req -newkey rsa:2048 -nodes -keyout private.key -x509 -days 365 -out certificate.crt

   

   

4. Paste or upload the certificate that was generated in Step 3 above in the Upload Certificate text box in the Fortanix DSM user interface (UI) for app authentication and save the details.

5.2 Updating the Certificate in Fortanix DSM

Perform the following steps to update the certificate in the authentication method:

1. Make sure you change the configuration to KMIP from the default, which is, REST API.

2. Now import the private key and certificate into the SSL key store, you need to combine the private key and certificate into one.

   NOTE

   • The certificate should come first, followed by the private key. Combine them as follows.

   • We give this entry label which will be used in the KMIP configuration file. Make a note of the label.

   • Depending on where you are running this command from, tweak the path of the "sdkms.pem" file.

   cat certificate.crt private.key > sdkms.pem

   

3. Verify the private key matches the Certificate and CSR.

   openssl x509 -noout -modulus -in certificate.crt | openssl md5

5.3 Create the SDKMS-KMIP.P12 and Stashed File

Run the following command:

gsk8capicmd_64 -keydb -create -db "sdkms-kmip.p12" -pw "sdkms-kmip.pWd" -type pkcs12 -stash

In case you get an error that the gsk8capicmd_64 command is not found; you need to export the libraries for gsk8capicmd_64 from sqllib.

Linux Environments:

export LD_LIBRARY_PATH=$HOME/sqllib/lib64/gskit:$LIBPATH

export PATH=$HOME/sqllib/gskit/bin:$PATH

Re-run the above command to create .p12 and stash file. In the following screenshot sdkms-kmip.p12 and sdkms-kmip.sth file is created.

5.4 Add Client Certificate and Key to SSL Keystore

Perform the following steps to add the client certificate and key to the SSL keystore:

1. Run the following command to add client cert and key to the SSL keystore:

   gsk8capicmd_64 -cert -add -db "sdkms-kmip.p12" -stashed -label "sdkms_app_cert" -file "sdkms.pem"

2. Find the CA certificate from your Fortanix DSM installation and copy it into a file CA.pem. Please note that if your CA certificate has a chain then the complete chain including the DSM TLS cert must be copied into CA.pem file. You can get the complete chain from your Fortanix DSM browser by going to your Fortanix DSM URL and then viewing certificates and downloading the certificate chain.
   Since we are using "https://<fortanix_dsm_url>",  let us get the CA Certificate from the UI.

3. In the IBM shell, run the following command to create the CA.pem file:

   touch CA.pem

4. Perform vi on CA.pem and then paste the certificate information to give the following output. The CA.pem file will contain the following:

   • DSM cert

   • Intermediate CA cert (if available)

   • Root CA cert.  

     

5.5 Import CA Certificate into SSL Keystore

Run the following command to import CA Certificate into the SSL keystore:

gsk8capicmd_64 -cert -add -db "sdkms-kmip.p12" -stashed -label "trustedCA" -file CA.pem

5.6 List Certificate in the Keystore

Run the following command to list certificate in your keystore to verify everything is fine:

gsk8capicmd_64 -cert -list -db sdkms-kmip.p12 -stashed

Create a KMIP config file in the KMIP folder. In the following example, it is kmip.cfg:

---------------------------
VERSION=1
PRODUCT_NAME=OTHER
ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=true
SSL_KEYDB=/database/config/db2inst1/SDKMS_Certs/sdkms-kmip.p12
SSL_KEYDB_STASH=/database/config/db2inst1/SDKMS_Certs/sdkms-kmip.sth
SSL_KMIP_CLIENT_CERTIFICATE_LABEL=sdkms_app_cert
MASTER_SERVER_HOST=<fortanix_dsm_hostname>   					
MASTER_SERVER_KMIP_PORT=5696		
------------------------------	

5.7 Configure a DB2 Instance to Use a Keystore

Perform the following steps to configure the Db2 instance to use a keystore:

1. To configure a Db2 instance to use a keystore for native encryption, you need to set two database manager configuration parameters: keystore_type and keystore_location.

2. For a centralized keystore, where the key manager product uses the Key Management Interoperability Protocol (KMIP), set keystore_type to "KMIP", and set keystore_location to the absolute path and file name of the centralized keystore configuration file.

3. To do this, run the following command:

   db2 update dbm cfg using keystore_location /mnt/blumeta0/home/db2inst1/KMIP/kmip.cfg keystore_type kmip

   

4. To get the keystore changes to take effect, we need to restart the Db2 again.
   Run the following command to stop the Db2:

   db2stop

5. Run the following command to start the Db2:

   db2start

   

6. Run the following command to verify that the dbm cfg is set correctly. Look at value of Keystore type and keystore location.

   db2 get dbm cfg

   

5.8 Renewing the DB2-DSM App Certificate

Perform the following steps to renew the Db2-DSM app certificate:

1. Run the following command to renew the certificate using the existing private key:

   openssl req -key private.key -new -x509 -days 700 -out renewcertificate.crt

   

   

2. Go to the Fortanix DSM UI and update the app certificate. Paste or upload the new certificate that was generated in the previous step.  

   

3. Import the private key and certificate into the SSL key store. You must combine the private key and certificate into one.

   cat renewcertificate.crt private.key > sdkms.pem

4. Verify that the private key matches the Certificate and CSR.

   openssl x509 -noout -modulus -in certificate.crt | openssl md5
   openssl x509 -noout -modulus -in renewcertificate.crt | openssl md5

5. Remove the existing sdkms.pem entry from the current p12 file.

   gsk8capicmd_64 -cert -delete -db "sdkms-kmip.p12" -stashed -label "sdkms_app_cert"

6. Add client certificate and key to SSL Keystore.

   gsk8capicmd_64 -cert -add -db "sdkms-kmip.p12" -stashed -label "sdkms_app_cert" -file "sdkms.pem"

   NOTE

   The database should be able to communicate with Fortanix DSM using the new certificate. The db2stop and db2start commands may be needed to force the use of the new certificate.

7. Import the CA certificate into the SSL Keystore.

   1. Run the following command to delete the existing CA.pem from the p12 file:

      gsk8capicmd_64 -cert -delete -db "sdkms-kmip.p12" -stashed -label "trustedCA" -file CA.pem

   2. Download the latest CA certificate from the Fortanix DSM URL as described from Step 2 to 4 in Section 5.4: Add Client Cert and Key to SSL Keystore.

      gsk8capicmd_64 -cert -add -db "sdkms-kmip.p12" -stashed -label "trustedCA" -file CA.pem

   NOTE

   Importing a CA certificate is an optional step and is only needed if there is a change in the Fortanix DSM CA cert.

8. List the certificate in your keystore to verify if everything is fine.

   gsk8capicmd_64 -cert -list -db sdkms-kmip.p12 -stashed

5.9 Updating Certificate in IBM DB2 Keystore

Perform the following steps to update the certificate in IBM Db2 keystore:

1. Verify the certificate in the IBM Db2 Keystore.

   gsk8capicmd_64 -cert -list -db sdkms-kmip.p12 -stashed

   output:

   db2inst1@2407b7a6943b SDKMS_Certs]$ gsk8capicmd_64 -cert -
   list -db sdkms-kmip.p12 -stashed
   Certificates found
   * default, - personal, ! trusted, # secret key
   !       CN=
   !       "CN=R3,O=Let's Encrypt,C=US"
   !       trustedCA
   -       sdkms_app_cert
   [db2inst1@2407b7a6943b SDKMS_Certs]$

2. Generate a new CSR request.

   gsk8capicmd_64 -certreq -recreate -db sdkms-kmip.p12 -stashed -label "sdkms_app_cert" -target new_cert_request.csr

3. Sign: Send the resulting new_cert_request.csr to be signed by the original Certificate Authority (CA).

4. Receive: After the signed certificate has been returned (assuming you got it back as new_cert_signed.csr) then receive it back into your server keystore.

   gsk8capicmd_64 -cert -receive -db sdkms-kmip.p12 -stashed -file new_cert_signed.csr

5. Verify: Verify the new dates on the received certificate.

   gsk8capicmd_64 -cert -details -label "sdkms_app_cert" -db sdkms- kmip.p12 -stashed

6. Restart: For the new certificate to take effect, the Db2 server instance must be restarted.

   db2stop
   db2start

5.10 Create an Encrypted Database

Perform the following steps to create the encrypted database:

1. Run the following command to create an encrypted database:

   db2 create db mydb1 encrypt

   

2. Once you create the database you can find the Master key created in Fortanix DSM as shown below.

   

3. You can find the Activity logs in the Apps tab as below.

   

In case you are getting any error in your environment. Then you need to troubleshoot the certificate and network-related issue so that we can communicate to the Fortanix DSM.

6.0 Rotating Master Keys in Fortanix Data Security Manager with IBM DB2

Rotating your encryption keys is part of a complete security policy. And as with passwords, how often is a controversial topic. This article is intended to give you information to make an informed decision about how and when to rotate your encryption keys. The focus is the keys that protect your data at rest and do not discuss SSL certificates.

IBM Db2 native encryption uses a 2-tier approach to data encryption where the data is encrypted with a Data Encryption Key (DEK) and the DEK itself is encrypted with a Master Key (MK). The encrypted DEK is stored with the data while the MK is stored in a keystore external to Db2.

As the master key is stored outside of the database manager, the requirement and frequency to rotate the master key depend on the type of keystore in use and the protections provided by the keystore. A local keystore file is protected by a password and operating system file permissions, however, it is owned by the Db2 Instance Owner, which is often a shared service account. In such an environment policy to rotate the master key on a regular basis would be natural. On the other extreme, master keys protected by Hardware Security Modules (HSM) require much less rotation if at all. Master keys protected by an HSM never leave the secure confines of the hardware device and strong controls exist to prevent the key from being extracted. Master keys accessed from a KMIP server fall somewhere in the middle. Strong controls exist within the KMIP server to authorize who has access to the master keys and audit their usage. However, these servers are often deployed as software running on a traditional operating system and servers and are only as secure as the environment in which they are deployed. On the other hand, there are secure HSMs offering KMIP interfaces. A key rotation schedule would be suggested by the security hardening of the KMIP server and the environment in which it is deployed.

Db2 provides routine SYSPROC.ADMIN_ROTATE_MASTER_KEY() to rotate the database master key to a new value. This operation decrypts the database DEK and re-encrypts it with the new master key.

The 2-tier approach ensures that the key used to encrypt the data, the DEK, is never exposed outside of the encrypted database, transaction log, or backup and no interfaces exist within Db2 to access the DEK. Since the MK is stored in a different location from the encrypted data, this makes concurrent exposure of the encrypted data and the MK much less likely again reducing risk. Finally, since the DEK is not exposed, there is little reason to rotate it, and rotation of the MK used to protect the DEK, can be done efficiently without the need to decrypt and re-encrypt the data itself.

6.1 Rotating Keys in DB2

Perform the following steps to rotate the keys in Db2:

1. List your DB directory.

   db2 list db directory

   

2. Connect the DB to the same database.

   db2 connect to MYDB1

   

3. Run the following command to check the encryption information:

   db2 “select * from table(sysproc.admin_get_encryption_info())”

   

4. Now rotate the master key from Db2.

   db2 “CALL SYSPROC.ADMIN_ROTATE_MASTER_KEY (NULL)”

   

5. After the key is rotated, check on Fortanix DSM end if the Master Key is rotated.

   

   You will find a new key created in Fortanix DSM.

7.0 Backup and Restore Encrypted Database

Perform the following steps:

1. Run the following command to take backup of the database:

   db2 backup database mydb1

   Where mydb1 is the database that is encrypted with keys in Fortanix DSM.

2. Move the backup file generated to the destination server.

3. On the destination server, configure Fortanix DSM integration for the new Db2 instance as previously described until Section 5.7: Configure a DB2 Instance to Use a Keystore.

   1. This will be a new configuration with a new app.

      NOTE

      The app must be created under the same group as earlier.

4. Run the following command to restore the backup of the encrypted database mydb1.

   db2 restore db mydb1 encrypt

5. Verify that you can query the encrypted data in the restored database.

   db2 list db directory
   db2 connect to mydb1
   db2 "select * from <table_name>"

   You should now be able to connect to the database and select data from tables.

6. Run the following query to see the new master key used by the database.

   db2 "select * from table(sysproc.admin_get_encryption_info())"

7. Verify from the Fortanix DSM UI that the new Db2 Key from the previous step is seen under the group’s security objects.

8.0 Migrating from a Local Keystore to a Centralized KMIP Keystore

If you want to migrate your Db2 local keystore to a centralized keystore that is configured for the Key Management Interoperability Protocol (KMIP), you can copy your master keys to the centralized keystore by issuing the db2p12tokmip command.

8.1 Prerequisites

The following are the prerequisites:

• Create a KMIP keystore configuration file.

• Configure TLS between the Db2 instance and the centralized key manager.

8.2 Procedure

The following is the procedure to migrate from a local keystore to a centralized KMIP keystore:

1. Set up the centralized KMIP keystore.

2. Set the allow_key_insert_without_keystore_backup parameter to “TRUE” in the centralized KMIP keystore configuration file.

3. Copy all master keys from the local keystore to the centralized KMIP by issuing the db2p12tokmip command.

   

Example:

db2p12tokmip -from /home/test/keystores/ne-keystore.p12 -to /database/config/db2inst1/KMIP/kmip.cfg

In the above example, /home/test/keystores/ne-keystore.p12 is the .p12 file for the local keystore and /database/config/db2inst1/KMIP/kmip.cfg is the config file for the KMIP Keystore.