WebSphere Application Server & Liberty

 View Only

WebSphere Application Server Data Source driver connection over SSL with Database server

By Ajit Jariwala posted Wed October 06, 2021 04:02 PM



This blog focuses on SSL connectivity from WebSphere Application Server – JDBC provider and data source configuration with backend database server. 

SSL - stands for Secure Sockets Layer and, in short, SSL is the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two systems over a network. In this blog, the connection we want to secure is between WebSphere and a backend Database server. 


What is the SSL handshake? 

Communication using SSL begins with an exchange of information between the client (WebSphere) and the server (Database) to negotiate the SSL protocol components. This exchange of information is called the SSL handshake.

The three main purposes of the SSL handshake are to: 

1.Negotiate the cipher suite 

The SSL session begins with a negotiation between the client and the server as to which cipher suite they will use. A cipher suite is a set of cryptographic algorithms and key sizes to encrypt data.

2.Authenticate identity 

Authenticating the server allows the client to be sure that the server represents the entity that the client believes the server represents.

3.Establish information security by agreeing on encryption mechanisms 

The client and server exchange information that allows them to agree on the same secret key. For example, with RSA, the client uses the server's public key, obtained from the public key certificate, to encrypt the secret key information.

SSL - TLSv1 and TLSv1.1 Protocol are deprecated and considered insecure. TLSv1.2 and TLSv1.3 are the new industry standard protocols that are considered secure.

WebSphere Secure connection Data Source architecture flow: 

SSL runtime for JDBC Driver

Simplified runtime SSL flow connecting to database


Common questions 

These are common questions we receive when talking to customers about setting up TLS connections to backend databases. These answers are general, and database specific configurations are discussed later on in this blog. 

Client: WebSphere Application Server - JDBC provider/ Data Source driver - Where a JDBC Provider is configured (using a JDBC Driver jar file), under which a Data Source is defined, to be used by an application running on the WAS server to establish connections to a Database Server. 

Server: Database Server – Example: (IBM DB2, MS SQL server, Oracle) etc.

What JDBC data source driver custom properties need to be configured in WebSphere? 

Answer: This depends on type of database and driver used for connection.

How does the WebSphere decide which TLS protocol the JDBC driver should use? 

Answer: WebSphere and the JDBC driver both use the underlying Java Virtual Machine (JVM) to create TLS connections. The WebSphere administrator can restrict the TLS protocols available to the JVM and can further restrict the protocols used by the JDBC driver.

How does the WebSphere decide which ciphers are used? 

Answer: The JVM and JVM settings can restrict the list of ciphers which are available at runtime. 

High strength (AES_256) ciphers require installation of the JDK unrestricted policy files. List of cipher supported by IBM Java -

And SDK Security policy files - https://www.ibm.com/docs/en/sdk-java-technology/8?topic=guide-sdk-security-policy-files#sdkpolicyfiles 

As exploits are identified for various cipher suites, those cipher suites will be disabled by the WebSphere Application Server/Java runtime to keep our customers safe. 

Each handshake protocol supports only a subset of the cipher suites made available by the JVM. 

When the SSLContext for the connection is created by the JDBC driver, the list of cipher suites from Java can be further reduced using driver specific settings. 

Note: for the DB2 JDBC driver prior to version 4.3, the list can be reduced by modifying the cipher suite settings in WAS Security Navigate to WAS Security > Global Security > SSL Certificate and key management > SSL Configurations > [NodeDefaultSSLSettings /Or CellDefaultSSLSettings ] > Quality of Protection (QoP) page. 

How does WebSphere decide which keystore/truststore is used? 

Answer: Since WebSphere and the JDBC Driver both use the underlying JVM to create TLS connections. Keystore and trustore settings can be set globally on the JVM or individually on the JDBC driver. We recommend setting keystore settings individually on the JDBC driver for better decoupling of application server config from JDBC driver config. 

Setup TLS on your system 

Identify Current Level of Java: 

Run WAS_HOME/java/bin/java -version to find out the java versions. 

To Verify Java SDK version shipped with IBM WebSphere Application Server fix packs: 

Minimum Java version to support TLSv1.2 

  • Java 6 – SR10 FP1  --- > Out of support 
  • Java 7 – SR9 FP50 
  • Java 7.1 –SR3 FP50 
  • Java 8 –SR3 FP10 

