Secure installation for client signer retrieval in SSL

Each profile in the WebSphere® Application Server environment contains a unique chained certificate signed by a unique long lived root certificate that was created when the profile was created. This certificate replaces the default self-signed certificate that ships with WebSphere Application Server Version 6.1 as well as the default dummy certificate that ships in releases prior to Version 6.1. When a profile is federated to a deployment manager, the signer for the root signing certificate is added to the common truststore for the cell, establishing trust for all certificates signed by that root certificate.

Best practice: Do not use the dummy keystore and truststore files, which are referenced in this topic, in a production environment. These files contain the same certificates and are used everywhere, which is not secure. Also, change the passwords for the keystore and truststore so that it does not use the WebAS default password.

By default, clients do not trust servers from different profiles in the WebSphere Application Server environment. That is, they do not contain the root signer for these servers. There are some things that you can do to assist in establishing this trust:

Enable the signer exchange prompt to accept the signer during the connection attempt.
Run the retrieveSigners utility to download the signers from that system prior to making the connection.
Copy the trust.p12 file from the /config/cells/<cell_name>/nodes/<node_name> directory of the server profile to the /etc directory of the client. Update the SSL configuration to reflect the new file name and password, if they are different. Copying the file provides the client with a trust.p12 that contains all signers from servers in that cell. Also, you might need to perform this step for back-level clients that are still using the DummyClientTrustFile.jks file. In this case, you might need to change the sas.client.props or soap.client.props file to reflect the new truststore, truststore password, and truststore type (PKCS12).

For clients to perform an in-band signer exchange, you must specify the ssl.client.props file as a com.ibm.SSL.ConfigURL property in the SSL configuration. For managed clients, this is done automatically. Signers are designated either as in-band during the connection or out-of-band during runtime. You must also set the com.ibm.ssl.enableSignerExchangePrompt attribute to true.

Tip: You can configure a certificate expiration monitor to replace server certificates that are about to expire. For more information about how clients can retrieve the new signer from the configuration, see Certificate expiration monitoring in SSL.

Using the signer exchange prompt to retrieve signers from a client

When the client does not already have a signer to connect to a process, you can enable the signer exchange prompt. The signer exchange prompt displays once for each unique certificate and for each node. After the signer for the node is added, the signer remains in the client truststore. The following sample code shows the signer exchange prompt retrieving a signer from a client:

C:\WASX_e0540.11\AppServer\profiles\AppSrv01\bin\serverStatus -all ADMU0116I: Tool information is being logged in file
C:\WASX_e0540.11\AppServer\profiles\AppSrv01\logs\serverStatus.log ADMU0128I: Starting tool with the 
AppSrv01 profile ADMU0503I:
Retrieving server status for all servers ADMU0505I: Servers found in configuration: 
ADMU0506I: Server name: dmgr
*** SSL SIGNER EXCHANGE PROMPT *** SSL signer from target host 192.168.1.5 is not found in truststore
C:\WebSphere\AppServer\profiles\AppSrv01\etc\trust.p12.

Here is the signer information (verify the digest value matches what is  displayed at the server):
Subject DN:    CN=myhost.austin.ibm.com, OU=myhostNode01Cell, OU=myhostNode01, O=IBM, C=US
Issuer DN:     CN=myhost.austin.ibm.com, OU=Root Certificate, OU=myhostNode01Cell, OU=myhostNode01, 
O=IBM, C=US
Serial number: 2510775664686266 Expires:       Thu Feb 19 15:58:49 CST 2009
SHA-1 Digest:  2F:96:70:23:08:58:6F:66:CD:72:61:E3:46:8B:39:D4:AF:62:98:C3
MD5 Digest:    04:53:F8:20:A2:8A:6D:31:D0:1D:18:90:3D:58:B9:9D

Subject DN: CN=myhost.austin.ibm.com, OU=Root Certificate, OU=myhostNode01Cell,
OU=myhostNode01, O=IBM, C=US Issuer DN:  CN=myhost.austin.ibm.com, OU=Root
Certificate, OU=myhostNode01Cell, OU=myhostNode01, O=IBM, C=US Serial number:
2510773295548841 Expires: Tue Feb 15 15:58:46 CST 2028 SHA-1 Digest:
2F:96:70:23:08:58:6F:66:CD:72:61:E3:46:8B:39:D4:AF:62:98:C3
MD5 Digest: 04:53:F8:20:A2:8A:6D:31:D0:1D:18:90:3D:58:B9:9D
Add signer to the truststore now? (y/n) y A retry of the request may need to occur. ADMU0508I:
The Deployment Manager "dmgr" is STARTED

