Replace Default Dummy Keyrings with Self-signed Keyring Certificate
 Technote (FAQ)
 
Problem
How to replace WebSphere's Dummykeyring with another self-signed keyring.
 
Solution
By default WebSphere uses its own keyring for "internal SSL" communication whenever security has been enabled. The "internal SSL" communication is only between the Admin Server processes and Application Server processes and has nothing to do with communication between the webserver's plugin and the Application Server (HTTPS transport).

Overview:

Use the following steps:

1. Create a new ServerKeyFile to replace the default DummyServerKeyFile.

2. Create a new ServerTrustFile to replace the default DummyServerTrustFile.

3. Create a new ClientKeyFile to replace the default DummyClientKeyFile.

4. Create a new ClientTrustFile to replace the default DummyClientTrustFile.

5. Update the WebSphere security configuration to pick up these files.


WebSphere's 4.0 infocenter gives step-by-step instruction for creating your own keyfiles.
(www.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/)
5.5.6.2.1.1 Creating a server key store
This will show how to:
Create a keyfile.jks file
Create a self-signed certificate in the keyfile.jks file.
Export the signer certificate from the keyfile.jks to a cert.arm file.
5.5.6.2.1.2 Creating a client trust store
This will show how to
Create a trust.jks
Add the signer certificate exported from the keyfile.jks to the new trust.jks file.

Follow the steps in section 5.5.6.2.1.1 to create the ServerKeyFile. The self-signed certificate will only have to be created once in the ServerKeyFile. Then export the certificate as a cert.arm file to be used later in the ServerTrustFile, ClientKeyFile, and ClientTrustFile. You will then need to take one additional step not listed in section 5.5.6.2.1.1 to add the certificate back into the ServerKeyFile just created. To do this, go to signer certificates and add the cert.arm file.

The instructions for section 5.5.6.2.1.2 "Creating a client trust store" will be the same for the trust and client files (ServerTrustFile, ClientKeyFile and ClientTrustFile). The cert.arm exported from the ServerKeyFile is what gets added to the other ServerTrustFile, ClientKeyFile and ClientTrustFiles as a signer certificate.

To make these files accessible to Admin Server, open the "Security Center" in the administrative console. From the General tab, press the Default SSL Configuration button. Enter the proper path/file names in the fields provided for the ServerKeyFile and ServerTrustFile and press the OK button.

The sas.server.props file will be automatically updated to use the new server keyrings once WebSphere has been restarted. But you must modify the sas.client.props file manually to point to the ClientKeyFile and ClientTrustFiles complete with passwords.

In order to have the new keyrings take effect you will stop and restart WebSphere.

Problems:
If the Admin Server will not start after making the changes and you see these messages in the tracefile.
[01.12.13 15:20:48:501 CST] 4db20d01 ORBRas        W com.ibm.CORBA.iiop.Util Util P=447690:O=0:CT JORB0012: Pass by reference has been set to:  true (NoLocalCopies = true)
[01.12.13 15:20:53:529 CST] 4db20d01 ORBRas        X com.ibm.CORBA.iiop.IIOPConnection send P=447690:O=0:CT The following exception was logged
            javax.net.ssl.SSLHandshakeException: handshake failure
Confirm that the changes were properly updated in the sas.server.props file. You may just have to try restarting WebSphere a second time if the first attempt did not update the properties file. Also confirm the keyfile paths, file permission's, and passwords are correct.

If the Admin Server starts but the Admin Console or App Servers will not start, confirm that the keyfile paths and passwords are correct in the sas.client.props file as well as file permission's.

For remote consoles:
If your remote console is used solely to access the server where you have replaced your key files, you will have to copy the ClientKeyFile.jks and ClientTrustFile.jks to the remote system. Then the sas.client.props file can be updated to point to these new files.

If you use your remote console to connect to the server where you have replaced you key files as well as to servers where they haven't being replaced, then you will have to copy the cert.arm file. Import the cert.arm file in both client jks files being used. These files are listed in the remote sas.client.props file.

NOTE:
It should be possible to create only 1 keystore file (jks file) complete with self-signed cert and signer cert and have server key, server trust, client key and client trust use this one file. There is currently a defect opened to allow this to happen but as of this writing it will not work for the Admin Server.
 
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Security
Operating system(s): HP-UX
Software version: 4.0
Software edition:
Reference #: 1047447
IBM Group: Software Group
Modified date: Sep 3, 2004