SSL defaults in Liberty

Specifies the default SSL certificate, keystore, and configuration in Liberty.

Default Certificate and keystore

As a convenience tool to help developers get up and running, users can use the createSSLCertificate parameter in the securityUtility command to create self-signed certificates. Users can either call the tool directly from the command line or allow the server to call it to create the default certificate and keystore on server startup.

The server creates the default keystore and certificate if a user has a keystore element that is called defaultKeyStore in the server.xml file. For example:
<keyStore id="defaultKeyStore" password="yourPassword" />

If a keystore configuration for the defaultKeyStore is in place and the keystore does not exist when the server starts, the server calls the createSSLCertificate parameter. This parameter creates the keystore with a password that is specified in the configuration.

Default keystore details:
  • Location: The keystore file is called key.p12 and is in the server or clients resources/security directory.
  • Keystore type: The keystore type is PKCS12.
  • Through 19.0.0.2: Location: The keystore file is called key.jks and is in the server or clients resources/security directory.
  • Through 19.0.0.2: Keystore type: The keystore type is JKS.
  • Password: Password that is provided in the configuration.
Default certificate that is created by Liberty details:
  • Type: The certificate is a self-signed certificate.
  • Size: The default certificate size is 2048.
  • Signature algorithm: The signature algorithm for the certificate is SHA256WITHRSA.
  • Validity: The certificate is valid for 365 days.
  • SubjectDN: The certificate gets created with CN=<hostname>,OU=<client or server name>,O=ibm,C=US as the SubjectDN.

The createSSLCertificate parameter can be called on the command line if users would like to customize the certificate.

Note: When the use of a collective controller is not practical, perhaps there is only one or two Liberty servers, a self-signed certificate can be used to restrict the number of clients that can connect to the Liberty member server. It is suggested that an IHS server is used in front of the Liberty servers, where an appropriate CA signed certificate can be used, along with a CN allowlist to control which clients can connect to HIS. A trusted channel between IHS and the Liberty Member server can be maintained by using the self signed certificate.

Default SSL configuration

The minimal configuration that is needed for SSL is a single keystore element called defaultKeyStore. When the defaultKeyStore exists in the configuration, the run time builds an SSL configuration that is called defaultSSLConfig around it.

defaultSSLConfig details:

  • Protocol: When the IBM® JRE is used, the protocol is set to SSL_TLSv2 by default. If the Oracle JRE is used, SSL is used as the protocol.

    Whether you use the IBM JRE or the Oracle JRE, the sslProtocol attribute includes the TLSv1, TLSv1.1 and TLSv1.2 protocols. The TLSv1.3 protocol is also included if you use IBM Semeru Runtimes for Java™ 11 or later. For more information about using OpenSSL for cryptographic acceleration with IBM Semeru Runtimes for Java™ 11, see the Semeru Runtimes security migration guide.

  • Ciphers: The cipher list is built by getting a list of supported ciphers from the underlying JRE. By default, the list is reduced to all the ciphers that are 128 bit and higher or 3DES. RC4 is removed because having them enabled is not considered to be safe.ECDHE ciphers are removed because they can cause errors if you are going to a server that does not support them. The cipher list can be customized to include them.
  • Client authentication: By default clientAuthentication and clientAuthenticationSupported are disabled.
  • Keystore: In the default configuration, the defaultKeyStore is used as both the key and truststore.

An SSL element that is called defaultSSLConfig can be entered in the server.xml file for customization of the SSL configuration properties. A customized ssl element that is called defaultSSLConfig is still treated like the default SSL configuration when a different SSL configuration is not identified as the default. For more information, see SSL configuration attributes.

To designate a different ssl element in the configuration as the default SSL configuration, users can identify that with the sslDefault element.
<sslDefault sslRef="customSSLConfiguration" />

Both (transportSecurity-1.0) and (ssl-1.0) are security processing behaviors. The transportSecurity-1.0 behavior supersedes the ssl-1.0 behavior in fix pack 17.0.0.1 and later. Use the transportSecurity-1.0 behavior to employ SSL options for the outbound connection. If your security configuration does not include options for the outbound connection, you can continue to use the ssl-1.0 behavior.

The (transportSecurity-1.0) behavior

When you enable the transportSecurity-1.0 feature, outbound SSL options become available. You can either set an outbound default with the outboundSSLRef attribute on the sslDefault element or set the SSL filter on the SSL configuration to allow for dynamic outbound connections. The filter consists of either a host or host and port combinations. Based on the host and port of the outbound connection, the outbound connection can match with the SSL configuration.

The SSL runtime code does not set the SSLContext process default when you enable the transportSecurity-1.0 feature. The SSL runtime code sets a custom SSLSocketFactory class with the ssl.SocketFactory.provider Java™ security property. The SSLContext process default is the SSLContext Java Secure Socket Extension (JSSE) default that uses the cacerts file for the key and trust.

The program returns the Liberty custom SSL socket factory to any code that attempts to obtain the SSLSocketFactory class default with the javax.net.ssl.SSLSocketFactory.getDefault() property. The custom SSLSocketFactory class can resolve the proper SSL configuration for the outbound connection.

Features that Liberty provides use Liberty SSL configurations. However, third-party APIs that make outbound SSL calls might require configuration to use Liberty capabilities. The Liberty SSL runtime code does not set the SSLContext process default when the transportSecurity-1.0 feature is enabled. Third-party APIs that rely on the default SSL context do not benefit from the Liberty SSL configuration. When the transportSecurity-1.0 feature is enabled, the Liberty SSL runtime code sets a custom SSLSocketFactory class with the ssl.SocketFactory.provider Java security property. Third-party APIs can benefit from the Liberty SSL configuration with the SocketFactory default by calling the javax.net.ssl.SSLSocketFactory.getDefault() property.
Note: The Liberty custom SSLSocketFactory class does not acknowledge Java system properties, such as javax.net.ssl.keystore.
The (ssl-1.0) behavior

The attributes from the Liberty default SSL configuration are used to create an SSLContext. That SSLContext is set on the process as the default SSLContext by using the Java API SSLContext.setDefault(). If an application calls to an API like httpURLConnection() with an https URL and does not provide any SSL information, then the application picks up the default SSLContext of the process. In this case is the SSLContext that is created with the Liberty default SSL configuration.

Liberty uses the JSSE's default SSLContext if a default SSL configuration is not set in Liberty. The JSSE's default SSLContext uses the cacerts file for the keystore and truststore. Liberty does not have a default SSL configuration if the SSL feature is not defined, or if the SSL configuration that exists is not identified as the default. The default configuration is either called defaultSSLConfig, which can be implicit if a defaultKeyStore is defined or an alternative SSL configuration can be designated by using the sslDefault element.

The javax system properties, javax.net.ssl.keystore is used to set up the keystore and truststore information for the default SSL context and must not be used. If the properties are set on the process, then the call to SSLContext.setDefault() wipes them out.

To enable an SSL element to be used as the default for outbound SSL connections, you can use the outboundSSLRef attribute on the sslDefault element.
<feature>transportSecurity-1.0</feature>
<sslDefault sslRef="mySSLConfig" outboundSSLRef="customSSLConfiguration" />
To specify a default outbound SSL element, the transportSecurity-1.0 feature must be enabled. When outboundSSLRef is specified, outbound SSL connections default to using an SSL configuration that is specified by that attribute. If the transportSecurity-1.0 feature is missing, then outboundSSLRef is ignored. If no outboundSSLRef attribute is specified, the outbound call uses the value that is specified by the sslRef attribute or defaultSSLConfig if sslRef does not reference an SSL configuration.