skip to content

What did TLS 1.3 change from TLS 1.2 for a Java service that uses JSSE?

level: middleimportance: should knowfreq 38%

answer

  1. no new API, new names
  2. suite names lose key exchange
  3. renegotiation becomes KeyUpdate
  4. half-close and late client-cert errors
  5. 27 prefers a hybrid group

basics

~20 s

TLS 1.3, added in JDK 11 without new public API, is enabled and preferred by default on JDK 25 and 27. Java code sees new suite names, no renegotiation, half-close, later client-certificate failures and authType UNKNOWN in custom trust managers.

solid answer

~40 s

JEP 332 added TLS 1.3 in JDK 11 with no new public API, so most code just negotiates it: on 25 and 27, `SSLContext.getInstance("TLS")` enables `TLSv1.3` and `TLSv1.2`. The differences show at the edges. Suites are new, such as `TLS_AES_256_GCM_SHA384`, so a hard-coded TLS 1.2 list silently keeps you on 1.2. Renegotiation is gone: a second `startHandshake()` sends a `KeyUpdate`. Closing is half-close, so each side should close both directions. A rejected client certificate can surface on the first read rather than in `startHandshake()`, and a custom `X509TrustManager` receives `authType` `UNKNOWN` in `checkServerTrusted`. DSA certificates cannot be used. JDK 27 also prefers the hybrid post-quantum group `X25519MLKEM768`, where 25 starts with `x25519`.

go deeper

for a junior

Recall that Java has supported TLS 1.3 since JDK 11, that it is negotiated by default, and how to read the negotiated protocol from SSLSession.

for a middle

Explain the visible changes: suite names, no renegotiation, half-close, later client-certificate failures, authType UNKNOWN, and why a versioned getInstance name does not pin the protocol.

for a senior

Show upgrade judgment: find hard-coded suites and authType checks, test mutual-TLS error paths on the first read, and verify close handling under half-close.

for a principal

Set the policy: which protocol versions and named groups services allow, when to rely on hybrid key exchange, and how to roll changes out against peers that lag.

