diff --git a/Cargo.lock b/Cargo.lock index f8f659fe236..163f9e36ba8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5892,6 +5892,24 @@ dependencies = [ "toml 1.1.6+spec-1.1.0", ] +[[package]] +name = "moq-sign" +version = "0.0.1" +dependencies = [ + "aws-lc-rs", + "bench-harness", + "bytes", + "data-encoding", + "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 de4f1c52b45..64146a1b172 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -39,6 +39,7 @@ default-members = [ "rs/moq-rtsp", "rs/moq-scene", "rs/moq-shaper", + "rs/moq-sign", "rs/moq-sock", "rs/moq-srt", "rs/moq-stats", @@ -106,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/bun.lock b/bun.lock index f42718e0e13..ca4e7fc2f78 100644 --- a/bun.lock +++ b/bun.lock @@ -381,6 +381,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", @@ -897,6 +910,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/doc/concept/standard.md b/doc/concept/standard.md index 68ccd9d86c1..3f686ba23da 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, 20, 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 393a1fedd61..afbaa85c9c2 100644 --- a/doc/lib/js/index.md +++ b/doc/lib/js/index.md @@ -32,6 +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, 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 d6093c51d3b..32605008b6c 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -36,6 +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, 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/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..59cb3c65a3d --- /dev/null +++ b/drafts/draft-lcurley-moq-sign.md @@ -0,0 +1,213 @@ +--- +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 + 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 + e2ee: I-D.lcurley-moq-e2ee + 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, 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 it, retiming it, or moving it to another position. + +--- 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. + +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`. +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 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. + +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) + || u64(timescale) + || u64(timestamp) + || 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. +The epoch names one sequence space: a publisher that restarts its group sequences signs under a new one. + +**track**: +The UTF-8 track name. +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. +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. +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`). + +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, 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 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. + +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. +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. + + +# 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 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/drafts/moq-sign-00.json b/drafts/moq-sign-00.json new file mode 100644 index 00000000000..6f854a0d3ac --- /dev/null +++ b/drafts/moq-sign-00.json @@ -0,0 +1,410 @@ +{ + "profile": "moq-sign-00", + "constants": { + "label": "6d6f712d7369676e2d3030", + "key_len": 32, + "signature_len": 64 + }, + "keys": [ + { + "id": "rfc8032-test-1", + "seed": "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60", + "public": "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a", + "endpoint": "47pjoycnsrfmxikm95jh13y88e8qnhzu5kungjpxyepgt7a8krpy" + }, + { + "id": "test", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "public": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y" + }, + { + "id": "other", + "seed": "6d6f712d7369676e2d3030206f74686572207365656421212121212121212121", + "public": "a159de3c301ce808bc042676c8f609ef61e4aed5181df8a002a7e014091d3758", + "endpoint": "wfc7hxboduwytxyrr35ct7oj77o6jmsidyq9teynw9obene7g7cy" + }, + { + "id": "ones", + "public": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", + "endpoint": "999999999999999999999999999999999999999999999999999o" + } + ], + "frames": [ + { + "id": "base", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "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": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e" + }, + { + "id": "empty-payload", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 0, + "timescale": 0, + "timestamp": 0, + "payload": "", + "message": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d0000000000000003000000000000000000000000000000000000000000000000", + "body": "c8d983a9846d860b5f0b76997eeb943e16e487fc24e28b6266866806cf97845cf98e7036416b86e004fba15157503cb9871ff46f6fa1d9474164e3b3f8e1ad00" + }, + { + "id": "group-above-u32", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "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": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000001000000000500000000000000000000000000000000000000000000000068656c6c6f", + "body": "68656c6c6f224feecc93d46bce865c75815dbd11b07632a6e63895e165a049b6629b38c9db04e429979f293b240cc92f21af5b84620a3eeef9afaeff5469c3911903ddb70b" + }, + { + "id": "frame-above-u32", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "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": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000001000000000000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fab70f52b0543b17d166cf5741abffd14c47df0ca80affb2630caf63be2550eb4c66bcbe3d00f7699f2b7608b06f6bfd8abfe0b3a0400512a1ae804d12e08c80a" + }, + { + "id": "max-u53", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "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": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d001fffffffffffff00000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6fe963734e25dadea272b61c217cb582ef02c1d3c5b9306150557856e990a14c5aab94f20177fd01025c4895b32914c34fdfab28f25a12c9a9ce9684598bfda90b" + }, + { + "id": "empty-path-utf8-track", + "seed": "6d6f712d7369676e2d3030207465737420736565642121212121212121212121", + "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": "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", + "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": "6d6f712d7369676e2d3030000000000000000d6d6573682f6e6f64652f737368000000000000002430313961326233632d346435652d376636302d386131622d326333643465356636613762000000000000000673747265616d000000000000000300000000000000010000000000000000000000000000000068656c6c6f", + "body": "68656c6c6f68c375b5d8b44fdd7fc89fa39809855c38a73a7168fa0301bf1a6b5fa6b482471e402d1effdbf943bd7a2c04b4dafb7adf342394cd4e65a4530f3f7cf0e87700" + } + ], + "negative": [ + { + "id": "relocated-path", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/http", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "relocated-epoch", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7c", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "relocated-track", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream2", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "relocated-group", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 4, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "relocated-frame", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 0, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "shifted-boundary", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/sshs", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "tream", + "group": 3, + "frame": 1, + "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", + "endpoint": "wfc7hxboduwytxyrr35ct7oj77o6jmsidyq9teynw9obene7g7cy", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "tampered-payload", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "69656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e", + "error": "signature" + }, + { + "id": "tampered-signature", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0f", + "error": "signature" + }, + { + "id": "appended-byte", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e758b7f5458f0e00", + "error": "signature" + }, + { + "id": "truncated", + "endpoint": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y", + "path": "mesh/node/ssh", + "epoch": "019a2b3c-4d5e-7f60-8a1b-2c3d4e5f6a7b", + "track": "stream", + "group": 3, + "frame": 1, + "timescale": 0, + "timestamp": 0, + "body": "68656c6c6fa7fb15e4a621a495794c2c9a15afded4df4277277da75cffe036ef1b32937d8e1a598b0c1671a796db9b12610692f99547bcea449c786b6a57e7", + "error": "signature" + }, + { + "id": "empty", + "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" + } + ], + "invalid_ids": [ + { + "id": "uppercase", + "text": "EYAMFTWCF3SCK8RS5M1MEUGF8ODWQG78473T7P3ST9WXOB9CSZ8Y" + }, + { + "id": "short", + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8" + }, + { + "id": "long", + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8yy" + }, + { + "id": "outside-alphabet", + "text": "0yamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8y" + }, + { + "id": "trailing-bits", + "text": "eyamftwcf3sck8rs5m1meugf8odwqg78473t7p3st9wxob9csz8b" + }, + { + "id": "hex", + "text": "4030b2c68c2e6cc51c96dae4b44cc53c07471ba7d7731eb7368fe8f807ecb5ce" + }, + { + "id": "empty", + "text": "" + } + ] +} diff --git a/drafts/moq-sign-00.ts b/drafts/moq-sign-00.ts new file mode 100644 index 00000000000..9a23a4c219f --- /dev/null +++ b/drafts/moq-sign-00.ts @@ -0,0 +1,376 @@ +#!/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. 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); +} + +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 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; + 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), + u64(identity.timescale), + u64(identity.timestamp), + payload, + ); +} + +/** The endpoint ID of a 32-byte public key: its 52-character z-base-32. */ +export function endpointId(key: Uint8Array): string { + return zbase32(key); +} + +/** Parse an endpoint ID: exactly 52 z-base-32 characters with zero trailing bits. */ +export function parseKey(text: string): Uint8Array { + 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 { + 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; + timescale: number; + timestamp: number; +}; + +function identityJson(identity: Identity): IdentityJson { + 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), + timescale: BigInt(row.timescale), + timestamp: BigInt(row.timestamp), + }; +} + +async function frameVector(id: string, seed: string, identity: Identity, payload: Uint8Array) { + return { + id, + seed, + endpoint: endpointId(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, + 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 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, + endpoint, + ...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, + 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), + 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("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: [ + 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("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]))), + 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, 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: "" }, + ], + }; +} + +async function check(doc: Awaited>): Promise { + for (const row of doc.keys) { + 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(parseKey(row.endpoint), identity, hex(row.body))), + row.payload, + ); + } + for (const row of doc.negative) { + 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)); + } +} + +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/js/sign/README.md b/js/sign/README.md new file mode 100644 index 00000000000..530ed7085d1 --- /dev/null +++ b/js/sign/README.md @@ -0,0 +1,50 @@ +

