diff --git a/Cargo.lock b/Cargo.lock index 128570fd142..e84829060b8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4790,6 +4790,7 @@ dependencies = [ "proptest", "rand 0.10.3", "rangemap", + "rind", "serde", "serde_json", "slab", @@ -4798,6 +4799,7 @@ dependencies = [ "tracing", "url", "workspace-hack", + "zeroize", ] [[package]] @@ -4915,6 +4917,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 346e45ca086..20b76f970c7 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 544b7c04030..4b7b403629e 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: @@ -922,6 +925,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). @@ -997,6 +1002,30 @@ 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)). +An endpoint MUST NOT send the parameter on a session that provides no exporter. +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. +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} 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. @@ -1936,6 +1965,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 d5aa87581aa..9c4ae23b308 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -24,6 +24,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"; @@ -38,6 +39,7 @@ import { hasGoaway, hasPadding, hasProbeRtt, + hasRouteKey, hasSetupStream, hasTrackStream, hasTracks, @@ -384,10 +386,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..d782acdb8dd --- /dev/null +++ b/js/net/src/lite/route_key.test.ts @@ -0,0 +1,88 @@ +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"]); +}); + +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 new file mode 100644 index 00000000000..5c2c2fffa77 --- /dev/null +++ b/js/net/src/lite/route_key.ts @@ -0,0 +1,52 @@ +/** + * 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)); + // Select page capability once: unavailable Ed25519 leaves sessions unproven. + pageKey ??= ( + crypto.subtle.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]) as Promise + ).catch(() => undefined); + const key = await pageKey; + return key ? sign(key, secret, client) : undefined; +} + +/** 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 91c3310693d..228e7266344 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -657,6 +657,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..625a899d88a 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 @@ -498,9 +500,10 @@ benchmarks. ## Required +- [Scoped peers prove a route key](/quest/m1/cluster-routing/routes/proof.md) - records the session proof decision and implementation + - [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 index 3d39fee6050..26c62d66f01 100644 --- a/quest/m1/cluster-routing/routes/proof.md +++ b/quest/m1/cluster-routing/routes/proof.md @@ -2,73 +2,49 @@ ## 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. +A lite-07 peer proves a route key once per session in SETUP. A relay files +every identity a scoped, proven peer sends, its own included, under +H(domain, proven key, id). Relays sharing a key file fail over as one; +unscoped peers stay bare and unproven scoped peers get a per-session key. +Proof production and verification are implemented by this PR; filing belongs +to [Route session integration](/quest/m1/cluster-routing/routes/session.md). ## 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. +✅ Decided 2026-11-05 (maintainer, /quest-plan): prove the route key once per +session in lite-07 SETUP parameter 0x8, without a nonce, and keep the node's +own identity a random u64. This supersedes the 2026-11-04 bullets requiring +proof per announce stream, a nonce in ANNOUNCE_REQUEST, a proof in +ANNOUNCE_OK, and H(key, per-process salt) for the own identity. The signature +already covers TLS exporter output unique to the session, so a nonce adds +nothing. A session has one key, so proving it once in SETUP costs less than +per announce stream. A peer cannot verify H(key, per-process salt), making +it equivalent to random. ROUTE retains its u64 identity. + +The other five choices in the PR remain as made: + +- The own identity stays a fresh random u64, as decided above. +- moq-net calls rind directly; moq-crypto's sign feature depends on moq-net, + so moving one key type into another crate adds unnecessary machinery. +- The key lives on origin::Config. The relay's --cluster-route-key file + covers accepted and dialed sessions; moq-tokio needs no additional flag. +- qmux currently provides no exporter and proves nothing. This is an + implementation limitation, not a prohibition on TLS bindings. +- Browsers prove a per-page WebCrypto key when their transport exposes + exportKeyingMaterial, without adding a public JS API. + +The 2026-11-04 choices to ship before the lite-07 cut, share a relay key +file, qualify the proven peer's own identity, and retain u64 ROUTE identities +stand. A missing key file is generated; without a configured file, a relay +generates a fresh key on startup. + +The signed transcript is ASCII `moq-lite route key`, one role byte (0 client, +1 server), and 32 bytes from exporter label `EXPORTER-moq-lite-route-key` +with empty context. The proof is the 32-byte public key plus 64-byte +signature. No ANNOUNCE_OK proof body is needed by this draft or implementation; +[lite-07 route wire](https://github.com/moq-dev/moq/pull/7764) owns its message changes. ## 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 +- [Route session integration](/quest/m1/cluster-routing/routes/session.md) - files identities under the proven key +- [lite-07 route wire](/quest/m1/cluster-routing/routes/wire.md) - coordinates announce messages diff --git a/quest/m1/cluster-routing/routes/session.md b/quest/m1/cluster-routing/routes/session.md index ee92c083059..c44d1a8ffb7 100644 --- a/quest/m1/cluster-routing/routes/session.md +++ b/quest/m1/cluster-routing/routes/session.md @@ -96,15 +96,16 @@ 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 -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 +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 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: -- ✅ A route key the peer proves once per announce stream, before the lite-07 cut +- ✅ A route key the peer proves once per session in SETUP, before the lite-07 cut + (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 diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index c9c7cd2b2e4..509dac6eadc 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 0d6afe92b7a..c61ed607bde 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -42,11 +42,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 80a90640232..2b4b39be9b8 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. + ### Group batch operations and `poll_next_frame` are crate-private ([#7874](https://github.com/moq-dev/moq/pull/7874)) Read a frame in chunks with the async `group::Consumer::next_frame`, or read whole frames with `poll_read_frame` from a poll loop. diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index bbc75ffcf02..14f107bcfb3 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -331,6 +331,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 f0136e0c90c..e9cf3c1f39f 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -8564,7 +8564,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 { @@ -9149,7 +9149,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(), @@ -9276,7 +9276,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(), @@ -9339,7 +9339,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(), @@ -9397,7 +9397,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(), @@ -9544,7 +9544,7 @@ mod tests { } let peer_setup = crate::lite::PeerSetup::new(false, crate::transport::Address::Setup); - peer_setup.set(crate::lite::Setup::default()); + let _ = peer_setup.set(crate::lite::Setup::default()); let (_, goaway) = crate::goaway::Handle::new(true); let log = Log::default(); let publisher = Publisher::new(PublisherConfig { @@ -9674,7 +9674,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 { @@ -9803,7 +9803,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 { @@ -10055,7 +10055,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(), @@ -10105,7 +10105,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(), @@ -10267,7 +10267,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 { @@ -10322,7 +10322,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 { @@ -10379,7 +10379,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 { @@ -10462,7 +10462,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/session.rs b/rs/moq-net/src/lite/session.rs index 2d8a73d43f3..fc105f68d68 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -263,6 +263,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. @@ -303,6 +319,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 @@ -315,7 +332,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..8ac3d5b27d8 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. @@ -650,6 +709,56 @@ mod tests { assert!(Setup::decode_slice(&valued, Version::Lite07).is_err()); } + /// 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]); + 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); + } + /// 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] diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index a54e95cd82e..ae0924eff6b 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() @@ -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, 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 c2eb91bd28a..eec7b20bbdf 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -65,6 +65,8 @@ pub mod origin { Config, Consumer, Cost, Driver, HopLimit, Link, Preference, Prepared, Producer, Publication, Request, Requesting, Requests, Route, Source, }; + pub use crate::route::RouteKey; + // Relay-level: every route change, for forwarding and stats. Apps read // `announce` and `follow` instead. #[doc(hidden)] diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index c38abc84bb4..e1bc2bdd0c9 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -107,6 +107,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 @@ -163,6 +168,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, @@ -2138,7 +2144,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, @@ -2218,12 +2224,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, + update_hold: shared.update_hold, + route_key: shared.route_key.clone(), } } @@ -2232,6 +2240,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 { @@ -2252,7 +2266,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(), @@ -5270,6 +5284,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. @@ -5308,9 +5324,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, @@ -6635,6 +6652,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..7bc6fec6772 --- /dev/null +++ b/rs/moq-net/src/route/proof.rs @@ -0,0 +1,186 @@ +//! 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..d3ea706bf08 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,16 @@ 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 b1b8e7249dc..994db90172e 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -198,6 +198,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() @@ -1105,7 +1107,6 @@ struct Answer { /// The deadline's timer, armed once the reply first waits. timer: Option, unanswered: Unanswered, - stats: stats::Session, /// When to give up on the peer taking the reply. deadline: Option, /// The request being answered, emptied of what the start took. @@ -1127,7 +1128,6 @@ impl Answer { reply: None, timer: None, unanswered: Unanswered(Some((session, version, stats.clone()))), - stats, deadline, handshake, } @@ -1143,9 +1143,9 @@ impl Answer { drop(std::mem::replace(&mut self.unanswered, Unanswered(None))); return Poll::Ready(Err(Error::Timeout)); }; - self.unanswered.0 = None; - if let Err(err) = &res { - self.stats.end(err); + match &res { + Ok(_) => self.unanswered.answered(), + Err(err) => self.unanswered.refuse(err), } Poll::Ready(res) } @@ -1197,6 +1197,20 @@ impl Answer { /// took too long. struct Unanswered(Option<(Transport, Version, stats::Session)>); +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 { fn drop(&mut self) { if let Some((mut session, version, stats)) = self.0.take() { @@ -1415,6 +1429,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)] @@ -1484,6 +1501,7 @@ mod tests { token: None, ietf: false, implementation: None, + route_key: None, } .encode(&mut crate::coding::Encoder::new(&mut buf, v.into()), v) .unwrap(); @@ -1874,6 +1892,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)]); 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 d37c209c833..27854c1e2d0 100644 --- a/rs/moq-net/src/transport/boxed.rs +++ b/rs/moq-net/src/transport/boxed.rs @@ -349,6 +349,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 { @@ -488,6 +489,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 { @@ -676,6 +681,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..5c341e1366d 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,38 @@ 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!(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), + 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), @@ -1212,10 +1243,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, 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 f68fc7d416a..8feeb704302 100644 --- a/rs/moq-quic/src/connection/mod.rs +++ b/rs/moq-quic/src/connection/mod.rs @@ -1571,16 +1571,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..bf43d49322c 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,7 +84,6 @@ 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( &self, output: &mut [u8], diff --git a/rs/moq-quic/src/tests/mod.rs b/rs/moq-quic/src/tests/mod.rs index d3e5e6c9362..b6c7c19f826 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 8fd61d1515c..1e8372107a0 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 = ["async", "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 60eee46dabe..8fe00749305 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 2c57bc7c3df..6cec2479b92 100644 --- a/rs/moq-tokio/src/quic/driver/connection.rs +++ b/rs/moq-tokio/src/quic/driver/connection.rs @@ -476,6 +476,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 47b2b6f25ec..b81799c783c 100644 --- a/rs/moq-tokio/src/quic/web/session.rs +++ b/rs/moq-tokio/src/quic/web/session.rs @@ -1050,6 +1050,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"))] @@ -1318,6 +1343,36 @@ 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 144c6ebc1c2..11fc1800a66 100644 --- a/rs/moq-uring/src/quic/driver/connection.rs +++ b/rs/moq-uring/src/quic/driver/connection.rs @@ -283,6 +283,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 aea49b43106..fcde2f336b6 100644 --- a/rs/moq-uring/src/quic/web.rs +++ b/rs/moq-uring/src/quic/web.rs @@ -834,6 +834,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 {