Configuring connections under the IBM Data Server Driver for JDBC and SQLJ to use SSL

To configure database connections under the IBM® Data Server Driver for JDBC and SQLJ to use SSL, you need to set the DB2BaseDataSource.sslConnection property to true.

Before you begin

Before a connection to a data source can use SSL, the port to which the application connects must be configured in the database server as the SSL listener port.

Procedure

  1. Set DB2BaseDataSource.sslConnection on a Connection or DataSource instance. Alternatively, set the db2.jcc.override.sslConnection or db2.jcc.sslConnection configuration parameter on the driver instance.
  2. Optional: Set the location of the truststore and the truststore password. The truststore location can be set without the password, but it is best to set both values.
    1. Set DB2BaseDataSource.sslTrustStoreLocation on a Connection or DataSource instance to identify the location of the truststore. Alternatively, set the db2.jcc.override.sslTrustStoreLocation or db2.jcc.sslTrustStoreLocation configuration parameter on the driver instance.
      Setting the sslTrustStoreLocation property is an alternative to setting the Java™ javax.net.ssl.trustStore property. If you set DB2BaseDataSource.sslTrustStoreLocation, javax.net.ssl.trustStore is not used.
    2. Optional: Set DB2BaseDataSource.sslTrustStorePassword on a Connection or DataSource instance to identify the truststore password. Alternatively, set the db2.jcc.override.sslTrustStorePassword or db2.jcc.sslTrustStorePassword configuration parameter on the driver instance.
      Setting the sslTrustStorePassword property is an alternative to setting the Java javax.net.ssl.trustStorePassword property. If you set DB2BaseDataSource.sslTrustStorePassword, javax.net.ssl.trustStorePassword is not used.
  3. Optional: Set DB2BaseDataSource.sslCipherSuites on a Connection or DataSource instance, if you do not want to use the default cipher suites that are enabled in the JRE (Java Runtime Environment). The driver enables only the cipher suites that you set.
  4. Optional: Set the location of the keystore, the keystore password, and the keystore type. These parameters are applicable only for mutual authentication or client certificate authentication, which is enabled only in Db2® for z/OS®.
    1. Set DB2BaseDataSource.sslKeyStoreLocation on a Connection or DataSource instance to identify the location of the keystore. Alternatively, set the db2.jcc.override.sslKeyStoreLocation or db2.jcc.sslKeyStoreLocation configuration parameter on the driver instance. Setting the sslKeyStoreLocation property is an alternative to setting the Java javax.net.ssl.keyStore property. If you set DB2BaseDataSource.sslKeyStoreLocation, javax.net.ssl.keyStore is not used.
    2. Set DB2BaseDataSource.sslKeyStorePassword on a Connection or DataSource instance to identify the keystore password. Alternatively, you can set the db2.jcc.override.sslKeyStorePassword or db2.jcc.sslKeyStorePassword configuration parameter on the driver instance. Setting the sslKeyStorePassword property is an alternative to setting the Java javax.net.ssl.keyStorePassword property. If you set DB2BaseDataSource.sslKeyStorePassword, javax.net.ssl.keyStorePassword is not used.
    3. Set DB2BaseDataSource.sslKeyStoreType on a Connection or DataSource instance to identify the keystore type. Alternatively, set the db2.jcc.override.sslKeyStoreType or db2.jcc.sslKeyStoreType configuration parameter on the driver instance. Setting the sslKeyStoreType property is an alternative to setting the Java javax.net.ssl.keyStoreType property. If you set DB2BaseDataSource.sslKeyStoreType, javax.net.ssl.keyStoreType is not used.
  5. Optional: For a connection to a Db2 for z/OS data server, set DB2BaseDataSource.sslTrustStoreType on a Connection or DataSource to specify the type of sslTrustStore. Alternatively, set the db2.jcc.override.sslTrustStoreType or db2.jcc.sslTrustStoreType configuration parameter on the driver instance.
  6. Optional: Set DB2BaseDataSource.keyUsage on a Connection or DataSource to select the keyUsage based certificates from WINDOWS-MY of keyStore type. The PKI Card supports WINDOWS-MY type keyStore and WINDOWS-ROOT of trustStore type. Alternatively, set the db2.jcc.override.keyUsage or db2.jcc.keyUsage configuration parameter on the driver instance. The keyUsage is only for client certificate selection. It doesn’t apply on server certificate for server certificate authentication.
    If DataSource or Connection is configured with securityMechanism TLS_CLIENT_CERTIFICATE_SECURITY, then keyUsage is applied on connection object to select the client certificate. If DataSource or Connection is not configured with securityMechanism TLS_CLIENT_CERTIFICATE_SECURITY, the JCC driver ignores keyUsage and proceeds with the default settings for an SSL connection.
  7. Optional: Set DB2BaseDataSource.sslCertLocation on a Connection or DataSource to specify the location of a trusted certificate file.
    Alternatively, you can set the db2.jcc.override.sslCertLocation or db2.jcc.sslCertLocation configuration parameter on the driver instance.

    If sslConnection property is set to true, and both sslCertLocation and sslTrustStoreLocation properties are configured, IBM Data Server Driver for JDBC and SQLJ gives precedence to the sslCertLocation property and ignores the sslTruststoreLocation configuration. Therefore, only the certificate that is supplied through sslCertLocation is considered trusted for an SSL connection with a Db2 server.

Example

The following example demonstrates how to set the sslConnection property on a Connection instance:
java.util.Properties properties = new java.util.Properties();
properties.put("user", "xxxx");
properties.put("password", "yyyy");
properties.put("sslConnection", "true");
java.sql.Connection con = 
  java.sql.DriverManager.getConnection(url, properties);