DB2 Version 9.7 for Linux, UNIX, and Windows

Configuring Secure Sockets Layer (SSL) support in non-Java DB2 clients

You can configure DB2® database clients, such as CLI, CLP, and .Net Data Provider clients, to support Secure Sockets Layer (SSL) for communication with the DB2 server.

About this task

The SSL communication will always be in FIPS mode.

Before you begin

Note: If your Version 9.7 DB2 client or DB2 Connect™ server establishes an SSL connection to a DB2 for z/OS® server on a z/OS V1.8, V1.9, or V1.10 system, the appropriate PTF for APAR PK72201 must be applied to the Communication Server for z/OS IP Services.

Note: Due to an incompatibility between GSKit version 8 and GSKit 7d versions prior to 7.0.4.20, CLI applications connecting to an IDS data server using GSKit 7d versions prior to 7.0.4.20 will fail. To correct the problem, upgrade the GSKit library on the IDS data server to GSKit 7.0.4.20 or later

Before configuring SSL support for a client, perform the following steps:

If both the client and the server are on the same physical computer, you do not need to install GSKit, because GSKit is automatically installed with the DB2 server.

Starting with Version 9.7 Fix Pack 1, when you install the 64-bit version of the DB2 server, the 32-bit GSKit libraries are automatically included in the installation. To use these libraries, on Linux and UNIX operating systems you must ensure that the LD_LIBRARY_PATH, LIBPATH, or SHLIB_PATH environment variable is correctly set. On Windows operating systems, ensure that the PATH environment variable is correctly set, as shown in the following table.

Application	Operating system	Location of GSKit libraries	Environment variable setting
32-bit	Linux and UNIX 64-bit	`$INSTHOME`/sqllib/lib32	Include `$INSTHOME`/sqllib/lib32 in the `LD_LIBRARY_PATH`, `LIBPATH`, or `SHLIB_PATH` environment variable
64-bit	Linux and UNIX 64-bit	`$INSTHOME`/sqllib/lib64	Include `$INSTHOME`/sqllib/lib64 in the `LD_LIBRARY_PATH`, `LIBPATH`, or `SHLIB_PATH` environment variable
32-bit	Windows 64-bit	C:\Program Files (x86)\IBM\GSK8\lib	Include C:\Program Files (x86)\IBM\GSK8\lib in `PATH` environment variable
64-bit	Windows 64-bit	C:\Program Files\IBM\GSK8\lib64	Include C:\Program Files\IBM\GSK8\lib64 in `PATH` environment variable

SSL communication will always be in FIPS mode.

On non-Windows platforms, the DB2 database manager installs GSKit locally, and for a given instance, the GSKit libraries would be located in sqllib/lib or sqllib/lib64. It is unnecessary to have another copy of GSKit installed in a global location. If a global copy of GSKit does exist, keep the version of the global GSKit at the same or a higher version than the local GSKit.

If the client is being installed in a separate computer, for "C" based clients, you must install GSKit if the clients use SSL to communicate with the servers. You can install the GSKit libraries from the IBM DB2 Support Files for SSL Functionality DVD. Alternatively, you can install from an image that you downloaded from Passport Advantage®.
- Ensure that the path to the IBM® Global Security Kit (GSKit) libraries appears in the PATH environment variable on Windows and in the LIBPATH, SHLIB_PATH or LD_LIBRARY_PATH environment variables on Linux and UNIX. For example, on Windows, add the GSKit bin and lib directories to the PATH environment variable:
```
set PATH="C:\Program Files\ibm\gsk8\bin";%PATH%
set PATH="C:\Program Files\ibm\gsk8\lib";%PATH% 
```

Documentation for the GSKit tool: GSKCapiCmd

For information about the GSKit tool GSKCapiCmd, see the GSKCapiCmd User's Guide, available at ftp://ftp.software.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_CapiCmd_UserGuide.pdf.

Procedure

To configure SSL support in a DB2 client:

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 SSL connections to that server. See Configuring Secure Sockets Layer (SSL) 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 web-site of the CA.
On the DB2 client computer, use the GSKCapiCmd tool to create a key database, of CMS type. 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 platforms, 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 "mydbclientpw0" 
     -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.
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 "mydbclientpw0" 
      -label "dbselfsigned" -file "mydbserver.arm" -format ascii -fips
