Enabling SSL communication in Liberty

To enable SSL communication in Liberty, there is a minimal set of SSL configuration options. It assumes most of the SSL options require some keystore configuration information.

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

About this task

SSL client authentication occurs during the connection handshake by using SSL certificates. The SSL handshake is a series of messages that are exchanged over the SSL protocol to negotiate for connection-specific protection. During the handshake, the secure server requests that the client send back a certificate or certificate chain for the authentication. To enable SSL in Liberty, you add the transportSecurity-1.0 Liberty feature to the configuration root document file, server.xml, along with code of the keystore information for authentication.

By default, the path and file name for the configuration root document file is path_to_liberty/wlp/usr/servers/server_name/server.xml. path_to_liberty is the location that you installed Liberty on your operating system, and server_name is the name of your server. However, you can change the path. See Customizing the Liberty environment.

Procedure

Enable the transportSecurity-1.0 Liberty feature in the server.xml file.
```
<featureManager>
    <feature>transportSecurity-1.0</feature>
</featureManager>
```
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.
Alternatively, SSL communication can be enabled by adding the ssl-1.0 Liberty feature in the server.xml file.
```
<featureManager>
    <feature>ssl-1.0</feature>
</featureManager>
```
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 the appSecurity Liberty feature to the server.xml file. The appSecurity feature enables the ssl-1.0 feature. It is not necessary to add both features. However, the appSecurity feature does not enable the transportSecurity-1.0 feature. If you need both appSecurity and transportSecurity-1.0, you must add them separately.

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

The transportSecurity-1.0 feature supersedes the ssl-1.0 feature and adds functionality that is not included with the ssl-1.0 feature. You can specify an SSL configuration to be used as the outbound as well as setup filters on an SSL configuration so that the SSL configuration can be 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.

Note: Due to the nature of the JDK, 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, the Liberty server must be restarted to use the feature to its complete functionality.
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
Add the keystore service object entry to the server.xml file. The keyStore element is called defaultKeyStore and contains the keystore password. The password can be entered in clear text or encoded. The securityUtility encode option can be used to encode the password.
```
<keyStore id="defaultKeyStore" password="yourPassword" />
```
The Liberty server creates a keystore password during profile creation and puts it in the server.env file that is in the server's home directory. If there is no keystore element 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 password from the server.env file is used to open the file. 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.
An example of a SAF key ring in the minimal configuration:
```
<keyStore id="defaultKeyStore" location="safkeyring:///WASKeyring"
          type="JCERACFKS" password="password" fileBased="false"
          readOnly="true" />
```
RACF® key ring needs to be set up before you configure them for use by the Liberty server. The server does not create certificates and add them to RACF.
The safkeyring URL is in the form:
```
safkeyring://racfid/WASKeyring
```
where the racfid is the RACF user ID with read authority to the key ring named, WASKeyring.
The single keystore entry for a minimal SSL configuration can be extended to include the location and type as well.
```
<keyStore id="defaultKeyStore" location="myKeyStore.p12" password="yourPassword" type="PKCS12"/>
```
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.

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

Through 19.0.0.2, the keystore is assumed to be a JKS keystore 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 of it. The certificate is a self-signed certificate with a validity period of 365 days, the CN value of the certificate's subjectDN is the host name of the machine where the server is running, and has a signature algorithm of SHA256withRSA.

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 IHS. A trusted channel between IHS and the Liberty Member server can be maintained by using the self-signed certificate.