Configuring TLS 1.3 for southbound traffic

This page explains how to configure TLS 1.3 in Apigee Message Processors for southbound traffic (traffic between the Message Processor and the backend server).

To learn more about TLS 1.3 feature in Java, see JDK 8u261 Update Release Notes.

The procedure to enable TLS 1.3 depends on the version of Java you're using. See Check the Java version in a Message Processor below to find the version of Java installed in the Message Processor.

TLS v1.3 and Java versions

TLS 1.3 feature was introduced in the following versions of Java:

Oracle JDK 8u261
OpenJDK 8u272

In the following Java versions, TLS v1.3 feature exists but is not enabled by default in client roles:

Oracle JDK 8u261 or later but less than Oracle JDK 8u341
OpenJDK 8u272 or later but less than OpenJDK 8u352

If you are using one of these versions, you need to enable TLS v1.3, as described in How to enable TLS v1.3 when it is not enabled by default.

If you are using one of the following versions, TLS v1.3 should already be enabled by default in client roles (Message Processor acts as a client for southbound TLS connections), so you don't need to take any action:

Oracle JDK 8u341 or later
OpenJDK 8u352 or later

For TLS v1.3 to work, all the following must hold true:

Underlying Java on Message Processor must support TLS v1.3.
TLS v1.3 must be enabled in Java on Message Processor.
TLS v1.3 must be enabled in the Message Processor application.

How to enable TLS v1.3 in Java when it is not enabled by default.

This section explains how to enable TLS v1.3 in case you are using one of the following versions of Java:

Oracle JDK 8u261 or later but less than Oracle JDK 8u341
OpenJDK 8u272 or later but less than OpenJDK 8u352

In the message processor, set Java property jdk.tls.client.protocols. Values are comma separated and can contain one or more of TLSv1, TLSv1.1, TLSv1.2, TLSv1.3, and SSLv3.

For example, setting -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3 enables client protocols TLSv1.2 and TLSv1.3.

See to Change other JVM properties to learn how to set JVM properties in an Edge component.

To enable TLS v1, v1.1, v1.2 and v1.3 protocols:

Set the following configuration in the message processor configuration file (/opt/apigee/customer/application/message-processor.properties):
```
   bin_setenv_ext_jvm_opts=-Djdk.tls.client.protocols=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3
```
Restart the Message Processor.

How to disable TLS v1.3 when it is enabled by default

If you're using Oracle JDK 8u341 or later, or OpenJDK 8u352 or later, TLSv1.3 is enabled by default for clients. If you wish to disable TLS v1.3 in such cases, you have two options:

Configure your target server's SSLInfo and ensure that TLSv1.3 is not mentioned in the protocols list. See TLS/SSL TargetEndpoint Configuration Elements. Note: If no protocols are specified in the target server configuration, whatever protocols are supported by Java will be sent as options in client handshake.
Disable TLS v1.3 in the message processor by disabling protocol completely. See Set the TLS protocol on the Message Processor.

Check the Java version in a Message Processor

To check the Java version installed in a Message Processor, log into the Message Processor node and execute the following command:

java -version

The sample output below shows that OpenJDK 8u312 is installed.

$ java -version
openjdk version "1.8.0_312"
OpenJDK Runtime Environment (build 1.8.0_312-b07)
OpenJDK 64-Bit Server VM (build 25.312-b07, mixed mode)

Supported ciphers

At present, Java 8 supports 2 TLS v1.3 ciphers:

TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256

You can use openssl to check if your target server supports TLS v1.3 and at least one of the ciphers above using below. Note that this example uses the openssl11 utility which has TLS v1.3 enabled.

$ openssl11 s_client -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256" -connect target_host:target_port -tls1_3