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.
The SSL communication will always be in FIPS mode.
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.
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.
To configure SSL support in a DB2 client:
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
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.
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
"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.
[sampledb]
Database=sampledb
Protocol=tcpip
Hostname=myhost
Servicename=50001
Security=ssl
SSLClientKeystoredb=/home/test1/keystore/clientstore.kdb
SSLClientKeystash=/home/test1/keystore/clientstore.sth
[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
<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
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
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