Configuring TLS support in non-Java Db2 clients

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

About this task

The TLS communication will always be in FIPS mode.

Note: You can configure Db2 11.5.6 and newer clients to validate the hostname of Db2 instances to which they are connecting, during a TLS handshake. For more information, see Configuring Db2 clients for hostname validation when negotiating a TLS connection.

From Db2 V10.5 FP5 and later, if the client is being installed on a separate computer and uses TLS to communicate with servers, ignore step 2 to step 4 of the following Procedure section. You can pass the TLS Certificate to these client drivers using the SSLServerCertificate keyword in the CLI connection string, db2cli.ini file, or db2dsdriver.cfg file. The client driver will create an internal key database and add the certificate to it. You do not need to modify any environment variable.

Procedure

To configure TLS support in a Db2 client:

  1. Obtain the signer certificate of the server digital certificate on the client. The server certificate can either be a self-signed certificate or a certificate signed by a certificate authority (CA).
    • If your server certificate is a self-signed certificate, you must extract its signer certificate to a file on the server computer and then distribute it to computers running clients that will be establishing TLS connections to that server. See Configuring TLS support in a Db2 instance for information about how to extract the certificate to a file.
    • If your server certificate is signed by a well known CA, your client key database might already contain the CA certificate that signed your server certificate. If it does not, you must obtain the CA certificate, which is usually done by visiting the website of the CA.
  2. On the Db2 server computer, use the GSKCapiCmd tool to create a key database.
    The GSKCapiCmd tool is a non-Java-based command-line tool (Java™ does not need to be installed on your system to use this tool).

    You invoke GSKCapiCmd using the gskcapicmd command, as described in the GSKCapiCmd User's Guide. The path for the command is sqllib/gskit/bin on Linux® and UNIX operating systems, and C:\Program Files\IBM\GSK8\bin on both 32-bit and 64-bit Windows operating systems. (On 64-bit operating systems, the 32-bit GSKit executable files and libraries are also present; in this case, the path for the command is C:\Program Files (x86)\IBM\GSK8\bin.)

    For example, the following command creates a key database called mydbclient.kdb and a stash file called mydbclient.sth:
    gsk8capicmd_64 -keydb -create -db "mydbclient.kdb" -pw "myClientPassw0rdpw0" 
          -stash

    The -stash option 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 signer certificate into the client key database
    For example, the following gsk8capicmd command imports the certificate from the file mydbserver.arm into the key database called mydbclient.kdb:
    gsk8capicmd_64 -cert -add -db "mydbclient.kdb" -pw "myClientPassw0rdpw0" 
          -label "dbselfsigned" -file "mydbserver.arm" -format ascii 
  4. Copy the key database and stash file to the client computer. Ensure the client has the proper file permissions to be able to read both the key database and the stash file.
  5. For your client application, set the appropriate connection string or configuration parameters, as shown in the applicable example for your client.

Example

CLP and embedded SQL clients

CLP clients and embedded SQL clients can connect to a database on a remote host that has been added to the node catalog using the CATALOG TCPIP NODE command. Issue the CATALOG TCPIP NODE command with the SECURITY keyword set to SSL to specify TLS for that connection.

The following example demonstrates how to catalog a node and database so that a CLP client can connect to them using a TLS connection.

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  AUTHENTICATION SERVER
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 (.kdb) 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/test1/sqllib/security/keystore/clientkey.kdb 
      SSL_CLNT_STASH /home/test1/sqllib/security/keystore/clientstore.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.

Then, connect to the server from the CLP client:
db2 connect to myssldb user user1 using password

Alternatively, an embedded SQL application could use the following statement to connect:

Strcpy(dbAlias,"myssldb");
 EXEC SQL CONNECT TO :dbAlias USER :user USING :pswd;
