fix(media): stop permanent voice loss after bad-network blip (protocol v2)
A bad UDP packet on a flaky link could permanently wedge the voice path, unrecoverable even across app restarts. Three defects: 1. Anti-replay window was advanced from the UNAUTHENTICATED header seq before the AEAD tag was checked, and not rolled back on failure. One corrupted/forged frame shoved recv_highest_ far ahead, after which every legitimate frame was rejected as "too old" forever. Reorder to replay-check -> authenticate -> update (RFC 3711 3.3); the window now moves only after a successful tag check. 2. The wire seq was only the low 16 bits of the nonce counter (zero-extended on receive). After 65,536 frames the nonce desynced and all frames failed auth. Widen the voice frame seq u16 -> u64 (header 14 -> 20 bytes). The core owns all UDP framing, so Swift/C# clients need only a rebuild. This is a versioned wire change: VOICECAT_PROTOCOL_VERSION 1 -> 2, handshake rejects on mismatch. 3. Server leaked per-session UDP state on disconnect; unregister_session now frees udp_endpoints_/udp_tokens_/ssrc_to_session_. Also add rate-limited dropped-frame logging to MediaRelay so a wedged media path is observable. New regression tests in test_media_aead.cpp cover the poison (fails on old code) and the 16-bit wrap. ctest --preset dev -E external_pcm: 22/22 pass (external_pcm aborts on a pre-existing CoreAudio shutdown race, unrelated).
This commit is contained in:
@@ -153,6 +153,9 @@ Notes:
|
||||
- **Version negotiation.** Each side sends `proto_version` (integer) and a `features`
|
||||
string list. The effective version is `min(client, server)`; the effective feature set
|
||||
is the intersection. A client that doesn't understand a feature simply never uses it.
|
||||
The **current `proto_version` is 2**. v2 widened the UDP voice frame `seq` field from
|
||||
u16 to u64 (voice.md §2) — a wire-format change with no backward compatibility on the
|
||||
media path, so the server rejects any peer not on v2 rather than min-negotiating down.
|
||||
- **Auth over TLS.** Passwords cross the wire only inside TLS 1.3 and are verified against
|
||||
an Argon2id hash at rest (see security.md). `auth_methods` in `ServerHello` advertises
|
||||
whether `guest` is enabled.
|
||||
|
||||
@@ -89,8 +89,13 @@ the design depends on that.
|
||||
- **Nonce discipline:** `nonce = direction_bit ‖ ssrc ‖ monotonic_packet_counter`. The
|
||||
counter never repeats under one key; the session **rekeys** (re-derives via the exporter
|
||||
with a bumped epoch) well before counter exhaustion or on a time/byte budget.
|
||||
- **Anti-replay:** a sliding-window replay filter per ssrc (à la IPsec) keyed on the packet
|
||||
counter. Replays and out-of-window packets are dropped before decode.
|
||||
- **Anti-replay:** a 64-bit sliding-window replay filter keyed on the packet counter (à la
|
||||
IPsec). The window is **advanced only after the AEAD tag verifies** (RFC 3711 §3.3 order:
|
||||
replay-check → authenticate → update). The counter is read from the unauthenticated
|
||||
header, so advancing the high-water mark *before* authentication would let a single
|
||||
corrupted or forged packet jump it far ahead, after which every legitimate packet is
|
||||
rejected as "too old" — a permanent denial of the whole stream. Failed-auth packets leave
|
||||
the window untouched. Replays and out-of-window packets are dropped before decode.
|
||||
|
||||
## 3. UDP session binding
|
||||
|
||||
|
||||
@@ -35,13 +35,16 @@ macOS, **and iOS** (via a ReplayKit broadcast extension).
|
||||
|
||||
A fixed binary header — no protobuf on the RT path. Multi-byte fields are big-endian.
|
||||
|
||||
The header is **20 bytes** (protocol v2; v1 was 14 bytes with a u16 seq — see note below).
|
||||
|
||||
```
|
||||
0 1 2 3 4 5 6 7 8 ...
|
||||
0 1 2 3 4 5 6 7 8 ............ 15
|
||||
┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬───────────────┐
|
||||
│ type │flags │ codec │ ssrc (u32) │
|
||||
├──────┴──────┴──────┴──────┼──────┬──────┬──────┬──────┬──────────────┤
|
||||
│ seq (u16) │ timestamp (u32, in samples @48k) │ payload ... │
|
||||
└─────────────┴──────────────────────────────────────────┴──────────────┘
|
||||
│ type │flags │ codec │ ssrc (u32) │ seq (u64) ──▶ │
|
||||
├──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴───────────────┤
|
||||
│ ◀── seq (u64) ──┤ timestamp (u32 @48k) │ payload ... │
|
||||
└──────────────────┴────────────────────────────────────┴───────────────┘
|
||||
bytes [8..15] = seq (u64) [16..19] = timestamp (u32)
|
||||
|
||||
type u8 1 = VOICE, 2 = KEEPALIVE, 3 = UDP_BINDING (handshake)
|
||||
flags u8 bit0 marker (start of talkspurt) · bit1 FEC-present
|
||||
@@ -49,11 +52,19 @@ flags u8 bit0 marker (start of talkspurt) · bit1 FEC-present
|
||||
codec u16 0 = OPUS (room for future codecs)
|
||||
ssrc u32 media-plane stream id. Client sends its own ssrc; the server
|
||||
validates it against the bound session and relays unchanged.
|
||||
seq u16 per-ssrc sequence number, wraps; drives loss detection + reorder
|
||||
seq u64 full monotonic send counter. This IS the AEAD nonce counter, so the
|
||||
receiver derives the nonce directly from it — no rollover guessing.
|
||||
timestamp u32 RTP-style sample clock @48 kHz; drives the jitter buffer
|
||||
payload one Opus packet (the encoder's output for one frame)
|
||||
```
|
||||
|
||||
> **Why u64 (protocol v2).** v1 carried only the low 16 bits of the counter and the
|
||||
> receiver zero-extended them to rebuild the AEAD nonce. After 65,536 frames the seq
|
||||
> wrapped, the reconstructed nonce diverged from the sealing nonce, and **every frame
|
||||
> failed authentication permanently** (no rollover counter). v2 puts the full 64-bit
|
||||
> counter on the wire so the nonce is always exact. A v2 server and a v1 client cannot
|
||||
> interoperate; the `Hello` handshake rejects on `proto_version` mismatch.
|
||||
|
||||
This is intentionally RTP-shaped (familiar semantics: ssrc/seq/timestamp) without RTP's
|
||||
full machinery. The **server relays the payload unmodified** — it only reads the header to
|
||||
route by ssrc→channel and may restamp nothing (the client's ssrc is globally unique once
|
||||
|
||||
Reference in New Issue
Block a user