DB2 Version 9.7 for Linux, UNIX, and Windows

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 can configure your Java Runtime Environment for SSL, you need to satisfy the following prerequisites:

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 only 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.

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.
  - 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.
Example: Use a java.security file similar to this one if you need to run in FIPS-compliant mode, and you enable FIPS mode in the IBMJSSE2 provider:
```
# 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: Use a java.security file similar to this one if you need to run in FIPS-compliant mode, and you use the IBMJSSE provider:
```
# 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: Use a java.security file similar to this one if you use the SunJSSE provider:
```
# 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
```
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 are:
```
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: Include SSL socket factory provider entries like these in the java.security file when you enable FIPS mode in the IBMJSSE2 provider:
```
# Set the SSL socket factory provider
ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl 
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl 
```
Example: Include SSL socket factory provider entries like these in the java.security file when you enable FIPS mode in the IBMJSSE provider:
```
# Set the SSL socket factory provider
ssl.SocketFactory.provider=com.ibm.fips.jsse.JSSESocketFactory
ssl.ServerSocketFactory.provider=com.ibm.fips.jsse.JSSEServerSocketFactory
```
Example: Include SSL socket factory provider entries like these when you use the SunJSSE provider, and the Java Runtime Environment, 6 or earlier:
```
# 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 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 is set, its value overrides the javax.net.ssl.trustStorePassword property value.

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 named MySSL.java, which accesses a data source using an SSL connection. You have defined a truststore named cacerts. The following command sets the truststore name when you run the application.
```
java -Djavax.net.ssl.trustStore=cacerts MySSL
```