DB2 10.5 for Linux, UNIX, and Windows

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.

Before you begin

Before configuring SSL support, perform the following steps:

About this task

The SSL communication will always be in FIPS mode.

SSL support for DB2 Connect™
If you are using DB2 Connect for System i®, DB2 Connect for System z®, or DB2 Enterprise Server Edition on an intermediate server computer to connect DB2 clients to a host or System i database, SSL support is available in any of the following configurations:
  • Between the client and the DB2 Connect server
  • Between the DB2 Connect server and the server
  • Between both the client and the DB2 Connect server and the DB2 Connect server and the server
Note: For SSL support to be enabled on all paths in the configuration, each client or server must fulfill all requirements for SSL support. For example, if the DB2 Connect connection concentrator is on, the inbound request to the DB2 Connect server cannot use SSL. However, the outbound request to the target server can use SSL.
SSL support for High Availability Disaster Recovery (HADR) systems
SSL is supported between clients and the HADR primary server. Clients connecting to the HADR primary server using SSL are able to reroute to the HADR standby database using SSL. However, SSL is not supported between the HADR primary and standby servers.
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.
Configuring SSL support
To configure SSL support, first, you create a key database to manage your digital certificates. These certificates and encryption keys are used for establishing the SSL connections. Second, the DB2 instance owner must configure the DB2 instance for SSL support.

Procedure

  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

Example

The following example demonstrates how to display a certificate. This example uses the self-signed certificate created by the following command:
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"
To display the certificate, issue the following command:
gsk8capicmd_64 -cert -details -db "mydbserver.kdb" -pw "mydbserverpw0" 
  -label "myselfsigned"
