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

You can call the createSSLCertificate option from the command line to customize the certificate. For more information, see securityUtility createSSLCertificate on the Open Liberty website.

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" />

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

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

You can specify an SSL configuration to use as the outbound. You 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 Configuring SSL Settings 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 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.

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, you 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. You don't need to add both features. However, the Application Security feature does not enable the transportSecurity-1.0 feature. If you need both the Application Security feature and transportSecurity-1.0, you 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 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 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 you 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, you 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, you might need to update your application code when you change from one feature to the other. For more information, see ssl-1.0 and transportSecurity-1.0 feature restrictions