Enabling 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. Configuring 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.
About this task
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 that is used by the client. The minimal information that is required to form an
TLS configuration is a keystore and a password.
You can use the securityUtility
createSSLCertificate command to create the keystore of the client and to provide
you with information about the configuration. Using the tool is optional, because you can also
create a keystore and the associated configuration for other customer-defined purposes.
Procedure
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 that is 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.
Through 19.0.0.2, 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 it is recommended that the securityUtilitiy
createSSLCertificate command be used to create the default
keystore used in the defaultKeyStore
configuration.
If you 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)
You 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, you 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 you 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. You 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.