## Where TLS 1.3 came from in Java TLS 1.3 reached Java in **JDK 11** through JEP 332, which states that no new public API was needed for its minimal implementation, only new standard names: `TLSv1.3` for the protocol and the `SSLContext`, plus new cipher suite names. A service that upgrades therefore usually negotiates TLS 1.3 with no code change. How the protocol works on the wire is covered with the TLS protocol itself; this answer is about what a Java program sees. On JDK 27, as on 25, `SSLContext.getInstance("TLS")` enables `TLSv1.3` and `TLSv1.2` on the client and server sides, and `TLSv1` and `TLSv1.1` sit in the default `jdk.tls.disabledAlgorithms` security property. `SSLSession.getProtocol()` and `getCipherSuite()` report what was negotiated. ## What your code sees differently | Area | TLS 1.2 in JSSE | TLS 1.3 in JSSE | |---|---|---| | Cipher suite names | `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` names key exchange and signature | `TLS_AES_256_GCM_SHA384` names neither | | `authType` passed to `checkServerTrusted` | The key exchange, such as `ECDHE_ECDSA` | `UNKNOWN` | | A second `startHandshake()` | Starts a renegotiation | Sends a `KeyUpdate`, since renegotiation is forbidden | | Closing | Duplex close | Half-close: each direction closes on its own | | Server rejects a client with no certificate | The client's `startHandshake()` fails | `startHandshake()` can return, then the first read fails with `certificate_required` | | DSA certificates | Still usable through DSS suites | Not supported | The consequences: - **Hard-coded cipher lists.** Enabling only TLS 1.2 suites with `setEnabledCipherSuites` silently keeps the connection on TLS 1.2, even when both sides support 1.3. Restricting the protocols to `TLSv1.3` as well makes the handshake fail with `No appropriate protocol (protocol is disabled or cipher suites are inappropriate)`. - **Custom trust managers.** The `X509TrustManager` Javadoc describes the server-side `authType` as the key-exchange part of the suite, which TLS 1.3 suites no longer have, so code that branches on it needs another signal. - **Mutual TLS errors.** Error handling that wraps only `startHandshake()` misses a rejected client certificate under TLS 1.3, because it can surface on the first read. - **Closing.** Each side should close both directions. The JSSE guide warns that closing only one side with `SSLEngine.closeInbound()` or `closeOutbound()` can hang or time out; the `jdk.tls.acknowledgeCloseNotify` system property, `false` by default, restores a duplex close as a fallback. - **Key limits.** The `jdk.tls.keyLimits` security property defaults to `AES/GCM/NoPadding KeyUpdate 2^37, ChaCha20-Poly1305 KeyUpdate 2^37`, so a long-lived connection updates its keys with no action from your code. - **DSA-only servers.** A server whose only certificate has a DSA key does not quietly fall back: with default protocols on both sides it picks TLS 1.3, finds no usable certificate and fails the handshake with `No available authentication scheme`, while the client sees a `handshake_failure` alert. Replace the key with an EC or RSA one; pinning the protocols to `TLSv1.2` only papers over it. - **Resumption.** It now uses pre-shared keys from session tickets sent after the handshake; the release notes expect minimal impact unless an application depends on handshake details. ## Pinning a version The name passed to `getInstance` is not a ceiling: - `SSLContext.getInstance("TLSv1.2")` enables only `TLSv1.2` in client mode, but server mode still enables `TLSv1.3` and `TLSv1.2`. - `SSLContext.getInstance("TLSv1.3")` still enables `TLSv1.2` on both sides. - To pin a connection, call `SSLParameters.setProtocols` or `setEnabledProtocols`. - To change process defaults, set `jdk.tls.client.protocols` or `jdk.tls.server.protocols`; they apply to the `TLS` and `Default` contexts, not to the versioned ones. ## What JSSE leaves out JEP 332 did not implement 0-RTT early data or post-handshake client authentication. On JDK 27 and 25 the private `SSLExtension` enum still lists `early_data` and `post_handshake_auth` with no implementation attached, so a Java peer neither sends early data nor requests a client certificate after the handshake. The post-handshake messages it does handle are `KeyUpdate` and, on the client, `NewSessionTicket`. ## What JDK 27 adds - **Post-quantum hybrid key exchange** (JEP 527). The default named groups start with `X25519MLKEM768`, which combines X25519 with ML-KEM-768 to defend against traffic recorded now and decrypted later by a quantum computer. A client offers `X25519MLKEM768` and `x25519` key shares, so a peer without the hybrid group can still use `x25519`. It applies to TLS 1.3 only. On JDK 25 the list starts with `x25519` and has no hybrid group. - **Certificate compression** with zlib for TLS 1.3, on by default; adding `compress_certificate` to `jdk.tls.client.disableExtensions` and `jdk.tls.server.disableExtensions` turns it off. - `ffdhe6144` and `ffdhe8192` left the default named-group list. To choose groups yourself, set `jdk.tls.namedGroups` or call `SSLParameters.setNamedGroups`.

  • A javax.net.debug log shows TLSv1.2 in the ClientHello's version field. Did the client fail to offer TLS 1.3?
    No. The JSSE guide explains that for TLS 1.3 this legacy field holds the fixed value `TLSv1.2`, and the real offer travels in the `supported_versions` extension. Read that extension in the log, or check `SSLSession.getProtocol()` after the handshake.
  • Does SSLContext.getInstance("TLSv1.2") keep a Java server on TLS 1.2?
    No. On JDK 27 and 25 that context enables only `TLSv1.2` in client mode, but in server mode it still enables `TLSv1.3` and `TLSv1.2`, so a TLS 1.3 client gets 1.3. Pin the server with `SSLParameters.setProtocols` or `setEnabledProtocols` on the server socket or engine.
  • How do you confirm a JDK 27 connection used the hybrid group, and when will it not?
    Run with `-Djavax.net.debug=ssl:handshake` and read the `key_share` extension in the ServerHello, which names the chosen group. The hybrid group is not used when the peer lacks it, when TLS 1.2 is negotiated, or when `jdk.tls.namedGroups` or `SSLParameters.setNamedGroups` leaves it out.

  • JSSE needed new TLS 1.3 APIs, so existing socket code must be rewritten to use it.
  • Getting an SSLContext named TLSv1.2 guarantees a Java server never negotiates TLS 1.3.
  • Calling startHandshake again on a TLS 1.3 connection renegotiates the session.
  • A custom trust manager can still read the key exchange from authType under TLS 1.3.
  • JSSE sends 0-RTT early data when it resumes a TLS 1.3 session.
  • The hybrid key exchange in JDK 27 also requires post-quantum certificates on the server.

TLS 1.3 in JSSE (TLSv1.3)
Java 11
jdk.tls.keyLimits security property
Java 11
Post-quantum hybrid key exchange for TLS 1.3
Java 27

Assumes Java 27; TLS 1.3 has been in JSSE since JDK 11, and the hybrid key exchange, certificate compression and group-list changes named here are absent on JDK 25.

context