Secure Sockets Layer (SSL) support in DB2 for Linux, UNIX, and Windows

Step-by-step instructions

Using Secure Sockets Layer (SSL) with IBM® DB2® means your data can be sent securely over the network. In this article, learn how to configure this protocol for DB2 V9.7 and newer releases.

Praveen R. Sogalad (psogalad@in.ibm.com), Staff Software Engineer, IBM

Color photo of Praveen SogaladPraveen R. Sogalad is with IBM India Software Labs - Bangalore since Dec 2004. He has been working as a Staff Software Engineer in the DB2 for Linux, UNIX, and Windows Advanced Support team. He has three developerWorks articles in his name and more then 50 technotes published, which serves customer FAQ's and help them solve issues in DB2 databases. Prior to this role, he was an application developer for the DB2 Samples Development team in the IBM India Software Labs - Bangalore.



Hemant Singh (hemant_singh@in.ibm.com), Staff Software Engineer, IBM

Author photo newHemant K Singh has been working as a staff software engineer in System Verification Testing for DB2 since June 2006. He is an IBM DB2 Certified V9 Advanced DBA. His area of expertise is DB2 High Availability Disaster Recovery (HADR) and Extent Movement.



13 June 2013

Also available in Chinese

Overview

Secure Sockets Layer (SSL) is a protocol that lets services communicate over a network without compromising security. It creates a secure connection between a client and a server. Any amount of data can then be sent securely over that connection. You should consider using SSL if, for example, you process credit cards through an online application, process sensitive data such as personal identification information, or need to comply with privacy standards.

You can use SSL to protect data in transit on all networks that use TCP/IP. Alternatively, you can think of an SSL connection as a secured TCP/IP connection.

The DB2 database system supports the use of Secure Sockets Layer (SSL). The IBM Data Server Driver for JDBC and SQLJ provides support for the SSL through the Java Secure Socket Extension (JSSE).

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.

The SSL communication will always be in Federal Information Process Standards(FIPS) mode.

Note: If you are configuring SSL on DB2 Versions V9.5 and earlier, then see the Resources section for an article that describes a step-by-step procedure to setup SSL on Windows platform.


Server side SSL parameters

Prior to DB2 V9.7, for DB2 data servers to recognize SSL support, the DB2COMM registry variable has to be set to include SSL, and the SSL configuration file SSLconfig.ini must be created in the instance directory under cfg (UNIX and Linux operating systems) or instance directory (Windows operating systems). The file shown in Table 1 stores the SSL parameters that are used to start SSL at the server.

Table 1. Shows the server side SSL parameters you can set prior to DB2 V9.7
Name of SSL parametersNullable?Description
DB2_SSL_KEYSTORE_FILENOFully Qualified file name of KeyStore that stores the Server Certificate
DB2_SSL_KEYSTORE_PWYESPassword of KeyStore that stores the Server Certificate
DB2_SSL_KEYSTORE_LABELYESLabel of Server Certificate
DB2_SSL_LISTENERNOService name/Port number for SSL Listener

Starting from DB2 V9.7 and new versions, you don't need to create the SSL configuration file SSLconfig.ini. The SSL parameters mentioned previously in Table 1 are moved into the database manager configuration file, as shown in Table 2.

Table 2. Shows the server side SSL parameters you can set from DB2 V9.7 and above
Name of SSL DBM configuration parametersNullable?Description
SSL_SVR_KEYDBNOFully qualified path of the key file
SSL_SVR_STASHNOFully qualified path of the stash file
SSL_SVR_LABELNOLabel of Server Certificate
SSL_SVCENAMENOService name/Port number for SSL Listener

Note 1: DB2_SSL_KEYSTORE_PW specifies the password to access the key database at the server side. But this has been replaced with SSL_SVR_STASH file. You will not add a DBM cfg parameter for the password. Instead, you will let GSKit encrypt the password and save it in a stash file and add a DBM cfg parameter SSL_SVR_STASH for the stash file. On the one hand, it avoids exposing the password in clear text. It also enables db2start to go without users’ intervention to supply the password. The stash file should be strongly protected by the file system.

Note 2: During instance startup, if DB2COMM is set to SSL, GSKit will use the stash file defined in the SSL_SVR_STASH DBM configuration file to access the key file. So SSL_SVR_KEYDB and SSL_SVR_STASH must be defined. If they are NULL (not specified), the instance will be started up without SSL protocol support.


Client side SSL parameters

Starting from DB2 V9.7, you don't need to create a separate SSLClientconfig.ini file to define client-side settings for SSL. The SSL parameters are moved into the database manager configuration file, as shown in Table 3.

Table 3. Shows the client side SSL parameters you can set from DB2 V9.7 and newer releases
Name of SSL DBM configuration parametersNullable?Description
ssl_clnt_keydbNOThe fully qualified file path of the key file to be used for SSL connection at the client-side.
ssl_clnt_stashNOThe fully qualified file path of the stash file to be used for SSL connections at the client-side

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.

Clients connecting to the HADR primary database server is the same as clients connecting to a standard database server. Therefore SSL can be used between clients and the HADR primary server. However, between the HADR primary server and standby server, only TCPIP (either TCPIP4 or TCPIP6) can currently be used. They use the hostnames/ports defined in the DB CFG to communicate with each other. They listen on their own listener ports, which is different from the one in SVCENAME. Protocols set in DB2COMM are irrelevant.


Pre-configuration tasks on server

The IBM Global Security Kit (GSKit) supports the use of the SSL protocol to protect DB2 client server communications over the network. GSKit is automatically included when you install the DB2 database system. In some situations, if you want to use SSL, you might need to install GSKit by yourself.

For information about the GSKit tool GSKCapiCmd, see the GSKCapiCmd User's Guide, available from the Resources section.

For more information on IBM Global Security Kit (GSKit), refer to the Resources section.

Before configuring SSL, ensure that the path to the IBM Global Security Kit (GSKit) libraries appears in the PATH environment variable on Windows platforms, and the LIBPATH, SHLIB_PATH or LD_LIBRARY_PATH environment variables on Linux and UNIX platforms.

  • On Windows 32-bit platforms, the GSKit libraries are located in C:\Program Files\IBM\GSK8\lib. In this case, the system PATH must include C:\Program Files\IBM\GSK8\lib.
  • On Windows 64-bit platforms, the 64-bit GSKit libraries are located in C:\Program Files\IBM\GSK8\lib64, and the 32-bit GSKit libraries are located in C:\Program Files (x86)\IBM\GSK8\lib.
  • On UNIX and Linux platforms, the GSKit libraries are located in sqllib/lib/gskit.
  • 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 to bring up the instance. If a global copy of GSKit does exist, keep the version of the global GSKit at the same version of the local GSKit.

Steps to configure SSL support on AIX

Server side

Perform the following steps to configure the SSL on server side:

  1. Configure your system environment variable, as shown in Listing 1.
    Listing 1. Configure your system environment variable
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/db2inst1/sqllib/gskit/bin 
    export PATH=$PATH:/home/db2inst1/sqllib/gskit/bin
  2. Make a separate directory SSL under instance home directory to keep all SSL files separately, as shown in Listing 2.
    Listing 2. Make separate directory SSL
    /home/db2inst1> mkdir SSL
                            
    /home/db2inst1> cd SSL 
                            
    /home/db2inst1/SSL> pwd 
                            
    /home/db2inst1/SSL
  3. Create a server key database and set up your digital certificates as follows:
    1. Create Server key database, as shown in Listing 3.
      Listing 3. Create Server key database
      /home/db2inst1/SSL> gsk8capicmd_64 -keydb -create -db "key.kdb" -pw 
      "ibm123456" -stash
    2. Add a certificate for your server to your key database, as shown in Listing 4.
      Listing 4. Add certificate
      /home/db2inst1/SSL> gsk8capicmd_64 -cert -create -db "key.kdb" -pw 
      "ibm123456" -label "SSLLabel" -dn "CN=bugdbug.ibm.com,O=IBM,OU=ISL,
      L=Bangalore,ST=KA,C=INDIA"
    3. Extract the certificate you just created to a file, as shown in Listing 5.
      Listing 5. Extract certificate
      /home/db2inst1/SSL> gsk8capicmd_64 -cert -extract -db "key.kdb" -pw 
      "ibm123456" -label "SSLLabel" -target "key.arm" -format ascii -fips
    4. Verify the following files are created inside SSL directory, as shown in Listing 6.
      Listing 6. Verify files
      /home/db2inst1/SSL> ls 
                                      
      key.arm, key.crl, key.kdb, key.rdb, key.sth
  4. Log in to DB2 server as instance owner to set database manager configuration parameters on the server for SSL, as shown in Listing 7, and mentioned previously in Table 2.
    Listing 7. Set database manager configuration parameters
    /home/db2inst1> db2 update dbm cfg using SSL_SVR_KEYDB /home/db2inst1/SSL/key.kdb
    DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.
                            
    /home/db2inst1> db2 update dbm cfg using SSL_SVR_STASH /home/db2inst1/SSL/key.sth
    DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.
                            
    /home/db2inst1> db2 update dbm cfg using SSL_SVR_LABEL SSLLabel
    DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.
                            
    /home/db2inst1> db2 update dbm cfg using SSL_SVCENAME 50602 
    DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.

    Note: The value set to SSL_SVCENAME should be the one which does not exist in your /etc/services file.

  5. Set the DB2COMM registry variable, as shown in Listing 8.
    Listing 8. Set DB2COMM
    /home/db2inst1> db2set DB2COMM=SSL,TCPIP 
    or  
    /home/db2inst1> db2set DB2COMM=SSL
  6. Update DIAGLEVEL database manager configuration parameter to 4.
    /home/db2inst1> db2 update dbm cfg using DIAGLEVEL 4
  7. Refresh your instance for above setting to become effective. After the steps shown previously, stop and start DB2 using db2stop and db2start, as shown in Listing 9.
    Listing 9. Stop and start DB2
    /home/db2inst1> db2stop force 
    SQL1064N  DB2STOP processing was successful. 
                            
    /home/db2inst1>  db2start 
    SQL1063N  DB2START processing was successful.

    Note: You should see the processing was successful messages after you do the db2stop and db2start.

  8. Listing 10 shows the db2diag.log file.
    Listing 10. db2diag.log file
    2013-03-06-06.52.35.356786-300 I40437A358         LEVEL: Info
    PID     : 1126566              TID  : 258       PROC : db2sysc
    INSTANCE: db2inst1             NODE : 000
    EDUID   : 258                  EDUNAME: db2sysc>
    FUNCTION: DB2 UDB, common communication, sqlcctcp_start_listen, probe:81
    MESAGE : DIA3000I "SSL" protocol support was successfully started.
                    
    2013-03-06-06.52.36.356973-300 I40796A312         LEVEL: Info
    PID     : 1126566              TID  : 258         PROC : db2sysc
    INSTANCE: db2inst1             NODE : 000
    EDUID   : 258                  EDUNAME: db2sysc
    FUNCTION: DB2 UDB, common communication, sqlccstrts, probe:984
    MESSAGE : SSL is setup properly

    If you see all of the above messages, than SSL setup is successful on the server side.

Note: If you see the messages shown in Listing 11 after db2start, then there may be some problem with either the system environment variables setting or with SSL server parameters settings for your instance.

Listing 11. Alternative messages after db2start
/home/db2inst1> db2start
SQL5043N Support for one or more communications protocols failed to start successfully. 
However, core database manager functionality started successfully.
SQL1063N DB2START processing was successful.

Client side

Perform the following steps to configure the SSL on the client side.

  1. Make a separate directory SSL under instance home directory to keep all SSL files separately, as shown in Listing 12.
    Listing 12. Make separate directory SSL
    /home/db2inst2> mkdir SSL  
                         
    /home/db2inst2> cd SSL
                            
    /home/db2inst2/SSL> pwd 
                            
    /home/db2inst2/SSL
  2. FTP the key.arm from the server and place it in the client inside /home/db2inst2/SSL.
  3. Create a client key database and set up a digital certificate as follows:
    1. Create the client key database.
      /home/db2inst2/SSL> gsk8capicmd_64 -keydb -create -db "keyclient.kdb" 
      -pw "ibm654321" -stash
    2. Add the signer certificate sent from the server to the client key database.
      /home/db2inst2/SSL> gsk8capicmd_64 -cert -add -db "keyclient.kdb" 
      -pw "ibm654321" -label "SSLLableClt" -file key.arm -format ascii -fips
  4. As shown in Listing 13, log in to DB2 client as the instance owner to set database manager configuration parameters on client for SSL as mentioned previously in Table 3.
    Listing 13. Set database manager configuration parameters
    /home/db2inst2> 
    db2 update dbm cfg using SSL_CLNT_KEYDB /home/svtdbm12/SSL/keyclient.kdb 
    DB20000I  The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.
                            
    /home/db2inst2> db2 update dbm cfg using SSL_CLNT_STASH 
    /home/svtdbm12/SSL/keyclient.sth DB20000I  
    The UPDATE DATABASE MANAGER CONFIGURATION command completed successfully.
  5. Set up your DB2 Client for SSL Support as follows:
    1. Catalog the server with SSL port and SECURITY SSL option, as shown in Listing 14.
      Listing 14. Catalog the server
      /home/db2inst2> db2 catalog tcpip node dbug remote bugdbug server 50602 
      security ssl 
      DB20000I  The CATALOG TCPIP NODE command completed successfully. 
      DB21056W  Directory changes may not be effective until the directory 
      cache is refreshed
                                  
      /home/db2inst2> db2 catalog db sample as sampleSSL at node dbug  
      DB20000I  The CATALOG DATABASE command completed successfully. 
      DB21056W  Directory changes may not be effective until the directory 
      cache is refreshed
                                  
      /home/db2inst2> db2 terminate 
      DB20000I  The TERMINATE command completed successfully.
    2. Connect to the server database, as shown in Listing 15.
      Listing 15. Connect to server database
      /home/db2inst2> db2 connect to samssl user db2inst1 using 
      "server_instance_password" 
                                  
      Database Connection Information
                                  
      Database server        = DB2/AIX64 9.7.7
      SQL authorization ID   = DB2INST1
      Local database alias   = SAMSSL

SSL configuration is not enabled if the following is true.

  1. The ssl_svr_keydb configuration parameter is null (unset) instead of the fully qualified path of the key database file.
  2. The ssl_svr_stash configuration parameter is null (unset) instead of fully qualified path of the stash file.
  3. The ssl_svcename is null (unset).

    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.

    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.

  4. When the DB2COMM registry variable is set to 'TCPIP, SSL', and 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, as shown in Listing 16.
    Listing 16. SQL5043N error when configuration parameter set to null
    /home/db2inst1> db2set -all 
    [i] DB2COMM=SSL,TCPIP 
                                
    /home/db2inst1> db2 get dbm cfg | grep -i svcename
    TCP/IP Service name                          (SVCENAME) =
  5. Trying to start your instance during db2start will return SQL5043N, as shown in Listing 17.
    Listing 17. SQL5043N error for instance during db2start
    /home/db2inst1> db2start 
    SQL5043N  Support for one or more communications protocols failed to start 
    successfully. 
    However, core database manager functionality started successfully.
  6. DB2 connection concentrator is ON. To determine whether connection concentrator is ON, issue the GET DATABASE MANAGER CONFIGURATION command. If the configuration parameter MAX_CONNECTIONS is set to a value greater than the value of MAX_COORDAGENTS, connection concentrator is ON. Listing 18 shows MAX_CONNECTIONS greater than MAX_COORDAGENTS.
    Listing 18. MAX_CONNECTIONS greater than MAX_COORDAGENTS
    /home/db2inst1> db2 get dbm cfg | grep -i max 
                            
    Max number of coordinating agents   (MAX_COORDAGENTS) = AUTOMATIC(100) 
    Max number of client connections     (MAX_CONNECTIONS)  = AUTOMATIC(1000)
  7. If SSL_CLNT_KEYDB and SSL_CLNT_STASH NULL are not specified, the connection will fail with SQL30081N.
  8. You can see messages in db2diag.log file, as shown in Listing 19.
    Listing 19. db2diag.log file messages
    2013-03-14-07.01.01.252735-240 I13216A330         LEVEL: Error 
    PID     : 1126574              TID  : 258         PROC : db2sysc
    INSTANCE: db2inst1             NODE : 000
    EDUID   : 258                  EDUNAME: db2sysc
    FUNCTION: DB2 UDB, common communication, sqlcctcpconnmgr, probe:110
    MESSAGE : Disable SSL as Concentrator is ON 

    Note: If DB2 Connect Concentrator is ON, the inbound request to the DB2 Connect server can not be SSL. However, the outbound request to the target database server can still be SSL. If DB2 Connect Concentrator is OFF, both the inbound and the outbound requests can be SSL.


Conclusion

SSL is a valuable protocol for protecting your data as it moves through a network. Almost any Internet service can be protected with SSL. Using the configuration instructions and test case verification program described in this article, you can get started with securing your own DB2 data.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.
  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=933577
ArticleTitle=Secure Sockets Layer (SSL) support in DB2 for Linux, UNIX, and Windows
publish-date=06132013