Ciphersuites

A suite selects a key encapsulation mechanism (KEM), key derivation function (KDF), and authenticated cipher (AEAD). Both peers must use the same suite. Sizes below are bytes; IDs are hexadecimal wire codepoints.

open Hpke

let suite =
  Suite.create ~kem:Kem.X25519 ~kdf:Kdf.Hkdf_sha256 ~aead:Aead.Aes_128_gcm

let exporter =
  Suite.export_only ~kem:Kem.X25519 ~kdf:Kdf.Hkdf_sha256

Registries use OCaml variants. Convert wire IDs with of_int; unknown IDs return Unsupported_algorithm. Hybrid KEMs and Draft_hpke_04 require 0.4.0 or newer.

KEM

Public and Private are serialized key sizes; Enc is the encapsulated key size; Secret is the shared secret size. Read them through Kem.public_key_size, private_key_size, encapsulated_key_size, and secret_size. Kem.supports_auth reports Auth support.

X448 backends

X448 uses curve448's OCaml backend by default. Add curve448.c to your executable's libraries to select its C backend. With ocamlfind, link curve448.ocaml or curve448.c explicitly.

ML-KEM

These KEMs use FIPS 203 ML-KEM from mlkem with the HPKE integration from draft-ietf-hpke-pq-05. They support Base and PSK; Auth and AuthPSK return Unsupported_mode.

• Private keys serialize as a 64-byte seed (d || z), not an expanded decapsulation key.
• Parsing a private key runs key generation; parsing a public key expands its matrix. Parse once and reuse.
• A tampered encapsulation of the correct length produces an unrelated secret without a setup error (implicit rejection). The first open returns Open_error; export-only protocols must confirm the secret with the peer.
• derive_key_pair derives the seed using SHAKE256. Store the private key, not just its derivation input: the draft may change.

The draft prefers ML-KEM-768 and ML-KEM-1024 to ML-KEM-512. mlkem is unaudited and does not guarantee constant-time execution; read the dependency limits.

Hybrid KEMs

MLKEM768-P256, MLKEM768-X25519 (X-Wing), and MLKEM1024-P384 combine ML-KEM with an elliptic-curve exchange using SHA3-256. They follow draft-ietf-hpke-pq-05 and draft-irtf-cfrg-concrete-hybrid-kems. Like ML-KEM, they support Base and PSK only.

• Private keys are 32-byte seeds. SHAKE256 expands each into an ML-KEM seed and a curve scalar.
• A public key is the ML-KEM key followed by a group element. An encapsulated key is the ML-KEM ciphertext followed by an ephemeral group element.
• The ML-KEM half uses implicit rejection. An invalid curve point or low-order X25519 value returns Invalid_encapsulation at receiver setup.

This implementation rejects all-zero X25519 exchanges, although the concrete hybrid draft leaves them unchecked. Honest senders do not produce them. The draft and key-derivation caveats above also apply.

KDF

HKDF exports allow 0 through 255 times the hash size. A negative or excessive length returns Export_length_out_of_range.

SHAKE KDFs

These KDFs are available only in Hpke.Draft_hpke_04. Its registry also includes the three HKDFs above.

The one-stage schedule derives the key, base nonce, and exporter secret in one LabeledDerive call. Each of info, the PSK, and its identifier is limited to 65,535 bytes; longer inputs return Invalid_length. Exports allow 0 through 65,535 bytes. Nh is the KDF parameter returned by hash_size.

AEAD

Export-only is a separate suite type. It supports context setup and export, but cannot be passed to encryption or decryption functions.

Modes

Draft_hpke_04 provides Base and PSK only.

Key validation

• All parsers check the exact encoded length.
• NIST public keys must be uncompressed SEC1 points on the curve. Private scalars must be non-zero and below the curve order.
• X25519 and X448 private keys are clamped on parsing and serialization. Low-order public values are rejected when used.
• ML-KEM public keys must pass the FIPS 203 modulus check. Every 64-byte private seed is accepted.
• Hybrid keys validate both components. P-256 and P-384 seed expansion can fail to find a scalar with negligible probability.

Limits

• Exhausting a context's 96-bit sequence returns Message_limit_reached.
• Plaintexts beyond the AEAD limit return Plaintext_too_long.
• Ciphertexts shorter than the tag return Open_error without advancing the sequence.
• Exports follow the KDF limits above and do not advance the sequence.

Not provided

Transport framing, key management, compressed NIST points, expanded ML-KEM private keys, and TurboSHAKE KDFs. Private keys and PSKs have no printers or equality helpers.

Protocol versions

Hpke.Rfc9180 keeps its RFC wire behavior. Hpke.Draft_hpke_04 implements draft-ietf-hpke-hpke-04 with Base, PSK, and the SHAKE KDFs. With HKDF, it produces the same encapsulations, ciphertexts, and exports as Rfc9180. Keys, AEADs, PSKs, and context types are shared.

let draft_suite =
  Draft_hpke_04.Suite.create ~kem:Kem.Mlkem768_x25519
    ~kdf:Draft_hpke_04.Kdf.Shake256 ~aead:Aead.Chacha20_poly1305

let send ~rng ~recipient ~plaintext =
  Draft_hpke_04.seal_base ~rng draft_suite ~recipient
    ~info:"example-v1" ~aad:"" ~plaintext

A later HPKE draft that changes wire behavior gets a separate module. The ML-KEM and hybrid KEM integrations also follow drafts; pin versions when testing interoperability.