```
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 SSL for that connection.

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

First, catalog the node and database so that client applications can establish SSL 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 SQL30081N.

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;

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.

Certificate-based authentication

Starting in DB2 Version 9.7 Fix Pack 6, CERTIFICATE authentication has been introduced in the db2dsdriver.cfg authentication parameter.

<parameter name="Authentication" value="CERTIFICATE | SERVER | SERVER_ENCRYPT | 
			SERVER_ENCRYPT_AES | DATA_ENCRYPT | KERBEROS | GSSPLUGIN"/>

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 CERTIFICATE 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.

Starting in DB2 Version 9.7 Fix Pack 6, a new keyword SSLClientKeyStoreDBPassword is also introduced to set the password for the keystore db specified through SSLClientKeystoredb keyword. 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.

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 SQL30081N.

Examples of working with certificates in the client key database

The following example demonstrates how to display the certificate that was added to the client key database:

gsk8capicmd_64 -cert -details -db "mydbclient.kdb" -pw "mydbclientpw0" 
   -label "myselfsigned"

The output would display as follows:

label : myselfsigned
key size : 1024
version : X509 V3
serial : 96c2db8fa769a09d
issuer : cn=myhost.mycompany.com, ou=myOrganizationUnit, o =myOrganization, 
   l =myLocation, st =Ontario, c =CA
subject : cn=myhost.mycompany.com, ou=myOrganizationUnit, o =myOrganization, 
   l =myLocation, st =Ontario, c =CA
not before : Tuesday, 24 February 2009 17:11:50 PM
not after : Thursday, 25 February 2010 17:11:50 PM
public Key   
    30 81 9F 30 0D 06 09 2A 86 48 86 F7 0D 01 01 01
    05 00 03 81 8D 00 30 81 89 02 81 81 00 B6 B8 DC
    79 69 62 C9 A5 C1 5C 38 31 53 AB 27 BE 63 C0 DB
    DE C6 BC 2E A4 0D 37 45 95 22 0E 83 32 FE 67 A9
    2F D7 51 FF 40 A3 76 68 B9 E3 34 CB 7D 4A D8 38
    CA B1 6B 32 66 74 8F E2 B8 DA 8F D0 F3 62 04 BE
    C4 FE 80 2A D0 FF 27 72 37 9A 36 1D DB D3 A1 33
    A1 A6 48 33 E9 64 B9 9B 6B DB 08 60 7D 5E 0E 20
    0A 26 AA 62 3A DF D3 78 56 DC 15 DE 9F 0B 91 DD
    3B 1B 2B E2 82 FA 24 FF 81 A3 F7 3F C1 02 03 01
    00 01
public key type : RSA : 1.2.840.113549.1.1.1
finger print : SHA1 :    
    2D C1 93 F8 AC A0 8F E2 C2 05 D8 23 D7 5D 87 E6
    82 3C 47 EC
signature algorithm : SHA1WithRSASignature : 1.2.840.113549.1.1.5
value   
    0E 80 24 98 F6 6E 89 43 76 57 76 7F 82 95 18 6A
    43 A5 81 EC F4 82 1F 1F F2 3F E5 61 67 48 C0 59
    94 17 8E 8F DE 4F 7C 35 0C 5D A7 98 73 2A 34 7D
    1E BA 53 78 A5 E4 31 45 D1 08 86 BE 5E 57 C6 9D
    B5 E7 A7 01 3F 54 01 5E 8F 8B 2F 66 19 24 1E A4
    94 58 B0 D4 40 95 AB 98 C2 EF 1C 5C 4A 29 48 EC
    8C C0 A2 B1 AC 2A E9 3C 14 E5 77 B2 A6 55 A8 21
    CB 59 81 86 79 F0 46 35 F8 FC 99 2D EC D4 B9 EB
Trusted : enabled

To add the trial Root Certificate into mydbclient.kdb, issue the following command:

gsk8capicmd_64 -cert -add -db "mydbclient.kdb" -pw "mydbclientpw0" 
   -label "TrialRootCert" -file RootCert.arm

To list all the certificates in mydbclient.kdb, issue the following command:

gsk8capicmd_64 -cert -list all -db "mydbclient.kdb" -pw "mydbclientpw0"   

certificates found
* default, - personal, ! trusted
!       TrialRootCert
!       myselfsigned