Enable TLS communication for the Liberty application client container

The Liberty application client container might require some TLS configuration for the client container to communicate with a server. Configure TLS for the application client container requires the use of the same TLS feature, transportSecurity-1.0, that the server requires for TLS enablement. The configuration elements and attributes are the same for the application client as for the server; however, for the application client container, these values are specified in the client.xml file.

The TLS handshake is a series of messages that are exchanged over the TLS protocol between a client and a server to negotiate for connection-specific protection. To enable TLS for the Liberty application client container the TLS feature, transportSecurity-1.0, must include the minimal information that is needed to form an TLS configuration used by the client. The minimal information that is required to form an TLS configuration is a keystore and a password.

We can use the securityUtility createSSLCertificate command to create the keystore of the client and to provide you with information about the configuration. Use the tool is optional, because we can also create a keystore and the associated configuration for other customer-defined purposes. Add the keystore element to the client.xml file. The id attribute must be defaultKeyStore and the password attribute contains the keystore password. The password can be entered in clear text or encoded. Use the securityUtility encode option to encode the password. 

    <keyStore id="defaultKeyStore" password="yourPassword" />

This is the minimum configuration that is needed to create an TLS configuration. In this configuration, the client creates the keystore and certificate if it does not exist during TLS initialization. The password provided must be at least 6 characters long.

The default keystore type is PKCS12. The default keystore is called key.p12. These defaults are in the /resources/security directory.

In version 19.0.0.2 and earlier, the default keystore type is JKS. The default keystore is called key.jks. These defaults are in the <client home>/resources/security directory.

The client will create the defaultKeyStore the first time it starts when using the previous configuration, however having the client create the default certificate comes with a performance cost. To avoid the performance cost IBM recommends that the securityUtilitiy createSSLCertificate command be used to create the default keystore used in the defaultKeyStore configuration.

If we need a custom TLS configuration, see Liberty: TLS configuration attributes.

    Accepting signer certificates

    If the client does not have an established trust relationship with the server the communication with the client prompts the user and asks if they accept the certificate from the server. If the user responds with yes, the certificate is taken and stored in the client keystore configuration and the command proceeds. If the user specifies no then there is no trust that is established and the call ends in an error.The prompt looks like the following example. 

      *** SSL SIGNER EXCHANGE PROMPT ***
The SSL signer from target host is not found in trust store C:/liberty/workspace/build.image/wlp/usr/clients/myTestClient/resources/security/key.p12.

Here is the signer information (verify the digest value matches what is displayed at the server):
Subject DN:    CN=localhost, O=ibm, C=us
Issuer DN:     CN=localhost, O=ibm, C=us
Serial number: 1327582458
Expires:       Sun Jan 04 06:54:18 CST 2099
SHA-1 Digest:  00:6F:25:F1:78:5D:EB:00:B1:E2:99:DB:E8:D7:DF:3B:F8:E0:20:9A
Add signer to the trust store now? (y/n)

    Through 19.0.0.2, the prompt looks like the following example. 

      *** SSL SIGNER EXCHANGE PROMPT ***
The SSL signer from target host is not found in trust store C:/liberty/workspace/build.image/wlp/usr/clients/myTestClient/resources/security/key.jks.

Here is the signer information (verify the digest value matches what is displayed at the server):
Subject DN:    CN=localhost, O=ibm, C=us
Issuer DN:     CN=localhost, O=ibm, C=us
Serial number: 1327582458
Expires:       Sun Jan 04 06:54:18 CST 2099
SHA-1 Digest:  00:6F:25:F1:78:5D:EB:00:B1:E2:99:DB:E8:D7:DF:3B:F8:E0:20:9A
Add signer to the trust store now? (y/n)

    We might receive the following error message if the user specifies no when asked to add the signer to the truststore:

      [ERROR ] CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN CN=localhost, O=ibm, C=us sent from the target host. The signer might need to be added to local trust store C:/liberty/workspace/build.image/wlp/usr/clients/myTestClient/resources/security/key.p12, located in SSL configuration alias defaultSSLConfig. The extended error message from the SSL handshake exception is: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by SubjectDN CN=localhost, O=ibm, C=us is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error throw able: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: PKIX path building failed: java.security.cert.CertPathBuilderException : PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by SubjectDN CN=localhost, O=ibm, C=us is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error

    Through 19.0.0.2, we might receive the following error message if the user specifies no when asked to add the signer to the truststore:

      [ERROR ] CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN CN=localhost, O=ibm, C=us sent from the target host. The signer might need to be added to local trust store C:/liberty/workspace/build.image/wlp/usr/clients/myTestClient/resources/security/key.jks, located in SSL configuration alias defaultSSLConfig. The extended error message from the SSL handshake exception is: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by SubjectDN CN=localhost, O=ibm, C=us is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error throw able: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: PKIX path building failed: java.security.cert.CertPathBuilderException : PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by SubjectDN CN=localhost, O=ibm, C=us is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error

    Auto accept signer certificate

    If the client does not want to be prompted for the signer certificate and chooses to accept the server signer certificate without examining the certificate, the user can provide the -autoAcceptSigner flag to the client container command line. 

      client run client_name --autoAcceptSigner

    Client authentication

    If the client is communicating with a server that has client authentication that is enabled, then the server needs to trust the client as well as the client trusting the server. The client must have a key, and personal certificate, in its keystore. If we use the securityUtility createSSLCertificate command, the keystore contains a personal certificate. The server that the client application container is communicating with must trust the client, so the signer from the client needs to be added to the truststore of the server. We can use the java tool, keytool, to extract the signer from the keystore of the application client container and add the certificate from the client to the truststore of the server.