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

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 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.
  - 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: 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
```