Configuring Secure Sockets Layer (SSL) support in a DB2 instance

The DB2® database system supports SSL, which means that a DB2 client application that also supports SSL can connect to a DB2 database using an SSL socket. CLI, CLP, and .Net Data Provider client applications and applications that use the IBM® Data Server Driver for JDBC and SQLJ (type 4 connections) support SSL.

1. Create a key database and set up your digital certificates.
   1. Use the GSKCapiCmd tool to create your key database. It must be a Certificate Management System (CMS) type key database. The GSKCapiCmd is a non-Java-based command-line tool, and 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 platforms, and C:\Program Files\IBM\GSK8\bin on both 32-bit and 64-bit Windows platforms. (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.) Ensure PATH (on the Windows platform) includes the proper GSKit library path, and LIBPATH, SHLIB_PATH, or LD_LIBRARY_PATH (on UNIX or Linux platforms) include the proper GSKit library path, such as sqllib/lib64/gskit.

      For example, the following command creates a key database called mydbserver.kdb and a stash file called mydbserver.sth:

      gsk8capicmd_64 -keydb -create -db "mydbserver.kdb" -pw "myServerPassw0rdpw0" 
            -stash

      The -stash option creates a stash file at the same path as the key database, with a file extension of .sth. At instance start-up, GSKit uses the stash file to obtain the password to the key database.

      Note: You should use strong file system protection on the stash file. By default, only the instance owner has access to this file (both read and write access).

      When you create a key database, it is automatically populated with signer certificates from a few certificate authorities (CAs), such as Verisign.

   2. Add a certificate for your server to your key database. The server sends this certificate to clients during the SSL handshake to provide authentication for the server. To obtain a certificate, you can either use GSKCapiCmd to create a new certificate request and submit it to a CA to be signed, or you can create a self-signed certificate for testing purposes.
      For example, to create a self-signed certificate with a label of myselfsigned, use the GSKCapiCmd command as shown in the following example:

      gsk8capicmd_64 -cert -create -db "mydbserver.kdb" -pw "myServerPassw0rdpw0" 
              -label "myselfsigned" -dn "CN=myhost.mycompany.com,O=myOrganization,
              OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA"

   3. Extract the certificate you just created to a file, so that you can distribute it to computers running clients that will be establishing SSL connections to your DB2 server.
      For example, the following GSKCapiCmd command extracts the certificate to a file called mydbserver.arm:

      gsk8capicmd_64 -cert -extract -db "mydbserver.kdb" -pw "myServerPassw0rdpw0" 
             -label "myselfsigned" -target "mydbserver.arm" -format ascii -fips

2. To set up your DB2 server for SSL support, log in as the DB2 instance owner and set the following configuration parameters and the DB2COMM registry variable.
   1. Set the ssl_svr_keydb configuration parameter to the fully qualified path of the key database file. For example:

      db2 update dbm cfg using SSL_SVR_KEYDB 
               /home/test/sqllib/security/keystore/key.kdb

      If ssl_svr_keydb is null (unset), SSL support is not enabled.
   2. Set the ssl_svr_stash configuration parameter to the fully qualified path of the stash file. For example:

      db2 update dbm cfg using SSL_SVR_STASH 
              /home/test/sqllib/security/keystore/mydbserver.sth

      If ssl_svr_stash is null (unset), SSL support is not enabled.
   3. Set the ssl_svr_label configuration parameter to the label of the digital certificate of the server, which you added in Step 1. If ssl_svr_label is not set, the default certificate in the key database is used. If there is no default certificate in the key database, SSL is not enabled. For example: db2 update dbm cfg using SSL_SVR_LABEL myselfsigned where myselfsigned is a sample label.
   4. Set the ssl_svcename configuration parameter to the port that the DB2 database system should listen on for SSL connections. If TCP/IP and SSL are both enabled (the DB2COMM registry variable is set to 'TCPIP, SSL'), you must set ssl_svcename to a different port than the port to which svcename is set. The svcename configuration parameter sets the port that the DB2 database system listens on for TCP/IP connections. If you set ssl_svcename to the same port as svcename, neither TCP/IP or SSL will be enabled. If ssl_svcename is null (unset), SSL support is not enabled.
      Note: In HADR environments, do not set hadr_local_svc on the primary or standby database system to the same value as you set for ssl_svcename. Also, do not set hadr_local_svc to the same value as svcename, or svcename plus one.
      Note: When the DB2COMM registry variable is set to 'TCPIP,SSL', if TCPIP support is not properly enabled, for example due to the svcename configuration parameter being set to null, the error SQL5043N is returned and SSL support is not enabled.
   5. (Optional) If you want to specify which cipher suites the server can use, set the ssl_cipherspecs configuration parameter. If you leave ssl_cipherspecs as null (unset), this allows GSKit to pick the strongest available cipher suite that is supported by both the client and the server. See Supported cipher suites for information about which cipher suites are available.
   6. Add the value SSL to the DB2COMM registry variable. For example:

      db2set -i db2inst1 DB2COMM=SSL

      where db2inst1 is the DB2 instance name. The database manager can support multiple protocols at the same time. For example, to enable both TCP/IP and SSL communication protocols:

      db2set -i db2inst1 DB2COMM=SSL,TCPIP

   7. Restart the DB2 instance. For example:

      db2stop
      db2start

gsk8capicmd_64 -cert -create -db "mydbserver.kdb" -pw "mydbserverpw0" 
  -label "myselfsigned" -dn "CN=myhost.mycompany.com,O=myOrganization,
        OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA"

gsk8capicmd_64 -cert -details -db "mydbserver.kdb" -pw "mydbserverpw0" 
  -label "myselfsigned"

label : myselfsigned
key size : 1024
version : X509 V3
serial : 96c2db8fa769a09d
issue:CN=myhost.mycompany.com,O=myOrganization,OU=myOrganizationUnit,
   L=myLocation,ST=ON,C=CA
subject:CN=myhost.mycompany.com,O=myOrganization,OU=myOrganizationUnit,
   L=myLocation,ST=ON,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