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.
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 before 7.0.4.20, CLI applications connecting to an IDS data server using
GSKit 7d versions before 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/gskit |
Include $INSTHOME/sqllib/lib32/gskit
in the LD_LIBRARY_PATH, LIBPATH, or
SHLIB_PATH environment variable |
64-bit |
Linux and UNIX 64-bit |
$INSTHOME/sqllib/lib64/gskit |
Include $INSTHOME/sqllib/lib64/gskit
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/gskit or sqllib/lib64/gskit. 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 version of 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®.
From DB2 V10.5 FP5 onwards, if the client is being installed on a separate computer and uses SSL
to communicate with servers, ignore numbers two and three of the Procedure section. GSK also does
not need to be installed for CLI, .NET, and open source drivers. You can pass the SSL 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.
Note: GSK is still required
for Certificate-based authentication, such as two-way authentication supported by DB2 for
z/OS.
- 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/v80/GSK_CapiCmd_UserGuide.pdf.
About this task
The SSL communication will always be in FIPS mode.
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 website 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 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.
- 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 -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 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;
- 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
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.