Creating Custom Secure Socket Layer (SSL) Key Files for V4.0
 Technote (FAQ)
 
Problem
This document describes the steps necessary to replace the Dummy key files shipped with WebSphere® Application Server V4.0 using self-signed certificates.
 
Solution
Note: You should disable security and restart the Admin Server 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 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: ServerKey.jks
Location Name: C:\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:\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" -> Exit

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/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: ClientKey.jks
Location Name: C:\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:\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" -> Exit

III. Plugin Key File

The plugin 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\GSK5\bin\gsk5ikm.exe
Solaris: /opt/ibm/gsk5/bin/gsk5ikm
HP: /opt/ibm/gsk5/bin/gsk5ikm
AIX: /usr/opt/ibm/gsk5/bin/gsk5ikm
Linux: /usr/local/ibm/gsk5/bin/gsk5ikm
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:\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:\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:\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:\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:\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:\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 plugin's public certificate -> Click OK

Certificate File Name: PluginKey.arm
Location: C:\WebSphere\AppServer\etc

12) Enter a label for the plugin 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" -> Exit

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/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: ClientTrust.jks
Location Name: C:\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:\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:\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" -> Exit
Configuring WebSphere Application Server To Use The New Keys

Updating WebSphere Application Server

From the Admin Console, do the following:

1) Select "Console" -> "Security Center..."

2) Click the "..." button next to "Default SSL Configuration"

3) Change the following entries to reflect the path and passwords of the new keys -> 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>

3) Save changes and stop the node

4) Restart the server process using the adminserver command

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:/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 will be 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 Plugin SSL key -> Save the file

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

Note: The path to your key files will be relative to your WebSphere installation and platform
Note: You will need to 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 #: 1157165
IBM Group: Software Group
Modified date: Sep 10, 2004