Attention:
With Db2 11.5.6 and newer versions, if you are connecting to a database over TLS through an application using embedded SQL, much of the process is now handled programmatically.
  • You no longer need to download and install the GSKit package separately to configure TLS
  • Your application no longer needs to utilize the GSKCapiCmd tool to create a key database or stash file
  • You application no longer needs to pass values for the SSLClientKeystoredb, SSLClientKeystoreDBPassword, or SSLClientKeyStash keywords in the db2dsdriver.cfg file.
The db2dsdriver.cfg file, however. must contain the following statement:
Security=SSL
Your embedded SQL application specifies the signer certificate of the server using the SSLServerCertificate keyword from the db2dsdriver.cfg file. The application also specifies the TLS port number. If the SSLServerCertificate keyword parameter is not specified but the Security keyword is specified, then the default Db2 Cloud certificate DigiCertGlobalRootCA.arm is added to the default key database created by the driver. The default Db2 Cloud certificate, located in your <DB2 client install directory>/cfg folder, allows a TLS connection to a Db2 pubic cloud offering, if attempted. For example, the mark-up of your db2dsdriver.cfg file might look similar to the following:
<dsn alias="sample" host="myhost.ibm.com" name="sample" port="50001">
 <parameter name="SSLServerCertificate" value="/work/mywork/DB2.CERTAUTH.CERTB64.arm"/>
<parameter name="SecurityTransportMode" value="SSL"/>
  </dsn>
From an embedded SQL application, you can use the sample database defined in the db2dsdriver.cfg file, by running the following command:
 EXEC SQL CONNECT TO :sample USER :user USING :pswd;
Note: In the db2dsdriver.cfg file, you can also specify your Security keyword in place of SecurityTransportMode.
CLI/ODBC client applications
Depending in which environment you are running your CLI application, you use either connection string parameters (SSLClientKeystoredb and SSLClientKeystash) or Db2 configuration parameters (ssl_clnt_keydb and ssl_clnt_stash) to specify the path for the client key database and for the stash file.
  • If you are using the IBM Data Server Driver for ODBC and CLI, you use connection string parameters, as shown in this example:
    Call SQLDriverConnect with a connection string that contains the SECURITY=SSL keyword. For example:
    "Database=sampledb; Protocol=tcpip; Hostname= myhost; Servicename=50001; 
    Security=ssl; SSLClientKeystoredb=/home/test1/keystore/clientstore.kdb;
    SSLClientKeystash=/home/test1/keystore/clientstore.sth;"

    In this case, because Security=ssl is specified, the SSLClientKeystoredb and SSLClientKeystash connection string parameters must be set, otherwise the connection will fail.

  • If you are using the IBM data server client or IBM Data Server Runtime Client, you can use either connection string parameters or Db2 configuration parameters to set the path for the client key database and for the stash file. If the SSLClientKeystoredb and SSLClientKeystash connection string parameters are set, they override any values set by the ssl_clnt_keydb or the ssl_clnt_stash configuration parameters.
    This example uses the db2cli.ini file to set connection string parameters:
    [sampledb]
    Database=sampledb
    Protocol=tcpip
    Hostname=myhost
    Servicename=50001
    Security=ssl
    SSLClientKeystoredb=/home/test1/keystore/clientstore.kdb
    SSLClientKeystash=/home/test1/keystore/clientstore.sth
    
    This example uses the FileDSN CLI/ODBC keyword to identify a DSN file that contains the database connectivity information, which sets the connection string parameters. For example, the DSN file may look like this:
    [ODBC]
    DRIVER=IBM DB2 ODBC DRIVER – DB2COPY1
    UID=user1
    AUTHENTICATION=SERVER
    PORT=50001
    HOSTNAME=myhost
    PROTOCOL=TCPIP
    DATABASE=SAMPLEDB
    SECURITY=SSL
    SSLClientKeystoredb=/home/test1/keystore/clientstore.kdb
    SSLClientKeystash=/home/test1/keystore/clientstore.sth
    

    In these cases, because Security=ssl is specified, if the SSLClientKeystoredb and SSLClientKeystash connection string parameters are not set, and also the ssl_clnt_keydb and ssl_clnt_stash configuration parameters are not set, the connection will fail.

