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.
This article also talks about the known issues for setting up IBM Semeru JDK and how it can be resolved
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
Steps
SSL Configuration steps:
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.
First step in setting up SSL is to obtain the servers certificate. DB2 Admin should be able to provide the server certificate to clients.
Or
To create a self-signed server certificate, please follow below steps one after the other or place the commands in a .bat file and execute the bat file. (Update the kdb filename and password as required)
gsk8capicmd_64 -keydb -create -db mydbserver.kdb -pw mykdb123 -stash -populate
gsk8capicmd_64 -cert -create -db mydbserver.kdb -pw mykdb123 -label "Server_CA" -default_cert yes -expire 1000
gsk8capicmd_64 -cert -extract -db mydbserver.kdb -pw mykdb123 -label "Server_CA" -target ~/sqllib/cfg/ mydbserver.arm -format ascii -fips
gsk8capicmd_64 -cert -list -db mydbserver.kdb -pw mykdb123
gsk8capicmd_64 -cert -details -db mydbserver.kdb -pw mykdb123 -label "Server_CA"
db2 update dbm config using SSL_SVR_KEYDB /<your kdb path>/ssl/ mydbserver.kdb
db2 update dbm config using SSL_SVR_STASH /<your kdb path>/ssl/ mydbserver.sth
db2 update dbm config using SSL_SVR_LABEL Server_CA
db2 update dbm config using SSL_SVCENAME 50001
db2set DB2COMM=SSL,TCPIP
db2 get dbm cfg | grep SSL
db2stop
db2start
1.2 Create the truststore
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
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 db2.jcc.sslConnection=true (global properties file) or sslConnection=true; (URL)
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/myTrustStore.jks");
ds.setSslTrustStorePassword("password"); (Datasource)
or
db2.jcc.sslTrustStoreLocation=C:/Security/SSL/certificates/myTrustStore.jks
db2.jcc.sslTrustStorePassword=password (global properties file)
or
sslTrustStoreLocation= C:/Security/SSL/certificates/myTrustStore.jks;sslTrustStorePassword=password (URL)
1.5 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
db2.jcc.sslVersion=TLSv1.1 (global properties file)
or
sslVersion=TLSv1.1;
Using Windows trust store:
If the application is in Windows environment and you want to use Microsoft Certificate Store (MSCS, also known as windows trust store) for authentication, it can be achieved by, importing the DB2 server certificate in Windows Certificate Manager under the Trusted Root Certificates. Then JCC properties for SSL can be configured as below through Datasource or global properties file or through URL.
ds.setSslTrustStoreType ("WINDOWS-ROOT"); (Datasource)
ds.setSslTrustStoreLocation("NUL");
or
db2.jcc.sslTrustStoreType=WINDOWS-ROOT (global properties file)
db2.jcc.sslTrustStoreLocation=NUL;
or
sslTrustStoreType=WINDOWS-ROOT;sslTrustStoreLocation=NUL;( URL)
2. 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(1.1 to 1.4) under server authentication.
2.1 Generate java keystore and add client certificate:
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.
2.2 Set parameter securityMechanism:
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 db2.jcc.securityMechanism=18 (global properties file) or securityMechanism=18;(URL)
2.3 Set parameter sslKeystoreLocation
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
db2.jcc.sslKeyStoreLocation=C:/Security/SSL/certificates/clientkeystore.jks
db2.jcc.sslKeyStorePassword=password (global properties file)
or
sslKeyStoreLocatoin=C:/Security/SSL/certificates/clientkeystore.jks; sslKeyStorePassword=password; (URL)
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/SSL/certificates/clientkeystore.jks"); System.setProperty("javax.net.ssl.keyStorePassword","password");
Troubleshooting Tips:
Verify the connection from commandline before using below command:
java com.ibm.db2.jcc.DB2Jcc -url jdbc:db2://hostname:portnumber/dbname:sslConnection=true;sslTrustStoreLocation=<path to trust store including the trust store name>;sslTrustStorePassword=********;sslVersion=TLSv1.2; -user username -password ********
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.
IBM Semeru JDK 1.8 know SSL V1.2 Protocol issue and resolution:
The default SSL protocol works fine with IBM Semeru JDK 1.8.0_322 version and JDK 1.8.0_312 as well. This issue shows up only for IBM Semeru JDK version 1.8.0_332 onwards.
The fix is available in a special build for JCC driver version 4.32.38. Please use this version until the official driver release.
- When SSL server hostname and port are incorrectly configured we get below error:
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: Server and Port for SSL must be configured correctly. Verify if you are connecting to ssl port and there was no error in server after ssl configuration - When Server Certificate is not available in truststore or certificate is not trusted we get below error.
Error : java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target
Soln: This error occurs when the Server certificate not present in TrustStore or certificate provided by server is not trusted. Verify if the certificate path set is correct where the certificate is present or verify the truststore details using the keytool.
- When user tries mutual SSL authentication but server is not configured for mutual authentication we get below error:
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 : Set up the Server configuration for mutual authentication as given in the section Server authentication above.
- When the keydb (.kdb) file does not have the server certificate in the DB2 server we get this error:
Error:java.sql.SQLNonTransientException :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). Message: Remote host terminated the handshake. ERRORCODE=-4499, SQLSTATE=08001 DSRA0010E: SQL State = 08001, Error Code = -4,499 Soln : This error occurs if you do not have the server certificate in the DB2 server kdb and hence the server is not responding to the request from client. If your certificate issuer had multiple signer certificates, add all those certificates to the database server keydb and restart the database server instance.
- When connecting using SSL Connection but PORT mentioned is Non-SSL port we get the below error:
Error:com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2030][11211][4.32.14] 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). Message: Remote host terminated the handshake. ERRORCODE=-4499, SQLSTATE=08001 at com.ibm.db2.jcc.am.ExceptionFactory.newDisconnectException(ExceptionFactory.java:338)
Soln : Update the correct SSL port for the DB2 SSL connection and restart the server.
- When the SSLTrustStoreLocation is incorrect we get the below error:
Error:com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2043][11550][4.32.14] Exception java.io.FileNotFoundException: Error opening socket to server localhost/127.0.0.1 on port 50,001 with message: C:\ssldir1\cfg\localKeyCert.jks (The system cannot find the path specified.). ERRORCODE=-4499, SQLSTATE=08001
Soln : Provide the correct TrustStore location.
- When SSLTrustStorePassword is incorrect we get the below error:
Error:com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2043][11550][4.32.14] Exception java.io.IOException: Error opening socket to server localhost/127.0.0.1 on port 50,001 with message: Keystore was tampered with, or password was incorrect. ERRORCODE=-4499, SQLSTATE=08001
Soln : Provide the correct SSL TrustStore Password.
- When sslVersion is incorrectly set we get the below error. In this case TLSv12 is set instead of TLSv1.2
Error:java.security.NoSuchAlgorithmException: TLSv12 SSLContext not available com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2043][11550][4.32.14] Exception com.ibm.db2.jcc.am.SqlException: Error opening socket to server localhost/127.0.0.1 on port 50,001 with message: [jcc][t4][20133][12451][4.32.14] Caught NoSuchAlgorithmException while doing SSL Connection. See attached Throwable for details. ERRORCODE=-4499, SQLSTATE=null. ERRORCODE=-4499, SQLSTATE=08001
Soln : Verify the sslVersion supported by the DB2 server and provide only supported sslVersion in the connection string or datasource.
- When sslConnection=false is set when trying to connect to SSL port we get the below error:
Error:com.ibm.db2.jcc.am.DisconnectNonTransientException: [jcc][t4][2034][11148][4.32.14] Execution failed due to a distribution protocol error that caused deallocation of the conversation. A DRDA Data Stream Syntax Error was detected. Reason: 0x3. ERRORCODE=-4499, SQLSTATE=58009
Soln : Do not forget to set the sslConnection=true for a DB2 SSL connection.
- When the property sslConnection is not set to true for getting a SSL DB2 connection we get the below error:
Error:com.ibm.db2.jcc.am.DisconnectNonTransientException: [jcc][t4][2034][11148][4.32.14] Execution failed due to a distribution protocol error that caused deallocation of the conversation. A DRDA Data Stream Syntax Error was detected. Reason: 0x3. ERRORCODE=-4499, SQLSTATE=58009
Soln : Always set the sslConnection=true for a DB2 SSL connection.
- When the SSL protocol versions set on the client and server are not same we get the below error. Here Client side TLSV1.2 was set and server supported only TLSV1.1
Error:Caused by: javax.net.ssl.SSLHandshakeException: Received fatal alert: protocol_version com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2030][11211][4.32.14] 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). Message: Received fatal alert: protocol_version. ERRORCODE=-4499, SQLSTATE=08001
Soln : Verify the sslVersion supported by the DB2 server and provide only supported sslVersion in the connection string or datasource.
- When the SSL port number is set incorrectly we get the below error:
Error:Caused by: java.net.ConnectException: Connection refused: connect com.ibm.db2.jcc.am.DisconnectNonTransientConnectionException: [jcc][t4][2043][11550][4.32.14] Exception java.net.ConnectException: Error opening socket to server localhost/127.0.0.1 on port 50,002 with message: Connection refused: connect. ERRORCODE=-4499, SQLSTATE=08001
Soln : Update the correct SSL port for the DB2 SSL connection.
Document Location
Worldwide
Product Synonym
IBM Data Server Driver for JDBC and SQLJ; Db2 ; Db2 Connect ; Db2 for LUW
Was this topic helpful?
Document Information
Modified date:
17 May 2023
UID
ibm11077081