+

Search Tips   |   Advanced Search

 

Secure installation for client signer retrieval

 

Each profile in the WAS environment contains a unique self-signed certificate that was created when the profile was created. This certificate replaces the default dummy certificate that ships with WebSphere Application Server in releases prior to version 6.1. When a profile is federated to a deployment manager, the signer for that self-signed certificate is added to the common truststore for the cell.

For transitioning users: Beginning with version 6.1, clients and servers that are not within the same cell require more complex SSL configurations than do servers that are within the same cell and that use the default self-signed certificate configuration.trns

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

  1. Enable the signer exchange prompt to except 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 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, 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.

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.

 

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, you can enable the signer exchange prompt if you want to be able to accept the signer during the connection attempt. The 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, O=IBM, C=US
Issuer DN:     CN=myhost.austin.ibm.com, O=IBM, C=US
Serial number: 1128544457
Expires:       Thu Oct 05 15:34:17 CDT 2006
SHA-1 Digest:  91:A1:A9:2D:F2:7D:70:0F:04:06:73:A3:B4:A4:9C:56:9D:A8:A3:BA
MD5 Digest:    88:72:C5:88:00:1C:A7:FA:D6:EB:04:88:AC:A1:C9:13

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.

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 self-signed certificate configuration.

 

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

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

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 6.1, 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.

Sub-topics


retrieveSigners command

 

Related concepts


Default self-signed certificate configuration