Transport Security1.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.
The Transport Security feature supersedes the Secure Socket Layer (ssl-1.0) feature and adds functions that are not included with the ssl-1.0 feature.
When the ssl-1.0 feature is enabled, the SSL context that is obtained by the SSLContext.getDefault() method is the default Liberty configuration. When the Transport Security feature is enabled, the SSL context that is obtained by the SSLContext.getDefault() method is the SSLContext of the Java Secure Socket Extension (JSSE).
However, when the Transport Security 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. Due to these differences between the Transport Security feature 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, or when you migrate from Java EE to Jakarta EE. For more information, see Troubleshooting SSL and TLS.
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 server creates a default keystore and certificate if you specify defaultKeyStore as the ID value for the keyStore element in your server.xml file. The following example shows the minimum configuration to specify a keystore:
<keyStore id="defaultKeyStore" password="yourPassword"/>Default keystore and TLS certificate configurations
When the defaultKeyStore value is specified, Open Liberty builds a TLS configuration around it with an ID attribute value of defaultSSLConfig. If the keystore does not exist on server startup, the server also creates a default keystore file. In the default TLS configuration, this keystore file is used as both the keystore and truststore.
Open Liberty creates a keystore password when the server is created and puts it in the ${server.config.dir}/server.env file that is in the server home directory. If no keyStore element exists to create the default keystore file, this password is used to create a keystore file. This keystore file is then used as the default keystore 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.
The following table lists the default keystore file details.
| Keystore details | Description |
|---|---|
Location | The keystore file is called |
Keystore type | The keystore type is |
Password | The default password is the password that is specified in the |
This default configuration enables all TLS protocols. The TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols are enabled according to what the Java SDK supports. You can configure specific TLS protocols instead of configuring and enabling all of them by default.
The default ciphers include all ciphers that are size 128-bit and higher. Client authentication is not enabled by the default configuration.
If no certificate exists during TLS initialization, the server also creates a default certificate. The default certificate is self-signed, with a certificate size of 2048 kb. The validity period is 365 days and the signature algorithm is SHA256WITHRSA. The certificate is created with CN=<hostname>,OU=<client or server name>,O=ibm,C=US as the subjectDN attribute. The hostname value is the hostname of the computer where the server is running.
You can also run the securityUtility createSSLCertificate command to create and customize the default certificate and keystore.
For more information, see SSL Repertoire.
Specify an alternate SSL configuration as default
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"/>Configure specific TLS protocols
Configure TLS protocols on the sslProtocol attribute if the underlying JDK support exists for the protocols. Create a comma-separated list from the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocol values. This list of protocols overrides the TLS protocols that are enabled in the default TLS configuration.
The TLSv1.3 and TLSv1.2 protocols are configured in the following example:
<ssl id="myDefaultSSLConfig"
keyStoreRef="defaultKeyStore"
trustStoreRef="defaultTrustStore"
sslProtocol="TLSv1.3, TLSv1.2" />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.crtIn the following example, an environment variable supplies a certificate to a truststore that is called defaultKeyStore:
cert_defaultKeyStore="-----BEGIN CERTIFICATE-----
....
-----END CERTIFICATE-----"Hostname and IP address verification
Hostname and IP address verification are enabled by default. This verification is enforced for target servers in all SSL connections through Open Liberty socket factories. However, you can specify a list of hostnames, IP addresses, or both to skip verification.
To disable hostname verification entirely, set the verifyHostname attribute within the ssl tag to false.
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" verifyHostname="false"/>When hostname verification is enabled, you can skip verification for hostnames or IP addresses that are specified in the skipHostnameVerificationForHosts attribute within the ssl tag. The skipHostnameVerificationForHosts attribute is a comma-separated list of hostnames, IP addresses, or both.
<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" skipHostnameVerificationForHosts="myHost.com"/>The verification makes sure that the hostname or IP address in the URL matches the Subject Alternative Name (SAN) in the SSL certificate of the server. If the SAN is not found, the property makes sure that the hostname in the URL matches the Common Name (CN). If a mismatch exists, the SSL connection is rejected.
Typically, during hostname verification, when the hostname is used in the request, it checks against the DNSName entry in the SAN. If the SAN does not contain a DNSName entry, hostname verification uses the certificate owner’s Common Name (CN). When an IP address is used in the request, hostname verification relies on the IP address information in the SAN only.
For more information, see Troubleshooting SSL and TLS.
