Expand description
Diffie-Hellman key exchange for stream MAC key derivation.
Streaming responses use MAC authentication instead of per-token Ed25519 signatures for performance. The MAC key is derived from a DH shared secret.
§Ristretto255
This module uses Ristretto255, a prime-order group built on Curve25519. Unlike X25519, Ristretto255 has no cofactor issues:
- No small subgroups or low-order points
- Invalid encodings are rejected at decode time
- If a point decodes successfully, it’s safe to use
See: https://ristretto.group/why_ristretto.html
§Flow
- Client generates ephemeral Ristretto keypair
- Client includes ephemeral public key in signed RequestEnvelope
- Server computes shared secret:
DH(server_secret, client_ephemeral_pubkey) - Both derive MAC key:
KDF(shared_secret || salt, context="mac") - Server MACs each stream chunk, client verifies
§Feature Flags
- Default: Blake3 derive_key + Ristretto255 DH
fips: HKDF-SHA256 + ECDH P-256 (NIST approved)
Structs§
- Notification
Keys - Derived keys for notification broadcast encryption.
- Ristretto
KeyExchange - Ristretto255 key exchange implementation.
- Ristretto
Public - Ristretto255 public key (compressed point).
- Ristretto
Secret - Ristretto255 secret key (scalar).
- Shared
Secret - Shared secret from DH key exchange.
- Stream
Keys - Derived keys for E2E authenticated streaming.
Traits§
- KeyExchange
- Trait for Diffie-Hellman key exchange implementations.
Functions§
- blinded_
dh - Perform blinding-aware DH:
shared = (secret + blinding_scalar) * their_pubkey. - blinded_
dh_ raw - Blinding-aware DH from raw bytes:
(secret + blinding_scalar) * their_pubkey. - client_
hybrid_ stream_ keys - Client side of the hybrid stream handshake (S3 #554).
- client_
identified_ stream_ epoch - Client side of the transcript-bound identified stream epoch bootstrap.
- derive_
notification_ keys - Derive notification keys (enc_key and mac_key) from DH shared secret.
- derive_
stream_ keys - Derive stream keys (topic and mac_key) from DH shared secret.
- generate_
ephemeral_ keypair - Generate an ephemeral Ristretto255 keypair (for one-time use in requests).
- ratchet_
stream_ key - One-way epoch ratchet for long-lived streams (S3 #554 / #223).
- reconstruct_
blinded_ pub_ raw - Reconstruct a blinded pubkey from raw bytes:
P_sub + r * G. - rerandomize_
pubkey - Rerandomize a Ristretto255 public key:
blinded = pubkey + r * G. - ristretto_
dh - Perform Ristretto255 Diffie-Hellman and return shared secret bytes.
- ristretto_
dh_ raw - Ristretto255 DH from raw scalar and pubkey bytes.
- server_
hybrid_ stream_ keys - Server side of the hybrid stream handshake (S3 #554).
- server_
identified_ stream_ epoch - Server side of the transcript-bound identified stream epoch bootstrap.
Type Aliases§
- Default
KeyExchange - Default key exchange algorithm based on feature flags.