Skip to main content

Module key_exchange

Module key_exchange 

Source
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

  1. Client generates ephemeral Ristretto keypair
  2. Client includes ephemeral public key in signed RequestEnvelope
  3. Server computes shared secret: DH(server_secret, client_ephemeral_pubkey)
  4. Both derive MAC key: KDF(shared_secret || salt, context="mac")
  5. Server MACs each stream chunk, client verifies

§Feature Flags

  • Default: Blake3 derive_key + Ristretto255 DH
  • fips: HKDF-SHA256 + ECDH P-256 (NIST approved)

Structs§

NotificationKeys
Derived keys for notification broadcast encryption.
RistrettoKeyExchange
Ristretto255 key exchange implementation.
RistrettoPublic
Ristretto255 public key (compressed point).
RistrettoSecret
Ristretto255 secret key (scalar).
SharedSecret
Shared secret from DH key exchange.
StreamKeys
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§

DefaultKeyExchange
Default key exchange algorithm based on feature flags.