Configuring TLS Support in a non-Java Db2 client using a keystore

You can configure Db2 database clients, such as CLI, CLP, and .Net Data Provider clients, to support Transport Layer Security (TLS) for communication with the Db2 server.

About this task

This task shows you how to configure TLS support in a non-Java Db2® client by using the signing certificate only. For information on how to configure TLS support using the certificate file only, see Configuring TLS Support in a non-Java Db2 client using a certificate file.

Procedure

  1. Obtain the signing certificate for your Db2 server:
    • If the server certificate is self signed, obtain the certificate that was extracted for distribution to clients.
    • If the server certificate is signed by a 3rd party certificate authority (CA), obtain the CA's root certificate. This can be done by asking the CA, and is usually provided when signing the server certificate.
      Note: The root certificate must be used on the client when configuring TLS support for a CA-signed server certificate.
  2. On a computer where gsk8capicmd_64 is available, create a keystore from the server certificate.
    This can be done on the server computer, or a client computer where GSKit has been installed separately from the client. For more information, see Introduction to Global Security Kit installation. 
    gsk8capicmd_64 -keydb -create -db "client.p12" -pw "myClientPassw0rdpw0" -stash
    where -stash creates a stash file at the same path as the key database, with a file extension of .sth. At connect time, GSKit uses the stash file to obtain the password to the key database.
  3. Add the certificate to the client keystore: 
    gsk8capicmd_64 -cert -add -db "client.p12" -stashed -label "myServerCert" -file "server.pem" -format ascii
  4. Copy the key database and stash file to the client computer.
    Ensure that the client has the proper file permissions to read both the key database and the stash file. To configure your client application, set the appropriate connection string or configuration parameters, as shown in the applicable example for your client.

Example

Example 1: Connecting to a database from the CLP or Embedded SQL applications, using the Db2 catalogs:
First, catalog the node and database so that client applications can establish TLS connections to them:
catalog TCPIP NODE mynode  REMOTE  127.0.0.1  SERVER 50001  SECURITY SSL 
catalog DATABASE sample  AS myssldb  AT NODE mynode
Next, use the ssl_clnt_keydb and ssl_clnt_stash configuration parameters to specify the client key-database and the stash file. You set the ssl_clnt_keydb configuration parameter to the fully qualified path of the key database file (.p12) and the ssl_clnt_stash configuration parameter to the fully qualified path of the stash file:
db2 update dbm cfg using SSL_CLNT_KEYDB /home/db2inst1/client.p12 SSL_CLNT_STASH /home/db2inst1/client.sth

If either the ssl_clnt_keydb or ssl_clnt_stash configuration parameter is null (unset), the connection fails and returns error SQL10013N with token GSKit Error: GSKit_return_code.

Connect to the server from the CLP client: 
db2 connect to myssldb user user1 using password
You can also use the following statement to connect from an embedded SQL application: 
Strcpy(dbAlias,"myssldb"); EXEC SQL CONNECT TO :dbAlias USER :user USING :pswd;

Example 2: Connecting to a database from a CLI/ODBC application, using a connection string:

Use a connection string that contains the SECURITY=SSL, SSLClientKeystoredb, and SSLClientStash keywords to call the SQLDriverConnect function t. For example:
"Database=sampledb; Protocol=tcpip; Hostname= myhost; Servicename=50001; 
Security=ssl; SSLClientKeystoredb=/home/db2inst1/client.p12;
SSLClientKeystash=/home/db2inst1/client.sth;"

Example 3: Connecting to a database from a CLI/ODBC application, using a db2cli.ini configuration file:

Use the db2cli.ini file to set the needed connection parameters:
[sampledb]
Database=sampledb
Protocol=tcpip
Hostname=myhost
Servicename=50001
Security=ssl
SSLClientKeystoredb=/home/db2inst1/client.p12
SSLClientKeystash=/home/db2inst1/client.sth

Example 4: Connecting to a database from a CLI/ODBC application, using the SQLDriverConnect function (CLI):

Use the FileDSN CLI/ODBC keyword to identify a DSN file from which a connection string is built for connecting to the Db2 server. You specify the value of FileDSN in the connection string of the SQLDriverConnect function.

The following example shows how the DSN file might be written: 
[ODBC]
DRIVER=IBM DB2 ODBC DRIVER – DB2COPY1
UID=user1
AUTHENTICATION=SERVER
PORT=50001
HOSTNAME=myhost
PROTOCOL=TCPIP
DATABASE=SAMPLEDB
SECURITY=SSL 
SSLClientKeystoredb=/home/db2inst1/client.p12
SSLClientKeystash=/home/db2inst1/client.sth

Example 5: Connecting to a database from a CLI/ODBC application or embedded SQL application, using the db2dsdriver.cfg configuration file.

If you are running Db2 11.5.7 or later, you can include the SSLServerCertificate keyword in the db2dsdriver.cfg configuration file to connect from an embedded SQL application.

The following example shows how the db2dsdriver.cfg configuration file might be written:
<dsn alias="sample" host="myhost.ibm.com" name="sample" port="50001">
   <parameter name="SSLClientKeystoredb" value="/home/db2inst1/client.p12"/>
   <parameter name="SSLClientKeystash" value="/home/db2inst1/client.sth"/>
   <parameter name="SecurityTransportMode" value="SSL"/>
</dsn>