Module hmac
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::ConstantTimeEqprevents 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§
- Stream
Hmac State - Chained HMAC state for stream block authentication, matching wire format.