Skip to content

README.md

Latest commit

 

History

History
209 lines (149 loc) · 15.7 KB

README.md

File metadata and controls

209 lines (149 loc) · 15.7 KB
Raw

hpke-ng

CI License

A clean-slate Rust implementation of HPKE (RFC 9180) with type-driven ciphersuite selection.

Read the announcement: hpke-ng: Faster, Smaller, Harder HPKE for Rust — for the full design rationale, benchmarks, and migration notes.

use hpke_ng::*;
use rand::rngs::SysRng;
use rand_core::UnwrapErr;

type Suite = Hpke<DhKemX25519HkdfSha256, HkdfSha256, ChaCha20Poly1305>;

let mut os = SysRng;
let mut rng = UnwrapErr(&mut os);
let (sk_r, pk_r) = DhKemX25519HkdfSha256::generate(&mut rng)?;
let (enc, ct)  = Suite::seal_base(&mut rng, &pk_r, b"info", b"aad", b"hello")?;
let pt         = Suite::open_base(&enc, &sk_r, b"info", b"aad", &ct)?;
assert_eq!(pt, b"hello");
# Ok::<_, hpke_ng::HpkeError>(())

Why a new HPKE crate?

hpke-ng exists because three friction points in the existing Rust HPKE story kept producing real bugs and real overhead:

  1. Provider abstraction overhead. A trait-based pluggable backend pushes dispatch costs into hot paths and inflates the Hpke struct to hundreds of bytes — for a value the type system already knows.
  2. Struct-owned PRNG hazard. When the Hpke instance owns its RNG, cloning silently aliases randomness state. The fix is structural: don't own it.
  3. Type-system gaps. Option<&[u8]> for mode-specific parameters turns missing-PSK and wrong-mode into runtime errors that should be compile errors.

The design takes one position on each: no provider abstraction, no owned RNG, type parameters instead of mode enums. The math is a solved problem; the surrounding library is where the engineering still has slack.

Design highlights

  • Type-parameterized API. Hpke<K, F, A> is zero-sized; the ciphersuite lives in the type system. Mismatched primitives are compile errors.
  • Four explicit methods per mode. seal_base, seal_psk, seal_auth, seal_auth_psk — no Option<&[u8]> parameters for required-by-mode arguments.
  • Validated PSK bundle. PSK modes take a single Psk, built by Psk::new(secret, id), which enforces the RFC 9180 32-byte minimum up front. The PSK and its identifier — one secret, one usually public — cannot be transposed at a call site.
  • Auth restricted to DHKEMs at the type level. Hpke::<XWingDraft06, ...>::seal_auth(...) does not compile.
  • Export-only restricted at the type level. Hpke::<_, _, ExportOnly>::seal_base(...) does not compile; only *_export* methods are available.
  • Type-tagged keys. Private keys carry their KEM in their type, so passing a DhKemP256 key into an X25519 suite is rejected by the compiler, not at runtime.
  • Caller-provided RNG. No PRNG owned by the configuration; cloning cannot alias randomness.
  • Structural nonce-reuse prevention. Context is non-cloneable and refuses to encrypt at seq == u64::MAX.
  • no_std + alloc. HpkeError implements core::error::Error regardless; the default std feature only forwards std to the subtle dependency.
  • One provider stack. All primitives from RustCrypto-org crates.

Compile-time guarantees

Operation Elsewhere hpke-ng
Calling seal_auth on a non-DH KEM Runtime error Compile error
Using a wrong-KEM private key Runtime mismatch Compile error (type-tagged)
Base-mode call with a PSK supplied Runtime error Compile error (no PSK param)
Encrypt with an ExportOnly AEAD Runtime error Compile error
Transposing psk and psk_id Silent wrong key Not expressible (one Psk arg)

Supported ciphersuites

Component Variants
KEMs DhKemX25519HkdfSha256, DhKemX448HkdfSha512, DhKemP256HkdfSha256, DhKemP384HkdfSha384, DhKemP521HkdfSha512, DhKemK256HkdfSha256
KEMs (post-quantum, pq feature) XWingDraft06, MlKem768, MlKem1024 — registered by draft-ietf-hpke-pq, not RFC 9180
KDFs HkdfSha256, HkdfSha384, HkdfSha512
AEADs Aes128Gcm, Aes256Gcm, ChaCha20Poly1305, ExportOnly
Modes Base, Psk, Auth, AuthPsk

Performance

hpke-ng is benchmarked head-to-head against the two major Rust HPKE libraries, hpke-rs and rust-hpke, across 137 benchmark cells (76 against hpke-rs, 61 against rust-hpke) spanning every supported ciphersuite. A cell counts as a tie when the two medians fall within ±2% of each other.

