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 IBM® JSSE provider or the SunJSSE provider must be installed. The IBM JSSE 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.
The Java security provider entries that you add depend on whether you use the IBM JSSE provider or the SunJSSE provider.
- If you use the SunJSSE provider, add entries for the Oracle security providers to your java.security file.
- If you use the IBM JSSE provider, use one of the
following methods:
- Use the IBMJSSE2 provider (supported for the IBM SDK
for Java 1.4.2 and later):Recommendation: Use the IBMJSSE2 provider, and use it in FIPS mode.
- If you do not need to operate in FIPS-compliant mode:
- For the IBM SDK for Java 1.4.2, add an entry for the IBMJSSE2Provider to the java.security file. Ensure that an entry for the IBMJCE provider is in the java.security file. The java.security file that is shipped with the IBM SDK for Java contains an entry for entries for IBMJCE.
- For later versions of the IBM SDK for Java, ensure that entries for the IBMJSSE2Provider 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.
- If you do not need to operate in FIPS-compliant mode:
- Use the IBMJSSE provider (supported for the IBM SDK for
Java 1.4.2 only):
- If you do not need to operate in FIPS-compliant mode, ensure that entries for the IBMJSSEProvider 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 entries for the FIPS-approved provider IBMJSSEFIPSProvider and the IBMJCEFIPS provider to your java.security file before the entry for the IBMJCE provider.
Restriction: If you use the IBMJSSE provider on the Solaris operating system, you need to include an entry for the SunJSSE provider before entries for the IBMJCE, IBMJCEFIPS, IBMJSSE, or IBMJSSE2 providers. - Use the IBMJSSE2 provider (supported for the IBM SDK
for Java 1.4.2 and later):
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 need to run in FIPS-compliant mode, and you are using the IBMJSSE provider, use a java.security file similar to this example:
# Set the Java security providers security.provider.1=com.ibm.fips.jsse.IBMJSSEFIPSProvider 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
For more information about the IBMCAC provider, see Introduction to IBMCAC provider.
-
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 IBMJSSE 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 Common Access Card (IBMCAC) provider, overwrite the default truststore and
keystore definitions:
-Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.keyStoreType=Windows-MY