Crate mlkem_tls 

mlkem-tls

X25519MLKEM768 and X25519MLKEM1024 hybrid post-quantum kems, per draft-ietf-tls-ecdhe-mlkem. wire-format compatible with the TLS 1.3 codepoint 0x11EC, which Cloudflare, Chrome, Firefox and rustls >= 0.23.27 ship today.

hybrid construction

• classical half: x25519-dalek (audited, constant-time).
• post-quantum half: mlkem-rs (FIPS 203 ML-KEM in pure rust).
• combiner: concatenation of the two shared secrets, ML-KEM first. no kdf wrapper. matches §1.5 of draft-ietf-tls-ecdhe-mlkem-04.

the wire byte order also matches the draft: ML-KEM bytes come first, X25519 bytes come second, both for public keys (sent client to server) and ciphertext (sent server to client).

security falls back to the stronger of the two halves: a quantum adversary that breaks X25519 still cannot read traffic protected by the resulting key, and a classical adversary that breaks ML-KEM still cannot read traffic protected by it.

quick start

use mlkem_tls::X25519MlKem768;
use rand::thread_rng;

let mut rng = thread_rng();

// bob: generate the long-term hybrid keypair, send the encaps key over the wire.
let (bob_ek, bob_dk) = X25519MlKem768::keygen(&mut rng);

// alice: encapsulate against bob's encaps key.
let (ct, alice_ss) = X25519MlKem768::encapsulate(&bob_ek, &mut rng);

// bob: decapsulate to recover the same 64-byte shared secret.
let bob_ss = X25519MlKem768::decapsulate(&bob_dk, &ct);
assert_eq!(alice_ss.as_bytes(), bob_ss.as_bytes());

variants

• X25519MlKem768: TLS codepoint 0x11EC. encaps key 1216 B, ciphertext 1120 B, shared secret 64 B. this is the one browsers ship.
• X25519MlKem1024: non-standard symmetric variant for those who want the higher security category. encaps key 1600 B, ciphertext 1600 B, shared secret 64 B.

features

• std (default): standard-library hooks on the dependencies. disable for no_std + alloc builds (cortex-m, wasm32).

not audited

the post-quantum half delegates to mlkem-rs, which is unaudited. for production cryptography, please use rustls’s built-in PQ provider, which ships rustcrypto’s audited ml-kem plus the same X25519 hybrid combiner. this crate exists for stacks that don’t use rustls (custom QUIC, MLS PQ ciphersuites, HPKE PQ extensions, embedded TLS) and need the hybrid combiner as a stand-alone reusable kem.

Structs

Ciphertext768Hybrid

Ciphertext1024Hybrid

DecapsKey768

DecapsKey1024

EncapsKey768

EncapsKey1024

LengthError

returned when bytes handed to try_from have the wrong length.

SharedSecret768Hybrid

SharedSecret1024Hybrid

X25519MlKem768

X25519MlKem1024

Constants

MLKEM_SS_BYTES

length of the ML-KEM portion of the shared secret in bytes.

SHARED_SECRET_BYTES

total hybrid shared-secret length: ML-KEM ss (32) || X25519 ss (32).

X25519_BYTES

length of the X25519 public key in bytes.

X25519_SS_BYTES

length of the X25519 shared secret in bytes.