Wire v2 privacy profile and PAKE

Wire 0x02 anti-downgrade floor, pseudonymous paired reconnect, opt-in Argon2id PAKE pairing, blinded /v2/relay epoch mailboxes, bucketed inner padding, and jittered scheduling.

The Tendril v2 Privacy Profile (WIRE_VERSION_V2 = 0x02, specified in spec/wire-v2.md and spec/relay-v2.md) hardens handshake metadata, relay mailbox identifiers, inner frame lengths, and keepalive/rekey timing while preserving Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256 and hybrid Ed25519 + ML-DSA-65 identity signatures. Wire v1 (0x01) remains intact for backward compatibility with unupgraded peers.

Preamble binding and anti-downgrade floor

Every v2 connection opens with a 6-byte cleartext preamble ("TND" || 0x02 || intent || flags) where intent is 0x01 (session) or 0x02 (pair) and flags is 0x00 (standard v2) or 0x01 (FLAG_PAKE_PAIR, permitted only when intent == 0x02).

  • Prologue binding: Standard v2 connections feed the 6-byte preamble verbatim as the Noise prologue. PAKE pairing feeds preamble (6 B) || pake_context_tag (32 B) so mutating any preamble byte or mode flag causes AEAD failure in msg2 and msg3.
  • Anti-downgrade (min_wire_version): Persisted peer and pinned host records carry min_wire_version (1 or 2). Once a peer is recorded over 0x02 (or pinned with min_wire_version = 2), both sides persist min_wire_version >= 2, reject decreasing the floor without explicit revocation and re-pairing, and fail closed (VersionDowngrade) before disclosing HostHello, SessionHello, PairClaim, or burning pairing codes if 0x01 is offered. Because PinnedHost has no floor field and PairingInitiator::new / new_m2m default to floor 1, initiator embedders MUST pass the persisted peer floor (via Roster::pairing_floor or V2PinnedHost) into PairingInitiator::new_with_min_wire_version / PairingInitiator::new_m2m_with_min_wire_version, or attach PairingInitiator::with_roster_floors(&Roster) so unpinned v1 TOFU aborts at AwaitMsg2 with CoreError::VersionDowngrade (0 msg3 bytes written) whenever the responder already has min_wire_version >= 2 in the roster.
  • Protocol-isolated inbound routing: InboundRouter separates 0x01 and 0x02 inbound handshakes into isolated queues and rate limiters, while set_pair_enabled(false) disables and clears both v1 and v2 pair queues.

Pseudonymous paired reconnect

In v1, Noise_XXhfs msg2 is encrypted only under ephemeral ee + ekem1, allowing active scanners to read HostHello (host_id, signing_pub, rotation) and the responder's static X25519 key. In v2 session reconnect (intent = 0x01, flags = 0x00), both peers export reconnect_secret and mailbox_secret via HKDF-SHA256 from the post-se chaining key and handshake hash after a completed v2 handshake.

sequenceDiagram
  participant I as Initiator
  participant R as Responder
  I->>R: Preamble (0x02, 0x01, 0x00) + msg1 (e, e1, nonce || ts || rendezvous_mac [56 B])
  Note over R: Check |ts - now| <= 300s, shared RendezvousReplayCache, constant-time MAC scan
  alt Verified and fresh
    R->>I: msg2 (real static_pub + ChaCha20Poly1305-sealed HostHello padded to V2_HANDSHAKE_BUCKETS)
    I->>R: msg3 (padded SessionHello)
  else Unauthenticated probe, stale (> 300s), or replayed
    R->>I: msg2 (ephemeral decoy_static + CSPRNG decoy payload in identical V2_HANDSHAKE_BUCKETS size)
    Note over I,R: Responder rejects msg3 unconditionally (HostKeyUnverified)
  end
  • Timestamped proof (56 B): msg1 carries rendezvous_nonce (16 B) || ts_be8 (8 B) || rendezvous_mac (32 B) authenticated with reconnect_secret over the preamble, e_i_pub, and SHA-256(e1).
  • Shared replay cache and constant-time scan: Multi-connection listeners share one RendezvousReplayCache across concurrent inbound connections, enforcing |ts_unix - now_unix| <= 300 seconds, evicting only expired entries at capacity, and failing closed to the decoy path when full. The responder evaluates rendezvous_mac across all roster entries without early exit regardless of payload length.
  • Rotation-matched decoy msg2: Both genuine sealed HostHello envelopes and unauthenticated CSPRNG decoy payloads pad to the same V2_HANDSHAKE_BUCKETS ([4096, 16384, 32768, 63488]) size computed for the responder's real HostHello (including any RotationRecord chain), hiding static_pub, host_id, signing_pub, and rotation state from active scanners.
  • Post-establish floor and secret retention: Pairing-derived reconnect_secret and mailbox_secret are retained across reconnects to prevent msg3-drop or concurrent-session secret desynchronization (session-exported secrets are informational/explicit-only). Reaching Established (msg3 verified against an Active peer) raises min_wire_version = 2, never speculatively at msg2.

