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§
- Hybrid
KemMaterial - 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-kemrecipient prekey. - KemShare
- One component’s encapsulated ciphertext, tagged with its
KemId. - Keyed
KemTrust Store - In-memory kid-anchored
#mesh-kemtrust store: Ed25519 signer identity → anchored hybrid-KEMRecipientPublic. Bindings come from the node’s own hybrid identity and from attested peer identities (their resolved DIDkeyAgreement), established out-of-band — never from wire-asserted material. - MlKem768
Kem - ML-KEM-768 (FIPS 203) component. The recipient decapsulation key is carried
as its 64-byte FIPS 203 seed (
d ‖ z). - Recipient
Keypair - A recipient’s hybrid keypair: per-component decapsulation keys (secret) and encapsulation keys (public), in suite-component order.
- Recipient
Public - A recipient’s public hybrid material: per-component encapsulation keys in
suite order. This is what an encapsulator needs (published via
#mesh-kemfor the envelope, or sent in the stream handshake — wiring in S3/S4). - X25519
Kem - X25519 as a DHKEM (RFC 9180 §4.1):
Encappicks 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.
- KemTrust
Store - Resolves the anchored hybrid-KEM recipient public material for a peer’s
Ed25519 signer identity (its
#mesh-kemkeyAgreement 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
suitefrom per-component seeds — one per suite component, in suite order, each of that component’sKemComponent::seed_len.