+ 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, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. + +## Shape + +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, 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"; +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. 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 + +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/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..53394fdb52b --- /dev/null +++ b/js/sign/src/broadcast.ts @@ -0,0 +1,103 @@ +/** + * 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; + // 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) { + 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); + const timescale = info.timescale ?? undefined; + 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. */ + 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. 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. */ + 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..a1263e2222b --- /dev/null +++ b/js/sign/src/group.ts @@ -0,0 +1,174 @@ +/** + * 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 at the track's timescale, or `undefined` when untimed. 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; + // 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; +} + +/** + * 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(); + // 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, at, owned); + this.#check(); + this.#inner.writeFrame({ payload: body, timestamp: at }); + 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.timestamp, + 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..1061a81373b --- /dev/null +++ b/js/sign/src/index.ts @@ -0,0 +1,40 @@ +/** + * 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, 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, 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(); + * 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"; +/** 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..c94dcb2c0fc --- /dev/null +++ b/js/sign/src/key.ts @@ -0,0 +1,98 @@ +/** + * Endpoint keys: an Ed25519 secret key and the public key that names its endpoint. + * + * @module + */ +import { Failure } from "./failure.ts"; +import * as ZBase32 from "./zbase32.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 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; + #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. @internal */ + 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 52 z-base-32 characters. */ + static parse(text: string): PublicKey { + const bytes = ZBase32.decode(text, KEY_LEN); + if (!bytes) throw new Failure("key"); + return new PublicKey(bytes); + } + + /** Whether `other` is the same key. */ + equals(other: PublicKey): boolean { + return this.#bytes.every((byte, i) => byte === other.#bytes[i]); + } + + /** The endpoint ID: 52 z-base-32 characters. */ + toString(): string { + return ZBase32.encode(this.#bytes); + } + + /** 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..caf673e2557 --- /dev/null +++ b/js/sign/src/scope.ts @@ -0,0 +1,88 @@ +// The signed message: what a frame's signature binds besides its payload. +import type { Epoch, Path, Time } 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. +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`, 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); + 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, + 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); + 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, + 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, 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 new file mode 100644 index 00000000000..08c4e31749f --- /dev/null +++ b/js/sign/src/sign.test.ts @@ -0,0 +1,209 @@ +// 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.follow(path); + 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), { next: 0 }), 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")); + // 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); + 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); + 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(); + 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.createGroup(1); + 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 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(); + 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..67d1423f051 --- /dev/null +++ b/js/sign/src/track.ts @@ -0,0 +1,153 @@ +/** + * Signing producer and verifying subscriber for one track. + * + * @module + */ +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"; +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. */ + readonly name: string; + + #inner: NetTrack.Producer; + #writer: Group.Writer; + #sequences: Sequences; + #finished = false; + + 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, + 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. */ + get closed(): NetTrack.Producer["closed"] { + return this.#inner.closed; + } + + /** Start a group one past the highest sequence this instance signed on the track. */ + appendGroup(): Group.Producer { + return this.createGroup(this.#sequences.next); + } + + /** + * 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(); + 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. */ + 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..7e69e27ff94 --- /dev/null +++ b/js/sign/src/vectors.test.ts @@ -0,0 +1,91 @@ +// Every vector in drafts/moq-sign-00.json, run against the internal primitives. +import { expect, test } from "bun:test"; +import { Epoch, type Path, Time } 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)); +} + +// 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 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, 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.endpoint)), group, frame, at, 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.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")); + } + expect(() => PublicKey.fromBytes(new Uint8Array(31))).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/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 a52fb46a138..aeb657e49c1 100644 --- a/package.json +++ b/package.json @@ -42,6 +42,7 @@ "js/pattern", "js/auth", "js/e2ee", + "js/sign", "js/json", "js/libav", "js/hang", 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/Cargo.toml b/rs/moq-sign/Cargo.toml new file mode 100644 index 00000000000..8b1bff66dbc --- /dev/null +++ b/rs/moq-sign/Cargo.toml @@ -0,0 +1,37 @@ +[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 } +data-encoding = { workspace = true } +kio = { workspace = true } +moq-net = { workspace = true } +thiserror = { workspace = true } +zeroize = { workspace = true } + +[dev-dependencies] +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"] } + +[[bench]] +name = "sign" +harness = false + +[lints] +workspace = true diff --git a/rs/moq-sign/README.md b/rs/moq-sign/README.md new file mode 100644 index 00000000000..24ddc348ea1 --- /dev/null +++ b/rs/moq-sign/README.md @@ -0,0 +1,45 @@ +[![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, retime, or relocate them. Signatures +authenticate content, not liveness: a relay that recorded an instance can replay it whole. + +## Shape + +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, 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")?; +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. 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. + +## 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/benches/sign.rs b/rs/moq-sign/benches/sign.rs new file mode 100644 index 00000000000..06669bd31b1 --- /dev/null +++ b/rs/moq-sign/benches/sign.rs @@ -0,0 +1,88 @@ +//! 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(&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/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/rs/moq-sign/src/broadcast.rs b/rs/moq-sign/src/broadcast.rs new file mode 100644 index 00000000000..15eee2d58e6 --- /dev/null +++ b/rs/moq-sign/src/broadcast.rs @@ -0,0 +1,136 @@ +//! 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 std::collections::HashMap; +use std::sync::{Arc, Mutex}; + +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, + // Each track's lowest unsigned sequence, kept across the track's replacements. + next: Arc>>>>, +} + +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(), + next: Arc::default(), + } + } + + /// 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); + 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)) + } +} + +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. 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, + 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..f304aab3438 --- /dev/null +++ b/rs/moq-sign/src/group.rs @@ -0,0 +1,164 @@ +//! 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 at the track's timescale, or `None` when untimed. 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<()> { + // 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, timestamp, 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.timestamp, 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..aa977c818bc --- /dev/null +++ b/rs/moq-sign/src/key.rs @@ -0,0 +1,197 @@ +//! 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; + +/// 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 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) + .verify(message, signature) + .is_ok() + } +} + +/// 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 52 z-base-32 characters")] +#[non_exhaustive] +pub struct InvalidKey; + +impl FromStr for PublicKey { + type Err = InvalidKey; + + fn from_str(text: &str) -> Result { + Ok(Self(decode(text)?)) + } +} + +impl fmt::Display for PublicKey { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&ZBASE32.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 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]; + 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) +} + +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 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. + /// + /// # 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), + }; + // 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()?; + 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 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 52 z-base-32 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..52b912a0001 --- /dev/null +++ b/rs/moq-sign/src/lib.rs @@ -0,0 +1,34 @@ +//! 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, 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, 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/ +//! +//! 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}; + +#[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..23b4ede72ce --- /dev/null +++ b/rs/moq-sign/src/scope.rs @@ -0,0 +1,88 @@ +//! 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(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"; + +/// 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`, 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); + 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, + 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); + 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, + 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, 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 new file mode 100644 index 00000000000..5a71485dd41 --- /dev/null +++ b/rs/moq-sign/src/tests.rs @@ -0,0 +1,564 @@ +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, 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()); + 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 id = &row["id"]; + let endpoint = public(&row["endpoint"]); + assert_eq!( + endpoint, + PublicKey::from_bytes(hex(&row["public"]).try_into().unwrap()), + "{id}" + ); + assert_eq!(endpoint.to_string(), row["endpoint"].as_str().unwrap(), "{id}"); + if !row["seed"].is_null() { + assert_eq!(seed(&row["seed"]).public(), endpoint, "{id}"); + } + } +} + +#[test] +fn vector_frames() { + for row in vectors()["frames"].as_array().unwrap() { + let id = &row["id"]; + let (scope, group, frame, timestamp) = identity(row); + let payload = hex(&row["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["endpoint"]), group, frame, timestamp, 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, timestamp) = identity(row); + let body = Bytes::from(hex(&row["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"]); + } +} + +#[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()); + // 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(); + 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(""), "{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(&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, Arc::default()), + 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(); + // Signed at the track's scale, which the net group converts it to. + group + .write_frame(moq_net::Timestamp::from_micros(2_400).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())); + 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); +} + +#[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.create_group(1).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) + )); +} + +#[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(); + 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))); +} + +/// 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 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() { + 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(); + 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)| serde_json::json!({ "payload": payload, "micros": micros.map(|m| m[frame]) })) + .collect(); + 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, 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(), 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 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(|(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, expected); + // The same body does not verify at the neighboring group. + 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/rs/moq-sign/src/track.rs b/rs/moq-sign/src/track.rs new file mode 100644 index 00000000000..684d3e6d4ea --- /dev/null +++ b/rs/moq-sign/src/track.rs @@ -0,0 +1,196 @@ +//! Signing producer and verifying subscriber for one track. + +use std::fmt; +use std::sync::{Arc, Mutex}; +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. +/// +/// 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, + next: Arc>, + ) -> Self { + Self { + inner, + key, + scope, + next, + } + } + + /// The track name. + pub fn name(&self) -> &str { + self.inner.name() + } + + /// 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 { + self.claim(None) + } + + /// Start a group at an explicit sequence, above any this instance signed on the track. + /// + /// # Errors + /// + /// [`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)) + } + + 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 diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 7f8bc0d4698..1f91340dc74 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -122,9 +122,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 ;; diff --git a/test/interop/sign.ts b/test/interop/sign.ts new file mode 100644 index 00000000000..01ab2657810 --- /dev/null +++ b/test/interop/sign.ts @@ -0,0 +1,85 @@ +/** 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, 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 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)); +} + +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, 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, 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); + 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 producers = new Map(); +const taps = new Map(); +const js: Group[] = []; +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, micros } of frames) { + await group.writeFrame(micros == null ? undefined : Time.Timestamp.fromMicros(micros), unhex(payload)); + } + group.finish(); + const raw = await taps.get(track)?.recvGroup(); + assert(raw); + 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 })); diff --git a/test/justfile b/test/justfile index 8fa22166d21..cd28eadbc02 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