/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/bin/serverStatus -all ADMU0116I:
Tool information is being logged in file
/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/logs/serverStatus.log ADMU0128I:
Starting tool with the dmgr profile ADMU0503I:
Retrieving server status for all servers ADMU0505I: Servers found in configuration: 
ADMU0506I: Server name:
dmgr  *** SSL SIGNER EXCHANGE PROMPT *** SSL signer from target host 192.168.1.5 is 
not found in truststore
/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/etc/trust.p12.
Here is the signer information (verify the digest value matches what is  displayed at the server):
Subject DN:    CN=myhost.austin.ibm.com, OU=myhostNode01Cell, OU=myhostNode01, O=IBM, C=US
Issuer DN:     CN=myhost.austin.ibm.com, OU=Root Certificate, OU=myhostNode01Cell, OU=myhostNode01, 
O=IBM, C=US
Serial number: 2510775664686266 Expires:       Thu Feb 19 15:58:49 CST 2009
SHA-1 Digest:  2F:96:70:23:08:58:6F:66:CD:72:61:E3:46:8B:39:D4:AF:62:98:C3
MD5 Digest:    04:53:F8:20:A2:8A:6D:31:D0:1D:18:90:3D:58:B9:9D 

Subject DN: CN=myhost.austin.ibm.com, OU=Root Certificate, OU=myhostNode01Cell,
OU=myhostNode01, O=IBM, C=US Issuer DN:  CN=myhost.austin.ibm.com, OU=Root
Certificate, OU=myhostNode01Cell, OU=myhostNode01, O=IBM, C=US Serial number:
2510773295548841 Expires: Tue Feb 15 15:58:46 CST 2028 SHA-1 Digest:
2F:96:70:23:08:58:6F:66:CD:72:61:E3:46:8B:39:D4:AF:62:98:C3

MD5 Digest: 04:53:F8:20:A2:8A:6D:31:D0:1D:18:90:3D:58:B9:9D

Add signer to the truststore now? (y/n) y A retry of the request may need to occur. ADMU0508I: 
The Deployment Manager "dmgr" is STARTED

To automate this process, see retrieveSigners command.

When a prompt occurs to accept the signer, a socket timeout can occur and the connection might be broken. For this reason, the message A retry of the request may need to occur. displays after answering the prompt. The message informs the user to resubmit the request. This problem should not happen frequently, and it might be more prevalent for some protocols than others.

A retry of the request may need to occur if the socket times out while waiting for a prompt response. If the retry is required, note that the prompt will not be re-displayed if (y) is entered, which indicates the signer has already been added to the trust store.

Verify the displayed SHA-1 digest, which is the signature of the certificate that is sent by the server. If you look at the certificate on the server, verify that the same SHA-1 digest displays.

You can disable the prompt when you do not want it to display by running the retrieveSigners utility to retrieve all of the signers for a particular cell. You can download or upload the signers from any remote keystore to any local keystore by referencing a common truststore with this client script. For more information, see Default chained certificate configuration in SSL.

Using the retrieveSigners utility to download signers for a client

You can run the retrieveSigners utility to retrieve all of the signers from the remote keystore for a specified client keystore.

The typical remote keystore to reference is CellDefaultTrustStore.

The truststore contains the signers that enable the client to connect to its processes. The retrieveSigners utility can point to any keystore in the target configuration, within the scope of the target process, and can download the signers (certificate entries only) to any client keystore in the ssl.client.props file.

The following sample code shows the retrieveSigners utility in a deployment manager environment. [AIX Solaris HP-UX Linux Windows]

C:\WASX_e0540.11\AppServer\profiles\AppSrv01\bin\retrieveSigners.bat CellDefaultTrustStore 
ClientDefaultTrustStore -autoAcceptBootstrapSigner  CWPKI0308I: Adding signer alias 
"CN=myhost.austin.ibm.com,
O=IBM, C=US" to local keystore "ClientDefaultTrustStore" with the following SHA
digest: 91:A1:A9:2D:F2:7D:70:0F:04:06:73:A3:B4:A4:9C:56:9D:A8:A3:BA  CWPKI0308I: 
Adding signer alias "default" to
local keystore "ClientDefaultTrustStore" with the following SHA digest:
40:20:CF:BE:B4:B2:9C:F0:96:4D:EE:E5:14:92:9E:37:8D:51:A5:47