Comparison Cells Wins Ties Losses
vs hpke-rs 76 61 13 2
vs rust-hpke 61 38 7 16
Combined 137 99 20 18

rust-hpke has no standalone ML-KEM-768 / ML-KEM-1024 and no secp256k1 support, so those ciphersuites are scored only against hpke-rs.

Where the KEM wins come from

Most of the speedup traces to two pieces of caching. On the decapsulation path, hpke-ng stores the expanded FIPS 203 decapsulation key directly in the PrivateKey, whereas hpke-rs rebuilds it from the seed on every setup_receiver. For classical KEMs, caching the recipient's serialized public key alongside the secret removes a redundant base-point scalar multiplication on every decap.

Operation vs hpke-rs vs rust-hpke
ML-KEM-768 / 1024 decap 54–56% faster n/a
X25519 decap 44% faster 51% faster
X-Wing decap 38% faster ≈ parity ¹
ML-KEM encap 33–41% faster n/a
X-Wing encap 15% faster ≈ parity

¹ rust-hpke wraps raw decap inside a full HPKE setup, so the closest comparison is hpke-ng's setup_receiver, which lands at roughly parity.

AEAD and single-shot throughput

Operation vs hpke-rs vs rust-hpke
Export (all 5 output lengths) 71–76% faster —
Single-shot open (all payloads) 13–41% faster 8–47% faster
AES-128-GCM single-shot seal 9–22% faster (≤ 16 KiB) 29–51% faster (≤ 4 KiB); slower ≥ 16 KiB
Post-setup Context::seal (64 B) 13% faster 44% faster
End-to-end roundtrip (1 KiB) 30% faster 49% faster

Export is the largest sustained advantage over hpke-rs. For bulk AEAD the per-byte rates converge as payloads grow: rust-hpke pulls ahead on AES-GCM at ≥ 16 KiB, and on post-setup Context::seal at ≥ 1 KiB, once framing overhead stops dominating.

(n/a = unsupported by that library; — = no separate head-to-head figure reported.)

Memory and binary footprint

Quantity hpke-rs hpke-ng rust-hpke
Hpke<K, F, A> struct 344 bytes 0 bytes (PhantomData) n/a
Context<_, _, ChaCha20Poly1305> struct 424 bytes 88 bytes 96 bytes
Context<_, _, ExportOnly> struct n/a 56 bytes 184 bytes
Context<_, _, Aes128Gcm> struct 424 bytes 792 bytes 912 bytes
Context<_, _, Aes256Gcm> struct 424 bytes 1,048 bytes 1,168 bytes
Minimal release binary 586 KB 370 KB (~37% smaller than hpke-rs) 385 KB

Notes on the table above:

  • rust-hpke has no typed configuration handle — it uses free setup_sender / setup_receiver functions rather than a struct like Hpke<K, F, A>, so that row is n/a. Its context types are AeadCtxS<A, Kdf, Kem> (sender) and AeadCtxR<A, Kdf, Kem> (receiver), measured here as AeadCtxS with X25519HkdfSha256 + HkdfSha256.
  • Context size grows by Nh bytes with a larger KDF — e.g. +32 bytes for HkdfSha512.
  • ExportOnly maps to rust-hpke's ExportOnlyAead. It is larger there (184 B vs 56 B) because rust-hpke's AeadCtx always reserves space for a full nonce buffer regardless of the AEAD variant.
  • The AES-GCM Context rows are larger in hpke-ng than in hpke-rs because the expanded round keys + GHash table are cached inline — which is exactly what eliminates the per-call AES key-schedule cost in Context::seal. AES-GCM streaming trades memory for throughput; ChaCha20-Poly1305 is unaffected.

Reproducing the benchmarks

Build with RUSTFLAGS="-C target-cpu=native" to pick up AES-NI / SHA-NI where available; [profile.bench] in Cargo.toml sets lto = "thin" and codegen-units = 1. For the head-to-head numbers:

cargo bench --features comparative --bench comparative

This loads both hpke-rs (with its experimental feature, so the post-quantum KEM stubs are wired up) and rust-hpke 0.14 (whose X-Wing support the comparison needs) as dev-dependencies, and emits side-by-side criterion results for every supported ciphersuite. KEM-op rows for hpke-rs and rust-hpke carry a _via_setup_* suffix: neither library exposes raw encap / decap separable from setup, so those rows are explicitly not apples-to-apples with hpke-ng's bare-operation rows.

Security posture

The library responds to two classes of issue observed in prior implementations:

  • Zero shared-secret check (RFC 9180 §7.1.4). Enforced for every DH group — X25519, X448 and the four prime-order curves — with subtle::ConstantTimeEq. It is unreachable on the prime-order curves given a validated public key and a non-zero scalar; it is kept there as defense in depth and for parity.
  • Nonce counter wraparound. Prevented structurally: Context uses a u64 sequence number, refuses to encrypt at u64::MAX, and is non-cloneable so a counter cannot fork.

