Add named groups (supported_groups) to ConnectionSpec for post-quantum key exchange

[yschimke]

Resolves #9497.

Summary

Adds the ability to configure TLS 1.3 named groups (the supported_groups extension) on a ConnectionSpec, so callers can require or prefer post-quantum hybrid key exchange such as X25519MLKEM768. Previously ConnectionSpec only exposed cipher suites and TLS versions, and the key-exchange algorithm is negotiated separately via supported_groups — so there was no way to require, restrict, or prefer PQC key exchange.

val pqcSpec = ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS)
    .namedGroups(NamedGroup.X25519MLKEM768, NamedGroup.X25519, NamedGroup.SECP256R1)
    .build()

[yschimke]

Prior art: how other HTTP/TLS stacks configure named groups

Named-group / post-quantum key-exchange configuration varies a lot across ecosystems — from per-client (Go), to per-provider (rustls), to a global JVM property (Netty/JDK), to no app-level API at all (Python). OkHttp's ConnectionSpec.namedGroups follows the per-configuration model.

Rust — reqwest / rustls (per-CryptoProvider; PQC on by default)
rustls with the aws-lc-rs backend enables X25519MLKEM768 first by default via the prefer-post-quantum feature. To set groups explicitly you build a CryptoProvider:

use rustls::crypto::{aws_lc_rs, CryptoProvider};

let provider = CryptoProvider {
    kx_groups: vec![
        rustls_post_quantum::X25519MLKEM768,
        aws_lc_rs::kx_group::X25519,
        aws_lc_rs::kx_group::SECP256R1,
    ],
    ..aws_lc_rs::default_provider()
};
provider.install_default().unwrap(); // process-wide; or .with_crypto_provider() per ClientConfig

Docs: CryptoProvider · rustls-post-quantum · rustls PQ key-exchange notes

Go — net/http / crypto/tls (per-tls.Config; closest analog to OkHttp)

client := &http.Client{Transport: &http.Transport{
    TLSClientConfig: &tls.Config{
        CurvePreferences: []tls.CurveID{tls.X25519MLKEM768, tls.X25519},
    },
}}

X25519MLKEM768 is the default since Go 1.24. Docs: tls.Config.CurvePreferences · Go 1.24 release notes

Netty (JVM) — no first-class API
SslContextBuilder exposes no named-groups setter. With the JDK provider, groups come from the global JVM system property (process-wide, not per-SslContext):

-Djdk.tls.namedGroups=X25519MLKEM768,x25519,secp256r1

For the OpenSSL/tcnative (BoringSSL) provider, configuring supported_groups is still an open request. Docs: SslContextBuilder · netty-tcnative#567 · jdk.tls.namedGroups (JEP 527)

Python — requests / urllib3 — no app-level API
ssl.SSLContext can only set a single curve, which can't express a hybrid PQC group or a list:

import ssl
ctx = ssl.create_default_context()
ctx.set_ecdh_curve("x25519")  # one curve only

A multi-group set_groups() / get_groups() API is only proposed. In practice PQC is transparent when Python links OpenSSL 3.5 (which sends X25519MLKEM768 by default) — there's no requests-level switch. Docs: set_ecdh_curve · cpython#136306 (proposed set_groups)

[yschimke]

Should OkHttp set named groups by default (and how does jdk.tls.namedGroups fit)?

jdk.tls.namedGroups is the JVM-wide system property that overrides the default named-group list for all SunJSSE TLS in the process. The question: should OkHttp ship a default named-group list (e.g. bake X25519MLKEM768 into MODERN_TLS), or leave namedGroups unset (null) and defer to the platform default / this property?

OkHttp's current behavior: namedGroups defaults to null, and the implementation only calls SSLParameters.setNamedGroups(...) when it is explicitly set. So an unset ConnectionSpec leaves jdk.tls.namedGroups and the platform default fully in effect — OkHttp does not clobber them.

Option A — keep the default null (defer to platform / jdk.tls.namedGroups) ✅ AI recommended

Pros

• Zero maintenance. OkHttp doesn't track an evolving named-group list (unlike the cipher-suite treadmill).
• Free PQC rollout. Platforms already move the default for us: JDK 27 (JEP 527) puts X25519MLKEM768 first by default; Conscrypt 2.6 likewise. Deferring means users get PQC automatically as their platform adopts it.
• Respects operator control. jdk.tls.namedGroups is the standard, documented knob; OkHttp not overriding it means ops can tune groups JVM-wide without fighting the library.
• No connectivity risk. A pinned-but-stale list could exclude a group a server needs, or include one a provider rejects. Deferring avoids that.
• Provider-agnostic. SunJSSE, Conscrypt, and BouncyCastle each have their own sensible defaults; we don't second-guess them.

Cons

• Non-deterministic across environments. Behavior depends on JDK/provider version, so two deployments can negotiate different groups.
• No guaranteed PQC. On platforms whose default lacks PQC, users get none unless they opt in.

Option B — bake a default list into MODERN_TLS/RESTRICTED_TLS

Pros

• Deterministic, version-pinned behavior tied to the OkHttp release, consistent with how cipher suites and TLS versions are already curated.
• Could guarantee PQC even where the platform default doesn't include it yet.

Cons

• Overrides jdk.tls.namedGroups. Setting groups on the socket wins over the JVM property, taking control away from operators — a surprising, hard-to-debug regression for anyone relying on the property.
• Maintenance + breakage risk. OkHttp would own a list that must track new groups every release; a stale list silently blocks newer/better key exchange or breaks servers that require a group we dropped.
• Provider/version skew. A baked name may be unsupported on some providers/versions; setNamedGroups is best-effort, so failures are silent and inconsistent.
• Redundant with the platform. On JDK 27 / Conscrypt 2.6 the default already leads with X25519MLKEM768, so pinning mostly duplicates the platform at the cost of the above.

AI Recommendation

Keep namedGroups defaulting to null (Option A). Ship the per-ConnectionSpec API so callers who need to require or restrict PQC can, and document jdk.tls.namedGroups as the JVM-wide alternative. Don't bake a default list into MODERN_TLS now — revisit only if a single PQC group becomes universally supported and a hard default is clearly worth the maintenance and override cost.