Transport Security
1.0

This feature enables support for Secure Sockets Layer (SSL) connections. The secure HTTPS listener is not started unless the transportSecurity-1.0 feature is enabled and a keystore is configured.

When the Transport Security feature is enabled, the SSL context for the process is the default SSL context of the Java Secure Socket Extension (JSSE). Therefore, the SSLContext.getDefault() method returns the default SSL context of the JSSE. However, when this feature is enabled, Open Liberty also sets a custom SSL socket factory. Therefore, the SSLSocketFactory.getDefault() method returns an SSL socket factory that is based on the Open Liberty custom socket factory provider, which uses the Open Liberty SSL context instead of the JSSE default.

Enabling this feature

To enable the Transport Security 1.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>transportSecurity-1.0</feature>

Examples

Configure transport layer security (TLS)

To enable TLS connections, you must enable the Transport Security feature and add the keyStore element to your server.xml file. The following example shows the minimum configuration to specify a keystore:

<keyStore id="defaultKeyStore" password="yourPassword"/>

When the defaultKeyStore value is specified, Open Liberty builds a TLS configuration around it with an ID attribute value of defaultSSLConfig. In this default TLS configuration, the defaultKeyStore file is used as both the keystore and truststore.

This default configuration enables all TLS levels. Levels TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 are enabled, according to what the Java SDK supports. The default ciphers include all ciphers that are size 128-bit and higher. Client authentication is not enabled by the default configuration.

In this configuration, the server creates the keystore and a certificate, if no certificate exists during SSL initialization. The certificate is self-signed, with a validity period of 365 days and a signature algorithm of SHA256withRSA. The common name (CN) value of the certificate subjectDN attribute is the hostname of the computer where the server is running, such as www.example.com.

Open Liberty creates a keystore password during profile creation and puts it in the server.env file that is in the server home directory. 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 server.xml file, the password from the server.env file is used to open the file. If you don’t want to use the generated keystore password, remove the keystore_password entry from the server.env file. If a default keystore file was already generated with the password from the server.env file, you might need to remove it.

You can designate a different ssl element in the configuration as the default SSL configuration by specifying the sslRef attribute on the sslDefault element, as shown in the following example:

<sslDefault sslRef="customSSLConfiguration"/>

For more information, see SSL Repertoire.

Use the Java Virtual Machine (JVM) default truststore

You can set the trustDefaultCerts attribute to true to specify that the JVM default truststore can be used, in addition to the configured truststore, as shown in the following example:

<ssl id="myDefaultSSLConfig"
      keyStoreRef="defaultKeyStore"
      trustStoreRef="defaultTrustStore"
      trustDefaultCerts="true"/>

Configure outbound TLS

You can configure Open Liberty to have a global outbound default TLS configuration that is different from the inbound default configuration. Outbound TLS filters are configured on the outboundConnection element that is nested in the ssl element. You can specify either a host or a host and port to indicate where the outbound SSL connection goes by setting attributes on the outboundConnection element.

In the following example, outbound TLS connections that go to any port on the otherhost host use the TLS configuration that is specified by the defaultSSLConfig value. All other outbound TLS connections use the outbound default TLS configuration that is specified by the outboundSSLRef attribute called outboundSSLSettings:

<sslDefault outboundSSLRef=”outboundSSLSettings”/>

<ssl id="defaultSSLConfig"
      keyStoreRef="defaultKeyStore"
      trustStoreRef="defaultTrustStore" >
	<outboundConnection host=”otherhost”/>
</ssl>

<keyStore id="defaultKeyStore"
           location="key.p12"
           type="PKCS12"
           password=”yourpassword”/>

<keyStore id="defaultTrustStore"
           location="trust.p12"
           type="PKCS12"
           password="yourpassword"/>

<ssl id="outboundSSLSettings"
      keyStoreRef="outboundKeyStore"
      trustStoreRef="outboundTrustStore"/>

<keyStore id="outboundKeyStore"
           location="server1/outboundKeyFile.p12"
           password="yourpassword"/>

<keyStore id="outboundTrustStore"
           location="server1/outboundTrustFile.p12"
           password="yourpassword"/>

Provide certificates from an environment variable or a file

At startup, Open Liberty can read certificates from an environment variable so that they can be used to establish trust. To provide a certificate, set the cert_(name of existing truststore) environment variable to equal the value of the certificate or a file that contains one or more certificates. Certificates must be either DER encoded or in the PEM format. Environment variables are set in the server.env file.

Any value that does not start with the -----BEGIN CERTIFICATE----- tag is treated like a file.

In the following example, an environment variable supplies certificates to a truststore that is called defaultKeyStore from a file that is called certs.crt:

cert_defaultKeyStore=/var/certs.crt

In the following example, an environment variable supplies a certificate to a truststore that is called defaultKeyStore:

cert_defaultKeyStore="-----BEGIN CERTIFICATE-----
....
-----END CERTIFICATE-----"

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-17.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

com.ibm.websphere.appserver.transportSecurity-1.0; type="osgi.subsystem.feature"