+

Search Tips   |   Advanced Search

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 created when the profile was created. 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.

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.bprac

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

  1. Enable the signer exchange prompt to accept the signer during the connection attempt.

  2. Run the retrieveSigners utility to download the signers from that system prior to making the connection.

  3. Copy the trust.p12 file from...

      /config/cells/cell/nodes/node

    ...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 containing all signers from servers in that cell. Also, we might need to perform this step for back-level clients that are still using the DummyClientTrustFile.jks file. In this case, we 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, 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. We must also set...

Tip: We can configure a certificate expiration monitor to replace server certificates that are about to expire. See Certificate expiration monitoring in SSL.


Use the signer exchange prompt to retrieve signers from a client

When the client does not already have a signer to connect to a process, we 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
D5 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
D5 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
(iSeries) 
/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
D5 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

D5 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
(iSeries) 
/QIBM/UserData/WebSphere/AppServer/V85/profiles/default/bin/serverStatus -all ADMU0116I:
Tool information is being logged in file 
/QIBM/UserData/WebSphere/AppServer/V85/profiles/default/logs/serverStatus.log ADMU0128I:
Starting tool with the default profile ADMU0503I: Retrieving server status for all servers 
ADMU0505I: Servers found in
configuration: ADMU0506I: Server name: server1
*** SSL SIGNER EXCHANGE PROMPT *** SSL signer from target host 192.168.1.5 
is not found in truststore
/QIBM/UserData/WebSphere/AppServer/V85/profiles/default/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, 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
D5 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
D5 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 Application Manager "server1" 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 sent by the server. If we look at the certificate on the server, verify that the same SHA-1 digest displays.

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


Use the retrieveSigners utility to download signers for a client

We 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. 

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
(iSeries) 
/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 WAS automatically to retrieve and accept the signer for administrative connections. The SHA-1 digest is printed while the signer is added so we can verify the digest after the operation is complete.


Obtain 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 WAS cannot obtain signers as easily as in the current release. We 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/nodes/node directory in the configuration repository and has a default password of WebAS. trns

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

  1. 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.

  2. Change the client-side keystore password so that it matches the default cell name that is associated with the copied keystore.

  3. 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
(iSeries) 
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
(iSeries) 
com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=/QIBM/UserData/WebSphere/AppServer/V85/Base/
profiles/default/
etc/DummyClientKeyFile.jks
com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS com.ibm.ssl.trustStore=
/QIBM/UserData/WebSphere/AppServer/
V85/Base/profiles/default/etc/DummyClientTrustFile.jks com.ibm.ssl.trustStorePassword={xor}CDo9Hgw\=
com.ibm.ssl.trustStoreType=JKS

SSL configuration changes 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
(iSeries) 
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
(iSeries) 
com.ibm.ssl.protocol=SSL com.ibm.ssl.keyStore=/QIBM/UserData/WebSphere/AppServer/V85/Base/
profiles/default/etc/
DummyClientKeyFile.jks com.ibm.ssl.keyStorePassword={xor}CDo9Hgw\= com.ibm.ssl.keyStoreType=JKS
com.ibm.ssl.trustStore=/QIBM/UserData/WebSphere/AppServer/V85/Base/profiles/default/etc/trust.p12
com.ibm.ssl.trustStorePassword=myhostNode01Cell com.ibm.ssl.trustStoreType=PKCS12

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

We 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, we must also change the keyStorePassword and keyStoreType values to match those in the default key.p12 file.

In releases of WAS prior to v7.0, we 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. We might need to manually extract the default certificate from the DummyServerKeyFile.jks file and then import the certificate into the trust.p12 file that we added to the configuration.


Subtopics


Related:

  • Default chained certificate configuration in SSL