SSL defaults in Liberty

Liberty includes default settings for the SSL certificate, keystore, and configuration.


Default Certificate and keystore

As a convenience tool to help you get up and running, use the createSSLCertificate parameter in the securityUtility command to create self-signed certificates. We 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 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 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.

      In version 19.0.0.2 and earlier:, the keystore file is called key.jks and is in the server or clients resources/security directory.

      Keystore type

      The keystore type is PKCS12.

      In version 19.0.0.2 and earlier, the keystore type is JKS.

      Password

      The password is provided in the configuration.

    Default certificate 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.

We can call the createSSLCertificate option from the command line to customize the certificate.

See securityUtility createSSLCertificate on the Open Liberty website.

Note: If a collective controller is not practical, we can use a self-signed certificate to restrict the number of clients that can connect to the Liberty member server. We can use an IHS server in front of the Liberty servers, with an appropriate CA signed certificate and a CN allowlist to control which clients can connect to IHS. We can then maintain a trusted channel between IHS and the Liberty member server 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 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 we 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 we 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 we 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 called defaultSSLConfig can be entered in the server.xml file for customization of the SSL configuration properties. A customized ssl element called defaultSSLConfig is still treated like the default SSL configuration when a different SSL configuration is not identified as the default.

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.


Differences between the transportSecurity-1.0 and ssl-1.0 features

Both the transportSecurity-1.0 and ssl-1.0 features configure security processing behaviors. The transportSecurity-1.0 behavior supersedes the ssl-1.0 behavior. Use the transportSecurity-1.0 behavior to employ SSL options for the outbound connection. The ssl-1.0 feature does not enable options for the outbound connection.

    transportSecurity-1.0 feature behavior

    When we enable the transportSecurity-1.0 feature, outbound SSL options become available. We 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 we 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.

    When the transportSecurity-1.0 feature is enabled, the Liberty server sets a custom SSL Socket factory that uses the ssl.SocketFactory.provider Java security property. This security property is automatically set when the transportSecurity-1.0 feature is enabled. When we are using the transportSecurity-1.0 feature, the process SSLContext is the SSLContext of the Java Secure Socket Extension (JSSE). A call to SSLContext.getDefault() returns the default context SSLContext of the JSSE. A call to SSLSocketFactory.getDefault() returns an SSLSocketFactory that is based on the Liberty server custom socket factory provider that uses the Liberty SSLContext.

    The outboundSSLRef attribute and the outboundConnection element are used for outbound SSL connections only if the transportSecurity-1.0 feature is specified. If the transportSecurity-1.0 feature is not specified, then the outboundSSLRef attribute and the outboundConnection element are ignored.

    We can specify an SSL configuration to use as the outbound. We can also set filters on an SSL configuration so that it is used for an outbound SSL call based on a destination host and port. For more information about outbound SSL options, see Configure SSL Sets for outbound communications and Outbound filters for SSL configurations.

    ssl-1.0 feature 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 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 created with the Liberty default SSL configuration.

    When the ssl-1.0 feature is enabled, the Liberty server creates an SSLContext from the default SSL configuration and makes that SSLContext the server default by calling the SSLContext.setDefault() Java API. This configuration makes the default SSLContext of the Liberty server the process default SSLContext. If anything makes the SSLContext.getDefault() Java API call, then the method returns Liberty SSLContext. The same applies to the SSLSocketFactory.getDefault() Java API, in that the default socket factory from the default SSLContext is returned.

Note: The ssl-1.0 feature does not enable SSL redirects. If application security is required and security information is redirected to a secure port, we must add a version of the Application Security Liberty feature, for example appSecurity-4.0, to the server.xml file. The Application Security feature enables the ssl-1.0 feature. We don't need to add both features. However, the Application Security feature does not enable the transportSecurity-1.0 feature. If we need both the Application Security feature and transportSecurity-1.0, we must add them separately.

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 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, we 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 an SSL configuration that this attribute specifies. 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 the sslRef attribute specifies or to the defaultSSLConfig if sslRef does not reference an SSL configuration.

Note: If we are changing from the transportSecurity-1.0 feature to the ssl-1.0 feature, or from the ssl-1.0 feature to the transportSecurity-1.0 feature, we must restart the Liberty server.

Furthermore, because of differences between transportSecurity-1.0 and ssl-1.0 in how the default Liberty SSLContext class is obtained, we might need to update the application code when we change from one feature to the other.

See ssl-1.0 and transportSecurity-1.0 feature restrictions