Using 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, 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 the iKeyman utility on your workstation. For more information, see The iKeyman utility.

  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. For more information, see The iKeyman utility.

  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 com.ibm.as400.ibmonly.net.ssl.Provider is specified as security provider through 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.as400.ibmonly.net.ssl.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLServerSocketFactoryImpl

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

security.provider.6=com.ibm.as400.ibmonly.net.ssl.Provider
ssl.SocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLServerSocketFactoryImpl

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

Example server JSSE application code

Your application code cannot use ServerSocketFactory serverSocketFactory = SSLServerSocketFactory.getDefault() to obtain the ServerSocketFactory unless com.ibm.as400.ibmonly.net.ssl.Provider is specified as security provider through 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.as400.ibmonly.net.ssl.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLServerSocketFactoryImpl

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

security.provider.6=com.ibm.as400.ibmonly.net.ssl.Provider
ssl.SocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.as400.ibmonly.net.ssl.SSLServerSocketFactoryImpl

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