Skip to main content

Module hmac

Module hmac 

Source
Expand description

Stream block HMAC for authenticating streaming responses.

Streaming responses (XPUB/XSUB) use chained MACs instead of per-token Ed25519 signatures for performance:

  • Ed25519: ~10k signatures/sec
  • Blake3/HMAC-SHA256: millions of MACs/sec

§Wire format

Each chunk’s MAC depends on the previous chunk’s MAC, providing cryptographic ordering without explicit sequence numbers:

mac_0 = HMAC(key, topic.as_bytes() || capnp_data_0)[..16]  // Block 0: seed = topic
mac_n = HMAC(key, mac_{n-1} || capnp_data_n)[..16]         // Subsequent blocks

§Security Properties

  • Authenticates server as holder of the DH-derived MAC key
  • Per-stream key derivation binds chains to specific sessions
  • Chained MAC provides cryptographic ordering (no separate sequence field)
  • Reordering is impossible — can’t verify block N without mac_{N-1}
  • 16-byte truncation (128 bits) provides standard authentication strength
  • Constant-time verification via subtle::ConstantTimeEq prevents timing attacks

§Backend

  • Default: Blake3 keyed_hash() (~10+ GB/s with SIMD)
  • FIPS mode: HMAC-SHA256 (FIPS 198-1)

§Cryptographic notes (from external review)

  • 128-bit truncation is well above NIST recommendations and standard for stream auth
  • First-N-bytes truncation is the safe pattern for both Blake3 and HMAC-SHA256
  • Topic-as-seed is sound: the key is secret; topic publicness is fine
  • Per-stream replay protection comes from the per-call ECDH ephemeral keypair, which makes the topic effectively per-stream-random

Structs§

StreamHmacState
Chained HMAC state for stream block authentication, matching wire format.