JDK-8245485 : Release Note: JEP 332: Transport Layer Security (TLS) 1.3
  • Type: Sub-task
  • Component: security-libs
  • Sub-Component: javax.net.ssl
  • Affected Version: 8u261
  • Priority: P3
  • Status: Closed
  • Resolution: Delivered
  • Submitted: 2020-05-20
  • Updated: 2022-06-17
  • Resolved: 2021-12-02
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 8u261 includes an implementation of the Transport Layer Security (TLS) 1.3 specification (RFC 8446). For more details including a list of the features that are supported, refer to the *Java Secure Socket Extension (JSSE) Reference Guide* documentation and [JEP 332](http://openjdk.java.net/jeps/332).

For TLS 1.3, the following new standard algorithm names are defined:
1. TLS protocol version name: TLSv1.3
2. `SSLContext` algorithm name: TLSv1.3
3. TLS cipher suite names for TLS 1.3: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384

TLS 1.3 is *disabled* for default SSLContext("SSL" or "TLS") for *client end-point*.

The TLS 1.3 protocol can be enabled using several mechanisms already available in the JDK.
For example, TLS 1.3 protocol can be enabled on SSL/TLS connections using SSLSocket/SSLEngine/SSLServerSocket APIs and system properties by the following:

1) `sslSocket.setEnabledProtocols(new String[] { "TLSv1.3", "TLSv1.2"});`
2) Setting up and using a TLSv1.3 based SSLContext :
    `SSLContext ctx = SSLContext.getInstance("TLSv1.3");`
3) Using the SSLParameters API:
    `sslParameters.setProtocols(new String[] {"TLSv1.3", "TLSv1.2"});`
4) The `jdk.tls.client.protocols` system property can also be used to control the protocols in use for a TLS connection. One may launch their application with this property. For example, `java -Djdk.tls.client.protocols="TLSv1.3,TLSv1.2"` enables TLSv1.3 and TLSv1.2 on client SSLSockets.
5) The `https.protocols` system property can also be used to control the protocols on connection obtained through use of the `HttpsURLConnection` class or `URL.openStream()` operations. For example, `-Dhttps.protocols=TLSv1.3,TLSv1.2`.

A new system property, `jdk.tls.server.protocols`, has been added to configure the default enabled protocol suite in the server side of the SunJSSE provider.
A new security property, `jdk.tls.keyLimits`, has been added for TLS 1.3. When the specified amount of data of a specific algorithm has been processed, a post-handshake Key and IV Update is triggered to derive new keys.

Note that TLS 1.3 is not directly compatible with previous versions. Although TLS 1.3 can be implemented with a backward-compatibility mode, there are still several compatibility risks to take into account when upgrading to TLS 1.3:

1. TLS 1.3 uses a half-close policy, while TLS 1.2 and prior versions use a duplex-close policy. For applications that depend on the duplex-close policy, there might be compatibility issues when upgrading to TLS 1.3. A new system property, `jdk.tls.acknowledgeCloseNotify`, is added. The default value of the system property is "false". If the system property is set to "true", a corresponding `close_notify` alert will be sent when receiving a `close_notify` alert, and the connection will be duplex closed.
2. The `signature_algorithms_cert` extension requires that pre-defined signature algorithms are used for certificate authentication. In practice, however, an application can use unsupported signature algorithms.
3. The DSA signature algorithm is not supported in TLS 1.3. If a server is configured to only use DSA certificates, it cannot upgrade to TLS 1.3.
4. The supported cipher suites for TLS 1.3 are not the same as TLS 1.2 and prior versions. If an application hard-codes cipher suites that are no longer supported, it cannot use TLS 1.3 without modifying the application code.
5. The TLS 1.3 session resumption and key update behaviors are different from TLS 1.2 and prior versions. The compatibility impact should be minimal; however, there could be a risk if an application depends on the handshake details of the TLS protocols.
6. The legacy `com.sun.net.ssl.dhKeyExchangeFix` system property has been removed from the new TLS implementation.

Improved JSSE debug logging format has been introduced to record the logger name, the logger level, the thread ID, the thread name, the time and the caller for each log item. Use the `javax.net.debug=all` system property to get full debug logs.