From b5235d9c7814f44d9558f320fec2a8198cfd5dca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 22:38:45 -0800 Subject: [PATCH 01/10] chore(quest): claim quest/m1/cluster-routing/routes/proof.md Quest-Claim: 594ba9a8f2b5e7d8 From 00070749f395ba4dde21ca59d1b28f49a291dd4a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 22:58:36 -0800 Subject: [PATCH 02/10] feat(net): origins prove a route key in lite-07 SETUP A lite-07 endpoint proves its origin's Ed25519 route key with the new Route Key Setup Parameter: a signature over keying material both ends export from the session and the prover's side, so the proof neither replays on another session nor reflects to its sender. QUIC and WebTransport sessions export it; other transports prove nothing. moq-relay loads the key from --cluster-route-key, so relays sharing the file fail over as one origin to a scoped peer. Browsers whose WebTransport exposes exportKeyingMaterial prove one key per page. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 3 + doc/bin/relay/config.md | 1 + drafts/draft-lcurley-moq-lite.md | 28 +++ js/net/src/lite/connection.ts | 14 +- js/net/src/lite/route_key.test.ts | 65 +++++++ js/net/src/lite/route_key.ts | 48 +++++ js/net/src/lite/setup.test.ts | 16 ++ js/net/src/lite/setup.ts | 30 ++- js/net/src/lite/version.ts | 16 ++ quest/m1/cluster-routing/README.md | 5 +- quest/m1/cluster-routing/routes/README.md | 9 +- quest/m1/cluster-routing/routes/proof.md | 74 -------- quest/m1/cluster-routing/routes/session.md | 6 +- quest/m1/lite07-finalize.md | 7 +- rs/moq-crypto/src/sign/secret.rs | 9 + rs/moq-net/Cargo.toml | 3 + rs/moq-net/MIGRATE.md | 5 + rs/moq-net/src/client.rs | 2 + rs/moq-net/src/lite/publisher.rs | 14 +- rs/moq-net/src/lite/session.rs | 19 +- rs/moq-net/src/lite/setup.rs | 107 ++++++++++- rs/moq-net/src/lite/subscriber.rs | 2 +- rs/moq-net/src/lite/version.rs | 8 + rs/moq-net/src/model/mod.rs | 1 + rs/moq-net/src/model/origin.rs | 28 ++- rs/moq-net/src/route/mod.rs | 3 + rs/moq-net/src/route/proof.rs | 177 ++++++++++++++++++ rs/moq-net/src/route/tests/routing.rs | 9 +- rs/moq-net/src/server.rs | 3 + rs/moq-net/src/transport.rs | 15 ++ rs/moq-net/src/transport/boxed.rs | 9 + rs/moq-net/src/transport/memory.rs | 17 ++ .../integration/routing_contracts/mod.rs | 36 +++- .../integration/routing_contracts/model.rs | 37 ++-- rs/moq-quic/src/connection/mod.rs | 16 +- rs/moq-quic/src/crypto.rs | 4 +- rs/moq-quic/src/tests/mod.rs | 17 +- rs/moq-relay/Cargo.toml | 1 + rs/moq-relay/src/cluster.rs | 20 ++ rs/moq-relay/src/settings.rs | 3 + rs/moq-tokio/src/quic/driver/connection.rs | 7 + rs/moq-tokio/src/quic/web/session.rs | 47 +++++ rs/moq-uring/src/quic/driver/connection.rs | 6 + rs/moq-uring/src/quic/web.rs | 25 +++ rs/moq-uring/src/transport/local.rs | 4 + 45 files changed, 809 insertions(+), 167 deletions(-) create mode 100644 js/net/src/lite/route_key.test.ts create mode 100644 js/net/src/lite/route_key.ts delete mode 100644 quest/m1/cluster-routing/routes/proof.md create mode 100644 rs/moq-net/src/route/proof.rs diff --git a/Cargo.lock b/Cargo.lock index 82d01682648..80a365de3dd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4784,6 +4784,7 @@ dependencies = [ "proptest", "rand 0.10.3", "rangemap", + "rind", "serde", "serde_json", "slab", @@ -4792,6 +4793,7 @@ dependencies = [ "tracing", "url", "workspace-hack", + "zeroize", ] [[package]] @@ -4909,6 +4911,7 @@ dependencies = [ "libc", "moq-auth 0.2.1", "moq-congestion", + "moq-crypto", "moq-net", "moq-quic", "moq-shaper", diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index f34ef8537f1..2e023b174f7 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -306,6 +306,7 @@ connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost pric node = "https://us-west.example.com/" # This relay's own URL. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. id = 12345 # Stable Hop ID across restarts. +route_key = "route.key" # Route key; relays sharing the file fail over as one to scoped peers. max_hops = 32 # Longest accepted/forwarded hop path (1 to 32). [cluster.api] diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 029f98648a6..9f412e07987 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -19,6 +19,7 @@ author: normative: moqt: I-D.ietf-moq-transport qmux: I-D.ietf-quic-qmux + webtrans-h3: I-D.ietf-webtrans-http3 qmuxws: title: "QMux over WebSocket" target: https://datatracker.ietf.org/doc/draft-lcurley-qmux-websocket/ @@ -29,6 +30,8 @@ normative: date: false RFC3986: RFC6455: + RFC8032: + RFC8446: RFC8831: RFC9000: RFC9002: @@ -919,6 +922,8 @@ The following Setup Parameters are defined: |------|----------------|-------------| | 0x7 | Token | Token (b) | |------|----------------|-------------| +| 0x8 | Route Key | Proof (..) | +|------|----------------|-------------| ### Probe Parameter {#probe-parameter} The Probe Parameter advertises the sender's capability level when acting as a publisher on a [Probe Stream](#probe). @@ -994,6 +999,28 @@ The URI is fixed before the version is negotiated, so a client that may negotiat Only the client sends it; a client that receives one MUST close the session with a PROTOCOL_VIOLATION. A relay MUST NOT forward it. +### Route Key Parameter {#route-key-parameter} +The Route Key Parameter proves that the sender holds an Ed25519 [RFC8032] key, bound to this session, so a receiver recognizes the sender, and endpoints sharing its key, across sessions. + +~~~ +Route Key Proof { + Public Key (256), + Signature (512), +} +~~~ + +**Public Key**: +The sender's Ed25519 public key. + +**Signature**: +The key's Ed25519 signature over the ASCII bytes `moq-lite route key`, then one byte naming the sender's side of the session (0 for the client, 1 for the server), then 32 bytes of keying material exported from the session with the label `EXPORTER-moq-lite-route-key` and an empty context. + +Binding 1 exports with the TLS exporter (Section 7.5 of [RFC8446]), and binding 2 with the WebTransport session's exporter [webtrans-h3] (see [Transports](#transports)). +The other bindings have no exporter, and an endpoint MUST NOT send the parameter on them. +The exported material and the sender's side keep a proof from being replayed on another session or reflected back to its sender. + +Either endpoint MAY send it. A receiver MUST close the session with a PROTOCOL_VIOLATION if the value is not 96 bytes, or if it can export keying material and the signature does not verify. A relay MUST NOT forward it. + ## ANNOUNCE_REQUEST {#announce-request} A subscriber sends an ANNOUNCE_REQUEST message to indicate it wants to receive announcements for any broadcasts with a path that starts with the requested prefix. @@ -1933,6 +1960,7 @@ The `Message Length` describes the payload size on the wire. - Added the reliable ordered RTCDataChannel binding, with one Qmux Record per binary message and no datagrams. - Added the SETUP `Implementation` parameter (0x6): the sender's software as `name/version` product tokens. - Added the client-only Token Setup Parameter (0x7), carrying the connection credential in SETUP instead of only the request URI. +- Added the Route Key Setup Parameter (0x8): an Ed25519 public key and its signature over keying material exported from the session. - Added Padding Stream (0x2), read and discarded incrementally by either endpoint. - A Report-level publisher reads and ignores PROBE targets instead of resetting the Probe Stream. - A GOAWAY recipient MAY keep opening requests on the current session until it has moved to a replacement session; previously it MUST NOT open new streams. The sender SHOULD keep answering them and MAY reset one with GOING_AWAY, which the recipient SHOULD retry on another route. diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index a1ca4405692..71817a3501e 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -23,6 +23,7 @@ import { Fetch } from "./fetch.ts"; import { Goaway } from "./goaway.ts"; import { Group } from "./group.ts"; import { Publisher } from "./publisher.ts"; +import { proveRouteKey } from "./route_key.ts"; import { SessionInfo } from "./session.ts"; import { hasClientParameters, ProbeLevel, type Role, Setup } from "./setup.ts"; import { DataType, StreamId } from "./stream.ts"; @@ -36,6 +37,7 @@ import { hasGoaway, hasPadding, hasProbeRtt, + hasRouteKey, hasSetupStream, hasTrackStream, hasTracks, @@ -376,10 +378,14 @@ export class Connection implements Established { try { await writer.u53(DataType.Setup); const probe = await probeLevel(this.#quic, this.#version); - await new Setup({ probe, hop: this.hop, token: this.#token, implementation: this.#implementation }).encode( - writer, - this.#version, - ); + const routeKey = hasRouteKey(this.#version) ? await proveRouteKey(this.#quic, this.#client) : undefined; + await new Setup({ + probe, + hop: this.hop, + token: this.#token, + implementation: this.#implementation, + routeKey, + }).encode(writer, this.#version); writer.close(); } catch (err: unknown) { writer.reset(err); diff --git a/js/net/src/lite/route_key.test.ts b/js/net/src/lite/route_key.test.ts new file mode 100644 index 00000000000..f817b8d478c --- /dev/null +++ b/js/net/src/lite/route_key.test.ts @@ -0,0 +1,65 @@ +import { expect, test } from "bun:test"; +import { proveRouteKey, sign } from "./route_key.ts"; + +// PKCS#8 v1 (RFC 8410) prefix of an Ed25519 key, up to its 32-byte seed. +const PKCS8_SEED_PREFIX = [0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]; + +// Shared with rs/moq-net/src/route/proof.rs, so both sides sign the same transcript. +const SEED = new Uint8Array(32).fill(1); +const SECRET = new Uint8Array(32).fill(2); +const CLIENT_PROOF = + "8a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c" + + "e7ea4e34a65b8501185b805d09b58a61b5b8495654fcaac0949d4f98aa35002e" + + "6fca096329973e91e1105030dd88fa0eb543c68c00e18394f8300cb0574cf901"; + +async function keyFromSeed(seed: Uint8Array): Promise { + const der = new Uint8Array([...PKCS8_SEED_PREFIX, ...seed]); + const privateKey = await crypto.subtle.importKey("pkcs8", der, { name: "Ed25519" }, true, ["sign"]); + // WebCrypto derives the public key only through a JWK export. + const jwk = await crypto.subtle.exportKey("jwk", privateKey); + const publicKey = await crypto.subtle.importKey( + "jwk", + { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, + { name: "Ed25519" }, + true, + ["verify"], + ); + return { privateKey, publicKey }; +} + +function hex(bytes: Uint8Array): string { + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); +} + +test("a proof matches the Rust transcript", async () => { + const proof = await sign(await keyFromSeed(SEED), SECRET, true); + expect(hex(proof)).toBe(CLIENT_PROOF); +}); + +test("the prover's side changes the signature", async () => { + const key = await keyFromSeed(SEED); + const client = await sign(key, SECRET, true); + const server = await sign(key, SECRET, false); + expect(client.subarray(0, 32)).toEqual(server.subarray(0, 32)); + expect(client.subarray(32)).not.toEqual(server.subarray(32)); +}); + +test("a transport without an exporter proves nothing", async () => { + expect(await proveRouteKey({} as WebTransport, true)).toBeUndefined(); +}); + +test("a transport with an exporter proves one key per page", async () => { + const labels: string[] = []; + const transport = { + exportKeyingMaterial: async (label: BufferSource, context: BufferSource, length: number) => { + labels.push(new TextDecoder().decode(label)); + expect((context as Uint8Array).byteLength).toBe(0); + return new Uint8Array(length).fill(3); + }, + } as unknown as WebTransport; + const first = await proveRouteKey(transport, true); + const second = await proveRouteKey(transport, false); + expect(first?.byteLength).toBe(96); + expect(first?.subarray(0, 32)).toEqual(second?.subarray(0, 32)); + expect(labels).toEqual(["EXPORTER-moq-lite-route-key", "EXPORTER-moq-lite-route-key"]); +}); diff --git a/js/net/src/lite/route_key.ts b/js/net/src/lite/route_key.ts new file mode 100644 index 00000000000..a9570001d1a --- /dev/null +++ b/js/net/src/lite/route_key.ts @@ -0,0 +1,48 @@ +/** + * Route key proofs: an endpoint shows its peer that it holds an Ed25519 key, bound to the + * session by keying material both ends export from its handshake. + * + * A tab proves one key per page load, so a peer recognizes it across its sessions. Only a + * transport that exposes `exportKeyingMaterial` can bind a proof; elsewhere the tab sends + * none and stays unproven. + * + * @module + */ + +const EXPORTER_LABEL = new TextEncoder().encode("EXPORTER-moq-lite-route-key"); +const DOMAIN = new TextEncoder().encode("moq-lite route key"); +const SECRET_SIZE = 32; + +/** The keying material export a WebTransport may offer; only some browsers ship it. */ +type Exporter = (label: BufferSource, context: BufferSource, outputLength: number) => Promise; + +let pageKey: Promise | undefined; + +/** + * The proof to send in SETUP for `transport`, or `undefined` when it cannot export keying + * material. `client` is whether this endpoint dialed the session. + */ +export async function proveRouteKey(transport: WebTransport, client: boolean): Promise { + const exporter = (transport as { exportKeyingMaterial?: Exporter }).exportKeyingMaterial; + if (typeof exporter !== "function") return undefined; + const secret = new Uint8Array(await exporter.call(transport, EXPORTER_LABEL, new Uint8Array(), SECRET_SIZE)); + pageKey ??= crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]) as Promise; + return sign(await pageKey, secret, client); +} + +/** Sign the proof for `secret`, the session's exported keying material. Exported for tests. */ +export async function sign(key: CryptoKeyPair, secret: Uint8Array, client: boolean): Promise { + if (secret.byteLength !== SECRET_SIZE) throw new Error("route key secret must be 32 bytes"); + // The domain, then the prover's side of the session (0 dialed, 1 accepted), then the secret. + const message = new Uint8Array(DOMAIN.byteLength + 1 + SECRET_SIZE); + message.set(DOMAIN); + message[DOMAIN.byteLength] = client ? 0 : 1; + message.set(secret, DOMAIN.byteLength + 1); + + const publicKey = new Uint8Array(await crypto.subtle.exportKey("raw", key.publicKey)); + const signature = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key.privateKey, message)); + const proof = new Uint8Array(publicKey.byteLength + signature.byteLength); + proof.set(publicKey); + proof.set(signature, publicKey.byteLength); + return proof; +} diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 4cd56920cc2..361925a0021 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -231,6 +231,22 @@ test("SETUP refuses an empty token", async () => { await expect(Setup.decode(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); }); +test("SETUP route key round-trips on lite-07 only, at exactly 96 bytes", async () => { + const proof = new Uint8Array(96).fill(7); + const msg = new Setup({ routeKey: proof }); + const wire = await bytes((w) => msg.encode(w, Version.DRAFT_07), Version.DRAFT_07); + const got = await Setup.decode(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); + expect(got.routeKey).toEqual(proof); + + await expect(bytes((w) => msg.encode(w, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); + // An older version ignores the parameter like any unknown one. + expect((await decodeParam(0x8n, proof, Version.DRAFT_06)).routeKey).toBeUndefined(); + + const short = new Setup({ routeKey: new Uint8Array(95) }); + await expect(bytes((w) => short.encode(w, Version.DRAFT_07), Version.DRAFT_07)).rejects.toThrow(); + await expect(decodeParam(0x8n, new Uint8Array(95), Version.DRAFT_07)).rejects.toThrow(); +}); + test("older SETUP versions ignore the unknown Implementation parameter before parsing it", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { for (const value of [new TextEncoder().encode("x/1"), new Uint8Array([0xff])]) { diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index 30694c8ddf5..f5c30b80c2c 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -9,7 +9,7 @@ import { type Hop, HopSchema, wireHop } from "../hop.ts"; import { encodeVarint, Reader, type Writer } from "../stream.ts"; import { decodeUtf8 } from "../util/utf8.ts"; import * as Message from "./message.ts"; -import { hasAuth, hasImplementation, hasSetupStream, type Version } from "./version.ts"; +import { hasAuth, hasImplementation, hasRouteKey, hasSetupStream, type Version } from "./version.ts"; const clientParameters = new WeakSet(); @@ -30,6 +30,10 @@ const PARAM_HOP = 0x5n; const PARAM_IMPLEMENTATION = 0x6n; /** Setup Parameter id for the client's connection credential (client-only, lite-07+). */ const PARAM_TOKEN = 0x7n; +/** Setup Parameter id for the sender's route key proof (lite-07+). */ +const PARAM_ROUTE_KEY = 0x8n; +/** A route key proof's size: an Ed25519 public key, then its signature. */ +const ROUTE_KEY_PROOF_SIZE = 96; /** SETUP only carries negotiation parameters, so it gets a far smaller cap than other messages. */ const MAX_SETUP_SIZE = 0xffff; @@ -179,6 +183,8 @@ export interface SetupProps { token?: Uint8Array; /** See {@link Setup.implementation}. Omitted by default. */ implementation?: string; + /** See {@link Setup.routeKey}. Omitted by default. */ + routeKey?: Uint8Array; } /** @@ -228,13 +234,20 @@ export class Setup { */ implementation?: string; - constructor({ probe, path, role, hop, token, implementation }: SetupProps = {}) { + /** + * Proof that the sender holds its route key, bound to this session (lite-07+): the + * Ed25519 public key, then its signature over keying material exported from the session. + */ + routeKey?: Uint8Array; + + constructor({ probe, path, role, hop, token, implementation, routeKey }: SetupProps = {}) { this.probe = probe ?? ProbeLevel.None; this.path = path; this.role = role ?? Role.Both; this.hop = hop; this.token = token; this.implementation = implementation; + this.routeKey = routeKey; } static #guard(version: Version) { @@ -267,6 +280,11 @@ export class Setup { if (this.token.byteLength === 0) throw new Error("setup token cannot be empty"); params.setBytes(PARAM_TOKEN, this.token); } + if (this.routeKey !== undefined) { + if (!hasRouteKey(version)) throw new Error("setup route key not supported for this version"); + if (this.routeKey.byteLength !== ROUTE_KEY_PROOF_SIZE) throw new Error("setup route key must be 96 bytes"); + params.setBytes(PARAM_ROUTE_KEY, this.routeKey); + } await params.encode(w); } @@ -295,7 +313,13 @@ export class Setup { const implementationBytes = hasImplementation(version) ? params.getBytes(PARAM_IMPLEMENTATION) : undefined; const implementation = implementationBytes === undefined ? undefined : decodeUtf8(implementationBytes); - const setup = new Setup({ probe, path, role, hop, token, implementation }); + // Kept but not verified: nothing here files routes under the sender's key. + const routeKey = hasRouteKey(version) ? params.getBytes(PARAM_ROUTE_KEY) : undefined; + if (routeKey !== undefined && routeKey.byteLength !== ROUTE_KEY_PROOF_SIZE) { + throw new Error("setup route key must be 96 bytes"); + } + + const setup = new Setup({ probe, path, role, hop, token, implementation, routeKey }); if (pathBytes !== undefined || roleCode !== undefined || token !== undefined) clientParameters.add(setup); return setup; } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 88e849ba25f..e1f37433668 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -654,6 +654,22 @@ export function hasSynced(version: Version): boolean { } } +/** Whether SETUP may carry a route key proof, added in lite-07. */ +export function hasRouteKey(version: Version): boolean { + // Explicitly list older versions so future versions default to carrying it. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } +} + /** Whether SETUP recognizes the Implementation parameter, added in lite-07. */ export function hasImplementation(version: Version): boolean { switch (version) { diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 7561462e69b..21329a1909b 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -43,9 +43,8 @@ Decided with the maintainer, 2026-10-13: key proof is planned; if a use case needs a provable identity, moq-lite-07's route identity becomes a public key, independent of P2P. Decided 2026-11-04 (maintainer, /quest-unblock): scoped forgery is that use case. A peer proves - a route key once per announce stream, its own identity derives from it, and - every identity it sends while scoped is qualified under it - ([Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md)). + a route key in its lite-07 SETUP, bound to the session, and every identity it + sends while scoped, its own included, is qualified under it. Receiver-stamped per-session identities were dropped 2026-10-26 (maintainer): in a mesh, two relays stamping their sessions from one origin forward its routes as diff --git a/quest/m1/cluster-routing/routes/README.md b/quest/m1/cluster-routing/routes/README.md index 7793203f1fe..bef26c154fd 100644 --- a/quest/m1/cluster-routing/routes/README.md +++ b/quest/m1/cluster-routing/routes/README.md @@ -89,9 +89,11 @@ The wire sketch is in [wire](/quest/m1/cluster-routing/routes/wire.md); the bull planned; a provable identity, if a use case needs one, makes this route identity a public key, independent of P2P. Decided 2026-11-04 (maintainer, /quest-unblock): scoped forgery is that use case; a peer proves a route key - once per announce stream, its own identity derives from that key, and every - identity it sends while scoped is qualified under it - ([Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md)). + in its lite-07 SETUP (the Route Key parameter, bound to the session by its + exporter), and every identity it sends while scoped, its own included, is + qualified under it. The own identity stays a fresh random id per process: + peers cannot check one derived from the key and a private salt, so deriving + it adds nothing. Decided 2026-10-26 (maintainer): receivers do not stamp a fresh identity per session. In a mesh, two relays stamping their sessions from one origin forward its routes as two identities a third relay cannot recognize as @@ -500,7 +502,6 @@ benchmarks. - [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - lite-07 and the draft carry ROUTE, ANNOUNCE_FLOOR, ROUTE_REQUEST, and path-less ANNOUNCE - [Route session integration](/quest/m1/cluster-routing/routes/session.md) - one router per origin node drives the origin and every lite-07 announce stream -- [Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md) - a peer proves a route key once per announce stream, and its forwarded identities are qualified by it - [Announcement availability](/quest/m1/cluster-routing/routes/availability.md) - announcements report availability, and a let-go is offline rather than END, in Rust and JS - [js/net route layer](/quest/m1/cluster-routing/routes/js.md) - `js/net` encodes, decodes, and resolves the route layer - [Route layer acceptance](/quest/m1/cluster-routing/routes/acceptance.md) - forwarding fixtures ported and the model deleted, incident fixtures, end-to-end checks, and benchmarks diff --git a/quest/m1/cluster-routing/routes/proof.md b/quest/m1/cluster-routing/routes/proof.md deleted file mode 100644 index 3d39fee6050..00000000000 --- a/quest/m1/cluster-routing/routes/proof.md +++ /dev/null @@ -1,74 +0,0 @@ -# [M] Scoped peers prove a route key - -## Goal - -A lite-07 peer proves a route key once per announce stream. The requester -sends a nonce in ANNOUNCE_REQUEST, and the publisher's ANNOUNCE_OK carries its -public key and a signature over that nonce, bound to the session. A relay -files every identity a scoped, proven peer sends, its own included (the -2026-10-26 rule in [Routes and announces](/quest/m1/cluster-routing/routes/README.md)), -under H(domain, proven key, id), so a scoped peer that forges or inflates -another origin's identity only affects claims inside its own grant. Relays -that share one key file present an origin under the same qualified key -whichever of them carries it, so a reader of relay l1's own broadcast fails -over through sibling l2 when l1's direct uplink is lost. Unscoped peers stay -bare, and a scoped peer that proves nothing gets a per-session key. This lands -in lite-07 before the cut. - -## Plan - -Decided 2026-11-04 (maintainer, /quest-unblock), from the keying question in -[Route session integration](/quest/m1/cluster-routing/routes/session.md). -This reverses the 2026-10-25 and 2026-11-02 decisions that no identity proof -gates the lite-07 cut. Options shown for each: - -- Proof timing: ✅ before the lite-07 cut. Not chosen: an issuer-named route - label in the grant now with the proof after the cut, or a per-session key. -- Where a relay's key comes from: ✅ a key file. An operator gives all its - relays the same file, so two separate relays (the l1/l2 two-uplink fixture, - `scoped_delivery_through_two_uplinks_reaches_one_key`) fail over as one key. - A relay without a file generates one. The own identity stays fresh per - restart as H(key, per-process salt), as `restart_reusing_identity_is_refused` - requires. Not chosen: a fresh key per process. -- Browsers: ✅ prove with WebTransport's `exportKeyingMaterial(label, context, - outputLength)` where the browser exposes it, detected at session setup (no - runtime fallback); otherwise unproven with a per-session key. As of - 2026-11-04 only Firefox ships it (spec-matching from Firefox 160); Chrome has - an Intent to Prototype and Safari nothing. Tabs do not forward routes, so an - unproven tab loses little. Not chosen: browsers never proven, or signing the - nonce with the dialed server name and role. -- Identity on the wire: ✅ ROUTE keeps its u64 node ID, the first 64 bits of - H(key, salt), so the router's `Id` type and ROUTE stay as they are. Not - chosen: the full 32-byte key in each ROUTE. - -Own identity, settled in review of -[moq-dev/moq#7919](https://github.com/moq-dev/moq/pull/7919): it is qualified -like any other, not filed bare. Filed bare, l1's own origin would reach c1 as -its bare id but c2 (through l2) as a qualified key, so the two would not fail -over to each other. Extend the two-uplink fixture so l1 serves its own -broadcast and loses its direct uplink, and the reader fails over through l2. - -Binding: a bare nonce can be relayed (a peer passes another relay's signed OK -off as its own), so the signature covers the session too. Rust uses the TLS -exporter (`rs/moq-quic` already exposes one); browsers use -`exportKeyingMaterial`. Settle the exact signed transcript (nonce, exporter -output, role, a domain label) and record it in the draft. - -Cost, estimated 2026-11-04: about 16 bytes of nonce in ANNOUNCE_REQUEST and -about 90 bytes of key and signature in ANNOUNCE_OK, no extra round trip, and -one Ed25519 sign and verify per announce stream rather than per route update. - -Reuse: `rs/moq-crypto`'s `sign::PublicKey` and `SecretKey::load_or_generate`, -backed by `rind` Ed25519, and `js/crypto`'s WebCrypto Ed25519 signing. -moq-crypto's `sign` feature depends on moq-net, so either moq-net calls `rind` -directly or the key type moves to a lower crate. Decide which in the PR. - -Public API: moq-net gains the proof on announce streams; moq-relay and -moq-tokio gain a route key file option. Wire: ANNOUNCE_REQUEST and ANNOUNCE_OK -change in lite-07 and its draft. - -## Related - -- [Route session integration](/quest/m1/cluster-routing/routes/session.md) - files identities under the key this proves -- [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - the announce messages this extends -- [P2P](/quest/m2/p2p/README.md) - its roster id is already planned as a public key diff --git a/quest/m1/cluster-routing/routes/session.md b/quest/m1/cluster-routing/routes/session.md index c006ea8c030..c5d583a0648 100644 --- a/quest/m1/cluster-routing/routes/session.md +++ b/quest/m1/cluster-routing/routes/session.md @@ -97,9 +97,9 @@ revision, stays separate ("keep administrative identity and broadcast epoch separate", in the epic). Decided 2026-11-04 (maintainer, /quest-unblock): a scoped peer's identities -are keyed by a route key the peer proves, specified in -[Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md). -Every identity a scoped, proven peer sends, its own included, is qualified +are keyed by a route key the peer proves in its lite-07 SETUP: the session's +`PeerSetup::route_key` once its SETUP arrives, and `None` for a peer that proved +none. Relays set theirs with `--cluster-route-key`. Every identity a scoped, proven peer sends, its own included, is qualified under its proven key, so relays sharing a key file fail over as one. A peer that proves no key gets a per-session key. `Scope::qualify` still takes the key from the caller, so this quest does not wait on the proof. Options shown: diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 961d41858c9..c7b0f7ed9fc 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -37,10 +37,9 @@ stability. Both are additive and, per the freeze policy, target whichever lite wip is current when they land. Decided 2026-10-25: no routing identity proof gates the cut, and lite-07 routing identities stay declared and unverified (2026-11-02: peer grants are dropped and no key proof is planned). Reversed -2026-11-04 (maintainer, /quest-unblock): a peer proves a route key once per -announce stream before the cut, through -[Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md) in -[Routes and announces](/quest/m1/cluster-routing/routes/README.md). Decided 2026-10-26 +2026-11-04 (maintainer, /quest-unblock): a peer proves a route key before the +cut, which landed as lite-07's Route Key Setup Parameter; its routes are filed +under it in [Routes and announces](/quest/m1/cluster-routing/routes/README.md). Decided 2026-10-26 (maintainer): receivers do not stamp per-session identities either, since that splits one origin into several identities across a relay mesh. diff --git a/rs/moq-crypto/src/sign/secret.rs b/rs/moq-crypto/src/sign/secret.rs index 19c86a1ba37..70d45466126 100644 --- a/rs/moq-crypto/src/sign/secret.rs +++ b/rs/moq-crypto/src/sign/secret.rs @@ -125,6 +125,15 @@ impl SecretKey { } } +impl From<&SecretKey> for moq_net::origin::RouteKey { + /// The same key, for an origin to prove to its peers. + fn from(key: &SecretKey) -> Self { + let seed = key.0.pair.to_seed(); + let seed: Zeroizing<[u8; KEY_LEN]> = Zeroizing::new(seed.as_ref().try_into().expect("a 32-byte Ed25519 seed")); + Self::from_seed(&seed) + } +} + impl fmt::Debug for SecretKey { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("SecretKey") diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index b34d923d7a8..0db34754814 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -37,11 +37,14 @@ moq-pattern = { workspace = true, features = ["serde"] } num_enum = { workspace = true } rand = { workspace = true } rangemap = { workspace = true } +# Ed25519 for route key proofs, and HKDF for the in-memory transport's exporter. +rind = { workspace = true } serde = { workspace = true } slab = { workspace = true } thiserror = { workspace = true } tracing = { workspace = true } url = { workspace = true } +zeroize = { workspace = true } [dev-dependencies] criterion = { package = "bench-harness", path = "../bench-harness" } diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 79fb80906f3..0182fbd72e7 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Origins prove a route key ([#7937](https://github.com/moq-dev/moq/pull/7937)) + +`origin::Config::route_key` takes an `origin::RouteKey`, which every lite-07 session on the origin proves to its peer in SETUP. Origins sharing a key fail over as one to a peer that scopes them; `None`, the default, proves nothing. +A proof binds to the session through the new `poll::Session::export_keying_material`, which defaults to `None`: a transport over TLS returns its exporter, and a wrapper around another transport forwards it. + ### Opens wait their turn for stream credit ([#7894](https://github.com/moq-dev/moq/pull/7894)) A request no longer fails with `Error::NoStreamCredit` when the peer grants no more streams: every stream a session opens waits for credit, and returning credit goes to the open whose stream the transport would send first. The variant is removed; drop any arm matching it. diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 5047e1d1afb..9ad0cc7120a 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -329,6 +329,8 @@ impl Client { token: self.setup_token.clone().filter(|_| version.has_auth()), ietf: self.extensions.ietf && version.has_ietf(), implementation: self.implementation(), + // Filled by `lite::start` from the attached origin handles. + route_key: None, } } else { lite::Setup::default() diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 426bf81a649..27869bb9e2c 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -8541,7 +8541,7 @@ mod tests { // A SETUP that declares no origin of its own, so only the assigned one applies. let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { @@ -9126,7 +9126,7 @@ mod tests { } let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { runtime: crate::time::sim(), @@ -9253,7 +9253,7 @@ mod tests { .unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { estimate: kio::Producer::default().weak(), @@ -9316,7 +9316,7 @@ mod tests { let _track = broadcast.create_track("video", crate::track::Info::timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { estimate: kio::Producer::default().weak(), @@ -9374,7 +9374,7 @@ mod tests { broadcast.announce(Default::default()).unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { estimate: kio::Producer::default().weak(), @@ -9468,7 +9468,7 @@ mod tests { broadcast.announce(Default::default()).unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let version = Version::Lite07; let publisher = Publisher::new(PublisherConfig { @@ -9597,7 +9597,7 @@ mod tests { broadcast.announce(Default::default()).unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let version = Version::Lite07; let publisher = Publisher::new(PublisherConfig { diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index d0632dc2b28..0410b7a35a8 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -255,6 +255,22 @@ pub fn start(config: Config) -> Result { .filter(|hop| hop.id() != 0); } + // Prove our origin's route key, bound to this session, so a peer that scopes us files + // our routes under it. A transport without an exporter cannot bind a proof, so neither + // side proves anything there. + let transcript = version + .has_route_key() + .then(|| session.export_keying_material(crate::route::EXPORTER_LABEL, &[])) + .flatten() + .map(crate::route::Transcript::new); + let route_key = publish + .as_ref() + .and_then(|origin| origin.route_key()) + .or_else(|| subscribe.as_ref().and_then(|origin| origin.route_key())); + if let (Some(transcript), Some(key)) = (&transcript, route_key) { + our_setup.route_key = Some(transcript.prove(&key, client)); + } + // What the peer's connection credential earns by default: publishing what our // subscribe half accepts, and subscribing to what our publish half serves. A // missing half grants nothing. @@ -295,6 +311,7 @@ pub fn start(config: Config) -> Result { // Setup stream isn't expected on the wire again. let peer_implementation = crate::setup::PeerImplementation::default(); let mut peer_setup_slot = PeerSetup::new(client, session.address()) + .with_transcript(transcript) .offer_ietf(our_setup.ietf) .with_implementation(peer_implementation.clone()); // Without AUTH, the server checks a client's credential before its SETUP, which the @@ -307,7 +324,7 @@ pub fn start(config: Config) -> Result { peer_implementation.set(None); } let early = if let Some(accepted) = peer_setup { - peer_setup_slot.set(accepted.setup); + peer_setup_slot.set(accepted.setup)?; accepted.early } else { Vec::new() diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 6cdd9965762..8f2b4e244ef 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -19,6 +19,8 @@ const PARAM_HOP: u64 = 0x5; const PARAM_IMPLEMENTATION: u64 = 0x6; /// Setup Parameter id for the client's connection credential (client-only, lite-07+). const PARAM_TOKEN: u64 = 0x7; +/// Setup Parameter id for the sender's route key proof (lite-07+). +const PARAM_ROUTE_KEY: u64 = 0x8; /// Setup Parameter id offering the `ietf` extension (draft-lcurley-moq-ietf): "IETF" in ASCII. const PARAM_IETF: u64 = 0x4945_5446; @@ -207,6 +209,8 @@ pub struct Setup { /// The sender's implementation, as space-separated `name/version` product tokens /// (`moq-net-rs/0.3.10`). Opaque; `None` omits the parameter. pub implementation: Option, + /// Proof that the sender holds its route key, bound to this session (lite-07+). + pub route_key: Option, } impl std::fmt::Debug for Setup { @@ -224,6 +228,7 @@ impl std::fmt::Debug for Setup { .field("token", &self.token) .field("ietf", &self.ietf) .field("implementation", &self.implementation) + .field("route_key", &self.route_key) .finish() } } @@ -280,6 +285,12 @@ impl<'a> Message<'a> for Setup { } params.set_bytes(PARAM_IETF, Vec::new()); } + if let Some(proof) = self.route_key { + if !version.has_route_key() { + return Err(EncodeError::Version); + } + params.set_bytes(PARAM_ROUTE_KEY, proof.to_bytes()); + } params.encode(w, version) } @@ -343,6 +354,12 @@ impl<'a> Message<'a> for ReceivedSetup { }, _ => false, }; + let route_key = match params.get_bytes(PARAM_ROUTE_KEY) { + Some(value) if version.has_route_key() => { + Some(crate::route::Proof::from_bytes(value).ok_or(DecodeError::InvalidValue)?) + } + _ => None, + }; Ok(Self { role_present: role_code.is_some(), @@ -355,6 +372,7 @@ impl<'a> Message<'a> for ReceivedSetup { token, ietf, implementation, + route_key, }, }) } @@ -383,6 +401,27 @@ struct PeerSetupState { implementation: crate::setup::PeerImplementation, /// The session's auth link to tell once the peer's SETUP accepts the connection. accept: Option, + /// What the peer's route key proof must sign, or `None` when the transport cannot bind + /// one to this session, so any proof leaves the peer unproven. + transcript: Option, + /// The route key the peer proved. + route_key: Option<[u8; 32]>, +} + +impl PeerSetupState { + /// Keep the key the peer's SETUP proves, or refuse a proof whose signature fails. + fn prove(&mut self, setup: &Setup) -> Result<(), crate::Error> { + let (Some(proof), Some(transcript)) = (&setup.route_key, &self.transcript) else { + return Ok(()); + }; + // The peer holds the side of the session we do not. + if !transcript.verify(proof, !self.client) { + return Err(crate::Error::ProtocolViolation); + } + tracing::debug!(proof = ?proof, "peer proved its route key"); + self.route_key = Some(proof.key); + Ok(()) + } } impl PeerSetup { @@ -395,9 +434,17 @@ impl PeerSetup { setup: None, implementation: Default::default(), accept: None, + transcript: None, + route_key: None, })) } + /// Check the peer's route key proof against `transcript`, this session's. + pub fn with_transcript(self, transcript: Option) -> Self { + self.0.lock().transcript = transcript; + self + } + /// Tell `link` once the peer's SETUP arrives that it accepted the connection credential. pub fn accepting(self, link: crate::auth::Link) -> Self { link.await_setup(); @@ -418,6 +465,7 @@ impl PeerSetup { { return Err(crate::Error::ProtocolViolation); } + state.prove(&received.setup)?; state.seen = true; state.implementation.set(received.setup.implementation.clone()); state.setup = Some(received.setup); @@ -454,12 +502,23 @@ impl PeerSetup { } } - /// Record the peer's SETUP. - pub fn set(&self, setup: Setup) { + /// Record the peer's SETUP, refusing a route key proof that does not hold. + pub fn set(&self, setup: Setup) -> Result<(), crate::Error> { let mut state = self.0.lock(); + state.prove(&setup)?; state.seen = true; state.implementation.set(setup.implementation.clone()); state.setup = Some(setup); + Ok(()) + } + + /// The route key the peer proved, once its SETUP arrived. + #[cfg_attr( + not(test), + expect(dead_code, reason = "session integration files a scoped peer's routes under it") + )] + pub fn route_key(&self) -> Option<[u8; 32]> { + self.0.lock().route_key } /// Claim the Setup Stream before decoding its body, refusing any second stream. @@ -652,6 +711,50 @@ mod tests { /// The connection credential rides lite-07+, which an older version ignores like any /// unknown parameter, and only an untyped, non-empty token can be sent. + #[test] + fn route_key_is_lite07_only() { + let transcript = crate::route::Transcript::new([2; 32]); + let msg = Setup { + route_key: Some(transcript.prove(&crate::origin::RouteKey::generate(), true)), + ..Default::default() + }; + let buf = msg.encode_bytes(Version::Lite07).unwrap(); + assert_eq!(Setup::decode_slice(&buf, Version::Lite07).unwrap().0, msg); + assert!(matches!(msg.encode_bytes(Version::Lite06), Err(EncodeError::Version))); + + // One parameter, its id, then a 95-byte value: not a proof. + let mut short = vec![0x01, 0x08, 0x5f]; + short.extend([0; 95]); + let mut framed = Vec::new(); + Encoder::new(&mut framed, Version::Lite07.into()).varint(short.len() as u64).unwrap(); + framed.extend(short); + assert!(Setup::decode_slice(&framed, Version::Lite07).is_err()); + } + + /// A server checks the client's proof against this session, and refuses one that fails. + #[test] + fn peer_route_key_is_kept_only_when_its_proof_holds() { + let key = crate::origin::RouteKey::generate(); + let session = || Some(crate::route::Transcript::new([2; 32])); + let proven = |client: bool| Setup { + route_key: Some(crate::route::Transcript::new([2; 32]).prove(&key, client)), + ..Default::default() + }; + let server = || PeerSetup::new(false, crate::transport::Address::Setup).with_transcript(session()); + + let peer = server(); + peer.set(proven(true)).unwrap(); + assert_eq!(peer.route_key(), proven(true).route_key.map(|proof| proof.key)); + + // A server's own proof reflected back as the client's. + assert!(matches!(server().set(proven(false)), Err(crate::Error::ProtocolViolation))); + + // A transport that cannot export leaves the peer unproven, whatever it sends. + let unbound = PeerSetup::new(false, crate::transport::Address::Setup); + unbound.set(proven(false)).unwrap(); + assert_eq!(unbound.route_key(), None); + } + #[test] fn token_is_lite07_only() { let token = crate::setup::Token { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 58f76ed899d..98f853c177b 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -3965,7 +3965,7 @@ mod tests { .unwrap(); assert_eq!(accepted.early.len(), 2); assert!(log.stops().is_empty()); - peer_setup.set(accepted.setup); + peer_setup.set(accepted.setup).unwrap(); accepted.early } else { Vec::new() diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 4732ac9958d..469ac26b633 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -327,6 +327,14 @@ impl Version { ) } + /// Whether SETUP may carry a route key proof. Added in lite-07. + pub(crate) fn has_route_key(self) -> bool { + !matches!( + self, + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 + ) + } + /// Whether the announce stream has ANNOUNCE_RESTART: another publisher instance /// replacing an advertisement in place. Added in lite-07. Older versions send an /// ANNOUNCE_END then an ANNOUNCE_START. diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 2d20e881904..b8d1c6920cd 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -53,6 +53,7 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { pub use super::follow::Following; + pub use crate::route::RouteKey; pub(crate) use super::origin_impl::HiddenWithheld; #[cfg(feature = "async")] pub(crate) use super::origin_impl::HiddenWithholding; diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index b08a1aaec0a..0b1fb7b67e8 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -106,6 +106,11 @@ pub struct Config { /// detection and shortest-path routing. pub hop: Hop, + /// The key this origin proves to every lite-07 peer, which files the routes it sends + /// under it when its grant is scoped. Origins sharing a key fail over as one. `None` + /// proves nothing, so such a peer files them under a key of its session alone. + pub route_key: Option, + /// Longest hop path a session using this origin accepts or forwards (default 32). /// /// Applies to moq-lite-03+ hop paths and the negotiated MoQ Cluster extension on @@ -162,6 +167,7 @@ impl Default for Config { let pool = cache::Pool::new(cache::Config::default().with_expiry(cache::DEFAULT_EXPIRY)); Self { hop: Hop::random(), + route_key: None, max_hops: HopLimit::default(), pool, cache_duration: Duration::MAX, @@ -2137,7 +2143,7 @@ impl Producer { let (tasks, set) = TaskSet::new(); let scope = OriginScope::default(); let timers = Deadlines::new(Instant::ZERO); - let shared = SendCell::new(kio::Shared::new(OriginState::new(config.update_hold))); + let shared = SendCell::new(kio::Shared::new(OriginState::new(config.update_hold, config.route_key))); let pool = config.pool.clone(); let producer = Self { hop: config.hop, @@ -2223,6 +2229,7 @@ impl Producer { pool: self.pool.clone(), cache_duration: self.cache_duration, update_hold: self.shared.lock().update_hold, + route_key: self.route_key(), } } @@ -2231,6 +2238,12 @@ impl Producer { self.hop } + /// The key sessions prove for this origin. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn route_key(&self) -> Option { + self.shared.lock().route_key.clone() + } + // Sessions enforce the policy configured once on the origin. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub(crate) fn max_hops(&self) -> HopLimit { @@ -2251,7 +2264,7 @@ impl Producer { scope: OriginScope::empty(), max_hops: HopLimit::default(), root: Path::default(), - shared: SendCell::new(kio::Shared::new(OriginState::new(DEFAULT_UPDATE_HOLD))), + shared: SendCell::new(kio::Shared::new(OriginState::new(DEFAULT_UPDATE_HOLD, None))), pool: cache::Pool::default(), cache_duration: Duration::MAX, stats: stats::Session::default(), @@ -5171,6 +5184,8 @@ struct OriginState { // See [`Config::update_hold`]. No `Default`: every origin takes it from its // config, so no path silently disables the hold. update_hold: Duration, + // See [`Config::route_key`]. + route_key: Option, // The announced routes, keyed by prefix. The table holds one entry per live // advertisement, not one per broadcast consumer. @@ -5209,9 +5224,10 @@ struct OriginState { } impl OriginState { - fn new(update_hold: Duration) -> Self { + fn new(update_hold: Duration, route_key: Option) -> Self { Self { update_hold, + route_key, routes: RouteTable::default(), next_route: 0, next_watch: 0, @@ -6543,6 +6559,12 @@ impl Consumer { self.hop } + /// The key sessions prove for this origin. + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn route_key(&self) -> Option { + self.shared.lock().route_key.clone() + } + /// A clone that never serves the given peer its own data: routes whose hop /// chain contains `peer`, or whose announcing session is `peer`, are invisible /// and never resolved from, matching what the announce loop advertises to them. diff --git a/rs/moq-net/src/route/mod.rs b/rs/moq-net/src/route/mod.rs index b14b9ffa373..a8e7611b51d 100644 --- a/rs/moq-net/src/route/mod.rs +++ b/rs/moq-net/src/route/mod.rs @@ -13,6 +13,7 @@ #![cfg_attr(not(test), allow(dead_code, reason = "the lite-07 session does not drive it yet"))] +mod proof; mod view; #[cfg(test)] @@ -27,6 +28,8 @@ use std::{ use crate::Path; +pub use proof::RouteKey; +pub(crate) use proof::{EXPORTER_LABEL, Proof, Transcript}; pub(crate) use view::{View, overlaps, within}; /// An opaque routing identity, declared by an origin or derived by [`Scope`]. diff --git a/rs/moq-net/src/route/proof.rs b/rs/moq-net/src/route/proof.rs new file mode 100644 index 00000000000..90b518cedba --- /dev/null +++ b/rs/moq-net/src/route/proof.rs @@ -0,0 +1,177 @@ +//! Route key proofs: an endpoint shows its peer that it holds a route key's secret. +//! +//! A proof is an Ed25519 signature over a secret both ends export from the session's +//! handshake and the prover's side of the session, so it neither replays on another +//! session nor reflects back to the peer that sent it. + +use std::{fmt, sync::Arc}; + +use rind::signature::{Ed25519KeyPair, PublicKey, verify::ED25519}; +use zeroize::Zeroizing; + +/// The label every transport binding exports the session secret under. +pub(crate) const EXPORTER_LABEL: &[u8] = b"EXPORTER-moq-lite-route-key"; + +/// Bytes of exported secret a proof signs. +const SECRET_LEN: usize = 32; + +/// Separates a route proof from anything else the same key signs. +const DOMAIN: &[u8] = b"moq-lite route key"; + +const KEY_LEN: usize = 32; +const SIGNATURE_LEN: usize = 64; + +/// The PKCS#8 v1 (RFC 8410) encoding of an Ed25519 key, up to its 32-byte seed. rind loads a +/// seed alone only this way. +const PKCS8_SEED_PREFIX: [u8; 16] = [ + 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, +]; + +/// The Ed25519 key an origin proves to its peers, so they file its routes under it. +/// +/// Relays sharing one key present an origin under the same identity whichever of them +/// carries it, so a scoped peer reached through either fails over as one. Cheap to clone; +/// its `Debug` shows only the public key. +#[derive(Clone)] +pub struct RouteKey(Arc); + +impl RouteKey { + /// Generate a fresh key from the system's secure random source. + pub fn generate() -> Self { + Self(Arc::new(Ed25519KeyPair::generate().expect("system randomness"))) + } + + /// The key with this 32-byte Ed25519 seed. + pub fn from_seed(seed: &[u8; KEY_LEN]) -> Self { + let mut der = Zeroizing::new([0u8; PKCS8_SEED_PREFIX.len() + KEY_LEN]); + der[..PKCS8_SEED_PREFIX.len()].copy_from_slice(&PKCS8_SEED_PREFIX); + der[PKCS8_SEED_PREFIX.len()..].copy_from_slice(seed); + Self(Arc::new( + Ed25519KeyPair::from_pkcs8(der.as_ref()).expect("a PKCS#8 v1 Ed25519 key"), + )) + } + + fn public(&self) -> [u8; KEY_LEN] { + self.0 + .public_key() + .as_ref() + .try_into() + .expect("a 32-byte Ed25519 public key") + } +} + +impl fmt::Debug for RouteKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_tuple("RouteKey").field(&Hex(&self.public())).finish() + } +} + +/// A proof that the sender holds a route key, as it travels in SETUP: the public key, then +/// its signature. +#[derive(Clone, Copy, PartialEq, Eq)] +pub(crate) struct Proof { + pub key: [u8; KEY_LEN], + pub signature: [u8; SIGNATURE_LEN], +} + +impl Proof { + /// Its encoded size; any other is malformed. + pub const LEN: usize = KEY_LEN + SIGNATURE_LEN; + + pub fn to_bytes(self) -> Vec { + [self.key.as_slice(), self.signature.as_slice()].concat() + } + + /// Decode a proof, or `None` when `bytes` is not exactly [`Self::LEN`] long. + pub fn from_bytes(bytes: &[u8]) -> Option { + let (key, signature) = bytes.split_first_chunk::()?; + Some(Self { + key: *key, + signature: signature.try_into().ok()?, + }) + } +} + +impl fmt::Debug for Proof { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("Proof").field("key", &Hex(&self.key)).finish_non_exhaustive() + } +} + +/// What a proof on one session signs: the secret both ends export from its handshake. +pub(crate) struct Transcript(Zeroizing<[u8; SECRET_LEN]>); + +impl Transcript { + pub fn new(secret: [u8; SECRET_LEN]) -> Self { + Self(Zeroizing::new(secret)) + } + + /// The signed message: the domain, the prover's side (0 dialed, 1 accepted), and the secret. + fn message(&self, client: bool) -> Zeroizing> { + Zeroizing::new([DOMAIN, &[u8::from(!client)], self.0.as_slice()].concat()) + } + + /// Prove `key` as the side of this session `client` names. + pub fn prove(&self, key: &RouteKey, client: bool) -> Proof { + Proof { + key: key.public(), + signature: key + .0 + .sign(&self.message(client)) + .as_ref() + .try_into() + .expect("a 64-byte Ed25519 signature"), + } + } + + /// Whether `proof` shows its key held by the side of this session `client` names. + pub fn verify(&self, proof: &Proof, client: bool) -> bool { + PublicKey::new(&ED25519, &proof.key).is_ok_and(|key| key.verify(&self.message(client), &proof.signature).is_ok()) + } +} + +struct Hex<'a>(&'a [u8]); + +impl fmt::Debug for Hex<'_> { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.0.iter().try_for_each(|byte| write!(f, "{byte:02x}")) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Shared with `js/net/src/lite/route_key.test.ts`, so both sides sign the same transcript. + const CLIENT_PROOF: &str = concat!( + "8a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c", + "e7ea4e34a65b8501185b805d09b58a61b5b8495654fcaac0949d4f98aa35002e", + "6fca096329973e91e1105030dd88fa0eb543c68c00e18394f8300cb0574cf901", + ); + + #[test] + fn a_proof_matches_the_js_transcript() { + let proof = Transcript::new([2; 32]).prove(&RouteKey::from_seed(&[1; 32]), true); + assert_eq!(format!("{:?}", Hex(&proof.to_bytes())), CLIENT_PROOF); + } + + #[test] + fn a_proof_holds_only_for_its_side_of_its_session() { + let transcript = Transcript::new([2; 32]); + let proof = transcript.prove(&RouteKey::generate(), true); + assert!(transcript.verify(&proof, true)); + assert!(!transcript.verify(&proof, false), "reflected to its sender"); + assert!(!Transcript::new([3; 32]).verify(&proof, true), "replayed on another session"); + + let other = RouteKey::generate().public(); + assert!(!transcript.verify(&Proof { key: other, ..proof }, true), "claimed for another key"); + } + + #[test] + fn a_proof_decodes_only_at_its_size() { + let proof = Transcript::new([2; 32]).prove(&RouteKey::generate(), false); + assert_eq!(Proof::from_bytes(&proof.to_bytes()), Some(proof)); + assert_eq!(Proof::from_bytes(&[0; Proof::LEN - 1]), None); + assert_eq!(Proof::from_bytes(&[0; Proof::LEN + 1]), None); + } +} diff --git a/rs/moq-net/src/route/tests/routing.rs b/rs/moq-net/src/route/tests/routing.rs index 2397704c8c7..68579209a42 100644 --- a/rs/moq-net/src/route/tests/routing.rs +++ b/rs/moq-net/src/route/tests/routing.rs @@ -605,7 +605,8 @@ fn forged_identity_is_filed_apart_under_a_scoped_grant() { /// A local mesh publishing through two uplinks, each admitted under the same /// subject. Both CDN relays file the local origin under one key, so it -/// survives losing an uplink; a retracted identity leaves no alias behind. +/// survives losing an uplink, and so does the local relay's own identity; a +/// retracted identity leaves no alias behind. #[test] fn scoped_delivery_through_two_uplinks_reaches_one_key() { let (c1, c2, l1, l2, origin) = (0, 1, 2, 3, 4); @@ -627,6 +628,12 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { assert_eq!(next(&sim, c2, key), Some(l2)); assert_eq!(next(&sim, c1, qualified(LOCAL.subject, 20)), Some(l1)); + sim.disconnect(l1, c1); + assert!(sim.run()); + assert_eq!(next(&sim, c1, qualified(LOCAL.subject, 20)), Some(c2), "the local relay's own fails over"); + sim.connect(l1, c1); + assert!(sim.run()); + sim.disconnect(l2, c2); assert!(sim.run()); assert_eq!(next(&sim, c2, key), Some(c1)); diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index f43fb9179ee..8660fb95e34 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -179,6 +179,8 @@ impl Server { token: None, ietf: self.extensions.ietf && version.has_ietf(), implementation: self.implementation(), + // Filled by `lite::start` from the attached origin handles. + route_key: None, } } else { lite::Setup::default() @@ -1107,6 +1109,7 @@ mod tests { token: None, ietf: false, implementation: None, + route_key: None, } .encode(&mut crate::coding::Encoder::new(&mut buf, v.into()), v) .unwrap(); diff --git a/rs/moq-net/src/transport.rs b/rs/moq-net/src/transport.rs index 195553bf134..30141b4e1dc 100644 --- a/rs/moq-net/src/transport.rs +++ b/rs/moq-net/src/transport.rs @@ -407,6 +407,17 @@ pub mod poll { None } + /// Export 32 bytes of keying material from this session's handshake under `label` and + /// `context` (RFC 8446 section 7.5), or `None` when the transport has no exporter. + /// + /// Both ends of one session export the same bytes, and no other session does. + /// WebTransport derives them per session as its draft specifies, since other sessions + /// may share the connection. + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + let _ = (label, context); + None + } + /// Accept the next unidirectional stream opened by the peer. fn accept_uni(&self) -> AcceptUni<'_, Self> { AcceptUni::new(self) @@ -615,6 +626,10 @@ pub mod poll { fn stream_credit(&self, dir: super::Dir) -> Option { (**self).stream_credit(dir) } + + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + (**self).export_keying_material(label, context) + } } /// A transport that the async client and server can box: diff --git a/rs/moq-net/src/transport/boxed.rs b/rs/moq-net/src/transport/boxed.rs index 4730d990ca5..09c2b72b355 100644 --- a/rs/moq-net/src/transport/boxed.rs +++ b/rs/moq-net/src/transport/boxed.rs @@ -355,6 +355,7 @@ pub(super) trait ErasedSession: Send + Sync { fn probe(&self) -> Option; fn receive_window(&self) -> Option; fn stream_credit(&self, dir: Dir) -> Option; + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]>; } trait ErasedGroup: Send + Sync { @@ -494,6 +495,10 @@ impl ErasedSession for S { fn stream_credit(&self, dir: Dir) -> Option { poll::Session::stream_credit(self, dir) } + + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + poll::Session::export_keying_material(self, label, context) + } } impl ErasedGroup for G { @@ -682,6 +687,10 @@ impl poll::Session for Session { fn stream_credit(&self, dir: Dir) -> Option { self.inner.session.stream_credit(dir) } + + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + self.inner.session.export_keying_material(label, context) + } } impl poll::SendStream for SendStream { diff --git a/rs/moq-net/src/transport/memory.rs b/rs/moq-net/src/transport/memory.rs index c1e54229394..fe0f1bec1f2 100644 --- a/rs/moq-net/src/transport/memory.rs +++ b/rs/moq-net/src/transport/memory.rs @@ -78,7 +78,10 @@ impl Default for Config { /// Create two connected sessions: streams one opens, the other accepts. pub fn pair(config: Config) -> (Session, Session) { + let mut secret = [0; 32]; + rand::RngExt::fill(&mut kio::clock::rng(), &mut secret); let conn = Arc::new(Conn { + secret: rind::hkdf::Salt::new(&rind::hkdf::HKDF_SHA256, &[]).extract(&secret), close: Default::default(), incoming: [Incoming::default(), Incoming::default()], config, @@ -158,6 +161,8 @@ fn closed(close: &Close) -> Option { /// State shared by both sides of a pair. struct Conn { config: Config, + /// What both sides export keying material from, standing in for a TLS handshake's secret. + secret: rind::hkdf::Prk, close: Close, /// What each side has yet to accept. incoming: [Incoming; 2], @@ -442,6 +447,18 @@ impl poll::Session for Session { super::Dir::Bi => stream_credit(&outgoing.bi_open, config.max_concurrent_bi_streams), }) } + + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + // Length-prefixed, so no label and context pair collides with another. + let lengths = [u8::try_from(label.len()).ok()?, u8::try_from(context.len()).ok()?]; + let mut output = [0; 32]; + self.conn() + .secret + .expand(&[&lengths, label, context], output.len()) + .fill(&mut output) + .expect("32 bytes fit HKDF-SHA256"); + Some(output) + } } /// One direction of a stream: the messages its writer queued for its reader. diff --git a/rs/moq-net/tests/integration/routing_contracts/mod.rs b/rs/moq-net/tests/integration/routing_contracts/mod.rs index b39e9ded6ef..6d342c4e3bd 100644 --- a/rs/moq-net/tests/integration/routing_contracts/mod.rs +++ b/rs/moq-net/tests/integration/routing_contracts/mod.rs @@ -1109,8 +1109,8 @@ fn transit_priority_depends_on_arrival_order() { /// claims outside the forger's namespace, and its seqno outlives it: after it /// leaves, the victim's real routes are refused until the victim counts past /// the forged seqno. Filed under `hash(subject, id)`, the forgery serves only -/// claims inside the forger's scope. The forger's own proven identity stays -/// bare either way. +/// claims inside the forger's scope. The forger's own identity is filed the +/// same way, so declaring the victim's identity as its own gains it nothing more. #[test] fn forged_identity_hijacks_claims_outside_the_forgers_scope() { for scoped_admission in [false, true] { @@ -1137,7 +1137,13 @@ fn forged_identity_hijacks_claims_outside_the_forgers_scope() { net.forge(forger, 7, 1000); assert!(net.run()); - assert!(net.route(core, 3).is_some(), "a connection's own identity is bare"); + let own = if scoped_admission { qualified("forger", 3) } else { 3 }; + assert!(net.route(core, own).is_some()); + assert_eq!( + net.route(core, 3).is_some(), + !scoped_admission, + "a scoped connection's own identity is qualified" + ); let served = served_by(&net.request(core, "other/x", Forward::Pinned)); if scoped_admission { assert_eq!(served, Some((7, victim))); @@ -1165,8 +1171,8 @@ fn forged_identity_hijacks_claims_outside_the_forgers_scope() { /// subject. Both CDN relays file the local origin under one key, so it survives /// losing an uplink: the first hop keeps its identity and the request follows /// the other uplink, named as the local relay knows it. Claims outside the -/// scope are refused under that key, and the local relay's own identity stays -/// bare. +/// scope are refused under that key. The local relay's own identity is filed +/// under the same key, so its own broadcast fails over the same way. #[test] fn scoped_delivery_through_two_uplinks_reaches_one_key() { let (c1, c2, l1, l2, origin) = (0, 1, 2, 3, 4); @@ -1182,13 +1188,31 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { net.originate(l1, 20, 0); net.claim(9, "local/", 0, None); net.claim(9, "cdn/", 0, None); + net.claim(20, "local/l1/", 0, None); assert!(net.run()); let key = qualified(LOCAL.subject, 9); assert!(net.route(c1, 9).is_none()); assert_eq!(net.route(c1, key).and_then(|route| route.next), Some(l1)); assert_eq!(net.route(c2, key).and_then(|route| route.next), Some(l2)); - assert_eq!(net.route(c1, 20).and_then(|route| route.next), Some(l1)); + let own = qualified(LOCAL.subject, 20); + assert!(net.route(c1, 20).is_none(), "the local relay's own identity is qualified"); + assert_eq!(net.route(c1, own).and_then(|route| route.next), Some(l1)); + assert_eq!(net.resolve(c2, "local/l1/x"), Some(own)); + + // The local relay loses its direct uplink, and its own broadcast fails over through its sibling. + net.disconnect(l1, c1); + assert!(net.run()); + assert_eq!(net.resolve(c1, "local/l1/x"), Some(own)); + assert_eq!( + net.request(c1, "local/l1/x", Forward::Pinned), + Outcome::Served { + by: 20, + path: vec![c1, c2, l2, l1] + } + ); + net.connect(l1, c1); + assert!(net.run()); assert_eq!(net.resolve(c2, "local/x"), Some(key)); assert_eq!( net.request(c2, "local/x", Forward::Pinned), diff --git a/rs/moq-net/tests/integration/routing_contracts/model.rs b/rs/moq-net/tests/integration/routing_contracts/model.rs index 18af0b52ca9..2d094da842e 100644 --- a/rs/moq-net/tests/integration/routing_contracts/model.rs +++ b/rs/moq-net/tests/integration/routing_contracts/model.rs @@ -533,10 +533,10 @@ pub struct Retained { #[derive(Default)] struct State { - /// The identity this node's sessions prove, if it originates one. + /// This node's own identity, if it originates one. proven: Option, - /// Identities this node serves itself, with their seqnos: its proven one, - /// plus any it forges. + /// Identities this node serves itself, with their seqnos: its own, plus any + /// it forges. origins: BTreeMap, /// Whether this node advertises identities it does not serve. transit: bool, @@ -686,9 +686,6 @@ pub struct Net { /// Every `(subject, scope)` a configured link grants. grants: BTreeSet<(&'static str, &'static str)>, up: BTreeSet<(Node, Node)>, - /// `(node, peer)`: the identity `node` proved on its session to `peer`. A - /// session proves one key, once. - proved: BTreeMap<(Node, Node), Id>, /// `(at, peer)`: `peer` sent `at` a GOAWAY on their current session. draining: BTreeSet<(Node, Node)>, queues: BTreeMap<(Node, Node), VecDeque>, @@ -717,7 +714,6 @@ impl Net { links: vec![vec![None; nodes]; nodes], grants: BTreeSet::new(), up: BTreeSet::new(), - proved: BTreeMap::new(), draining: BTreeSet::new(), queues: BTreeMap::new(), acks: BTreeMap::new(), @@ -773,11 +769,6 @@ impl Net { pub fn connect(&mut self, a: Node, b: Node) { assert!(self.links[a][b].is_some(), "unknown link {a}-{b}"); self.up.insert(Self::pair(a, b)); - for (x, y) in [(a, b), (b, a)] { - if let Some(id) = self.nodes[x].proven { - self.proved.insert((x, y), id); - } - } self.advertise(a); self.advertise(b); } @@ -792,7 +783,6 @@ impl Net { for (x, y) in [(a, b), (b, a)] { self.queues.remove(&(x, y)); self.acks.remove(&(x, y)); - self.proved.remove(&(x, y)); self.held.remove(&(x, y)); self.draining.remove(&(y, x)); let state = &mut self.nodes[y]; @@ -848,14 +838,9 @@ impl Net { (0..self.nodes.len()).filter(move |&peer| self.links[node][peer].is_some() && self.connected(node, peer)) } - /// `node` starts originating `id` at seqno `seqno`, proving it on every session. + /// `node` starts originating `id` at seqno `seqno`. pub fn originate(&mut self, node: Node, id: Id, seqno: Seqno) { assert_eq!(id & QUALIFIED, 0, "a key-derived identity is never qualified"); - let peers: Vec = self.peers(node).collect(); - for peer in peers { - let proved = *self.proved.entry((node, peer)).or_insert(id); - assert_eq!(proved, id, "node {node}'s session to {peer} already proved another key"); - } let state = &mut self.nodes[node]; state.proven = Some(id); state.origins.insert(id, seqno); @@ -869,7 +854,7 @@ impl Net { self.advertise(node); } - /// `node` advertises `id` as if forwarding it, without proving it. + /// `node` advertises `id` as if forwarding it. pub fn forge(&mut self, node: Node, id: Id, seqno: Seqno) { self.nodes[node].origins.insert(id, seqno); self.advertise(node); @@ -889,9 +874,8 @@ impl Net { /// The origin at `node` retires its identity for a fresh one and announces /// its claims again there: what it does instead of advancing a seqno or a - /// revision to [`VARINT_MAX`]. A session proves one key once, so every - /// session closes and reopens to prove the new one, and every node lets the - /// old identity go. + /// revision to [`VARINT_MAX`]. Every session closes and reopens, so every + /// node lets the old identity go. fn rotate(&mut self, node: Node) { let peers: Vec = self.peers(node).collect(); for &peer in &peers { @@ -917,7 +901,7 @@ impl Net { self.nodes[node].views.get_mut(&id).unwrap().floors.insert("", rev); } - /// The identity `node` proves. + /// The identity `node` originates. pub fn proven(&self, node: Node) -> Id { self.nodes[node].proven.expect("not an origin") } @@ -1185,9 +1169,12 @@ impl Net { } /// The key `at` files `id` under when `from` names it, or `None` when refused. + /// + /// Under a scoped grant every identity is qualified, the sender's own included, by + /// the grant's subject, which stands in for the route key the sender proved. fn key(&self, at: Node, from: Node, id: Id) -> Option { match self.side(at, from).grant { - Some(grant) if self.proved.get(&(from, at)) != Some(&id) => { + Some(grant) => { if id & QUALIFIED != 0 && !self.cfg.requalify { return None; } diff --git a/rs/moq-quic/src/connection/mod.rs b/rs/moq-quic/src/connection/mod.rs index a0d9551cefc..5acafd0c3cf 100644 --- a/rs/moq-quic/src/connection/mod.rs +++ b/rs/moq-quic/src/connection/mod.rs @@ -1570,16 +1570,12 @@ impl Connection { self.crypto.peer_identity() } - /// Fill `output` with keying material exported from the TLS session (RFC 5705), using - /// `label` and `context` for domain separation - #[cfg(test)] - pub(crate) fn export_keying_material( - &self, - output: &mut [u8], - label: &[u8], - context: &[u8], - ) -> Result<(), crypto::ExportKeyingMaterialError> { - self.crypto.export_keying_material(output, label, context) + /// 32 bytes of keying material exported from the TLS session (RFC 8446 section 7.5) under + /// `label` and `context`, or `None` before the handshake completes. + pub fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + let mut output = [0; 32]; + self.crypto.export_keying_material(&mut output, label, context).ok()?; + Some(output) } /// Whether the connection is in the process of being established diff --git a/rs/moq-quic/src/crypto.rs b/rs/moq-quic/src/crypto.rs index 7a49936e139..b703f86f16f 100644 --- a/rs/moq-quic/src/crypto.rs +++ b/rs/moq-quic/src/crypto.rs @@ -33,7 +33,6 @@ pub struct HandshakeData { /// The requested keying material is longer than the handshake's hash can export. #[derive(Debug, PartialEq, Eq)] -#[cfg_attr(not(test), expect(dead_code, reason = "only tests export keying material"))] pub(crate) struct ExportKeyingMaterialError; /// A cryptographic session (commonly TLS) @@ -85,8 +84,7 @@ pub(crate) trait Session: Send + Sync + 'static { /// /// This function will fail, returning [ExportKeyingMaterialError], /// if the requested output length is too large. - #[cfg_attr(not(test), expect(dead_code, reason = "only tests export keying material"))] - fn export_keying_material( + fn export_keying_material( &self, output: &mut [u8], label: &[u8], diff --git a/rs/moq-quic/src/tests/mod.rs b/rs/moq-quic/src/tests/mod.rs index 96ed3f932b6..8ce17be6282 100644 --- a/rs/moq-quic/src/tests/mod.rs +++ b/rs/moq-quic/src/tests/mod.rs @@ -898,19 +898,10 @@ fn export_keying_material() { const LABEL: &[u8] = b"test_label"; const CONTEXT: &[u8] = b"test_context"; - // client keying material - let mut client_buf = [0u8; 64]; - pair.client_conn_mut(client_ch) - .export_keying_material(&mut client_buf, LABEL, CONTEXT) - .unwrap(); - - // server keying material - let mut server_buf = [0u8; 64]; - pair.server_conn_mut(server_ch) - .export_keying_material(&mut server_buf, LABEL, CONTEXT) - .unwrap(); - - assert_eq!(&client_buf[..], &server_buf[..]); + let client = pair.client_conn_mut(client_ch).export_keying_material(LABEL, CONTEXT); + let server = pair.server_conn_mut(server_ch).export_keying_material(LABEL, CONTEXT); + assert!(client.is_some()); + assert_eq!(client, server); } #[test] diff --git a/rs/moq-relay/Cargo.toml b/rs/moq-relay/Cargo.toml index 21abed77acb..ef01349896b 100644 --- a/rs/moq-relay/Cargo.toml +++ b/rs/moq-relay/Cargo.toml @@ -69,6 +69,7 @@ hyper = { workspace = true, optional = true } hyper-util = { workspace = true, features = ["server-auto"] } kio = { workspace = true, features = ["runtime", "serde"] } moq-auth = { workspace = true, features = ["client"] } +moq-crypto = { workspace = true, features = ["sign"] } moq-net = { workspace = true } # The flow-control limits both QUIC runtimes take, for widening a peer's connection. moq-quic = { workspace = true } diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 5686ddc3818..9f10cb5a394 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -739,6 +739,20 @@ pub struct Config { )] pub id: Option, + /// Route key file: the Ed25519 key this relay proves to every moq-lite-07 peer, + /// which files the routes this relay sends under it when this relay's grant is scoped. + /// + /// Relays given the same file present an origin under one key, so a scoped peer + /// reached through either fails over as one. A missing file is generated (mode 0600). + /// Unset generates a fresh key on every start. + #[usage( + name = "cluster-route-key", + long = "cluster-route-key", + env = "MOQ_CLUSTER_ROUTE_KEY", + setting = "cluster.route_key" + )] + pub route_key: Option, + /// Longest hop path accepted or forwarded, from 1 to 32 (default 32). #[usage( name = "cluster-max-hops", @@ -1393,6 +1407,12 @@ impl Cluster { peer.quic.validate()?; let mut work = kio::Tasks::new(); let mut origin_config = origin::Config::new(id); + origin_config.route_key = Some(match &config.route_key { + Some(path) => (&moq_crypto::sign::SecretKey::load_or_generate(path) + .with_context(|| format!("--cluster-route-key {}", path.display()))?) + .into(), + None => origin::RouteKey::generate(), + }); if let Some(max) = config.max_hops { origin_config.max_hops = origin::HopLimit::new(max).context("--cluster-max-hops must be from 1 to 32")?; } diff --git a/rs/moq-relay/src/settings.rs b/rs/moq-relay/src/settings.rs index 436558c2716..3b798f655e9 100644 --- a/rs/moq-relay/src/settings.rs +++ b/rs/moq-relay/src/settings.rs @@ -74,6 +74,9 @@ struct Cluster { #[usage(env = "MOQ_CLUSTER_ID", cli("--cluster-id"))] id: Option, + #[usage(env = "MOQ_CLUSTER_ROUTE_KEY", cli("--cluster-route-key"))] + route_key: Option, + #[usage(env = "MOQ_CLUSTER_MAX_HOPS", cli("--cluster-max-hops"))] max_hops: Option, diff --git a/rs/moq-tokio/src/quic/driver/connection.rs b/rs/moq-tokio/src/quic/driver/connection.rs index 234f23b538a..7e96468bfd2 100644 --- a/rs/moq-tokio/src/quic/driver/connection.rs +++ b/rs/moq-tokio/src/quic/driver/connection.rs @@ -496,6 +496,13 @@ impl Connection { moq_net::transport::ReceiveWindow::new(state.inner.receive_window(), state.inner.stream_receive_window()) } + /// 32 bytes of keying material exported from the TLS session under `label` and `context`, + /// or `None` before the handshake completes. + #[cfg(feature = "net")] + pub(crate) fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + self.0.state.lock().inner.export_keying_material(label, context) + } + /// The peer's stream credit in `dir`, as this connection last heard it. #[cfg(feature = "net")] pub(crate) fn stream_credit(&self, dir: moq_net::transport::Dir) -> moq_net::transport::StreamCredit { diff --git a/rs/moq-tokio/src/quic/web/session.rs b/rs/moq-tokio/src/quic/web/session.rs index 7fccf5c88ef..cf85a742186 100644 --- a/rs/moq-tokio/src/quic/web/session.rs +++ b/rs/moq-tokio/src/quic/web/session.rs @@ -1074,6 +1074,31 @@ impl moq_net::transport::poll::Session for Session { fn stream_credit(&self, dir: moq_net::transport::Dir) -> Option { Some(self.conn.stream_credit(dir)) } + /// The connection's exporter on raw QUIC; on WebTransport, this session's own. + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + match self.session_id { + None => self.conn.export_keying_material(label, context), + Some(id) => self.conn.export_keying_material( + WEBTRANSPORT_EXPORTER, + &webtransport_exporter_context(id.into_inner(), label, context)?, + ), + } + } +} + +/// The TLS exporter label WebTransport derives each session's exporter under. +const WEBTRANSPORT_EXPORTER: &[u8] = b"EXPORTER-WebTransport"; + +/// The TLS exporter context for WebTransport session `id`'s exporter (draft-ietf-webtrans-http3 +/// section 4.8), or `None` when `label` or `context` exceeds 255 bytes. +fn webtransport_exporter_context(id: u64, label: &[u8], context: &[u8]) -> Option> { + let mut exporter = Vec::with_capacity(10 + label.len() + context.len()); + exporter.extend_from_slice(&id.to_be_bytes()); + exporter.push(u8::try_from(label.len()).ok()?); + exporter.extend_from_slice(label); + exporter.push(u8::try_from(context.len()).ok()?); + exporter.extend_from_slice(context); + Some(exporter) } #[cfg(all(test, feature = "_certs"))] @@ -1342,6 +1367,28 @@ mod tests { } } + /// Both ends of a session export the same keying material as soon as it starts. A + /// WebTransport session derives its own from the connection's, so it differs from what + /// raw QUIC on the same connection would export. + #[tokio::test] + async fn both_ends_export_the_same_keying_material() { + use moq_net::transport::poll::Session as _; + + for framed in [false, true] { + let (client, server, _endpoints) = pair().await; + let (client, server) = sessions(framed, client, server).await; + let exported = client.export_keying_material(b"label", b"context"); + assert!(exported.is_some(), "framed: {framed}"); + assert_eq!(server.export_keying_material(b"label", b"context"), exported, "framed: {framed}"); + assert_ne!(client.export_keying_material(b"label", b""), exported, "framed: {framed}"); + assert_eq!( + client.conn.export_keying_material(b"label", b"context") == exported, + !framed, + "framed: {framed}" + ); + } + } + /// Once a read met the peer's reset, the close watch keeps reporting it rather than a clean end. #[tokio::test] async fn a_read_reset_stays_reset_for_the_close_watch() { diff --git a/rs/moq-uring/src/quic/driver/connection.rs b/rs/moq-uring/src/quic/driver/connection.rs index 849a33213a7..cbe21e39079 100644 --- a/rs/moq-uring/src/quic/driver/connection.rs +++ b/rs/moq-uring/src/quic/driver/connection.rs @@ -288,6 +288,12 @@ impl Connection { self.shared.conn.borrow().peer_identity() } + /// 32 bytes of keying material exported from the TLS session under `label` and `context`, + /// or `None` before the handshake completes. + pub(crate) fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + self.shared.conn.borrow().export_keying_material(label, context) + } + /// The peer's current UDP address, following any migration. pub fn remote_address(&self) -> SocketAddr { self.shared.conn.borrow().remote_address() diff --git a/rs/moq-uring/src/quic/web.rs b/rs/moq-uring/src/quic/web.rs index 925033a1124..8b955d2632a 100644 --- a/rs/moq-uring/src/quic/web.rs +++ b/rs/moq-uring/src/quic/web.rs @@ -852,6 +852,31 @@ impl moq_net::transport::poll::Session for Session { fn stream_credit(&self, dir: moq_net::transport::Dir) -> Option { Some(self.conn.stream_credit(dir)) } + /// The connection's exporter on raw QUIC; on WebTransport, this session's own. + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + match &self.web { + None => self.conn.export_keying_material(label, context), + Some(web) => self.conn.export_keying_material( + WEBTRANSPORT_EXPORTER, + &webtransport_exporter_context(web.session_id, label, context)?, + ), + } + } +} + +/// The TLS exporter label WebTransport derives each session's exporter under. +const WEBTRANSPORT_EXPORTER: &[u8] = b"EXPORTER-WebTransport"; + +/// The TLS exporter context for WebTransport session `id`'s exporter (draft-ietf-webtrans-http3 +/// section 4.8), or `None` when `label` or `context` exceeds 255 bytes. +fn webtransport_exporter_context(id: u64, label: &[u8], context: &[u8]) -> Option> { + let mut exporter = Vec::with_capacity(10 + label.len() + context.len()); + exporter.extend_from_slice(&id.to_be_bytes()); + exporter.push(u8::try_from(label.len()).ok()?); + exporter.extend_from_slice(label); + exporter.push(u8::try_from(context.len()).ok()?); + exporter.extend_from_slice(context); + Some(exporter) } /// Close the session: in web mode with a `CloseWebTransportSession` capsule diff --git a/rs/moq-uring/src/transport/local.rs b/rs/moq-uring/src/transport/local.rs index 0151df50605..bdae2cb556a 100644 --- a/rs/moq-uring/src/transport/local.rs +++ b/rs/moq-uring/src/transport/local.rs @@ -117,6 +117,10 @@ impl poll::Session for Local { fn stream_credit(&self, dir: moq::Dir) -> Option { self.0.stream_credit(dir) } + + fn export_keying_material(&self, label: &[u8], context: &[u8]) -> Option<[u8; 32]> { + self.0.export_keying_material(label, context) + } } impl poll::SendStream for Local { From 30ae988ebeabfd38a663291f7de49a9098313e7b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 23:16:02 -0800 Subject: [PATCH 03/10] test(net): l1's own broadcast fails over in the reference model Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 4 +++- js/net/src/lite/route_key.test.ts | 4 +++- rs/moq-net/tests/integration/routing_contracts/mod.rs | 8 ++++++-- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 9f412e07987..ba671156996 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1019,7 +1019,9 @@ Binding 1 exports with the TLS exporter (Section 7.5 of [RFC8446]), and binding The other bindings have no exporter, and an endpoint MUST NOT send the parameter on them. The exported material and the sender's side keep a proof from being replayed on another session or reflected back to its sender. -Either endpoint MAY send it. A receiver MUST close the session with a PROTOCOL_VIOLATION if the value is not 96 bytes, or if it can export keying material and the signature does not verify. A relay MUST NOT forward it. +Either endpoint MAY send it. A receiver MUST close the session with a PROTOCOL_VIOLATION if the value is not 96 bytes. +A receiver that relies on the key MUST verify the signature first, closing the session with a PROTOCOL_VIOLATION if it does not verify; without an exporter on the session, it cannot rely on the key. +A relay MUST NOT forward it. ## ANNOUNCE_REQUEST {#announce-request} diff --git a/js/net/src/lite/route_key.test.ts b/js/net/src/lite/route_key.test.ts index f817b8d478c..ffa5f460283 100644 --- a/js/net/src/lite/route_key.test.ts +++ b/js/net/src/lite/route_key.test.ts @@ -2,7 +2,9 @@ import { expect, test } from "bun:test"; import { proveRouteKey, sign } from "./route_key.ts"; // PKCS#8 v1 (RFC 8410) prefix of an Ed25519 key, up to its 32-byte seed. -const PKCS8_SEED_PREFIX = [0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]; +const PKCS8_SEED_PREFIX = [ + 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, +]; // Shared with rs/moq-net/src/route/proof.rs, so both sides sign the same transcript. const SEED = new Uint8Array(32).fill(1); diff --git a/rs/moq-net/tests/integration/routing_contracts/mod.rs b/rs/moq-net/tests/integration/routing_contracts/mod.rs index 6d342c4e3bd..6da8959fcdf 100644 --- a/rs/moq-net/tests/integration/routing_contracts/mod.rs +++ b/rs/moq-net/tests/integration/routing_contracts/mod.rs @@ -1203,6 +1203,10 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { // The local relay loses its direct uplink, and its own broadcast fails over through its sibling. net.disconnect(l1, c1); assert!(net.run()); + assert!(net.starved(c1, own), "the detour is longer than the lost uplink"); + // Its own set of sessions changed, so the origin advances its seqno. + net.bump(l1); + assert!(net.run()); assert_eq!(net.resolve(c1, "local/l1/x"), Some(own)); assert_eq!( net.request(c1, "local/l1/x", Forward::Pinned), @@ -1236,10 +1240,10 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { ); // A retracted identity leaves no alias behind. - assert_eq!(net.aliases(c1), 1); + assert_eq!(net.aliases(c1), 2, "the origin's and the local relay's own"); net.kill(origin); assert!(net.run()); - assert_eq!(net.aliases(c1), 0); + assert_eq!(net.aliases(c1), 1); } /// A local relay missing its `upstream` mark leaks CDN routes back to the CDN, From f8edf4191eb4cd5e82d78990dd5006bc62c941c5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 23:25:47 -0800 Subject: [PATCH 04/10] style: rustfmt Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/setup.rs | 9 +++++++-- rs/moq-net/src/model/mod.rs | 2 +- rs/moq-net/src/route/proof.rs | 17 +++++++++++++---- rs/moq-net/src/route/tests/routing.rs | 6 +++++- .../tests/integration/routing_contracts/mod.rs | 5 ++++- rs/moq-quic/src/crypto.rs | 2 +- rs/moq-tokio/src/quic/web/session.rs | 12 ++++++++++-- 7 files changed, 41 insertions(+), 12 deletions(-) diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 8f2b4e244ef..9b0d24fb6b7 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -726,7 +726,9 @@ mod tests { let mut short = vec![0x01, 0x08, 0x5f]; short.extend([0; 95]); let mut framed = Vec::new(); - Encoder::new(&mut framed, Version::Lite07.into()).varint(short.len() as u64).unwrap(); + Encoder::new(&mut framed, Version::Lite07.into()) + .varint(short.len() as u64) + .unwrap(); framed.extend(short); assert!(Setup::decode_slice(&framed, Version::Lite07).is_err()); } @@ -747,7 +749,10 @@ mod tests { assert_eq!(peer.route_key(), proven(true).route_key.map(|proof| proof.key)); // A server's own proof reflected back as the client's. - assert!(matches!(server().set(proven(false)), Err(crate::Error::ProtocolViolation))); + assert!(matches!( + server().set(proven(false)), + Err(crate::Error::ProtocolViolation) + )); // A transport that cannot export leaves the peer unproven, whatever it sends. let unbound = PeerSetup::new(false, crate::transport::Address::Setup); diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index b8d1c6920cd..2c2f4a304c1 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -53,7 +53,6 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { pub use super::follow::Following; - pub use crate::route::RouteKey; pub(crate) use super::origin_impl::HiddenWithheld; #[cfg(feature = "async")] pub(crate) use super::origin_impl::HiddenWithholding; @@ -64,6 +63,7 @@ pub mod origin { Config, Consumer, Cost, Driver, HopLimit, Link, Preference, Prepared, Producer, Publication, Request, Requesting, Requests, Route, Source, }; + pub use crate::route::RouteKey; } /// Subscribing to route (un)announcements from an origin. diff --git a/rs/moq-net/src/route/proof.rs b/rs/moq-net/src/route/proof.rs index 90b518cedba..7bc6fec6772 100644 --- a/rs/moq-net/src/route/proof.rs +++ b/rs/moq-net/src/route/proof.rs @@ -94,7 +94,9 @@ impl Proof { impl fmt::Debug for Proof { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Proof").field("key", &Hex(&self.key)).finish_non_exhaustive() + f.debug_struct("Proof") + .field("key", &Hex(&self.key)) + .finish_non_exhaustive() } } @@ -126,7 +128,8 @@ impl Transcript { /// Whether `proof` shows its key held by the side of this session `client` names. pub fn verify(&self, proof: &Proof, client: bool) -> bool { - PublicKey::new(&ED25519, &proof.key).is_ok_and(|key| key.verify(&self.message(client), &proof.signature).is_ok()) + PublicKey::new(&ED25519, &proof.key) + .is_ok_and(|key| key.verify(&self.message(client), &proof.signature).is_ok()) } } @@ -161,10 +164,16 @@ mod tests { let proof = transcript.prove(&RouteKey::generate(), true); assert!(transcript.verify(&proof, true)); assert!(!transcript.verify(&proof, false), "reflected to its sender"); - assert!(!Transcript::new([3; 32]).verify(&proof, true), "replayed on another session"); + assert!( + !Transcript::new([3; 32]).verify(&proof, true), + "replayed on another session" + ); let other = RouteKey::generate().public(); - assert!(!transcript.verify(&Proof { key: other, ..proof }, true), "claimed for another key"); + assert!( + !transcript.verify(&Proof { key: other, ..proof }, true), + "claimed for another key" + ); } #[test] diff --git a/rs/moq-net/src/route/tests/routing.rs b/rs/moq-net/src/route/tests/routing.rs index 68579209a42..d3ea706bf08 100644 --- a/rs/moq-net/src/route/tests/routing.rs +++ b/rs/moq-net/src/route/tests/routing.rs @@ -630,7 +630,11 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { sim.disconnect(l1, c1); assert!(sim.run()); - assert_eq!(next(&sim, c1, qualified(LOCAL.subject, 20)), Some(c2), "the local relay's own fails over"); + assert_eq!( + next(&sim, c1, qualified(LOCAL.subject, 20)), + Some(c2), + "the local relay's own fails over" + ); sim.connect(l1, c1); assert!(sim.run()); diff --git a/rs/moq-net/tests/integration/routing_contracts/mod.rs b/rs/moq-net/tests/integration/routing_contracts/mod.rs index 6da8959fcdf..5c341e1366d 100644 --- a/rs/moq-net/tests/integration/routing_contracts/mod.rs +++ b/rs/moq-net/tests/integration/routing_contracts/mod.rs @@ -1196,7 +1196,10 @@ fn scoped_delivery_through_two_uplinks_reaches_one_key() { assert_eq!(net.route(c1, key).and_then(|route| route.next), Some(l1)); assert_eq!(net.route(c2, key).and_then(|route| route.next), Some(l2)); let own = qualified(LOCAL.subject, 20); - assert!(net.route(c1, 20).is_none(), "the local relay's own identity is qualified"); + assert!( + net.route(c1, 20).is_none(), + "the local relay's own identity is qualified" + ); assert_eq!(net.route(c1, own).and_then(|route| route.next), Some(l1)); assert_eq!(net.resolve(c2, "local/l1/x"), Some(own)); diff --git a/rs/moq-quic/src/crypto.rs b/rs/moq-quic/src/crypto.rs index b703f86f16f..bf43d49322c 100644 --- a/rs/moq-quic/src/crypto.rs +++ b/rs/moq-quic/src/crypto.rs @@ -84,7 +84,7 @@ pub(crate) trait Session: Send + Sync + 'static { /// /// This function will fail, returning [ExportKeyingMaterialError], /// if the requested output length is too large. - fn export_keying_material( + fn export_keying_material( &self, output: &mut [u8], label: &[u8], diff --git a/rs/moq-tokio/src/quic/web/session.rs b/rs/moq-tokio/src/quic/web/session.rs index cf85a742186..902504d92df 100644 --- a/rs/moq-tokio/src/quic/web/session.rs +++ b/rs/moq-tokio/src/quic/web/session.rs @@ -1379,8 +1379,16 @@ mod tests { let (client, server) = sessions(framed, client, server).await; let exported = client.export_keying_material(b"label", b"context"); assert!(exported.is_some(), "framed: {framed}"); - assert_eq!(server.export_keying_material(b"label", b"context"), exported, "framed: {framed}"); - assert_ne!(client.export_keying_material(b"label", b""), exported, "framed: {framed}"); + assert_eq!( + server.export_keying_material(b"label", b"context"), + exported, + "framed: {framed}" + ); + assert_ne!( + client.export_keying_material(b"label", b""), + exported, + "framed: {framed}" + ); assert_eq!( client.conn.export_keying_material(b"label", b"context") == exported, !framed, From ca7c2b53fbcdeb22dd7bd0be1dd246b5b49b112b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 23:49:16 -0800 Subject: [PATCH 05/10] test(net): unwrap the fallible peer SETUP record in feature-gated tests Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 12 ++++++------ rs/moq-net/src/lite/subscriber.rs | 12 +++++++----- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 27869bb9e2c..0f4ae080373 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -9849,7 +9849,7 @@ mod tests { let track = broadcast.create_track("video", track::Info::timed()).unwrap(); let dynamic = track.requests(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { runtime: crate::time::sim(), @@ -9899,7 +9899,7 @@ mod tests { open.write_frame(crate::Timestamp::ZERO, b"a".to_vec()).unwrap(); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let publisher = Publisher::new(PublisherConfig { runtime: crate::time::sim(), @@ -10061,7 +10061,7 @@ mod tests { version, &estimate, ); - probe.shared.peer_setup.set(lite::Setup::default()); + probe.shared.peer_setup.set(lite::Setup::default()).unwrap(); let mut shared = probe.shared; Arc::get_mut(&mut shared).expect("one owner").origin = origin.consume(); let mut control = Control { @@ -10116,7 +10116,7 @@ mod tests { version, &estimate, ); - probe.shared.peer_setup.set(lite::Setup::default()); + probe.shared.peer_setup.set(lite::Setup::default()).unwrap(); let mut shared = probe.shared; Arc::get_mut(&mut shared).expect("one owner").origin = origin.consume(); let control = |stream| Control { @@ -10173,7 +10173,7 @@ mod tests { version, &estimate, ); - probe.shared.peer_setup.set(lite::Setup::default()); + probe.shared.peer_setup.set(lite::Setup::default()).unwrap(); let mut shared = probe.shared; Arc::get_mut(&mut shared).expect("one owner").origin = origin.consume(); let mut control = Control { @@ -10256,7 +10256,7 @@ mod tests { /// A publisher on a session with send groups. fn grouped_publisher(origin: origin::Consumer) -> (Publisher, crate::lite::test_transport::Log) { let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + peer_setup.set(crate::lite::Setup::default()).unwrap(); let (_, goaway) = crate::goaway::Handle::new(true); let session = ScriptedSession::new(Vec::new()).with_groups(); let log = session.log.clone(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 98f853c177b..53bef384d18 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -4119,10 +4119,12 @@ mod tests { } let session = crate::lite::test_transport::ScriptedSession::eof(script); let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup).offer_ietf(true); - peer_setup.set(lite::Setup { - ietf: true, - ..Default::default() - }); + peer_setup + .set(lite::Setup { + ietf: true, + ..Default::default() + }) + .unwrap(); let subscriber = Subscriber::new(SubscriberConfig { runtime: crate::time::sim(), session: crate::driver::Transport::new(session.clone()), @@ -5401,7 +5403,7 @@ mod tests { /// A subscriber on `version` over `session`, whose peer's SETUP was already read. fn pipelining(session: crate::driver::Transport, version: Version) -> Subscriber { let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(lite::Setup::default()); + peer_setup.set(lite::Setup::default()).unwrap(); Subscriber::new(SubscriberConfig { runtime: crate::time::sim(), session, From 1994aafe058c50b8277aae6d3c3b57f95a219713 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 23:58:21 -0800 Subject: [PATCH 06/10] fix(net): read an origin's config under one lock Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/origin.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 0b1fb7b67e8..b7da2090ce8 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -2223,13 +2223,14 @@ impl Producer { /// This origin's construction config. pub fn config(&self) -> Config { + let shared = self.shared.lock(); Config { hop: self.hop, max_hops: self.max_hops, pool: self.pool.clone(), cache_duration: self.cache_duration, - update_hold: self.shared.lock().update_hold, - route_key: self.route_key(), + update_hold: shared.update_hold, + route_key: shared.route_key.clone(), } } From 83af022e63cfe0bc450f535c5d4508f1873261ec Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 00:20:57 -0800 Subject: [PATCH 07/10] fix(net): close a refused accepted session with the refusal's code A server that failed to start an accepted session, such as on a client route key proof that does not verify, disarmed its close guard without closing the transport, so the client never learned why. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/server.rs | 49 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 8660fb95e34..84a7cea7793 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -816,9 +816,10 @@ impl Handshake { Some(at) => kio::clock::timeout_at(at, reply).await.map_err(|_| Error::Timeout)?, None => reply.await, }; - unanswered.answered(); - if let Err(err) = &res { - stats.end(err); + match &res { + Ok(_) => unanswered.answered(), + // Starting can refuse what the peer sent, such as a route key proof that fails. + Err(err) => unanswered.refuse(err), } res } @@ -847,6 +848,14 @@ impl Unanswered { fn answered(mut self) { self.0 = None; } + + /// Close the session with `err`'s wire code, so the peer learns why it was refused. + fn refuse(mut self, err: &Error) { + if let Some((mut session, version, stats)) = self.0.take() { + close(&mut session, err, Some(version)); + stats.end(err); + } + } } impl Drop for Unanswered { @@ -1040,6 +1049,9 @@ mod tests { fn poll_closed(&self, _waiter: &kio::Waiter) -> std::task::Poll { std::task::Poll::Pending } + fn export_keying_material(&self, _label: &[u8], _context: &[u8]) -> Option<[u8; 32]> { + Some([9; 32]) + } } #[derive(Clone, Default)] @@ -1479,6 +1491,37 @@ mod tests { assert_eq!(request.path(), "/closed"); } + /// A client whose route key proof fails is refused with PROTOCOL_VIOLATION, not left waiting. + #[kio::test] + async fn a_failed_route_key_proof_closes_with_its_code() { + let v = lite::Version::Lite07; + // Signed for another session's exported secret, so it fails against this one's. + let proof = crate::route::Transcript::new([1; 32]).prove(&crate::origin::RouteKey::generate(), true); + let mut setup = Vec::new(); + lite::DataType::Setup + .encode(&mut crate::coding::Encoder::new(&mut setup, v.into()), v) + .unwrap(); + lite::Setup { + route_key: Some(proof), + ..Default::default() + } + .encode(&mut crate::coding::Encoder::new(&mut setup, v.into()), v) + .unwrap(); + + let session = FakeSession::new(ALPN_LITE_07_WIP, [setup]); + let transport = session.clone(); + let request = Server::new() + .with_versions(Version::Lite(v).into()) + .accept_request(kio::clock::now(), session) + .await + .unwrap(); + assert!(matches!(request.ok().await, Err(Error::ProtocolViolation))); + assert_eq!( + transport.close_code(), + Some(Version::Lite(v).session_code(&SessionError::ProtocolViolation)) + ); + } + #[kio::test] async fn accepted_lite_setup_refuses_a_second_setup_stream() { let session = FakeSession::new(ALPN_LITE_05, [lite05_setup(None, None, None)]); From b6ac5aac0e24fb7c73b520fe806ee2a8c9ebf169 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 09:06:26 -0800 Subject: [PATCH 08/10] test(net): isolate unavailable browser key capability Co-Authored-By: GPT-6.1 Sol --- js/net/src/lite/route_key.test.ts | 37 +++++++++++++++++-------------- js/net/src/lite/route_key.ts | 5 +++-- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/js/net/src/lite/route_key.test.ts b/js/net/src/lite/route_key.test.ts index 6d15f491ec7..d782acdb8dd 100644 --- a/js/net/src/lite/route_key.test.ts +++ b/js/net/src/lite/route_key.test.ts @@ -1,4 +1,4 @@ -import { expect, spyOn, test } from "bun:test"; +import { expect, test } from "bun:test"; import { proveRouteKey, sign } from "./route_key.ts"; // PKCS#8 v1 (RFC 8410) prefix of an Ed25519 key, up to its 32-byte seed. @@ -66,20 +66,23 @@ test("a transport with an exporter proves one key per page", async () => { expect(labels).toEqual(["EXPORTER-moq-lite-route-key", "EXPORTER-moq-lite-route-key"]); }); - -test("unavailable Ed25519 leaves this page unproven across sessions", async () => { - // A separate module instance has its own page capability cache. - const moduleUrl = new URL("./route_key.ts?unavailable", import.meta.url).href; - const { proveRouteKey: prove } = await import(moduleUrl); - const generate = spyOn(crypto.subtle, "generateKey").mockRejectedValue(new Error("unavailable")); - try { - const transport = { - exportKeyingMaterial: async () => SECRET, - } as unknown as WebTransport; - expect(await prove(transport, true)).toBeUndefined(); - expect(await prove(transport, true)).toBeUndefined(); - expect(generate).toHaveBeenCalledTimes(1); - } finally { - generate.mockRestore(); - } +test("unavailable Ed25519 leaves this page unproven across sessions", () => { + // A child has its own page capability cache, independent of the successful proof tests. + const moduleUrl = new URL("./route_key.ts", import.meta.url).href; + const child = Bun.spawnSync([ + process.execPath, + "-e", + ` + import { strict as assert } from "node:assert"; + import { proveRouteKey } from ${JSON.stringify(moduleUrl)}; + let calls = 0; + crypto.subtle.generateKey = async () => { calls++; throw new Error("unavailable"); }; + const transport = { exportKeyingMaterial: async () => new Uint8Array(32) }; + assert.equal(await proveRouteKey(transport, true), undefined); + assert.equal(await proveRouteKey(transport, true), undefined); + assert.equal(calls, 1); + `, + ]); + expect(child.stderr.toString()).toBe(""); + expect(child.exitCode).toBe(0); }); diff --git a/js/net/src/lite/route_key.ts b/js/net/src/lite/route_key.ts index 5e2eda08aad..5c2c2fffa77 100644 --- a/js/net/src/lite/route_key.ts +++ b/js/net/src/lite/route_key.ts @@ -27,8 +27,9 @@ export async function proveRouteKey(transport: WebTransport, client: boolean): P if (typeof exporter !== "function") return undefined; const secret = new Uint8Array(await exporter.call(transport, EXPORTER_LABEL, new Uint8Array(), SECRET_SIZE)); // Select page capability once: unavailable Ed25519 leaves sessions unproven. - pageKey ??= (crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]) as Promise) - .catch(() => undefined); + pageKey ??= ( + crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]) as Promise + ).catch(() => undefined); const key = await pageKey; return key ? sign(key, secret, client) : undefined; } From 507d42581c337df7f6c8c89fdd96513552d7f29b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 09:15:57 -0800 Subject: [PATCH 09/10] docs(net): attach setup test comments to their cases Co-Authored-By: GPT-6.1 Sol --- rs/moq-net/src/lite/setup.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 9b0d24fb6b7..8ac3d5b27d8 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -709,8 +709,7 @@ mod tests { assert!(Setup::decode_slice(&valued, Version::Lite07).is_err()); } - /// The connection credential rides lite-07+, which an older version ignores like any - /// unknown parameter, and only an untyped, non-empty token can be sent. + /// Route key proofs are accepted only on lite-07 and must have the fixed wire size. #[test] fn route_key_is_lite07_only() { let transcript = crate::route::Transcript::new([2; 32]); @@ -760,6 +759,8 @@ mod tests { assert_eq!(unbound.route_key(), None); } + /// The connection credential rides lite-07+, which an older version ignores like any + /// unknown parameter, and only an untyped, non-empty token can be sent. #[test] fn token_is_lite07_only() { let token = crate::setup::Token { From 9795891f77adfdb6c7bcf139d4dbe0aaaf73ca80 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 5 Nov 2026 10:09:35 -0800 Subject: [PATCH 10/10] quest: date the SETUP route-key decision correctly in session.md Co-Authored-By: Claude Opus 5.5 --- quest/m1/cluster-routing/routes/session.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quest/m1/cluster-routing/routes/session.md b/quest/m1/cluster-routing/routes/session.md index 81a01568639..c44d1a8ffb7 100644 --- a/quest/m1/cluster-routing/routes/session.md +++ b/quest/m1/cluster-routing/routes/session.md @@ -96,7 +96,7 @@ epoch. The route layer's own origin-node identity, with its seqno and revision, stays separate ("keep administrative identity and broadcast epoch separate", in the epic). -Decided 2026-11-04 (maintainer, /quest-unblock): a scoped peer's identities +Decided 2026-11-05 (maintainer, /quest-plan): a scoped peer's identities are keyed by a route key the peer proves in its lite-07 SETUP: the session's `PeerSetup::route_key` once its SETUP arrives, and `None` for a peer that proved none. Relays set theirs with `--cluster-route-key`. Every identity a scoped, proven peer sends, its own included, is qualified @@ -105,7 +105,7 @@ key gets a per-session key. `Scope::qualify` still takes the key from the caller, so this quest does not wait on the proof. Options shown: - ✅ A route key the peer proves once per session in SETUP, before the lite-07 cut - (superseded 2026-11-05, maintainer, /quest-plan) + (2026-11-05, maintainer, /quest-plan; supersedes the per-announce proof option) - A route label carried in the grant (the earlier recommendation), with the proven key added after the cut - A per-session key now