The post-DH all-zeros check is constant-time. Context cannot be Cloned, so two ciphertexts cannot be produced under the same (key, nonce) from two copies of the same context.

Constant-time considerations

This crate composes RustCrypto primitives. Constant-time properties are inherited from those crates:

Primitive CT property
X25519, X448 CT by construction.
P-256, P-384, P-521, secp256k1 CT in arithmetic mode (pinned).
HKDF-SHA-{256,384,512} CT (deterministic; no secret-dependent branches).
ChaCha20-Poly1305 CT by construction.
AES-128-GCM, AES-256-GCM CT only with hardware AES-NI/PCLMULQDQ. Prefer ChaCha20Poly1305 on platforms without these instructions.
ML-KEM, X-Wing CT per upstream documentation; both crates are pre-1.0.

Zeroization

Everything this crate controls is scrubbed: private keys, shared secrets, PRKs, candidate scalars, seeds, and the derived AEAD key and base nonce are held in Zeroizing/ZeroizeOnDrop wrappers, with explicit manual scrubbing wherever an upstream type lacks zeroize-on-drop (the X448 scalar and shared-secret point, GenericArray temporaries from SecretKey::to_bytes and HkdfExtract::finalize, and the ML-KEM/X-Wing shared-secret arrays).

Known limitation — HKDF/HMAC internal state. The RustCrypto hkdf/hmac crates do not zeroize their internal HMAC state on drop. Every HKDF extract/expand operation therefore leaves PRK-derived ipad/opad block state transiently in freed memory. This is key-equivalent material: an attacker who can read process memory (core dumps, swap, a same-process memory-disclosure bug) could recover it while the allocation remains unreused. The limitation is shared by every RustCrypto-based HPKE implementation and cannot be fixed from this crate. Deployments with a strong memory-forensics threat model should disable core dumps and swap (or use encrypted swap) for processes holding HPKE keys.

Testing

cargo test                                                        # library, roundtrip, negative matrix
cargo test --features pq                                          # + post-quantum, X-Wing KAT, rust-hpke differential
cargo test --features pq,hazmat-kat-internals                     # + RFC 9180 KAT
cargo test --features pq,hazmat-kat-internals --test compile_fail # + compile-time invariant tests
cargo test --features pq,hazmat-differential,hazmat-kat-internals # + differential vs hpke-rs

To regenerate the compile-fail .stderr fixtures after an intentional change (e.g. a toolchain bump), run:

TRYBUILD=overwrite cargo test --features pq,hazmat-kat-internals --test compile_fail

This rewrites the fixtures unconditionally and should not be used as the normal test invocation.

Coverage includes:

  • Roundtrip matrix — 57 macro-generated tests across every ciphersuite × mode combination.
  • Negative matrix — 19 tests asserting that each transcript input actually binds (info, aad, PSK, PSK ID, sender public key), that tampered, truncated and replayed ciphertexts are refused, and that a failed open leaves the sequence counter untouched.
  • Known-answer tests — the RFC 9180 vectors for X25519, X448, P-256, P-521 and secp256k1, plus the official X-Wing draft vectors.
  • Cross-implementation differential — against hpke-rs (X25519, P-256, secp256k1) and against rust-hpke (P-384, P-521, ML-KEM-768, ML-KEM-1024, X-Wing, with X25519/P-256 as controls). Between the two, every supported ciphersuite is checked against either published vectors or an independent implementation.
  • Compile-fail tests — locking in the type-system invariants: Context is non-cloneable, ExportOnly cannot seal, PQ KEMs cannot authenticate, each key-schedule path rejects the wrong mode tag, and external crates cannot implement the sealed supertrait.
  • Unit tests — including direct verification of the RFC 9180 §5.2 nonce derivation formula (nonce = base_nonce XOR I2OSP(seq, Nn)) at sequence-number boundaries.
  • Fuzzing — five cargo-fuzz targets over the parsers, DeriveKeyPair, the key schedule, and open; panics are treated as bugs.

The full suite (without the hpke-rs differential) runs in under two seconds.

Migration from hpke-rs

Three mechanical steps, typically under an hour for a real codebase:

  1. Define a type Suite = Hpke<K, F, A>; alias for the ciphersuite you use.
  2. Replace hpke.seal(...) calls with the explicit mode method: Suite::seal_base, seal_psk, seal_auth, or seal_auth_psk.
  3. Thread &mut rng through call sites — the configuration no longer owns one.

See the announcement post for a worked example.

Authors

hpke-ng is a joint project between Nadim Kobeissi and Daniel Dia.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.