Creating Custom Secure Socket Layer (SSL) Key Files for V5.0 using Self-Signed Certificates.
 Technote (troubleshooting)
 
Problem(Abstract)
This document describes the steps necessary to replace the Dummy key files shipped with IBM® WebSphere® Application Server V5.0 using self-signed certificates.
 
Resolving the problem
If you are using WebSphere Application Server Network Deployment Manager, you should disable security in the cell BEFORE following the instructions below!
Creating The Custom SSL Key Files

I. Server Key File

The Server Key file is created using the Ikeyman utility. The Ikeyman utility can be found in the $WAS_HOME/bin directory. On Microsoft® Windows® Systems, the file is called ikeyman.bat and on UNIX® or Linux®, the file is called ikeyman.sh.

  1. Create a new JKS file by selecting Key Database File > New.
  2. Enter the following information to create the key file > Click OK.
    File Name: ServerKey.jks
    Location Name: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location name should be relative to your installation of WebSphere Application Server in the etc directory.
  3. Enter a password for your key file > Click OK.
  4. Select Create > New Self-Signed Certificate.
  5. Enter the following information to create the certificate > Click OK.
    Key Label: WebSphere Server Key
    Common Name: <hostname>
    Organization: WebSphere

    Note: The hostname should be set by default.
  6. Select Extract Certificate.
  7. Enter the following information to extract the public certificate > Click OK.
    Certificate File Name: ServerKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc
    Note: Your location should be relative to your installation of WebSphere Application Server in the etc directory.
  8. Select Key Database File > Close.
II. Client Key File

The Client Key file is created using the Ikeyman utility. The Ikeyman utility can be found in the $WAS_HOME/bin directory. On Windows Systems, the file is called ikeyman.bat and on UNIX or Linux, the file is called ikeyman.sh.
  1. Create a new JKS file by selecting Key Database File > New.
  2. Enter the following information to create the key file > Click OK.
    File Name: ClientKey.jks
    Location Name: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location name should be relative to your installation of WebSphere Application Server in the etc directory.
  3. Enter a password for your key file > Click OK.
  4. Select Create > New Self-Signed Certificate.
  5. Enter the following information to create the certificate > Click OK.
    Key Label: WebSphere Client Key
    Common Name: <hostname>
    Organization: WebSphere

    Note: The hostname should be set by default.
  6. Select Extract Certificate.
  7. Enter the following information to extract the public certificate > Click OK.
    Certificate File Name: ClientKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location should be relative to your installation of WebSphere Application Server in the etc directory.
  8. Select Key Database File > Close.

III. Plug-in Key File

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

Windows: C:\Program Files\IBM\GSKX\bin\gskXikm.exe
Solaris: /opt/ibm/gskX/bin/gskXikm
HP: /opt/ibm/gskX/bin/gskXikm
AIX: /usr/opt/ibm/gskX/bin/gskXikm
Linux: /usr/local/ibm/gskX/bin/gskXikm
  1. Create a new KDB file by selecting Key Database File > New.
  2. Enter the following information to create the key file > Click OK
    File Name: PluginKey.kdb
    Location Name: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location name should be relative to your installation of WebSphere Application Server in the etc directory.
  3. Enter a password for your key file and select the check box entitled Stash the password to a file > Click OK.
  4. Select Create > New Self-Signed Certificate.
  5. Enter the following information to create the certificate > Click OK.
    Key Label: WebSphere Plugin Key
    Common Name: <hostname>
    Organization: WebSphere

    Note: The IP address be set by default.
  6. Select Extract Certificate.
  7. Enter the following information to extract the public certificate > Click OK.
    Certificate File Name: PluginKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location should be relative to your installation of WebSphere Application Server in the etc directory.
  8. Select Signer Certificates from the pull down navigation menu.
  9. Select Add.
  10. Enter the following information to add the server's public certificate > Click OK.
    Certificate File Name: ServerKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc
  11. Enter a label for the client key public certificate > Click OK.

    Enter a label for the certificate: WebSphere Server CA
  12. Select Key Database File > Close.

IV. Server Trust File

The Server Trust file is created using the Ikeyman utility. The Ikeyman utility can be found in the $WAS_HOME/bin directory. On Windows Systems, the file is called ikeyman.bat and on UNIX/Linux systems, the file is called ikeyman.sh.

1. Create a new JKS file by selecting Key Database File > New.
2. Enter the following information to create the key file > Click OK.
File Name: ServerTrust.jks
Location Name: C:\Program Files\WebSphere\AppServer\etc

Note: Your location name should be relative to your installation of WebSphere Application Server in the etc directory.
3. Enter a password for your key file > Click OK.
4. Select Add.
5. Enter the following information to add the client's public certificate > Click OK.
Certificate File Name: ClientKey.arm
Location: C:\Program Files\WebSphere\AppServer\etc
6. Enter a label for the client key public certificate > Click OK.

