Changing the default SSL keystore and truststore files

Changing the default Secure Sockets Layer keystore and truststore files

See Secure Sockets Layer for an overview of how Secure Sockets Layer (SSL) is used to provide secure connections between WebSphere Application Server clients and servers. When and why to perform this task

After installation, the administrative console HTTPS port and other server ports are configured to use digital certificates that are shipped with the product. Using the default certificates is not safe and you need to replace the default keystore and truststore files as soon as possible. However, it is more secure if you first enable global security and complete this and other configuration tasks after global security is enforced.

  1. Install the WebSphere Web server plug-ins on the same system where the application server is installed. The key management utility (iKeyman) is packaged with the Web server plug-ins. iKeyman is a graphical tool which is used for creating digital certificates and keystore files for both Web server plug-ins and application servers.

    iSeries only: Install the Web server plug-ins component on your administrative workstation. Next, map a drive from your administrative workstation to the iSeries system where the application server is installed to use iKeyman to manage keystore files on your iSeries system.

  2. Create the keystore files and public certificate files listed in the table below in the profile_root/etc directory where profile_root is the directory containing your WebSphere Application Server profile.

    keystore filepublic certificate file
    appServerKey.jksappServer.arm
    appClientKey.jksappClient.arm

    As you create each keystore file, also create a personal self-signed certificate and extract the public certificate to the corresponding public certificate file. For example:

    1. Create the keystore file profile_root/etc/appServerKey.jks. Refer to Creating a keystore file.

    2. Create a self-signed certificate in appServerKey.jks. Refer to Creating self-signed personal certificates.

    3. Extract the public certificate to profile_root/etc/appServer.arm. Refer to Extracting public certificates for truststore files

    Note: When creating appServerKey.jks and appClientKey.jks, use JKS as the key database type.

    Note: Instead of using self-signed certificates you can request certificates from a Certificate Authority (CA).

  3. In the profile_root/etc directory of your profile, create the truststore files listed in the table below.

    truststore filepublic certificate file
    appServerTrust.jksappClient.arm
    appClientTrust.jksappServer.arm
    appPluginKey.kdbappServer.arm

    As you create each truststore file, also delete all of the default signers and add the public certificates for the signers to be trusted. For example:

    1. Create the truststore file profile_root/etc/appServerTrust.jks. Refer to Creating truststore files.

    2. Delete all of the default signers from appServerTrust.jks. Refer to Deleting signer certificates.

    3. Using appClient.arm, add the public certificates to signers in appServerTrust.jks. Refer to Importing signer certificates.

    Note: When creating appPluginKey.kdb, use CMS as the key database type and when prompted for the password select stash the password to a file.

  4. Use mapped drives or FTP to copy the keystore and truststore files you created above to the profile_root/etc directory of all federated nodes and remote profiles configured in the cell. If there are no federated nodes or remote profiles configured then proceed to the next step.

    Important: Also, copy the stash (.sth) file created with your CMS keystore. For example, copy appPluginKey.sth to profile_root/etc.

  5. Replace the keystore and truststore files in the default Secure Sockets Layer (SSL) repertoires with your own keystore and truststore files. For example, replace DummyServerKeyFile.jks with appServerKey.jks and replace DummyServerTrustFile.jks with appServerTrust.jks in the node/DefaultSSLSettings repertoire. Refer to Changing the default Secure Sockets Layer repertoire key files.

    Important: For Network Deployment edition only, each node in the cell contains a default SSL repertoire. Be sure to replace the keystore and truststore files in the SSL repertoires of all nodes in the cell.

  6. Stop all Web servers configured for the cell. For Network Deployment edition only, you can stop the Web servers using the administrative console as follows:

    1. Click Servers.

    2. Click Web servers.

    3. Select all Web servers.

    4. Click Stop.

  7. Stop the application server. For Network Deployment stop the deployment manager and all node agents and application servers configured in the cell.

  8. Edit the profile_root/properties/sas.client.props and profile_root/properties/soap.client.props files to set the properties listed below for your new client keystore and truststore files.

    • com.ibm.ssl.keyStore.

    • com.ibm.ssl.keyStorePassword.

    • com.ibm.ssl.trustStore.

    • com.ibm.ssl.trustStorePassword.

    Note:For Network Deployment, edit the profile_root/properties/sas.client.props and profile_root/properties/soap.client.props files for the deployment manager and each federated node.

    Note: You can use the PropFilePasswordEncoder script to encode plain text passwords in properties files. Refer to Protecting plain text passwords.

  9. Start the application server. For Network Deployment start the deployment manager and all node agents and application servers configured in the cell.

    Important: Do not restart the deployment manager before you complete the steps for changing the default Secure Sockets Layer repertoire key files for the federated nodes. If you restart the deployment manager before you change the default SSL key files for the federated nodes, the deployment manager cannot communicate with the federated nodes with global security enabled. To fix this, revert the deployment manager default SSL key files back to the original key and trust files and restart the deployment manager.

    Note: All WebSphere clients that are running must also be restarted

  10. Set the KeyringLocation and StashfileLocation Web server plug-in custom properties to profile_root/etc/appPluginKey.kdb and profile_root/etc/appPluginKey.sth, respectively. Refer to Web server plug-in custom properties.

    Note: Skip this step if no Web server is configured for the cell.

    Note: SSL is enabled for the Web server plug-in in the default configuration.

  11. Regenerate the plug-in configuration files for all Web servers. Refer to Regenerating the Web server plug-in configuration file.

  12. Start all Web servers configured for the cell. For Network Deployment edition only, you can start the Web servers using the administrative console as follows:

    1. Click Servers.

    2. Click Web servers.

    3. Select all Web servers.

    4. Click Start.

Result

The default keystores and truststores are replaced in the SSL configuration protecting the administrative console HTTPS port and in all other default SSL configurations in the cell.

What to do next

Other than replacing the default keystore and truststore files, the SSL configuration within the cell remains unchanged. If additional SSL configuration changes are required see Configuring Secure Sockets Layer.