From Db2 V10.5 FP5 onwards, the SSLClientKeystoredb and SSLClientKeystash keywords are not needed in the connection string, db2cli.ini file, FileDSN, or db2dsdriver.cfg file. If you have not set or passed values for the SSLClientKeystoreddb and SSLClientKeystash keywords, the CLI/ODBC client driver will create a default key database internally during the first SSL connection. The Client driver will call GSKit API's to create a key database populated with the default root certificates. If the application has passed the signer certificate of the server (*.arm file)using the SSLServerCertificate keyword, the client driver will add this certificate to this default key database and proceed for the SSL connection. In this case, the application needs to use the Security=SSL and SSLServerCertificate=<certificate file name> as in below connection string.
 "Database=sampledb;Protocol=tcpip;Hostname=myhost;Servicename=50001;Security=ssl;SSLServerCertificate=server.arm;"

If both SSLClientKeystoredb and SSLServerCertificate keywords are used, the client driver will add the certificate file to the key database which the SSLClientKeystoredb points to and then proceed for SSL connection.

Certificate-based authentication
Note: Certificate-based authentication is only available for connections with a Db2 for z/OS® server.

The certificate-based authentication allows you to use SSL client authentication without the need of providing database passwords on the database client. When certificate-based authentication is configured to supply authentication information, a password cannot be specified in any other way (as in the db2dsdriver.cfg configuration file, in the db2cli.ini configuration file, or in the connection string). Since the authentication parameter needs a label to be specified, a new data server driver configuration parameter SSLClientLabel is also introduced. If the CERTIFICATE authentication is specified, then the new label parameter SSLCLientLabel must also be specified in the CLI configuration file, db2cli.ini, or in the data server driver configuration file, db2dsdriver.cfg.

The SSLClientKeyStoreDBPassword keyword sets the keystore database password. The configuration parameters SSLClientKeystash and SSLClientKeyStoreDBPassword are mutually exclusive. When the SSLClientKeystash configuration parameter and the SSLClientKeyStoreDBPassword configuration parameter are both specified in either the CLI configuration file or the data server driver configuration file, error CLI0220E is returned. Hence, for a successful certificate-based authentication, it is recommended to specify only one of the keywords but not both.

An example of the IBM data server driver configuration file (db2dsdriver.cfg) entry follows:
<parameter name="Authentication" value="CERTIFICATE"/>
Db2 .Net Data Provider applications
A Db2 .Net Data Provider application can establish an SSL connection to a database by specifying the path for the client key database and for the stash file by defining the connection string parameters, SSLClientKeystoredb and SSLClientKeystash. The connection string must also contain Security=SSL. For example:
String connectString = "Server=myhost:50001;Database=sampledb;Security=ssl;
SSLClientKeystoredb=/home/test1/keystore/clientstore.kdb;
SSLClientKeystash=/home/test1/keystore/clientstore.sth";
Then, as shown in the following C# code fragment, to connect to a database, pass this connectString to the DB2Connection constructor and use the Open method of the DB2Connection object to connect to the database identified in connectString:
DB2Connection conn = new DB2Connection(connectString);
Conn.Open();
Return conn;

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

From Db2 V10.5FP5 onwards, you do not need to use the SSLClientKeystoredb and SSLClientKeystash keywords in the SSL connection. However, the connection string must also contain Security=SSL. The connection string can be used as below:
 String connectString = "Server=myhost:50001;Database=sampledb;Security=ssl;SSLServerCertificate=server.arm;";
Notes:
  • When a self-signed client certificate created in a keystore database is extracted, the extract command extracts the public key data from the keystore database and places it into an identified file. However, no information that is related to the private key is extracted. If such a certificate is imported into another keystore database, only the public key data is imported and the private key data is not present in the new keystore database. So, an authentication of a client using the new keystore database fails. As a solution, either the entire keystore database needs to be shared by various applications or different client certificates need to be generated for each client.