The output is displayed is as follows:
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
To obtain a CA-signed certificate for your server (instead of a self-signed certificate), you need to generate a certificate signing request and pay the well known CA, such as VeriSign, to sign the certificate. After you get the signed certificate back, you need to receive it into the server key database. The following example demonstrates how to request and receive a certificate. It uses a trial version of a certificate.
  1. First, create a Certificate Signing Request (CSR) for mydbserver.kdb The following command creates a new RSA private-public key pair and a PKCS10 certificate request in the specified key database. For CMS key databases, the certificate request information is stored in the file with the ".rdb" extension. The file specified by the -file option is the one that needs to be sent to a CA.
    gsk8capicmd_64 -certreq -create -db "mydbserver.kdb" -pw "mydbserverpw0" 
       -label "mycert" -dn "CN=myhost.mycompany.com,
        O=myOrganization,OU=myOrganizationUnit,L=myLocation,ST=ON,C=CA", 
       -file "mycertRequestNew"
    The following command lists the detailed information of the certificate request for my db server:
    gsk8capicmd_64 -certreq -details -showOID -db "mydbserver.kdb" 
       -pw "mydbserverpw0" -label "mycert"
    The output would display as follows:
    label : mycert
    key size : 1024
    subject :    Common Name (CN):
        Type : 2.5.4.3
        Value: myhost.mycompany.com
       Organization (O):
        Type : 2.5.4.10
        Value: myOrganization
       Organizational Unit (OU):
        Type : 2.5.4.11
        Value: myOrganizationUnit
       Locality (L):
        Type : 2.5.6.3 
        Value: myLocation
       State (ST):
        Type : ?
        Value: Ontario
       Country or region (C):
        Type : 2.5.4.6
        Value: CA
    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 9C B4 62
        3C 89 02 4E B0 D8 EA 0B B8 CC 70 63 4A 59 1F 0F
        FD 98 9A 1A 39 94 E3 43 C1 63 7A CD 21 47 57 D9
        86 6F 11 B8 91 08 AC E3 E2 21 32 FE 43 1F 07 C9
        F5 40 6B 3E 4D 56 35 05 62 D6 78 0B E3 97 28 F7
        27 31 A4 05 BE F2 3A 44 6B D8 D1 FF 1E DA 59 63
        E6 49 52 39 45 9C 1E 8E CC DA A1 D9 0F 3A 96 09
        66 5C 89 23 2E EE 31 65 8D 87 8E B9 61 C6 69 BC
        A5 DB EB 03 16 E6 33 85 14 68 BC DD F1 02 03 01
        00 01
    finger print : 
    e0dcde10ded3a46a53c0190e84cc994e
    5d7e4bad
    attributes
    signature algorithm1.2.840.113549.1.1.5
    value   
        4F 06 B4 E3 1F 00 B4 81 90 CC A2 99 4A 02 68 D0
        84 B5 7F 33 0B F0 04 D5 7D 4C 5C CB 5C D3 37 77
        E2 6D 10 17 50 19 D0 7F 61 C7 C8 54 7B DB CD 6F
        47 9F 7E 7E 5A CC 64 20 85 95 A8 5E C7 7D FB F4
        8A 7F 4B 74 6F 0A C6 EF 09 E7 0A 15 17 CC 1D D2
        5D ED 02 A1 BE 1D FC F2 65 EB 0D E2 93 BC 88 4C
        4C 73 76 16 9F 1B 12 3B 7A 01 CF E0 63 97 E8 38
        02 FB 47 EE F2 17 54 66 4D F7 7F 9E 13 DA 76 A2
    To display the certificate request file:
    $ cat mycertRequestNew
    
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAO
    BgNVBAcTB01hcmtoYW0xDDAKBgNVBAoTA0lCTTEMMAoGA1UECxMDREIyMR8wHQYD
    VQQDExZnaWxlcmEudG9yb2xhYi5pYm0uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GN
    ADCBiQKBgQCctGI8iQJOsNjqC7jMcGNKWR8P/ZiaGjmU40PBY3rNIUdX2YZvEbiR
    CKzj4iEy/kMfB8n1QGs+TVY1BWLWeAvjlyj3JzGkBb7yOkRr2NH/HtpZY+ZJUjlF
    nB6OzNqh2Q86lglmXIkjLu4xZY2Hjrlhxmm8pdvrAxbmM4UUaLzd8QIDAQABoAAw
    DQYJKoZIhvcNAQEFBQADgYEATwa04x8AtIGQzKKZSgJo0IS1fzML8ATVfUxcy1zT
    N3fibRAXUBnQf2HHyFR7281vR59+flrMZCCFlahex3379Ip/S3RvCsbvCecKFRfM
    HdJd7QKhvh388mXrDeKTvIhMTHN2Fp8bEjt6Ac/gY5foOAL7R+7yF1RmTfd/nhPa
    dqI=
    -----END NEW CERTIFICATE REQUEST-----
    In case you need to delete the certificate request, use a command similar to the following example:
    gsk8capicmd_64 -certreq -delete -db "mydbserver.kdb" -pw "mydbserverpw0" 
       -label "mycert"
  2. Next, go to the VeriSign website, register and you will be asked to cut and paste the request file to submit the request. For trial version, you would receive an email that contains the signed certificate. The email also contains links for downloading the trial root CA certificate and the trial intermediate CA certificate. Use notepad or vi to save all three certificates into files:
    • RootCert.arm
    • IntermediateCert.arm
    • MyCertificate.arm
    These three are in a chain of trust.
    Add the trial Root CA Certificate into mydbserver.kdb with the following command:
    gsk8capicmd_64 -cert -add -db "mydbserver.kdb" -pw "mydbserverpw0" 
       -label "trialRootCACert"  -file RootCert.arm -format ascii
    Add the trial Intermediate CA Certificate into mydbserver.kdb with the following command:
    gsk8capicmd_64 -cert -add -db "mydbserver.kdb" -pw "mydbserverpw0" 
       -label "trialIntermediateCACert" -file IntermediateCert.arm -format ascii
    Receive the trial Certificate into mydbserver.kdb with the following command:
    $ cat SSLCertificate.cer2
                                                                                              
    -----BEGIN CERTIFICATE-----
    MIIFVjCCBD6gAwIBAgIQdOydrySM+J4uUPNzbPHhVjANBgkqhkiG9w0BAQUFADCB
    yzELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTAwLgYDVQQL
    EydGb3IgVGVzdCBQdXJwb3NlcyBPbmx5LiAgTm8gYXNzdXJhbmNlcy4xQjBABgNV
    BAsTOVRlcm1zIG9mIHVzZSBhdCBodHRwczovL3d3dy52ZXJpc2lnbi5jb20vY3Bz
    L3Rlc3RjYSAoYykwNTEtMCsGA1UEAxMkVmVyaVNpZ24gVHJpYWwgU2VjdXJlIFNl
    cnZlciBUZXN0IENBMB4XDTA5MDIyMzAwMDAwMFoXDTA5MDMwOTIzNTk1OVowgaox
    CzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdPbnRhcmlvMRAwDgYDVQQHFAdNYXJraGFt
    MQwwCgYDVQQKFANJQk0xDDAKBgNVBAsUA0RCMjE6MDgGA1UECxQxVGVybXMgb2Yg
    dXNlIGF0IHd3dy52ZXJpc2lnbi5jb20vY3BzL3Rlc3RjYSAoYykwNTEfMB0GA1UE
    AxQWZ2lsZXJhLnRvcm9sYWIuaWJtLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw
    gYkCgYEAnLRiPIkCTrDY6gu4zHBjSlkfD/2Ymho5lONDwWN6zSFHV9mGbxG4kQis
    4+IhMv5DHwfJ9UBrPk1WNQVi1ngL45co9ycxpAW+8jpEa9jR/x7aWWPmSVI5RZwe
    jszaodkPOpYJZlyJIy7uMWWNh465YcZpvKXb6wMW5jOFFGi83fECAwEAAaOCAdcw
    ggHTMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMEMGA1UdHwQ8MDowOKA2oDSGMmh0
    dHA6Ly9TVlJTZWN1cmUtY3JsLnZlcmlzaWduLmNvbS9TVlJUcmlhbDIwMDUuY3Js
    MEoGA1UdIARDMEEwPwYKYIZIAYb4RQEHFTAxMC8GCCsGAQUFBwIBFiNodHRwczov
    L3d3dy52ZXJpc2lnbi5jb20vY3BzL3Rlc3RjYTAdBgNVHSUEFjAUBggrBgEFBQcD
    AQYIKwYBBQUHAwIwHwYDVR0jBBgwFoAUZiKOgeAxWd0qf6tGxTYCBnAnh1oweAYI
    KwYBBQUHAQEEbDBqMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC52ZXJpc2lnbi5j
    b20wQgYIKwYBBQUHMAKGNmh0dHA6Ly9TVlJTZWN1cmUtYWlhLnZlcmlzaWduLmNv
    bS9TVlJUcmlhbDIwMDUtYWlhLmNlcjBuBggrBgEFBQcBDARiMGChXqBcMFowWDBW
    FglpbWFnZS9naWYwITAfMAcGBSsOAwIaBBRLa7kolgYMu9BSOJsprEsHiyEFGDAm
    FiRodHRwOi8vbG9nby52ZXJpc2lnbi5jb20vdnNsb2dvMS5naWYwDQYJKoZIhvcN
    AQEFBQADggEBAKs1YpIeOAL6mTryIXpYfokkzRdwP5ooDutHhVbRYcPwq9ynOrHM
    3gZolv8th5PpSkZAGTPr3HJZG6HnxRiQjPT88PAADR3SEzVMzQEESHfYToF1qBPZ
    svigphI9eIHcg5IWwv7dyuXtkFGbTCqcvEqJiT3UHhubgMfoTuTGayhNoGt75FGU
    h4kSJz3af6MNuGmQLs4wzJTepU7srlhGV1C1ujTCydax2BiWfWwO4YaFcckvHxbR
    6I7vVj1PTC2RO8n5qcWJYmGU0PG3d58hJETD4E8tAReh21ShBWDgn4+e0k1XtQ8K
    lB66QpsFYGTLtGyd/4w4BAgq/QLmcs+mpjc=
    -----END CERTIFICATE-----
    
    gsk8capicmd_64 -cert -receive -file MyCertificate.arm -db "mydbserver.kdb" 
       -pw "mydbserverp -format ascii 
    List all the certificates in mydbserver.kdb with the following command:
    gsk8capicmd_64 -cert -list all -db "mydbserver.kdb" -pw "mydbserverpw0"
    
    certificates found
    * default, - personal, ! trusted
    -!      mycert
    !       trialIntermediateCACert
    !       trialRootCACert
    -!      myselfsigned
    db2 update dbm cfg using SSL_SVR_LABEL mycert  
Notes: