IBM Support

Complete guide to set up SSL using IBM Data Server Driver for JDBC and SQLJ

How To


Summary

This article talks about the set up required at client-side (The IBM Data Server Driver for JDBC and SQLJ) to configure SSL. Set up at server side is out of scope of this article. Client-side configuration steps are same regardless of which server we are connecting to. There are 2 ways SSL can be configured, server authentication and Mutual authentication.

Objective

How to set up SSL using IBM Data Server Driver for JDBC and SQLJ .
There are 2 ways SSL can be configured, server authentication and Mutual authentication. 

Environment

Windows, same is applicable for other platforms as well.

Steps

Server Authentication:

Also known as 1-way authentication. In this type, the client is presented with a server’s certificate. The client computer might try to match the server’s CA against the client’s list of trusted CAs. If the issuing CA is trusted, the client will verify that the certificate is authentic and has not been tampered with.

Set up steps:

1) Obtain servers certificate

               First step in setting up SSL is to obtain the servers certificate. DB2 Admin should be able to provide the server certificate to clients.

2)Create a trust store and add the server certificate to the trust store. Trust store is a place where the client will store all the certificate it trusts. We can use keytool provided by JDK for this. Keytool will be usually present in path java_installation_path/jdk64/bin. Below command will create a truststore “myTrustStore.jks” if it doesn’t exist and add server certificate “mydbserver.arm” into it.

keytool -import -trustcacerts -alias myalias -file mydbserver.arm -keystore       myTrustStore.jks

You can verify the presence of the certificate in the TrustStore by executing the following command.

              

keytool -list -v -keystore myTrustStore.jks

3) Set JCC parameter sslConnection to true. sslConnection parameter can be set through Datasource or global properties file or through URL.

ds.setSslConnection(true); (Datasource)
or
sslConnection=true (global properties file)

4) Set parameter sslTrustStoreLocation to the path where trust stored is placed and set sslTrustStorePassword to the password of the truststore. sslTrustStoreLocation and sslTrustStorePassword parameters can be set through Datasource or global properties file or through URL.

              

 ds.setSslTrustStoreLocation("C:/Security/SSL/certificates/mynewdbclient.jks");
 ds.setSslTrustStorePassword("password"); (Datasource)

 or
 sslTrustStoreLocation=C:/Security/SSL/certificates/mynewdbclient.jks
 sslTrustStroePassword=password  (global properties file)

Optional: The version of the SSL & TLS protocols used will be decided by the JRE used in the application. But if we want to set the version to a different level than the default, we need to set “sslVersion” parameter as shown below.

ds.setSslVersion("TLSv1.1"); (Datasource)
or
sslVersion=TLSv1.1 (global properties file)

Mutual Authentication:

Also known as 2-way authentication. In mutual SSL authentication, both client and server authenticate each other through the digital certificate so that both parties are assured of the others' identity. With mutual authentication, a connection can occur only when the client trusts the server's certificate and the server trusts the client's certificate.

In order to configure mutual authentication, we need to do further set up steps in addition to steps mentioned above. Continue to step 5 after finishing first 4 steps under server authentication.

5) Generate client certificate, create a KeyStore and add the client certificate to the KeyStore. KeyStore is a place for the client to store its own certificate so that it can provide when requested by servers. The following key command will take care of all 3 steps.

keytool -genkey -keyalg rsa -keystore clientkeystore.jks -storepass password -alias client_cert

The command will ask for details to include in the certificate such as first name, last name, organization unit, organization, city, state & country code. When prompted with ‘Enter key password for’, press Enter to use the same password as the KeyStore password.

Note: It is not recommended to use same JKS as both TrustStore and KeyStore, since KeyStore will contain private key also in addition to client certificate. By using same JKS for both purpose we will be compromising the security of private key.

6) Set parameter securityMechanism to 18 (DB2BaseDataSource.TLS_CLIENT_CERTIFICATE_SECURITY). This can be done through datasource or global properties file or through URL.

ds.setSecurityMechanism((com.ibm.db2.jcc.DB2BaseDataSource.TLS_CLIENT_CERTIFICATE_SECURITY)); (Datasource) 
or 
securityMechanism=18 (global properties file)

7) Set parameter “sslKeystoreLocation” to the path where keystore is present. And set “sslKeyStorePassword” to the key store password.

ds.setSslKeyStoreLocation("C:/Security/SSL/certificates/clientkeystore.jks");
ds.setSslKeyStorePassword("password");    (Datasource)
or
sslKeyStoreLocatoin=C:/Security/SSL/certificates/clientkeystore.jks
sslKeyStorePassword=password     (global properties file)

Note: sslKeystoreLocation and sslKeyStorePassword are supported in JCC4 and not in JCC3. If you are using JCC3 then these properties should be set using system properties.

System.setProperty("javax.net.ssl.keyStore","C:/Security/certificates/mykeystore");
System.setProperty("javax.net.ssl.keyStorePassword","123456");  

Trouble Shooting Tips:

In case there is any error during connection after SSL set up, you can set the system property "javax.net.debug" to "ssl:handshake:verbose" which will provide SSL handshake details in the console. Analyzing this SSL handshake log will help in figuring out the problem. Listed below are some of the common errors encountered by customers and how to resolve them.

  • 1) Error: A communication error occurred during operations on the connection's underlying socket, socket input stream, or socket output stream.  Error location: Reply.fill() - socketInputStream.read (-1)

    • Soln: verify if you are connecting to ssl port and there was no error in server after ssl configuration

  • 2)  Error : java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target

  •   Soln:  Server certificate not present in TrustStore or certificate provided by server is not trusted

3)  Error: com.ibm.db2.jcc.am.DisconnectNonTransientException: Execution failed due to a distribution protocol error that caused deallocation of the conversation. A DRDA Conversational Protocol Error was detected.  Reason: 0x1245. ERRORCODE=-4499, SQLSTATE=58009     

    • Soln : This error occurs when user is trying to mutual SSL authentication(securityMechanism is set to 18) but Server has not been configured for mutual authentication.

Document Location

Worldwide

Operating System

Cross Brand:All operating systems listed

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSEPDU","label":"Db2 Connect"},"Component":"JDBC;SQLJ;IBM Data Server Driver for JDBC and SQLJ","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"11.5","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Product Synonym

IBM Data Server Driver for JDBC and SQLJ; Db2 ; Db2 Connect ; Db2 for LUW

Document Information

Modified date:
11 October 2019

UID

ibm11077081