Minimum Java for TLSv1.3 

  • Java 8 ( and above) – for traditional WebSphere Application Server 
  • WebSphere Liberty – openJ9 and JDK 11 or IBM Java 8 ( 

Note: - Please engage vendor driver support team to confirm which version of driver supported with TLSv1.3 

JDBC Driver specific SSL/TLS configuration:

DB2 Driver 

DB2 driver: DB2 JDBC Driver Versions and Downloads 

Minimum requirement to set up DB2 Driver SSL setup: 

  1. Go to IBM WebSphere Application Server console
  2. Click - Resources - JDBC - Data sources > myDataSource > Custom properties

WebSphere Application Server data source properties: 

Add the following custom properties: 

  • sslConnection=true (db2 driver custom properties) 
  • sslVersion=<version of protocol> (e.g., TLSv1.2) 
  • sslTrustStoreLocation=<trustStorelocation path> 
  • sslTrustStroePassword=<password> 

Note: SSL truststore properties are required only if you do not want to add signer in WebSphere SSL configuration trustStore, best practice would be to be defined at driver code level custom properties. 

Mutual Authentication enabled on Server side (Database Server) 

  • securityMechanism=18 
  • sslKeyStoreLocatoin=<keyStorelocation path> 
  • sslKeyStorePassword=<password> 

Note: - The WebSphere Application Server SSL settings are used for the DB2 JDBC 4.2 or earlier release. When the WAS certificates are used, 

In ND signer certificate should be trusted with CellDefaultTrustStore In Base environment it should be trusted with NodeDefaultTrustStore. 

It can be customized a separate SSL configuration used only for the JDBC configuration. This is called a dynamic outbound SSL configuration.

Microsoft SQL Driver 

Microsoft server-side settings: 

    Note: - For further assistant on server side and driver, IBM support recommend engaging vendor support. 

    Microsoft SQL driver SSL setup on WebSphere Application Server side with minimum requirement 

    Microsoft SQL driver: 

    1. Go to IBM WebSphere Application Server console
    2. Click - Resources - JDBC - Data sources > myDataSource > Custom properties

    Add the following custom property : 

    • sslProtocol=TLSv1.2 
    • encrypt=true (Indicates if SSL (Secure Sockets Layer) encryption should be used for communication with the database. 

    One of two ways to determine trust: 

    • trustServerCertificate=true (default is false) – Determines if the JDBC driver validates the SSL certificate of the database. A value of false causes the JDBC driver to validate the SSLcertificate, applied only when encrypt is true. 

    Note: - By enabling true, not require any server certificate to be trusted with client. If its false then signer certificate from database server should be trusted with client trustStore, another word client side trustStore file. Only for testing purpose or if you want to accept any trusted certificate from database, once its works, then suggest disabled as default with false, then add below two properties to setup signer certificate. 

    • trustStore=<trustStore path> 
    • trustStorePassword=<myPassword> 
    • hostNameInCertificate=<hostname> - Host name is used to validate the SSL certificate of the database, this also applied only when encrypt is set to true. And trustServerCertificate is false. 

    Default used by MS SQL driver as java layer CACERTS or you can define explicitly trustStore file and password using driver custom properties. 

    Microsoft JDBC Driver and TLSv12 

    –At minimum JDBC version 4.1 is needed (JDBC driver version 4.0 is already out of support)

    Oracle driver 

    SSL connection using Oracle Thin Driver and Oracle Wallets 

    The Following Oracle blog provides clear steps to establish an SSL connection over TLSv1.2 using the JDBC thin driver with either JKS files or a wallet. 

    Oracle Driver: 

    Minimum requirement on WebSphere Application Server side. 1. Ensure that Java is current or as latest build as possible 

    2. You should have following jars in classpath for Oracle Wallet to work. 

    ojdbcdriver, oraclepki, osdt_core, and osdt_certin 

    Oracle JDBC driver specific properties 

    • The Oracle JDBC driver has added support for a new Custom Properties under connectionProperties. 
    • The method used with datasources is to set a Custom Property in the datasource as follows: 
    • Name: connectionProperties Value: propertyA=valueA;propertyB=valueB 

    Using Oracle JDBC driver specific properties through a datasource 


    1. Go to IBM WebSphere Application Server console
    2. Click - Resources - JDBC - Data sources > myDataSource > Custom properties


    • oracle.net.ssl_version=1.2 
    • oracle.net.ssl_server_dn_match=false 
    • oracle.net.authentication_services=TCPS 
    • oracle.net.wallet_location={location}; 

    Name: connectionProperties 

    Value: oracle.net.ssl_version=1.2;oracle.net.ssl_server_dn_match=false;oracle.net.authentication_services=TCPS;oracle.net.wallet_location=/work/security/oracle/; 

    Description: Set of properties that will be passed to the Oracle JDBC driver to be used when creating new connections. 

    Type: java.lang.String 


    URL connection property: 


    Note: - This URL should match the corresponding entry in tnsnames.ora

    MySQL driver (connector) 

    Configuration properties define how Connector/J will make a connection to a MySQL server. 

    1. Go to IBM WebSphere Application Server console
    2. Click - Resources - JDBC - Data sources > myDataSource > Custom properties

    For 8.0.12 and earlier: As long as the server is correctly configured to use SSL, there is no need to configure anything on the Connector/J client to use encrypted connections (the exception is when Connector/J is connecting to very old server versions like 5.6.25 and earlier or 5.7.5 and 

    earlier, in which case the client must set the connection property useSSL=true in order to use encrypted connections). The client can demand SSL to be used by setting the connection property requireSSL=true; the connection then fails if the server is not configured to use SSL. Without requireSSL=true, the connection just falls back to non-encrypted mode if the server is not configured to use SSL.

    PostgreSQL JDBC driver 

    There are a number of connection parameters for configuring the client for SSL. See SSL Connection parameters 

    Configuring the Client: 

    MongoDB JDBC driver 

    The Java driver supports SSL connections to MongoDB servers using the underlying support for SSL provided by the JDK. You can configure the driver to use SSL either with MongoClientURI or with MongoClientOptions. 

    With MongoClientURI, specify `ssl=true as a query parameter, as in: 

    • SSL - Java driver supports SSL connections to MongoDB server 

    Example: - mongodb://localhost/?ssl=true

    Sybase Driver 

    The Sybase driver supports SSL for data encryption. SSL secures the integrity of your data by encrypting information and providing authentication. See Data Encryption Across the Network for an overview. 


    Connection hangs can occur when the driver is configured for SSL and the database server does not support SSL. You may want to set a login timeout using the LoginTimeout property to avoid problems when connecting to a server that does not support SSL. 


    To configure SSL encryption: 

    1. Set the EncryptionMethod property to SSL. 

    2. Specify the location and password of the truststore file used for SSL server authentication. Either set the TrustStore and TrustStore properties or their corresponding Java system properties (javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword, respectively). 

    3. To validate certificates sent by the database server, set the ValidateServerCertificate property to true. 

    4. Optionally, set the HostNameInCertificate property to a host name to be used to validate the certificate. The HostNameInCertificate property provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested. 

    Sybase support page type 4 driver. 

    Data Encryption Across the Network 


    JVM system properties: 

    A typical application will need to set several JVM system properties to ensure that the client is able to validate the SSL certificate presented by the server: 

    Some JDBC driver may require setting SSL configuration property as JVM system properties, please review JDBC driver vendor (third-party) documentation for JDBC driver SSL setup. 

    • javax.net.ssl.keyStore: the path to a key store containing the client’s SSL certificates 
    • javax.net.ssl.keyStorePassword: the password to access this key store 
    • javax.net.ssl.trustStore: the path to a trust store containing the certificate of the signing authority 
    • javax.net.ssl.trustStorePassword: the password to access this trust store 

    The trust store is typically created with the keytool command line program provided as part of the JDK.

    For example: 

    keytool -importcert -trustcacerts -file <path to certificate authority file> -keystore <path to trust store> -storepass <password> 

    General Knowledge comments: 

    Some drivers use SSLContext for the connection, which was hard coded TLS, but IBM JDK provided fix to override, some driver code might still require as workaround by setting these two properties. This workaround would be to use as last resources. First and recommended best practice to use driver level SSL protocol properties for data source. 

    Generic jvm arguments (JVM settings):

    • -Dcom.ibm.jsse2.overrideDefaultTLS=true
    • -Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12

    Use the system property com.ibm.jsse2.overrideDefaultTLS to match the behavior of SSLContext.getInstance("TLS") in the IBM SDK with the Oracle implementation. Start of changes for service refresh 6 fix pack 25In service refresh 6, fix pack 25, the IBM implementation changed to match the Oracle implementation, so this property no longer has any effect. This property is deprecated and might be removed in a future release. JDK IBM implementation of SSLContext.getInstance("TLS") now matches Oracle
    The IBM implementation of SSLContext.getInstance("TLS") is changed to match Oracle: specifying TLS in this method now enables the TLS V1.0, V1.1, and V1.2 protocols. As a result, the -Dcom.ibm.jsse2.overrideDefaultTLS system property is redundant and no longer has any effectEnd of changes for service refresh 6 fix pack 25

    com.ibm.jsse2.overrideDefaultTLS =[true|false]

    NOTE:- Further more detailed on JDK customize --- JDK Knowledge Center

    More info about JDK 8 -
    What's New

    If you have not explicitly configured an SSL socket factory, you can use a system property to override the SSL protocol that is specified by the default SSL socket factory.

    To improve security, SSL socket factories should be explicitly configured instead of using the default SSL socket factory. The use of system properties to configure SSL socket factories is not recommended. However, the system property com.ibm.jsse2.overrideDefaultProtocol can be specified to set a different SSL protocol at run time.





    After following this doc does not resolve SSL / TLS configuration issue for your specific driver, then we would recommend deep dive by enabling following trace and/or open a ticket with IBM Support 

    Deep dive by enabling trace: 

    JDBC trace 

    PostgreSQL JDBC driver logging: 

    Informix, Microsoft SQL, DB2, Oracl, Sybase, Derby JDBC driver trace in WebSphere. 

    Mustagher J2C 

    Mustgather SSL/JSSE