Enabling SSL communication in Liberty

To enable SSL communication in Liberty, add the Transport Security feature and specify a keystore configuration. The Transport Layer Security (TLS) protocol supersedes the now deprecated Secure Sockets Layer protocol.

For the most current information about enabling SSL communication in Liberty, see the Open Liberty website.

Beginning with Liberty 26.0.0.5, there are changes to how SSL suites are configured.

securityLevel attribute

Starting with version 26.0.0.5, the securityLevel attribute is ignored.

If the enabledCiphers attribute is not specified or is empty, Liberty uses the effective cipher suites provided by the underlying Java™ SDK when performing the TLS handshake.

If enabledCiphers is specified, Liberty uses either a custom list of cipher suites or a set of filter rules, as described in the following sections.

enabledCiphers attribute behavior

The enabledCiphers attribute now supports two mutually exclusive configuration modes:

Specify an explicit list of cipher suites.
Specify filter criteria to add to or remove cipher suites from the Java SDK’s effective cipher suites.

The underlying Java runtime environment (JRE) determines which TLS cipher suites are supported.

Mode 1: Explicit cipher list (existing behavior)

To explicitly control which cipher suites are enabled, specify a space-separated list of cipher suite names.

<ssl id="defaultSSLConfig" 
  enabledCiphers="TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384"/>

When you use this mode, only the specified cipher suites are enabled for SSL communication. No additional cipher suites are included.

Mode 2: Cipher filtering (new behavior)

Filter mode allows you to modify the Java SDK's effective cipher suites by adding or removing specific cipher suites.

Prefix a cipher suite with the minus sign (-) to remove it.
Prefix a cipher suite with the plus sign (+) to add it.
Separate entries with spaces.
Use the wildcard character (*) only with the minus sign (-) and only at the end of a cipher suite prefix.
Do not use wildcards when adding cipher suites. Wildcards are not supported in this configuration.

For example:

<ssl id="defaultSSLConfig"
  enabledCiphers="-TLS_RSA_* +TLS_AES_128_GCM_SHA256"/>

In this example:

All cipher suites that begin with TLS_RSA_ are removed.
The TLS_AES_128_GCM_SHA256 cipher suite is added if it is supported by the JRE.

Procedure

Enable the transportSecurity-1.0 Liberty feature in the server.xml file.
```
<featureManager>
    <feature>transportSecurity-1.0</feature>
</featureManager>
```
1. Optional: Alternatively, you can enable SSL communication by adding the ssl-1.0 Liberty feature in the server.xml file.
```
<featureManager>
    <feature>ssl-1.0</feature>
</featureManager>
```
  The transportSecurity-1.0 feature supersedes the ssl-1.0 feature and adds functions that are not included with the ssl-1.0 feature. For more information, see Differences between the transportSecurity-1.0 and ssl-1.0 features.
Add the keystore element to the server.xml file.
The default keystore configuration is called defaultKeyStore and contains the keystore password.
```
<keyStore id="defaultKeyStore" password="yourPassword" />
```
Liberty creates a keystore password during server creation and puts it in the server.env file that is in the server home directory unless the --no-password option is specified on the server create command. If no keystore element exists for the defaultKeyStore file, this password is used to create a keystore file. This keystore file is then used as the defaultKeyStore file. Likewise, if a defaultKeyStore entry exists without a password in the sever.xml file when the server starts, the keystore password from the server.env file is used to open the file.

The keystore_password from the server.env file is also used as the LTPA keys password if both the keysPassword attribute in the <ltpa> element in the server.xml file and the ltpa_keys_password environment variable in the server.env file are not defined. For more information, see the keysPassword description in the LTPA configuration element.

If you don't want to use the Liberty-generated keystore password, remove the keystore_password entry from the server.env file. If a default keystore was already generated with the password from the server.env file, you might need to remove it.

This configuration is the minimum that is needed to create an SSL configuration. In this configuration, the server creates the keystore and certificate if it does not exist during SSL initialization. The password that is provided must be at least 6 characters long. You can enter the password in clear text or encode it by using the securityUtility encode option.

The keystore is assumed to be a PKCS12 keystore file that is called key.p12 in the server home/resources/security directory.

In version 19.0.0.2 and earlier, the keystore is assumed to be a JKS keystore file that is called key.jks in the server home/resources/security directory.

If the file does not exist, the server creates it for you. If the server creates the keystore file, it also creates the certificate inside it. The certificate is a self-signed certificate with a validity period of 365 days. The CN value of the certificate subjectDN is the hostname of the machine where the server is running, and it has a signature algorithm of SHA256withRSA.
1. Optional: You can extend the single keystore entry for a minimal SSL configuration to include the keystore location and type, as shown in the following example.
```
<keyStore id="defaultKeyStore" location="myKeyStore.p12" password="yourPassword" type="PKCS12"/>
```