Creating custom Secure Socket Layer (SSL) key files for V4.0 using keytool and gsk5cmd
 Technote (FAQ)
 
Problem
This technote describes how to use the command line tools (keytool, gsk5cmd) to replace the Dummy key files shipped with WebSphere® Application Server V4.0.
 
Solution
Note: Disable security and restart the Administrative Server BEFORE following these instructions.

Creating the custom SSL Key Files

I. Server Key File

  1. Create the Server Key file and certificate:

    $WAS_HOME\java\bin\keytool -genkey -alias "WebSphere Server Key" -dname "cn=<hostname>,o=websphere,c=us" -keyalg RSA -keypass <password> -keystore $WAS_HOME\etc\ServerKey.jks -sigalg MD5withRSA -storepass <password> -validity <days>

    Note: The -keypass and -storepass must be the same.

  2. Extract the Server Key's public certificate:

    $WAS_HOME\java\bin\keytool -export -alias "WebSphere Server Key" -file $WAS_HOME\etc\ServerKey.arm -keypass <password> -keystore $WAS_HOME\etc\ServerKey.jks -rfc -storepass <password>

    Note: The -keypass and -storepass must be the same.

II. Client Key File
  1. Create the Client Key file and certificate:

    $WAS_HOME\java\bin\keytool -genkey -alias "WebSphere Client Key" -dname "cn=<hostname>,o=websphere,c=us" -keyalg RSA -keypass <password> -keystore $WAS_HOME\etc\ClientKey.jks -sigalg MD5withRSA -storepass <password> -validity <days>

    Note: The -keypass and -storepass must be the same.

  2. Extract the Client Key's public certificate:

    $WAS_HOME\java\bin\keytool -export -alias "WebSphere Client Key" -file $WAS_HOME\etc\ClientKey.arm -keypass <password> -keystore $WAS_HOME\etc\ClientKey.jks -rfc -storepass <password>

    Note: The -keypass and -storepass must be the same.


III. Plug-in Key File

The plug-in key must be created with the GSKit utility. This utility is installed to the following directories (Path might vary) during the WebSphere installation:

Windows®: C:\Program Files\IBM\GSK5\bin\gsk5cmd.exe
Solaris™: /opt/ibm/gsk5/bin/gsk5cmd
HP: /opt/ibm/gsk5/bin/gsk5cmd
AIX®: /usr/opt/ibm/gsk5/bin/gsk5cmd
Linux®: /usr/local/ibm/gsk5/bin/gsk5cmd

  1. Create the Plug-in Key file:

    <GSK_ROOT>\bin\gsk5cmd -keydb -create -db $WAS_HOME\etc\PluginKey.kdb -pw <password> -stash

  2. Create the Plug-in Key certificate

    <GSK_ROOT>\bin\gsk5cmd -cert -create -default_cert yes -db $WAS_HOME\etc\PluginKey.kdb -dn "cn=<hostname>,o=websphere,c=us" -label "WebSphere Plugin Key" -pw <password>

    Note: The password must be the same as the password used to create the Plug-in Key file.

  3. Extract the Plug-in Key's public certificate:

    <GSK_ROOT>\bin\gsk5cmd -cert -extract -db $WAS_HOME\etc\PluginKey.kdb -format ascii -label "WebSphere Plugin Key" -pw <password> -target $WAS_HOME\etc\PluginKey.arm

  4. Add the Server Key's public certificate:

    <GSK_ROOT>\bin\gsk5cmd -cert -add -db $WAS_HOME\etc\PluginKey.kdb -file $WAS_HOME\etc\ServerKey.arm -format ascii -label "WebSphere Server CA" -pw <password> -trust enable

IV. Server Trust File

Create the Server Trust File and add the Server, Client, and Plug-in keys:

$WAS_HOME\java\bin\keytool -import -alias "WebSphere Server CA" -file $WAS_HOME\etc\ServerKey.arm -keystore $WAS_HOME\etc\ServerTrust.jks -storepass <password> -noprompt

$WAS_HOME\java\bin\keytool -import -alias "WebSphere Client CA" -file $WAS_HOME\etc\ClientKey.arm -keystore $WAS_HOME\etc\ServerTrust.jks -storepass <password> -noprompt

$WAS_HOME\java\bin\keytool -import -alias "WebSphere Plugin CA" -file $WAS_HOME\etc\PluginKey.arm -keystore $WAS_HOME\etc\ServerTrust.jks -storepass <password> -noprompt



V. Client Trust File

Create the Client Trust File and add the Server and Client keys:

$WAS_HOME\java\bin\keytool -import -alias "WebSphere Server CA" -file $WAS_HOME\etc\ServerKey.arm -keystore $WAS_HOME\etc\ClientTrust.jks -storepass <password> -noprompt

$WAS_HOME\java\bin\keytool -import -alias "WebSphere Client CA" -file $WAS_HOME\etc\ClientKey.arm -keystore $WAS_HOME\etc\ClientTrust.jks -storepass <password> -noprompt


Configuring WebSphere Application Server to use the new keys

Updating WebSphere Application Server

From the administrative console, do the following:

  1. Select Console > Security Center.

  2. Click the ellipsis ( ... ) button next to Default SSL Configuration.

  3. Change the following entries to reflect the path and passwords of the new keys, then click OK.

    Key File Name: ${WAS_HOME}/etc/ServerKey.jks
    Key File Password: <ServerKey.jks Password>
    Trust File Name: ${WAS_HOME}/etc/ServerTrust.jks
    Trust File Password: <ServerTrust.jks Password>

  4. Save these changes, then stop the node.

  5. Use the adminserver command to restart the server process.

Updating the sas.client.props file
  1. Open the $WAS_HOME/properties/sas.client.props file in an editor.

  2. Change the following lines in the sas.client.props file to reflect the new SSL settings, then save the file.

    com.ibm.ssl.keyStore=C:/WebSphere/AppServer/etc/ClientKey.jks
    com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
    com.ibm.ssl.trustStore=C:/WebSphere/AppServer/etc/ClientTrust.jks
    com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>


    Note: The path to your key files is relative to your WebSphere installation and platform.

Updating the plugin-cfg.xml file
  1. Open the $WAS_HOME/config/plugin-cfg.xml file in an editor.

  2. Change the following lines in the plugin-cfg.xml file to reflect the new Plug-in SSL key, then save the file.

    <Property Name="keyring" Value="C:\WebSphere\AppServer\etc\PluginKey.kdb"/>
    <Property Name="stashfile" Value="C:\WebSphere\AppServer\etc\PluginKey.sth"/>


    Notes:
    1. The path to your key files is relative to your WebSphere installation and platform.
    2. You must change all Transports that use HTTPS in the plugin-cfg.xml file.

  3. Restart your Web server for the new changes to take effect.
 
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Security
Operating system(s): Windows
Software version: 4.0
Software edition:
Reference #: 1156606
IBM Group: Software Group
Modified date: Mar 27, 2006