Use Java keystore files

If you are porting a JSSE application from another platform, or require the Java JSSE interfaces to certificate storage using Java keystore files, or require access to miscellaneous SSL implementation classes such as com.ibm.net.ssl.SSLContext then use the configuration steps below to use Java JSSE. Also, you may use Java keystore files for applications that use the java.net.URL class to provide a direct connection to the Web server through HTTPS protocol. For more information, see Configure SSL for java.net.URL HTTPS protocol.

Configure the client Java keystore

This step may be omitted if you already have a client Java keystore file populated with the required personal and signer certificates.

To configure the client Java keystore, create an SSL key file that is used for both trust validation and key storage. Peform these steps:

  1. Start iKeyman on your workstation. For more information, see IBM Key Managment Tool (iKeyman).

  2. Create a new key database file:
    1. Click Key Database File and select New.
    2. Specify settings:

      • Key database type: JKS
      • File Name: clientAppKeys.jks
      • Location: your myKeys directory, such as WAS_INSTANCE_ROOT/myKeys

    3. Click OK.
    4. Enter a password (twice for confirmation) and click OK.

  3. Click Signer Certificates and select Personal Certificates.

  4. Add a new self-signed certificate:
    1. Click New Self-Signed to add a self-signed certificate.
    2. Specify settings:

      • Key Label: clientAppTest
      • Common Name: use the DNS name for your iSeries server
      • Organization: IBM

    3. Click OK.

  5. Extract the certificate from this self-signed certificate so that it can be imported into the server application's SSL key file:
    1. Click Extract Certificate.
    2. Specify settings:

      • Data Type: Base64-encoded ASCII data
      • Certificate file name: clientAppsCA.arm
      • Location: the path to your myKeys directory

    3. Click OK.

  6. Import the server application's CA certificate from the serverAppKeys.jks file:
    1. Click Personal Certificates and select Signer Certificates.
    2. Click Add.
    3. Specify settings:

      • Data Type: Base64-encoded ASCII data
      • Certificate file name: serverAppsCA.arm
      • Location: the path to your myKeys directory

    4. Click OK.

  7. Enter serverAppsCA for the label and click OK.

  8. Click Key Database File.

  9. Select Exit.

Configure the server Java keystore

This step may be omitted if you already have a server Java keystore file populated with the required personal and signer certificates.

To configure the server Java keystore, create an SSL key file used for both trust validation and key storage. Perform these steps:

  1. Start iKeyman on your workstation. The iKeyman tool is located in the bin subdirectory of the WebSphere workstation-based tools.

  2. Create a new key database file:
    1. Click Key Database File and select New.
    2. Specify settings:

      • Key database type: JKS
      • File Name: serverAppKeys.jks
      • Location: your myKeys directory, such as WAS_INSTANCE_ROOT/myKeys

    3. Click OK.
    4. Enter a password (twice for confirmation) and click OK..

  3. Click Signer Certificates and select Personal Certificates.

  4. Add a new self-signed certificate:
    1. Click New Self-Signed to add a self-signed certificate.
    2. Specify settings:

      • Key Label: serverAppTest
      • Common Name: use the DNS name for your iSeries server
      • Organization: IBM

    3. Click OK.

  5. Extract the certificate from this self-signed certificate so that it can be imported into the client application's SSL key file:
    1. Click Extract Certificate.
    2. Specify settings:

      • Data Type: Base64-encoded ASCII data
      • Certificate file name: serverAppsCA.arm
      • Location: the path to your myKeys directory

    3. Click OK.

  6. Import the client application's CA certificate from the clientAppKeys.jks file:
    1. Click Personal Certificates and select Signer Certificates.
    2. Click Add.
    3. Specify settings:

      • Data Type: Base64-encoded ASCII data
      • Certificate file name: clientAppsCA.arm
      • Location: the path to your myKeys directory

    4. Click OK.

  7. Enter clientAppsCA for the label and click OK.

  8. Click Key Database File.

  9. Select Exit.

Example client JSSE application code

Note that your application code cannot use SocketFactory socketFactory = SSLSocketFactory.getDefault() to obtain the SocketFactory unless os400.jdk13.jst.factories=true is specified as either a command line Java virtual machine system property or a security property in the java.security file.

For fully supported use of Java keystore files, two other properties which can only be specified in the java.security file must also be set as follows:

  ssl.SocketFactory.provider=com.ibm.jsse.JSSESocketFactory
  ssl.ServerSocketFactory.provider=com.ibm.jsse.JSSEServerSocketFactory

The default java.security file in the properties directory provided for each user instance sets the three properties as follows:

  os400.jdk13.jst.factories=true
  ssl.SocketFactory.provider=com.ibm.jsse.JSSESocketFactory
  ssl.ServerSocketFactory.provider=com.ibm.jsse.JSSEServerSocketFactory

See Example: JSSE client servlet. The client keystore must be placed in the working directory of WebSphere Application Server.

Example server JSSE application code

Your application code cannot use ServerSocketFactory serverSocketFactory = SSLServerSocketFactory.getDefault() to obtain the ServerSocketFactory unless os400.jdk13.jst.factories=true is specified as either a command line Java virtual machine system property or a security property in the java.security file.

For fully supported use of Java keystore files, two other properties which can only be specified in the java.security file must also be set as follows:

  ssl.SocketFactory.provider=com.ibm.jsse.JSSESocketFactory
  ssl.ServerSocketFactory.provider=com.ibm.jsse.JSSEServerSocketFactory

The default java.security file in the properties directory provided for each user instance sets the three properties as follows:

  os400.jdk13.jst.factories=true
  ssl.SocketFactory.provider=com.ibm.jsse.JSSESocketFactory
  ssl.ServerSocketFactory.provider=com.ibm.jsse.JSSEServerSocketFactory

See Example: JSSE server servlet. The server keystore must be placed in the working directory of the WebSphere Application Server.