Secure installation for client signer retrieval
Each profile in the WAS 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 dmgr, 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.
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:
- Enable the signer exchange prompt to except 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...
/config/cells/<cell_name>/nodes/<node_name>...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, specify ssl.client.props 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 attribute...
com.ibm.ssl.enableSignerExchangePrompt...to true.
Tip: You can configure a certificate expiration monitor to replace server certificates that are about to expire.
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:
serverStatus -allADMU0116I: Tool information is being logged in file 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
PROFILE_HOME\AppSrv01\etc\trust.p12.
Here is the signer information (verify the digest value matches what is displayed at the server):
Subject DN: CN=myhost.mpls.setgetweb.com, OU=Node01Cell, OU=Node01, O=IBM, C=US
Issuer DN: CN=myhost.mpls.setgetweb.com, OU=Root Certificate, OU=Node01Cell, OU=Node01,
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.mpls.setgetweb.com, OU=Root Certificate, OU=Node01Cell, OU=Node01, O=IBM, C=US Issuer DN: CN=myhost.mpls.setgetweb.com, OU=Root
Certificate, OU=Node01Cell, OU=Node01, 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 STARTEDTo automate this process, see retrieveSigners.
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 we 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.
See Default chained certificate configuration in SSL.
Use 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 ssl.client.props.
The following sample code shows the retrieveSigners utility in a deployment manager environment.
C:\WAS\AppServer\profiles\AppSrv01\bin\retrieveSigners.bat CellDefaultTrustStore ClientDefaultTrustStore-autoAcceptBootstrapSigner CWPKI0308I: Adding signer alias "CN=myhost.mpls.setgetweb.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
To enable WAS automatically to retrieve and accept the signer for administrative connections use the option...
–autoAcceptBootstrapSignerThe SHA-1 digest is printed while the signer is added so we 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 WAS cannot obtain signers as as in the current release. You can copy the dmgr common truststore to the 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...
/config/cells/<cell_name>/nodes/<node_name>...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:
- 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=JKSSSL 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=JKScom.ibm.ssl.trustStore=file\: /// C\:/SERV1_601_0208/AppServer/profiles/AppSrv01/etc/trust.p12 com.ibm.ssl.trustStorePassword=Node01Cell com.ibm.ssl.trustStoreType=PKCS12
Tip: You can run the PropsFilePasswordEncoder script, which is located in the /bin directory to reset 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, also change the keyStorePassword and keyStoreType values to match those in the default key.p12 file.
In releases of WAS prior to version 7.0, 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.
Subtopics
retrieveSigners
Related concepts
Default chained certificate configuration in SSL