Add support for TLS 1.3

In  elytron security

Overview

JDK 11 has added support for TLS 1.3. This task is to update Elytron to be able to make use of TLS 1.3. This RFE assumes that the TLS 1.3 protocol is provided by the default JSSE provider.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Affected Projects or Components

  • WildFly, Security

Other Interested Projects

Requirements

Hard Requirements

  • It should be possible to configure a server-ssl-context and client-ssl-context in the Elytron subsystem using the TLS 1.3 protocol and TLS 1.3 cipher suites. (Note that TLS 1.2 cipher suites cannot be used with TLS 1.3 and vice and versa.)

    • A new attribute cipher-suite-names will be added to both server-ssl-context and client-ssl-context to specify the TLS 1.3 cipher suites that should be enabled. The format will be a colon (:) separated list of cipher suite names (similar to the new OpenSSL-style TLS 1.3 ciphersuites option).

    • For now, we will have TLS 1.3 disabled by default due to the performance issue described in WFWIP-160. Configuring the above cipher-suite-names attribute will result in TLS 1.3 being enabled.

      • When we are ready to have TLS 1.3 enabled by default, the default value for the cipher-suite-names attribute will be the same as the OpenSSL default cipher suites for TLS 1.3: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

    • Example configuration:

   <server-ssl-context name="myTLS13ServerContext" ... cipher-suite-names="TLS_AES_128_CCM_8_SHA256:TLS_AES_256_GCM_SHA384"/>
   <client-ssl-context name="myTLS13ClientContext" ... cipher-suite-names="TLS_AES_128_CCM_8_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"/>

  • It should be possible to configure subsystems that reference an ssl-context to make use of this TLS 1.3 server-ssl-context.

  • It should be possible to configure an ssl-context using the Elytron authentication client using the TLS 1.3 protocol and TLS 1.3 cipher suites.

    • A new attribute names will be added to the cipher-suite element to specify the TLS 1.3 cipher suites that should be enabled. The format will be a colon (:) separated list of cipher suite names (similar to the new OpenSSL-style TLS 1.3 ciphersuites option).

    • For now, we will have TLS 1.3 disabled by default due to the performance issue described in WFWIP-160. Configuring the above names attribute will result in TLS 1.3 being enabled.

      • When we are ready to have TLS 1.3 enabled by default, the default value for the names attribute will be the same as the OpenSSL default cipher suites for TLS 1.3: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

    • Example configuration:

   <ssl-context name="myTLS13Context">
   ...
     <cipher-suite names="TLS_AES_128_CCM_8_SHA256:TLS_AES_256_GCM_SHA384"/>
   ...
   </ssl-context>

*

Nice-to-Have Requirements

Non-Requirements

  • The ability to use TLS providers other than the default JSSE provider is a non-requirement.

Test Plan

All testing should be done using the default JSSE provider. The TLS 1.3 cipher suites that are actually available will depend on this provider.

One-way and two-way SSL tests will be added that make use of the TLS 1.3 protocol and TLS 1.3 cipher suites. The java.specification.version system property will be used to make sure that these new tests only get run when JDK 11 is in use.

One thing that is important to note is that TLS 1.3 has made session IDs essentially obsolete. This means that the session ID can no longer reliably be used to test if a session was resumed. Instead, creation time can be used to test if a session was resumed. Currently, clients need to read from server after the first handshake in order to receive the NewSessionTicket that can be used for resumption. However, this may change once JDK-8209953 is resolved.

Community Documentation

Documentation will be added in the "Using the Elytron Subsystem" section in the WildFly documentation to indicate that the TLS 1.3 protocol can be used with JDK 11 or higher by configuring the cipher-suite-names attribute. The documentation should mention the limitations around session resumption.

A warning will be added to indicate that when there is a very large number of TLS 1.3 requests being made, it is possible that a drop in performance (throughput and response time) will occur compared to TLS 1.2 when JDK 11 is in use. Upgrading to newer JDK versions should improve performance.

Release Note Content

It is now possible to use TLS 1.3 with WildFly when running against JDK 11 or higher. However, if JDK 11 is in use and if there is a very large number of TLS 1.3 requests being made, it is possible that a drop in performance (throughput and response time) will occur compared to TLS 1.2. Upgrading to newer JDK versions should improve performance. For this reason, the use of TLS 1.3 is currently disabled by default. TLS 1.3 can be enabled by configuring the new cipher-suite-names attribute in the SSL Context resource definition in the Elytron subsystem. It is recommended to test for performance degradation prior to enabling TLS 1.3 in a production environment.