Opt-in PAKE pairing (FLAG_PAKE_PAIR = 0x01)

For human-mediated pairing over untrusted paths, intent = 0x02, flags = 0x01 derives master_pake from the normalized pairing code and a 16-byte CSPRNG channel_salt via Argon2id (m = 19456 KiB, t = 2, p = 1, enforced minimum in production builds), then expands pake_prologue_key, pake_init_key, pake_hello_key, pake_confirm_key, and pake_context_tag via HKDF-SHA256.

  • Replay-protected msg1 and Argon2id pass floor: msg1 carries channel_salt (16 B) || init_mac (32 B). The responder checks a bounded (channel_salt, init_mac) replay cache before accepting and enforces a minimum floor of V2_PAKE_FIXED_ARGON2_PASSES = 4 Argon2id passes on every msg1 (passes_run < 4 is padded with dummy Argon2id passes, hiding live code counts 0..=3 only; when more than 4 live codes are active, one pass runs per live code). Unmatched, replayed, or full-cache msg1 attempts route to an ephemeral decoy_static + decoy prologue msg2 of identical V2_HANDSHAKE_BUCKETS length (including the 32-byte resp_confirm_mac overhead) without charging or burning live pairing codes.
  • Authenticated HostHello and msg3: On a valid match, msg2 seals HostHello with pake_hello_key (AAD = h_pre) and appends resp_confirm_mac. Invalid msg3 (init_confirm_mac mismatch) fails with PairingAuthFailed without burning live codes, preventing code-burn DoS.
  • Passive dictionary work factor: A passive observer capturing a legitimate msg1 + msg2 exchange can test code guesses offline at one Argon2id(19 MiB, t=2, p=1) evaluation per guess. Remote3Group (31^12 ~= 2^59.4) resists offline brute force; shorter Lan2Group (31^8 ~= 2^39.6) codes MUST remain restricted to trusted local networks. Runtime embedders MUST bound concurrent Argon2id derivations.

Blinded hourly /v2/relay mailboxes

spec/relay-v2.md replaces /v1/relay's static device_id with hourly (3600 s) HKDF-derived Ed25519 mailbox_id keys derived from mailbox_secret and uint64_be(epoch):

Artifact Derivation (HKDF-SHA256) Purpose
mailbox_id Ed25519 keypair from info = "tendril-relay-v2-ed25519" Ephemeral per-epoch listener registration and accept signature
dial_auth_key Key from info = "tendril-relay-v2-dial-auth" Computes conn_id-bound dial_token HMAC for dial and incoming verification
  • Host-bound challenges (VerifiedRelayHost): Clients canonicalize challenge.host (lowercase, no trailing dot or :port) and verify it matches the dialed relay host before signing register, dial, or accept proofs.
  • Atomic incoming verification: Listeners verify dial_token across the active RelayEpochWindow (+-1 hour skew) before recording (epoch, dial_nonce, conn_id) in RelayDialReplayCache, ignoring invalid or replayed notifications silently.
  • Per-epoch socket isolation: Clients requiring cross-epoch unlinkability MUST open a separate control WebSocket per epoch mailbox_id rather than registering (epoch - 1, epoch, epoch + 1) on one persistent control socket.

Bucketed inner frames and jittered scheduling

Mechanism Specification (spec/wire-v2.md) Privacy effect
0x09 PADDED Wraps 0x01..=0x07 inner frames (inner_type || uint16_be(len) || payload || 0x00...) padded to [256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65503] Hides inner frame type boundaries and exact payload sizes; constant-time zero-padding check
0x08 PADDING Zero-filled cover frame silently discarded after AEAD decrypt and nonce advance Supports cover traffic on v2 sessions (rejected on v1)
Keepalive & REKEY jitter ScheduleJitterPolicy samples PING intervals (+-25% default) and per-epoch REKEY thresholds (75%..=100% of max frames/age) via CSPRNG Removes periodic beacon and fixed rekey timing fingerprints

Connections

Local graph

Linked from