/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/bin retrieveSigners CellDefaultTrustStore
ClientDefaultTrustStore -autoAcceptBootstrapSigner  CWPKI0308I: Adding signer alias "CN=myhost.austin.ibm.com,
O=IBM, C=US" to local keystore "ClientDefaultTrustStore" with the following
SHA digest: 91:A1:A9:2D:F2:7D:70:0F:04:06:73:A3:B4:A4:9C:56:9D:A8:A3:BA  CWPKI0308I: Adding signer alias 
"default" to local keystore
"ClientDefaultTrustStore" with the following SHA digest: 40:20:CF:BE:B4:B2:9C:F0:96:4D:EE:E5:14:
92:9E:37:8D:51:A5:47

Use the -autoAcceptBootstrapSigner option to enable WebSphere Application Server automatically to retrieve and accept the signer for administrative connections. The SHA-1 digest is printed while the signer is added so you can verify the digest after the operation is complete.

Obtaining signers for clients and servers from a previous release

For transitioning users: When a client from a release prior to version 7.0 connects to the current release, the client must obtain signers for a successful handshake. Clients using previous releases of WebSphere Application Server cannot obtain signers as easily as in the current release. You can copy the deployment manager common truststore to your back-level client or server, and then re-configure the SSL configuration to directly reference that truststore. This common truststore of type PKCS12 is located in the /config/cells/<cell_name>/nodes/<node_name> directory in the configuration repository and has a default password of WebAS.

To collect all of the signers for the cell in a single trust.p12 keystore file, complete following steps:

Copy the trust.p12 keystore file on the server and replicate it on the client. The client references the file directly from the sas.client.props and soap.client.props files that specify the SSL properties for previous releases.
Change the client-side keystore password so that it matches the default cell name that is associated with the copied keystore.
Change the default keystore type for the trust.p12 file to PKCS12 in the client configuration.

The following two code samples show you a before and an after view of the changes to make.

Default SSL configuration of sas.client.props for a previous release

com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=file\:///  C\:/SERV1_601_0208/AppServer/profiles/AppSrv01/etc/
DummyClientKeyFile.jks com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS
com.ibm.ssl.trustStore=
file\:/// C\:/SERV1_601_0208/AppServer/profiles/AppSrv01/etc/DummyClientTrustFile.jks
com.ibm.ssl.trustStorePassword={xor}CDo9Hgw\=
com.ibm.ssl.trustStoreType=JKS

com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/
dmgr/etc/DummyClientKeyFile.jks
com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS com.ibm.ssl.trustStore=
/QIBM/UserData/WebSphere/
AppServer/V85/ND/profiles/dmgr/etc/DummyClientTrustFile.jks com.ibm.ssl.trustStorePassword={xor}CDo9Hgw\
= com.ibm.ssl.trustStoreType=JKS

SSL configuration changes that are required to common truststore file in the /etc directory of the client

com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=file\:/// C\:/SERV1_601_0208/AppServer/profiles/AppSrv01/etc/
DummyClientKeyFile.jks com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS
com.ibm.ssl.trustStore=file\:/// C\:/SERV1_601_0208/AppServer/profiles/AppSrv01/etc/trust.p12
com.ibm.ssl.trustStorePassword=myhostNode01Cell com.ibm.ssl.trustStoreType=PKCS12

com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/etc/
DummyClientKeyFile.jks com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS
com.ibm.ssl.trustStore=/QIBM/UserData/WebSphere/AppServer/V85/ND/profiles/dmgr/etc/trust.p12
com.ibm.ssl.trustStorePassword=myhostNode01Cell com.ibm.ssl.trustStoreType=PKCS12

Tip: You can run the PropsFilePasswordEncoder script, which is located in the /bin directory to encode the password.

You can also make these changes in the soap.client.props file and specify the key.p12 file in place of the DummyClientKeyFile.jks file. However, you must also change the keyStorePassword and keyStoreType values to match those in the default key.p12 file.

In releases of WebSphere Application Server prior to Version 7.0, you must edit the SSL configuration on the server to replace the common truststore. The trust.p12 file, which is used by the server, also must contain the default dummy certificate signer for connections among servers at previous release levels. You might need to manually extract the default certificate from the DummyServerKeyFile.jks file and then import the certificate into the trust.p12 file that you added to the configuration.