Skip to main content

Module hybrid_kem

Module hybrid_kem 

Source
Expand description

Hybrid multi-KEM key agreement (“HyKEM”) — #551 / S0 of epic #550.

A component-pluggable hybrid Key Encapsulation Mechanism whose combined shared secret is secure as long as at least one component KEM remains unbroken (the standard “secure-if-one-holds” combiner property). This is the confidentiality counterpart to the hybrid EdDSA + ML-DSA-65 signature stack in crate::crypto::cose_sign.

§Construction

A SuiteId fixes an ordered list of component KEMs. Encapsulation runs every component against the recipient’s per-component encapsulation key, collects each (ciphertext, shared_secret), and folds them into a single 32-byte secret with a KMAC256 transcript-binding combiner (NIST SP 800-185), generalizing the X-Wing combiner (SHA3-256(ss_M ‖ ss_X ‖ ct_X ‖ pk_X ‖ label), draft-connolly-cfrg-xwing-kem) to N components:

K  = KMAC256_DOMAIN_KEY                       (fixed 32-byte domain key)
S  = "HyKEM-v1-combiner" ‖ 0x00 ‖ suite_id    (KMAC customization string)
X  = be16(suite_id) ‖ be32(n)
     ‖  Σ_i lp(ss_i)                           (ALL component shared secrets)
     ‖  Σ_i lp(ct_i)                           (ALL component ciphertexts)
     ‖  Σ_i lp(ek_i)                           (ALL recipient encap keys)
secret = KMAC256(K, X, L=256 bits, S)

where lp(x) = be32(len(x)) ‖ x and the component order is the suite’s.

§Why secure-if-one-holds

KMAC256 is a PRF keyed by a fixed domain key. Every component shared secret is an input block, so the output is pseudorandom to an adversary who is missing any single ss_i — breaking N-1 components (learning their secrets) does not let them predict the output while one ss_i stays unknown. Including every ct_i and recipient ek_i binds the full transcript (X-Wing binds the X25519 ct/pk for exactly this reason), so a component’s ciphertext cannot be swapped without changing the key.

§Why suite-bound (extensibility without collisions)

The suite_id is folded into both the KMAC customization string S and the message X. A future suite that appends a third (e.g. non-lattice) leg is a new SuiteId with a distinct id, so its combined secret is in a separate domain and can never collide with the 2-KEM suite’s — the trait and combiner never name a concrete KEM, so adding a leg is additive (epic #550 §3). Suite selection is a pinned policy decision; there is no in-band negotiation.

§Forward secrecy

The X25519 leg is modeled as DHKEM (RFC 9180 §4.1): each encapsulation uses a fresh ephemeral X25519 key, so that leg is forward-secret. The ML-KEM leg encapsulates to the recipient’s (possibly long-lived) key; forward secrecy of the suite therefore rests on the ephemeral X25519 leg unless the ML-KEM key is itself ephemeral/rotated (handled by the caller — streams use ephemeral ML-KEM keys per #554; the envelope uses rotated #mesh-kem prekeys per #552).

§Wasm

All components are pure Rust (x25519-dalek, ml-kem, tiny-keccak) and compile to wasm32-unknown-unknown.

§Scope (S0)

This module is the primitive + Rust wire types only. The Cap’n Proto schema wiring of HybridKemMaterial into RequestEnvelope / StreamInfo / SignedEnvelope is deferred to S3 (#554) and S4 (#555).

Structs§

HybridKemMaterial
The full set of per-component ciphertexts for a hybrid encapsulation, tagged with the suite. Replaces the legacy single fixed-ML-KEM-ciphertext field; the Cap’n Proto field wiring lands in S3/S4.
KemPrekey
A short-lived, rotated #mesh-kem recipient prekey.
KemShare
One component’s encapsulated ciphertext, tagged with its KemId.
KeyedKemTrustStore
In-memory kid-anchored #mesh-kem trust store: Ed25519 signer identity → anchored hybrid-KEM RecipientPublic. Bindings come from the node’s own hybrid identity and from attested peer identities (their resolved DID keyAgreement), established out-of-band — never from wire-asserted material.
MlKem768Kem
ML-KEM-768 (FIPS 203) component. The recipient decapsulation key is carried as its 64-byte FIPS 203 seed (d ‖ z).
RecipientKeypair
A recipient’s hybrid keypair: per-component decapsulation keys (secret) and encapsulation keys (public), in suite-component order.
RecipientPublic
A recipient’s public hybrid material: per-component encapsulation keys in suite order. This is what an encapsulator needs (published via #mesh-kem for the envelope, or sent in the stream handshake — wiring in S3/S4).
X25519Kem
X25519 as a DHKEM (RFC 9180 §4.1): Encap picks a fresh ephemeral key, the ciphertext is the ephemeral public key, and the shared secret is the X25519 DH output. The ephemeral key gives this leg forward secrecy.

Enums§

KemId
Stable wire identifier for a single KEM component.
SuiteId
A pinned hybrid-KEM suite: an ordered set of component KEMs plus a stable id that is cryptographically bound into the combiner.

Traits§

KemComponent
One KEM component of a hybrid suite.
KemTrustStore
Resolves the anchored hybrid-KEM recipient public material for a peer’s Ed25519 signer identity (its #mesh-kem keyAgreement key).

Functions§

decapsulate
Decapsulate hybrid material with a recipient keypair, recovering the same combined 32-byte shared secret. Fails closed on suite/share mismatch.
encapsulate_to
Encapsulate to a recipient’s public material, returning the wire HybridKemMaterial (the per-component ciphertexts) and the combined 32-byte shared secret.
generate_recipient
Generate a fresh recipient keypair for suite (one component keypair each).
recipient_from_seeds
Deterministically build a recipient keypair for suite from per-component seeds — one per suite component, in suite order, each of that component’s KemComponent::seed_len.