Integration with CipherTrust Manager
This section lists the steps to integrate IBM DB2 with CipherTrust Manager.
Prerequisites
This section provides the prerequisites for integration of IBM Db2 with CipherTrust Manager.
Ensure that the CipherTrust Manager is installed and configured. For more details, refer to the CipherTrust Manager documentation.
Ensure that Db2 is installed and configured. For more details, refer to the IBM Documentation.
Db2 communicates with the CipherTrust Manager using the KMIP interface. Ensure that the KMIP interface is configured on CipherTrust Manager. Refer to CipherTrust Manager Administration Guide for details.
IP address of the CipherTrust Manager and port of the KMIP interface must be accessible from the Db2.
Ensure that the required licenses are activated. For more details, refer to the CipherTrust Manager documentation.
Configuration on CipherTrust Manager
To configure the CipherTrust Manager, you need to perform the following steps:
Creating a Domain (Optional)
Perform the following steps to be performed on CipherTrust Manager:
Navigate to Admin Settings > Domains.
Click Add Domain. The Add Domain page appears.
Specify the following information:
Name - Enter the domain name.
Admins - Select the admins (one or more) from the list available in the drop down. For example, admin.
Parent CA - Select parent CA as root CA.
Allow Subdomain User Management - Select this check box if you want to enable the sub-domain user management through this domain.
Click Save.
Switch to the newly created domain by clicking the top right on the current Domain Name.
Creating a User
To create a user, perform the following steps:
Log on to the CipherTrust Manager GUI.
Open the Keys & Access Management application.
On the left pane, click Users. The Users page is displayed.
On the Users page, click Create New User.
On the Create a New User screen provide the following details:
Enter Username.
Enter Password.
Click Create. The newly created user is listed on the Users page.
Note
To create a user in sub-domain, you must enable Allow Subdomain User management.
To create a user, perform the following steps:
Log on to the CipherTrust Manager GUI with the User you created within the sub-domain.
Open the Keys & Access Management application.
On the left pane, click Users. The Users page is displayed.
On the Users page, click Create New User.
On the Create a New User screen provide the following details:
Enter Username.
Enter Password.
Click Create. The newly created user is listed on the Users page.
Assigning User to a Group
Perform the following steps to add user to a group:
Click the ellipsis button (...) corresponding to the user that you created in the previous step.
Click Edit.
Click Group Memberships > Add Group.
In the search bar, enter the desired Group name and select the check box corresponding to it. For example, Key Admins or Key Users.
Click Add Group.
Creating or Adding a CA (Optional)
To create/add a Self-signed local CA, perform the following steps:
Navigate to CA > Local. Select Add Local CA, the Add Local CA page appears.
Provide the required information and click Add Local CA. The created Local CA will appear under Pending CAs section.
Click the ellipsis against the Local CA that you created and select the option Self-sign.
Select a valid duration for the Local CA. Click Save.
To add an external CA, perform the following steps:
Navigate to CA > External. Select Add External CA, the Add External Certificate page appears.
Provide the required information.
If you want to upload the external CA, select the File Upload option and click Upload Certificate. Browse and select the required External CA.
OR
Select Text and paste the contents of External Certificate
Click Add External CA.
Registering a KMIP Client
You can register a KMIP client on the CipherTrust Manager through:
Auto Registration
Manual Registration
Create a Registration Token using the following steps:
Log on to the CipherTrust Manager in root domain.
Go to Access Management > Registration Tokens.
Click Create New Registration Token.
Copy the
Registration Token
once it is created.Turn ON Auto Registration using the following steps:
Go to Admin Settings > Interfaces.
Click the ellipsis button (...) corresponding to the kmip interface.
Click Edit.
Under Configure KMIP window, select Auto Registration.
Paste the
Registration Token
.Select the mode as TLS, verify client cert, user name taken from client cert, auth request is optional.
Click Update.
Log on to the CipherTrust Manager.
Go to Products > KMIP.
Create Client Profile using the following steps:
Go to Client Profile and click Add Profile.
Add a Profile Name.
Select CN in Username Location in Certificate.
Click Certificate Details.
Paste the content of
client.csr
.Click Save.
Create Registration Token using the following steps:
Go to Registration Token and click New Registration Token > Begin.
Add a Name Prefix.
Specify a Token Lifetime value along with the Client Capacity for the token.
Click Select CA.
Select the CA type as Local/External depending on what you are using.
Select the appropriate CA from the dropdown menu and click Select Profile.
Select the Client Profile from the dropdown which you have created in the above step.
Click Create Token.
Copy the value of the Token created and click Done.
If you are using External CA then you can select the external CA that you created and uploaded on the CipherTrust Manager.
Go to Registered Clients and click Add Client.
Specify client name and paste the Registration Token generated in the above step.
If you are using external CA then you need to paste the signed client certificate in the Client Certificate field.
Click Save to save the client certificate.
You can register a KMIP client on the CipherTrust Manager through:
Auto Registration
Manual Registration
Create a Registration Token in the sub-domain using the following steps:
Log on to the CipherTrust Manager in your specified sub-domain.
Go to Access Management > Registration Tokens.
Click Add Registration Token > Begin.
Add a Name Prefix.
Specify a Token Lifetime value along with the Client Capacity for the token.
Copy the value of the Registration Token once it is created.
Switch to Root Domain.
Turn ON Auto Registration using the following steps:
Log on to the CipherTrust Manager in the root domain.
Go to Admin Settings > Interfaces.
Click the ellipsis button (...) corresponding to the kmip interface.
Click Edit.
Under Configure KMIP window, select Auto Registration.
Paste the
Registration Token
.Select the mode as TLS, verify client cert, user name taken from client cert, auth request is optional.
Click Update.
Log on to the CipherTrust Manager into your domain.
Go to Products > KMIP.
Create Client Profile using the following steps:
Go to Client Profile and click Add Profile.
Add a Profile Name.
Select CN in Username Location in Certificate.
Expand the Certificate Details section.
You can either paste the content of a generated client.csr or you can create one, by filling in the details.
For domain, the format to enter the Common Name field of the cert is always:
domainName||domainUser
Click Save.
Create a Registration Token using the following steps:
Go to Registration Token and click New Registration Token > Begin.
Add a Name Prefix.
Specify a Token Lifetime value along with the Client Capacity for the token.
Click Select CA.
Select the CA type as Local/External depending on what you are using.
Select the appropriate CA from the dropdown menu and click Select Profile.
Select the Client Profile from the dropdown which you have created in the above step.
Click Create Token.
Copy the value of the Token created and click Done.
If you are using External CA then you can select the external CA which you created earlier. Refer to External CA under Creating or Adding a CA.
Go to Registered Clients and click Add Client.
Specify client name and paste the Registration Token generated in the above step.
If you are using external CA then you need to paste the signed client certificate in the Client Certificate field.
Click Save to save the client certificate.
Configuring the KMIP Interface
The KMIP interface can be configured through:
Go to Admin Settings > Interfaces.
On the KMIP Interface, click the ellipsis button (...) and then click View/Edit.
Select the Auto Registration checkbox if you auto-registered your KMIP client and paste the value of the registration token that you created.
Note
By default, the Auto Registration is disabled.
Select the mode as TLS, verify client cert, user name taken from client cert, auth request is optional.
Specify selections for Local CA for Automatic Server Certificate Generation as desired.
Local CA for Automatic Server Certificate Generation should be set to Turn off auto generation from Local CA in case of External CA.
Select the CA according to your preference:
If you are using External CA then select the CA under External Trusted CAs
If you are using Local CA then select the CA under Local Trusted CAs
If you are using an External CA, expand the Upload Certificate section:
In the Certificate field, paste the contents of Server Certificate, CA, and Server Key file in the same order. Do not introduce any space or character or symbol between the contents of these files.
Select certificate Format as PEM.
Password field is optional and can be skipped.
Click Update.
Select the CA according to your preference.
Login to your sub-domain. Go to CA > Local. Click the ellipsis (...) and copy the contents of your CA Certificate.
Logout of your sub-domain and now login to the root domain.
Go to CA > External > Add External CA.
Enter a name for this Domain CA and select the text radio button and paste the certificate contents.
Click Add External CA.
Go to Admin Settings > Interfaces.
Click the Add icon to add the External CA.
Click Update.
Note
If you are using an External CA in the Sub-Domain, you need to add the CA as an External CA in both the root domain as well as the sub-domain and modify the interface accordingly.
Login to your sub-domain. Go to CA > Local. Click the ellipsis (...) and copy the contents of your CA Certificate.
Logout of your sub-domain and now login to the root domain.
Go to CA > External > Add External CA.
Enter a name for this Domain CA and select the text radio button and paste the certificate contents.
Click Add External CA.
Go to Admin Settings > Interfaces.
Click the Add icon to add the External CA.
Click Update.
On the KMIP interface, click the ellipsis (...) > Certificate Options > Upload New Certificate > Ok.
Select the Certificate Chain option and click Build Certificate Chain.
Click on Text and paste the contents of Server Certificate, CA, and Server Key file in the same order. Do not introduce any space, character or symbol between the contents of these files.
Select certificate Format as PEM.
Click on Upload Certificate.
On the KMIP Interface, click the ellipsis button (...) and then click View/Edit.
Select the Auto Registration checkbox if you auto-registered your KMIP client and paste the value of the registration token that you created.
Note
By default, the Auto Registration is disabled.
Select the mode as TLS, verify client cert, user name taken from client cert, auth request is optional.
Specify selections for Local CA for Automatic Server Certificate Generation as desired.
Local CA for Automatic Server Certificate Generation should be set to Turn off auto generation from Local CA in case of External CA.
Further, you need to configure the following:
Adding the CA Cert and Generating the CSR
You can download and add the CA cert in the local keystore for any of the following Certificate Authorities:
In the CipherTrust Manager, download the Local CA Cert (Certificate.pem).
Move the downloaded CA Cert to work folder that you created in DB2 Server.
Rename the
Certificate.pem
toca.crt
.mv <work_folder_location/Certificate.pem> <work_folder_location/ca.crt
For example: mv /opt/wallet/KMIP/Certificate.pem /opt/wallet/KMIP/ca.crt
Add the CA cert to the local keystore.
</home/<DB2 user instance>/sqllib/gskit/bin/gsk8capicmd_64 -cert -add -db <work_folder_location/local_keystore> -stashed -label <LABEL FOR CA CERTIFICATE> -file <CA CERTIFICATE FILE>
For Example: /home/db2user/sqllib/gskit/bin/gsk8capicmd_64 -cert -add -db "/opt/wallet/KMIP/clientkeydb.p12" -stashed -label "DB2_CA_CERT" -file "/opt/wallet/KMIP/ca.crt"
Generate the External CA using OpenSSL or any other CA generator.
Upload the CA on the CipherTrust Manager, using the following steps:
Go to CA > External.
On the CA page, click Add External CA.
Paste the contents of the
rootCACert.pem
and click Save.
Move the downloaded CA Cert to work folder that you created in DB2 Server.
Add the CA cert to the local keystore.
</home/<DB2 user instance>/sqllib/gskit/bin/gsk8capicmd_64 -cert -add -db <work_folder_location/local_keystore> -stashed -label <LABEL FOR CA CERTIFICATE> -file <CA CERTIFICATE FILE>
For Example: /home/db2user/sqllib/gskit/bin/gsk8capicmd_64 -cert -add -db "/opt/wallet/KMIP/clientkeydb.p12" -stashed -label "DB2_CA_CERT" -file "/opt/wallet/KMIP/ca.crt"
Generating the CSR for Client Certificate
After adding the CA cert to the local keystore, generate the Client Certificate request using the following steps:
In the DB2 server, generate the Client Certificate Request. Use the newly created user created on CipherTrust Manager (DB2_CLIENT_CERT
in this case) as reference while generating the CSR.
<DB2_HOME>/sqllib/gskit/bin/gsk8capicmd_64 -certreq -create -db < LOCAL KEYSTORE FILE> -stashed -label <LABEL FOR CLIENT CERTIFICATE> -dn <CLIENT CERTIFICATE DETAILS> -target <CLIENT CSR FILE> -size 2048 -sigalg SHA256
For Example: /home/db2user/sqllib/gskit/bin/gsk8capicmd_64 -certreq -create -db "/opt/wallet/KMIP/clientkeydb.p12" -stashed -label "DB2_CLIENT_CERT" -dn "CN=DB2_CLIENT_CERT, O=Gemalto, OU=PA, L=Noida, ST=UP, C=IN" -target "/opt/wallet/KMIP/client_cert_request.arm" -size 2048 -sigalg SHA256
Generating the CSR for Server Certificate
Note
Server certificate is required only when you are using External CA. You may skip this step if you are using the Local CA.
To create a server certificate, perform the following steps:
Create a server key using the following command.
openssl genrsa -out server.key 2048
Create a CSR for the server, using the above generated key.
openssl req -key server.key -new -sha256 -out server.csr -subj /O=my-org/OU=my-org/OU=server/CN=server
After generating the CSR (server.csr
in this case), create a server certificate using the following openssl command:
openssl x509 -req -days 7300 -in server.csr -CA rootCACert.pem -CAkey rootCAKey.pem -CAcreateserial -out server.cert -sha256
This Server key and Server certificate will be used in configuring the KMIP interface.
Generating the Client Certificate
Before generating the client certificate, ensure that you have registered the KMIP client.
Tip
To register the KMIP client, click [here](https://thalesdocs.com/ctp/ig/ibm/db2/db2-int-with-cm.md#registering-a-kmip-client.
You can generate the client certificate using any of the following two options:
Generate a registration token using the Local Root CA and the profile generated in the previous step.
Copy the registration token and go to Registered clients > Add client. Specify the client name and paste the registration token and click Save.
Download the resultant client certificate.
Move the downloaded client certificate in the working folder (/opt/wallet/KMIP) of DB2 server and rename it to client.crt.
After moving and renaming the client certificate as mentioned above, add the signed client certificate into local KeyStore. To do so, execute the following command:
/home/<db2 instance user>/sqllib/gskit/bin/gsk8capicmd_64 -cert -receive -db <LOCAL KEYSTOREFILE> -stashed -file <CLIENT CERTIFICATE>
For Example: /home/db2user/sqllib/gskit/bin/gsk8capicmd_64 -cert -receive -db "/opt/wallet/KMIP/clientkeydb.p12" -stashed -file "client.crt"
Copy the CSR generated previously.
On the CipherTrust Manager GUI perform the following steps:
Go to CA > Local , click on the Local CA present there.
Click on Upload CSR.
Add a specified name in Display name and paste the content of CSR in the CSR column and select Certificate Purpose as client.
Click on Issue Certificate and save the certificate.
Move the downloaded client certificate in the working folder (/opt/wallet/KMIP) of DB2 server and rename it to client.crt.
After moving and renaming the client certificate as mentioned above, add the signed client certificate into local KeyStore. To do so, execute the following command:
/home/<db2 instance user>/sqllib/gskit/bin/gsk8capicmd_64 -cert -receive -db <LOCAL KEYSTOREFILE> -stashed -file <CLIENT CERTIFICATE>
For Example: /home/db2user/sqllib/gskit/bin/gsk8capicmd_64 -cert -receive -db "/opt/wallet/KMIP/clientkeydb.p12" -stashed -file "client.crt".
Configuration on IBM DB2
Generating Master Encryption Key in the CipherTrust Manager
To generate the Master Encryption Key in the CipherTrust Manager, perform the following steps:
Create a centralized KeyStore.
To store a Master Encryption Key in CipherTrust Manager for a DB2 native encryption, you need to create a configuration file that contains all details about this centralized KeyStore i.e. the CipherTrust Manager.
In the work folder (/opt/wallet/KMIP) of the DB2 server, create kmip.cfg file with the following details:
VERSION=1 PRODUCT_NAME=KEYSECURE ALLOW_KEY_INSERT_WITHOUT_KEYSTORE_BACKUP=true SSL_KEYDB=/opt/wallet/KMIP/clientkeydb.p12 SSL_KEYDB_STASH=/opt/wallet/KMIP/clientkeydb.sth SSL_KMIP_CLIENT_CERTIFICATE_LABEL=DB2_CLIENT_CERT ALLOW_NONCRITICAL_BASIC_CONSTRAINT=false MASTER_SERVER_HOST=IP of CM MASTER_SERVER_KMIP_PORT=<port for KMIP interface> CLONE_SERVER_HOST= CLONE_SERVER_KMIP_PORT=
where:
SSL_KEYDB (Required): Absolute path and name of the local keystore file that holds the SSL certificates for communication between DB2 server and the CipherTrust Manager.
SSL_KEYDB_STASH (Optional): Absolute path and name of the stash file for the local keystore that hold the certificates for communication between DB2 server and the CipherTrust Manager.
SSL_KMIP_CLIENT_CERTIFICATE_LABEL (Required): The label of the SSL certificate for authenticating the client during communication with the CipherTrust Manager.
MASTER_SERVER_HOST is the CipherTrust Manager IP.
MASTER_SERVER_KMIP_PORT is the KMIP interface Port in the CipherTrust Manager.
Configure a DB2 instance to use CipherTrust Manager as centralized keystore.
Enter into DB2 command line using the db2 command with the DB2@instance user.
Update the keystore to point to our new config file kmip.cfg.
db2 => update dbm cfg using keystore_location <file path>/kmip.cfg db2 => update dbm cfg using keystore_type kmip
Stop and Start the database.
db2 => db2stop db2 => db2start
Creating an Encrypted Database
To create an encrypted database you need to add the parameter encrypt in the create database command.
db2 => create db <database_name> encrypt
For Example: db2 => create db myencdb encrypt
Note
In the above example, an encrypted database myencdb is created. This database is using the native encryption of DB2.
After executing the above command, a master encryption key is created in the CipherTrust Manager.