Enter a label for the certificate: WebSphere Client CA
7. Select "Add..."
8. Enter the following information to add the server's public certificate > Click OK.
Certificate File Name: ServerKey.arm
Location: C:\Program Files\WebSphere\AppServer\etc
9. Enter a label for the server key public certificate > Click OK.

Enter a label for the certificate: WebSphere Server CA
10. Select Add.
11. Enter the following information to add the plug-in's public certificate > Click OK.
Certificate File Name: PluginKey.arm
Location: C:\Program Files\WebSphere\AppServer\etc
12. Enter a label for the plug-in key public certificate > Click OK.

Enter a label for the certificate: WebSphere Plugin CA

Optional: If you are going to enable SSL between the LDAP server and WebSphere, you will need to add the public certificate (X509 Format) from the LDAP server into this key file.
13. Select Key Database File > Close.

V. Client Trust File

The Client Trust file is created using the Ikeyman utility. The Ikeyman utility can be found in the $WAS_HOME/bin directory. On Windows systems, the file is called ikeyman.bat and on UNIX or Linux, the file is called ikeyman.sh.
  1. Create a new JKS file by selecting Key Database File > New.
  2. Enter the following information to create the key file > Click OK.
    File Name: ClientTrust.jks
    Location Name: C:\Program Files\WebSphere\AppServer\etc

    Note: Your location name should be relative to your installation of WebSphere Application Server in the etc directory.
  3. Enter a password for your key file > Click OK.
  4. Select Add.
  5. Enter the following information to add the client's public certificate > Click OK.
    Certificate File Name: ClientKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc
  6. Enter a label for the client key public certificate > Click OK.

    Enter a label for the certificate: WebSphere Client CA
  7. Select Add.
  8. Enter the following information to add the server's public certificate > Click OK.
    Certificate File Name: ServerKey.arm
    Location: C:\Program Files\WebSphere\AppServer\etc
  9. Enter a label for the server key public certificate > Click OK.

    Enter a label for the certificate: WebSphere Server CA
  10. Select "Key Database File" > Close

Note: If you are in an ND environment, you will need to copy the ServerKey.jks, ClientKey.jks, ServerTrust.jks, and ClientTrust.jks to the deployment manager and each node in the cell. The files should be placed in the same directory on each node (for example, <WAS_ROOT>/etc>).

Configuring WebSphere Application Server To Use The New Keys

Updating WebSphere Application Server

From the Administrative Console, follow these steps:

  1. Select Security > SSL > "<cell>/DefaultSSLSettings.
  2. Change the following entries to reflect the path and passwords of the new keys > Click OK.
    Key File Name: ${USER_INSTALL_ROOT}/etc/ServerKey.jks
    Key File Password: <ServerKey.jks Password>
    Trust File Name: ${USER_INSTALL_ROOT}/etc/ServerTrust.jks
    Trust File Password: <ServerTrust.jks Password>

    Note: If you are in an ND environment, you will need to update the <dmgr>/DefaultSSLSettings as well with the entries above.
  3. Save changes and logout.
  4. Restart the server process using the stopServer and startServer commands.

Note: If you are in a ND environment, you will need to restart all Servers, Node Agents, and the Deployment Manager for the new settings to take effect cell wide

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. Save the file.
    com.ibm.ssl.keyStore=C\:/Program Files/WebSphere/AppServer/etc/ClientKey.jks
    com.ibm.ssl.keyStorePassword=<ClientKey.jks Password>
    com.ibm.ssl.trustStore=C\:/Program Files/WebSphere/AppServer/etc/ClientTrust.jks
    com.ibm.ssl.trustStorePassword=<ClientTrust.jks Password>
Note: The path to your key files will be relative to your Application Server installation and platform

Updating the soap.client.props file
  1. Open the $WAS_HOME/properties/soap.client.props file in an editor.
  2. Change the following lines in the soap.client.props file to reflect the new SSL settings. Save the file.
    com.ibm.ssl.keyStore=C\:/Program Files/WebSphere/AppServer/etc/ClientKey.jks
    com.ibm.ssl.keyStorePassword=
    <ClientKey.jks Password>
    com.ibm.ssl.trustStore=C\:/Program Files/WebSphere/AppServer/etc/ClientTrust.jks
    com.ibm.ssl.trustStorePassword=
    <ClientTrust.jks Password>

    Note: The path to your key files will be relative to your Application Server installation and platform

Updating the plugin-cfg.xml file
  1. Open the $WAS_HOME/config/cells/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.Save the file.

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

    Note: The path to your key files will be relative to your Application Server installation and platform.

    Note: You will need to change all Transports that use HTTPS in the plugin-cfg.xml file.
  3. Restart the Web server for the new changes to take effect.
 
 
Cross Reference information
Segment Product Component Platform Version Edition
Application Servers Runtimes for Java Technology Java SDK
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Security
Operating system(s): Windows
Software version: 5.1
Software edition:
Reference #: 1154255
IBM Group: Software Group
Modified date: Sep 1, 2007