From d675c5e7e517bb05fe955c314c095ae1b5c97834 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:09:49 -0700 Subject: [PATCH 01/10] chore(quest): claim quest/m2/mesh/sign.md Quest-Claim: f1165cecb3e4eb5f From 58cc3d7145d9b54c1022c55c19c85bed460e1116 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:23:01 -0700 Subject: [PATCH 02/10] feat(sign): Rust per-frame Ed25519 signing crate and moq-sign-00 vectors Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 17 ++ Cargo.toml | 1 + drafts/moq-sign-00.json | 278 +++++++++++++++++++++++++++ drafts/moq-sign-00.ts | 270 ++++++++++++++++++++++++++ rs/moq-sign/Cargo.toml | 36 ++++ rs/moq-sign/benches/sign.rs | 85 +++++++++ rs/moq-sign/src/broadcast.rs | 126 +++++++++++++ rs/moq-sign/src/error.rs | 19 ++ rs/moq-sign/src/group.rs | 153 +++++++++++++++ rs/moq-sign/src/key.rs | 182 ++++++++++++++++++ rs/moq-sign/src/lib.rs | 33 ++++ rs/moq-sign/src/scope.rs | 62 ++++++ rs/moq-sign/src/tests.rs | 354 +++++++++++++++++++++++++++++++++++ rs/moq-sign/src/track.rs | 167 +++++++++++++++++ sh/drafts/check.sh | 2 +- 15 files changed, 1784 insertions(+), 1 deletion(-) create mode 100644 drafts/moq-sign-00.json create mode 100644 drafts/moq-sign-00.ts create mode 100644 rs/moq-sign/Cargo.toml create mode 100644 rs/moq-sign/benches/sign.rs create mode 100644 rs/moq-sign/src/broadcast.rs create mode 100644 rs/moq-sign/src/error.rs create mode 100644 rs/moq-sign/src/group.rs create mode 100644 rs/moq-sign/src/key.rs create mode 100644 rs/moq-sign/src/lib.rs create mode 100644 rs/moq-sign/src/scope.rs create mode 100644 rs/moq-sign/src/tests.rs create mode 100644 rs/moq-sign/src/track.rs diff --git a/Cargo.lock b/Cargo.lock index d43faae9d44..726422dc6cd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5788,6 +5788,23 @@ dependencies = [ "toml 1.1.6+spec-1.1.0", ] +[[package]] +name = "moq-sign" +version = "0.0.1" +dependencies = [ + "aws-lc-rs", + "bytes", + "criterion", + "hex", + "kio 0.6.2", + "moq-net", + "serde_json", + "tempfile", + "thiserror 2.0.21", + "tokio", + "zeroize", +] + [[package]] name = "moq-sock" version = "0.2.0" diff --git a/Cargo.toml b/Cargo.toml index c96c253118d..ff0ed9f1b7d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -38,6 +38,7 @@ default-members = [ "rs/moq-rtsp", "rs/moq-scene", "rs/moq-shaper", + "rs/moq-sign", "rs/moq-sock", "rs/moq-srt", "rs/moq-stats", diff --git a/drafts/moq-sign-00.json b/drafts/moq-sign-00.json new file mode 100644 index 00000000000..f8f2759fee5 --- /dev/null +++ b/drafts/moq-sign-00.json @@ -0,0 +1,278 @@ +{ + "profile": "moq-sign-00", + "constants": { + "label": "6d6f712d7369676e2d3030", + "key_len": 32, + "signature_len": 64 + }, + "keys": [ + { + "id": "rfc8032-test-1", + "seed": "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60", + "public": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a" + }, + { + "id": "test", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" + }, + { + "id": "other", + "seed": "6d6f712d7369676e2d3030206f74686572207365656421212121212121212121", + "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758" + } + ], + "frames": [ + { + "id": "base", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000168656c6c6f", + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a" + }, + { + "id": "empty-payload", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 0, + "payload": "", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d00000000000000030000000000000000", + "body": "1e0ed358f8c4053edd585a3feb8eca2755f3b232d266b66df0b23ea5b843fec56d8af410d20d495df22f1b0cd7cd0118bd160edfd1ec33972e5738ab6aa58404" + }, + { + "id": "group-above-u32", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 1099511627781, + "frame": 0, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000010000000005000000000000000068656c6c6f", + "body": "68656c6c6f36ba11c14dd79078cc547ac35257552140d416bbd8eec0f31a67fa0e4da9d021ac43125ea0d8fb6de5d0c6376ce3529c9b50270dfffbb661559dd42ea1ec1309" + }, + { + "id": "frame-above-u32", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 4294967296, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000010000000068656c6c6f", + "body": "68656c6c6f96b21176ed8aa2cd6ea943a3601e60344ab2ff9ede5c1d3ec22b05c237c28946ac08f2619ca5669c3cb76051e1b0df928f8c1a07b976d1d6f5cf8801701fd404" + }, + { + "id": "max-u53", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 9007199254740991, + "frame": 1, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d001fffffffffffff000000000000000168656c6c6f", + "body": "68656c6c6f42daf8ec76ab76aff7b07fbe664504c0dfd9ad853383a6325b894c6bf6f413e60c14bda18b0e0f2635cf3677bc4f0e0d5fa4170b57503a89b73d587b0b06a709" + }, + { + "id": "empty-path-utf8-track", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "café", + "group": 3, + "frame": 1, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d30300000000000000000000000000000002430313961326233632d346435652d376636302d386131622d3263336434653566366137620000000000000005636166c3a90000000000000003000000000000000168656c6c6f", + "body": "68656c6c6f34c19a5af0957aee4440e37197ab2455b10b16e6f7c106fbf31901565efd651597856b6d08402e7adc6b394a5c2b28236348c77a84fa2419136b2bce2a2f5709" + }, + { + "id": "other-key", + "seed": "6d6f712d7369676e2d3030206f74686572207365656421212121212121212121", + "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000168656c6c6f", + "body": "68656c6c6fc70597b8ca756f8928014f3b72b05bc70dfe6894ee6f071a9cf11e61c15fddcf4713c8216d3952c8eda963348295f3f94f28bac7eb83e04711ca29c2cce6cb00" + } + ], + "negative": [ + { + "id": "relocated-path", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/http", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "relocated-epoch", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7c", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "relocated-track", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream2", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "relocated-group", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 4, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "relocated-frame", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 0, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "shifted-boundary", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/sshs", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "tream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "wrong-key", + "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "tampered-payload", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "69656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "error": "signature" + }, + { + "id": "tampered-signature", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0b", + "error": "signature" + }, + { + "id": "appended-byte", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a00", + "error": "signature" + }, + { + "id": "truncated", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189", + "error": "signature" + }, + { + "id": "empty", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "body": "", + "error": "signature" + } + ], + "invalid_ids": [ + { + "id": "uppercase", + "text": "4030B2C68C2E6CC51C96DAE4B44CC53C07471BA7D7731EB7368FE8F807ECB5CE" + }, + { + "id": "short", + "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5c" + }, + { + "id": "long", + "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce0" + }, + { + "id": "non-hex", + "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5cg" + }, + { + "id": "prefixed", + "text": "0x30b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" + }, + { + "id": "empty", + "text": "" + } + ] +} diff --git a/drafts/moq-sign-00.ts b/drafts/moq-sign-00.ts new file mode 100644 index 00000000000..2d37e8dd835 --- /dev/null +++ b/drafts/moq-sign-00.ts @@ -0,0 +1,270 @@ +#!/usr/bin/env bun +/** + * moq-sign-00 primitives and known-answer vectors. + * + * `bun drafts/moq-sign-00.ts` verifies drafts/moq-sign-00.json against this + * file. `bun drafts/moq-sign-00.ts --write` regenerates the JSON. + * + * This is the language-neutral contract, not the TypeScript signing core: it + * does not wrap tracks or groups. + */ + +import { readFileSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +export const PROFILE = "moq-sign-00"; +export const LABEL = utf8(PROFILE); +export const KEY_LEN = 32; +export const SIGNATURE_LEN = 64; + +// The RFC 8032 PKCS #8 wrapper for a raw Ed25519 seed. +const PKCS8_PREFIX = hex("302e020100300506032b657004220420"); +const ED25519 = { name: "Ed25519" } as const; + +export class ProfileError extends Error { + readonly code: string; + constructor(code: string) { + super(code); + this.code = code; + } +} + +/** One signed frame's identity. */ +export type Identity = { + path: string; + epoch: string; + track: string; + group: bigint; + frame: bigint; +}; + +function utf8(text: string): Uint8Array { + return new TextEncoder().encode(text); +} + +function hex(text: string): Uint8Array { + return Uint8Array.from(text.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16)); +} + +function toHex(bytes: Uint8Array): string { + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); +} + +function concat(...parts: Uint8Array[]): Uint8Array { + const out = new Uint8Array(parts.reduce((sum, part) => sum + part.byteLength, 0)); + let offset = 0; + for (const part of parts) { + out.set(part, offset); + offset += part.byteLength; + } + return out; +} + +function u64(value: bigint): Uint8Array { + const out = new Uint8Array(8); + new DataView(out.buffer).setBigUint64(0, value); + return out; +} + +function bytes(text: string): Uint8Array { + const data = utf8(text); + return concat(u64(BigInt(data.byteLength)), data); +} + +/** The message a frame's signature covers. */ +export function message(identity: Identity, payload: Uint8Array): Uint8Array { + return concat( + LABEL, + bytes(identity.path), + bytes(identity.epoch), + bytes(identity.track), + u64(identity.group), + u64(identity.frame), + payload, + ); +} + +/** Parse an endpoint ID: exactly 64 lowercase hex characters. */ +export function parseKey(text: string): Uint8Array { + if (!/^[0-9a-f]{64}$/.test(text)) throw new ProfileError("key"); + return hex(text); +} + +async function privateKey(seed: Uint8Array): Promise { + return crypto.subtle.importKey("pkcs8", concat(PKCS8_PREFIX, seed), ED25519, true, ["sign"]); +} + +/** The public key, and endpoint ID, of a 32-byte seed. */ +export async function publicKey(seed: Uint8Array): Promise> { + const jwk = await crypto.subtle.exportKey("jwk", await privateKey(seed)); + return Uint8Array.from(atob((jwk.x ?? "").replaceAll("-", "+").replaceAll("_", "/")), (c) => c.charCodeAt(0)); +} + +/** The frame body: `payload || signature`. */ +export async function sign( + seed: Uint8Array, + identity: Identity, + payload: Uint8Array, +): Promise> { + const signature = await crypto.subtle.sign(ED25519, await privateKey(seed), message(identity, payload)); + return concat(payload, new Uint8Array(signature)); +} + +/** The payload of a body whose signature verifies under `key` at `identity`. */ +export async function verify( + key: Uint8Array, + identity: Identity, + body: Uint8Array, +): Promise> { + if (body.byteLength < SIGNATURE_LEN) throw new ProfileError("signature"); + const split = body.byteLength - SIGNATURE_LEN; + const payload = body.slice(0, split); + const verifier = await crypto.subtle.importKey("raw", key, ED25519, false, ["verify"]); + if (!(await crypto.subtle.verify(ED25519, verifier, body.slice(split), message(identity, payload)))) { + throw new ProfileError("signature"); + } + return payload; +} + +// RFC 8032 Section 7.1 TEST 1, so the key derivation is checked against an outside answer. +const RFC8032_SEED = "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60"; +const RFC8032_PUBLIC = "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a"; +const SEED = toHex(utf8("moq-sign-00 test seed!!!!!!!!!!!")); +const OTHER_SEED = toHex(utf8("moq-sign-00 other seed!!!!!!!!!!")); +const EPOCH = "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b"; +const OTHER_EPOCH = "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7c"; + +type IdentityJson = { path: string; epoch: string; track: string; group: number; frame: number }; + +function identityJson(identity: Identity): IdentityJson { + return { ...identity, group: Number(identity.group), frame: Number(identity.frame) }; +} + +function parseIdentity(row: IdentityJson): Identity { + return { ...row, group: BigInt(row.group), frame: BigInt(row.frame) }; +} + +async function frameVector(id: string, seed: string, identity: Identity, payload: Uint8Array) { + return { + id, + seed, + public: toHex(await publicKey(hex(seed))), + ...identityJson(identity), + payload: toHex(payload), + message: toHex(message(identity, payload)), + body: toHex(await sign(hex(seed), identity, payload)), + }; +} + +async function generate() { + const base: Identity = { path: "mesh/node/ssh", epoch: EPOCH, track: "stream", group: 3n, frame: 1n }; + const payload = utf8("hello"); + const body = await sign(hex(SEED), base, payload); + const key = toHex(await publicKey(hex(SEED))); + const negative = (id: string, identity: Identity, frameBody: Uint8Array, publicHex = key) => ({ + id, + public: publicHex, + ...identityJson(identity), + body: toHex(frameBody), + error: "signature", + }); + const flipped = (index: number) => { + const out = body.slice(); + out[index] ^= 0x01; + return out; + }; + + return { + profile: PROFILE, + constants: { label: toHex(LABEL), key_len: KEY_LEN, signature_len: SIGNATURE_LEN }, + keys: [ + { id: "rfc8032-test-1", seed: RFC8032_SEED, public: RFC8032_PUBLIC }, + { id: "test", seed: SEED, public: key }, + { id: "other", seed: OTHER_SEED, public: toHex(await publicKey(hex(OTHER_SEED))) }, + ], + frames: [ + await frameVector("base", SEED, base, payload), + await frameVector("empty-payload", SEED, { ...base, frame: 0n }, new Uint8Array()), + await frameVector("group-above-u32", SEED, { ...base, group: 2n ** 40n + 5n, frame: 0n }, payload), + await frameVector("frame-above-u32", SEED, { ...base, frame: 2n ** 32n }, payload), + await frameVector("max-u53", SEED, { ...base, group: 2n ** 53n - 1n }, payload), + await frameVector("empty-path-utf8-track", SEED, { ...base, path: "", track: "café" }, payload), + await frameVector("other-key", OTHER_SEED, base, payload), + ], + negative: [ + negative("relocated-path", { ...base, path: "mesh/node/http" }, body), + negative("relocated-epoch", { ...base, epoch: OTHER_EPOCH }, body), + negative("relocated-track", { ...base, track: "stream2" }, body), + negative("relocated-group", { ...base, group: 4n }, body), + negative("relocated-frame", { ...base, frame: 0n }, body), + // Shifting a byte between the path and track keeps their concatenation equal. + negative("shifted-boundary", { ...base, path: "mesh/node/sshs", track: "tream" }, body), + negative("wrong-key", base, body, toHex(await publicKey(hex(OTHER_SEED)))), + negative("tampered-payload", base, flipped(0)), + negative("tampered-signature", base, flipped(body.byteLength - 1)), + negative("appended-byte", base, concat(body, new Uint8Array([0]))), + negative("truncated", base, body.slice(0, SIGNATURE_LEN - 1)), + negative("empty", base, new Uint8Array()), + ], + invalid_ids: [ + { id: "uppercase", text: key.toUpperCase() }, + { id: "short", text: key.slice(0, 63) }, + { id: "long", text: `${key}0` }, + { id: "non-hex", text: `${key.slice(0, 63)}g` }, + { id: "prefixed", text: `0x${key.slice(2)}` }, + { id: "empty", text: "" }, + ], + }; +} + +async function check(doc: Awaited>): Promise { + for (const row of doc.keys) { + assertEqual(`${row.id} public`, toHex(await publicKey(hex(row.seed))), row.public); + assertEqual(`${row.id} parse`, toHex(parseKey(row.public)), row.public); + } + for (const row of doc.frames) { + const identity = parseIdentity(row); + assertEqual(`${row.id} message`, toHex(message(identity, hex(row.payload))), row.message); + assertEqual(`${row.id} body`, toHex(await sign(hex(row.seed), identity, hex(row.payload))), row.body); + assertEqual(`${row.id} verify`, toHex(await verify(hex(row.public), identity, hex(row.body))), row.payload); + } + for (const row of doc.negative) { + await expectError(row.error, () => verify(hex(row.public), parseIdentity(row), hex(row.body))); + } + for (const row of doc.invalid_ids) { + await expectError("key", () => parseKey(row.text)); + } +} + +function assertEqual(label: string, actual: string, expected: string): void { + if (actual !== expected) throw new Error(`${label}: ${actual} != ${expected}`); +} + +async function expectError(code: string, fn: () => unknown | Promise): Promise { + try { + await fn(); + } catch (error) { + if (error instanceof ProfileError && error.code === code) return; + throw error; + } + throw new Error(`expected ${code}`); +} + +async function main(): Promise { + const generated = await generate(); + const jsonPath = join(dirname(fileURLToPath(import.meta.url)), "moq-sign-00.json"); + if (process.argv.includes("--write")) writeFileSync(jsonPath, `${JSON.stringify(generated, null, "\t")}\n`); + const onDisk = JSON.parse(readFileSync(jsonPath, "utf8")) as Awaited>; + await check(onDisk); + if (JSON.stringify(onDisk) !== JSON.stringify(generated)) { + throw new Error("drafts/moq-sign-00.json is stale; run bun drafts/moq-sign-00.ts --write"); + } + console.log( + `moq-sign-00: ${onDisk.keys.length} key, ${onDisk.frames.length} frame, ${onDisk.negative.length} negative, ${onDisk.invalid_ids.length} invalid ID vectors`, + ); +} + +if (import.meta.main) { + await main(); +} diff --git a/rs/moq-sign/Cargo.toml b/rs/moq-sign/Cargo.toml new file mode 100644 index 00000000000..58eeed033de --- /dev/null +++ b/rs/moq-sign/Cargo.toml @@ -0,0 +1,36 @@ +[package] +publish = false +name = "moq-sign" +description = "Per-frame Ed25519 signatures for MoQ broadcasts, so relays proxy without forging content." +authors = ["Luke Curley "] +repository = "https://github.com/moq-dev/moq" +license = "MIT OR Apache-2.0" + +version = "0.0.1" +edition = "2024" +rust-version.workspace = true + +keywords = ["quic", "http3", "webtransport", "signature", "live"] +categories = ["cryptography", "multimedia", "network-programming"] + +[dependencies] +aws-lc-rs = { workspace = true } +bytes = { workspace = true } +hex = { workspace = true } +kio = { workspace = true } +moq-net = { workspace = true } +thiserror = { workspace = true } +zeroize = { workspace = true } + +[dev-dependencies] +criterion = { workspace = true } +serde_json = { workspace = true } +tempfile = { workspace = true } +tokio = { workspace = true, features = ["macros", "rt", "test-util"] } + +[[bench]] +name = "sign" +harness = false + +[lints] +workspace = true diff --git a/rs/moq-sign/benches/sign.rs b/rs/moq-sign/benches/sign.rs new file mode 100644 index 00000000000..3dc29f72c00 --- /dev/null +++ b/rs/moq-sign/benches/sign.rs @@ -0,0 +1,85 @@ +//! Ed25519 cost per grouped frame through the public API: signing on write, verifying on read. +//! +//! Run with `cargo bench -p moq-sign`. + +use std::hint::black_box; +use std::task::Poll; +use std::time::Duration; + +use criterion::{Criterion, Throughput, criterion_group, criterion_main}; +use moq_sign::{SecretKey, broadcast}; + +fn produce(key: &SecretKey) -> (moq_sign::track::Producer, moq_net::broadcast::Producer) { + // A zero max age keeps only the newest group cached. + let info = moq_net::track::Info::default().with_max_age(Duration::ZERO); + let inner = moq_net::broadcast::Info::new().produce(); + let path = moq_net::Path::new("bench").unwrap(); + let track = broadcast::Producer::new(inner.clone(), key.clone(), path) + .create_track("stream", info) + .unwrap(); + (track, inner) +} + +/// A signed track published on an origin and a verifying subscription to it. +async fn roundtrip( + key: &SecretKey, +) -> ( + moq_sign::track::Producer, + moq_sign::track::Consumer, + moq_net::origin::Publication, +) { + let (origin, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::default()); + tokio::spawn(moq_net::time::run(driver)); + let path = moq_net::Path::new("bench").unwrap(); + let publication = origin.create_broadcast(&path).unwrap(); + let signed = broadcast::Producer::new(publication.broadcast().clone(), key.clone(), path.clone()); + let info = moq_net::track::Info::default().with_max_age(Duration::ZERO); + let track = signed.create_track("stream", info).unwrap(); + publication + .announce(moq_net::origin::Route::default().with_epoch(signed.epoch().clone())) + .unwrap(); + let inner = origin.consume().request_broadcast(&path, None).await.unwrap(); + let consumer = broadcast::Consumer::new(inner, key.public(), path).unwrap(); + let subscription = moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(60)); + let consumer = consumer.subscribe("stream", subscription).unwrap().await.unwrap(); + (track, consumer, publication) +} + +fn bench_sign(c: &mut Criterion) { + let key = SecretKey::generate(); + + let mut group = c.benchmark_group("sign"); + for size in [1024usize, 64 * 1024] { + let payload = vec![0u8; size]; + group.throughput(Throughput::Bytes(size as u64)); + group.bench_function(format!("write_{}k", size / 1024), |b| { + let (producer, _inner) = produce(&key); + b.iter(|| { + let mut group = producer.append_group().unwrap(); + group.write_frame(None, black_box(&payload)).unwrap(); + group.finish().unwrap(); + }); + }); + group.bench_function(format!("roundtrip_{}k", size / 1024), |b| { + let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap(); + let (producer, mut consumer, _origin) = runtime.block_on(roundtrip(&key)); + let waiter = kio::Waiter::noop(); + b.iter(|| { + let mut group = producer.append_group().unwrap(); + group.write_frame(None, black_box(&payload)).unwrap(); + group.finish().unwrap(); + let Poll::Ready(Ok(Some(mut group))) = consumer.poll_recv_group(&waiter) else { + panic!("the group is delivered in-process"); + }; + let Poll::Ready(Ok(Some(frame))) = group.poll_read_frame(&waiter) else { + panic!("the frame verifies"); + }; + black_box(frame); + }); + }); + } + group.finish(); +} + +criterion_group!(benches, bench_sign); +criterion_main!(benches); diff --git a/rs/moq-sign/src/broadcast.rs b/rs/moq-sign/src/broadcast.rs new file mode 100644 index 00000000000..da48de52e14 --- /dev/null +++ b/rs/moq-sign/src/broadcast.rs @@ -0,0 +1,126 @@ +//! Signed broadcasts, named by the application path both ends agree on. +//! +//! A relay may mount a broadcast under another prefix, so the path a signature binds is the one +//! the application names, never the path the transport reports. + +use crate::error::{Error, Result}; +use crate::key::{PublicKey, SecretKey}; +use crate::scope::Scope; +use crate::track; + +/// The publishing side of a signed broadcast. +/// +/// Mints a fresh epoch, so a restart never signs a sequence an earlier instance already signed. +/// Announce the wrapped broadcast with [`Self::epoch`] on its route. +#[derive(Clone)] +pub struct Producer { + inner: moq_net::broadcast::Producer, + key: SecretKey, + path: moq_net::Path, + epoch: moq_net::Epoch, +} + +impl Producer { + /// Sign `inner` with `key`, as the broadcast at application path `path`. + pub fn new(inner: moq_net::broadcast::Producer, key: SecretKey, path: moq_net::Path) -> Self { + Self { + inner, + key, + path, + epoch: moq_net::Epoch::mint(), + } + } + + /// The epoch this instance signs under, to announce on the broadcast's route. + pub fn epoch(&self) -> &moq_net::Epoch { + &self.epoch + } + + /// Create a track whose frames are signed. + /// + /// # Errors + /// + /// A net error if the broadcast already holds the name or has ended. + pub fn create_track( + &self, + name: &str, + info: impl Into>, + ) -> Result { + let inner = self.inner.create_track(name, info)?; + let scope = Scope::new(&self.path, &self.epoch, name); + Ok(track::Producer::new(inner, self.key.clone(), scope)) + } +} + +impl std::fmt::Debug for Producer { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("broadcast::Producer") + .field("key", &self.key.public()) + .field("path", &self.path) + .field("epoch", &self.epoch) + .finish() + } +} + +/// The subscribing side of a signed broadcast. +/// +/// Every frame must verify against the expected publisher key under the epoch of the route the +/// broadcast was resolved through. +#[derive(Clone)] +pub struct Consumer { + inner: moq_net::broadcast::Consumer, + key: PublicKey, + path: moq_net::Path, + epoch: moq_net::Epoch, +} + +impl Consumer { + /// Verify `inner` against `key`, as the broadcast at application path `path`. + /// + /// # Errors + /// + /// [`Error::Epoch`] if `inner` was not resolved through a route that names its epoch. + pub fn new(inner: moq_net::broadcast::Consumer, key: PublicKey, path: moq_net::Path) -> Result { + let epoch = inner.info().epoch.clone().ok_or(Error::Epoch)?; + Ok(Self { + inner, + key, + path, + epoch, + }) + } + + /// The epoch frames must be signed under. + pub fn epoch(&self) -> &moq_net::Epoch { + &self.epoch + } + + /// Subscribe to a track whose frames must verify. + /// + /// # Errors + /// + /// A net error if the broadcast has ended. + pub fn subscribe( + &self, + name: &str, + subscription: impl Into>, + ) -> Result> { + let inner = self.inner.track(name)?; + let scope = Scope::new(&self.path, &self.epoch, name); + Ok(kio::Pending::new(track::Subscribing::new( + inner.subscribe(subscription), + self.key, + scope, + ))) + } +} + +impl std::fmt::Debug for Consumer { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("broadcast::Consumer") + .field("key", &self.key) + .field("path", &self.path) + .field("epoch", &self.epoch) + .finish() + } +} diff --git a/rs/moq-sign/src/error.rs b/rs/moq-sign/src/error.rs new file mode 100644 index 00000000000..fe75aebe24c --- /dev/null +++ b/rs/moq-sign/src/error.rs @@ -0,0 +1,19 @@ +/// Typed failures from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). +#[derive(thiserror::Error, Debug, Clone)] +#[non_exhaustive] +pub enum Error { + /// A frame is shorter than a signature, or its signature does not verify at its identity. + #[error("signature")] + Signature, + + /// The broadcast was not resolved through a route that names its publisher epoch. + #[error("epoch")] + Epoch, + + /// The underlying MoQ broadcast, track, or group failed. + #[error(transparent)] + Net(#[from] moq_net::Error), +} + +/// A [`Result`](std::result::Result) using this crate's [`Error`]. +pub type Result = std::result::Result; diff --git a/rs/moq-sign/src/group.rs b/rs/moq-sign/src/group.rs new file mode 100644 index 00000000000..3d9102137d1 --- /dev/null +++ b/rs/moq-sign/src/group.rs @@ -0,0 +1,153 @@ +//! Signing writer and verifying reader for one group. + +use std::fmt; +use std::sync::Arc; +use std::task::{Poll, ready}; + +use bytes::Bytes; + +use crate::error::{Error, Result}; +use crate::key::{PublicKey, SecretKey}; +use crate::scope::Scope; + +/// A grouped frame whose signature verified. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Frame { + /// Presentation timestamp, or `None` when untimed. Not signed. + pub timestamp: Option, + /// The application bytes, without the signature. + pub payload: Bytes, +} + +/// Exclusive writer for one group, signing each frame at the index it lands on. +pub struct Producer { + inner: moq_net::group::Producer, + key: SecretKey, + scope: Arc, +} + +impl Producer { + pub(crate) fn new(inner: moq_net::group::Producer, key: SecretKey, scope: Arc) -> Self { + Self { inner, key, scope } + } + + /// The group's sequence number. + pub fn sequence(&self) -> u64 { + self.inner.sequence + } + + /// Sign `payload` at the next frame index and write it with the signature appended. + /// + /// # Errors + /// + /// A net error if the group is closed, the timestamp does not match the track, or the + /// signed frame exceeds the frame size limit. + pub fn write_frame(&mut self, timestamp: impl Into>, payload: &[u8]) -> Result<()> { + let frame = self.inner.frame_count() as u64; + let body = self.scope.sign(&self.key, self.inner.sequence, frame, payload); + self.inner.write_frame(timestamp, body)?; + Ok(()) + } + + /// Finish the group. No more frames will be written. + /// + /// # Errors + /// + /// A net error if the group is already closed. + pub fn finish(mut self) -> Result<()> { + self.inner.finish()?; + Ok(()) + } + + /// Abort the group with `err`, consuming the handle. + /// + /// # Errors + /// + /// A net error if the group is already closed. + pub fn abort(self, err: moq_net::Error) -> Result<()> { + self.inner.abort(err)?; + Ok(()) + } +} + +impl fmt::Debug for Producer { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("group::Producer") + .field("sequence", &self.sequence()) + .field("frames", &self.inner.frame_count()) + .finish() + } +} + +/// Reader for one signed group. +/// +/// A frame that fails to verify ends the group with [`Error::Signature`]: none of its bytes +/// reach the caller, and the underlying reader is released. The track keeps delivering groups. +pub struct Consumer { + // `None` once a frame failed to verify. + inner: Option, + sequence: u64, + key: PublicKey, + scope: Arc, +} + +impl Consumer { + pub(crate) fn new(inner: moq_net::group::Consumer, key: PublicKey, scope: Arc) -> Self { + Self { + sequence: inner.sequence, + inner: Some(inner), + key, + scope, + } + } + + /// The group's sequence number. + pub fn sequence(&self) -> u64 { + self.sequence + } + + /// Read the next verified frame, without blocking. + /// + /// # Errors + /// + /// [`Error::Signature`] once a frame has failed to verify, or a net error from the group. + pub fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { + let Some(inner) = self.inner.as_mut() else { + return Poll::Ready(Err(Error::Signature)); + }; + let Some(frame) = ready!(inner.poll_read_frame(waiter)?) else { + return Poll::Ready(Ok(None)); + }; + // The cursor already advanced past the frame, so a group resumed above frame 0 still + // verifies at the index the publisher signed. + let index = inner.index() - 1; + match self.scope.verify(&self.key, self.sequence, index, frame.payload) { + Ok(payload) => Poll::Ready(Ok(Some(Frame { + timestamp: frame.timestamp, + payload, + }))), + Err(err) => { + self.inner = None; + Poll::Ready(Err(err)) + } + } + } + + /// Read the next verified frame. + /// + /// # Errors + /// + /// Same as [`Self::poll_read_frame`]. + pub async fn read_frame(&mut self) -> Result> { + kio::wait(|waiter| self.poll_read_frame(waiter)).await + } +} + +impl fmt::Debug for Consumer { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("group::Consumer") + .field("sequence", &self.sequence()) + .field("index", &self.inner.as_ref().map(|inner| inner.index())) + .finish() + } +} diff --git a/rs/moq-sign/src/key.rs b/rs/moq-sign/src/key.rs new file mode 100644 index 00000000000..f1c9f0fb49b --- /dev/null +++ b/rs/moq-sign/src/key.rs @@ -0,0 +1,182 @@ +//! Endpoint keys: a persistent Ed25519 secret key and the public key that names its endpoint. + +use std::fmt; +use std::io::{self, Write}; +use std::str::FromStr; +use std::sync::Arc; + +use aws_lc_rs::signature::{ED25519, Ed25519KeyPair, KeyPair, UnparsedPublicKey}; +use zeroize::Zeroizing; + +use crate::scope::SIGNATURE_LEN; + +/// Ed25519 key length in bytes, for both the secret seed and the public key. +const KEY_LEN: usize = 32; + +/// An endpoint's Ed25519 public key, which is also its endpoint ID. +/// +/// Its text form is the 64-character lowercase hex of the key, the form iroh displays. Parsing +/// accepts only that form, so one key has exactly one ID to name a path by. +#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] +pub struct PublicKey([u8; KEY_LEN]); + +impl PublicKey { + /// Wrap the 32 raw bytes of an Ed25519 public key. + pub fn from_bytes(bytes: [u8; KEY_LEN]) -> Self { + Self(bytes) + } + + /// The 32 raw bytes of the key. + pub fn as_bytes(&self) -> &[u8; KEY_LEN] { + &self.0 + } + + /// Whether `signature` is this key's Ed25519 signature over `message`. + pub(crate) fn verify(&self, message: &[u8], signature: &[u8; SIGNATURE_LEN]) -> bool { + UnparsedPublicKey::new(&ED25519, &self.0).verify(message, signature).is_ok() + } +} + +/// The text is not the 64-character lowercase hex of a 32-byte key. +#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] +#[error("invalid key: expected 64 lowercase hex characters")] +#[non_exhaustive] +pub struct InvalidKey; + +impl FromStr for PublicKey { + type Err = InvalidKey; + + fn from_str(text: &str) -> Result { + Ok(Self(parse_hex(text)?)) + } +} + +impl fmt::Display for PublicKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&hex::encode(self.0)) + } +} + +impl fmt::Debug for PublicKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_tuple("PublicKey").field(&format_args!("{self}")).finish() + } +} + +/// Decode exactly 64 lowercase hex characters, refusing uppercase so a key has one text form. +fn parse_hex(text: &str) -> Result<[u8; KEY_LEN], InvalidKey> { + if text.len() != KEY_LEN * 2 || !text.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { + return Err(InvalidKey); + } + let mut out = [0u8; KEY_LEN]; + hex::decode_to_slice(text, &mut out).map_err(|_| InvalidKey)?; + Ok(out) +} + +struct Inner { + seed: Zeroizing<[u8; KEY_LEN]>, + pair: Ed25519KeyPair, + public: PublicKey, +} + +/// An endpoint's Ed25519 secret key: cheap to clone, redacted from `Debug`. +#[derive(Clone)] +pub struct SecretKey(Arc); + +impl SecretKey { + /// Generate a fresh key from the system's secure random source. + pub fn generate() -> Self { + let mut seed = Zeroizing::new([0u8; KEY_LEN]); + aws_lc_rs::rand::fill(seed.as_mut()).expect("system randomness"); + Self::from_seed(seed) + } + + pub(crate) fn from_seed(seed: Zeroizing<[u8; KEY_LEN]>) -> Self { + let pair = Ed25519KeyPair::from_seed_unchecked(seed.as_ref()).expect("a 32-byte Ed25519 seed"); + let public = PublicKey(pair.public_key().as_ref().try_into().expect("a 32-byte Ed25519 public key")); + Self(Arc::new(Inner { seed, pair, public })) + } + + /// The public key, which is this endpoint's ID. + pub fn public(&self) -> PublicKey { + self.0.public + } + + /// Load the key stored at `path`, or generate one and store it there if the file is missing. + /// + /// The file holds the seed as 64 lowercase hex characters and a newline, created with mode + /// `0600`. A key is never replaced implicitly: an existing file that does not parse, or that + /// other users can read, is an error rather than a reason to generate a new identity. + /// + /// # Errors + /// + /// [`io::ErrorKind::InvalidData`] for a malformed or exposed file, or the I/O error reading or + /// creating it. + pub fn load_or_generate(path: impl AsRef) -> io::Result { + let path = path.as_ref(); + match Self::load(path) { + Err(err) if err.kind() == io::ErrorKind::NotFound => {} + other => return other, + } + + let key = Self::generate(); + let mut options = std::fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600); + let mut file = match options.open(path) { + Ok(file) => file, + // Another process created it first; its key wins. + Err(err) if err.kind() == io::ErrorKind::AlreadyExists => return Self::load(path), + Err(err) => return Err(err), + }; + let mut text = Zeroizing::new(hex::encode(key.0.seed.as_ref())); + text.push('\n'); + file.write_all(text.as_bytes())?; + file.sync_all()?; + Ok(key) + } + + fn load(path: &std::path::Path) -> io::Result { + let file = std::fs::File::open(path)?; + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + if file.metadata()?.permissions().mode() & 0o077 != 0 { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + format!("key file {} is accessible by other users", path.display()), + )); + } + } + let mut text = Zeroizing::new(String::new()); + io::Read::read_to_string(&mut &file, &mut text)?; + let hex = text.strip_suffix('\n').unwrap_or(&text); + let seed = parse_hex(hex).map_err(|_| { + io::Error::new( + io::ErrorKind::InvalidData, + format!("key file {} is not 64 lowercase hex characters", path.display()), + ) + })?; + Ok(Self::from_seed(Zeroizing::new(seed))) + } + + /// Sign `message` with Ed25519. + pub(crate) fn sign(&self, message: &[u8]) -> [u8; SIGNATURE_LEN] { + self.0 + .pair + .sign(message) + .as_ref() + .try_into() + .expect("a 64-byte Ed25519 signature") + } +} + +impl fmt::Debug for SecretKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("SecretKey") + .field("public", &self.0.public) + .field("seed", &"") + .finish() + } +} diff --git a/rs/moq-sign/src/lib.rs b/rs/moq-sign/src/lib.rs new file mode 100644 index 00000000000..a20bbc4454a --- /dev/null +++ b/rs/moq-sign/src/lib.rs @@ -0,0 +1,33 @@ +//! Per-frame Ed25519 signatures for MoQ broadcasts. +//! +//! Implements profile `moq-sign-00` from [draft-lcurley-moq-sign]. A publisher signs every +//! grouped frame with its endpoint's [`SecretKey`], binding the broadcast path, its publisher +//! epoch, the track, the group, and the frame index. A subscriber hands a frame to the +//! application only after it verifies against the [`PublicKey`] it expects, so a relay can +//! proxy and cache without forging, replaying, or splicing content. +//! +//! [draft-lcurley-moq-sign]: https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/ +//! +//! A publisher wraps its `moq-net` broadcast in a [`broadcast::Producer`], which mints a fresh +//! epoch to announce on the broadcast's route. A subscriber wraps the broadcast an origin +//! resolved in a [`broadcast::Consumer`], which takes the epoch from that route. Both sides name +//! the broadcast by the same application path, independent of where a relay mounts it. +//! +//! A broadcast that needs no signature, the identity level, uses `moq-net` directly. + +#![warn(missing_docs)] + +pub mod broadcast; +pub mod group; +pub mod track; + +mod error; +mod key; +mod scope; + +pub use error::{Error, Result}; +pub use key::{InvalidKey, PublicKey, SecretKey}; +pub use scope::SIGNATURE_LEN; + +#[cfg(test)] +mod tests; diff --git a/rs/moq-sign/src/scope.rs b/rs/moq-sign/src/scope.rs new file mode 100644 index 00000000000..c23a15c6ee7 --- /dev/null +++ b/rs/moq-sign/src/scope.rs @@ -0,0 +1,62 @@ +//! The signed message: what a frame's signature binds besides its payload. + +use std::sync::Arc; + +use bytes::{BufMut, Bytes, BytesMut}; + +use crate::error::{Error, Result}; +use crate::key::{PublicKey, SecretKey}; + +/// Length of the Ed25519 signature appended to every signed frame. +pub const SIGNATURE_LEN: usize = 64; + +/// Domain separation for the profile, with no length prefix of its own. +const LABEL: &[u8] = b"moq-sign-00"; + +/// One track of one publisher instance: the identity every frame on it is signed under. +#[derive(Debug)] +pub(crate) struct Scope { + // The canonical prefix: label, path, epoch, and track, each length-prefixed. + prefix: Vec, +} + +impl Scope { + pub(crate) fn new(path: &moq_net::Path, epoch: &moq_net::Epoch, track: &str) -> Arc { + let mut prefix = Vec::with_capacity(LABEL.len() + 24 + path.as_str().len() + 36 + track.len()); + prefix.extend_from_slice(LABEL); + for field in [path.as_str(), epoch.as_str(), track] { + prefix.extend_from_slice(&(field.len() as u64).to_be_bytes()); + prefix.extend_from_slice(field.as_bytes()); + } + Arc::new(Self { prefix }) + } + + /// The message signed for `payload` at frame `frame` of group `group`. + pub(crate) fn message(&self, group: u64, frame: u64, payload: &[u8]) -> Vec { + let mut message = Vec::with_capacity(self.prefix.len() + 16 + payload.len()); + message.extend_from_slice(&self.prefix); + message.extend_from_slice(&group.to_be_bytes()); + message.extend_from_slice(&frame.to_be_bytes()); + message.extend_from_slice(payload); + message + } + + /// The frame body: `payload` followed by its signature. + pub(crate) fn sign(&self, key: &SecretKey, group: u64, frame: u64, payload: &[u8]) -> Bytes { + let signature = key.sign(&self.message(group, frame, payload)); + let mut body = BytesMut::with_capacity(payload.len() + SIGNATURE_LEN); + body.put_slice(payload); + body.put_slice(&signature); + body.freeze() + } + + /// The payload of a frame body whose signature verifies, without copying it. + pub(crate) fn verify(&self, key: &PublicKey, group: u64, frame: u64, body: Bytes) -> Result { + let split = body.len().checked_sub(SIGNATURE_LEN).ok_or(Error::Signature)?; + let signature: &[u8; SIGNATURE_LEN] = body[split..].try_into().expect("the signature's length"); + if !key.verify(&self.message(group, frame, &body[..split]), signature) { + return Err(Error::Signature); + } + Ok(body.slice(..split)) + } +} diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs new file mode 100644 index 00000000000..f9047fe492d --- /dev/null +++ b/rs/moq-sign/src/tests.rs @@ -0,0 +1,354 @@ +use std::sync::Arc; +use std::time::Duration; + +use bytes::Bytes; +use serde_json::Value; +use zeroize::Zeroizing; + +use crate::scope::Scope; +use crate::{Error, PublicKey, SecretKey, broadcast, group, track}; + +const VECTORS: &str = include_str!("../../../drafts/moq-sign-00.json"); + +fn vectors() -> Value { + serde_json::from_str(VECTORS).unwrap() +} + +fn hex(value: &Value) -> Vec { + hex::decode(value.as_str().unwrap()).unwrap() +} + +fn seed(value: &Value) -> SecretKey { + SecretKey::from_seed(Zeroizing::new(hex(value).try_into().unwrap())) +} + +fn public(value: &Value) -> PublicKey { + value.as_str().unwrap().parse().unwrap() +} + +/// A vector row's identity: its scope, group, and frame. +fn identity(row: &Value) -> (Arc, u64, u64) { + let path = moq_net::Path::new(row["path"].as_str().unwrap()).unwrap(); + let epoch = row["epoch"].as_str().unwrap().parse().unwrap(); + let scope = Scope::new(&path, &epoch, row["track"].as_str().unwrap()); + (scope, row["group"].as_u64().unwrap(), row["frame"].as_u64().unwrap()) +} + +#[test] +fn vector_keys() { + for row in vectors()["keys"].as_array().unwrap() { + let key = seed(&row["seed"]); + assert_eq!(key.public().to_string(), row["public"].as_str().unwrap(), "{}", row["id"]); + assert_eq!(key.public(), public(&row["public"])); + } +} + +#[test] +fn vector_frames() { + for row in vectors()["frames"].as_array().unwrap() { + let id = &row["id"]; + let (scope, group, frame) = identity(row); + let payload = hex(&row["payload"]); + assert_eq!(scope.message(group, frame, &payload), hex(&row["message"]), "{id}"); + let body = scope.sign(&seed(&row["seed"]), group, frame, &payload); + assert_eq!(body.as_ref(), hex(&row["body"]), "{id}"); + let opened = scope.verify(&public(&row["public"]), group, frame, body).unwrap(); + assert_eq!(opened.as_ref(), payload, "{id}"); + } +} + +#[test] +fn vector_negative() { + for row in vectors()["negative"].as_array().unwrap() { + let (scope, group, frame) = identity(row); + let body = Bytes::from(hex(&row["body"])); + let result = scope.verify(&public(&row["public"]), group, frame, body); + assert_eq!(row["error"], "signature"); + assert!(matches!(result, Err(Error::Signature)), "{}", row["id"]); + } +} + +#[test] +fn vector_invalid_ids() { + for row in vectors()["invalid_ids"].as_array().unwrap() { + assert!(row["text"].as_str().unwrap().parse::().is_err(), "{}", row["id"]); + } +} + +#[test] +fn key_file_persists_and_never_rotates() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("endpoint.key"); + + let created = SecretKey::load_or_generate(&path).unwrap(); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + assert_eq!(std::fs::metadata(&path).unwrap().permissions().mode() & 0o777, 0o600); + } + let loaded = SecretKey::load_or_generate(&path).unwrap(); + assert_eq!(created.public(), loaded.public()); + + // A damaged file is an error, never a reason to mint a new identity. + std::fs::write(&path, "not a key\n").unwrap(); + let err = SecretKey::load_or_generate(&path).unwrap_err(); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + assert_eq!(std::fs::read_to_string(&path).unwrap(), "not a key\n"); +} + +#[cfg(unix)] +#[test] +fn key_file_readable_by_others_is_refused() { + use std::os::unix::fs::PermissionsExt; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("endpoint.key"); + SecretKey::load_or_generate(&path).unwrap(); + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o640)).unwrap(); + let err = SecretKey::load_or_generate(&path).unwrap_err(); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); +} + +#[test] +fn debug_redacts_the_seed() { + let key = SecretKey::from_seed(Zeroizing::new([0x42; 32])); + let debug = format!("{key:?}"); + assert!(!debug.contains(&"42".repeat(32)), "{debug}"); + assert!(debug.contains(&key.public().to_string())); +} + +/// Let the origin's driver serve what a call started. +async fn settle() { + for _ in 0..10 { + tokio::task::yield_now().await; + } +} + +fn subscribe_all() -> moq_net::track::Subscription { + moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(60)) +} + +/// A signed broadcast published at `path` on its own origin, announced under its epoch. +struct Published { + origin: moq_net::origin::Producer, + _publication: moq_net::origin::Publication, + signed: broadcast::Producer, + path: moq_net::Path, +} + +fn publish(key: &SecretKey, path: &str) -> Published { + let (origin, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::default()); + tokio::spawn(moq_net::time::run(driver)); + let path = moq_net::Path::new(path).unwrap(); + let publication = origin.create_broadcast(&path).unwrap(); + let signed = broadcast::Producer::new(publication.broadcast().clone(), key.clone(), path.clone()); + publication + .announce(moq_net::origin::Route::default().with_epoch(signed.epoch().clone())) + .unwrap(); + Published { + origin, + _publication: publication, + signed, + path, + } +} + +impl Published { + /// The broadcast as a subscriber resolves it, verifying against `key`. + async fn consume(&self, key: PublicKey) -> broadcast::Consumer { + settle().await; + let inner = self.origin.consume().request_broadcast(&self.path, None).await.unwrap(); + broadcast::Consumer::new(inner, key, self.path.clone()).unwrap() + } + + /// A signed track over a net track the test can also write forged frames to. + fn track(&self, key: &SecretKey, name: &str) -> (track::Producer, moq_net::track::Producer) { + let net = self._publication.broadcast().create_track(name, None).unwrap(); + let scope = Scope::new(&self.path, self.signed.epoch(), name); + (track::Producer::new(net.clone(), key.clone(), scope), net) + } +} + +async fn subscribe(consumer: &broadcast::Consumer, name: &str) -> track::Consumer { + consumer.subscribe(name, subscribe_all()).unwrap().await.unwrap() +} + +async fn recv_group(consumer: &mut track::Consumer) -> group::Consumer { + settle().await; + consumer.recv_group().await.unwrap().expect("a group") +} + +async fn read(group: &mut group::Consumer) -> Result, Error> { + settle().await; + Ok(group.read_frame().await?.map(|frame| frame.payload)) +} + +#[tokio::test(start_paused = true)] +async fn roundtrip_through_an_origin() { + let key = SecretKey::generate(); + let published = publish(&key, "mesh/node/ssh"); + let video = published + .signed + .create_track("video", moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI)) + .unwrap(); + let consumer = published.consume(key.public()).await; + assert_eq!(consumer.epoch(), published.signed.epoch()); + let mut track = subscribe(&consumer, "video").await; + + let mut group = video.append_group().unwrap(); + group + .write_frame(moq_net::Timestamp::from_millis(1).unwrap(), b"keyframe") + .unwrap(); + group + .write_frame(moq_net::Timestamp::from_millis(2).unwrap(), b"") + .unwrap(); + group.finish().unwrap(); + + let mut received = recv_group(&mut track).await; + let first = received.read_frame().await.unwrap().unwrap(); + assert_eq!(first.payload, &b"keyframe"[..]); + assert_eq!(first.timestamp, Some(moq_net::Timestamp::from_millis(1).unwrap())); + assert_eq!(read(&mut received).await.unwrap().unwrap(), &b""[..]); + assert_eq!(read(&mut received).await.unwrap(), None); +} + +#[tokio::test(start_paused = true)] +async fn forged_frame_delivers_nothing_and_ends_only_its_group() { + let key = SecretKey::generate(); + let published = publish(&key, "mesh/node/ssh"); + let (signed, net) = published.track(&key, "stream"); + let consumer = published.consume(key.public()).await; + let mut track = subscribe(&consumer, "stream").await; + + // A relay's forgery: an unsigned frame the length of a signed one. + let mut forged = net.append_group().unwrap(); + forged.write_frame(None, vec![0u8; 80]).unwrap(); + forged.write_frame(None, vec![0u8; 80]).unwrap(); + forged.finish().unwrap(); + + let mut group = recv_group(&mut track).await; + assert!(matches!(read(&mut group).await, Err(Error::Signature))); + // The group stays ended, even though a later frame is buffered. + assert!(matches!(read(&mut group).await, Err(Error::Signature))); + + let mut next = signed.append_group().unwrap(); + next.write_frame(None, b"after").unwrap(); + next.finish().unwrap(); + let mut group = recv_group(&mut track).await; + assert_eq!(read(&mut group).await.unwrap().unwrap(), &b"after"[..]); +} + +/// Copy the raw body of frame 0 of the next group out of `net`'s own subscription. +async fn raw_frame(net: &mut moq_net::track::Subscriber) -> Bytes { + let mut group = net.recv_group().await.unwrap().unwrap(); + group.read_frame().await.unwrap().unwrap().payload +} + +#[tokio::test(start_paused = true)] +async fn frame_replayed_from_another_group_or_track_is_refused() { + let key = SecretKey::generate(); + let published = publish(&key, "mesh/node/ssh"); + let (signed, net) = published.track(&key, "a"); + let (_other, other_net) = published.track(&key, "b"); + let mut raw = net.subscribe(subscribe_all()); + let consumer = published.consume(key.public()).await; + let mut a = subscribe(&consumer, "a").await; + let mut b = subscribe(&consumer, "b").await; + + let mut group = signed.append_group().unwrap(); + group.write_frame(None, b"original").unwrap(); + group.finish().unwrap(); + let body = raw_frame(&mut raw).await; + assert_eq!(read(&mut recv_group(&mut a).await).await.unwrap().unwrap(), &b"original"[..]); + + // The same bytes as group 1 of the same track. + let mut replay = net.append_group().unwrap(); + replay.write_frame(None, body.clone()).unwrap(); + replay.finish().unwrap(); + assert!(matches!(read(&mut recv_group(&mut a).await).await, Err(Error::Signature))); + + // The same bytes at the same group and index of another track. + let mut moved = other_net.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + moved.write_frame(None, body.clone()).unwrap(); + moved.finish().unwrap(); + assert!(matches!(read(&mut recv_group(&mut b).await).await, Err(Error::Signature))); + + // The same bytes at frame 1 of a group at the original sequence's neighbor. + let mut shifted = net.append_group().unwrap(); + shifted.write_frame(None, b"filler".as_slice()).unwrap(); + shifted.write_frame(None, body).unwrap(); + shifted.finish().unwrap(); + assert!(matches!(read(&mut recv_group(&mut a).await).await, Err(Error::Signature))); +} + +#[tokio::test(start_paused = true)] +async fn broadcast_under_another_key_is_refused() { + let impostor = SecretKey::generate(); + let victim = SecretKey::generate(); + // The impostor publishes at the victim's path, signing with its own key. + let published = publish(&impostor, &format!("mesh/{}/ssh", victim.public())); + let track = published.signed.create_track("stream", None).unwrap(); + let consumer = published.consume(victim.public()).await; + let mut subscribed = subscribe(&consumer, "stream").await; + + let mut group = track.append_group().unwrap(); + group.write_frame(None, b"hello").unwrap(); + group.finish().unwrap(); + assert!(matches!( + read(&mut recv_group(&mut subscribed).await).await, + Err(Error::Signature) + )); +} + +#[tokio::test(start_paused = true)] +async fn frame_from_an_earlier_instance_is_refused() { + let key = SecretKey::generate(); + let old = publish(&key, "mesh/node/ssh"); + let (old_track, old_net) = old.track(&key, "stream"); + let mut raw = old_net.subscribe(subscribe_all()); + let mut group = old_track.append_group().unwrap(); + group.write_frame(None, b"stale").unwrap(); + group.finish().unwrap(); + let body = raw_frame(&mut raw).await; + + // A restart mints a new epoch, so the old instance's group 0 does not verify as the new one's. + let new = publish(&key, "mesh/node/ssh"); + assert_ne!(new.signed.epoch(), old.signed.epoch()); + let (_new_track, new_net) = new.track(&key, "stream"); + let consumer = new.consume(key.public()).await; + let mut subscribed = subscribe(&consumer, "stream").await; + let mut replay = new_net.append_group().unwrap(); + replay.write_frame(None, body).unwrap(); + replay.finish().unwrap(); + assert!(matches!( + read(&mut recv_group(&mut subscribed).await).await, + Err(Error::Signature) + )); +} + +#[tokio::test(start_paused = true)] +async fn group_resumed_above_frame_zero_verifies_at_its_index() { + let key = SecretKey::generate(); + let path = moq_net::Path::new("mesh/node/ssh").unwrap(); + let epoch = moq_net::Epoch::mint(); + let scope = Scope::new(&path, &epoch, "stream"); + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast.create_track("stream", None).unwrap(); + let net = track.append_group().unwrap(); + let raw = net.consume(); + let mut signed = group::Producer::new(net, key.clone(), Arc::clone(&scope)); + signed.write_frame(None, b"zero").unwrap(); + signed.write_frame(None, b"one").unwrap(); + signed.finish().unwrap(); + + let mut resumed = group::Consumer::new(raw.with_range(1..), key.public(), scope); + assert_eq!(read(&mut resumed).await.unwrap().unwrap(), &b"one"[..]); + assert_eq!(read(&mut resumed).await.unwrap(), None); +} + +#[test] +fn consumer_without_an_epoch_is_refused() { + let inner = moq_net::broadcast::Info::new().produce().consume(); + let path = moq_net::Path::new("mesh/node/ssh").unwrap(); + let result = broadcast::Consumer::new(inner, SecretKey::generate().public(), path); + assert!(matches!(result, Err(Error::Epoch))); +} diff --git a/rs/moq-sign/src/track.rs b/rs/moq-sign/src/track.rs new file mode 100644 index 00000000000..83ede31384e --- /dev/null +++ b/rs/moq-sign/src/track.rs @@ -0,0 +1,167 @@ +//! Signing producer and verifying subscriber for one track. + +use std::fmt; +use std::sync::Arc; +use std::task::{Poll, ready}; + +use crate::error::Result; +use crate::group; +use crate::key::{PublicKey, SecretKey}; +use crate::scope::Scope; + +/// Producer for one signed track. +pub struct Producer { + inner: moq_net::track::Producer, + key: SecretKey, + scope: Arc, +} + +impl Producer { + pub(crate) fn new(inner: moq_net::track::Producer, key: SecretKey, scope: Arc) -> Self { + Self { inner, key, scope } + } + + /// The track name. + pub fn name(&self) -> &str { + self.inner.name() + } + + /// Start a group at the next sequence. + /// + /// # Errors + /// + /// A net error if the track is closed. + pub fn append_group(&self) -> Result { + let inner = self.inner.append_group()?; + Ok(self.group(inner)) + } + + /// Start a group at an explicit sequence. + /// + /// # Errors + /// + /// A net error if the track is closed or already holds the sequence. + pub fn create_group(&self, sequence: u64) -> Result { + let inner = self.inner.create_group(moq_net::group::Info { sequence })?; + Ok(self.group(inner)) + } + + fn group(&self, inner: moq_net::group::Producer) -> group::Producer { + group::Producer::new(inner, self.key.clone(), Arc::clone(&self.scope)) + } + + /// Finish the track after the last group. + /// + /// # Errors + /// + /// A net error if the track is already closed. + pub fn finish(self) -> Result<()> { + self.inner.finish()?; + Ok(()) + } + + /// Abort the track with `err`, consuming the handle. + /// + /// # Errors + /// + /// A net error if the track is already closed. + pub fn abort(self, err: moq_net::Error) -> Result<()> { + self.inner.abort(err)?; + Ok(()) + } +} + +impl fmt::Debug for Producer { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("track::Producer").field("name", &self.name()).finish() + } +} + +/// The pollable state of a [`broadcast::Consumer::subscribe`](crate::broadcast::Consumer::subscribe); +/// awaited via the [`kio::Pending`] wrapper, whose `DerefMut` exposes [`Self::update`]. +pub struct Subscribing { + inner: kio::Pending, + key: PublicKey, + // Bound to the name subscribed to, never to the name a relay hands back. + scope: Arc, +} + +impl Subscribing { + pub(crate) fn new(inner: kio::Pending, key: PublicKey, scope: Arc) -> Self { + Self { inner, key, scope } + } + + /// Poll until the track is found, yielding a verifying [`Consumer`]. + /// + /// # Errors + /// + /// A net error if the track is aborted or not found. + pub fn poll_ok(&self, waiter: &kio::Waiter) -> Poll> { + let inner = ready!(self.inner.poll_ok(waiter))?; + Poll::Ready(Ok(Consumer { + inner, + key: self.key, + scope: Arc::clone(&self.scope), + })) + } + + /// Change the subscription preferences before (or after) it resolves. + /// + /// # Errors + /// + /// [`moq_net::Error::Closed`] if the track already ended. + pub fn update(&mut self, subscription: moq_net::track::Subscription) -> Result<()> { + Ok(self.inner.update(subscription)?) + } +} + +impl kio::Task for Subscribing { + type Output = Result; + + fn poll(&mut self, waiter: &kio::Waiter) -> Poll { + self.poll_ok(waiter) + } +} + +/// Subscriber for one signed track. +/// +/// Each group verifies on its own: a forged frame ends only the group that carried it. +pub struct Consumer { + inner: moq_net::track::Subscriber, + key: PublicKey, + scope: Arc, +} + +impl Consumer { + /// The track name. + pub fn name(&self) -> &str { + self.inner.name() + } + + /// Poll for the next group in arrival order. + /// + /// # Errors + /// + /// A net error if the track fails. + pub fn poll_recv_group(&mut self, waiter: &kio::Waiter) -> Poll>> { + let Some(inner) = ready!(self.inner.poll_recv_group(waiter)?) else { + return Poll::Ready(Ok(None)); + }; + Poll::Ready(Ok(Some(group::Consumer::new(inner, self.key, Arc::clone(&self.scope))))) + } + + /// Receive the next group in arrival order. + /// + /// # Errors + /// + /// Same as [`Self::poll_recv_group`]. + pub async fn recv_group(&mut self) -> Result> { + kio::wait(|waiter| self.poll_recv_group(waiter)).await + } +} + +impl fmt::Debug for Consumer { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.debug_struct("track::Consumer").field("name", &self.name()).finish() + } +} diff --git a/sh/drafts/check.sh b/sh/drafts/check.sh index 0e3f6af5421..e5b78393bec 100755 --- a/sh/drafts/check.sh +++ b/sh/drafts/check.sh @@ -30,7 +30,7 @@ for f in draft-*.md; do rm -f "${f%.md}.prepped.xml" done -for f in moq-e2ee-*.ts; do +for f in moq-e2ee-*.ts moq-sign-*.ts; do bun tsc --ignoreConfig --noEmit --skipLibCheck --target esnext --module esnext --moduleResolution bundler --types bun "$f" bun "$f" done From fcc72113162fc859c67c33f4b8ad66e643ee5bd7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:28:13 -0700 Subject: [PATCH 03/10] feat(sign): JS @moq/sign package and Rust/JS interop Co-Authored-By: Claude Opus 5.5 --- bun.lock | 15 +++ js/sign/package.json | 31 +++++++ js/sign/src/broadcast.ts | 94 +++++++++++++++++++ js/sign/src/failure.ts | 21 +++++ js/sign/src/group.ts | 160 ++++++++++++++++++++++++++++++++ js/sign/src/index.ts | 39 ++++++++ js/sign/src/key.ts | 96 +++++++++++++++++++ js/sign/src/pump.ts | 16 ++++ js/sign/src/scope.ts | 59 ++++++++++++ js/sign/src/sign.test.ts | 178 ++++++++++++++++++++++++++++++++++++ js/sign/src/track.ts | 123 +++++++++++++++++++++++++ js/sign/src/vectors.test.ts | 67 ++++++++++++++ js/sign/tsconfig.build.json | 10 ++ js/sign/tsconfig.json | 11 +++ package.json | 1 + rs/moq-sign/src/tests.rs | 72 +++++++++++++++ test/interop/sign.ts | 66 +++++++++++++ test/justfile | 3 +- 18 files changed, 1061 insertions(+), 1 deletion(-) create mode 100644 js/sign/package.json create mode 100644 js/sign/src/broadcast.ts create mode 100644 js/sign/src/failure.ts create mode 100644 js/sign/src/group.ts create mode 100644 js/sign/src/index.ts create mode 100644 js/sign/src/key.ts create mode 100644 js/sign/src/pump.ts create mode 100644 js/sign/src/scope.ts create mode 100644 js/sign/src/sign.test.ts create mode 100644 js/sign/src/track.ts create mode 100644 js/sign/src/vectors.test.ts create mode 100644 js/sign/tsconfig.build.json create mode 100644 js/sign/tsconfig.json create mode 100644 test/interop/sign.ts diff --git a/bun.lock b/bun.lock index c5ce21e30a9..b40719b1d75 100644 --- a/bun.lock +++ b/bun.lock @@ -398,6 +398,19 @@ "vite": "^8.3.4", }, }, + "js/sign": { + "name": "@moq/sign", + "version": "0.0.0", + "dependencies": { + "@moq/net": "workspace:^", + }, + "devDependencies": { + "@moq/clock": "workspace:^", + "@types/bun": "^1.4.3", + "rimraf": "^6.1.3", + "typescript": "7.0.2", + }, + }, "js/signals": { "name": "@moq/signals", "version": "0.2.5", @@ -912,6 +925,8 @@ "@moq/room": ["@moq/room@workspace:js/room"], + "@moq/sign": ["@moq/sign@workspace:js/sign"], + "@moq/signals": ["@moq/signals@workspace:js/signals"], "@moq/ui": ["@moq/ui@workspace:js/ui"], diff --git a/js/sign/package.json b/js/sign/package.json new file mode 100644 index 00000000000..b868837b696 --- /dev/null +++ b/js/sign/package.json @@ -0,0 +1,31 @@ +{ + "name": "@moq/sign", + "type": "module", + "version": "0.0.0", + "description": "Per-frame Ed25519 signatures for MoQ broadcasts, so relays proxy without forging content.", + "license": "(MIT OR Apache-2.0)", + "repository": { + "type": "git", + "url": "git+https://github.com/moq-dev/moq.git", + "directory": "js/sign" + }, + "private": true, + "sideEffects": false, + "exports": { + ".": "./src/index.ts" + }, + "scripts": { + "build": "rimraf dist && tsc -b tsconfig.build.json && bun ../common/package.ts", + "check": "tsc --noEmit", + "test": "bun test --only-failures" + }, + "dependencies": { + "@moq/net": "workspace:^" + }, + "devDependencies": { + "@moq/clock": "workspace:^", + "@types/bun": "^1.4.3", + "rimraf": "^6.1.3", + "typescript": "7.0.2" + } +} diff --git a/js/sign/src/broadcast.ts b/js/sign/src/broadcast.ts new file mode 100644 index 00000000000..d1b5f324dc8 --- /dev/null +++ b/js/sign/src/broadcast.ts @@ -0,0 +1,94 @@ +/** + * Signed broadcasts, named by the application path both ends agree on. + * + * A relay may mount a broadcast under another prefix, so the path a signature binds is the one + * the application names, never the path the transport reports. + * + * @module + */ +import { Epoch, type Broadcast as NetBroadcast, type Track as NetTrack, type Path } from "@moq/net"; +import { Failure } from "./failure.ts"; +import type { PublicKey, SecretKey } from "./key.ts"; +import { Scope } from "./scope.ts"; +import * as Track from "./track.ts"; + +/** + * The publishing side of a signed broadcast. + * + * Mints a fresh epoch, so a restart never signs a sequence an earlier instance already signed. + * Announce the wrapped broadcast with {@link epoch} on its route. + */ +export class Producer { + /** The epoch this instance signs under, to announce on the broadcast's route. */ + readonly epoch: Epoch.Valid = Epoch.mint(); + #inner: NetBroadcast.Producer; + #key: SecretKey; + #path: Path.Valid; + + /** Sign `inner` with `key`, as the broadcast at application path `path`, taking ownership of it: {@link close} ends it. */ + constructor(inner: NetBroadcast.Producer, key: SecretKey, path: Path.Valid) { + this.#inner = inner; + this.#key = key; + this.#path = path; + } + + /** Settles with `null` once the wrapped broadcast closes, as `@moq/net`'s `closed` does. */ + get closed(): NetBroadcast.Producer["closed"] { + return this.#inner.closed; + } + + /** Create a track whose frames are signed; throws the net error if the broadcast already holds it. */ + createTrack(name: string, info: Partial = {}): Track.Producer { + const inner = this.#inner.createTrack(name, info); + return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.epoch, name)); + } + + /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ + close(): void { + this.#inner.close(); + } +} + +/** + * The subscribing side of a signed broadcast. + * + * Every frame must verify against the expected publisher key under the epoch of the route the + * broadcast was resolved through. + */ +export class Consumer { + /** The epoch frames must be signed under. */ + readonly epoch: Epoch.Valid; + #inner: NetBroadcast.Consumer; + #key: PublicKey; + #path: Path.Valid; + + /** + * Verify `inner` against `key`, as the broadcast at application path `path`, taking ownership + * of it: {@link close} releases it. Throws {@link Failure} `epoch` if `inner` was not resolved + * through a route that names its epoch. + */ + constructor(inner: NetBroadcast.Consumer, key: PublicKey, path: Path.Valid) { + const epoch = inner.epoch; + if (!epoch) throw new Failure("epoch"); + this.epoch = epoch; + this.#inner = inner; + this.#key = key; + this.#path = path; + } + + /** Settles with `null` once the wrapped broadcast closes, as `@moq/net`'s `closed` does. */ + get closed(): NetBroadcast.Consumer["closed"] { + return this.#inner.closed; + } + + /** Subscribe to a track whose frames must verify. */ + subscribe(name: string, subscription?: NetTrack.Subscription): Track.Consumer { + const inner = this.#inner.track(name).subscribe(subscription); + return Track.Consumer.make(inner, this.#key, new Scope(this.#path, this.epoch, name)); + } + + /** Release the wrapped broadcast handle, as `@moq/net`'s `close` does. Idempotent. */ + close(): void { + this.#inner.close(); + } +} diff --git a/js/sign/src/failure.ts b/js/sign/src/failure.ts new file mode 100644 index 00000000000..9703a9f6da1 --- /dev/null +++ b/js/sign/src/failure.ts @@ -0,0 +1,21 @@ +/** + * A typed failure code from draft-lcurley-moq-sign. + * + * - `signature`: a frame is shorter than a signature, or its signature does not verify at its identity. + * - `epoch`: the broadcast was not resolved through a route that names its publisher epoch. + * - `key`: a public key is not 32 bytes, or its text is not 64 lowercase hex characters. + */ +export type Code = "signature" | "epoch" | "key"; + +/** A profile failure; the message is the {@link Code}. */ +export class Failure extends Error { + /** The draft's typed failure code. */ + readonly code: Code; + + /** Build a failure for `code`. */ + constructor(code: Code) { + super(code); + this.name = "Failure"; + this.code = code; + } +} diff --git a/js/sign/src/group.ts b/js/sign/src/group.ts new file mode 100644 index 00000000000..def28124a16 --- /dev/null +++ b/js/sign/src/group.ts @@ -0,0 +1,160 @@ +/** + * Signing writer and verifying reader for one group. + * + * @module + */ +import type { Group as NetGroup, Time } from "@moq/net"; +import { Failure } from "./failure.ts"; +import type { PublicKey, SecretKey } from "./key.ts"; +import type { Pump } from "./pump.ts"; +import type { Scope } from "./scope.ts"; + +/** A grouped frame whose signature verified. */ +export interface Frame { + /** Presentation timestamp, or `undefined` when untimed. Not signed. */ + timestamp?: Time.Timestamp; + /** The application bytes, without the signature. */ + payload: Uint8Array; +} + +/** State one track producer shares with its groups. @internal */ +export interface Writer { + // One signature in flight across the track, so net writes land in call order. + pump: Pump; + key: SecretKey; + scope: Scope; + // Set by release or abort: no new writes, including on existing groups. + closed: boolean; + aborted?: Error; +} + +/** + * Exclusive writer for one group, signing each frame at the index it lands on. + * + * Writes run through the track's serial pump, so each frame's index is its net write order. + */ +export class Producer { + /** The group's sequence number. */ + readonly sequence: number; + + #inner: NetGroup.Producer; + #writer: Writer; + // Frames written so far: the next frame's index. + #next = 0; + #closed = false; + + private constructor(inner: NetGroup.Producer, writer: Writer) { + this.#inner = inner; + this.#writer = writer; + this.sequence = inner.sequence; + } + + /** @internal */ + static make(inner: NetGroup.Producer, writer: Writer): Producer { + return new Producer(inner, writer); + } + + /** The group's final outcome after finish drains queued writes, or an abort. */ + get closed(): NetGroup.Producer["closed"] { + return this.#inner.closed; + } + + /** + * Sign `payload` at the next frame index and write it with the signature appended. + * + * The bytes are copied, so the caller may reuse its buffer. Rejects with the net error if + * the group is closed, the timestamp does not match the track, or the frame is too large. + */ + async writeFrame(timestamp: Time.Timestamp | undefined, payload: Uint8Array): Promise { + if (this.#closed || this.#writer.closed) throw this.#writer.aborted ?? new Error("group is closed"); + const owned = payload.slice(); + return this.#writer.pump.run(async () => { + this.#check(); + const body = await this.#writer.scope.sign(this.#writer.key, this.sequence, this.#next, owned); + this.#check(); + this.#inner.writeFrame({ payload: body, timestamp }); + this.#next += 1; + }); + } + + #check(): void { + if (this.#writer.aborted) throw this.#writer.aborted; + if (this.#inner.isClosed) throw new Error("group is closed"); + } + + /** Finish the group after every pending write. Idempotent; no new writes are accepted. */ + finish(): void { + if (this.#closed) return; + this.#closed = true; + void this.#writer.pump.run(() => this.#inner.finish()); + } + + /** Abort at once with `error`; a finished or aborted group keeps its outcome. */ + abort(error: Error): void { + this.#closed = true; + this.#inner.abort(error); + } +} + +/** + * Reader for one signed group. + * + * A frame that fails to verify ends the group with {@link Failure} `signature`: none of its + * bytes reach the caller, and the underlying reader is released. The track keeps delivering groups. + */ +export class Consumer { + /** The group's sequence number. */ + readonly sequence: number; + + #inner: NetGroup.Consumer; + #key: PublicKey; + #scope: Scope; + #failed?: Failure; + // Reads run one at a time, so frames verify in transport order. + #tail: Promise = Promise.resolve(); + + private constructor(inner: NetGroup.Consumer, key: PublicKey, scope: Scope) { + this.#inner = inner; + this.#key = key; + this.#scope = scope; + this.sequence = inner.sequence; + } + + /** @internal */ + static make(inner: NetGroup.Consumer, key: PublicKey, scope: Scope): Consumer { + return new Consumer(inner, key, scope); + } + + /** + * Read the next verified frame, or `undefined` at the end of the group. + * + * Rejects with {@link Failure} `signature` once a frame has failed to verify, or a net error. + */ + readFrame(): Promise { + const result = this.#tail.then(() => this.#read()); + this.#tail = result.catch(() => {}); + return result; + } + + async #read(): Promise { + if (this.#failed) throw this.#failed; + const frame = await this.#inner.readFrameSequence(); + if (!frame) return undefined; + // The frame's transport index, so a group resumed above frame 0 still verifies. + try { + const payload = await this.#scope.verify(this.#key, this.sequence, frame.sequence, frame.payload); + return { timestamp: frame.timestamp, payload }; + } catch (err) { + if (err instanceof Failure) { + this.#failed = err; + this.#inner.close(); + } + throw err; + } + } + + /** Stop reading this group, releasing its demand. Idempotent. */ + close(): void { + this.#inner.close(); + } +} diff --git a/js/sign/src/index.ts b/js/sign/src/index.ts new file mode 100644 index 00000000000..8a3e612e0e6 --- /dev/null +++ b/js/sign/src/index.ts @@ -0,0 +1,39 @@ +/** + * Per-frame Ed25519 signatures for MoQ broadcasts. + * + * Implements profile `moq-sign-00` from + * [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). A publisher + * signs every grouped frame with its endpoint's {@link SecretKey}, binding the broadcast path, its + * publisher epoch, the track, the group, and the frame index. A subscriber hands a frame to the + * application only after it verifies against the {@link PublicKey} it expects, so a relay can + * proxy and cache without forging, replaying, or splicing content. Mirrors the Rust `moq-sign` crate. + * + * ```ts + * const key = await SecretKey.generate(); + * const path = Path.from(`mesh/${key.public}/agent`); + * const publication = origin.createBroadcast(path); + * const signed = new Broadcast.Producer(publication.broadcast, key, path); + * const messages = signed.createTrack("messages"); + * publication.announce({ epoch: signed.epoch }); + * + * const group = messages.appendGroup(); + * await group.writeFrame(undefined, payload); + * group.finish(); + * ``` + * + * WebCrypto Ed25519 is asynchronous, so writes return promises and run through a serial pump + * per track: one signature in flight, net writes in call order. Await each write for backpressure. + * + * A broadcast that needs no signature, the identity level, uses `@moq/net` directly. + * + * @module + */ + +export * as Broadcast from "./broadcast.ts"; +export { type Code, Failure } from "./failure.ts"; +/** Signing writer and verifying reader for one group. */ +export * as Group from "./group.ts"; +export { PublicKey, SecretKey } from "./key.ts"; +export { SIGNATURE_LEN } from "./scope.ts"; +/** Signing producer and verifying subscriber for one track. */ +export * as Track from "./track.ts"; diff --git a/js/sign/src/key.ts b/js/sign/src/key.ts new file mode 100644 index 00000000000..bc95756dbb8 --- /dev/null +++ b/js/sign/src/key.ts @@ -0,0 +1,96 @@ +/** + * Endpoint keys: an Ed25519 secret key and the public key that names its endpoint. + * + * @module + */ +import { Failure } from "./failure.ts"; + +const KEY_LEN = 32; +const ED25519 = { name: "Ed25519" } as const; +// The PKCS #8 wrapper for a raw 32-byte Ed25519 seed, the only private format WebCrypto imports. +const PKCS8_PREFIX = Uint8Array.from([ + 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, +]); + +/** + * An endpoint's Ed25519 public key, which is also its endpoint ID. + * + * Its text form is the 64-character lowercase hex of the key, the form iroh displays. Parsing + * accepts only that form, so one key has exactly one ID to name a path by. + */ +export class PublicKey { + /** The 32 raw bytes of the key. */ + readonly bytes: Uint8Array; + #verifier?: Promise; + + private constructor(bytes: Uint8Array) { + this.bytes = bytes; + } + + /** Wrap the 32 raw bytes of an Ed25519 public key, copying them; throws {@link Failure} `key` otherwise. */ + static fromBytes(bytes: Uint8Array): PublicKey { + if (bytes.byteLength !== KEY_LEN) throw new Failure("key"); + return new PublicKey(Uint8Array.from(bytes)); + } + + /** Parse an endpoint ID; throws {@link Failure} `key` unless it is 64 lowercase hex characters. */ + static parse(text: string): PublicKey { + if (!/^[0-9a-f]{64}$/.test(text)) throw new Failure("key"); + return new PublicKey(Uint8Array.from(text.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16))); + } + + /** Whether `other` is the same key. */ + equals(other: PublicKey): boolean { + return this.bytes.every((byte, i) => byte === other.bytes[i]); + } + + /** The endpoint ID: 64 lowercase hex characters. */ + toString(): string { + return Array.from(this.bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); + } + + /** Whether `signature` is this key's Ed25519 signature over `message`. @internal */ + async verify(message: Uint8Array, signature: Uint8Array): Promise { + this.#verifier ??= crypto.subtle.importKey("raw", this.bytes, ED25519, false, ["verify"]); + return crypto.subtle.verify(ED25519, await this.#verifier, signature, message); + } +} + +/** An endpoint's Ed25519 secret key. The private half stays a nonextractable `CryptoKey`. */ +export class SecretKey { + /** The public key, which is this endpoint's ID. */ + readonly public: PublicKey; + #signer: CryptoKey; + + private constructor(signer: CryptoKey, publicKey: PublicKey) { + this.#signer = signer; + this.public = publicKey; + } + + /** Generate a fresh key from the platform's secure random source. */ + static async generate(): Promise { + const pair = await crypto.subtle.generateKey(ED25519, false, ["sign", "verify"]); + const raw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey)); + return new SecretKey(pair.privateKey, PublicKey.fromBytes(raw)); + } + + /** Load the key for a 32-byte seed, as the Rust key file stores it. @internal */ + static async fromSeed(seed: Uint8Array): Promise { + if (seed.byteLength !== KEY_LEN) throw new Failure("key"); + const pkcs8 = new Uint8Array(PKCS8_PREFIX.byteLength + KEY_LEN); + pkcs8.set(PKCS8_PREFIX); + pkcs8.set(seed, PKCS8_PREFIX.byteLength); + const signer = await crypto.subtle.importKey("pkcs8", pkcs8, ED25519, false, ["sign"]); + // An extractable copy only to read the public half back out. + const exported = await crypto.subtle.importKey("pkcs8", pkcs8, ED25519, true, ["sign"]); + const { x } = await crypto.subtle.exportKey("jwk", exported); + pkcs8.fill(0); + const raw = Uint8Array.from(atob((x ?? "").replaceAll("-", "+").replaceAll("_", "/")), (c) => c.charCodeAt(0)); + return new SecretKey(signer, PublicKey.fromBytes(raw)); + } + + /** Sign `message` with Ed25519. @internal */ + async sign(message: Uint8Array): Promise> { + return new Uint8Array(await crypto.subtle.sign(ED25519, this.#signer, message)); + } +} diff --git a/js/sign/src/pump.ts b/js/sign/src/pump.ts new file mode 100644 index 00000000000..c2689acbcd2 --- /dev/null +++ b/js/sign/src/pump.ts @@ -0,0 +1,16 @@ +/** + * Runs tasks one at a time in submit order: one AEAD call in flight, completions in order. + * + * A producer's depth one keeps a frame's ordinal equal to its `@moq/net` write order without + * reservations; the queue is the callers' own pending promises, so awaiting each write is the + * backpressure. A consumer runs only opens through it, never net waits. + */ +export class Pump { + #tail: Promise = Promise.resolve(); + + run(task: () => Promise | T): Promise { + const result = this.#tail.then(task); + this.#tail = result.catch(() => {}); + return result; + } +} diff --git a/js/sign/src/scope.ts b/js/sign/src/scope.ts new file mode 100644 index 00000000000..56b9a3b1d0a --- /dev/null +++ b/js/sign/src/scope.ts @@ -0,0 +1,59 @@ +// The signed message: what a frame's signature binds besides its payload. +import type { Epoch, Path } from "@moq/net"; +import { Failure } from "./failure.ts"; +import type { PublicKey, SecretKey } from "./key.ts"; + +/** Length of the Ed25519 signature appended to every signed frame. */ +export const SIGNATURE_LEN = 64; + +const encoder = new TextEncoder(); +// Domain separation for the profile, with no length prefix of its own. +const LABEL = encoder.encode("moq-sign-00"); + +/** One track of one publisher instance: the identity every frame on it is signed under. */ +export class Scope { + // The canonical prefix: label, path, epoch, and track, each length-prefixed. + #prefix: Uint8Array; + + constructor(path: Path.Valid, epoch: Epoch.Valid, track: string) { + const fields = [path, epoch, track].map((field) => encoder.encode(field)); + this.#prefix = new Uint8Array(LABEL.byteLength + fields.reduce((sum, field) => sum + 8 + field.byteLength, 0)); + const view = new DataView(this.#prefix.buffer); + this.#prefix.set(LABEL); + let offset = LABEL.byteLength; + for (const field of fields) { + view.setBigUint64(offset, BigInt(field.byteLength)); + this.#prefix.set(field, offset + 8); + offset += 8 + field.byteLength; + } + } + + /** The message signed for `payload` at frame `frame` of group `group`. */ + message(group: number, frame: number, payload: Uint8Array): Uint8Array { + const out = new Uint8Array(this.#prefix.byteLength + 16 + payload.byteLength); + const view = new DataView(out.buffer); + out.set(this.#prefix); + view.setBigUint64(this.#prefix.byteLength, BigInt(group)); + view.setBigUint64(this.#prefix.byteLength + 8, BigInt(frame)); + out.set(payload, this.#prefix.byteLength + 16); + return out; + } + + /** The frame body: `payload` followed by its signature. */ + async sign(key: SecretKey, group: number, frame: number, payload: Uint8Array): Promise> { + const signature = await key.sign(this.message(group, frame, payload)); + const body = new Uint8Array(payload.byteLength + SIGNATURE_LEN); + body.set(payload); + body.set(signature, payload.byteLength); + return body; + } + + /** The payload of a frame body whose signature verifies, as a view into `body`; throws {@link Failure} `signature`. */ + async verify(key: PublicKey, group: number, frame: number, body: Uint8Array): Promise { + const split = body.byteLength - SIGNATURE_LEN; + if (split < 0) throw new Failure("signature"); + const payload = body.subarray(0, split); + if (!(await key.verify(this.message(group, frame, payload), body.slice(split)))) throw new Failure("signature"); + return payload; + } +} diff --git a/js/sign/src/sign.test.ts b/js/sign/src/sign.test.ts new file mode 100644 index 00000000000..e8aab8f1934 --- /dev/null +++ b/js/sign/src/sign.test.ts @@ -0,0 +1,178 @@ +// Signed tracks over a real moq-lite session: the subscriber delivers only what verifies. +import { expect, test } from "bun:test"; +import { Milli } from "@moq/clock"; +import { type Broadcast, Connection, Origin, Path, Time } from "@moq/net"; +// The in-memory WebTransport pair @moq/net tests with; not part of its published surface. +import { createMockTransportPair } from "../../net/src/mock.ts"; +import * as Signed from "./broadcast.ts"; +import { Failure } from "./failure.ts"; +import type * as Group from "./group.ts"; +import { type PublicKey, SecretKey } from "./key.ts"; +import { Scope } from "./scope.ts"; +import * as Track from "./track.ts"; + +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); +const url = new URL("https://localhost:4443/test"); +const subscription = { maxDelay: Milli(60_000) }; + +async function session() { + const pair = createMockTransportPair("moq-lite-07-wip"); + const publisher = new Origin.Producer(); + const subscriber = new Origin.Producer(); + const [client, server] = await Promise.all([ + Connection.connect({ url, transport: pair.client, consume: subscriber }), + Connection.accept({ url, transport: pair.server, publish: publisher.consume() }), + ]); + return { + publisher, + subscriber, + close() { + client.abort(); + server.abort(); + }, + }; +} + +async function active(origin: Origin.Producer, path: Path.Valid): Promise { + const request = origin.request(path, { announced: true }); + for (;;) { + const front = request.active.peek(); + if (front) return front; + await request.active.changed(); + } +} + +/** A signed broadcast at `path` on a fresh session, and the raw net broadcast under it. */ +async function publish(key: SecretKey, path: Path.Valid) { + const net = await session(); + const publication = net.publisher.createBroadcast(path); + const signed = new Signed.Producer(publication.broadcast, key, path); + publication.announce({ epoch: signed.epoch }); + return { + ...net, + signed, + /** A signed track over a net track the test can also write forged frames to. */ + track(name: string) { + const raw = publication.broadcast.createTrack(name); + return { signed: Track.Producer.make(raw, key, new Scope(path, signed.epoch, name)), raw }; + }, + async consume(expected: PublicKey): Promise { + return new Signed.Consumer(await active(net.subscriber, path), expected, path); + }, + }; +} + +async function payload(group: Group.Consumer | undefined): Promise { + const frame = await group?.readFrame(); + return frame && decoder.decode(frame.payload); +} + +test("frames roundtrip signed, timestamps included", async () => { + const key = await SecretKey.generate(); + const path = Path.from(`mesh/${key.public}/agent`); + const published = await publish(key, path); + const video = published.signed.createTrack("video", { timescale: Time.Timescale.MILLI }); + + const group = video.appendGroup(); + await group.writeFrame(Time.Timestamp.fromMillis(1), encoder.encode("keyframe")); + await group.writeFrame(Time.Timestamp.fromMillis(2), new Uint8Array()); + + const consumer = await published.consume(key.public); + expect(consumer.epoch).toBe(published.signed.epoch); + const track = consumer.subscribe("video", subscription); + const received = await track.recvGroup(); + const first = await received?.readFrame(); + expect(decoder.decode(first?.payload)).toBe("keyframe"); + expect(first?.timestamp?.as(Time.Timescale.MILLI)).toBe(1); + expect(await payload(received)).toBe(""); + + await group.writeFrame(Time.Timestamp.fromMillis(3), encoder.encode("late")); + group.finish(); + expect(await payload(received)).toBe("late"); + expect(await received?.readFrame()).toBeUndefined(); + + track.close(); + video.finish(); + video.close(); + published.signed.close(); + published.close(); +}); + +test("a forged frame delivers nothing and ends only its group", async () => { + const key = await SecretKey.generate(); + const path = Path.from("mesh/node/ssh"); + const published = await publish(key, path); + const { signed, raw } = published.track("stream"); + const track = (await published.consume(key.public)).subscribe("stream", subscription); + + // A relay's forgery: unsigned frames the length of a signed one. + const forged = raw.appendGroup(); + forged.writeFrame({ payload: new Uint8Array(80) }); + forged.writeFrame({ payload: new Uint8Array(80) }); + forged.finish(); + const group = await track.recvGroup(); + await expect(group?.readFrame()).rejects.toEqual(new Failure("signature")); + await expect(group?.readFrame()).rejects.toEqual(new Failure("signature")); + + const next = signed.appendGroup(); + await next.writeFrame(undefined, encoder.encode("after")); + next.finish(); + expect(await payload(await track.recvGroup())).toBe("after"); + + track.close(); + published.close(); +}); + +test("a frame replayed into another group or track is refused", async () => { + const key = await SecretKey.generate(); + const path = Path.from("mesh/node/ssh"); + const published = await publish(key, path); + const a = published.track("a"); + const b = published.track("b"); + const tap = a.raw.subscribe(); + const consumer = await published.consume(key.public); + const readA = consumer.subscribe("a", subscription); + const readB = consumer.subscribe("b", subscription); + + const group = a.signed.appendGroup(); + await group.writeFrame(undefined, encoder.encode("original")); + group.finish(); + const body = (await (await tap.recvGroup())?.readFrame())?.payload; + if (!body) throw new Error("expected the signed body"); + expect(await payload(await readA.recvGroup())).toBe("original"); + + // Group 1 of the same track. + const replay = a.raw.appendGroup(); + replay.writeFrame({ payload: body }); + replay.finish(); + await expect((await readA.recvGroup())?.readFrame()).rejects.toEqual(new Failure("signature")); + + // The same group and index of another track. + const moved = b.raw.createGroup(0); + moved.writeFrame({ payload: body }); + moved.finish(); + await expect((await readB.recvGroup())?.readFrame()).rejects.toEqual(new Failure("signature")); + + readA.close(); + readB.close(); + tap.close(); + published.close(); +}); + +test("a broadcast signed under another key is refused", async () => { + const impostor = await SecretKey.generate(); + const victim = await SecretKey.generate(); + const path = Path.from(`mesh/${victim.public}/ssh`); + const published = await publish(impostor, path); + const stream = published.signed.createTrack("stream"); + const group = stream.appendGroup(); + await group.writeFrame(undefined, encoder.encode("hello")); + group.finish(); + + const track = (await published.consume(victim.public)).subscribe("stream", subscription); + await expect((await track.recvGroup())?.readFrame()).rejects.toEqual(new Failure("signature")); + + track.close(); + published.close(); +}); diff --git a/js/sign/src/track.ts b/js/sign/src/track.ts new file mode 100644 index 00000000000..9019040baba --- /dev/null +++ b/js/sign/src/track.ts @@ -0,0 +1,123 @@ +/** + * Signing producer and verifying subscriber for one track. + * + * @module + */ +import type { Track as NetTrack } from "@moq/net"; +import * as Group from "./group.ts"; +import type { PublicKey, SecretKey } from "./key.ts"; +import { Pump } from "./pump.ts"; +import type { Scope } from "./scope.ts"; + +/** + * Producer for one signed track. + * + * Every write on the track and its groups runs through one serial pump, so net writes land in + * call order. + */ +export class Producer { + /** The track name. */ + readonly name: string; + + #inner: NetTrack.Producer; + #writer: Group.Writer; + #finished = false; + + private constructor(inner: NetTrack.Producer, key: SecretKey, scope: Scope) { + this.#inner = inner; + this.name = inner.name; + this.#writer = { pump: new Pump(), key, scope, closed: false }; + } + + /** @internal */ + static make(inner: NetTrack.Producer, key: SecretKey, scope: Scope): Producer { + return new Producer(inner, key, scope); + } + + /** The track's final outcome, once its declared end is reached or it aborts. */ + get closed(): NetTrack.Producer["closed"] { + return this.#inner.closed; + } + + /** Start a group at the next sequence. */ + appendGroup(): Group.Producer { + this.#writable(); + return Group.Producer.make(this.#inner.appendGroup(), this.#writer); + } + + /** Start a group at an explicit sequence; throws the net error if the track already holds it. */ + createGroup(sequence: number): Group.Producer { + this.#writable(); + return Group.Producer.make(this.#inner.createGroup(sequence), this.#writer); + } + + /** Declare the end after queued writes. Existing groups may still be written; new groups are refused. Idempotent. */ + finish(): void { + if (this.#finished || this.#writer.closed) return; + this.#finished = true; + void this.#writer.pump.run(() => { + if (!this.#writer.aborted) this.#inner.finish(); + }); + } + + /** Abort the track and its open groups at once, rejecting pending writes. Idempotent. */ + abort(error: Error): void { + if (this.#writer.closed) return; + this.#writer.closed = true; + this.#writer.aborted = error; + this.#inner.abort(error); + } + + /** Release this producer: drain a declared end, or cancel when nothing finished it. Idempotent. */ + close(): void { + if (this.#writer.closed) return; + this.#writer.closed = true; + if (this.#finished) { + void this.#writer.pump.run(() => this.#inner.close()); + } else { + this.#inner.close(); + this.#writer.aborted = this.#inner.closed.peek() ?? undefined; + } + } + + #writable(): void { + if (this.#finished || this.#writer.closed) throw this.#writer.aborted ?? new Error("track is closed"); + } +} + +/** + * Subscriber for one signed track. + * + * Each group verifies on its own: a forged frame ends only the group that carried it. + */ +export class Consumer { + /** The track name. */ + readonly name: string; + + #inner: NetTrack.Subscriber; + #key: PublicKey; + #scope: Scope; + + private constructor(inner: NetTrack.Subscriber, key: PublicKey, scope: Scope) { + this.#inner = inner; + this.name = inner.name; + this.#key = key; + this.#scope = scope; + } + + /** @internal */ + static make(inner: NetTrack.Subscriber, key: PublicKey, scope: Scope): Consumer { + return new Consumer(inner, key, scope); + } + + /** Receive the next group in arrival order, or `undefined` once the track ends. */ + async recvGroup(): Promise { + const group = await this.#inner.recvGroup(); + return group && Group.Consumer.make(group, this.#key, this.#scope); + } + + /** Unsubscribe, releasing track demand. Groups already received end after the frames they hold. Idempotent. */ + close(): void { + this.#inner.close(); + } +} diff --git a/js/sign/src/vectors.test.ts b/js/sign/src/vectors.test.ts new file mode 100644 index 00000000000..baa1e91597b --- /dev/null +++ b/js/sign/src/vectors.test.ts @@ -0,0 +1,67 @@ +// Every vector in drafts/moq-sign-00.json, run against the internal primitives. +import { expect, test } from "bun:test"; +import { Epoch, type Path } from "@moq/net"; +import { Failure } from "./failure.ts"; +import { PublicKey, SecretKey } from "./key.ts"; +import { Scope } from "./scope.ts"; + +type Row = Record; + +const vectors = (await Bun.file(new URL("../../../drafts/moq-sign-00.json", import.meta.url)).json()) as { + keys: Row[]; + frames: Row[]; + negative: Row[]; + invalid_ids: Row[]; +}; + +function unhex(value: unknown): Uint8Array { + return Uint8Array.from(String(value).match(/../g) ?? [], (byte) => Number.parseInt(byte, 16)); +} + +function hex(bytes: Uint8Array): string { + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); +} + +// The vectors' path field is the raw signed text, including an empty one. +function scope(row: Row): Scope { + return new Scope(String(row.path) as Path.Valid, Epoch.parse(String(row.epoch)), String(row.track)); +} + +test("keys", async () => { + for (const row of vectors.keys) { + const key = await SecretKey.fromSeed(unhex(row.seed)); + expect(key.public.toString()).toBe(String(row.public)); + expect(PublicKey.parse(String(row.public)).equals(key.public)).toBe(true); + } +}); + +test("frames", async () => { + for (const row of vectors.frames) { + const s = scope(row); + const [group, frame] = [Number(row.group), Number(row.frame)]; + expect(hex(s.message(group, frame, unhex(row.payload)))).toBe(String(row.message)); + const body = await s.sign(await SecretKey.fromSeed(unhex(row.seed)), group, frame, unhex(row.payload)); + expect(hex(body)).toBe(String(row.body)); + const payload = await s.verify(PublicKey.parse(String(row.public)), group, frame, unhex(row.body)); + expect(hex(payload)).toBe(String(row.payload)); + } +}); + +test("negative", async () => { + for (const row of vectors.negative) { + const verified = scope(row).verify( + PublicKey.parse(String(row.public)), + Number(row.group), + Number(row.frame), + unhex(row.body), + ); + await expect(verified).rejects.toEqual(new Failure("signature")); + } +}); + +test("invalid ids", () => { + for (const row of vectors.invalid_ids) { + expect(() => PublicKey.parse(String(row.text))).toThrow(new Failure("key")); + } + expect(() => PublicKey.fromBytes(new Uint8Array(31))).toThrow(new Failure("key")); +}); diff --git a/js/sign/tsconfig.build.json b/js/sign/tsconfig.build.json new file mode 100644 index 00000000000..b58733f6162 --- /dev/null +++ b/js/sign/tsconfig.build.json @@ -0,0 +1,10 @@ +{ + // Build-only variant of tsconfig.json that keeps tests out of dist/, so they + // are neither published nor discovered by `bun test` at the package root. + // `tsc --noEmit` still uses tsconfig.json, so tests stay type-checked. + "extends": "./tsconfig.json", + "compilerOptions": { + "rootDir": "./src" + }, + "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"] +} diff --git a/js/sign/tsconfig.json b/js/sign/tsconfig.json new file mode 100644 index 00000000000..bfbf10ed73c --- /dev/null +++ b/js/sign/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../tsconfig.json", + "compilerOptions": { + "outDir": "dist", + // The transport test borrows `@moq/net`'s mock transport by relative path, so the + // type-check spans the workspace. The build pins `rootDir` to src and skips tests. + "rootDir": "..", + "types": ["bun"] + }, + "include": ["src"] +} diff --git a/package.json b/package.json index 452d3a43226..99d205b5562 100644 --- a/package.json +++ b/package.json @@ -42,6 +42,7 @@ "js/pattern", "js/auth", "js/e2ee", + "js/sign", "js/flate", "js/json", "js/libav", diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs index f9047fe492d..8c5991e9a06 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-sign/src/tests.rs @@ -352,3 +352,75 @@ fn consumer_without_an_epoch_is_refused() { let result = broadcast::Consumer::new(inner, SecretKey::generate().public(), path); assert!(matches!(result, Err(Error::Epoch))); } + +/// Runs `test/interop/sign.ts` with a JSON argument, returning its JSON stdout. +fn bun(input: Value) -> Value { + let output = std::process::Command::new("bun") + .arg(format!("{}/../../test/interop/sign.ts", env!("CARGO_MANIFEST_DIR"))) + .arg(input.to_string()) + .output() + .expect("Bun must be installed for the interop tests"); + assert!( + output.status.success(), + "sign.ts failed: {}", + String::from_utf8_lossy(&output.stderr) + ); + serde_json::from_slice(&output.stdout).unwrap() +} + +/// Rust-signed groups verify in JS and a relocated one does not; JS-signed groups verify in Rust. +#[test] +#[ignore = "requires Bun; run by just test interop"] +fn sign_interop() { + let mut seed = Zeroizing::new([0u8; 32]); + aws_lc_rs::rand::fill(seed.as_mut()).unwrap(); + let key = SecretKey::from_seed(seed.clone()); + let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public())).unwrap(); + let epoch = moq_net::Epoch::mint(); + + let payloads: [&[u8]; 3] = [b"zero", b"", &[0xff; 300]]; + let expected: Vec = payloads.iter().map(hex::encode).collect(); + // A group's bodies as Rust signs them at `signed_as`, delivered at `group`. + let sign_group = |group: u64, signed_as: u64| { + let scope = Scope::new(&path, &epoch, "video"); + let bodies: Vec = payloads + .iter() + .enumerate() + .map(|(frame, payload)| hex::encode(scope.sign(&key, signed_as, frame as u64, payload))) + .collect(); + serde_json::json!({ "track": "video", "group": group, "bodies": bodies }) + }; + + let output = bun(serde_json::json!({ + "seed": hex::encode(seed.as_ref()), + "path": path.as_str(), + "epoch": epoch.as_str(), + "rust": [sign_group(7, 7), sign_group(8, 7)], + "payloads": [expected, ["6a73"]], + })); + + assert_eq!(output["public"], key.public().to_string()); + assert_eq!(output["verified"][0], serde_json::json!(expected)); + assert_eq!(output["verified"][1], "signature"); + + let js_epoch = output["epoch"].as_str().unwrap().parse().unwrap(); + let groups = output["js"].as_array().unwrap(); + assert_eq!(groups.len(), 2); + for (row, payloads) in groups.iter().zip([expected, vec!["6a73".to_string()]]) { + let scope = Scope::new(&path, &js_epoch, row["track"].as_str().unwrap()); + let group = row["group"].as_u64().unwrap(); + let bodies = row["bodies"].as_array().unwrap(); + let opened: Vec = bodies + .iter() + .enumerate() + .map(|(frame, body)| { + let opened = scope.verify(&key.public(), group, frame as u64, Bytes::from(hex(body))); + hex::encode(opened.unwrap()) + }) + .collect(); + assert_eq!(opened, payloads); + // The same body does not verify at the neighboring group. + let relocated = scope.verify(&key.public(), group + 1, 0, Bytes::from(hex(&bodies[0]))); + assert!(matches!(relocated, Err(Error::Signature))); + } +} diff --git a/test/interop/sign.ts b/test/interop/sign.ts new file mode 100644 index 00000000000..5fc82cec959 --- /dev/null +++ b/test/interop/sign.ts @@ -0,0 +1,66 @@ +/** Exchange signed groups with Rust: verify the ones Rust signed, and sign through the JS wrappers. */ +import assert from "node:assert/strict"; +import { Broadcast, Epoch, Path } from "../../js/net/src/index.ts"; +import * as Signed from "../../js/sign/src/broadcast.ts"; +import { Failure } from "../../js/sign/src/failure.ts"; +import { SecretKey } from "../../js/sign/src/key.ts"; +import { Scope } from "../../js/sign/src/scope.ts"; +import * as Track from "../../js/sign/src/track.ts"; + +/** One group's frame bodies, signature included, as they cross the wire. */ +type Group = { track: string; group: number; bodies: string[] }; +type Input = { seed: string; path: string; epoch: string; rust: Group[]; payloads: string[][] }; + +function unhex(text: string): Uint8Array { + return Uint8Array.from(text.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16)); +} + +function hex(bytes: Uint8Array): string { + return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); +} + +const input = JSON.parse(process.argv[2] ?? "") as Input; +const key = await SecretKey.fromSeed(unhex(input.seed)); +const path = Path.from(input.path); +const epoch = Epoch.parse(input.epoch); + +// Each Rust group through a verifying JS track consumer: its payloads, or the failure code. +const verified: (string[] | string)[] = []; +for (const { track, group, bodies } of input.rust) { + const net = new Broadcast.Producer().createTrack(track); + const consumer = Track.Consumer.make(net.subscribe(), key.public, new Scope(path, epoch, track)); + const writer = net.createGroup(group); + for (const body of bodies) writer.writeFrame({ payload: unhex(body) }); + writer.finish(); + const received = await consumer.recvGroup(); + assert(received); + try { + const payloads: string[] = []; + for (let frame = await received.readFrame(); frame; frame = await received.readFrame()) { + payloads.push(hex(frame.payload)); + } + verified.push(payloads); + } catch (err) { + if (!(err instanceof Failure)) throw err; + verified.push(err.code); + } +} + +// Groups signed through the JS wrappers, tapped raw off the net broadcast. +const inner = new Broadcast.Producer(); +const signed = new Signed.Producer(inner, key, path); +const producer = signed.createTrack("js"); +const tap = inner.consume().track("js").subscribe(); +const js: Group[] = []; +for (const payloads of input.payloads) { + const group = producer.appendGroup(); + for (const payload of payloads) await group.writeFrame(undefined, unhex(payload)); + group.finish(); + const raw = await tap.recvGroup(); + assert(raw); + const bodies: string[] = []; + for (let frame = await raw.readFrame(); frame; frame = await raw.readFrame()) bodies.push(hex(frame.payload)); + js.push({ track: "js", group: raw.sequence, bodies }); +} + +process.stdout.write(JSON.stringify({ public: key.public.toString(), verified, epoch: signed.epoch, js })); diff --git a/test/justfile b/test/justfile index c138ec7c7cd..0569dfb3c27 100644 --- a/test/justfile +++ b/test/justfile @@ -64,13 +64,14 @@ harness: [positional-arguments] interop *args: cd .. && bun install --frozen-lockfile - just rs test -p moq-net --lib \ + just rs test -p moq-net -p moq-sign --lib \ auth_unsupported_interop \ ietf_compression_fallback_interop \ ietf_datagram_interop \ ietf_track_status_interop \ ietf_range_updates_interop \ padding_interop \ + sign_interop \ tracks_interop \ varint_interop \ --run-ignored all From 1f636805e1ae986e963fd33e6d6ee0edb3261903 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:30:47 -0700 Subject: [PATCH 04/10] docs(sign): moq-sign-00 draft, docs, and quest handoff Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 6 +- doc/lib/js/index.md | 1 + doc/lib/rs/index.md | 1 + doc/setup/repository.md | 1 + drafts/draft-lcurley-moq-sign.md | 169 +++++++++++++++++++++++++++++++ js/sign/README.md | 47 +++++++++ quest/m2/mesh/README.md | 1 - quest/m2/mesh/endpoint.md | 8 +- quest/m2/mesh/sign.md | 34 ------- quest/m2/stream/README.md | 5 +- rs/moq-sign/README.md | 42 ++++++++ rs/moq-sign/clippy.toml | 23 +++++ sh/gh/nightly.sh | 4 +- 13 files changed, 298 insertions(+), 44 deletions(-) create mode 100644 drafts/draft-lcurley-moq-sign.md create mode 100644 js/sign/README.md delete mode 100644 quest/m2/mesh/sign.md create mode 100644 rs/moq-sign/README.md create mode 100644 rs/moq-sign/clippy.toml diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 6d56cad8c94..26f1e335128 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -14,7 +14,7 @@ with it, while shipping a simpler profile you can use today. | [moq-transport](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/) | The IETF pub/sub protocol | Drafts 18 and 22 negotiated by ALPN; [moq-lite](/concept/moq-lite) is a forward-compatible subset | | [MSF](https://datatracker.ietf.org/doc/draft-ietf-moq-msf/) | The IETF catalog format | Read and written; broadcasts ending in `.msf` select it | | [LOC](https://datatracker.ietf.org/doc/draft-ietf-moq-loc/) | The IETF low-overhead container | Supported as a hang container kind | -| [moq-lite](/draft/moq-lite), [hang](/draft/moq-hang), [e2ee](/draft/moq-e2ee), and friends | This project's own drafts | Normative for the implementation, published to the datatracker from [`drafts/`](https://github.com/moq-dev/moq/tree/main/drafts) | +| [moq-lite](/draft/moq-lite), [hang](/draft/moq-hang), [e2ee](/draft/moq-e2ee), [sign](/draft/moq-sign), and friends | This project's own drafts | Normative for the implementation, published to the datatracker from [`drafts/`](https://github.com/moq-dev/moq/tree/main/drafts) | ## moq-transport @@ -62,7 +62,9 @@ does not offer it does not carry this state. Only Rust offers the extension, whe `extensions.ietf` is set, and `moq-relay` always does on moq-lite-07. [moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts application payloads, so relays still forward named tracks they cannot read. -See [Encryption](/concept/hang#encryption). +See [Encryption](/concept/hang#encryption). [moq-sign](/draft/moq-sign) is not +one either: it appends an Ed25519 signature to each frame, so relays still +forward and cache frames they cannot forge. ### Deliberate deviations diff --git a/doc/lib/js/index.md b/doc/lib/js/index.md index 08a07917167..d50dbaef861 100644 --- a/doc/lib/js/index.md +++ b/doc/lib/js/index.md @@ -33,6 +33,7 @@ small examples. The [API reference](/lib/js/api/) covers every package; source l | [@moq/json](/lib/js/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | | [@moq/flate](/lib/js/flate) | Opaque payloads over tracks, optionally compressed with group-scoped DEFLATE: snapshots or append logs. | | [@moq/e2ee](https://github.com/moq-dev/moq/tree/main/js/e2ee) | End-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. Workspace-only until the browser components use it. | +| [@moq/sign](https://github.com/moq-dev/moq/tree/main/js/sign) | Per-frame Ed25519 signatures, so relays forward content they cannot forge, replay, or relocate. Workspace-only until the mesh uses it. | | [@moq/loc](/lib/js/api/loc), [@moq/msf](/lib/js/api/msf) | The IETF LOC container and MSF catalog. | | [@moq/boy](/lib/js/api/boy) | The [MoQ Boy](/bin/demo) player element. | diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index ba5dbdab825..3a38169de68 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -37,6 +37,7 @@ see [Applications](/bin/). [Examples](/setup/examples) links runnable consumers; | [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | | [moq-flate](/lib/rs/moq-flate) | Opaque payloads over tracks, optionally compressed with group-scoped DEFLATE: snapshots or append logs. | | [moq-e2ee](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee) | Workspace-only end-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. | +| [moq-sign](https://github.com/moq-dev/moq/tree/main/rs/moq-sign) | Workspace-only per-frame Ed25519 signatures, so relays forward content they cannot forge, replay, or relocate. | | [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. | | [moq-stats](https://docs.rs/moq-stats) | Publish and consume relay traffic counters as tracks. | | [moq-clock](/lib/rs/moq-clock) | One clock for time and timers on tokio, the browser, and a deterministic test simulator. | diff --git a/doc/setup/repository.md b/doc/setup/repository.md index fa64a993050..74264d780b3 100644 --- a/doc/setup/repository.md +++ b/doc/setup/repository.md @@ -32,6 +32,7 @@ wrap the Rust core. [Layers](/lib/layers) maps the binding namespaces. | Language bindings | [`rs/moq-ffi`](https://github.com/moq-dev/moq/tree/main/rs/moq-ffi), [`rs/moq-c`](https://github.com/moq-dev/moq/tree/main/rs/moq-c), then `py/`, `swift/`, `kt/`, `go/`, `dart/`, or `cpp/moq/` | [Binding layers](/lib/layers) | | Rooms, chat, and application data | [`rs/moq-room`](https://github.com/moq-dev/moq/tree/main/rs/moq-room), [`js/room`](https://github.com/moq-dev/moq/tree/main/js/room), `rs/moq-json`, `js/json` | [Rooms](/lib/js/room), [JSON tracks](/lib/js/json) | | End-to-end encryption | [`rs/moq-e2ee`](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee), [`js/e2ee`](https://github.com/moq-dev/moq/tree/main/js/e2ee) | [Media encryption](/concept/hang), [E2EE draft](/draft/moq-e2ee) | +| Signed content | [`rs/moq-sign`](https://github.com/moq-dev/moq/tree/main/rs/moq-sign), [`js/sign`](https://github.com/moq-dev/moq/tree/main/js/sign) | [Signing draft](/draft/moq-sign) | | Async primitives and deterministic time | [`rs/kio`](https://github.com/moq-dev/moq/tree/main/rs/kio), [`rs/moq-clock`](https://github.com/moq-dev/moq/tree/main/rs/moq-clock), [`js/clock`](https://github.com/moq-dev/moq/tree/main/js/clock) | [Rust conventions](/lib/rs/#conventions), [clock](/lib/js/clock) | ## Find the surrounding work diff --git a/drafts/draft-lcurley-moq-sign.md b/drafts/draft-lcurley-moq-sign.md new file mode 100644 index 00000000000..8216c086f1a --- /dev/null +++ b/drafts/draft-lcurley-moq-sign.md @@ -0,0 +1,169 @@ +--- +title: "MoQ Per-Frame Signature Profile" +abbrev: "moq-sign" +category: info + +docname: draft-lcurley-moq-sign-latest +submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" +number: +date: +v: 3 +area: wit +workgroup: moq + +author: + - + fullname: Luke Curley + email: kixelated@gmail.com + +normative: + moql: I-D.lcurley-moq-lite + RFC4648: + RFC8032: + +informative: + moqt: I-D.ietf-moq-transport + e2ee: I-D.lcurley-moq-e2ee + iroh: + title: "iroh" + target: https://github.com/n0-computer/iroh + +--- abstract + +This document specifies moq-sign-00, a versioned profile that authenticates MoQ application payloads with a per-frame Ed25519 signature. +A publisher signs each grouped frame with its endpoint key, binding the broadcast path, the publisher epoch, the track, the group, and the frame index. +A subscriber that expects that key delivers a frame only after its signature verifies, so a relay can forward and cache content without forging, replaying, or relocating it. + +--- note_Note_to_Readers + +This document was generated by an AI model from the implementation at [github.com/moq-dev/moq](https://github.com/moq-dev/moq) and is maintained alongside it. +Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.com/moq-dev/moq/pulls) if this spec sucks and you want to fix anything. + +--- middle + +# Conventions and Definitions +{::boilerplate bcp14-tagged} + + +# Introduction +MoQ relays forward named tracks of groups and frames ({{moql}}, {{moqt}}) without parsing application payloads. +Transport security protects each hop, but a relay terminates it and can rewrite whatever it forwards. +This profile lets a subscriber check that every frame it delivers came from the publisher it expects, unmodified and at the position the publisher wrote it. + +A signature per frame costs 64 bytes and one verification, and adds no delay beyond receiving the whole frame: no hash chain or checkpoint has to arrive first. +The profile provides authenticity, not confidentiality; {{e2ee}} encrypts payloads and can be layered beneath it. + + +# Profile Version +This document defines profile `moq-sign-00`. +Both ends agree on the profile out of band; a subscriber MUST NOT accept unsigned frames, or another profile, because an announcement, catalog, or peer suggested one. + + +# Endpoint Key {#key} +A publisher holds an Ed25519 key pair ({{RFC8032}}). +The 32-byte public key is the endpoint ID. +Its text form is the lowercase base16 encoding ({{RFC4648}} Section 8) of the key: 64 characters, the form {{iroh}} displays. +An implementation MUST refuse other text, including uppercase, so one key has exactly one ID. + +The key identifies an endpoint for as long as the endpoint exists. +An implementation MUST NOT replace a stored key that fails to load; that would silently change the endpoint's identity. + +How a subscriber learns the key it expects is out of scope. +An application can, for example, publish each endpoint's broadcasts under a path containing its ID, so the subscriber reads the key from the path it subscribes to. + + +# Signed Message {#message} +Integers are unsigned big-endian of the stated width, and `bytes(x)` is `u64(length) || x`. + +~~~ +message = "moq-sign-00" + || bytes(path) + || bytes(epoch) + || bytes(track) + || u64(group) + || u64(frame) + || payload +~~~ + +**path**: +The UTF-8 broadcast path both ends name the broadcast by. +A relay may mount a broadcast under another prefix, so this is the application's path, not the one a transport hop reports. + +**epoch**: +The UUID text of the publisher instance's epoch, carried on the broadcast's route ({{moql}}). +A publisher instance MUST sign under an epoch it minted and no other instance has used. + +**track**: +The UTF-8 track name. +A subscriber uses the name it subscribed to, never one a relay reports. + +**group**: +The group sequence. + +**frame**: +The frame's index within its group. +moq-lite numbers frames from 0 in write order; on MoQ Transport this is the Object ID, which a publisher assigns contiguously from zero. + +**payload**: +The application bytes. + +Each length prefix keeps one field's bytes from shifting into the next. +Timestamps and other frame properties are not signed. + + +# Frame Body {#body} +The frame carried by MoQ is the payload followed by the 64-byte Ed25519 signature of the message. + +~~~ +body = payload || Ed25519-Sign(secret_key, message) +~~~ + +A body shorter than 64 bytes, or whose signature does not verify ({{RFC8032}} Section 5.1.7) under the expected key at the frame's identity, is a `signature` failure. + + +# Failure Behavior {#failure} +A subscriber MUST NOT deliver any byte of a frame before its signature verifies. + +A `signature` failure ends that group for the subscriber: it MUST deliver no later frame of the group. +Other groups of the track continue, since each verifies on its own. + +A subscriber that cannot learn the broadcast's epoch from its route MUST refuse to read it (`epoch`). + +Datagrams are not covered by this profile; a subscriber MUST NOT deliver datagrams from a track it reads under it. + + +# Test Vectors {#vectors} +Known-answer and negative vectors live in `moq-sign-00.json` beside this draft. +Hex strings are octet sequences. +The file covers key derivation from a seed, including {{RFC8032}} Section 7.1 TEST 1; signed messages and bodies for an empty payload, groups and frame indices above 32 bits, an empty path, and a non-ASCII track; relocation across every identity field, including a byte shifted between two fields; a wrong key; tampered payloads and signatures; truncated, extended, and empty bodies; and endpoint ID text that MUST be refused. + + +# Security Considerations +Relays, caches, and recorders are untrusted for content. +The publisher's secret key is trusted; anyone holding it can sign as that endpoint. + +The signature binds every field a relay could otherwise change to move an authentic frame: the path, the epoch, the track, the group, and the frame index. +Binding the epoch keeps a frame from an earlier instance of the same broadcast, which restarted its sequences, from verifying in a later one. + +A relay can still delay, drop, or reorder groups, end a group after any frame, and rewrite timestamps. +Nothing authenticates where a group ends, so an application MUST NOT treat a group's end as authentic. +A relay that presents a wrong epoch only causes `signature` failures. + +A relay can observe everything a signature does not hide: paths, epochs, track names, payloads, sizes, and timing. + +Ed25519 signing is deterministic, so no per-signature randomness can leak the key. + + +# IANA Considerations +This document requests no registrations. + + +--- back + +# Changelog +{:numbered="false"} + +## draft-lcurley-moq-sign-00 +{:numbered="false"} + +- Initial `moq-sign-00` profile: Ed25519 endpoint keys with a lowercase hex ID, a message binding path, epoch, track, group, and frame index, a payload-then-signature frame body, group-ending failures, and shared vectors. diff --git a/js/sign/README.md b/js/sign/README.md new file mode 100644 index 00000000000..e0b461fd9fc --- /dev/null +++ b/js/sign/README.md @@ -0,0 +1,47 @@ +

+ Media over QUIC +

+ +# @moq/sign + +Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile +`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/), +interoperable with the Rust `moq-sign` crate. + +Relays forward and cache signed frames; they cannot forge, replay, or relocate them. + +## Shape + +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 64 lowercase +hex characters. `SecretKey.generate()` keeps the private half a nonextractable `CryptoKey`. + +`Broadcast.Producer` wraps the `@moq/net` broadcast, mints a fresh epoch, and signs each frame +over the application path, epoch, track, group, and frame index. Announce the broadcast with that +epoch on its route: + +```ts +import { Broadcast, SecretKey } from "@moq/sign"; +import { Path } from "@moq/net"; + +const key = await SecretKey.generate(); +const path = Path.from(`mesh/${key.public}/agent`); +const publication = origin.createBroadcast(path); +const signed = new Broadcast.Producer(publication.broadcast, key, path); +const messages = signed.createTrack("messages"); +publication.announce({ epoch: signed.epoch }); + +const group = messages.appendGroup(); +await group.writeFrame(undefined, payload); +group.finish(); +``` + +A subscriber wraps the broadcast an origin resolved in a `Broadcast.Consumer` with the key it +expects and the same application path; it takes the epoch from the route. A frame reaches the +application only after it verifies. A forged or relocated frame ends its group with `Failure` +code `signature`, and the track keeps delivering other groups. + +## Processing + +WebCrypto Ed25519 is asynchronous, so writes return promises. Each track producer runs one serial +pump: one signature in flight, net writes in call order, so a frame's index always matches its +transport position. Await each write for backpressure. diff --git a/quest/m2/mesh/README.md b/quest/m2/mesh/README.md index 14bd6da1f24..4b29757e254 100644 --- a/quest/m2/mesh/README.md +++ b/quest/m2/mesh/README.md @@ -62,7 +62,6 @@ relay path to the third, surviving a relay restart. - [Outbound federation](/quest/m1/cluster-routing/federation.md) - a local relay dials its relays and prefers LAN peers - [Byte streams](/quest/m2/stream/README.md) - lossless TCP-level streams over MoQ - [Enrollment](/quest/m2/mesh/enroll.md) - a device proves its key and gets a relay URL and a scoped token, by device grant or a pre-authorized key -- [Signed broadcasts](/quest/m2/mesh/sign.md) - endpoint keys, per-frame signatures, and per-broadcast protection levels - [Endpoint API](/quest/m2/mesh/endpoint.md) - an iroh-shaped `Endpoint` that connects to an endpoint ID and service and accepts byte streams - [Daemon](/quest/m2/mesh/daemon.md) - `moq mesh up`, `serve`, `pipe`, and `install`, with SSH by ID on two hosts - [Robots](/quest/m2/mesh/robot.md) - aarch64 builds and a robot-shaped node surviving a flapping uplink diff --git a/quest/m2/mesh/endpoint.md b/quest/m2/mesh/endpoint.md index f22e75052b0..b5f87698aea 100644 --- a/quest/m2/mesh/endpoint.md +++ b/quest/m2/mesh/endpoint.md @@ -15,8 +15,11 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, `EndpointAddr`, and `Router` are out unless porting proves they are needed. - A service is the iroh ALPN analog: a name under `mesh//`. -- Streams are [byte streams](/quest/m2/stream/rust.md) with the - [signing](/quest/m2/mesh/sign.md) level the service declares. +- Streams are [byte streams](/quest/m2/stream/rust.md) at the protection + level the service declares: identity reads `moq-net` directly, and + authentication, the mesh default, reads through `moq-sign` against the + `PublicKey` parsed from the `mesh//` path it subscribes to. +- The secret key comes from `moq_sign::SecretKey::load_or_generate`. - The [daemon](/quest/m2/mesh/daemon.md) is built on this API, so a process either embeds an `Endpoint` or talks to the local daemon's relay. - Write a short porting note into the [guide](/quest/m2/mesh/guide.md). @@ -24,4 +27,3 @@ Decided 2026-10-25 (maintainer): iroh-shaped, not drop-in compatible; tickets, ## Required - [Rust byte streams](/quest/m2/stream/rust.md) - the stream this API returns -- [Signed broadcasts](/quest/m2/mesh/sign.md) - endpoint keys and verification diff --git a/quest/m2/mesh/sign.md b/quest/m2/mesh/sign.md deleted file mode 100644 index 3e537cdeef6..00000000000 --- a/quest/m2/mesh/sign.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] Signed broadcasts - -## Goal - -A node's persistent Ed25519 endpoint key signs every frame it publishes at the -authentication level, and subscribers deliver only frames that verify against -the endpoint ID in the broadcast path, so a relay can proxy without being able -to forge or splice content. Each broadcast picks its level: identity or -authentication, with authentication the mesh default. Rust and JS interoperate. - -## Plan - -Decided 2026-10-25 (maintainer): per-frame signatures, not hash chains or -per-group checkpoints; zero verification delay is worth 64 B per frame. The -endpoint ID is the public key in an iroh-style text encoding, persisted with -`0600` permissions and never rotated implicitly. - -- Bind each signature to the broadcast path, track, group, and frame index, so - a relay cannot replay, reorder, or move a frame between tracks. -- At the authentication and encryption levels a frame reaches the - application only after it verifies; a frame that fails ends its group with a - typed error, which a [byte stream](/quest/m2/stream/README.md) surfaces as a - reset. Only the identity level flushes partial frames as they arrive - (decided 2026-10-25, maintainer). A stream's frame is one socket read, so the - sender's frame-size cap bounds the added latency. -- Identity level carries no signature and trusts the token's path binding. -- Encryption nests on top later ([mesh keys](/quest/m3/mesh-keys.md)): keep - room for it without building it. -- If the format is new wire bytes, specify it in a draft beside - `draft-lcurley-moq-e2ee` with shared vectors; `just drafts check` passes. - -Tests: a forged frame delivering zero bytes to the application, a forged frame, a frame replayed from another group or track, and a -broadcast published under someone else's ID all refused; Rust/JS interop in -`just test interop`. diff --git a/quest/m2/stream/README.md b/quest/m2/stream/README.md index 0c1111f160f..ea8fbad4505 100644 --- a/quest/m2/stream/README.md +++ b/quest/m2/stream/README.md @@ -22,8 +22,9 @@ Decided 2026-10-25 with the maintainer (mesh planning interview): is written and a read has one. It coalesces whatever is buffered with no added timer (the local socket's own Nagle or `TCP_NODELAY` still applies). - The receiver flushes a frame's bytes to its socket as they arrive, never - waiting for the whole frame, unless the mesh's - [authentication](/quest/m2/mesh/sign.md) must verify it first. + waiting for the whole frame, unless the mesh's authentication level + (`moq-sign`) must verify it first; a frame that fails verification ends its + group with a typed error, surfaced as a reset. Group finish is a FIN (half-close); a group abort with a code is a reset. The implementer measures and records a frame-size cap. - Lossless delivery comes from diff --git a/rs/moq-sign/README.md b/rs/moq-sign/README.md new file mode 100644 index 00000000000..b6e76ac19a6 --- /dev/null +++ b/rs/moq-sign/README.md @@ -0,0 +1,42 @@ +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/moq-dev/moq/blob/main/LICENSE-MIT) + +# moq-sign + +Workspace-only implementation; this crate is not published. + +Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile +`moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). + +Relays forward and cache signed frames; they cannot forge, replay, or relocate them. + +## Shape + +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 64 lowercase +hex characters. `SecretKey::load_or_generate(path)` keeps one key for the life of a host, in a +`0600` file it never replaces implicitly. + +`broadcast::Producer` wraps the `moq-net` broadcast, mints a fresh epoch, and signs each frame +over the application path, epoch, track, group, and frame index. Announce the broadcast with that +epoch on its route: + +```rust +let key = SecretKey::load_or_generate("/var/lib/moq/endpoint.key")?; +let path = moq_net::Path::new(&format!("mesh/{}/agent", key.public()))?; +let publication = origin.create_broadcast(&path)?; +let signed = broadcast::Producer::new(publication.broadcast().clone(), key, path); +let messages = signed.create_track("messages", None)?; +publication.announce(Route::default().with_epoch(signed.epoch().clone()))?; +``` + +A subscriber wraps the broadcast an origin resolved in a `broadcast::Consumer` with the key it +expects and the same application path; it takes the epoch from the route. A frame reaches the +application only after it verifies. A forged or relocated frame ends its group with +`Error::Signature`, and the track keeps delivering other groups. + +A broadcast at the identity level, which trusts the relay's token check alone, uses `moq-net` +directly. + +## Processing + +Signing is inline and synchronous. `cargo bench -p moq-sign` measures it: a 1 KiB frame costs +about 8 µs to sign and 32 µs to sign and verify through an origin on one core. diff --git a/rs/moq-sign/clippy.toml b/rs/moq-sign/clippy.toml new file mode 100644 index 00000000000..d5a7b48f913 --- /dev/null +++ b/rs/moq-sign/clippy.toml @@ -0,0 +1,23 @@ +# Production uses the ambient clock; legacy test-only clock cleanup is tracked separately. +disallowed-methods = [ + { path = "std::time::Instant::now", reason = "read the ambient clock: moq_clock::now()" }, + { path = "std::time::Instant::elapsed", reason = "read the ambient clock: moq_clock::Instant::elapsed()" }, + { path = "std::time::SystemTime::now", reason = "read the ambient clock: moq_clock::wall()" }, + { path = "std::time::SystemTime::elapsed", reason = "wall time never measures elapsed time" }, + { path = "std::thread::sleep", reason = "sleep on the ambient clock: moq_clock::sleep()" }, + { path = "tokio::time::Instant::now", reason = "read the ambient clock: moq_clock::now()" }, + { path = "tokio::time::sleep", reason = "sleep on the ambient clock: moq_clock::sleep()" }, + { path = "tokio::time::sleep_until", reason = "sleep on the ambient clock: moq_clock::sleep_until()" }, + { path = "tokio::time::timeout", reason = "use the ambient clock: moq_clock::timeout()" }, + { path = "tokio::time::interval", reason = "use the ambient clock: moq_clock::interval()" }, + { path = "tokio::time::timeout_at", reason = "use deadlines from the ambient clock" }, + { path = "tokio::time::interval_at", reason = "tick on the ambient clock" }, +] + +disallowed-types = [ + { path = "std::time::SystemTime", reason = "use moq_clock::Wall" }, + { path = "std::time::Instant", reason = "use moq_clock::Instant" }, + { path = "tokio::time::Instant", reason = "use moq_clock::Instant" }, + { path = "tokio::time::Sleep", reason = "use moq_clock::Sleep" }, + { path = "tokio::time::Interval", reason = "use moq_clock::Interval" }, +] diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 876f702d46d..9da73a0151c 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -121,9 +121,9 @@ case "$1" in rust-extra) # The allocation/window/play-buffer tables keep their stdout in the run; # only Criterion estimates enter the trend report. - criterion extra --no-fail-fast -p moq-e2ee -p moq-json -p moq-archive -p moq-cli -p moq-mux -p moq-audio \ + criterion extra --no-fail-fast -p moq-e2ee -p moq-sign -p moq-json -p moq-archive -p moq-cli -p moq-mux -p moq-audio \ -p moq-quic --features moq-quic/fuzz \ - --bench protect --bench codec --bench table --bench allocations --bench window \ + --bench protect --bench sign --bench codec --bench table --bench allocations --bench window \ --bench producer --bench play_buffer --bench jitter --bench decode_clock --bench ts_programs --bench ts_video \ --bench bus --bench parameter_sets --bench sent_packets ;; From a86be3dca3da21001d21bc987a718398c6cd6674 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:48:55 -0700 Subject: [PATCH 05/10] refactor(sign): keep key bytes and signature length private Co-Authored-By: Claude Opus 5.5 --- js/sign/src/index.ts | 1 - js/sign/src/key.ts | 13 ++++++------ js/sign/src/scope.ts | 4 ++-- rs/moq-sign/benches/sign.rs | 5 ++++- rs/moq-sign/src/broadcast.rs | 6 +----- rs/moq-sign/src/key.rs | 21 +++++++++----------- rs/moq-sign/src/lib.rs | 1 - rs/moq-sign/src/scope.rs | 2 +- rs/moq-sign/src/tests.rs | 38 +++++++++++++++++++++++++++++------- 9 files changed, 54 insertions(+), 37 deletions(-) diff --git a/js/sign/src/index.ts b/js/sign/src/index.ts index 8a3e612e0e6..e1e10528ac0 100644 --- a/js/sign/src/index.ts +++ b/js/sign/src/index.ts @@ -34,6 +34,5 @@ export { type Code, Failure } from "./failure.ts"; /** Signing writer and verifying reader for one group. */ export * as Group from "./group.ts"; export { PublicKey, SecretKey } from "./key.ts"; -export { SIGNATURE_LEN } from "./scope.ts"; /** Signing producer and verifying subscriber for one track. */ export * as Track from "./track.ts"; diff --git a/js/sign/src/key.ts b/js/sign/src/key.ts index bc95756dbb8..3ffd267985a 100644 --- a/js/sign/src/key.ts +++ b/js/sign/src/key.ts @@ -19,15 +19,14 @@ const PKCS8_PREFIX = Uint8Array.from([ * accepts only that form, so one key has exactly one ID to name a path by. */ export class PublicKey { - /** The 32 raw bytes of the key. */ - readonly bytes: Uint8Array; + #bytes: Uint8Array; #verifier?: Promise; private constructor(bytes: Uint8Array) { - this.bytes = bytes; + this.#bytes = bytes; } - /** Wrap the 32 raw bytes of an Ed25519 public key, copying them; throws {@link Failure} `key` otherwise. */ + /** Wrap the 32 raw bytes of an Ed25519 public key, copying them; throws {@link Failure} `key` otherwise. @internal */ static fromBytes(bytes: Uint8Array): PublicKey { if (bytes.byteLength !== KEY_LEN) throw new Failure("key"); return new PublicKey(Uint8Array.from(bytes)); @@ -41,17 +40,17 @@ export class PublicKey { /** Whether `other` is the same key. */ equals(other: PublicKey): boolean { - return this.bytes.every((byte, i) => byte === other.bytes[i]); + return this.#bytes.every((byte, i) => byte === other.#bytes[i]); } /** The endpoint ID: 64 lowercase hex characters. */ toString(): string { - return Array.from(this.bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); + return Array.from(this.#bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); } /** Whether `signature` is this key's Ed25519 signature over `message`. @internal */ async verify(message: Uint8Array, signature: Uint8Array): Promise { - this.#verifier ??= crypto.subtle.importKey("raw", this.bytes, ED25519, false, ["verify"]); + this.#verifier ??= crypto.subtle.importKey("raw", this.#bytes, ED25519, false, ["verify"]); return crypto.subtle.verify(ED25519, await this.#verifier, signature, message); } } diff --git a/js/sign/src/scope.ts b/js/sign/src/scope.ts index 56b9a3b1d0a..0d904617452 100644 --- a/js/sign/src/scope.ts +++ b/js/sign/src/scope.ts @@ -3,8 +3,8 @@ import type { Epoch, Path } from "@moq/net"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; -/** Length of the Ed25519 signature appended to every signed frame. */ -export const SIGNATURE_LEN = 64; +// Length of the Ed25519 signature appended to every signed frame. +const SIGNATURE_LEN = 64; const encoder = new TextEncoder(); // Domain separation for the profile, with no length prefix of its own. diff --git a/rs/moq-sign/benches/sign.rs b/rs/moq-sign/benches/sign.rs index 3dc29f72c00..b879206ff3c 100644 --- a/rs/moq-sign/benches/sign.rs +++ b/rs/moq-sign/benches/sign.rs @@ -61,7 +61,10 @@ fn bench_sign(c: &mut Criterion) { }); }); group.bench_function(format!("roundtrip_{}k", size / 1024), |b| { - let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap(); + let runtime = tokio::runtime::Builder::new_current_thread() + .enable_all() + .build() + .unwrap(); let (producer, mut consumer, _origin) = runtime.block_on(roundtrip(&key)); let waiter = kio::Waiter::noop(); b.iter(|| { diff --git a/rs/moq-sign/src/broadcast.rs b/rs/moq-sign/src/broadcast.rs index da48de52e14..b1452e6fe95 100644 --- a/rs/moq-sign/src/broadcast.rs +++ b/rs/moq-sign/src/broadcast.rs @@ -41,11 +41,7 @@ impl Producer { /// # Errors /// /// A net error if the broadcast already holds the name or has ended. - pub fn create_track( - &self, - name: &str, - info: impl Into>, - ) -> Result { + pub fn create_track(&self, name: &str, info: impl Into>) -> Result { let inner = self.inner.create_track(name, info)?; let scope = Scope::new(&self.path, &self.epoch, name); Ok(track::Producer::new(inner, self.key.clone(), scope)) diff --git a/rs/moq-sign/src/key.rs b/rs/moq-sign/src/key.rs index f1c9f0fb49b..ab033f3d80f 100644 --- a/rs/moq-sign/src/key.rs +++ b/rs/moq-sign/src/key.rs @@ -21,19 +21,11 @@ const KEY_LEN: usize = 32; pub struct PublicKey([u8; KEY_LEN]); impl PublicKey { - /// Wrap the 32 raw bytes of an Ed25519 public key. - pub fn from_bytes(bytes: [u8; KEY_LEN]) -> Self { - Self(bytes) - } - - /// The 32 raw bytes of the key. - pub fn as_bytes(&self) -> &[u8; KEY_LEN] { - &self.0 - } - /// Whether `signature` is this key's Ed25519 signature over `message`. pub(crate) fn verify(&self, message: &[u8], signature: &[u8; SIGNATURE_LEN]) -> bool { - UnparsedPublicKey::new(&ED25519, &self.0).verify(message, signature).is_ok() + UnparsedPublicKey::new(&ED25519, &self.0) + .verify(message, signature) + .is_ok() } } @@ -93,7 +85,12 @@ impl SecretKey { pub(crate) fn from_seed(seed: Zeroizing<[u8; KEY_LEN]>) -> Self { let pair = Ed25519KeyPair::from_seed_unchecked(seed.as_ref()).expect("a 32-byte Ed25519 seed"); - let public = PublicKey(pair.public_key().as_ref().try_into().expect("a 32-byte Ed25519 public key")); + let public = PublicKey( + pair.public_key() + .as_ref() + .try_into() + .expect("a 32-byte Ed25519 public key"), + ); Self(Arc::new(Inner { seed, pair, public })) } diff --git a/rs/moq-sign/src/lib.rs b/rs/moq-sign/src/lib.rs index a20bbc4454a..5eb1e3984bb 100644 --- a/rs/moq-sign/src/lib.rs +++ b/rs/moq-sign/src/lib.rs @@ -27,7 +27,6 @@ mod scope; pub use error::{Error, Result}; pub use key::{InvalidKey, PublicKey, SecretKey}; -pub use scope::SIGNATURE_LEN; #[cfg(test)] mod tests; diff --git a/rs/moq-sign/src/scope.rs b/rs/moq-sign/src/scope.rs index c23a15c6ee7..2a61fd75910 100644 --- a/rs/moq-sign/src/scope.rs +++ b/rs/moq-sign/src/scope.rs @@ -8,7 +8,7 @@ use crate::error::{Error, Result}; use crate::key::{PublicKey, SecretKey}; /// Length of the Ed25519 signature appended to every signed frame. -pub const SIGNATURE_LEN: usize = 64; +pub(crate) const SIGNATURE_LEN: usize = 64; /// Domain separation for the profile, with no length prefix of its own. const LABEL: &[u8] = b"moq-sign-00"; diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs index 8c5991e9a06..d15baa24c03 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-sign/src/tests.rs @@ -38,7 +38,12 @@ fn identity(row: &Value) -> (Arc, u64, u64) { fn vector_keys() { for row in vectors()["keys"].as_array().unwrap() { let key = seed(&row["seed"]); - assert_eq!(key.public().to_string(), row["public"].as_str().unwrap(), "{}", row["id"]); + assert_eq!( + key.public().to_string(), + row["public"].as_str().unwrap(), + "{}", + row["id"] + ); assert_eq!(key.public(), public(&row["public"])); } } @@ -71,7 +76,11 @@ fn vector_negative() { #[test] fn vector_invalid_ids() { for row in vectors()["invalid_ids"].as_array().unwrap() { - assert!(row["text"].as_str().unwrap().parse::().is_err(), "{}", row["id"]); + assert!( + row["text"].as_str().unwrap().parse::().is_err(), + "{}", + row["id"] + ); } } @@ -188,7 +197,10 @@ async fn roundtrip_through_an_origin() { let published = publish(&key, "mesh/node/ssh"); let video = published .signed - .create_track("video", moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI)) + .create_track( + "video", + moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + ) .unwrap(); let consumer = published.consume(key.public()).await; assert_eq!(consumer.epoch(), published.signed.epoch()); @@ -258,26 +270,38 @@ async fn frame_replayed_from_another_group_or_track_is_refused() { group.write_frame(None, b"original").unwrap(); group.finish().unwrap(); let body = raw_frame(&mut raw).await; - assert_eq!(read(&mut recv_group(&mut a).await).await.unwrap().unwrap(), &b"original"[..]); + assert_eq!( + read(&mut recv_group(&mut a).await).await.unwrap().unwrap(), + &b"original"[..] + ); // The same bytes as group 1 of the same track. let mut replay = net.append_group().unwrap(); replay.write_frame(None, body.clone()).unwrap(); replay.finish().unwrap(); - assert!(matches!(read(&mut recv_group(&mut a).await).await, Err(Error::Signature))); + assert!(matches!( + read(&mut recv_group(&mut a).await).await, + Err(Error::Signature) + )); // The same bytes at the same group and index of another track. let mut moved = other_net.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); moved.write_frame(None, body.clone()).unwrap(); moved.finish().unwrap(); - assert!(matches!(read(&mut recv_group(&mut b).await).await, Err(Error::Signature))); + assert!(matches!( + read(&mut recv_group(&mut b).await).await, + Err(Error::Signature) + )); // The same bytes at frame 1 of a group at the original sequence's neighbor. let mut shifted = net.append_group().unwrap(); shifted.write_frame(None, b"filler".as_slice()).unwrap(); shifted.write_frame(None, body).unwrap(); shifted.finish().unwrap(); - assert!(matches!(read(&mut recv_group(&mut a).await).await, Err(Error::Signature))); + assert!(matches!( + read(&mut recv_group(&mut a).await).await, + Err(Error::Signature) + )); } #[tokio::test(start_paused = true)] From e130bff578c2b5d533c99bdca0d6cf04c4c65eff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:12:55 -0700 Subject: [PATCH 06/10] fix(sign): follow main's bench harness and request/follow renames Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 2 +- js/sign/src/sign.test.ts | 2 +- rs/moq-sign/Cargo.toml | 2 +- rs/moq-sign/benches/sign.rs | 2 +- rs/moq-sign/src/tests.rs | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 65f9f4d28b9..6f973a49f66 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5895,8 +5895,8 @@ name = "moq-sign" version = "0.0.1" dependencies = [ "aws-lc-rs", + "bench-harness", "bytes", - "criterion", "hex", "kio 0.6.2", "moq-net", diff --git a/js/sign/src/sign.test.ts b/js/sign/src/sign.test.ts index e8aab8f1934..e71b1414167 100644 --- a/js/sign/src/sign.test.ts +++ b/js/sign/src/sign.test.ts @@ -35,7 +35,7 @@ async function session() { } async function active(origin: Origin.Producer, path: Path.Valid): Promise { - const request = origin.request(path, { announced: true }); + const request = origin.follow(path); for (;;) { const front = request.active.peek(); if (front) return front; diff --git a/rs/moq-sign/Cargo.toml b/rs/moq-sign/Cargo.toml index 58eeed033de..130c19fb622 100644 --- a/rs/moq-sign/Cargo.toml +++ b/rs/moq-sign/Cargo.toml @@ -23,7 +23,7 @@ thiserror = { workspace = true } zeroize = { workspace = true } [dev-dependencies] -criterion = { workspace = true } +criterion = { package = "bench-harness", path = "../bench-harness" } serde_json = { workspace = true } tempfile = { workspace = true } tokio = { workspace = true, features = ["macros", "rt", "test-util"] } diff --git a/rs/moq-sign/benches/sign.rs b/rs/moq-sign/benches/sign.rs index b879206ff3c..06669bd31b1 100644 --- a/rs/moq-sign/benches/sign.rs +++ b/rs/moq-sign/benches/sign.rs @@ -38,7 +38,7 @@ async fn roundtrip( publication .announce(moq_net::origin::Route::default().with_epoch(signed.epoch().clone())) .unwrap(); - let inner = origin.consume().request_broadcast(&path, None).await.unwrap(); + let inner = origin.consume().request(&path, None).await.unwrap(); let consumer = broadcast::Consumer::new(inner, key.public(), path).unwrap(); let subscription = moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(60)); let consumer = consumer.subscribe("stream", subscription).unwrap().await.unwrap(); diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs index d15baa24c03..74040ba48d1 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-sign/src/tests.rs @@ -165,7 +165,7 @@ impl Published { /// The broadcast as a subscriber resolves it, verifying against `key`. async fn consume(&self, key: PublicKey) -> broadcast::Consumer { settle().await; - let inner = self.origin.consume().request_broadcast(&self.path, None).await.unwrap(); + let inner = self.origin.consume().request(&self.path, None).await.unwrap(); broadcast::Consumer::new(inner, key, self.path.clone()).unwrap() } From 7925da471b9d4c9050c35f7ba81d689b7bb41d85 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:21:50 -0700 Subject: [PATCH 07/10] feat(sign): z-base-32 endpoint IDs and signed timestamps Endpoint IDs and key files use 52-character z-base-32 (the mesh enrollment form, with zero trailing bits), and the signed message binds the frame's timescale and timestamp at the track's timescale, zeros when untimed. The draft records why signatures and not a shared MAC key, and that a group's end stays unauthenticated. Vectors and the Rust/JS interop exchange cover both. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + Cargo.toml | 1 + drafts/draft-lcurley-moq-sign.md | 57 ++++++-- drafts/moq-sign-00.json | 240 ++++++++++++++++++++++++------- drafts/moq-sign-00.ts | 154 ++++++++++++++++---- js/sign/README.md | 12 +- js/sign/src/broadcast.ts | 3 +- js/sign/src/group.ts | 24 +++- js/sign/src/index.ts | 7 +- js/sign/src/key.ts | 17 ++- js/sign/src/scope.ts | 51 +++++-- js/sign/src/sign.test.ts | 8 +- js/sign/src/track.ts | 12 +- js/sign/src/vectors.test.ts | 42 ++++-- js/sign/src/zbase32.ts | 44 ++++++ rs/moq-sign/Cargo.toml | 3 +- rs/moq-sign/README.md | 14 +- rs/moq-sign/src/group.rs | 17 ++- rs/moq-sign/src/key.rs | 52 ++++--- rs/moq-sign/src/lib.rs | 6 +- rs/moq-sign/src/scope.rs | 44 ++++-- rs/moq-sign/src/tests.rs | 142 +++++++++++++----- test/interop/sign.ts | 49 +++++-- 23 files changed, 774 insertions(+), 226 deletions(-) create mode 100644 js/sign/src/zbase32.ts diff --git a/Cargo.lock b/Cargo.lock index 6f973a49f66..657c9b45848 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5897,6 +5897,7 @@ dependencies = [ "aws-lc-rs", "bench-harness", "bytes", + "data-encoding", "hex", "kio 0.6.2", "moq-net", diff --git a/Cargo.toml b/Cargo.toml index 22083b18de5..64146a1b172 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -107,6 +107,7 @@ clap = { version = "4", features = ["derive"] } # CUDA driver bindings for the NVENC/NVDEC path. dlopen'd at runtime # (`fallback-dynamic-loading`), so nothing links against libcuda at build time. cudarc = { version = "0.19", default-features = false, features = ["driver", "fallback-dynamic-loading", "cuda-12020"] } +data-encoding = "2.11" dispatch2 = "0.3.1" ebml-iterable = "0.7.1" flate2 = { version = "1.1", default-features = false } diff --git a/drafts/draft-lcurley-moq-sign.md b/drafts/draft-lcurley-moq-sign.md index 8216c086f1a..0ab1cc08f5c 100644 --- a/drafts/draft-lcurley-moq-sign.md +++ b/drafts/draft-lcurley-moq-sign.md @@ -18,8 +18,13 @@ author: normative: moql: I-D.lcurley-moq-lite - RFC4648: RFC8032: + zbase32: + title: "Human-oriented base-32 encoding" + author: + - fullname: Zooko Wilcox-O'Hearn + date: 2002 + target: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt informative: moqt: I-D.ietf-moq-transport @@ -27,11 +32,14 @@ informative: iroh: title: "iroh" target: https://github.com/n0-computer/iroh + pkarr: + title: "Pkarr: Public-Key Addressable Resource Records" + target: https://github.com/pubky/pkarr --- abstract This document specifies moq-sign-00, a versioned profile that authenticates MoQ application payloads with a per-frame Ed25519 signature. -A publisher signs each grouped frame with its endpoint key, binding the broadcast path, the publisher epoch, the track, the group, and the frame index. +A publisher signs each grouped frame with its endpoint key, binding the broadcast path, the publisher epoch, the track, the group, the frame index, and the frame's timestamp. A subscriber that expects that key delivers a frame only after its signature verifies, so a relay can forward and cache content without forging, replaying, or relocating it. --- note_Note_to_Readers @@ -53,6 +61,10 @@ This profile lets a subscriber check that every frame it delivers came from the A signature per frame costs 64 bytes and one verification, and adds no delay beyond receiving the whole frame: no hash chain or checkpoint has to arrive first. The profile provides authenticity, not confidentiality; {{e2ee}} encrypts payloads and can be layered beneath it. +The profile uses public-key signatures rather than a symmetric MAC or AEAD tag. +A symmetric key, as in {{e2ee}}, is shared by everyone who verifies, so any subscriber holding it could forge frames that every other subscriber accepts. +A signature verifies under the publisher's public key alone, so only the holder of the secret key can produce one, whoever else reads the broadcast. + # Profile Version This document defines profile `moq-sign-00`. @@ -62,8 +74,9 @@ Both ends agree on the profile out of band; a subscriber MUST NOT accept unsigne # Endpoint Key {#key} A publisher holds an Ed25519 key pair ({{RFC8032}}). The 32-byte public key is the endpoint ID. -Its text form is the lowercase base16 encoding ({{RFC4648}} Section 8) of the key: 64 characters, the form {{iroh}} displays. -An implementation MUST refuse other text, including uppercase, so one key has exactly one ID. +Its text form is the z-base-32 encoding ({{zbase32}}) of the key, most significant bit first and without padding: 52 characters, the form {{pkarr}} and {{iroh}}'s DNS discovery use, and a valid DNS label. +The last character carries one bit of the key; its remaining four bits MUST be zero. +An implementation MUST refuse other text, including uppercase, nonzero trailing bits, and other encodings of the key such as hex, so one key has exactly one ID. The key identifies an endpoint for as long as the endpoint exists. An implementation MUST NOT replace a stored key that fails to load; that would silently change the endpoint's identity. @@ -82,6 +95,8 @@ message = "moq-sign-00" || bytes(track) || u64(group) || u64(frame) + || u64(timescale) + || u64(timestamp) || payload ~~~ @@ -92,6 +107,7 @@ A relay may mount a broadcast under another prefix, so this is the application's **epoch**: The UUID text of the publisher instance's epoch, carried on the broadcast's route ({{moql}}). A publisher instance MUST sign under an epoch it minted and no other instance has used. +The epoch names one sequence space: a publisher that restarts its group sequences signs under a new one. **track**: The UTF-8 track name. @@ -104,11 +120,19 @@ The group sequence. The frame's index within its group. moq-lite numbers frames from 0 in write order; on MoQ Transport this is the Object ID, which a publisher assigns contiguously from zero. +**timescale**: +The track's timescale in units per second, or 0 for an untimed track. +No timescale is 0, so an untimed frame cannot be confused with a timed one. + +**timestamp**: +The frame's presentation timestamp at the track's timescale, as the transport carries it, or 0 for an untimed track. +A publisher signs the value after any conversion to the track's timescale, so the subscriber verifies against exactly what it receives. + **payload**: The application bytes. Each length prefix keeps one field's bytes from shifting into the next. -Timestamps and other frame properties are not signed. +Other frame properties are not signed. # Frame Body {#body} @@ -129,26 +153,37 @@ Other groups of the track continue, since each verifies on its own. A subscriber that cannot learn the broadcast's epoch from its route MUST refuse to read it (`epoch`). +Every hop between the publisher and the subscriber must carry the route's epoch and each frame's timestamp and timescale unchanged; in {{moql}} that is moq-lite-07. +A hop that cannot, such as a moq-lite-05 or -06 hop that stamps an untimed frame with its send time, causes `signature` failures rather than a frame delivered with the wrong time. + Datagrams are not covered by this profile; a subscriber MUST NOT deliver datagrams from a track it reads under it. # Test Vectors {#vectors} Known-answer and negative vectors live in `moq-sign-00.json` beside this draft. -Hex strings are octet sequences. -The file covers key derivation from a seed, including {{RFC8032}} Section 7.1 TEST 1; signed messages and bodies for an empty payload, groups and frame indices above 32 bits, an empty path, and a non-ASCII track; relocation across every identity field, including a byte shifted between two fields; a wrong key; tampered payloads and signatures; truncated, extended, and empty bodies; and endpoint ID text that MUST be refused. +Hex strings are octet sequences, and `endpoint` strings are endpoint ID text. +The file covers key derivation from a seed, including {{RFC8032}} Section 7.1 TEST 1, and each key's endpoint ID; signed messages and bodies for an empty payload, groups, frame indices, and timestamps above 32 bits, an empty path, a non-ASCII track, and a timed frame; relocation across every identity field, including a byte shifted between two fields, a timestamp rescaled to the same instant, and a timestamp added to or dropped from a frame; a wrong key; tampered payloads and signatures; truncated, extended, and empty bodies; and endpoint ID text that MUST be refused. # Security Considerations Relays, caches, and recorders are untrusted for content. The publisher's secret key is trusted; anyone holding it can sign as that endpoint. -The signature binds every field a relay could otherwise change to move an authentic frame: the path, the epoch, the track, the group, and the frame index. +The signature binds every field a relay could otherwise change to move or retime an authentic frame: the path, the epoch, the track, the group, the frame index, and the timestamp. Binding the epoch keeps a frame from an earlier instance of the same broadcast, which restarted its sequences, from verifying in a later one. +Binding the timestamp keeps a relay from changing when a frame presents. + +Any subscriber can verify but none can sign, so subscribers that share a broadcast cannot forge frames to each other, as they could with a shared symmetric key. -A relay can still delay, drop, or reorder groups, end a group after any frame, and rewrite timestamps. -Nothing authenticates where a group ends, so an application MUST NOT treat a group's end as authentic. +A relay can still delay, drop, or reorder groups. A relay that presents a wrong epoch only causes `signature` failures. +## Group End {#group-end} +Nothing authenticates where a group ends: a relay can end a group after any frame, and the subscriber sees an ordinary end of group. +MoQ already lets a relay drop the tail of a group, for example when it falls behind the subscriber's delivery deadline, so the profile does not try to prevent it. +An application MUST NOT treat a group's end as proof that it received every frame the publisher wrote. +One that needs a complete group, such as a byte stream reading the end as a clean close, signs its own end marker as the group's last frame. + A relay can observe everything a signature does not hide: paths, epochs, track names, payloads, sizes, and timing. Ed25519 signing is deterministic, so no per-signature randomness can leak the key. @@ -166,4 +201,4 @@ This document requests no registrations. ## draft-lcurley-moq-sign-00 {:numbered="false"} -- Initial `moq-sign-00` profile: Ed25519 endpoint keys with a lowercase hex ID, a message binding path, epoch, track, group, and frame index, a payload-then-signature frame body, group-ending failures, and shared vectors. +- Initial `moq-sign-00` profile: Ed25519 endpoint keys with a z-base-32 ID, a message binding path, epoch, track, group, frame index, and timestamp, a payload-then-signature frame body, group-ending failures, an unauthenticated group end, and shared vectors. diff --git a/drafts/moq-sign-00.json b/drafts/moq-sign-00.json index f8f2759fee5..6f854a0d3ac 100644 --- a/drafts/moq-sign-00.json +++ b/drafts/moq-sign-00.json @@ -9,242 +9,370 @@ { "id": "rfc8032-test-1", "seed": "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60", - "public": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a" + "public": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a", + "endpoint": "47pjoycnsrfmxikm95jh13y88e8qnhzu5kungjpxyepgt7a8krpy" }, { "id": "test", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y" }, { "id": "other", "seed": "6d6f712d7369676e2d3030206f74686572207365656421212121212121212121", - "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758" + "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "endpoint": "wfc7hxboduwytxyrr35ct7oj77o6jmsidyq9teynw9obene7g7cy" + }, + { + "id": "ones", + "public": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", + "endpoint": "999999999999999999999999999999999999999999999999999o" } ], "frames": [ { "id": "base", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, + "timescale": 0, + "timestamp": 0, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000168656c6c6f", - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e" }, { "id": "empty-payload", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 0, + "timescale": 0, + "timestamp": 0, "payload": "", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d00000000000000030000000000000000", - "body": "1e0ed358f8c4053edd585a3feb8eca2755f3b232d266b66df0b23ea5b843fec56d8af410d20d495df22f1b0cd7cd0118bd160edfd1ec33972e5738ab6aa58404" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000000000000000000000000000000000000", + "body": "c8d983a9846d860b5f0b76997eeb943e16e487fc24e28b6266866806cf97845cf98e7036416b86e004fba15157503cb9871ff46f6fa1d9474164e3b3f8e1ad00" }, { "id": "group-above-u32", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 1099511627781, "frame": 0, + "timescale": 0, + "timestamp": 0, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000010000000005000000000000000068656c6c6f", - "body": "68656c6c6f36ba11c14dd79078cc547ac35257552140d416bbd8eec0f31a67fa0e4da9d021ac43125ea0d8fb6de5d0c6376ce3529c9b50270dfffbb661559dd42ea1ec1309" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000001000000000500000000000000000000000000000000000000000000000068656c6c6f", + "body": "68656c6c6f224feecc93d46bce865c75815dbd11b07632a6e63895e165a049b6629b38c9db04e429979f293b240cc92f21af5b84620a3eeef9afaeff5469c3911903ddb70b" }, { "id": "frame-above-u32", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 4294967296, + "timescale": 0, + "timestamp": 0, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000010000000068656c6c6f", - "body": "68656c6c6f96b21176ed8aa2cd6ea943a3601e60344ab2ff9ede5c1d3ec22b05c237c28946ac08f2619ca5669c3cb76051e1b0df928f8c1a07b976d1d6f5cf8801701fd404" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000001000000000000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fab70f52b0543b17d166cf5741abffd14c47df0ca80affb2630caf63be2550eb4c66bcbe3d00f7699f2b7608b06f6bfd8abfe0b3a0400512a1ae804d12e08c80a" }, { "id": "max-u53", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 9007199254740991, "frame": 1, + "timescale": 0, + "timestamp": 0, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d001fffffffffffff000000000000000168656c6c6f", - "body": "68656c6c6f42daf8ec76ab76aff7b07fbe664504c0dfd9ad853383a6325b894c6bf6f413e60c14bda18b0e0f2635cf3677bc4f0e0d5fa4170b57503a89b73d587b0b06a709" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d001fffffffffffff00000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fe963734e25dadea272b61c217cb582ef02c1d3c5b9306150557856e990a14c5aab94f20177fd01025c4895b32914c34fdfab28f25a12c9a9ce9684598bfda90b" }, { "id": "empty-path-utf8-track", "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "café", "group": 3, "frame": 1, + "timescale": 0, + "timestamp": 0, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d30300000000000000000000000000000002430313961326233632d346435652d376636302d386131622d3263336434653566366137620000000000000005636166c3a9000000000000000300000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6f422f0042a98ec96f0c233a21cf862bea7c3a98dbc16f07db31b18a58bfbd1df6e0252d5fad17011f79f084738c79f60096ed4ac436593e994495b26113fac005" + }, + { + "id": "timed", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "video", + "group": 3, + "frame": 1, + "timescale": 1000, + "timestamp": 2500, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d30300000000000000000000000000000002430313961326233632d346435652d376636302d386131622d3263336434653566366137620000000000000005636166c3a90000000000000003000000000000000168656c6c6f", - "body": "68656c6c6f34c19a5af0957aee4440e37197ab2455b10b16e6f7c106fbf31901565efd651597856b6d08402e7adc6b394a5c2b28236348c77a84fa2419136b2bce2a2f5709" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d3263336434653566366137620000000000000005766964656f0000000000000003000000000000000100000000000003e800000000000009c468656c6c6f", + "body": "68656c6c6ffaa4d387416d2811080277620e51f20287c6e3cfb3a1e187c91bd343214363d7339a765d7835b7f7da8087ae025487155f3e98690fc45824ea65c020d4ce7e09" + }, + { + "id": "timestamp-above-u32", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "video", + "group": 3, + "frame": 1, + "timescale": 90000, + "timestamp": 1099511627776, + "payload": "68656c6c6f", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d3263336434653566366137620000000000000005766964656f000000000000000300000000000000010000000000015f90000001000000000068656c6c6f", + "body": "68656c6c6fc9efcfce1f65a87743ba9b3b3e6ef1ff5e3e7bc4a633a44c84f2eab930084de9d64069c82fa6f220f229030f0b628f49f0fd50ea4bca74beaf989124b4e37502" }, { "id": "other-key", "seed": "6d6f712d7369676e2d3030206f74686572207365656421212121212121212121", - "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "endpoint": "wfc7hxboduwytxyrr35ct7oj77o6jmsidyq9teynw9obene7g7cy", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, + "timescale": 0, + "timestamp": 0, "payload": "68656c6c6f", - "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000168656c6c6f", - "body": "68656c6c6fc70597b8ca756f8928014f3b72b05bc70dfe6894ee6f071a9cf11e61c15fddcf4713c8216d3952c8eda963348295f3f94f28bac7eb83e04711ca29c2cce6cb00" + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6f68c375b5d8b44fdd7fc89fa39809855c38a73a7168fa0301bf1a6b5fa6b482471e402d1effdbf943bd7a2c04b4dafb7adf342394cd4e65a4530f3f7cf0e87700" } ], "negative": [ { "id": "relocated-path", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/http", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "relocated-epoch", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7c", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "relocated-track", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream2", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "relocated-group", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 4, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "relocated-frame", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 0, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "shifted-boundary", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/sshs", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "tream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "relocated-timestamp", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "video", + "group": 3, + "frame": 1, + "timescale": 1000, + "timestamp": 2501, + "body": "68656c6c6ffaa4d387416d2811080277620e51f20287c6e3cfb3a1e187c91bd343214363d7339a765d7835b7f7da8087ae025487155f3e98690fc45824ea65c020d4ce7e09", + "error": "signature" + }, + { + "id": "rescaled-timestamp", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "video", + "group": 3, + "frame": 1, + "timescale": 1000000, + "timestamp": 2500000, + "body": "68656c6c6ffaa4d387416d2811080277620e51f20287c6e3cfb3a1e187c91bd343214363d7339a765d7835b7f7da8087ae025487155f3e98690fc45824ea65c020d4ce7e09", + "error": "signature" + }, + { + "id": "timestamp-dropped", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "video", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6ffaa4d387416d2811080277620e51f20287c6e3cfb3a1e187c91bd343214363d7339a765d7835b7f7da8087ae025487155f3e98690fc45824ea65c020d4ce7e09", + "error": "signature" + }, + { + "id": "timestamp-added", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 1000, + "timestamp": 2500, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "wrong-key", - "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "endpoint": "wfc7hxboduwytxyrr35ct7oj77o6jmsidyq9teynw9obene7g7cy", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "tampered-payload", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "69656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a", + "timescale": 0, + "timestamp": 0, + "body": "69656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", "error": "signature" }, { "id": "tampered-signature", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0b", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0f", "error": "signature" }, { "id": "appended-byte", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189ca1ffe64ad0a00", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e00", "error": "signature" }, { "id": "truncated", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, - "body": "68656c6c6fb248e979ba0ada4b008cf57976a6bb114670990b0353e9c147b716ef51f2aad8c5401c2b49c0e8160a4bae8ec863527e6c2bd66ce941728cb189", + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e7", "error": "signature" }, { "id": "empty", - "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", "path": "mesh/node/ssh", "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", "track": "stream", "group": 3, "frame": 1, + "timescale": 0, + "timestamp": 0, "body": "", "error": "signature" } @@ -252,23 +380,27 @@ "invalid_ids": [ { "id": "uppercase", - "text": "4030B2C68C2E6CC51C96DAE4B44CC53C07471BA7D7731EB7368FE8F807ECB5CE" + "text": "EYAMFTWCF3SCK8RS5M1MEUGF8ODWQG78473T7P3ST9WXOB9CSZ8Y" }, { "id": "short", - "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5c" + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8" }, { "id": "long", - "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce0" + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8yy" + }, + { + "id": "outside-alphabet", + "text": "0yamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y" }, { - "id": "non-hex", - "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5cg" + "id": "trailing-bits", + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8b" }, { - "id": "prefixed", - "text": "0x30b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" + "id": "hex", + "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" }, { "id": "empty", diff --git a/drafts/moq-sign-00.ts b/drafts/moq-sign-00.ts index 2d37e8dd835..9a23a4c219f 100644 --- a/drafts/moq-sign-00.ts +++ b/drafts/moq-sign-00.ts @@ -30,15 +30,20 @@ export class ProfileError extends Error { } } -/** One signed frame's identity. */ +/** One signed frame's identity. An untimed frame has timescale and timestamp 0. */ export type Identity = { path: string; epoch: string; track: string; group: bigint; frame: bigint; + timescale: bigint; + timestamp: bigint; }; +// z-base-32: most significant bit first, no padding, trailing bits must be zero. +const ZBASE32 = "ybndrfg8ejkmcpqxot1uwisza345h769"; + function utf8(text: string): Uint8Array { return new TextEncoder().encode(text); } @@ -51,6 +56,23 @@ function toHex(bytes: Uint8Array): string { return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); } +function zbase32(bytes: Uint8Array): string { + let out = ""; + let buffer = 0; + let bits = 0; + for (const byte of bytes) { + buffer = (buffer << 8) | byte; + bits += 8; + while (bits >= 5) { + bits -= 5; + out += ZBASE32[(buffer >> bits) & 31]; + } + buffer &= (1 << bits) - 1; + } + if (bits > 0) out += ZBASE32[(buffer << (5 - bits)) & 31]; + return out; +} + function concat(...parts: Uint8Array[]): Uint8Array { const out = new Uint8Array(parts.reduce((sum, part) => sum + part.byteLength, 0)); let offset = 0; @@ -81,14 +103,37 @@ export function message(identity: Identity, payload: Uint8Array): Uint8Array { - if (!/^[0-9a-f]{64}$/.test(text)) throw new ProfileError("key"); - return hex(text); + if (text.length !== 52) throw new ProfileError("key"); + const out = new Uint8Array(KEY_LEN); + let buffer = 0; + let bits = 0; + let offset = 0; + for (const char of text) { + const value = ZBASE32.indexOf(char); + if (value < 0) throw new ProfileError("key"); + buffer = (buffer << 5) | value; + bits += 5; + if (bits >= 8) { + bits -= 8; + out[offset++] = (buffer >> bits) & 0xff; + } + buffer &= (1 << bits) - 1; + } + if (buffer !== 0) throw new ProfileError("key"); + return out; } async function privateKey(seed: Uint8Array): Promise { @@ -135,21 +180,41 @@ const OTHER_SEED = toHex(utf8("moq-sign-00 other seed!!!!!!!!!!")); const EPOCH = "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b"; const OTHER_EPOCH = "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7c"; -type IdentityJson = { path: string; epoch: string; track: string; group: number; frame: number }; +type IdentityJson = { + path: string; + epoch: string; + track: string; + group: number; + frame: number; + timescale: number; + timestamp: number; +}; function identityJson(identity: Identity): IdentityJson { - return { ...identity, group: Number(identity.group), frame: Number(identity.frame) }; + return { + ...identity, + group: Number(identity.group), + frame: Number(identity.frame), + timescale: Number(identity.timescale), + timestamp: Number(identity.timestamp), + }; } function parseIdentity(row: IdentityJson): Identity { - return { ...row, group: BigInt(row.group), frame: BigInt(row.frame) }; + return { + ...row, + group: BigInt(row.group), + frame: BigInt(row.frame), + timescale: BigInt(row.timescale), + timestamp: BigInt(row.timestamp), + }; } async function frameVector(id: string, seed: string, identity: Identity, payload: Uint8Array) { return { id, seed, - public: toHex(await publicKey(hex(seed))), + endpoint: endpointId(await publicKey(hex(seed))), ...identityJson(identity), payload: toHex(payload), message: toHex(message(identity, payload)), @@ -158,13 +223,26 @@ async function frameVector(id: string, seed: string, identity: Identity, payload } async function generate() { - const base: Identity = { path: "mesh/node/ssh", epoch: EPOCH, track: "stream", group: 3n, frame: 1n }; + const base: Identity = { + path: "mesh/node/ssh", + epoch: EPOCH, + track: "stream", + group: 3n, + frame: 1n, + timescale: 0n, + timestamp: 0n, + }; + // The same frame on a track timed in milliseconds. + const timed: Identity = { ...base, track: "video", timescale: 1000n, timestamp: 2500n }; const payload = utf8("hello"); const body = await sign(hex(SEED), base, payload); - const key = toHex(await publicKey(hex(SEED))); - const negative = (id: string, identity: Identity, frameBody: Uint8Array, publicHex = key) => ({ + const timedBody = await sign(hex(SEED), timed, payload); + const keyBytes = await publicKey(hex(SEED)); + const key = endpointId(keyBytes); + const otherKey = endpointId(await publicKey(hex(OTHER_SEED))); + const negative = (id: string, identity: Identity, frameBody: Uint8Array, endpoint = key) => ({ id, - public: publicHex, + endpoint, ...identityJson(identity), body: toHex(frameBody), error: "signature", @@ -179,9 +257,16 @@ async function generate() { profile: PROFILE, constants: { label: toHex(LABEL), key_len: KEY_LEN, signature_len: SIGNATURE_LEN }, keys: [ - { id: "rfc8032-test-1", seed: RFC8032_SEED, public: RFC8032_PUBLIC }, - { id: "test", seed: SEED, public: key }, - { id: "other", seed: OTHER_SEED, public: toHex(await publicKey(hex(OTHER_SEED))) }, + { + id: "rfc8032-test-1", + seed: RFC8032_SEED, + public: RFC8032_PUBLIC, + endpoint: endpointId(hex(RFC8032_PUBLIC)), + }, + { id: "test", seed: SEED, public: toHex(keyBytes), endpoint: key }, + { id: "other", seed: OTHER_SEED, public: toHex(await publicKey(hex(OTHER_SEED))), endpoint: otherKey }, + // Every bit set: the last character carries one key bit and four zero bits. + { id: "ones", public: "ff".repeat(KEY_LEN), endpoint: endpointId(new Uint8Array(KEY_LEN).fill(0xff)) }, ], frames: [ await frameVector("base", SEED, base, payload), @@ -190,6 +275,13 @@ async function generate() { await frameVector("frame-above-u32", SEED, { ...base, frame: 2n ** 32n }, payload), await frameVector("max-u53", SEED, { ...base, group: 2n ** 53n - 1n }, payload), await frameVector("empty-path-utf8-track", SEED, { ...base, path: "", track: "café" }, payload), + await frameVector("timed", SEED, timed, payload), + await frameVector( + "timestamp-above-u32", + SEED, + { ...timed, timescale: 90000n, timestamp: 2n ** 40n }, + payload, + ), await frameVector("other-key", OTHER_SEED, base, payload), ], negative: [ @@ -200,7 +292,13 @@ async function generate() { negative("relocated-frame", { ...base, frame: 0n }, body), // Shifting a byte between the path and track keeps their concatenation equal. negative("shifted-boundary", { ...base, path: "mesh/node/sshs", track: "tream" }, body), - negative("wrong-key", base, body, toHex(await publicKey(hex(OTHER_SEED)))), + negative("relocated-timestamp", { ...timed, timestamp: 2501n }, timedBody), + // The same instant at another scale is another signed value. + negative("rescaled-timestamp", { ...timed, timescale: 1000000n, timestamp: 2500000n }, timedBody), + negative("timestamp-dropped", { ...timed, timescale: 0n, timestamp: 0n }, timedBody), + // A hop that stamps an untimed frame with its send time, as moq-lite 05/06 do. + negative("timestamp-added", { ...base, timescale: 1000n, timestamp: 2500n }, body), + negative("wrong-key", base, body, otherKey), negative("tampered-payload", base, flipped(0)), negative("tampered-signature", base, flipped(body.byteLength - 1)), negative("appended-byte", base, concat(body, new Uint8Array([0]))), @@ -209,10 +307,13 @@ async function generate() { ], invalid_ids: [ { id: "uppercase", text: key.toUpperCase() }, - { id: "short", text: key.slice(0, 63) }, - { id: "long", text: `${key}0` }, - { id: "non-hex", text: `${key.slice(0, 63)}g` }, - { id: "prefixed", text: `0x${key.slice(2)}` }, + { id: "short", text: key.slice(0, 51) }, + { id: "long", text: `${key}y` }, + // "0", "2", "l", and "v" are not in the alphabet. + { id: "outside-alphabet", text: `0${key.slice(1)}` }, + // The last character's low four bits are padding and must be zero. + { id: "trailing-bits", text: `${key.slice(0, 51)}b` }, + { id: "hex", text: toHex(keyBytes) }, { id: "empty", text: "" }, ], }; @@ -220,17 +321,22 @@ async function generate() { async function check(doc: Awaited>): Promise { for (const row of doc.keys) { - assertEqual(`${row.id} public`, toHex(await publicKey(hex(row.seed))), row.public); - assertEqual(`${row.id} parse`, toHex(parseKey(row.public)), row.public); + if (row.seed) assertEqual(`${row.id} public`, toHex(await publicKey(hex(row.seed))), row.public); + assertEqual(`${row.id} endpoint`, endpointId(hex(row.public)), row.endpoint); + assertEqual(`${row.id} parse`, toHex(parseKey(row.endpoint)), row.public); } for (const row of doc.frames) { const identity = parseIdentity(row); assertEqual(`${row.id} message`, toHex(message(identity, hex(row.payload))), row.message); assertEqual(`${row.id} body`, toHex(await sign(hex(row.seed), identity, hex(row.payload))), row.body); - assertEqual(`${row.id} verify`, toHex(await verify(hex(row.public), identity, hex(row.body))), row.payload); + assertEqual( + `${row.id} verify`, + toHex(await verify(parseKey(row.endpoint), identity, hex(row.body))), + row.payload, + ); } for (const row of doc.negative) { - await expectError(row.error, () => verify(hex(row.public), parseIdentity(row), hex(row.body))); + await expectError(row.error, () => verify(parseKey(row.endpoint), parseIdentity(row), hex(row.body))); } for (const row of doc.invalid_ids) { await expectError("key", () => parseKey(row.text)); diff --git a/js/sign/README.md b/js/sign/README.md index e0b461fd9fc..6c67de7c5cf 100644 --- a/js/sign/README.md +++ b/js/sign/README.md @@ -12,12 +12,12 @@ Relays forward and cache signed frames; they cannot forge, replay, or relocate t ## Shape -An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 64 lowercase -hex characters. `SecretKey.generate()` keeps the private half a nonextractable `CryptoKey`. +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 +characters (a DNS label). `SecretKey.generate()` keeps the private half a nonextractable `CryptoKey`. `Broadcast.Producer` wraps the `@moq/net` broadcast, mints a fresh epoch, and signs each frame -over the application path, epoch, track, group, and frame index. Announce the broadcast with that -epoch on its route: +over the application path, epoch, track, group, frame index, and timestamp (rounded to the +track's timescale, as the wire carries it). Announce the broadcast with that epoch on its route: ```ts import { Broadcast, SecretKey } from "@moq/sign"; @@ -38,7 +38,9 @@ group.finish(); A subscriber wraps the broadcast an origin resolved in a `Broadcast.Consumer` with the key it expects and the same application path; it takes the epoch from the route. A frame reaches the application only after it verifies. A forged or relocated frame ends its group with `Failure` -code `signature`, and the track keeps delivering other groups. +code `signature`, and the track keeps delivering other groups. Every hop must carry the epoch and +timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop a +group's tail, as MoQ already allows. ## Processing diff --git a/js/sign/src/broadcast.ts b/js/sign/src/broadcast.ts index d1b5f324dc8..051b93d5089 100644 --- a/js/sign/src/broadcast.ts +++ b/js/sign/src/broadcast.ts @@ -40,7 +40,8 @@ export class Producer { /** Create a track whose frames are signed; throws the net error if the broadcast already holds it. */ createTrack(name: string, info: Partial = {}): Track.Producer { const inner = this.#inner.createTrack(name, info); - return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.epoch, name)); + const timescale = info.timescale ?? undefined; + return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.epoch, name), timescale); } /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ diff --git a/js/sign/src/group.ts b/js/sign/src/group.ts index def28124a16..a1263e2222b 100644 --- a/js/sign/src/group.ts +++ b/js/sign/src/group.ts @@ -3,7 +3,7 @@ * * @module */ -import type { Group as NetGroup, Time } from "@moq/net"; +import { type Group as NetGroup, Time } from "@moq/net"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; import type { Pump } from "./pump.ts"; @@ -11,7 +11,7 @@ import type { Scope } from "./scope.ts"; /** A grouped frame whose signature verified. */ export interface Frame { - /** Presentation timestamp, or `undefined` when untimed. Not signed. */ + /** Presentation timestamp at the track's timescale, or `undefined` when untimed. Signed. */ timestamp?: Time.Timestamp; /** The application bytes, without the signature. */ payload: Uint8Array; @@ -23,6 +23,8 @@ export interface Writer { pump: Pump; key: SecretKey; scope: Scope; + // The track's timescale, which every timestamp is signed at; undefined when untimed. + timescale?: Time.Timescale; // Set by release or abort: no new writes, including on existing groups. closed: boolean; aborted?: Error; @@ -68,11 +70,17 @@ export class Producer { async writeFrame(timestamp: Time.Timestamp | undefined, payload: Uint8Array): Promise { if (this.#closed || this.#writer.closed) throw this.#writer.aborted ?? new Error("group is closed"); const owned = payload.slice(); + // Signed at the track's timescale, rounded as the wire rounds it, and written that way so a + // local reader sees the signed value too. A frame whose timedness disagrees with the track + // is left for the net write to refuse. + const scale = this.#writer.timescale; + const at = + timestamp && scale !== undefined ? new Time.Timestamp(Math.round(timestamp.as(scale)), scale) : timestamp; return this.#writer.pump.run(async () => { this.#check(); - const body = await this.#writer.scope.sign(this.#writer.key, this.sequence, this.#next, owned); + const body = await this.#writer.scope.sign(this.#writer.key, this.sequence, this.#next, at, owned); this.#check(); - this.#inner.writeFrame({ payload: body, timestamp }); + this.#inner.writeFrame({ payload: body, timestamp: at }); this.#next += 1; }); } @@ -142,7 +150,13 @@ export class Consumer { if (!frame) return undefined; // The frame's transport index, so a group resumed above frame 0 still verifies. try { - const payload = await this.#scope.verify(this.#key, this.sequence, frame.sequence, frame.payload); + const payload = await this.#scope.verify( + this.#key, + this.sequence, + frame.sequence, + frame.timestamp, + frame.payload, + ); return { timestamp: frame.timestamp, payload }; } catch (err) { if (err instanceof Failure) { diff --git a/js/sign/src/index.ts b/js/sign/src/index.ts index e1e10528ac0..aca96f4a563 100644 --- a/js/sign/src/index.ts +++ b/js/sign/src/index.ts @@ -4,9 +4,10 @@ * Implements profile `moq-sign-00` from * [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). A publisher * signs every grouped frame with its endpoint's {@link SecretKey}, binding the broadcast path, its - * publisher epoch, the track, the group, and the frame index. A subscriber hands a frame to the - * application only after it verifies against the {@link PublicKey} it expects, so a relay can - * proxy and cache without forging, replaying, or splicing content. Mirrors the Rust `moq-sign` crate. + * publisher epoch, the track, the group, the frame index, and the timestamp. A subscriber hands a + * frame to the application only after it verifies against the {@link PublicKey} it expects, so a + * relay can proxy and cache without forging, replaying, retiming, or splicing content. Mirrors the + * Rust `moq-sign` crate. * * ```ts * const key = await SecretKey.generate(); diff --git a/js/sign/src/key.ts b/js/sign/src/key.ts index 3ffd267985a..c94dcb2c0fc 100644 --- a/js/sign/src/key.ts +++ b/js/sign/src/key.ts @@ -4,6 +4,7 @@ * @module */ import { Failure } from "./failure.ts"; +import * as ZBase32 from "./zbase32.ts"; const KEY_LEN = 32; const ED25519 = { name: "Ed25519" } as const; @@ -15,8 +16,9 @@ const PKCS8_PREFIX = Uint8Array.from([ /** * An endpoint's Ed25519 public key, which is also its endpoint ID. * - * Its text form is the 64-character lowercase hex of the key, the form iroh displays. Parsing - * accepts only that form, so one key has exactly one ID to name a path by. + * Its text form is the 52-character z-base-32 of the key, the form pkarr and iroh's DNS + * discovery use, which is also a valid DNS label. Parsing accepts only that form (lowercase, + * zero trailing bits), so one key has exactly one ID to name a path by. */ export class PublicKey { #bytes: Uint8Array; @@ -32,10 +34,11 @@ export class PublicKey { return new PublicKey(Uint8Array.from(bytes)); } - /** Parse an endpoint ID; throws {@link Failure} `key` unless it is 64 lowercase hex characters. */ + /** Parse an endpoint ID; throws {@link Failure} `key` unless it is 52 z-base-32 characters. */ static parse(text: string): PublicKey { - if (!/^[0-9a-f]{64}$/.test(text)) throw new Failure("key"); - return new PublicKey(Uint8Array.from(text.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16))); + const bytes = ZBase32.decode(text, KEY_LEN); + if (!bytes) throw new Failure("key"); + return new PublicKey(bytes); } /** Whether `other` is the same key. */ @@ -43,9 +46,9 @@ export class PublicKey { return this.#bytes.every((byte, i) => byte === other.#bytes[i]); } - /** The endpoint ID: 64 lowercase hex characters. */ + /** The endpoint ID: 52 z-base-32 characters. */ toString(): string { - return Array.from(this.#bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); + return ZBase32.encode(this.#bytes); } /** Whether `signature` is this key's Ed25519 signature over `message`. @internal */ diff --git a/js/sign/src/scope.ts b/js/sign/src/scope.ts index 0d904617452..caf673e2557 100644 --- a/js/sign/src/scope.ts +++ b/js/sign/src/scope.ts @@ -1,5 +1,5 @@ // The signed message: what a frame's signature binds besides its payload. -import type { Epoch, Path } from "@moq/net"; +import type { Epoch, Path, Time } from "@moq/net"; import { Failure } from "./failure.ts"; import type { PublicKey, SecretKey } from "./key.ts"; @@ -28,20 +28,41 @@ export class Scope { } } - /** The message signed for `payload` at frame `frame` of group `group`. */ - message(group: number, frame: number, payload: Uint8Array): Uint8Array { - const out = new Uint8Array(this.#prefix.byteLength + 16 + payload.byteLength); + /** + * The message signed for `payload` at frame `frame` of group `group`, presented at `timestamp`. + * + * The timestamp is its integer value at the track's timescale, so a frame keeps its signature + * only on a hop that carries both unchanged. An untimed frame binds zero for both, which no + * timescale can be. A fractional value, which no hop carries, never verifies. + */ + message( + group: number, + frame: number, + timestamp: Time.Timestamp | undefined, + payload: Uint8Array, + ): Uint8Array { + if (timestamp && !Number.isSafeInteger(timestamp.value)) throw new Failure("signature"); + const out = new Uint8Array(this.#prefix.byteLength + 32 + payload.byteLength); const view = new DataView(out.buffer); out.set(this.#prefix); - view.setBigUint64(this.#prefix.byteLength, BigInt(group)); - view.setBigUint64(this.#prefix.byteLength + 8, BigInt(frame)); - out.set(payload, this.#prefix.byteLength + 16); + let offset = this.#prefix.byteLength; + for (const field of [group, frame, timestamp?.scale ?? 0, timestamp?.value ?? 0]) { + view.setBigUint64(offset, BigInt(field)); + offset += 8; + } + out.set(payload, offset); return out; } /** The frame body: `payload` followed by its signature. */ - async sign(key: SecretKey, group: number, frame: number, payload: Uint8Array): Promise> { - const signature = await key.sign(this.message(group, frame, payload)); + async sign( + key: SecretKey, + group: number, + frame: number, + timestamp: Time.Timestamp | undefined, + payload: Uint8Array, + ): Promise> { + const signature = await key.sign(this.message(group, frame, timestamp, payload)); const body = new Uint8Array(payload.byteLength + SIGNATURE_LEN); body.set(payload); body.set(signature, payload.byteLength); @@ -49,11 +70,19 @@ export class Scope { } /** The payload of a frame body whose signature verifies, as a view into `body`; throws {@link Failure} `signature`. */ - async verify(key: PublicKey, group: number, frame: number, body: Uint8Array): Promise { + async verify( + key: PublicKey, + group: number, + frame: number, + timestamp: Time.Timestamp | undefined, + body: Uint8Array, + ): Promise { const split = body.byteLength - SIGNATURE_LEN; if (split < 0) throw new Failure("signature"); const payload = body.subarray(0, split); - if (!(await key.verify(this.message(group, frame, payload), body.slice(split)))) throw new Failure("signature"); + if (!(await key.verify(this.message(group, frame, timestamp, payload), body.slice(split)))) { + throw new Failure("signature"); + } return payload; } } diff --git a/js/sign/src/sign.test.ts b/js/sign/src/sign.test.ts index e71b1414167..a228c679ab3 100644 --- a/js/sign/src/sign.test.ts +++ b/js/sign/src/sign.test.ts @@ -76,7 +76,8 @@ test("frames roundtrip signed, timestamps included", async () => { const group = video.appendGroup(); await group.writeFrame(Time.Timestamp.fromMillis(1), encoder.encode("keyframe")); - await group.writeFrame(Time.Timestamp.fromMillis(2), new Uint8Array()); + // Signed at the track's scale, rounded as the wire rounds it. + await group.writeFrame(Time.Timestamp.fromMicros(2_400), new Uint8Array()); const consumer = await published.consume(key.public); expect(consumer.epoch).toBe(published.signed.epoch); @@ -85,7 +86,10 @@ test("frames roundtrip signed, timestamps included", async () => { const first = await received?.readFrame(); expect(decoder.decode(first?.payload)).toBe("keyframe"); expect(first?.timestamp?.as(Time.Timescale.MILLI)).toBe(1); - expect(await payload(received)).toBe(""); + const second = await received?.readFrame(); + expect(second?.payload.byteLength).toBe(0); + expect(second?.timestamp?.value).toBe(2); + expect(second?.timestamp?.scale).toBe(Time.Timescale.MILLI); await group.writeFrame(Time.Timestamp.fromMillis(3), encoder.encode("late")); group.finish(); diff --git a/js/sign/src/track.ts b/js/sign/src/track.ts index 9019040baba..7c655243ede 100644 --- a/js/sign/src/track.ts +++ b/js/sign/src/track.ts @@ -3,7 +3,7 @@ * * @module */ -import type { Track as NetTrack } from "@moq/net"; +import type { Track as NetTrack, Time } from "@moq/net"; import * as Group from "./group.ts"; import type { PublicKey, SecretKey } from "./key.ts"; import { Pump } from "./pump.ts"; @@ -23,15 +23,15 @@ export class Producer { #writer: Group.Writer; #finished = false; - private constructor(inner: NetTrack.Producer, key: SecretKey, scope: Scope) { + private constructor(inner: NetTrack.Producer, key: SecretKey, scope: Scope, timescale?: Time.Timescale) { this.#inner = inner; this.name = inner.name; - this.#writer = { pump: new Pump(), key, scope, closed: false }; + this.#writer = { pump: new Pump(), key, scope, timescale, closed: false }; } - /** @internal */ - static make(inner: NetTrack.Producer, key: SecretKey, scope: Scope): Producer { - return new Producer(inner, key, scope); + /** Sign `inner`, whose info declared `timescale` (undefined when untimed). @internal */ + static make(inner: NetTrack.Producer, key: SecretKey, scope: Scope, timescale?: Time.Timescale): Producer { + return new Producer(inner, key, scope, timescale); } /** The track's final outcome, once its declared end is reached or it aborts. */ diff --git a/js/sign/src/vectors.test.ts b/js/sign/src/vectors.test.ts index baa1e91597b..7e69e27ff94 100644 --- a/js/sign/src/vectors.test.ts +++ b/js/sign/src/vectors.test.ts @@ -1,6 +1,6 @@ // Every vector in drafts/moq-sign-00.json, run against the internal primitives. import { expect, test } from "bun:test"; -import { Epoch, type Path } from "@moq/net"; +import { Epoch, type Path, Time } from "@moq/net"; import { Failure } from "./failure.ts"; import { PublicKey, SecretKey } from "./key.ts"; import { Scope } from "./scope.ts"; @@ -27,22 +27,31 @@ function scope(row: Row): Scope { return new Scope(String(row.path) as Path.Valid, Epoch.parse(String(row.epoch)), String(row.track)); } +// A row's timestamp at its timescale, or undefined when the timescale is 0 (untimed). +function timestamp(row: Row): Time.Timestamp | undefined { + const scale = Number(row.timescale); + return scale === 0 ? undefined : new Time.Timestamp(Number(row.timestamp), Time.Timescale(scale)); +} + test("keys", async () => { for (const row of vectors.keys) { - const key = await SecretKey.fromSeed(unhex(row.seed)); - expect(key.public.toString()).toBe(String(row.public)); - expect(PublicKey.parse(String(row.public)).equals(key.public)).toBe(true); + const endpoint = PublicKey.parse(String(row.endpoint)); + expect(endpoint.equals(PublicKey.fromBytes(unhex(row.public)))).toBe(true); + expect(endpoint.toString()).toBe(String(row.endpoint)); + if (row.seed !== undefined) { + expect((await SecretKey.fromSeed(unhex(row.seed))).public.equals(endpoint)).toBe(true); + } } }); test("frames", async () => { for (const row of vectors.frames) { const s = scope(row); - const [group, frame] = [Number(row.group), Number(row.frame)]; - expect(hex(s.message(group, frame, unhex(row.payload)))).toBe(String(row.message)); - const body = await s.sign(await SecretKey.fromSeed(unhex(row.seed)), group, frame, unhex(row.payload)); + const [group, frame, at] = [Number(row.group), Number(row.frame), timestamp(row)]; + expect(hex(s.message(group, frame, at, unhex(row.payload)))).toBe(String(row.message)); + const body = await s.sign(await SecretKey.fromSeed(unhex(row.seed)), group, frame, at, unhex(row.payload)); expect(hex(body)).toBe(String(row.body)); - const payload = await s.verify(PublicKey.parse(String(row.public)), group, frame, unhex(row.body)); + const payload = await s.verify(PublicKey.parse(String(row.endpoint)), group, frame, at, unhex(row.body)); expect(hex(payload)).toBe(String(row.payload)); } }); @@ -50,15 +59,30 @@ test("frames", async () => { test("negative", async () => { for (const row of vectors.negative) { const verified = scope(row).verify( - PublicKey.parse(String(row.public)), + PublicKey.parse(String(row.endpoint)), Number(row.group), Number(row.frame), + timestamp(row), unhex(row.body), ); await expect(verified).rejects.toEqual(new Failure("signature")); } }); +test("a fractional timestamp never verifies", async () => { + const row = vectors.frames.find((frame) => frame.id === "timed"); + if (!row) throw new Error("expected the timed vector"); + const at = new Time.Timestamp(Number(row.timestamp) + 0.5, Time.Timescale(Number(row.timescale))); + const verified = scope(row).verify( + PublicKey.parse(String(row.endpoint)), + Number(row.group), + Number(row.frame), + at, + unhex(row.body), + ); + await expect(verified).rejects.toEqual(new Failure("signature")); +}); + test("invalid ids", () => { for (const row of vectors.invalid_ids) { expect(() => PublicKey.parse(String(row.text))).toThrow(new Failure("key")); diff --git a/js/sign/src/zbase32.ts b/js/sign/src/zbase32.ts new file mode 100644 index 00000000000..d5a2e71cd29 --- /dev/null +++ b/js/sign/src/zbase32.ts @@ -0,0 +1,44 @@ +// z-base-32: most significant bit first, no padding, trailing bits must be zero. +const ALPHABET = "ybndrfg8ejkmcpqxot1uwisza345h769"; + +/** Encode `bytes` as z-base-32. */ +export function encode(bytes: Uint8Array): string { + let out = ""; + let buffer = 0; + let bits = 0; + for (const byte of bytes) { + buffer = (buffer << 8) | byte; + bits += 8; + while (bits >= 5) { + bits -= 5; + out += ALPHABET[(buffer >> bits) & 31]; + } + buffer &= (1 << bits) - 1; + } + if (bits > 0) out += ALPHABET[(buffer << (5 - bits)) & 31]; + return out; +} + +/** + * Decode exactly `length` bytes, or `undefined` for any other text. The alphabet is + * lowercase-only and nonzero trailing bits are refused, so a value has one text form. + */ +export function decode(text: string, length: number): Uint8Array | undefined { + if (text.length !== Math.ceil((length * 8) / 5)) return undefined; + const out = new Uint8Array(length); + let buffer = 0; + let bits = 0; + let offset = 0; + for (const char of text) { + const value = ALPHABET.indexOf(char); + if (value < 0) return undefined; + buffer = (buffer << 5) | value; + bits += 5; + if (bits >= 8) { + bits -= 8; + out[offset++] = (buffer >> bits) & 0xff; + } + buffer &= (1 << bits) - 1; + } + return buffer === 0 ? out : undefined; +} diff --git a/rs/moq-sign/Cargo.toml b/rs/moq-sign/Cargo.toml index 130c19fb622..3edc87db19f 100644 --- a/rs/moq-sign/Cargo.toml +++ b/rs/moq-sign/Cargo.toml @@ -16,13 +16,14 @@ categories = ["cryptography", "multimedia", "network-programming"] [dependencies] aws-lc-rs = { workspace = true } bytes = { workspace = true } -hex = { workspace = true } +data-encoding = { workspace = true } kio = { workspace = true } moq-net = { workspace = true } thiserror = { workspace = true } zeroize = { workspace = true } [dev-dependencies] +hex = { workspace = true } criterion = { package = "bench-harness", path = "../bench-harness" } serde_json = { workspace = true } tempfile = { workspace = true } diff --git a/rs/moq-sign/README.md b/rs/moq-sign/README.md index b6e76ac19a6..a9b1fbcbad6 100644 --- a/rs/moq-sign/README.md +++ b/rs/moq-sign/README.md @@ -11,13 +11,13 @@ Relays forward and cache signed frames; they cannot forge, replay, or relocate t ## Shape -An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 64 lowercase -hex characters. `SecretKey::load_or_generate(path)` keeps one key for the life of a host, in a -`0600` file it never replaces implicitly. +An endpoint's `SecretKey` signs; its `PublicKey` is the endpoint ID, displayed as 52 z-base-32 +characters (a DNS label). `SecretKey::load_or_generate(path)` keeps one key for the life of a host, +as 52 z-base-32 characters in a `0600` file it never replaces implicitly. `broadcast::Producer` wraps the `moq-net` broadcast, mints a fresh epoch, and signs each frame -over the application path, epoch, track, group, and frame index. Announce the broadcast with that -epoch on its route: +over the application path, epoch, track, group, frame index, and timestamp (at the track's +timescale). Announce the broadcast with that epoch on its route: ```rust let key = SecretKey::load_or_generate("/var/lib/moq/endpoint.key")?; @@ -31,7 +31,9 @@ publication.announce(Route::default().with_epoch(signed.epoch().clone()))?; A subscriber wraps the broadcast an origin resolved in a `broadcast::Consumer` with the key it expects and the same application path; it takes the epoch from the route. A frame reaches the application only after it verifies. A forged or relocated frame ends its group with -`Error::Signature`, and the track keeps delivering other groups. +`Error::Signature`, and the track keeps delivering other groups. Every hop must carry the epoch +and timestamps unchanged, which means moq-lite-07. A group's end is not signed: a relay may drop +a group's tail, as MoQ already allows. A broadcast at the identity level, which trusts the relay's token check alone, uses `moq-net` directly. diff --git a/rs/moq-sign/src/group.rs b/rs/moq-sign/src/group.rs index 3d9102137d1..f304aab3438 100644 --- a/rs/moq-sign/src/group.rs +++ b/rs/moq-sign/src/group.rs @@ -13,7 +13,7 @@ use crate::scope::Scope; /// A grouped frame whose signature verified. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Frame { - /// Presentation timestamp, or `None` when untimed. Not signed. + /// Presentation timestamp at the track's timescale, or `None` when untimed. Signed. pub timestamp: Option, /// The application bytes, without the signature. pub payload: Bytes, @@ -43,8 +43,16 @@ impl Producer { /// A net error if the group is closed, the timestamp does not match the track, or the /// signed frame exceeds the frame size limit. pub fn write_frame(&mut self, timestamp: impl Into>, payload: &[u8]) -> Result<()> { + // Signed at the track's timescale, the value the net group stores and every hop carries. + // A frame whose timedness disagrees with the track is left for the write to refuse. + let timestamp = match (timestamp.into(), self.inner.timescale()) { + (Some(at), Some(timescale)) => Some(at.convert(timescale).map_err(|_| moq_net::Error::TimestampMismatch)?), + (timestamp, _) => timestamp, + }; let frame = self.inner.frame_count() as u64; - let body = self.scope.sign(&self.key, self.inner.sequence, frame, payload); + let body = self + .scope + .sign(&self.key, self.inner.sequence, frame, timestamp, payload); self.inner.write_frame(timestamp, body)?; Ok(()) } @@ -121,7 +129,10 @@ impl Consumer { // The cursor already advanced past the frame, so a group resumed above frame 0 still // verifies at the index the publisher signed. let index = inner.index() - 1; - match self.scope.verify(&self.key, self.sequence, index, frame.payload) { + match self + .scope + .verify(&self.key, self.sequence, index, frame.timestamp, frame.payload) + { Ok(payload) => Poll::Ready(Ok(Some(Frame { timestamp: frame.timestamp, payload, diff --git a/rs/moq-sign/src/key.rs b/rs/moq-sign/src/key.rs index ab033f3d80f..aa977c818bc 100644 --- a/rs/moq-sign/src/key.rs +++ b/rs/moq-sign/src/key.rs @@ -13,14 +13,29 @@ use crate::scope::SIGNATURE_LEN; /// Ed25519 key length in bytes, for both the secret seed and the public key. const KEY_LEN: usize = 32; +/// z-base-32: most significant bit first, no padding, trailing bits must be zero. +static ZBASE32: std::sync::LazyLock = std::sync::LazyLock::new(|| { + let mut spec = data_encoding::Specification::new(); + spec.symbols.push_str("ybndrfg8ejkmcpqxot1uwisza345h769"); + spec.encoding().expect("a valid z-base-32 specification") +}); + /// An endpoint's Ed25519 public key, which is also its endpoint ID. /// -/// Its text form is the 64-character lowercase hex of the key, the form iroh displays. Parsing -/// accepts only that form, so one key has exactly one ID to name a path by. +/// Its text form is the 52-character [z-base-32] of the key, the form pkarr and iroh's DNS +/// discovery use, which is also a valid DNS label. Parsing accepts only that form (lowercase, +/// zero trailing bits), so one key has exactly one ID to name a path by. +/// +/// [z-base-32]: https://philzimmermann.com/docs/human-oriented-base-32-encoding.txt #[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] pub struct PublicKey([u8; KEY_LEN]); impl PublicKey { + #[cfg(test)] + pub(crate) fn from_bytes(bytes: [u8; KEY_LEN]) -> Self { + Self(bytes) + } + /// Whether `signature` is this key's Ed25519 signature over `message`. pub(crate) fn verify(&self, message: &[u8], signature: &[u8; SIGNATURE_LEN]) -> bool { UnparsedPublicKey::new(&ED25519, &self.0) @@ -29,9 +44,9 @@ impl PublicKey { } } -/// The text is not the 64-character lowercase hex of a 32-byte key. +/// The text is not the 52-character z-base-32 of a 32-byte key. #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)] -#[error("invalid key: expected 64 lowercase hex characters")] +#[error("invalid key: expected 52 z-base-32 characters")] #[non_exhaustive] pub struct InvalidKey; @@ -39,13 +54,13 @@ impl FromStr for PublicKey { type Err = InvalidKey; fn from_str(text: &str) -> Result { - Ok(Self(parse_hex(text)?)) + Ok(Self(decode(text)?)) } } impl fmt::Display for PublicKey { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&hex::encode(self.0)) + f.write_str(&ZBASE32.encode(&self.0)) } } @@ -55,13 +70,14 @@ impl fmt::Debug for PublicKey { } } -/// Decode exactly 64 lowercase hex characters, refusing uppercase so a key has one text form. -fn parse_hex(text: &str) -> Result<[u8; KEY_LEN], InvalidKey> { - if text.len() != KEY_LEN * 2 || !text.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) { - return Err(InvalidKey); - } +/// Decode exactly 52 z-base-32 characters. The alphabet is lowercase-only and nonzero trailing +/// bits are refused, so a key has one text form. +fn decode(text: &str) -> Result<[u8; KEY_LEN], InvalidKey> { let mut out = [0u8; KEY_LEN]; - hex::decode_to_slice(text, &mut out).map_err(|_| InvalidKey)?; + match ZBASE32.decode_len(text.len()) { + Ok(KEY_LEN) => ZBASE32.decode_mut(text.as_bytes(), &mut out).map_err(|_| InvalidKey)?, + _ => return Err(InvalidKey), + }; Ok(out) } @@ -101,7 +117,7 @@ impl SecretKey { /// Load the key stored at `path`, or generate one and store it there if the file is missing. /// - /// The file holds the seed as 64 lowercase hex characters and a newline, created with mode + /// The file holds the seed as 52 z-base-32 characters and a newline, created with mode /// `0600`. A key is never replaced implicitly: an existing file that does not parse, or that /// other users can read, is an error rather than a reason to generate a new identity. /// @@ -127,7 +143,9 @@ impl SecretKey { Err(err) if err.kind() == io::ErrorKind::AlreadyExists => return Self::load(path), Err(err) => return Err(err), }; - let mut text = Zeroizing::new(hex::encode(key.0.seed.as_ref())); + // Sized up front, so appending the newline never leaves an unzeroized copy behind. + let mut text = Zeroizing::new(String::with_capacity(ZBASE32.encode_len(KEY_LEN) + 1)); + ZBASE32.encode_append(key.0.seed.as_ref(), &mut text); text.push('\n'); file.write_all(text.as_bytes())?; file.sync_all()?; @@ -148,11 +166,11 @@ impl SecretKey { } let mut text = Zeroizing::new(String::new()); io::Read::read_to_string(&mut &file, &mut text)?; - let hex = text.strip_suffix('\n').unwrap_or(&text); - let seed = parse_hex(hex).map_err(|_| { + let encoded = text.strip_suffix('\n').unwrap_or(&text); + let seed = decode(encoded).map_err(|_| { io::Error::new( io::ErrorKind::InvalidData, - format!("key file {} is not 64 lowercase hex characters", path.display()), + format!("key file {} is not 52 z-base-32 characters", path.display()), ) })?; Ok(Self::from_seed(Zeroizing::new(seed))) diff --git a/rs/moq-sign/src/lib.rs b/rs/moq-sign/src/lib.rs index 5eb1e3984bb..3136230ccf0 100644 --- a/rs/moq-sign/src/lib.rs +++ b/rs/moq-sign/src/lib.rs @@ -2,9 +2,9 @@ //! //! Implements profile `moq-sign-00` from [draft-lcurley-moq-sign]. A publisher signs every //! grouped frame with its endpoint's [`SecretKey`], binding the broadcast path, its publisher -//! epoch, the track, the group, and the frame index. A subscriber hands a frame to the -//! application only after it verifies against the [`PublicKey`] it expects, so a relay can -//! proxy and cache without forging, replaying, or splicing content. +//! epoch, the track, the group, the frame index, and the timestamp. A subscriber hands a frame +//! to the application only after it verifies against the [`PublicKey`] it expects, so a relay +//! can proxy and cache without forging, replaying, retiming, or splicing content. //! //! [draft-lcurley-moq-sign]: https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/ //! diff --git a/rs/moq-sign/src/scope.rs b/rs/moq-sign/src/scope.rs index 2a61fd75910..23b4ede72ce 100644 --- a/rs/moq-sign/src/scope.rs +++ b/rs/moq-sign/src/scope.rs @@ -31,19 +31,38 @@ impl Scope { Arc::new(Self { prefix }) } - /// The message signed for `payload` at frame `frame` of group `group`. - pub(crate) fn message(&self, group: u64, frame: u64, payload: &[u8]) -> Vec { - let mut message = Vec::with_capacity(self.prefix.len() + 16 + payload.len()); + /// The message signed for `payload` at frame `frame` of group `group`, presented at `timestamp`. + /// + /// The timestamp is its value at the track's timescale, so a frame keeps its signature only + /// on a hop that carries both unchanged. An untimed frame binds zero for both, which no + /// timescale can be. + pub(crate) fn message( + &self, + group: u64, + frame: u64, + timestamp: Option, + payload: &[u8], + ) -> Vec { + let (timescale, value) = timestamp.map_or((0, 0), |at| (at.scale().as_u64(), at.value())); + let mut message = Vec::with_capacity(self.prefix.len() + 32 + payload.len()); message.extend_from_slice(&self.prefix); - message.extend_from_slice(&group.to_be_bytes()); - message.extend_from_slice(&frame.to_be_bytes()); + for field in [group, frame, timescale, value] { + message.extend_from_slice(&field.to_be_bytes()); + } message.extend_from_slice(payload); message } /// The frame body: `payload` followed by its signature. - pub(crate) fn sign(&self, key: &SecretKey, group: u64, frame: u64, payload: &[u8]) -> Bytes { - let signature = key.sign(&self.message(group, frame, payload)); + pub(crate) fn sign( + &self, + key: &SecretKey, + group: u64, + frame: u64, + timestamp: Option, + payload: &[u8], + ) -> Bytes { + let signature = key.sign(&self.message(group, frame, timestamp, payload)); let mut body = BytesMut::with_capacity(payload.len() + SIGNATURE_LEN); body.put_slice(payload); body.put_slice(&signature); @@ -51,10 +70,17 @@ impl Scope { } /// The payload of a frame body whose signature verifies, without copying it. - pub(crate) fn verify(&self, key: &PublicKey, group: u64, frame: u64, body: Bytes) -> Result { + pub(crate) fn verify( + &self, + key: &PublicKey, + group: u64, + frame: u64, + timestamp: Option, + body: Bytes, + ) -> Result { let split = body.len().checked_sub(SIGNATURE_LEN).ok_or(Error::Signature)?; let signature: &[u8; SIGNATURE_LEN] = body[split..].try_into().expect("the signature's length"); - if !key.verify(&self.message(group, frame, &body[..split]), signature) { + if !key.verify(&self.message(group, frame, timestamp, &body[..split]), signature) { return Err(Error::Signature); } Ok(body.slice(..split)) diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs index 74040ba48d1..d2b3603226d 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-sign/src/tests.rs @@ -26,25 +26,37 @@ fn public(value: &Value) -> PublicKey { value.as_str().unwrap().parse().unwrap() } -/// A vector row's identity: its scope, group, and frame. -fn identity(row: &Value) -> (Arc, u64, u64) { +/// A vector row's identity: its scope, group, frame, and timestamp (timescale 0 when untimed). +fn identity(row: &Value) -> (Arc, u64, u64, Option) { let path = moq_net::Path::new(row["path"].as_str().unwrap()).unwrap(); let epoch = row["epoch"].as_str().unwrap().parse().unwrap(); let scope = Scope::new(&path, &epoch, row["track"].as_str().unwrap()); - (scope, row["group"].as_u64().unwrap(), row["frame"].as_u64().unwrap()) + let timestamp = match row["timescale"].as_u64().unwrap() { + 0 => None, + scale => Some(moq_net::Timestamp::from_scale(row["timestamp"].as_u64().unwrap(), scale).unwrap()), + }; + ( + scope, + row["group"].as_u64().unwrap(), + row["frame"].as_u64().unwrap(), + timestamp, + ) } #[test] fn vector_keys() { for row in vectors()["keys"].as_array().unwrap() { - let key = seed(&row["seed"]); + let id = &row["id"]; + let endpoint = public(&row["endpoint"]); assert_eq!( - key.public().to_string(), - row["public"].as_str().unwrap(), - "{}", - row["id"] + endpoint, + PublicKey::from_bytes(hex(&row["public"]).try_into().unwrap()), + "{id}" ); - assert_eq!(key.public(), public(&row["public"])); + assert_eq!(endpoint.to_string(), row["endpoint"].as_str().unwrap(), "{id}"); + if !row["seed"].is_null() { + assert_eq!(seed(&row["seed"]).public(), endpoint, "{id}"); + } } } @@ -52,12 +64,18 @@ fn vector_keys() { fn vector_frames() { for row in vectors()["frames"].as_array().unwrap() { let id = &row["id"]; - let (scope, group, frame) = identity(row); + let (scope, group, frame, timestamp) = identity(row); let payload = hex(&row["payload"]); - assert_eq!(scope.message(group, frame, &payload), hex(&row["message"]), "{id}"); - let body = scope.sign(&seed(&row["seed"]), group, frame, &payload); + assert_eq!( + scope.message(group, frame, timestamp, &payload), + hex(&row["message"]), + "{id}" + ); + let body = scope.sign(&seed(&row["seed"]), group, frame, timestamp, &payload); assert_eq!(body.as_ref(), hex(&row["body"]), "{id}"); - let opened = scope.verify(&public(&row["public"]), group, frame, body).unwrap(); + let opened = scope + .verify(&public(&row["endpoint"]), group, frame, timestamp, body) + .unwrap(); assert_eq!(opened.as_ref(), payload, "{id}"); } } @@ -65,9 +83,9 @@ fn vector_frames() { #[test] fn vector_negative() { for row in vectors()["negative"].as_array().unwrap() { - let (scope, group, frame) = identity(row); + let (scope, group, frame, timestamp) = identity(row); let body = Bytes::from(hex(&row["body"])); - let result = scope.verify(&public(&row["public"]), group, frame, body); + let result = scope.verify(&public(&row["endpoint"]), group, frame, timestamp, body); assert_eq!(row["error"], "signature"); assert!(matches!(result, Err(Error::Signature)), "{}", row["id"]); } @@ -97,6 +115,16 @@ fn key_file_persists_and_never_rotates() { } let loaded = SecretKey::load_or_generate(&path).unwrap(); assert_eq!(created.public(), loaded.public()); + // The seed as 52 z-base-32 characters and a newline. + let text = std::fs::read_to_string(&path).unwrap(); + let encoded = text.strip_suffix('\n').unwrap(); + assert_eq!(encoded.len(), 52); + assert!( + encoded + .bytes() + .all(|b| b"ybndrfg8ejkmcpqxot1uwisza345h769".contains(&b)), + "{text}" + ); // A damaged file is an error, never a reason to mint a new identity. std::fs::write(&path, "not a key\n").unwrap(); @@ -122,6 +150,7 @@ fn debug_redacts_the_seed() { let key = SecretKey::from_seed(Zeroizing::new([0x42; 32])); let debug = format!("{key:?}"); assert!(!debug.contains(&"42".repeat(32)), "{debug}"); + assert!(debug.contains(""), "{debug}"); assert!(debug.contains(&key.public().to_string())); } @@ -210,8 +239,9 @@ async fn roundtrip_through_an_origin() { group .write_frame(moq_net::Timestamp::from_millis(1).unwrap(), b"keyframe") .unwrap(); + // Signed at the track's scale, which the net group converts it to. group - .write_frame(moq_net::Timestamp::from_millis(2).unwrap(), b"") + .write_frame(moq_net::Timestamp::from_micros(2_400).unwrap(), b"") .unwrap(); group.finish().unwrap(); @@ -219,7 +249,9 @@ async fn roundtrip_through_an_origin() { let first = received.read_frame().await.unwrap().unwrap(); assert_eq!(first.payload, &b"keyframe"[..]); assert_eq!(first.timestamp, Some(moq_net::Timestamp::from_millis(1).unwrap())); - assert_eq!(read(&mut received).await.unwrap().unwrap(), &b""[..]); + let second = received.read_frame().await.unwrap().unwrap(); + assert_eq!(second.payload, &b""[..]); + assert_eq!(second.timestamp, Some(moq_net::Timestamp::from_millis(2).unwrap())); assert_eq!(read(&mut received).await.unwrap(), None); } @@ -392,7 +424,8 @@ fn bun(input: Value) -> Value { serde_json::from_slice(&output.stdout).unwrap() } -/// Rust-signed groups verify in JS and a relocated one does not; JS-signed groups verify in Rust. +/// Rust-signed groups verify in JS and a relocated or retimed one does not; JS-signed groups +/// verify in Rust, timestamps included. #[test] #[ignore = "requires Bun; run by just test interop"] fn sign_interop() { @@ -404,47 +437,88 @@ fn sign_interop() { let payloads: [&[u8]; 3] = [b"zero", b"", &[0xff; 300]]; let expected: Vec = payloads.iter().map(hex::encode).collect(); - // A group's bodies as Rust signs them at `signed_as`, delivered at `group`. - let sign_group = |group: u64, signed_as: u64| { - let scope = Scope::new(&path, &epoch, "video"); - let bodies: Vec = payloads + let millis = |value: u64| moq_net::Timestamp::from_millis(value).unwrap(); + // A group's frames as Rust signs them at `signed_as` and `timestamps` (in milliseconds on a + // timed track), delivered at `group` and `delivered`. + let sign_group = |group: u64, signed_as: u64, timestamps: Option<([u64; 3], [u64; 3])>| { + let track = if timestamps.is_some() { "video" } else { "data" }; + let scope = Scope::new(&path, &epoch, track); + let frames: Vec = payloads + .iter() + .enumerate() + .map(|(frame, payload)| { + let (signed, delivered) = match timestamps { + Some((signed, delivered)) => (Some(millis(signed[frame])), Some(delivered[frame])), + None => (None, None), + }; + let body = scope.sign(&key, signed_as, frame as u64, signed, payload); + serde_json::json!({ "body": hex::encode(body), "timestamp": delivered }) + }) + .collect(); + let timescale = timestamps.map(|_| 1000); + serde_json::json!({ "track": track, "group": group, "timescale": timescale, "frames": frames }) + }; + let write = |track: &str, micros: Option<[u64; 3]>| { + let frames: Vec = expected .iter() .enumerate() - .map(|(frame, payload)| hex::encode(scope.sign(&key, signed_as, frame as u64, payload))) + .map(|(frame, payload)| serde_json::json!({ "payload": payload, "micros": micros.map(|m| m[frame]) })) .collect(); - serde_json::json!({ "track": "video", "group": group, "bodies": bodies }) + serde_json::json!({ "track": track, "timescale": micros.map(|_| 1000), "frames": frames }) }; + let stamps = [10, 20, 30]; let output = bun(serde_json::json!({ "seed": hex::encode(seed.as_ref()), "path": path.as_str(), "epoch": epoch.as_str(), - "rust": [sign_group(7, 7), sign_group(8, 7)], - "payloads": [expected, ["6a73"]], + "rust": [ + sign_group(7, 7, None), + sign_group(8, 7, None), + sign_group(9, 9, Some((stamps, stamps))), + sign_group(10, 10, Some((stamps, [11, 20, 30]))), + ], + // Microseconds on a millisecond track: JS signs the rounded value the wire carries. + "js": [write("js", None), write("js", None), write("js-video", Some([2_400, 2_600, 3_000]))], })); assert_eq!(output["public"], key.public().to_string()); assert_eq!(output["verified"][0], serde_json::json!(expected)); assert_eq!(output["verified"][1], "signature"); + assert_eq!(output["verified"][2], serde_json::json!(expected)); + assert_eq!(output["verified"][3], "signature"); let js_epoch = output["epoch"].as_str().unwrap().parse().unwrap(); let groups = output["js"].as_array().unwrap(); - assert_eq!(groups.len(), 2); - for (row, payloads) in groups.iter().zip([expected, vec!["6a73".to_string()]]) { + assert_eq!(groups.len(), 3); + for row in groups { let scope = Scope::new(&path, &js_epoch, row["track"].as_str().unwrap()); let group = row["group"].as_u64().unwrap(); - let bodies = row["bodies"].as_array().unwrap(); - let opened: Vec = bodies + let timestamp = |frame: &Value| { + let scale = row["timescale"].as_u64()?; + Some(moq_net::Timestamp::from_scale(frame["timestamp"].as_u64().unwrap(), scale).unwrap()) + }; + let frames = row["frames"].as_array().unwrap(); + let opened: Vec = frames .iter() .enumerate() - .map(|(frame, body)| { - let opened = scope.verify(&key.public(), group, frame as u64, Bytes::from(hex(body))); + .map(|(index, frame)| { + let body = Bytes::from(hex(&frame["body"])); + let opened = scope.verify(&key.public(), group, index as u64, timestamp(frame), body); hex::encode(opened.unwrap()) }) .collect(); - assert_eq!(opened, payloads); + assert_eq!(opened, expected); // The same body does not verify at the neighboring group. - let relocated = scope.verify(&key.public(), group + 1, 0, Bytes::from(hex(&bodies[0]))); + let body = Bytes::from(hex(&frames[0]["body"])); + let relocated = scope.verify(&key.public(), group + 1, 0, timestamp(&frames[0]), body); assert!(matches!(relocated, Err(Error::Signature))); } + let timed: Vec = groups[2]["frames"] + .as_array() + .unwrap() + .iter() + .map(|frame| frame["timestamp"].as_u64().unwrap()) + .collect(); + assert_eq!(timed, [2, 3, 3]); } diff --git a/test/interop/sign.ts b/test/interop/sign.ts index 5fc82cec959..01ab2657810 100644 --- a/test/interop/sign.ts +++ b/test/interop/sign.ts @@ -1,15 +1,19 @@ /** Exchange signed groups with Rust: verify the ones Rust signed, and sign through the JS wrappers. */ import assert from "node:assert/strict"; -import { Broadcast, Epoch, Path } from "../../js/net/src/index.ts"; +import { Broadcast, Epoch, type Track as NetTrack, Path, Time } from "../../js/net/src/index.ts"; import * as Signed from "../../js/sign/src/broadcast.ts"; import { Failure } from "../../js/sign/src/failure.ts"; import { SecretKey } from "../../js/sign/src/key.ts"; import { Scope } from "../../js/sign/src/scope.ts"; import * as Track from "../../js/sign/src/track.ts"; -/** One group's frame bodies, signature included, as they cross the wire. */ -type Group = { track: string; group: number; bodies: string[] }; -type Input = { seed: string; path: string; epoch: string; rust: Group[]; payloads: string[][] }; +/** One frame as it crosses the wire: its body, signature included, and its timestamp at the track's timescale. */ +type Frame = { body: string; timestamp?: number | null }; +/** One group of a track, timed when it has a timescale. */ +type Group = { track: string; group: number; timescale?: number | null; frames: Frame[] }; +/** A group for JS to sign: payloads, and timestamps in microseconds on a timed track. */ +type Write = { track: string; timescale?: number | null; frames: { payload: string; micros?: number | null }[] }; +type Input = { seed: string; path: string; epoch: string; rust: Group[]; js: Write[] }; function unhex(text: string): Uint8Array { return Uint8Array.from(text.match(/../g) ?? [], (byte) => Number.parseInt(byte, 16)); @@ -26,11 +30,15 @@ const epoch = Epoch.parse(input.epoch); // Each Rust group through a verifying JS track consumer: its payloads, or the failure code. const verified: (string[] | string)[] = []; -for (const { track, group, bodies } of input.rust) { - const net = new Broadcast.Producer().createTrack(track); +for (const { track, group, timescale, frames } of input.rust) { + const scale = timescale == null ? undefined : Time.Timescale(timescale); + const net = new Broadcast.Producer().createTrack(track, { timescale: scale }); const consumer = Track.Consumer.make(net.subscribe(), key.public, new Scope(path, epoch, track)); const writer = net.createGroup(group); - for (const body of bodies) writer.writeFrame({ payload: unhex(body) }); + for (const { body, timestamp } of frames) { + const at = scale === undefined || timestamp == null ? undefined : new Time.Timestamp(timestamp, scale); + writer.writeFrame({ payload: unhex(body), timestamp: at }); + } writer.finish(); const received = await consumer.recvGroup(); assert(received); @@ -49,18 +57,29 @@ for (const { track, group, bodies } of input.rust) { // Groups signed through the JS wrappers, tapped raw off the net broadcast. const inner = new Broadcast.Producer(); const signed = new Signed.Producer(inner, key, path); -const producer = signed.createTrack("js"); -const tap = inner.consume().track("js").subscribe(); +const producers = new Map(); +const taps = new Map(); const js: Group[] = []; -for (const payloads of input.payloads) { +for (const { track, timescale, frames } of input.js) { + const scale = timescale == null ? undefined : Time.Timescale(timescale); + let producer = producers.get(track); + if (!producer) { + producer = signed.createTrack(track, { timescale: scale }); + producers.set(track, producer); + taps.set(track, inner.consume().track(track).subscribe()); + } const group = producer.appendGroup(); - for (const payload of payloads) await group.writeFrame(undefined, unhex(payload)); + for (const { payload, micros } of frames) { + await group.writeFrame(micros == null ? undefined : Time.Timestamp.fromMicros(micros), unhex(payload)); + } group.finish(); - const raw = await tap.recvGroup(); + const raw = await taps.get(track)?.recvGroup(); assert(raw); - const bodies: string[] = []; - for (let frame = await raw.readFrame(); frame; frame = await raw.readFrame()) bodies.push(hex(frame.payload)); - js.push({ track: "js", group: raw.sequence, bodies }); + const bodies: Frame[] = []; + for (let frame = await raw.readFrame(); frame; frame = await raw.readFrame()) { + bodies.push({ body: hex(frame.payload), timestamp: frame.timestamp?.value }); + } + js.push({ track, group: raw.sequence, timescale, frames: bodies }); } process.stdout.write(JSON.stringify({ public: key.public.toString(), verified, epoch: signed.epoch, js })); From 87cf4230481911b6ee0b718fd193baff5e3f470d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:58:02 -0700 Subject: [PATCH 08/10] chore(sign): sort dev-dependencies Co-Authored-By: Claude Opus 5.5 --- rs/moq-sign/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-sign/Cargo.toml b/rs/moq-sign/Cargo.toml index 3edc87db19f..8b1bff66dbc 100644 --- a/rs/moq-sign/Cargo.toml +++ b/rs/moq-sign/Cargo.toml @@ -23,8 +23,8 @@ thiserror = { workspace = true } zeroize = { workspace = true } [dev-dependencies] -hex = { workspace = true } criterion = { package = "bench-harness", path = "../bench-harness" } +hex = { workspace = true } serde_json = { workspace = true } tempfile = { workspace = true } tokio = { workspace = true, features = ["macros", "rt", "test-util"] } From 1bed46839ac989e48b1108619e0eee0cb0696710 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 23:23:13 -0700 Subject: [PATCH 09/10] docs(sign): signatures authenticate content, not liveness The subscriber takes the epoch from a relay-presented route, so a relay that recorded an instance can replay it whole. Narrow the claims and add a Freshness section to the draft: binding the epoch keeps instances from being spliced, and an application that needs freshness learns the epoch from a trusted channel or checks signed timestamps against a shared clock. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/index.md | 2 +- doc/lib/rs/index.md | 2 +- drafts/draft-lcurley-moq-sign.md | 11 +++++++++-- js/sign/README.md | 3 ++- js/sign/src/broadcast.ts | 3 ++- js/sign/src/index.ts | 5 +++-- rs/moq-sign/README.md | 3 ++- rs/moq-sign/src/broadcast.rs | 3 ++- rs/moq-sign/src/lib.rs | 4 +++- 9 files changed, 25 insertions(+), 11 deletions(-) diff --git a/doc/lib/js/index.md b/doc/lib/js/index.md index d934ea16d1f..afbaa85c9c2 100644 --- a/doc/lib/js/index.md +++ b/doc/lib/js/index.md @@ -32,7 +32,7 @@ small examples. The [API reference](/lib/js/api/) covers every package; source l | [@moq/signals](/lib/js/signals) | The reactive primitives every package exposes its state through. | | [@moq/json](/lib/js/json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | | [@moq/e2ee](https://github.com/moq-dev/moq/tree/main/js/e2ee) | End-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. Workspace-only until the browser components use it. | -| [@moq/sign](https://github.com/moq-dev/moq/tree/main/js/sign) | Per-frame Ed25519 signatures, so relays forward content they cannot forge, replay, or relocate. Workspace-only until the mesh uses it. | +| [@moq/sign](https://github.com/moq-dev/moq/tree/main/js/sign) | Per-frame Ed25519 signatures, so relays forward content they cannot forge, retime, or relocate. Workspace-only until the mesh uses it. | | [@moq/loc](/lib/js/api/loc), [@moq/msf](/lib/js/api/msf) | The IETF LOC container and MSF catalog. | | [@moq/boy](/lib/js/api/boy) | The [MoQ Boy](/bin/demo) player element. | diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index 77ae1066a80..32605008b6c 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -36,7 +36,7 @@ see [Applications](/bin/). [Examples](/setup/examples) links runnable consumers; | [moq-room](/lib/rs/moq-room) | Workspace-only native rooms; use the published JS room API for applications. | | [moq-json](/lib/rs/moq-json) | JSON over tracks: snapshots with merge-patch deltas, or append logs. | | [moq-e2ee](https://github.com/moq-dev/moq/tree/main/rs/moq-e2ee) | Workspace-only end-to-end encryption of groups, datagrams, and track names, scoped to a publisher epoch. | -| [moq-sign](https://github.com/moq-dev/moq/tree/main/rs/moq-sign) | Workspace-only per-frame Ed25519 signatures, so relays forward content they cannot forge, replay, or relocate. | +| [moq-sign](https://github.com/moq-dev/moq/tree/main/rs/moq-sign) | Workspace-only per-frame Ed25519 signatures, so relays forward content they cannot forge, retime, or relocate. | | [moq-loc](https://docs.rs/moq-loc), [moq-msf](https://docs.rs/moq-msf) | The IETF LOC container and MSF catalog. | | [moq-stats](https://docs.rs/moq-stats) | Publish and consume relay traffic counters as tracks. | | [moq-clock](/lib/rs/moq-clock) | One clock for time and timers on tokio, the browser, and a deterministic test simulator. | diff --git a/drafts/draft-lcurley-moq-sign.md b/drafts/draft-lcurley-moq-sign.md index 0ab1cc08f5c..9a231ba5e74 100644 --- a/drafts/draft-lcurley-moq-sign.md +++ b/drafts/draft-lcurley-moq-sign.md @@ -40,7 +40,7 @@ informative: This document specifies moq-sign-00, a versioned profile that authenticates MoQ application payloads with a per-frame Ed25519 signature. A publisher signs each grouped frame with its endpoint key, binding the broadcast path, the publisher epoch, the track, the group, the frame index, and the frame's timestamp. -A subscriber that expects that key delivers a frame only after its signature verifies, so a relay can forward and cache content without forging, replaying, or relocating it. +A subscriber that expects that key delivers a frame only after its signature verifies, so a relay can forward and cache content without forging it, retiming it, or moving it to another position. --- note_Note_to_Readers @@ -178,6 +178,13 @@ Any subscriber can verify but none can sign, so subscribers that share a broadca A relay can still delay, drop, or reorder groups. A relay that presents a wrong epoch only causes `signature` failures. +## Freshness {#freshness} +The profile authenticates content, not liveness. +The subscriber learns the epoch from the route, which a relay presents, so a relay that recorded an instance can later announce that epoch again and replay the instance's frames, whole or in part, after the publisher has gone or restarted. +Every replayed frame verifies, because the publisher did sign it at that position. +Binding the epoch only keeps frames of different instances from being spliced into one. +An application that needs freshness learns the expected epoch from a channel it trusts, or checks the signed timestamps against a clock it shares with the publisher. + ## Group End {#group-end} Nothing authenticates where a group ends: a relay can end a group after any frame, and the subscriber sees an ordinary end of group. MoQ already lets a relay drop the tail of a group, for example when it falls behind the subscriber's delivery deadline, so the profile does not try to prevent it. @@ -201,4 +208,4 @@ This document requests no registrations. ## draft-lcurley-moq-sign-00 {:numbered="false"} -- Initial `moq-sign-00` profile: Ed25519 endpoint keys with a z-base-32 ID, a message binding path, epoch, track, group, frame index, and timestamp, a payload-then-signature frame body, group-ending failures, an unauthenticated group end, and shared vectors. +- Initial `moq-sign-00` profile: Ed25519 endpoint keys with a z-base-32 ID, a message binding path, epoch, track, group, frame index, and timestamp, a payload-then-signature frame body, group-ending failures, an unauthenticated group end, no freshness guarantee, and shared vectors. diff --git a/js/sign/README.md b/js/sign/README.md index 6c67de7c5cf..530ed7085d1 100644 --- a/js/sign/README.md +++ b/js/sign/README.md @@ -8,7 +8,8 @@ Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. `moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/), interoperable with the Rust `moq-sign` crate. -Relays forward and cache signed frames; they cannot forge, replay, or relocate them. +Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. ## Shape diff --git a/js/sign/src/broadcast.ts b/js/sign/src/broadcast.ts index 051b93d5089..f7c445e12ea 100644 --- a/js/sign/src/broadcast.ts +++ b/js/sign/src/broadcast.ts @@ -54,7 +54,8 @@ export class Producer { * The subscribing side of a signed broadcast. * * Every frame must verify against the expected publisher key under the epoch of the route the - * broadcast was resolved through. + * broadcast was resolved through. The route comes from the relay, so this checks that frames + * belong together, not that the instance is live: a relay can replay a recorded instance whole. */ export class Consumer { /** The epoch frames must be signed under. */ diff --git a/js/sign/src/index.ts b/js/sign/src/index.ts index aca96f4a563..1061a81373b 100644 --- a/js/sign/src/index.ts +++ b/js/sign/src/index.ts @@ -6,8 +6,9 @@ * signs every grouped frame with its endpoint's {@link SecretKey}, binding the broadcast path, its * publisher epoch, the track, the group, the frame index, and the timestamp. A subscriber hands a * frame to the application only after it verifies against the {@link PublicKey} it expects, so a - * relay can proxy and cache without forging, replaying, retiming, or splicing content. Mirrors the - * Rust `moq-sign` crate. + * relay can proxy and cache without forging, retiming, relocating, or splicing content. Signatures + * authenticate content, not liveness: a relay that recorded an instance can replay it whole under + * its epoch. Mirrors the Rust `moq-sign` crate. * * ```ts * const key = await SecretKey.generate(); diff --git a/rs/moq-sign/README.md b/rs/moq-sign/README.md index a9b1fbcbad6..24ddc348ea1 100644 --- a/rs/moq-sign/README.md +++ b/rs/moq-sign/README.md @@ -7,7 +7,8 @@ Workspace-only implementation; this crate is not published. Per-frame Ed25519 signatures for [Media over QUIC](https://moq.dev) broadcasts. Profile `moq-sign-00` from [draft-lcurley-moq-sign](https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/). -Relays forward and cache signed frames; they cannot forge, replay, or relocate them. +Relays forward and cache signed frames; they cannot forge, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. ## Shape diff --git a/rs/moq-sign/src/broadcast.rs b/rs/moq-sign/src/broadcast.rs index b1452e6fe95..4f33da5fe39 100644 --- a/rs/moq-sign/src/broadcast.rs +++ b/rs/moq-sign/src/broadcast.rs @@ -61,7 +61,8 @@ impl std::fmt::Debug for Producer { /// The subscribing side of a signed broadcast. /// /// Every frame must verify against the expected publisher key under the epoch of the route the -/// broadcast was resolved through. +/// broadcast was resolved through. The route comes from the relay, so this checks that frames +/// belong together, not that the instance is live: a relay can replay a recorded instance whole. #[derive(Clone)] pub struct Consumer { inner: moq_net::broadcast::Consumer, diff --git a/rs/moq-sign/src/lib.rs b/rs/moq-sign/src/lib.rs index 3136230ccf0..52b912a0001 100644 --- a/rs/moq-sign/src/lib.rs +++ b/rs/moq-sign/src/lib.rs @@ -4,7 +4,9 @@ //! grouped frame with its endpoint's [`SecretKey`], binding the broadcast path, its publisher //! epoch, the track, the group, the frame index, and the timestamp. A subscriber hands a frame //! to the application only after it verifies against the [`PublicKey`] it expects, so a relay -//! can proxy and cache without forging, replaying, retiming, or splicing content. +//! can proxy and cache without forging, retiming, relocating, or splicing content. Signatures +//! authenticate content, not liveness: a relay that recorded an instance can replay it whole under +//! its epoch. //! //! [draft-lcurley-moq-sign]: https://datatracker.ietf.org/doc/draft-lcurley-moq-sign/ //! From f3e2e7b661bab98e00d4b4f3de80e0b3443761e5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 01:00:48 -0700 Subject: [PATCH 10/10] fix(sign): never sign a group sequence twice under an epoch moq-net serves an aborted or evicted group sequence again, so a signer could sign two groups at the same coordinates, and a relay holding both could splice their frames into a group that was never published. Group sequences now only rise per track under an epoch, kept across a track's replacements, in both moq-sign and @moq/sign, and the draft requires it. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-sign.md | 2 ++ js/sign/src/broadcast.ts | 9 ++++++- js/sign/src/sign.test.ts | 31 +++++++++++++++++++-- js/sign/src/track.ts | 46 ++++++++++++++++++++++++++------ rs/moq-sign/src/broadcast.rs | 15 ++++++++++- rs/moq-sign/src/tests.rs | 44 ++++++++++++++++++++++++++++-- rs/moq-sign/src/track.rs | 45 +++++++++++++++++++++++++------ 7 files changed, 170 insertions(+), 22 deletions(-) diff --git a/drafts/draft-lcurley-moq-sign.md b/drafts/draft-lcurley-moq-sign.md index 9a231ba5e74..59cb3c65a3d 100644 --- a/drafts/draft-lcurley-moq-sign.md +++ b/drafts/draft-lcurley-moq-sign.md @@ -115,6 +115,7 @@ A subscriber uses the name it subscribed to, never one a relay reports. **group**: The group sequence. +A publisher instance MUST NOT sign two groups at the same sequence of a track, even after the first is aborted or evicted, or after the track is replaced. **frame**: The frame's index within its group. @@ -171,6 +172,7 @@ The publisher's secret key is trusted; anyone holding it can sign as that endpoi The signature binds every field a relay could otherwise change to move or retime an authentic frame: the path, the epoch, the track, the group, the frame index, and the timestamp. Binding the epoch keeps a frame from an earlier instance of the same broadcast, which restarted its sequences, from verifying in a later one. +Within an instance, a signed position names one frame only because the publisher never signs a group sequence twice; a relay holding two groups signed at one sequence could splice their frames into a group that was never published. Binding the timestamp keeps a relay from changing when a frame presents. Any subscriber can verify but none can sign, so subscribers that share a broadcast cannot forge frames to each other, as they could with a shared symmetric key. diff --git a/js/sign/src/broadcast.ts b/js/sign/src/broadcast.ts index f7c445e12ea..53394fdb52b 100644 --- a/js/sign/src/broadcast.ts +++ b/js/sign/src/broadcast.ts @@ -24,6 +24,8 @@ export class Producer { #inner: NetBroadcast.Producer; #key: SecretKey; #path: Path.Valid; + // Each track's lowest unsigned sequence, kept across the track's replacements. + #sequences = new Map(); /** Sign `inner` with `key`, as the broadcast at application path `path`, taking ownership of it: {@link close} ends it. */ constructor(inner: NetBroadcast.Producer, key: SecretKey, path: Path.Valid) { @@ -41,7 +43,12 @@ export class Producer { createTrack(name: string, info: Partial = {}): Track.Producer { const inner = this.#inner.createTrack(name, info); const timescale = info.timescale ?? undefined; - return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.epoch, name), timescale); + let sequences = this.#sequences.get(name); + if (!sequences) { + sequences = { next: 0 }; + this.#sequences.set(name, sequences); + } + return Track.Producer.make(inner, this.#key, new Scope(this.#path, this.epoch, name), sequences, timescale); } /** End the wrapped broadcast, as `@moq/net`'s `close` does. Idempotent. */ diff --git a/js/sign/src/sign.test.ts b/js/sign/src/sign.test.ts index a228c679ab3..08c4e31749f 100644 --- a/js/sign/src/sign.test.ts +++ b/js/sign/src/sign.test.ts @@ -55,7 +55,7 @@ async function publish(key: SecretKey, path: Path.Valid) { /** A signed track over a net track the test can also write forged frames to. */ track(name: string) { const raw = publication.broadcast.createTrack(name); - return { signed: Track.Producer.make(raw, key, new Scope(path, signed.epoch, name)), raw }; + return { signed: Track.Producer.make(raw, key, new Scope(path, signed.epoch, name), { next: 0 }), raw }; }, async consume(expected: PublicKey): Promise { return new Signed.Consumer(await active(net.subscriber, path), expected, path); @@ -119,7 +119,7 @@ test("a forged frame delivers nothing and ends only its group", async () => { await expect(group?.readFrame()).rejects.toEqual(new Failure("signature")); await expect(group?.readFrame()).rejects.toEqual(new Failure("signature")); - const next = signed.appendGroup(); + const next = signed.createGroup(1); await next.writeFrame(undefined, encoder.encode("after")); next.finish(); expect(await payload(await track.recvGroup())).toBe("after"); @@ -164,6 +164,33 @@ test("a frame replayed into another group or track is refused", async () => { published.close(); }); +test("a group sequence is never signed twice", async () => { + const key = await SecretKey.generate(); + const published = await publish(key, Path.from("mesh/node/ssh")); + const track = published.signed.createTrack("stream"); + const group = track.appendGroup(); + await group.writeFrame(undefined, encoder.encode("first")); + group.abort(new Error("retry")); + + // Net would serve the aborted sequence again, but frames of both incarnations would verify, + // so a relay holding both could splice them into one group. + expect(() => track.createGroup(0)).toThrow("duplicate group"); + expect(track.appendGroup().sequence).toBe(1); + expect(() => track.createGroup(1)).toThrow("duplicate group"); + expect(track.createGroup(5).sequence).toBe(5); + expect(() => track.createGroup(3)).toThrow("duplicate group"); + + // A replacement track continues past its predecessor's sequences under the same epoch. + track.abort(new Error("replaced")); + const replacement = published.signed.createTrack("stream"); + expect(() => replacement.createGroup(0)).toThrow("duplicate group"); + expect(replacement.appendGroup().sequence).toBe(6); + + replacement.close(); + published.signed.close(); + published.close(); +}); + test("a broadcast signed under another key is refused", async () => { const impostor = await SecretKey.generate(); const victim = await SecretKey.generate(); diff --git a/js/sign/src/track.ts b/js/sign/src/track.ts index 7c655243ede..67d1423f051 100644 --- a/js/sign/src/track.ts +++ b/js/sign/src/track.ts @@ -9,11 +9,20 @@ import type { PublicKey, SecretKey } from "./key.ts"; import { Pump } from "./pump.ts"; import type { Scope } from "./scope.ts"; +/** The lowest group sequence an instance has not signed on a track, shared with the track's replacements. @internal */ +export interface Sequences { + next: number; +} + /** * Producer for one signed track. * * Every write on the track and its groups runs through one serial pump, so net writes land in * call order. + * + * Group sequences only rise under an epoch, even across a replacement of the track, so no two + * groups are signed at the same coordinates. A relay holding an aborted group and a new group at + * its sequence could otherwise splice their frames into a group that was never published. */ export class Producer { /** The track name. */ @@ -21,17 +30,31 @@ export class Producer { #inner: NetTrack.Producer; #writer: Group.Writer; + #sequences: Sequences; #finished = false; - private constructor(inner: NetTrack.Producer, key: SecretKey, scope: Scope, timescale?: Time.Timescale) { + private constructor( + inner: NetTrack.Producer, + key: SecretKey, + scope: Scope, + sequences: Sequences, + timescale?: Time.Timescale, + ) { this.#inner = inner; this.name = inner.name; this.#writer = { pump: new Pump(), key, scope, timescale, closed: false }; + this.#sequences = sequences; } /** Sign `inner`, whose info declared `timescale` (undefined when untimed). @internal */ - static make(inner: NetTrack.Producer, key: SecretKey, scope: Scope, timescale?: Time.Timescale): Producer { - return new Producer(inner, key, scope, timescale); + static make( + inner: NetTrack.Producer, + key: SecretKey, + scope: Scope, + sequences: Sequences, + timescale?: Time.Timescale, + ): Producer { + return new Producer(inner, key, scope, sequences, timescale); } /** The track's final outcome, once its declared end is reached or it aborts. */ @@ -39,16 +62,23 @@ export class Producer { return this.#inner.closed; } - /** Start a group at the next sequence. */ + /** Start a group one past the highest sequence this instance signed on the track. */ appendGroup(): Group.Producer { - this.#writable(); - return Group.Producer.make(this.#inner.appendGroup(), this.#writer); + return this.createGroup(this.#sequences.next); } - /** Start a group at an explicit sequence; throws the net error if the track already holds it. */ + /** + * Start a group at an explicit sequence, above any this instance signed on the track. + * + * Throws if this instance already signed the sequence or a later one, even in a group since + * aborted or evicted, or the net error if the track refuses it. + */ createGroup(sequence: number): Group.Producer { this.#writable(); - return Group.Producer.make(this.#inner.createGroup(sequence), this.#writer); + if (sequence < this.#sequences.next) throw new Error(`duplicate group: sequence=${sequence}`); + const inner = this.#inner.createGroup(sequence); + this.#sequences.next = sequence + 1; + return Group.Producer.make(inner, this.#writer); } /** Declare the end after queued writes. Existing groups may still be written; new groups are refused. Idempotent. */ diff --git a/rs/moq-sign/src/broadcast.rs b/rs/moq-sign/src/broadcast.rs index 4f33da5fe39..15eee2d58e6 100644 --- a/rs/moq-sign/src/broadcast.rs +++ b/rs/moq-sign/src/broadcast.rs @@ -3,6 +3,9 @@ //! A relay may mount a broadcast under another prefix, so the path a signature binds is the one //! the application names, never the path the transport reports. +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; + use crate::error::{Error, Result}; use crate::key::{PublicKey, SecretKey}; use crate::scope::Scope; @@ -18,6 +21,8 @@ pub struct Producer { key: SecretKey, path: moq_net::Path, epoch: moq_net::Epoch, + // Each track's lowest unsigned sequence, kept across the track's replacements. + next: Arc>>>>, } impl Producer { @@ -28,6 +33,7 @@ impl Producer { key, path, epoch: moq_net::Epoch::mint(), + next: Arc::default(), } } @@ -44,7 +50,14 @@ impl Producer { pub fn create_track(&self, name: &str, info: impl Into>) -> Result { let inner = self.inner.create_track(name, info)?; let scope = Scope::new(&self.path, &self.epoch, name); - Ok(track::Producer::new(inner, self.key.clone(), scope)) + let next = Arc::clone( + self.next + .lock() + .expect("signed sequences") + .entry(name.to_owned()) + .or_default(), + ); + Ok(track::Producer::new(inner, self.key.clone(), scope, next)) } } diff --git a/rs/moq-sign/src/tests.rs b/rs/moq-sign/src/tests.rs index d2b3603226d..5a71485dd41 100644 --- a/rs/moq-sign/src/tests.rs +++ b/rs/moq-sign/src/tests.rs @@ -202,7 +202,10 @@ impl Published { fn track(&self, key: &SecretKey, name: &str) -> (track::Producer, moq_net::track::Producer) { let net = self._publication.broadcast().create_track(name, None).unwrap(); let scope = Scope::new(&self.path, self.signed.epoch(), name); - (track::Producer::new(net.clone(), key.clone(), scope), net) + ( + track::Producer::new(net.clone(), key.clone(), scope, Arc::default()), + net, + ) } } @@ -274,7 +277,7 @@ async fn forged_frame_delivers_nothing_and_ends_only_its_group() { // The group stays ended, even though a later frame is buffered. assert!(matches!(read(&mut group).await, Err(Error::Signature))); - let mut next = signed.append_group().unwrap(); + let mut next = signed.create_group(1).unwrap(); next.write_frame(None, b"after").unwrap(); next.finish().unwrap(); let mut group = recv_group(&mut track).await; @@ -381,6 +384,43 @@ async fn frame_from_an_earlier_instance_is_refused() { )); } +#[test] +fn group_sequence_is_never_signed_twice() { + let key = SecretKey::generate(); + let net = moq_net::broadcast::Info::new().produce(); + let signed = broadcast::Producer::new(net, key, moq_net::Path::new("mesh/node/ssh").unwrap()); + let track = signed.create_track("stream", None).unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(None, b"first").unwrap(); + group.abort(moq_net::Error::Cancel).unwrap(); + + // Net would serve the aborted sequence again, but frames of both incarnations would verify, + // so a relay holding both could splice them into one group. + assert!(matches!( + track.create_group(0), + Err(Error::Net(moq_net::Error::Duplicate)) + )); + assert_eq!(track.append_group().unwrap().sequence(), 1); + assert!(matches!( + track.create_group(1), + Err(Error::Net(moq_net::Error::Duplicate)) + )); + assert_eq!(track.create_group(5).unwrap().sequence(), 5); + assert!(matches!( + track.create_group(3), + Err(Error::Net(moq_net::Error::Duplicate)) + )); + + // A replacement track continues past its predecessor's sequences under the same epoch. + track.abort(moq_net::Error::Cancel).unwrap(); + let replacement = signed.create_track("stream", None).unwrap(); + assert!(matches!( + replacement.create_group(0), + Err(Error::Net(moq_net::Error::Duplicate)) + )); + assert_eq!(replacement.append_group().unwrap().sequence(), 6); +} + #[tokio::test(start_paused = true)] async fn group_resumed_above_frame_zero_verifies_at_its_index() { let key = SecretKey::generate(); diff --git a/rs/moq-sign/src/track.rs b/rs/moq-sign/src/track.rs index 83ede31384e..684d3e6d4ea 100644 --- a/rs/moq-sign/src/track.rs +++ b/rs/moq-sign/src/track.rs @@ -1,7 +1,7 @@ //! Signing producer and verifying subscriber for one track. use std::fmt; -use std::sync::Arc; +use std::sync::{Arc, Mutex}; use std::task::{Poll, ready}; use crate::error::Result; @@ -10,15 +10,31 @@ use crate::key::{PublicKey, SecretKey}; use crate::scope::Scope; /// Producer for one signed track. +/// +/// Group sequences only rise under an epoch, even across a replacement of the track, so no two +/// groups are signed at the same coordinates. A relay holding an aborted group and a new group at +/// its sequence could otherwise splice their frames into a group that was never published. pub struct Producer { inner: moq_net::track::Producer, key: SecretKey, scope: Arc, + // The lowest sequence this instance has not signed on the track, shared with its replacements. + next: Arc>, } impl Producer { - pub(crate) fn new(inner: moq_net::track::Producer, key: SecretKey, scope: Arc) -> Self { - Self { inner, key, scope } + pub(crate) fn new( + inner: moq_net::track::Producer, + key: SecretKey, + scope: Arc, + next: Arc>, + ) -> Self { + Self { + inner, + key, + scope, + next, + } } /// The track name. @@ -26,23 +42,36 @@ impl Producer { self.inner.name() } - /// Start a group at the next sequence. + /// Start a group one past the highest sequence this instance signed on the track. /// /// # Errors /// /// A net error if the track is closed. pub fn append_group(&self) -> Result { - let inner = self.inner.append_group()?; - Ok(self.group(inner)) + self.claim(None) } - /// Start a group at an explicit sequence. + /// Start a group at an explicit sequence, above any this instance signed on the track. /// /// # Errors /// - /// A net error if the track is closed or already holds the sequence. + /// [`moq_net::Error::Duplicate`] if this instance already signed the sequence or a later one, + /// even in a group since aborted or evicted, or a net error if the track is closed. pub fn create_group(&self, sequence: u64) -> Result { + self.claim(Some(sequence)) + } + + fn claim(&self, sequence: Option) -> Result { + let mut next = self.next.lock().expect("signed sequences"); + let sequence = sequence.unwrap_or(*next); + if sequence < *next { + return Err(moq_net::Error::Duplicate.into()); + } + let after = sequence + .checked_add(1) + .ok_or(moq_net::Error::from(moq_net::BoundsExceeded))?; let inner = self.inner.create_group(moq_net::group::Info { sequence })?; + *next = after; Ok(self.group(inner)) }