Configuring the Java Runtime Environment to use SSL
Before you can use Secure Sockets Layer (SSL) connections in your JDBC and SQLJ applications, you need to configure the Java™ Runtime Environment to use SSL. An example procedure is provided. However, the procedure might be different depending on the Java Runtime Environment that you use.
Before you begin
- The Java Runtime Environment must include a Java security provider. The IBMJSSE2 provider, the IBMCAC provider, or the SunJSSE provider must be installed. The IBMJSSE2 provider is automatically installed with the IBM® SDK for Java.Restriction: You can use the SunJSSE provider only with an Oracle Java Runtime Environment. The SunJSSE provider does not work with an IBM Java Runtime Environment.
- SSL support must be configured on the database server.
Procedure
To configure your Java Runtime Environment to use SSL, follow these steps:
-
Import a certificate from the database server to a Java
truststore on the client.
Use the Java keytool utility to import the certificate into the truststore.
Example: Suppose that the server certificate is stored in a file named cacerts. Issue the following keytool utility statement to read the certificate from file jcc.cacert, and store it in a truststore named cacerts.keytool -import -file jcc.cacert -keystore cacerts
Example: Suppose that the server certificate is stored in a file named mydbserver.arm. Issue the following keytool utility statement to read the certificate from file mydbserver.arm, and store it in a truststore named mynewdbclient.jks.keytool -import -trustcacerts -alias myalias -file mydbserver.arm -keystore mynewdbclient.jks
-
Configure the Java Runtime Environment for the Java security providers by adding entries to the
java.security file.
The format of a security provider entry is:
security.provider.n=provider-package-name
A provider with a lower value of n takes precedence over a provider with a higher value of n.
- If you use the SunJSSE provider, add entries for the Oracle security providers to your java.security file.
- If you use the IBMCAC provider, add entries for the Oracle security providers and the IBMCAC provider to your java.security file.
For more information about the IBMCAC provider, see IBM Common Access Card (CAC) provider for Java.
- If you use the IBMJSSE2 provider, follow these steps:
- If you do not need to operate in FIPS-compliant mode:
Ensure that entries for the IBMJSSE2 provider and the IBMJCE provider are in the java.security file. The java.security file that is shipped with the IBM SDK for Java contains entries for those providers.
- If you need to operate in FIPS-compliant mode:
- Add an entry for the IBMJCEFIPS provider to your java.security file before the entry for the IBMJCE provider. Do not remove the entry for the IBMJCE provider.
- Enable FIPS mode in the IBMJSSE2 provider. See step 3.
Restriction: If you use the IBMJSSE2 provider on the Solaris operating system, you need to include an entry for the SunJSSE provider before entries for the IBMJCE, IBMJCEFIPS, or IBMJSSE2 providers. - If you do not need to operate in FIPS-compliant mode:
Example: If you need to run in FIPS-compliant mode, and you enabled FIPS mode in the IBMJSSE2 provider, use a java.security file similar to this example:
# Set the Java security providers security.provider.1=com.ibm.jsse2.IBMJSSEProvider2 security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.security.sasl.IBMSASL
Example: If you are using the SunJSSE provider, use a java.security file similar to this example:
# Set the Java security providers security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.rsajca.Provider security.provider.3=com.sun.crypto.provider.SunJCE security.provider.4=com.sun.net.ssl.internal.ssl.Provider
Example: If you are using the IBMCAC provider, use a java.security file similar to this example:
# Set the Java security providers security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.rsajca.Provider security.provider.3=com.sun.crypto.provider.SunJCE security.provider.4=com.sun.net.ssl.internal.ssl.Provider security.provider.10=com.ibm.security.capi.IBMCAC
-
If you plan to use the IBM Data Server Driver for JDBC and
SQLJ in
FIPS-compliant mode, you need to set the
com.ibm.jsse2.JSSEFIPS
Java system property:com.ibm.jsse2.JSSEFIPS=true
Restriction: Non-FIPS-mode JSSE applications cannot run in a JVM that is in FIPS mode.Restriction: When the IBMJSSE2 provider runs in FIPS mode, it cannot use hardware cryptography. -
Configure the Java Runtime Environment for the SSL socket
factory providers by adding entries to the java.security file. This step is not
necessary if you are using the SunJSSE provider and the Java
Runtime Environment, 7 or later.
The format of SSL socket factory provider entries is shown:
ssl.SocketFactory.provider=provider-package-name ssl.ServerSocketFactory.provider=provider-package-name
Specify the SSL socket factory provider for the Java security provider that you are using.
Example: When you enable FIPS mode in the IBMJSSE2 provider, include SSL socket factory provider entries in the java.security file:
# Set the SSL socket factory provider ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
Example: When you enable FIPS mode in the IBMJSSE2 provider, include SSL socket factory provider entries in the java.security file:
# Set the SSL socket factory provider ssl.SocketFactory.provider=com.ibm.fips.jsse.JSSESocketFactory ssl.ServerSocketFactory.provider=com.ibm.fips.jsse.JSSEServerSocketFactory
Example: When you use the SunJSSE provider, and the Java Runtime Environment, 6 or earlier, include SSL socket factory provider entries:
# Set the SSL socket factory provider ssl.SocketFactory.provider=com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl ssl.ServerSocketFactory.provider=com.sun.net.ssl.internal.ssl.SSLServerSocketFactoryImpl
-
Configure Java system properties to use the
truststore.
To do that, set the following Java system properties:
- javax.net.ssl.trustStore
- Specifies the name of the truststore that you specified with the -keystore parameter in the
keytool utility in step 1.
If the IBM Data Server Driver for JDBC and SQLJ property DB2BaseDataSource.sslTrustStoreLocation, db2.jcc.override.sslTrustStoreLocation, or db2.jcc.sslTrustStoreLocation is set, its value overrides the javax.net.ssl.trustStore property value.
- javax.net.ssl.trustStorePassword (optional)
- Specifies the password for the truststore. You do not need to set a truststore password.
However, if you do not set the password, you cannot protect the integrity of the
truststore.
If the IBM Data Server Driver for JDBC and SQLJ property DB2BaseDataSource.sslTrustStorePassword, db2.jcc.override.sslTrustStorePassword, or db2.jcc.sslTrustStorePassword is set, its value overrides the javax.net.ssl.trustStore property value.
If you are using a trusted certificate file (if DB2BaseDataSource.sslCertLocation, db2.jcc.override.sslCertLocation, or db2.jcc.sslCertLocation is set), the javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword values are not used.
Example: One way that you can set Java system properties is to specify them as the arguments of the -D option when you run a Java application. Suppose that you want to run a Java application that is named MySSL.java, which accesses a data source by using an SSL connection. If you defined a truststore named cacerts, then the following command sets the truststore name when you run the application.
java -Djavax.net.ssl.trustStore=cacerts MySSL
- To enable the IBMCAC provider, override the default truststore and keystore definitions:
-Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.keyStoreType=Windows-MY