Java and Post-Quantum TLS

Hello, tekkix!

JEP 527 adds post-quantum hybrid key exchange support for TLS 1.3 to JDK 27. If an application runs on the standard JSSE stack via javax.net.ssl, then after migrating to JDK 27 with JEP 527, it will be able to use the new hybrid key exchange in TLS 1.3.

What's in this article

1. What is TLS

2. The "harvest now, decrypt later" problem

3. What JEP 527 adds

4. Why the key exchange is hybrid

5. What changes for developers

6. What might break

1. What is TLS

TLS is a protocol for secure network connections. It is used in HTTPS, database connections, external APIs, and internal mTLS.

Handshake is the initial phase of a TLS connection. During this phase, the client and server agree on the protocol version, security parameters, verify certificates, and prepare keys.

TLS negotiation is the process of agreeing on parameters within the handshake: TLS version, algorithms, supported groups, and other settings that both parties are capable of using.

Key exchange is the part of the handshake where the two parties obtain a shared secret. Keys used to encrypt application traffic are then derived from this secret.

2. The "harvest now, decrypt later" problem

Classic TLS 1.3 typically uses ECDHE (Ephemeral Elliptic-Curve Diffie-Hellman), a familiar and widely used key exchange mechanism. It provides forward secrecy. If the server certificate's private key is leaked a year later, old TLS sessions should not be automatically exposed. The secrets for these sessions were generated using temporary keys during the handshake, rather than directly using the server certificate's private key.

But classical elliptic curve algorithms have an unpleasant prospect. A sufficiently powerful quantum computer will be able to attack this type of cryptography in a way that is different from a regular computer. This does not mean that all HTTPS will break tomorrow morning, but there is a harvest now, decrypt later threat. An attacker can record encrypted traffic now, but cannot decrypt it at the moment. But if the data is valuable in five or ten years, the question arises: what will happen when more powerful quantum attacks appear? This does not matter for a 30-second one-time code. For medical or personal data, financial documents and commercial contracts, it is already more relevant. This is exactly why cryptographic migration is started well in advance, while there is still time to calmly update platforms, protocols and infrastructure.

3. What JEP 527 adds

JEP 527 adds support for three hybrid TLS 1.3 named groups to the JDK:

X25519MLKEM768
SecP256r1MLKEM768
SecP384r1MLKEM1024

The most important option for application developers is X25519MLKEM768. It is the one included in the default list of named groups and placed first. Roughly speaking, the Java client starts telling the server:

I support X25519MLKEM768.
I also support regular x25519.
If you can, let's choose the hybrid option.
If not, we'll go with the old option.

This change is not in HTTP, REST, or HttpClient code, but inside the TLS handshake. If the server also supports X25519MLKEM768, the two parties can choose a hybrid key exchange. If it does not support it, a fallback to a regular group such as x25519 should trigger. But due to proxies, WAFs, TLS terminators, outdated libraries, and custom settings, this still needs to be tested on your own infrastructure.

4. Why key exchange is hybrid

Hybrid here means: both classical ECDHE and post-quantum ML-KEM are used. ML-KEM is a standardized post-quantum KEM. This algorithm was previously known as Kyber. The building blocks for this have already been available in Java for a while:

• JEP 452 added the KEM API;

• JEP 496 added ML-KEM;

• JEP 527 uses this in TLS 1.3.

Why not switch directly to a pure post-quantum key exchange? Because cryptographic migrations are better carried out cautiously. Classical algorithms have been extensively studied for a long time and are highly optimized. Post-quantum algorithms are newer: they have different key and message sizes, and a different performance profile. They still need to be widely rolled out and tested across infrastructure at scale. The hybrid approach uses both mechanisms simultaneously. If ECDHE ever becomes a vulnerability due to quantum attacks, ML-KEM remains as a backup. If a critical flaw is discovered in the new post-quantum algorithm, the classical component remains functional. This does not provide absolute protection against all threats. But it is a sensible transitional setup for the massive existing TLS ecosystem.

5. What changes for developers

If you use standard Java TLS via javax.net.ssl, your application code may not need to change at all. For example:

HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_2)
        .build();

This code contains neither ML-KEM nor X25519MLKEM768. But the TLS handshake is handled by the JDK itself. This means that after you update your runtime, the handshake behavior may change. This is the key practical consideration.

6. What can break

TLS negotiation is designed to be backward compatible. The client offers both hybrid key exchange groups and standard groups. The server selects whichever set of groups it supports. If hybrid groups are not supported, the standard x25519 group is selected. Issues arise in cases where infrastructure behaves in unexpected ways. For example:

• old proxy does not handle large ClientHello messages well;

• WAF(Web Application Firewall) incorrectly parses new named groups;

• TLS terminator(nginx or load balancer) hasn't been updated for several years;

• the application has a hardcoded list of groups with no fallback;

• JSSE is not used, and a different TLS provider is employed instead;

• different services in the mTLS environment run on vastly different runtimes.

Key practical point: post-quantum key exchange increases the size of the key share. ClientHello can become larger. Modern infrastructure should be able to handle this. However, old proxies, WAFs, or TLS terminators may fail to process such a handshake. Typical symptoms include:

• handshake timeout;

• SSLHandshakeException;

• connection reset;

• error occurs only via a specific proxy;

• works from one network but not from another.

Conclusion

JEP 527 updates the TLS 1.3 key exchange in the standard Java JSSE implementation. For this reason, HTTP client application code typically does not need to be modified. The behavior of the TLS handshake is changed at the JDK level.

After migrating to JDK 27, the Java client will be able to prioritize X25519MLKEM768 if the server supports it. If the server does not support the hybrid group, a fallback to classic groups such as x25519 must be used.

Before migration, you should verify jdk.tls.namedGroups, custom SSLParameters, critical endpoints, proxies, and TLS terminators. It is also important to understand where TLS is actually terminated: in the Java application, on nginx, on a load balancer, or in another component.

JEP 527 does not make the system fully protected against quantum attacks. It adds support for hybrid post-quantum key exchange for TLS 1.3 in Java. For the application team, this is a reason to verify the TLS-handshake when migrating to JDK 27.

References

• JEP 527: Post-Quantum Hybrid Key Exchange for TLS 1.3 - https://openjdk.org/jeps/527

• JEP 452: Key Encapsulation Mechanism API - https://openjdk.org/jeps/452

• JEP 496: Quantum-Resistant Module-Lattice-Based Key Encapsulation Mechanism - https://openjdk.org/jeps/496

If you liked the article, welcome to my blog!

Wishing you secure releases!