diff --git a/Cargo.lock b/Cargo.lock index 2bbc0785f5a..6b28a777444 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2943,6 +2943,7 @@ name = "hang" version = "0.21.11" dependencies = [ "anyhow", + "base64 0.23.1", "bytes", "derive_more 2.1.1", "hang", @@ -2959,6 +2960,7 @@ dependencies = [ "tokio", "tracing", "url", + "uuid", "workspace-hack", ] diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 1e30df81c5a..5b81c0af9a2 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -64,6 +64,7 @@ A few things the catalog can express beyond decoder config: - **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track. - **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. `@moq/watch` and `moqsrc` follow a referenced path's announcements like their own, restarting the rendition on each instance that serves it; every other reader, such as `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `instance` beside the path names the [stream](/concept/moq-lite#publisher-instances) it expects: a route of another instance ends the rendition instead of falling back to it, while a route whose instance a session minted (one that crossed an older version) cannot prove one, so there it is best effort. Omit `instance` for a broadcast produced on demand, which has none until a worker answers; see [identity and recovery](/concept/identity). - **Whole includes.** A root `include` map names whole broadcasts, such as transcoded renditions of the source, by the same relative path and optional `instance` as a rendition's reference. They share the listing catalog's PTS timeline and root settings, including its clock and join interval. Listing one opens nothing, so an include produced on demand starts only once a viewer selects it, which `@moq/watch` does with `broadcast.include(effect, id)`. Its rendition IDs stay its own. +- **DRM.** A root `drm` map describes the DRM systems protecting Common Encryption CMAF renditions, one entry per system, scheme, and key: its `system` and `kid` UUIDs, the `pssh` box, and the `license` and `certificate` servers. A protected rendition lists its entries' IDs in its own `drm` field, keeps the encrypted sample entry in its `init`, and names the codec that entry wraps. A rendition listing any ID is protected, even when its entry is one a reader cannot parse, so an unknown scheme or a malformed entry hides only the renditions it protects. An entry that is not a JSON object, or an ID the map lacks, still refuses the whole catalog. The MSF catalog carries the same entries as CMSF `contentProtections`. See [Content protection](#content-protection). - **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition. - **Jitter.** A rendition can say how much media it writes behind a frame's timestamp, in whole milliseconds rounded up: the reorder delay of B-frames and the span of a fragment or batch written together. It is measured from media timestamps alone, never the time a frame was written, so neither a constant encoder delay nor a capture clock counts. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent. - **Delay.** A rendition can also say how far its frames' timestamps trail those another rendition already wrote, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. A rendition alone measures none. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's. @@ -240,6 +241,42 @@ derived from the credential and a semantic name such as `foo.hang`; it carries no format marker. `moq-crypto` is the Rust implementation. Relays need no configuration to carry it. +## Content protection + +DRM is separate from moq-e2ee: the media itself is Common Encryption CMAF, +encrypted before it reaches MoQ by a packager such as Shaka Packager, and a +relay carries it like any other CMAF. The catalog's `drm` section names each +protected rendition's DRM systems: the scheme, key, and `pssh` from its init's +`schm`, `tenc`, and `pssh` boxes, and the license and certificate servers the +publisher supplies, which the media does not carry. + +```json +{ + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "pssh": "AAAANHBzc2gB...", + "license": { "url": "https://license.example.com/clearkey" } + } + }, + "video": { "renditions": { "video": { "codec": "avc1.64000c", "drm": ["1"], "container": { "kind": "cmaf", "init": "..." } } } } +} +``` + +WebCodecs cannot decrypt, so `@moq/watch` treats a protected rendition as +unplayable and never selects it. Playback through MSE and EME is not built yet. +Nothing in the Rust tools decrypts either: `moq play`, `moq export`, the HLS +gateway, transcoding, and the C and UniFFI bindings leave a protected rendition +out, as they would a codec they cannot decode. A recording stores every track as +published, protected ones included, and playing it back leaves them out the +same way. Every reader, `@moq/watch` included, also counts a CMAF rendition +whose `init` holds an encrypted sample entry (`encv`/`enca`) as protected when +it lists no `drm`. An entry a reader cannot parse, such as a scheme a later +draft adds, hides only the renditions that list it; an entry that is not a JSON +object refuses the catalog. + ## Your own format hang is a convention, not a requirement. If you control both ends, publish diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index fa80b68944b..1c43c2756d5 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -18,6 +18,14 @@ author: normative: moqmsf: I-D.ietf-moq-msf + moqcmsf: I-D.ietf-moq-cmsf + cenc: + title: "Information technology - MPEG systems technologies - Part 7: Common encryption in ISO base media file format files" + author: + - org: ISO/IEC + seriesinfo: + ISO/IEC: 23001-7 + date: false moql: I-D.lcurley-moq-lite moqflate: title: "DEFLATE Compressed Tracks for MoQ" @@ -160,6 +168,7 @@ type Catalog = { "broadcast": string, "instance": string | undefined, }> | undefined, + "drm": Record | undefined, // ... any custom fields ... } ~~~ @@ -172,7 +181,7 @@ For example, a chat entry should name a chat track, not carry individual chat me This way catalog updates are rare and a client MAY choose to not subscribe. The `json` and `binary` sections ({{data}}) are how a track like that is listed. -This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed in `include` ({{include}}). +This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), whole broadcasts listed in `include` ({{include}}), and the DRM systems protecting encrypted renditions ({{drm}}). ## Version {#catalog-version} The root `version` field is the oldest draft of this specification that reads the catalog correctly, by draft number: `4` needs a consumer of moq-hang-04 or later. @@ -188,7 +197,7 @@ This draft needs `version` 4 for: - a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead; - a video `warmup` ({{field-warmup}}) above zero, since an older consumer starts decoding a group at a picture that is not a keyframe. -Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints. +Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; `drm` ({{drm}}) leaves an older consumer selecting a protected rendition it then fails to decode, which raising `version` would not improve, since that would also refuse it the clear renditions; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints. ## Media {#media} The catalog's root `media` field holds what applies to every audio and video track: @@ -258,6 +267,37 @@ An include's rendition IDs belong to its own catalog and MUST NOT replace IDs in An unavailable include does not invalidate the listing catalog. A consumer does not expand an include's own `include`: each needs a selection of its own. +## DRM {#drm} +The optional root `drm` map describes the DRM systems protecting encrypted renditions. +Each key is an entry ID, and each entry is one DRM system for one Common Encryption scheme and one key: + +~~~ +type DrmSchema = { + "system": string, + "scheme": string, + "kid": string, + "pssh": string | undefined, + "license": { "url": string, "type": string | undefined } | undefined, + "certificate": { "url": string, "type": string | undefined } | undefined, +} +~~~ + +The `system` field is the DRM system ID and `kid` the default key ID, each a hyphenated UUID string, and `scheme` is the Common Encryption scheme {{cenc}}, `cenc` or `cbcs` as CMSF allows {{moqcmsf}}. +The `pssh` field is the system's whole `pssh` box, base64-encoded ({{!RFC4648, Section 4}}). +The `license` field names the server a consumer requests a license from, and `certificate` the server certificate a system such as FairPlay needs first; each `type` is the license protocol or the certificate's MIME type. +Renditions encrypted under the same system, scheme, and key MAY share an entry. + +A protected audio or video rendition lists the IDs of the entries that can decrypt it in its `drm` field, an array of strings; absent or empty lists none, and the rendition is clear unless its `init` holds an encrypted sample entry, as below. +Common Encryption is defined for CMAF, so a protected rendition is in practice a `cmaf` one ({{cmaf}}): its `init` keeps the encrypted sample entry with its `sinf`, and the `pssh` boxes, while its `codec` names the codec the encrypted entry wraps. +A rendition listing any ID is protected, whether or not the consumer can parse the entries it names. +A consumer MUST NOT reject a catalog for an entry it cannot parse, such as one with another `scheme` or a malformed UUID or URL: the renditions listing that entry stay protected, and the rest of the catalog stays usable. +A consumer MUST reject a catalog with a rendition listing an ID the root `drm` lacks, and an entry that is not a JSON object. +A consumer MUST treat a `cmaf` rendition whose `init` holds an encrypted sample entry (`encv` or `enca`) as protected, even when it lists no entry. +A consumer that cannot decrypt a protected rendition MUST treat it as one it cannot decode. + +Each entry maps onto a CMSF `contentProtections` entry {{moqcmsf}}: the ID is its `refID`, `kid` its single `defaultKID`, `system`, `license`, `certificate`, and `pssh` its `drmSystem`'s `systemID`, `laURL`, `certURL`, and `pssh`, and a rendition's `drm` its `contentProtectionRefIDs`. +A CMSF entry naming several `defaultKID`s has no single hang entry; a consumer converting it keeps it as an entry it cannot parse, so the renditions listing it stay protected. + ## Track Identity {#identity} A track name always means the same content, so a catalog update never redefines an audio or video track. A track's identity is the fields a consumer cannot change without reinitializing its decoder or demuxer: `codec`, `description`, and `container`, plus `displayAspectWidth`, `displayAspectHeight`, and `interlaced` for video and `sampleRate` and `numberOfChannels` for audio. @@ -1129,6 +1169,7 @@ This document has no IANA actions. - Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode. - Added the optional video `reorder` field: the most frames that can precede one in decode order and follow it in presentation, fixed for the track once declared. A consumer that authors decode times derives them from it and the current group alone, refusing deeper reordering; without it, a consumer infers them from timestamps. - Added an optional `instance` beside every rendition and data track `broadcast` reference ({{field-instance}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `instance` fails a rendition that resolves another stream, and is best effort against an Instance a receiver minted. +- Added the optional root `drm` map ({{drm}}) and the audio and video `drm` field: the DRM systems, scheme, and key protecting a Common Encryption `cmaf` rendition, mapping onto CMSF `contentProtections`. A rendition listing any entry is protected, and an entry a consumer cannot parse hides only the renditions that list it. - Added the optional root `include` map ({{include}}): whole broadcasts named by a relative `broadcast` and an optional `instance`, opened only on selection, whose rendition IDs stay their own. - Includes share the listing catalog's PTS timeline and root settings, including its clock and join interval. - An HLS master selects the includes it lists by reading their catalogs, without demanding media, and segments them on the listing catalog's `media`; an on-demand publisher answers its catalog without starting media production. diff --git a/js/hang/api/catalog.api.md b/js/hang/api/catalog.api.md index d0c8e83767a..81a828f41a1 100644 --- a/js/hang/api/catalog.api.md +++ b/js/hang/api/catalog.api.md @@ -7,6 +7,7 @@ import { $brand } from "zod/mini"; import { $loose } from "zod/v4/core"; import { $strip } from "zod/v4/core"; import { Net } from "@moq/hang"; +import { ZodMiniArray } from "zod/mini"; import { ZodMiniBase64 } from "zod/mini"; import { ZodMiniBoolean } from "zod/mini"; import { ZodMiniCatch } from "zod/mini"; @@ -14,16 +15,20 @@ import { ZodMiniCustom } from "zod/mini"; import { ZodMiniDefault } from "zod/mini"; import { ZodMiniDiscriminatedUnion } from "zod/mini"; import { ZodMiniEnum } from "zod/mini"; +import { ZodMiniGUID } from "zod/mini"; import { ZodMiniInt32 } from "zod/mini"; import { ZodMiniLiteral } from "zod/mini"; import { ZodMiniNumber } from "zod/mini"; import { ZodMiniObject } from "zod/mini"; import { ZodMiniOptional } from "zod/mini"; import { ZodMiniPipe } from "zod/mini"; +import { ZodMiniRecord } from "zod/mini"; import { ZodMiniString } from "zod/mini"; import { ZodMiniTransform } from "zod/mini"; import { ZodMiniType } from "zod/mini"; +import { ZodMiniURL } from "zod/mini"; import { ZodMiniUnion } from "zod/mini"; +import { ZodMiniUnknown } from "zod/mini"; import { infer } from "zod/mini"; export const Audio: { @@ -59,6 +64,7 @@ export const AudioConfigSchema: ZodMiniObject<{ }>>]>>; delay: ZodMiniOptional, "u53", "out">, ZodMiniTransform | undefined, number & $brand<"u53">>>>; description: ZodMiniOptional>; + drm: ZodMiniOptional>>; enabled: ZodMiniOptional>; instance: ZodMiniOptional>>; jitter: ZodMiniOptional, "u53", "out">, ZodMiniTransform | undefined, number & $brand<"u53">>>>; @@ -91,6 +97,7 @@ export const AudioSchema: ZodMiniObject<{ }; delay?: number & $brand<"u53"> | undefined; description?: string | undefined; + drm?: string[] | undefined; enabled?: boolean | undefined; instance?: ReferenceInstance | undefined; jitter?: number & $brand<"u53"> | undefined; @@ -203,6 +210,54 @@ export const ContainerSchema: ZodMiniDefault; + +export const DrmEntrySchema: ZodMiniUnion>; + url: ZodMiniURL; + }, $strip>>; + kid: ZodMiniGUID; + license: ZodMiniOptional>; + url: ZodMiniURL; + }, $strip>>; + pssh: ZodMiniOptional; + scheme: ZodMiniString; + system: ZodMiniGUID; +}, $strip>, ZodMiniRecord, ZodMiniUnknown>]>; + +export type DrmServer = infer; + +export const DrmServerSchema: ZodMiniObject<{ + type: ZodMiniOptional>; + url: ZodMiniURL; +}, $strip>; + +export type DrmSystem = infer; + +export const DrmSystemSchema: ZodMiniObject<{ + certificate: ZodMiniOptional>; + url: ZodMiniURL; + }, $strip>>; + kid: ZodMiniGUID; + license: ZodMiniOptional>; + url: ZodMiniURL; + }, $strip>>; + pssh: ZodMiniOptional; + scheme: ZodMiniString; + system: ZodMiniGUID; +}, $strip>; + export class DuplicateRendition extends Error { constructor(id: string); readonly id: string; @@ -285,6 +340,12 @@ export const MediaSchema: ZodMiniObject<{ }, $strip>>>; }, $strip>; +export class MissingDrm extends Error { + constructor(rendition: string, id: string); + readonly id: string; + readonly rendition: string; +} + export type Mode = infer; export const ModeSchema: ZodMiniString; @@ -350,6 +411,7 @@ export const RootSchema: ZodMiniObject<{ }; delay?: number & $brand<"u53"> | undefined; description?: string | undefined; + drm?: string[] | undefined; enabled?: boolean | undefined; instance?: ReferenceInstance | undefined; jitter?: number & $brand<"u53"> | undefined; @@ -374,6 +436,20 @@ export const RootSchema: ZodMiniObject<{ track?: string | undefined; }>, Record>>; }, $strip>, ZodMiniPipe, ZodMiniTransform>]>>; + drm: ZodMiniOptional, Record>, ZodMiniTransform | { + certificate?: { + type?: string | undefined; + url: string; + } | undefined; + kid: string; + license?: { + type?: string | undefined; + url: string; + } | undefined; + pssh?: string | undefined; + scheme: string; + system: string; + }>, Record>>>; echo: ZodMiniOptional>; }, $strip>, ZodMiniPipe, ZodMiniTransform>]>>; @@ -494,6 +570,7 @@ export const RootSchema: ZodMiniObject<{ description?: string | undefined; displayAspectHeight?: number & $brand<"u53"> | undefined; displayAspectWidth?: number & $brand<"u53"> | undefined; + drm?: string[] | undefined; enabled?: boolean | undefined; framerate?: number | undefined; instance?: ReferenceInstance | undefined; @@ -700,6 +777,7 @@ export const VideoConfigSchema: ZodMiniObject<{ description: ZodMiniOptional>; displayAspectHeight: ZodMiniOptional<$ZodBranded, "u53", "out">>; displayAspectWidth: ZodMiniOptional<$ZodBranded, "u53", "out">>; + drm: ZodMiniOptional>>; enabled: ZodMiniOptional>; framerate: ZodMiniOptional>; instance: ZodMiniOptional>>; @@ -791,6 +869,7 @@ export const VideoSchema: ZodMiniObject<{ description?: string | undefined; displayAspectHeight?: number & $brand<"u53"> | undefined; displayAspectWidth?: number & $brand<"u53"> | undefined; + drm?: string[] | undefined; enabled?: boolean | undefined; framerate?: number | undefined; instance?: ReferenceInstance | undefined; @@ -831,6 +910,11 @@ export function encode(root: Root): Root; export const hexSchema: ZodMiniString; +export function isProtected(config: { + container?: Container; + drm?: string[]; +}): boolean; + export function modeSupported(mode: Mode): mode is KnownMode; export const nonzeroU53Schema: $ZodBranded, "u53", "out">; diff --git a/js/hang/api/cmaf.api.md b/js/hang/api/cmaf.api.md index 3f8f50fb814..7c81e196891 100644 --- a/js/hang/api/cmaf.api.md +++ b/js/hang/api/cmaf.api.md @@ -15,6 +15,7 @@ export interface InitSegment { defaultSampleFlags: number; defaultSampleSize: number; description?: Uint8Array; + encrypted: boolean; kind: "audio" | "video"; timescale: number; trackId: number; diff --git a/js/hang/bench/cmaf.ts b/js/hang/bench/cmaf.ts index 840fa6ccd4f..a362a40520f 100644 --- a/js/hang/bench/cmaf.ts +++ b/js/hang/bench/cmaf.ts @@ -40,6 +40,7 @@ const init: InitSegment = { timescale: 90_000, trackId: 1, kind: "video", + encrypted: false, defaultSampleDuration: 3_000, defaultSampleSize: 0, defaultSampleFlags: 0, diff --git a/js/hang/src/catalog/audio.ts b/js/hang/src/catalog/audio.ts index 1ca49041eb7..ab77659b5c5 100644 --- a/js/hang/src/catalog/audio.ts +++ b/js/hang/src/catalog/audio.ts @@ -39,6 +39,13 @@ const AudioConfigFields = z.object({ // The container format, used to decode the timestamp and more. container: ContainerSchema, + // The IDs of the root `drm` entries protecting this rendition, one per DRM system that can + // decrypt it. Absent or empty lists none, and the rendition is still protected when its CMAF init + // holds an encrypted sample entry (see `isProtected`). Common Encryption is defined for CMAF, so in practice + // it is a CMAF rendition, and `codec` names the codec its encrypted sample entry wraps. A consumer + // that can't decrypt skips it. + drm: z.optional(z.array(z.string())), + // The description is used for some codecs. // If provided, we can initialize the decoder based on the catalog alone. // Otherwise, the initialization information is in-band. diff --git a/js/hang/src/catalog/drm.ts b/js/hang/src/catalog/drm.ts new file mode 100644 index 00000000000..36c0f4d8504 --- /dev/null +++ b/js/hang/src/catalog/drm.ts @@ -0,0 +1,91 @@ +import * as z from "zod/mini"; +import { decodeInitSegment } from "../cmaf/decode"; +import type { Container } from "./container"; + +/** + * Well-known DRM system IDs, as draft-ietf-moq-cmsf lists them. + */ +export const DRM_SYSTEM = { + widevine: "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", + playready: "9a04f079-9840-4286-ab92-e65be0885f95", + fairplay: "94ce86fb-07ff-4f43-adb8-93d2fa968ca2", + // The W3C Common System ID: for testing, since the key travels in the clear. + clearkey: "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", +} as const; + +/** A license or certificate server. */ +export const DrmServerSchema = z.object({ + url: z.url(), + // The protocol a license server speaks (e.g. `EME-1.0`), or the MIME type of a certificate. + type: z.optional(z.string()), +}); + +/** A license or certificate server. */ +export type DrmServer = z.infer; + +/** + * One DRM system protecting renditions under one Common Encryption scheme and one default key. + * + * Each protected video or audio rendition lists the IDs of its entries in its own `drm` field; + * each entry maps onto one of draft-ietf-moq-cmsf's `contentProtections`. A CMSF entry naming + * several default keys has no hang form, so it reads as one this build cannot read. + */ +export const DrmSystemSchema = z.object({ + // The DRM system ID, as a UUID string (see `DRM_SYSTEM`). + system: z.guid(), + // How the samples are encrypted: draft-ietf-moq-cmsf allows `cenc` and `cbcs`, and another + // is kept so a scheme a later draft adds leaves the rest of the catalog readable. + scheme: z.string(), + // The default key ID (`tenc`'s `default_KID`), as a UUID string. + kid: z.guid(), + // The system's whole `pssh` box from the init segment, base64. + pssh: z.optional(z.base64()), + // Where to request a license. + license: z.optional(DrmServerSchema), + // Where to fetch the server certificate, which systems such as FairPlay need first. + certificate: z.optional(DrmServerSchema), +}); + +/** One DRM system protecting renditions. */ +export type DrmSystem = z.infer; + +/** + * A root `drm` entry: one this build reads, or one it cannot (such as a malformed UUID or URL), + * kept as-is. A rendition listing either is protected. + */ +export const DrmEntrySchema = z.union([DrmSystemSchema, z.record(z.string(), z.unknown())]); + +/** A root `drm` entry. */ +export type DrmEntry = z.infer; + +/** A protected rendition lists a `drm` entry the root `drm` section lacks. */ +export class MissingDrm extends Error { + /** The rendition listing the entry. */ + readonly rendition: string; + /** The entry ID the root lacks. */ + readonly id: string; + + constructor(rendition: string, id: string) { + super(`rendition ${rendition} references missing drm entry ${id}`); + this.name = "MissingDrm"; + this.rendition = rendition; + this.id = id; + } +} + +/** + * Whether a rendition is protected, so its samples are encrypted and only a consumer that can + * decrypt them may select it: it lists `drm` entries, or it is CMAF and its init holds an encrypted + * (`encv`/`enca`) sample entry, so a publisher that encrypts without signalling it is never read as + * clear. An init that fails to parse is not one, since no consumer reads it either way. + */ +export function isProtected(config: { drm?: string[]; container?: Container }): boolean { + if ((config.drm?.length ?? 0) > 0) return true; + if (config.container?.kind !== "cmaf") return false; + try { + const init = Uint8Array.from(atob(config.container.init), (char) => char.charCodeAt(0)); + return decodeInitSegment(init).encrypted; + } catch { + return false; + } +} diff --git a/js/hang/src/catalog/index.ts b/js/hang/src/catalog/index.ts index d58df4bcf95..ee899fcb194 100644 --- a/js/hang/src/catalog/index.ts +++ b/js/hang/src/catalog/index.ts @@ -2,8 +2,8 @@ * JSON catalog schema and types describing a broadcast's tracks: audio/video decoder configs for * WebCodecs, container format, rendition layout, the `media` section (the broadcast's `clock` and * `join` interval), - * plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, and - * broadcasts listed in `include` without opening them. + * plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, broadcasts + * listed in `include` without opening them, and the `drm` systems protecting CMAF renditions. * * @module */ @@ -26,6 +26,7 @@ export { AudioConfigSchema, AudioSchema } from "./audio"; export * from "./binary"; export * from "./clock"; export * from "./container"; +export * from "./drm"; export * from "./echo"; export * from "./format"; export * from "./hex"; diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 80f80eb11d4..fa090e963d6 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -4,6 +4,7 @@ import { Path } from "@moq/net"; import * as z from "zod/mini"; import { AudioSchema } from "./audio"; import { BinarySchema } from "./binary"; +import { DrmEntrySchema, MissingDrm } from "./drm"; import { EchoSchema } from "./echo"; import { TRACK } from "./format"; import { IncludeSchema } from "./include"; @@ -86,6 +87,10 @@ export const RootSchema = z.looseObject({ binary: section(BinarySchema, "tracks"), // A new key, so a malformed entry fails the catalog, the same as Rust. include: z.optional(renditions(IncludeSchema, "include")), + // The DRM systems protecting the CMAF renditions, keyed by entry ID; each protected rendition + // lists its entries' IDs in its own `drm`. An entry this build cannot read is kept as-is, so it + // fails only the renditions it protects, the same as Rust; one that is not an object fails. + drm: z.optional(renditions(DrmEntrySchema, "drm entry")), }); /** The root catalog object: the media sections, `media`, the data track sections, plus any app extensions. */ @@ -125,11 +130,26 @@ export class DuplicateRendition extends Error { } } -/** Refuse an update with an ID naming both a video and an audio rendition. */ +/** + * Refuse an update with an ID naming both a video and an audio rendition, or with a rendition + * listing a `drm` entry the root lacks. + * + * Throws {@link DuplicateRendition} or {@link MissingDrm}. + */ export function checkRenditions(root: Root): Root { const audio = root.audio?.renditions ?? {}; const duplicate = Object.keys(root.video?.renditions ?? {}).find((id) => Object.hasOwn(audio, id)); if (duplicate !== undefined) throw new DuplicateRendition(duplicate); + + // A protected rendition whose entry is missing would read as clear, or name no system. + const drm = root.drm ?? {}; + const sections: (Record | undefined)[] = [root.video?.renditions, audio]; + for (const section of sections) { + for (const [rendition, config] of Object.entries(section ?? {})) { + const missing = config.drm?.find((id) => !Object.hasOwn(drm, id)); + if (missing !== undefined) throw new MissingDrm(rendition, missing); + } + } return root; } diff --git a/js/hang/src/catalog/video.ts b/js/hang/src/catalog/video.ts index a04b81d3aad..5509d8b8a2b 100644 --- a/js/hang/src/catalog/video.ts +++ b/js/hang/src/catalog/video.ts @@ -135,6 +135,13 @@ export const VideoConfigSchema = z.object({ // The container format, used to decode the timestamp and more. container: ContainerSchema, + // The IDs of the root `drm` entries protecting this rendition, one per DRM system that can + // decrypt it. Absent or empty lists none, and the rendition is still protected when its CMAF init + // holds an encrypted sample entry (see `isProtected`). Common Encryption is defined for CMAF, so in practice + // it is a CMAF rendition, and `codec` names the codec its encrypted sample entry wraps. A consumer + // that can't decrypt skips it. + drm: z.optional(z.array(z.string())), + // The description is used for some codecs. // If provided, we can initialize the decoder based on the catalog alone. // Otherwise, the initialization information is (repeated) before each key-frame. diff --git a/js/hang/src/cmaf/decode.test.ts b/js/hang/src/cmaf/decode.test.ts index 0b2d55cbeff..4a34abe89c3 100644 --- a/js/hang/src/cmaf/decode.test.ts +++ b/js/hang/src/cmaf/decode.test.ts @@ -62,6 +62,7 @@ const INIT: InitSegment = { timescale: 90_000, trackId: 1, kind: "video", + encrypted: false, defaultSampleDuration: 3_000, defaultSampleSize: 1, defaultSampleFlags: 0, @@ -76,6 +77,48 @@ function fragment(trun: Uint8Array, data: number): Uint8Array { return out; } +// Renaming the sample entry stands in for a real `encv`/`enca`, which also wraps the clear fields. +function encrypt(init: Uint8Array, clear: string, encrypted: string): Uint8Array { + const out = new Uint8Array(init); + const at = Buffer.from(out).indexOf(clear, Buffer.from(out).indexOf("moov")); + if (at < 0) throw new Error(`no ${clear} sample entry`); + out.set(new TextEncoder().encode(encrypted), at); + return out; +} + +describe("CMAF encrypted sample entries", () => { + const fixtures = JSON.parse(readFileSync(new URL("./fixtures.json", import.meta.url), "utf8")); + const init = (name: string) => new Uint8Array(Buffer.from(fixtures[name], "base64")); + + test("an encv or enca entry reads as encrypted", () => { + expect(decodeInitSegment(init("videoInit")).encrypted).toBe(false); + expect(decodeInitSegment(encrypt(init("videoInit"), "avc1", "encv")).encrypted).toBe(true); + expect(decodeInitSegment(init("audioInit")).encrypted).toBe(false); + expect(decodeInitSegment(encrypt(init("audioInit"), "Opus", "enca")).encrypted).toBe(true); + }); + + test("an encrypted later track is not hidden by a clear first one", () => { + const [ftyp, moov] = split(init("videoInit")); + const [, audioMoov] = split(encrypt(init("audioInit"), "Opus", "enca")); + const audioTrak = split(audioMoov.subarray(8)).find((child) => child.subarray(4, 8).toString() === "trak"); + if (!audioTrak) throw new Error("no audio trak"); + const both = Buffer.concat([ftyp, box("moov", ...split(moov.subarray(8)), audioTrak)]); + const decoded = decodeInitSegment(both); + expect(decoded.kind).toBe("video"); + expect(decoded.encrypted).toBe(true); + }); +}); + +/** The boxes in `data`, each whole with its header. */ +function split(data: Uint8Array): Buffer[] { + const out: Buffer[] = []; + const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength); + for (let at = 0; at < buffer.byteLength; at += buffer.readUInt32BE(at)) { + out.push(buffer.subarray(at, at + buffer.readUInt32BE(at))); + } + return out; +} + describe("CMAF untrusted counts and sizes", () => { test("a zero timescale is refused at initialization", () => { const init = new Uint8Array(Buffer.from(cases[0].init, "base64")); diff --git a/js/hang/src/cmaf/decode.ts b/js/hang/src/cmaf/decode.ts index 409b0c2ccec..3d5f11327f3 100644 --- a/js/hang/src/cmaf/decode.ts +++ b/js/hang/src/cmaf/decode.ts @@ -135,6 +135,8 @@ export interface InitSegment { trackId: number; /** Whether the track carries audio or video. */ kind: "audio" | "video"; + /** Whether the sample entry is encrypted (`encv`/`enca`), so only a player that decrypts can read it. */ + encrypted: boolean; /** Default sample duration from moov/mvex/trex, used when not overridden in tfhd/trun. */ defaultSampleDuration: number; /** Default sample size from moov/mvex/trex, used when not overridden in tfhd/trun. */ @@ -163,6 +165,24 @@ export interface Sample { duration: number; } +/** + * Whether any track in the moov has an encrypted (`encv`/`enca`) sample entry, which only a player + * that decrypts can read. Every track counts, as Rust's check reads them all. + */ +function encrypted(moov: Box[]): boolean { + for (const trak of moov) { + if (trak.type !== "trak") continue; + const mdia = child(boxes(trak.payload), "mdia"); + const minf = mdia && child(boxes(mdia.payload), "minf"); + const stbl = minf && child(boxes(minf.payload), "stbl"); + const stsd = stbl && child(boxes(stbl.payload), "stsd"); + if (!stsd) continue; + if (boxes(stsd.payload.subarray(8)).some((entry) => entry.type === "encv" || entry.type === "enca")) + return true; + } + return false; +} + /** * Parse an init segment (ftyp + moov) to extract codec description and timescale. * @@ -234,6 +254,7 @@ export function decodeInitSegment(init: Uint8Array): InitSegment { timescale, trackId, kind, + encrypted: encrypted(moov), defaultSampleDuration: trex?.duration ?? 0, defaultSampleSize: trex?.size ?? 0, defaultSampleFlags: trex?.flags ?? 0, diff --git a/js/hang/src/cmaf/format.test.ts b/js/hang/src/cmaf/format.test.ts index ffbeccf15f4..6a0e794a72c 100644 --- a/js/hang/src/cmaf/format.test.ts +++ b/js/hang/src/cmaf/format.test.ts @@ -9,6 +9,7 @@ const INIT: InitSegment = { timescale: TIMESCALE, trackId: 1, kind: "video", + encrypted: false, defaultSampleDuration: 0, defaultSampleSize: 0, defaultSampleFlags: 0, diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index 30bf5525266..15d226531f4 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -19,6 +19,7 @@ const TEST_INIT: InitSegment = { timescale: TIMESCALE, trackId: 1, kind: "video", + encrypted: false, defaultSampleDuration: 0, defaultSampleSize: 0, defaultSampleFlags: 0, diff --git a/js/msf/api/index.api.md b/js/msf/api/index.api.md index 9072a2e3920..22fd207c24f 100644 --- a/js/msf/api/index.api.md +++ b/js/msf/api/index.api.md @@ -18,12 +18,30 @@ import { infer } from "zod/mini"; export type Catalog = infer; export const CatalogSchema: ZodMiniObject<{ + contentProtections: ZodMiniOptional>; + drmSystem: ZodMiniObject<{ + certURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + laURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + pssh: ZodMiniOptional>; + systemID: ZodMiniString; + }, $strip>; + refID: ZodMiniString; + scheme: ZodMiniString; + }, $strip>>>; ext: ZodMiniOptional, Record>, ZodMiniTransform, Record>>>; tracks: ZodMiniArray>; bitrate: ZodMiniOptional>; channelConfig: ZodMiniOptional>; codec: ZodMiniOptional>; + contentProtectionRefIDs: ZodMiniOptional>>; delay: ZodMiniOptional>; framerate: ZodMiniOptional>; height: ZodMiniOptional>; @@ -57,6 +75,41 @@ export const CatalogSchema: ZodMiniObject<{ }, $strip>>; }, $strip>; +export type ContentProtection = infer; + +export const ContentProtectionSchema: ZodMiniObject<{ + defaultKID: ZodMiniArray>; + drmSystem: ZodMiniObject<{ + certURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + laURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + pssh: ZodMiniOptional>; + systemID: ZodMiniString; + }, $strip>; + refID: ZodMiniString; + scheme: ZodMiniString; +}, $strip>; + +export type DrmSystem = infer; + +export const DrmSystemSchema: ZodMiniObject<{ + certURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + laURL: ZodMiniOptional>; + url: ZodMiniString; + }, $strip>>; + pssh: ZodMiniOptional>; + systemID: ZodMiniString; +}, $strip>; + export type Packaging = infer; export const PackagingSchema: ZodMiniUnion, ZodMiniString]>; +export const ProtectionUrlSchema: ZodMiniObject<{ + type: ZodMiniOptional>; + url: ZodMiniString; +}, $strip>; + export type Role = infer; export const RoleSchema: ZodMiniUnion>; channelConfig: ZodMiniOptional>; codec: ZodMiniOptional>; + contentProtectionRefIDs: ZodMiniOptional>>; delay: ZodMiniOptional>; framerate: ZodMiniOptional>; height: ZodMiniOptional>; diff --git a/js/msf/src/catalog.test.ts b/js/msf/src/catalog.test.ts index d352acda37e..3035aba5729 100644 --- a/js/msf/src/catalog.test.ts +++ b/js/msf/src/catalog.test.ts @@ -345,3 +345,38 @@ test("refuses malformed Unicode in catalogs", () => { const prefix = new TextEncoder().encode('{"version":1,"extension":"'); expect(() => decode(new Uint8Array([...prefix, 0xff, 0x22, 0x7d]))).toThrow(); }); + +// Mirrors moq-msf: CMSF content protection round-trips, and a dangling refID is refused. +test("content protection round-trips and a dangling refID is refused", () => { + const contentProtections = [ + { + refID: "1", + defaultKID: ["a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"], + scheme: "cbcs", + drmSystem: { + systemID: "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + laURL: { url: "https://license.example.com/", type: "EME-1.0" }, + pssh: "AAAA", + }, + }, + ]; + const track = { name: "video", packaging: "cmaf", isLive: true, role: "video", codec: "avc1.64001f" }; + const catalog = decode( + encodeJson({ + version: "draft-01", + contentProtections, + tracks: [{ ...track, contentProtectionRefIDs: ["1"] }], + }), + ); + expect(catalog.contentProtections).toEqual(contentProtections); + expect(catalog.tracks[0].contentProtectionRefIDs).toEqual(["1"]); + expect(catalog.ext).toBeUndefined(); + expect(decode(encode(catalog))).toEqual(catalog); + + const dangling = encodeJson({ version: "draft-01", tracks: [{ ...track, contentProtectionRefIDs: ["2"] }] }); + expect(() => decode(dangling)).toThrow("missing content protection"); + // Encoding refuses it too, so a publisher fails before its subscribers do. + expect(() => + encode({ tracks: [{ ...track, contentProtectionRefIDs: ["2"] }] } as Parameters[0]), + ).toThrow("missing content protection"); +}); diff --git a/js/msf/src/catalog.ts b/js/msf/src/catalog.ts index dc79ac70bc3..5de4678e944 100644 --- a/js/msf/src/catalog.ts +++ b/js/msf/src/catalog.ts @@ -48,6 +48,8 @@ const trackShape = { altGroup: z.optional(z.number()), maxGrpSapStartingType: z.optional(z.number()), maxObjSapStartingType: z.optional(z.number()), + /** The `refID`s of the root `contentProtections` entries protecting this track (CMSF 4.1.2). */ + contentProtectionRefIDs: z.optional(z.array(z.string())), // Non-standard: maximum delay (ms) between consecutive frames on this track. // The player's buffer must be at least this large to avoid underruns. @@ -60,6 +62,40 @@ const trackShape = { delay: z.optional(z.number().check(z.nonnegative())), }; +/** A service URL in a {@link DrmSystem}, with an optional protocol or MIME type. */ +export const ProtectionUrlSchema = z.object({ + url: z.string(), + type: z.optional(z.string()), +}); + +/** + * A DRM system description (CMSF 4.1.1.4). draft-ietf-moq-cmsf-01 names no member for its + * authorization URL or robustness, so neither is carried. + */ +export const DrmSystemSchema = z.object({ + systemID: z.string(), + laURL: z.optional(ProtectionUrlSchema), + certURL: z.optional(ProtectionUrlSchema), + /** A base64 `pssh` box with the system's initialization data. */ + pssh: z.optional(z.string()), +}); + +/** A DRM system description within a {@link ContentProtection}. */ +export type DrmSystem = z.infer; + +/** One DRM system configuration protecting tracks of the broadcast (CMSF 4.1.1). */ +export const ContentProtectionSchema = z.object({ + refID: z.string(), + /** The default key IDs (`default_KID`) as UUID strings. */ + defaultKID: z.array(z.string()), + /** The Common Encryption scheme, such as `cenc` or `cbcs`. */ + scheme: z.string(), + drmSystem: DrmSystemSchema, +}); + +/** One DRM system configuration protecting tracks of the broadcast. */ +export type ContentProtection = z.infer; + /** Zod schema describing a single track entry in an MSF catalog. */ export const TrackSchema = z.object(trackShape); @@ -69,6 +105,8 @@ export type Track = z.infer; /** Zod schema for the top-level MSF catalog: a version-agnostic snapshot of tracks. */ export const CatalogSchema = z.object({ tracks: z.array(TrackSchema), + /** The DRM systems protecting the tracks, which reference them by `refID` (CMSF 4.1.1). */ + contentProtections: z.optional(z.array(ContentProtectionSchema)), // The application extension: root members beyond the ones MSF defines, kept // verbatim. An extension adds a section here, e.g. the `mpegts` section of // draft-lcurley-moq-mpegts. Mirrors `Catalog::ext` in `moq-msf`, which is typed; @@ -97,7 +135,7 @@ export const CatalogSchema = z.object({ export type Catalog = z.infer; /** Root member names MSF itself defines, which an extension section must not reuse. */ -const RESERVED_ROOT = ["version", "generatedAt", "isComplete", "tracks", "initDataList"]; +const RESERVED_ROOT = ["version", "generatedAt", "isComplete", "tracks", "initDataList", "contentProtections"]; /** The newest MSF draft version string this package emits on the wire. */ export const VERSION = "draft-01"; @@ -124,12 +162,31 @@ const WireCatalogSchema = z.object({ version: z.union([z.literal(1), z.string()]), tracks: z.optional(z.array(WireTrackSchema)), initDataList: z.optional(z.array(InitDataSchema)), + contentProtections: z.optional(z.array(ContentProtectionSchema)), }); +/** + * Refuse a track whose protection names no root entry: it would claim encryption the catalog + * cannot describe, so it is refused like a missing initRef. + */ +function checkProtections( + tracks: { name: string; contentProtectionRefIDs?: string[] }[], + protections: { refID: string }[] | undefined, +): void { + const refIDs = new Set((protections ?? []).map((cp) => cp.refID)); + for (const track of tracks) { + const missing = track.contentProtectionRefIDs?.find((id) => !refIDs.has(id)); + if (missing !== undefined) { + throw new Error(`MSF track "${track.name}" references missing content protection "${missing}"`); + } + } +} + /** Serialize a catalog to its JSON wire representation (draft-01). */ export function encode(catalog: Catalog): Uint8Array { // Refuse what `decode` would reject, so a publisher fails here instead of its subscribers. CatalogSchema.parse(catalog); + checkProtections(catalog.tracks, catalog.contentProtections); // Hoist inline init payloads into a shared, deduplicated initDataList and // reference each from its track via initRef (the draft-01 wire shape). @@ -155,6 +212,7 @@ export function encode(catalog: Catalog): Uint8Array { // the member from the encoded catalog. const wire: Record = Object.assign(Object.create(null), { version: VERSION, tracks }); if (initDataList.length > 0) wire.initDataList = initDataList; + if (catalog.contentProtections?.length) wire.contentProtections = catalog.contentProtections; // Extension members are written flat, so one named after a field MSF defines would // emit a duplicate key and lose one of the two on re-parse. Refuse instead. The Rust @@ -191,6 +249,8 @@ export function decode(raw: Uint8Array): Catalog { byId.set(entry.id, entry); } + checkProtections(wire.tracks ?? [], wire.contentProtections); + const tracks = (wire.tracks ?? []).map(({ initRef, ...track }) => { track.isLive ??= false; @@ -216,7 +276,10 @@ export function decode(raw: Uint8Array): Catalog { return track; }); - return Object.keys(ext).length > 0 ? { tracks, ext } : { tracks }; + const catalog: Catalog = { tracks }; + if (wire.contentProtections?.length) catalog.contentProtections = wire.contentProtections; + if (Object.keys(ext).length > 0) catalog.ext = ext; + return catalog; } /** Read and decode the next catalog frame from a track, or undefined if the track ended. */ diff --git a/js/watch/src/audio/config.ts b/js/watch/src/audio/config.ts index 4452effc5a4..51d2c186a7d 100644 --- a/js/watch/src/audio/config.ts +++ b/js/watch/src/audio/config.ts @@ -13,7 +13,7 @@ const MP3_MPEG1_MIN_SAMPLE_RATE = 32000; /** The catalog fields that determine the demuxer and WebCodecs decoder instance. */ export type DecoderConfig = Pick< Catalog.AudioConfig, - "codec" | "container" | "description" | "sampleRate" | "numberOfChannels" | "warmup" + "codec" | "container" | "description" | "sampleRate" | "numberOfChannels" | "warmup" | "drm" >; /** The routing and decoder state whose changes require a replacement subscription. */ @@ -33,6 +33,7 @@ export function decoderConfig(config: Catalog.AudioConfig): DecoderConfig { sampleRate: config.sampleRate, numberOfChannels: config.numberOfChannels, warmup: config.warmup, + drm: config.drm, }; } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 748ca269d7c..ec03b43c664 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -1044,6 +1044,12 @@ async function supported(config: Catalog.AudioConfig): Promise { return false; } + // WebCodecs cannot decrypt, so an encrypted rendition is unplayable here. + if (Catalog.isProtected(config)) { + console.warn(`audio: ignoring protected rendition ${config.codec}: playback cannot decrypt it`); + return false; + } + // Opus only runs at its native rates, so a catalog advertising anything else is wrong and Safari // refuses to decode it. Warn rather than reject: Chrome and Firefox ignore the configured rate and // play these streams fine, so rejecting would silence them for a publisher they handle today. @@ -1051,24 +1057,25 @@ async function supported(config: Catalog.AudioConfig): Promise { console.warn(`audio: opus advertised at ${config.sampleRate}Hz, which some browsers cannot decode`); } + let init: { description?: Uint8Array } | undefined; + if (config.container.kind === "cmaf") { + try { + const Cmaf = await import("@moq/hang/cmaf"); + init = Cmaf.decodeInitSegment(base64ToBytes(config.container.init)); + } catch (err) { + // A malformed init segment means we can't extract the codec + // description, so we can't probe support reliably. Reject the + // track rather than letting isConfigSupported pass on a + // description-less config and then having decode() fail later. + console.warn(`audio: malformed CMAF init segment for codec ${config.codec}`, err); + return false; + } + } + // Opus in CMAF uses raw packets; dOps is not a valid OGG Identification Header. let description: Uint8Array | undefined; if (config.codec !== "opus") { - if (config.description) { - description = Util.Hex.toBytes(config.description); - } else if (config.container.kind === "cmaf") { - try { - const Cmaf = await import("@moq/hang/cmaf"); - description = Cmaf.decodeInitSegment(base64ToBytes(config.container.init)).description; - } catch (err) { - // A malformed init segment means we can't extract the codec - // description, so we can't probe support reliably. Reject the - // track rather than letting isConfigSupported pass on a - // description-less config and then having decode() fail later. - console.warn(`audio: malformed CMAF init segment for codec ${config.codec}`, err); - return false; - } - } + description = config.description ? Util.Hex.toBytes(config.description) : init?.description; } // Install the WebCodecs polyfill before probing, since playback would decode through it where // AudioDecoder is missing (Node, Bun, older browsers). Loads nothing where WebCodecs audio is native. diff --git a/js/watch/src/msf.test.ts b/js/watch/src/msf.test.ts index 97c797be4c5..dc3ea261947 100644 --- a/js/watch/src/msf.test.ts +++ b/js/watch/src/msf.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import * as Catalog from "@moq/hang/catalog"; import { u53 } from "@moq/hang/catalog"; import * as Msf from "@moq/msf"; import { Path } from "@moq/net"; @@ -325,3 +326,63 @@ test("a later MSF track with a name replaces the earlier one, whatever its role" "vp09.00.10.08", ); }); + +// A known hang `drm` entry, or a failed test. +function known(entry: Catalog.DrmEntry | undefined): Catalog.DrmSystem { + return Catalog.DrmSystemSchema.parse(entry); +} + +// A protected MSF track lands as a hang rendition listing its `drm` entries, so `` +// knows it cannot play it. Mirrors moq-mux: each refID is an entry ID, any UUID form MSF uses is +// read as lowercase hyphenated, and an entry the hang catalog cannot read, such as one naming two +// default keys or a malformed system, is kept as-is so the video it protects stays protected. +test("maps CMSF content protection onto hang drm entries", () => { + const catalog: Msf.Catalog = { + contentProtections: [ + { + refID: "ck", + defaultKID: ["A1B2C3D4E5F60718293A4B5C6D7E8F90"], + scheme: "cens", + drmSystem: { systemID: "{1077EFEC-C0B2-4D02-ACE3-3C1E52E2FB4B}", laURL: { url: "https://l.example/" } }, + }, + { + refID: "two", + defaultKID: ["01234567-89ab-cdef-0123-456789abcdef", "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"], + scheme: "cbcs", + drmSystem: { systemID: "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed" }, + }, + { + refID: "bad", + defaultKID: ["01234567-89ab-cdef-0123-456789abcdef"], + scheme: "cbcs", + drmSystem: { systemID: "widevine" }, + }, + ], + tracks: [ + { + name: "video", + packaging: "loc", + role: "video", + codec: "vp8", + contentProtectionRefIDs: ["ck", "two", "bad"], + }, + { name: "audio", packaging: "loc", role: "audio", codec: "opus" }, + { name: "words", packaging: "loc", role: "caption", codec: "vtt" }, + { name: "sealed", packaging: "loc", role: "caption", codec: "vtt", contentProtectionRefIDs: ["ck"] }, + ], + }; + const root = Catalog.checkRenditions(toHang(catalog)); + // A hang text rendition has no `drm`, so a protected one is left out rather than read as clear. + expect(Object.keys(root.text?.renditions ?? {})).toEqual(["words"]); + expect(Object.keys(root.drm ?? {}).sort()).toEqual(["bad", "ck", "two"]); + const ck = known(root.drm?.ck); + expect(ck.system).toBe(Catalog.DRM_SYSTEM.clearkey); + expect(ck.kid).toBe("a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"); + expect(ck.scheme).toBe("cens"); + expect(ck.license?.url).toBe("https://l.example/"); + expect(Catalog.DrmSystemSchema.safeParse(root.drm?.two).success).toBe(false); + expect(Catalog.DrmSystemSchema.safeParse(root.drm?.bad).success).toBe(false); + expect(root.video?.renditions.video?.drm).toEqual(["ck", "two", "bad"]); + expect(Catalog.isProtected(root.video?.renditions.video ?? { drm: [] })).toBe(true); + expect(root.audio?.renditions.audio?.drm).toBeUndefined(); +}); diff --git a/js/watch/src/msf.ts b/js/watch/src/msf.ts index d87c0611099..7b98d4fe9c9 100644 --- a/js/watch/src/msf.ts +++ b/js/watch/src/msf.ts @@ -1,5 +1,5 @@ import type * as Catalog from "@moq/hang/catalog"; -import { u53 } from "@moq/hang/catalog"; +import { DrmSystemSchema, u53 } from "@moq/hang/catalog"; import * as Util from "@moq/hang/util"; import type * as Msf from "@moq/msf"; import { Path } from "@moq/net"; @@ -120,8 +120,74 @@ function namesCatalog(namespace: Path.Valid, base: Path.Valid): boolean { return endsWith(a, b) || endsWith(b, a); } +const HYPHENATED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; +const SIMPLE = /^[0-9a-f]{32}$/i; + +/** + * A UUID in lowercase hyphenated form, from any form moq-mux's `uuid` parse accepts: simple, + * hyphenated, braced, or URN. `undefined` for anything else. + */ +function normalizeUuid(text: string): string | undefined { + let hyphenated: string; + if (text.length === 32) { + if (!SIMPLE.test(text)) return undefined; + const at = [0, 8, 12, 16, 20, 32]; + hyphenated = at + .slice(1) + .map((end, i) => text.slice(at[i], end)) + .join("-"); + } else if (text.length === 36) { + hyphenated = text; + } else if (text.length === 38 && text.startsWith("{") && text.endsWith("}")) { + hyphenated = text.slice(1, -1); + } else if (text.length === 45 && text.slice(0, 9).toLowerCase() === "urn:uuid:") { + hyphenated = text.slice(9); + } else { + return undefined; + } + return HYPHENATED.test(hyphenated) ? hyphenated.toLowerCase() : undefined; +} + +/** + * The hang `drm` entry one MSF content protection describes, or `undefined` when the hang catalog + * cannot read it. + * + * Mirrors moq-mux: a hang entry names one key, so an entry naming several default keys is not read. + */ +function toEntry(cp: Msf.ContentProtection): Catalog.DrmSystem | undefined { + if (cp.defaultKID.length !== 1) return undefined; + const system = normalizeUuid(cp.drmSystem.systemID); + const kid = normalizeUuid(cp.defaultKID[0]); + if (system === undefined || kid === undefined) return undefined; + // The scheme, the servers' URLs, and the pssh are checked the way the hang catalog reads them. + const entry = DrmSystemSchema.safeParse({ + system, + scheme: cp.scheme, + kid, + pssh: cp.drmSystem.pssh, + license: cp.drmSystem.laURL, + certificate: cp.drmSystem.certURL, + }); + return entry.success ? entry.data : undefined; +} + +/** + * The hang `drm` entries an MSF catalog's `contentProtections` describe, keyed by `refID`. + * + * An entry the hang catalog cannot read is kept as-is, so the tracks it protects stay protected. + */ +function toDrm(msf: Msf.Catalog): Record { + const drm: Record = Object.create(null); + for (const cp of msf.contentProtections ?? []) drm[cp.refID] = toEntry(cp) ?? { ...cp }; + return drm; +} + /** Convert an MSF catalog to a hang catalog Root. */ export function toHang(msf: Msf.Catalog, base?: Path.Valid): Catalog.Root { + const drm = toDrm(msf); + // A track's refIDs are its entries' IDs; @moq/msf refuses a refID the root lacks. + const protection = (track: Msf.Track): { drm?: string[] } => + track.contentProtectionRefIDs?.length ? { drm: track.contentProtectionRefIDs } : {}; // Track names are untrusted keys; a null prototype keeps `__proto__` an ordinary rendition. const videoRenditions: Record = Object.create(null); const audioRenditions: Record = Object.create(null); @@ -152,10 +218,10 @@ export function toHang(msf: Msf.Catalog, base?: Path.Valid): Catalog.Root { } if (track.role === "video") { const config = toVideoConfig(track); - if (config) videoRenditions[track.name] = { ...config, broadcast }; + if (config) videoRenditions[track.name] = { ...config, broadcast, ...protection(track) }; } else if (track.role === "audio") { const config = toAudioConfig(track); - if (config) audioRenditions[track.name] = { ...config, broadcast }; + if (config) audioRenditions[track.name] = { ...config, broadcast, ...protection(track) }; } else if ( track.role === "caption" || track.role === "subtitle" || @@ -164,6 +230,8 @@ export function toHang(msf: Msf.Catalog, base?: Path.Valid): Catalog.Root { track.role !== "signlanguage" && ["vtt", "ttml", "utf8"].includes(track.codec ?? "")) ) { + // A hang text rendition has no `drm` to say it is protected, so it would read as clear. + if (track.contentProtectionRefIDs?.length) continue; const info = toContainer(track); // A player selects usable renditions; an optional unsupported track cannot invalidate A/V. if (!info) continue; @@ -193,5 +261,7 @@ export function toHang(msf: Msf.Catalog, base?: Path.Valid): Catalog.Root { if (Object.keys(textRenditions).length > 0) root.text = { renditions: textRenditions }; + if (Object.keys(drm).length > 0) root.drm = drm; + return root; } diff --git a/js/watch/src/protected.test.ts b/js/watch/src/protected.test.ts new file mode 100644 index 00000000000..e269ff6db90 --- /dev/null +++ b/js/watch/src/protected.test.ts @@ -0,0 +1,49 @@ +import { expect, mock, test } from "bun:test"; +import * as Catalog from "@moq/hang/catalog"; + +// Bun cannot load the blob-URL worklet import, so mock it before the decoder imports it. +mock.module("./audio/render-worklet.ts?worklet", () => ({ default: async () => "blob:fake-render" })); +const Audio = await import("./audio/decoder"); +const Video = await import("./video/decoder"); + +// WebCodecs cannot decrypt, so `` treats a protected rendition as unplayable before it +// asks the decoder, whatever the codec. +test("protected renditions are unplayable", async () => { + const cmaf = { kind: "cmaf", init: "AAAA" }; + const video = Catalog.VideoConfigSchema.parse({ codec: "avc1.64001f", container: cmaf, drm: ["1"] }); + const audio = Catalog.AudioConfigSchema.parse({ + codec: "mp4a.40.2", + container: cmaf, + sampleRate: 48000, + numberOfChannels: 2, + drm: ["1"], + }); + expect(await Video.Decoder.supported(video)).toBe(false); + expect(await Audio.Decoder.supported(audio)).toBe(false); +}); + +// An encrypted sample entry marks a CMAF rendition protected even when its catalog lists no `drm` +// entry, so a publisher that encrypts without signalling it is never decoded as clear. +test("an encrypted CMAF init is unplayable without drm entries", async () => { + const fixtures = JSON.parse(await Bun.file(new URL("../../hang/src/cmaf/fixtures.json", import.meta.url)).text()); + const encrypt = (name: string, clear: string, encrypted: string) => { + const init = Buffer.from(fixtures[name], "base64"); + init.write(encrypted, init.indexOf(clear, init.indexOf("moov")), "latin1"); + return init.toString("base64"); + }; + const video = Catalog.VideoConfigSchema.parse({ + codec: "avc1.64001f", + container: { kind: "cmaf", init: encrypt("videoInit", "avc1", "encv") }, + }); + const audio = Catalog.AudioConfigSchema.parse({ + codec: "opus", + container: { kind: "cmaf", init: encrypt("audioInit", "Opus", "enca") }, + sampleRate: 48000, + numberOfChannels: 2, + }); + expect(await Video.Decoder.supported(video)).toBe(false); + expect(await Audio.Decoder.supported(audio)).toBe(false); + expect(Catalog.isProtected(video)).toBe(true); + expect(Catalog.isProtected(audio)).toBe(true); + expect(Catalog.isProtected({ container: { kind: "cmaf", init: fixtures.videoInit } })).toBe(false); +}); diff --git a/js/watch/src/video/config.ts b/js/watch/src/video/config.ts index fd5cd257781..0faade426c7 100644 --- a/js/watch/src/video/config.ts +++ b/js/watch/src/video/config.ts @@ -3,7 +3,7 @@ import type * as Catalog from "@moq/hang/catalog"; /** The catalog fields that determine the demuxer and WebCodecs decoder instance. */ export type DecoderConfig = Pick< Catalog.VideoConfig, - "codec" | "container" | "description" | "displayAspectWidth" | "displayAspectHeight" + "codec" | "container" | "description" | "displayAspectWidth" | "displayAspectHeight" | "drm" > & { optimizeForLatency: boolean; interlaced: boolean; @@ -29,6 +29,7 @@ export function playbackIdentity(config: Catalog.VideoConfig): PlaybackIdentity description: config.description, displayAspectWidth: config.displayAspectWidth, displayAspectHeight: config.displayAspectHeight, + drm: config.drm, optimizeForLatency: config.optimizeForLatency ?? true, interlaced: config.interlaced ?? false, }, diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 8042e3b3829..1b804dfd05a 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -1335,13 +1335,17 @@ async function supported(config: Catalog.VideoConfig): Promise { return false; } - let description: Uint8Array | undefined; - if (config.description) { - description = Util.Hex.toBytes(config.description); - } else if (config.container.kind === "cmaf") { + // WebCodecs cannot decrypt, so an encrypted rendition is unplayable here. + if (Catalog.isProtected(config)) { + console.warn(`video: ignoring protected rendition ${config.codec}: playback cannot decrypt it`); + return false; + } + + let init: { description?: Uint8Array } | undefined; + if (config.container.kind === "cmaf") { try { const Cmaf = await import("@moq/hang/cmaf"); - description = Cmaf.decodeInitSegment(base64ToBytes(config.container.init)).description; + init = Cmaf.decodeInitSegment(base64ToBytes(config.container.init)); } catch (err) { // A malformed init segment means we can't extract the codec // description, so we can't probe support reliably. Reject the @@ -1351,6 +1355,7 @@ async function supported(config: Catalog.VideoConfig): Promise { return false; } } + const description = config.description ? Util.Hex.toBytes(config.description) : init?.description; const { supported } = await VideoDecoder.isConfigSupported({ codec: config.codec, description, diff --git a/rs/hang/Cargo.toml b/rs/hang/Cargo.toml index 219b305193e..90cc09a4200 100644 --- a/rs/hang/Cargo.toml +++ b/rs/hang/Cargo.toml @@ -21,6 +21,7 @@ default = [] async = ["kio/async"] [dependencies] +base64 = { workspace = true } bytes = { workspace = true } hex = { workspace = true } kio = { workspace = true, features = ["runtime"] } @@ -31,6 +32,7 @@ serde_json = { workspace = true } serde_with = { workspace = true, features = ["base64"] } thiserror = { workspace = true } url = { workspace = true, features = ["serde"] } +uuid = { workspace = true, features = ["serde"] } [dependencies.derive_more] version = "2" diff --git a/rs/hang/fixtures/catalog-parity.json b/rs/hang/fixtures/catalog-parity.json index c64baa31b66..d5c24ad4347 100644 --- a/rs/hang/fixtures/catalog-parity.json +++ b/rs/hang/fixtures/catalog-parity.json @@ -3759,5 +3759,389 @@ } }, "refused": true + }, + { + "name": "drm entries protect video and audio", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "pssh": "AAAA", + "license": { + "url": "https://license.example.com/", + "type": "EME-1.0" + } + }, + "2": { + "system": "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "certificate": { + "url": "https://cert.example.com/" + } + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1", "2"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "video": ["v"], + "audio": ["a"] + }, + { + "name": "drm unknown entry members are ignored", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "future": true + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "video": ["v"], + "audio": ["a"] + }, + { + "name": "drm unreferenced entry is accepted", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" + } + } + } + }, + { + "name": "drm dangling video reference refuses the catalog", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["2"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "refused": true + }, + { + "name": "drm dangling audio reference refuses the catalog", + "catalog": { + "drm": {}, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": [] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "refused": true + }, + { + "name": "drm scheme cens keeps the catalog", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cens", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "video": ["v"], + "audio": ["a"] + }, + { + "name": "drm malformed system keeps the catalog", + "catalog": { + "drm": { + "1": { + "system": "widevine", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "video": ["v"], + "audio": ["a"] + }, + { + "name": "drm entry without kid keeps the catalog", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cenc" + } + } + } + }, + { + "name": "drm license without url keeps the catalog", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "license": { + "type": "EME-1.0" + } + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "video": ["v"], + "audio": ["a"] + }, + { + "name": "drm references must be a list", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" + } + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": "1" + } + } + }, + "audio": { + "renditions": { + "a": { + "codec": "mp4a.40.2", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "refused": true + }, + { + "name": "drm unhyphenated kid keeps the catalog", + "catalog": { + "drm": { + "1": { + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cenc", + "kid": "a1b2c3d4e5f60718293a4b5c6d7e8f90" + } + } + } + }, + { + "name": "drm entry that is not an object refuses the catalog", + "catalog": { + "drm": { + "1": "cbcs" + }, + "video": { + "renditions": { + "v": { + "codec": "avc1.64001f", + "container": { + "kind": "cmaf", + "init": "AAAA" + }, + "drm": ["1"] + } + } + } + }, + "refused": true } ] diff --git a/rs/hang/src/catalog/audio/mod.rs b/rs/hang/src/catalog/audio/mod.rs index 0df4866edfd..9dd365edc29 100644 --- a/rs/hang/src/catalog/audio/mod.rs +++ b/rs/hang/src/catalog/audio/mod.rs @@ -174,6 +174,17 @@ pub struct AudioConfig { #[serde(default)] pub container: Container, + /// The IDs of the root `drm` entries protecting this rendition, one per DRM system that can + /// decrypt it. Empty lists none and is left off the wire; the rendition is still protected + /// when its CMAF init holds an encrypted sample entry. + /// + /// Common Encryption is defined for CMAF, so a protected rendition is a [`Cmaf`](Container::Cmaf) + /// one in practice: its init segment carries the encrypted sample entry (`encv`/`enca`), while + /// `codec` names the codec it wraps. A consumer that cannot decrypt treats a protected + /// rendition as undecodable. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub drm: Vec, + /// The maximum delay between a frame being ready and the publisher flushing it. /// The player's jitter buffer should be larger than this value. /// If not provided, the player should assume each frame is flushed immediately. @@ -239,6 +250,7 @@ impl AudioConfig { enabled: true, description: None, container: Container::default(), + drm: Vec::new(), jitter: None, warmup: None, delay: None, diff --git a/rs/hang/src/catalog/drm.rs b/rs/hang/src/catalog/drm.rs new file mode 100644 index 00000000000..c23537488a7 --- /dev/null +++ b/rs/hang/src/catalog/drm.rs @@ -0,0 +1,346 @@ +//! Content protection: the DRM systems that encrypt a broadcast's CMAF renditions. +//! +//! The catalog's root `drm` section maps an entry ID to an [`Entry`], and each protected video or +//! audio rendition lists the IDs of the entries that protect it in its `drm` field. A rendition +//! that lists none is clear. Every entry names one DRM system, one Common Encryption +//! [`Scheme`], and one default key, so each maps onto one of draft-ietf-moq-cmsf's +//! `contentProtections` and a rendition's IDs onto its `contentProtectionRefIDs`. A CMSF entry +//! naming several default keys has no hang form, so it reads as [`Entry::Unknown`]. +//! +//! An entry this build cannot read decodes to [`Entry::Unknown`] instead of failing the catalog, +//! and a rendition listing any entry is protected whether or not its entries are readable. +//! +//! ```json +//! { +//! "drm": { +//! "1": { +//! "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", +//! "scheme": "cbcs", +//! "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", +//! "pssh": "AAAANHBzc2gB...", +//! "license": { "url": "https://license.example.com/clearkey" } +//! } +//! }, +//! "video": { "renditions": { "hd": { "codec": "avc1.64001f", "drm": ["1"], "...": "..." } } } +//! } +//! ``` + +use bytes::Bytes; +use serde::{Deserialize, Deserializer, Serialize, Serializer}; +use serde_with::serde_as; + +/// Re-export of the [`uuid`] crate's UUID, which system and key IDs are. +pub use uuid::Uuid; + +/// Well-known DRM system IDs, as draft-ietf-moq-cmsf lists them. +pub mod system { + /// Google Widevine. + pub const WIDEVINE: uuid::Uuid = uuid::uuid!("edef8ba9-79d6-4ace-a3c8-27dcd51d21ed"); + /// Microsoft PlayReady. + pub const PLAYREADY: uuid::Uuid = uuid::uuid!("9a04f079-9840-4286-ab92-e65be0885f95"); + /// Apple FairPlay Streaming. + pub const FAIRPLAY: uuid::Uuid = uuid::uuid!("94ce86fb-07ff-4f43-adb8-93d2fa968ca2"); + /// W3C ClearKey, the Common System ID: for testing, since the key travels in the clear. + pub const CLEARKEY: uuid::Uuid = uuid::uuid!("1077efec-c0b2-4d02-ace3-3c1e52e2fb4b"); +} + +/// One root `drm` entry: a DRM system this build reads, or one it does not. +#[expect( + clippy::large_enum_variant, + reason = "a catalog holds a few entries, nearly all known, so boxing would only add an allocation and a deref to the common case" +)] +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Entry { + /// An entry this build reads. + Known(System), + + /// An entry this build cannot read, such as one with a malformed UUID or URL, preserved + /// verbatim. The renditions listing it are still protected. + Unknown(UnknownEntry), +} + +impl From for Entry { + fn from(system: System) -> Self { + Self::Known(system) + } +} + +impl Serialize for Entry { + fn serialize(&self, serializer: S) -> Result { + match self { + Self::Known(system) => system.serialize(serializer), + Self::Unknown(unknown) => unknown.0.serialize(serializer), + } + } +} + +impl<'de> Deserialize<'de> for Entry { + fn deserialize>(deserializer: D) -> Result { + let object = serde_json::Map::deserialize(deserializer)?; + let value = serde_json::Value::Object(object); + match System::deserialize(&value) { + Ok(system) => Ok(Self::Known(system)), + Err(_) => match value { + serde_json::Value::Object(object) => Ok(Self::Unknown(UnknownEntry(object))), + _ => unreachable!("built from an object"), + }, + } + } +} + +/// The raw JSON of a `drm` entry this build cannot read. +/// +/// Kept intact so a relay or transcoder that reparses and republishes a catalog round-trips the +/// entry rather than dropping it and leaving its renditions' IDs dangling. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct UnknownEntry(serde_json::Map); + +impl UnknownEntry { + /// An entry holding `fields` verbatim. + pub fn new(fields: serde_json::Map) -> Self { + Self(fields) + } + + /// The full JSON object. + pub fn fields(&self) -> &serde_json::Map { + &self.0 + } +} + +/// One DRM system protecting renditions under one scheme and one default key. +/// +/// The scheme, key, system, and `pssh` are the media's own (the init segment's `schm`, `tenc`, +/// and `pssh` boxes); the license and certificate servers are the publisher's, which the media +/// does not carry. +/// +/// Marked `#[non_exhaustive]` so optional fields can be added later. External callers build one +/// with [`System::new`]. +#[serde_as] +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct System { + /// The DRM system ID, as a UUID string (see [`system`]). + #[serde_as(as = "Hyphenated")] + pub system: uuid::Uuid, + + /// How the samples are encrypted. + pub scheme: Scheme, + + /// The default key ID (`tenc`'s `default_KID`), as a UUID string. + #[serde_as(as = "Hyphenated")] + pub kid: uuid::Uuid, + + /// The system's whole `pssh` box from the init segment, base64: what the player hands its + /// DRM system to request a license. + #[serde(default)] + #[serde_as(as = "Option")] + pub pssh: Option, + + /// Where to request a license. + #[serde(default)] + pub license: Option, + + /// Where to fetch the server certificate, which systems such as FairPlay need first. + #[serde(default)] + pub certificate: Option, +} + +impl System { + /// An entry with no `pssh` and no servers. + pub fn new(system: uuid::Uuid, scheme: Scheme, kid: uuid::Uuid) -> Self { + Self { + system, + scheme, + kid, + pssh: None, + license: None, + certificate: None, + } + } +} + +/// A UUID in its hyphenated form only, as draft-ietf-moq-cmsf writes one, refusing the simple, +/// braced, and URN forms [`uuid::Uuid`]'s own decoder also takes. +struct Hyphenated; + +impl serde_with::SerializeAs for Hyphenated { + fn serialize_as(source: &uuid::Uuid, serializer: S) -> Result { + source.hyphenated().serialize(serializer) + } +} + +impl<'de> serde_with::DeserializeAs<'de, uuid::Uuid> for Hyphenated { + fn deserialize_as>(deserializer: D) -> Result { + let text = String::deserialize(deserializer)?; + match text.len() { + 36 => uuid::Uuid::try_parse(&text).map_err(serde::de::Error::custom), + _ => Err(serde::de::Error::custom(format_args!( + "expected a hyphenated UUID: {text:?}" + ))), + } + } +} + +/// Standard base64 with its padding, refusing the unpadded form serde_with's own decoder also +/// takes, as JS `z.base64()` and CMSF do. +struct Padded; + +impl serde_with::SerializeAs for Padded { + fn serialize_as(source: &Bytes, serializer: S) -> Result { + use base64::Engine; + serializer.serialize_str(&base64::engine::general_purpose::STANDARD.encode(source)) + } +} + +impl<'de> serde_with::DeserializeAs<'de, Bytes> for Padded { + fn deserialize_as>(deserializer: D) -> Result { + use base64::Engine; + let text = String::deserialize(deserializer)?; + let bytes = base64::engine::general_purpose::STANDARD.decode(text); + bytes.map(Bytes::from).map_err(serde::de::Error::custom) + } +} + +/// The Common Encryption scheme (ISO/IEC 23001-7) of a protected rendition. +/// +/// draft-ietf-moq-cmsf allows `cenc` and `cbcs`; any other is kept as [`Other`](Self::Other), so +/// a scheme a later draft adds leaves the rest of the catalog readable. +#[derive(Debug, Clone, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub enum Scheme { + /// AES-CTR, full sample or subsample. + Cenc, + /// AES-CBC pattern encryption with a constant IV, which FairPlay and most hardware decode. + Cbcs, + /// A scheme this build does not know, such as `cens` or `cbc1`. + Other(String), +} + +impl Scheme { + /// The scheme's four-character code, as `schm` carries it. + pub fn as_str(&self) -> &str { + match self { + Self::Cenc => "cenc", + Self::Cbcs => "cbcs", + Self::Other(other) => other, + } + } +} + +impl From<&str> for Scheme { + fn from(s: &str) -> Self { + match s { + "cenc" => Self::Cenc, + "cbcs" => Self::Cbcs, + other => Self::Other(other.to_string()), + } + } +} + +impl std::fmt::Display for Scheme { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.as_str()) + } +} + +impl Serialize for Scheme { + fn serialize(&self, serializer: S) -> Result { + serializer.serialize_str(self.as_str()) + } +} + +impl<'de> Deserialize<'de> for Scheme { + fn deserialize>(deserializer: D) -> Result { + Ok(Self::from(String::deserialize(deserializer)?.as_str())) + } +} + +/// A license or certificate server. +/// +/// Marked `#[non_exhaustive]` so optional fields can be added later. External callers build one +/// with [`Server::new`]. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub struct Server { + /// The server's URL. + pub url: url::Url, + + /// The protocol a license server speaks (e.g. `EME-1.0`), or the MIME type of a certificate + /// (e.g. `application/pkcs7-mime`). + #[serde(default, rename = "type")] + pub kind: Option, +} + +impl Server { + /// A server at `url`, of no declared type. + pub fn new(url: url::Url) -> Self { + Self { url, kind: None } + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn an_entry_round_trips_with_hang_member_names() { + let json = serde_json::json!({ + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cbcs", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + "pssh": "AAAA", + "license": { "url": "https://license.example.com/", "type": "EME-1.0" }, + }); + let Entry::Known(system) = serde_json::from_value(json.clone()).unwrap() else { + panic!("expected a known entry"); + }; + assert_eq!(system.system, system::CLEARKEY); + assert_eq!(system.scheme, Scheme::Cbcs); + assert_eq!(system.pssh.as_deref(), Some(&[0u8, 0, 0][..])); + assert_eq!(system.license.as_ref().unwrap().kind.as_deref(), Some("EME-1.0")); + assert_eq!(serde_json::to_value(Entry::Known(system)).unwrap(), json); + } + + /// A scheme a later draft adds is kept, so the entry stays readable. + #[test] + fn another_scheme_is_kept() { + let json = serde_json::json!({ + "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", + "scheme": "cens", + "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", + }); + let Entry::Known(system) = serde_json::from_value(json.clone()).unwrap() else { + panic!("expected a known entry"); + }; + assert_eq!(system.scheme, Scheme::Other("cens".into())); + assert_eq!(serde_json::to_value(Entry::Known(system)).unwrap(), json); + } + + /// An entry this build cannot read is preserved verbatim rather than failing. + #[test] + fn an_unreadable_entry_round_trips() { + for json in [ + // A UUID without hyphens. + serde_json::json!({ "system": "1077efecc0b24d02ace33c1e52e2fb4b", "scheme": "cenc", "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90" }), + // A license URL that does not parse. + serde_json::json!({ "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", "scheme": "cenc", "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", "license": { "url": "not a url" } }), + // A pssh without its base64 padding, which `@moq/hang` refuses too. + serde_json::json!({ "system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b", "scheme": "cenc", "kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90", "pssh": "AAAAAA" }), + // A future shape with no fields this build knows. + serde_json::json!({ "keySystem": "future" }), + ] { + let entry: Entry = serde_json::from_value(json.clone()).unwrap(); + assert!(matches!(entry, Entry::Unknown(_)), "{json}"); + assert_eq!(serde_json::to_value(&entry).unwrap(), json); + } + } + + /// An entry that is not even an object is malformed. + #[test] + fn a_non_object_entry_is_refused() { + assert!(serde_json::from_value::(serde_json::json!("cenc")).is_err()); + } +} diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 634bf60a76e..cbc37c39f05 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -10,6 +10,7 @@ mod binary; mod clock; mod consumer; mod container; +pub mod drm; mod echo; mod hex; mod include; diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index a3328a79a6a..4ca2a453078 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -93,6 +93,15 @@ pub struct Catalog { /// Omitted from the wire when empty. A malformed entry refuses the catalog. pub include: std::collections::BTreeMap, + /// The DRM systems protecting the broadcast's CMAF renditions, keyed by entry ID. + /// + /// A protected video or audio rendition lists the IDs of its entries in its own `drm` field, + /// and one listing an ID missing here is refused by [`check_renditions`](Self::check_renditions). + /// Omitted from the wire when empty. An entry this build cannot read decodes as + /// [`Unknown`](crate::catalog::drm::Entry::Unknown) rather than refusing the catalog, and the + /// renditions listing it stay protected. See [`drm`](crate::catalog::drm). + pub drm: std::collections::BTreeMap, + /// Application-defined root sections, flattened alongside the base catalog sections. /// /// The root `version` is reserved: serializing computes it from the base sections, and fails if @@ -170,6 +179,9 @@ struct Wire { #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] include: std::collections::BTreeMap, + #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] + drm: std::collections::BTreeMap, + #[serde(flatten, serialize_with = "serialize_ext")] ext: E, } @@ -205,6 +217,7 @@ impl From> for Catalog { stats, echo, include, + drm, ext, } = wire; Self { @@ -218,6 +231,7 @@ impl From> for Catalog { stats, echo, include, + drm, ext, } } @@ -272,10 +286,11 @@ impl Catalog<()> { } impl Catalog { - /// Refuse a catalog with an ID naming both a video and an audio rendition, or with a - /// rendition field out of range, such as a zero sample rate or a projection out of bounds. + /// Refuse a catalog with an ID naming both a video and an audio rendition, with a rendition + /// field out of range, such as a zero sample rate or a projection out of bounds, or with a + /// rendition listing a `drm` entry the root lacks. /// - /// Decoding already refuses an out-of-range rendition, so this catches a catalog built by hand. + /// Decoding already refuses an out-of-range rendition, so that catches a catalog built by hand. pub fn check_renditions(&self) -> Result<()> { use crate::catalog::Rendition; @@ -293,6 +308,18 @@ impl Catalog { for config in self.audio.renditions.values() { config.check()?; } + + // A protected rendition whose entry is missing would read as clear, or name no system. + let drm = (self.video.renditions.iter().map(|(id, config)| (id, &config.drm))) + .chain(self.audio.renditions.iter().map(|(id, config)| (id, &config.drm))); + for (rendition, ids) in drm { + if let Some(id) = ids.iter().find(|id| !self.drm.contains_key(*id)) { + return Err(crate::Error::MissingDrm { + rendition: rendition.clone(), + id: id.clone(), + }); + } + } Ok(()) } @@ -320,13 +347,14 @@ impl Catalog { (renamed || warmup).then_some(4) } - /// Copy the media sections into a catalog with no application extension. + /// Copy the media sections and the `drm` entries into a catalog with no application extension. pub fn without_ext(&self) -> Catalog<()> { Catalog { video: self.video.clone(), audio: self.audio.clone(), media: self.media, text: self.text.clone(), + drm: self.drm.clone(), ..Default::default() } } @@ -488,6 +516,44 @@ mod test { assert!(failures.is_empty(), "{}", failures.join("\n")); } + /// A protected rendition references a root `drm` entry, which survives a round trip and the + /// media copy; a clear catalog writes no `drm` at all, and a dangling reference is refused. + #[test] + fn drm_entries_round_trip_and_dangling_references_are_refused() { + use crate::catalog::drm; + + let mut catalog = Catalog::<()>::default(); + assert!(!catalog.to_json().unwrap().contains("drm")); + + let kid = uuid::uuid!("a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"); + catalog.drm.insert( + "1".into(), + drm::System::new(drm::system::CLEARKEY, drm::Scheme::Cbcs, kid).into(), + ); + let mut video = VideoConfig::new(H264 { + profile: 0x64, + constraints: 0, + level: 0x1f, + inline: false, + }); + video.container = Container::Cmaf { + init: bytes::Bytes::from_static(b"init"), + }; + video.drm = vec!["1".into()]; + catalog.video.renditions.insert("hd".into(), video); + catalog.check_renditions().unwrap(); + + let decoded = Catalog::<()>::from_str(&catalog.to_json().unwrap()).unwrap(); + assert_eq!(decoded, catalog); + assert_eq!(catalog.without_ext().drm, catalog.drm); + + catalog.drm.clear(); + assert!(matches!( + catalog.check_renditions(), + Err(crate::Error::MissingDrm { rendition, id }) if rendition == "hd" && id == "1" + )); + } + /// The rendition count is the publisher's to choose: a catalog listing many is accepted. #[test] fn many_renditions_are_accepted() { @@ -788,6 +854,7 @@ mod test { reorder: None, optimize_for_latency: None, container: Container::Legacy, + drm: Vec::new(), warmup: None, jitter: Some(std::time::Duration::from_millis(100)), delay: Some(std::time::Duration::from_millis(200)), @@ -810,6 +877,7 @@ mod test { enabled: true, description: None, container: Container::Legacy, + drm: Vec::new(), warmup: None, jitter: Some(std::time::Duration::from_millis(40)), delay: None, diff --git a/rs/hang/src/catalog/video/mod.rs b/rs/hang/src/catalog/video/mod.rs index e2faf3e660a..f8d8200f328 100644 --- a/rs/hang/src/catalog/video/mod.rs +++ b/rs/hang/src/catalog/video/mod.rs @@ -316,6 +316,17 @@ pub struct VideoConfig { #[serde(default)] pub container: Container, + /// The IDs of the root `drm` entries protecting this rendition, one per DRM system that can + /// decrypt it. Empty lists none and is left off the wire; the rendition is still protected + /// when its CMAF init holds an encrypted sample entry. + /// + /// Common Encryption is defined for CMAF, so a protected rendition is a [`Cmaf`](Container::Cmaf) + /// one in practice: its init segment carries the encrypted sample entry (`encv`/`enca`), while + /// `codec` names the codec it wraps. A consumer that cannot decrypt treats a protected + /// rendition as undecodable. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub drm: Vec, + /// The maximum delay between a frame being ready and the publisher flushing it. /// The player's jitter buffer should be larger than this value. /// If not provided, the player should assume each frame is flushed immediately. @@ -393,6 +404,7 @@ impl VideoConfig { reorder: None, optimize_for_latency: None, container: Container::default(), + drm: Vec::new(), jitter: None, warmup: None, delay: None, diff --git a/rs/hang/src/error.rs b/rs/hang/src/error.rs index ce4a66b5a2e..95a374bacde 100644 --- a/rs/hang/src/error.rs +++ b/rs/hang/src/error.rs @@ -17,6 +17,15 @@ pub enum Error { #[error("catalog rendition ID is both video and audio: {0}")] DuplicateRendition(String), + /// A protected rendition lists a `drm` entry the catalog's root `drm` section lacks. + #[error("rendition {rendition} references missing drm entry {id}")] + MissingDrm { + /// The rendition listing the entry. + rendition: String, + /// The entry ID the root lacks. + id: String, + }, + /// A catalog needs a newer moq-hang draft than this reader implements. #[error("unsupported catalog version {0}: upgrade to read it")] UnsupportedVersion(u64), diff --git a/rs/moq-audio/src/decode/decoder.rs b/rs/moq-audio/src/decode/decoder.rs index 462981480fa..eb6937c82ff 100644 --- a/rs/moq-audio/src/decode/decoder.rs +++ b/rs/moq-audio/src/decode/decoder.rs @@ -54,7 +54,15 @@ impl Decoder { /// catalog fields directly and requires an absent `description`. AAC reads /// its AudioSpecificConfig; without one, legacy and LOC packets carry ADTS headers, /// while demuxed CMAF samples remain raw. + /// + /// A protected rendition (see [`moq_mux::catalog::hang::protected`]) is refused, since its samples are + /// encrypted and nothing here decrypts them. pub fn new(catalog: &hang::catalog::AudioConfig, config: &Config) -> Result { + if moq_mux::catalog::hang::protected(&catalog.drm, &catalog.container) { + return Err(Error::Unsupported( + "the rendition is encrypted, and decryption is not supported".into(), + )); + } let backend = backend::open(catalog, config)?; let delay = backend.delay(); Ok(Self { @@ -406,6 +414,17 @@ pub(crate) mod tests { } } + /// A protected rendition's samples are encrypted, so it is refused before any backend opens. + #[test] + fn a_protected_rendition_is_unsupported() { + let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + catalog.drm = vec!["1".into()]; + assert!(matches!( + Decoder::new(&catalog, &Config::default()), + Err(Error::Unsupported(_)) + )); + } + /// Without a description the catalog shapes the stream, which has no pre-skip. #[test] fn opus_decodes_without_a_description() { diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 7fc7bdcc593..1dbbd7dd821 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -402,11 +402,12 @@ impl Consume { mut catalog: moq_mux::catalog::hang::Consumer, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { + let mut clear = moq_mux::catalog::hang::Clear::default(); loop { // `biased` so a pending close always wins over a ready update: a hot // stream must not be able to starve the close signal, and we must not // deliver another update once close has been requested. - let update = tokio::select! { + let mut update = tokio::select! { biased; _ = &mut close => return Ok(()), next = catalog.next() => match next? { @@ -414,6 +415,9 @@ impl Consume { None => return Ok(()), }, }; + // A protected rendition's samples are encrypted, and nothing here decrypts them or + // exposes the `drm` section, so the bindings treat it as one they cannot decode. + clear.retain(&mut update); // Unfortunately we need to store the codec information on the heap. let audio_codec = update diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 13304162ecb..763e5cdc652 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -956,6 +956,83 @@ fn publish_video_config_replaces_its_own_rendition() { assert_eq!(moq_origin_close(origin), 0); } +/// The `ftyp` and `moov` of an fMP4 file, ahead of its first fragment, with its `avc1` sample entry +/// renamed `encv`: an encrypted entry, as far as any reader that cannot decrypt is concerned. +fn encrypted_init() -> Vec { + const FILE: &[u8] = include_bytes!("../../moq-mux/src/container/fmp4/test_data/bbb.mp4"); + let mut end = 0; + while &FILE[end + 4..end + 8] != b"moof" { + end += u32::from_be_bytes(FILE[end..end + 4].try_into().unwrap()) as usize; + } + let mut init = FILE[..end].to_vec(); + let moov = init.windows(4).position(|window| window == b"moov").unwrap(); + let entry = moov + init[moov..].windows(4).position(|window| window == b"avc1").unwrap(); + init[entry..entry + 4].copy_from_slice(b"encv"); + init +} + +/// A protected rendition (here a CMAF one whose init is encrypted) is absent from the catalog the +/// bindings see: they cannot decrypt it, so they treat it as one they cannot decode. +#[test] +fn consume_catalog_hides_protected_renditions() { + let origin = id(moq_origin_create()); + let path = b"catalog-protected"; + let broadcast = publish_broadcast(origin, path); + + let video = |name: &'static str, codec: &'static str, container: moq_container| moq_video_config { + preference: 0, + name: name.as_ptr().cast(), + name_len: name.len(), + label: std::ptr::null(), + label_len: 0, + codec: codec.as_ptr().cast(), + codec_len: codec.len(), + description: std::ptr::null(), + description_len: 0, + coded_width: 640, + coded_height: 360, + container, + warmup_us: 0, + has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, + }; + let init = encrypted_init(); + let protected = video( + "protected", + "avc1.64001f", + moq_container { + kind: moq_container_kind::MOQ_CONTAINER_KIND_CMAF as u32, + init: init.as_ptr(), + init_len: init.len(), + }, + ); + assert_eq!(unsafe { moq_publish_video_config(broadcast, &protected) }, 0); + let clear = video("clear", "vp8", moq_container::default()); + assert_eq!(unsafe { moq_publish_video_config(broadcast, &clear) }, 0); + + let consume = request_broadcast(origin, path); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog = id(catalog_cb.recv()); + + let mut config = video("", "", moq_container::default()); + assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut config) }, 0); + assert_eq!(borrowed_string(config.name, config.name_len).as_deref(), Some("clear")); + assert!(unsafe { moq_consume_video_config(catalog, 1, &mut config) } < 0); + + assert_eq!(moq_consume_catalog_free(catalog), 0); + assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); + assert_eq!(catalog_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + /// Manual catalog metadata cannot redefine the decoder identity of an existing raw track. #[test] fn manual_video_identity_change_is_refused() { diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 7753c9b1b3e..bfd77b0e935 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -599,11 +599,17 @@ impl MoqVideoInit { } } +/// Convert a catalog snapshot for the bindings, leaving out the protected renditions. +/// +/// A protected rendition (see [`moq_mux::catalog::hang::protected`]) carries encrypted samples, and +/// nothing here decrypts them or exposes the `drm` section, so the bindings treat it as one they +/// cannot decode. pub(crate) fn convert_catalog(catalog: &moq_mux::catalog::hang::Catalog) -> MoqCatalog { let video = catalog .video .renditions .iter() + .filter(|(_, config)| !moq_mux::catalog::hang::protected(&config.drm, &config.container)) .filter_map(|(name, config)| { Some(( name.clone(), @@ -637,6 +643,7 @@ pub(crate) fn convert_catalog(catalog: &moq_mux::catalog::hang::Catalog>(), ["clear"]); + assert!(converted.audio.is_empty()); + } + #[test] fn catalog_exposes_rendition_labels() { let mut catalog = moq_mux::catalog::hang::Catalog::default(); diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 46bd3c189ee..5b338d93fb1 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -976,6 +976,7 @@ impl Session { let mut tasks = tokio::task::JoinSet::new(); let mut catalog_closed = false; let mut result = Ok(()); + let mut clear = moq_mux::catalog::hang::Clear::default(); loop { if catalog_closed && tasks.is_empty() { @@ -991,7 +992,11 @@ impl Session { // The guard stops us polling a closed catalog track (which would spin the loop // returning None) while the followers drain. next = catalog_consumer.next(), if !catalog_closed => match next { - Ok(Some(catalog)) => reconcile(&catalog, &source, &playback, &mut followers, &mut tasks, &emptied, cancel), + Ok(Some(mut catalog)) => { + // Encrypted samples would reach the decoders as ciphertext; this source does not decrypt. + clear.retain(&mut catalog); + reconcile(&catalog, &source, &playback, &mut followers, &mut tasks, &emptied, cancel) + } // Catalog track closed. Don't stop the followers: let each reader reach its natural // end, and just stop reconciling while they drain. // diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 143f1d1028a..cff01deee4d 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -528,6 +528,9 @@ struct WatchCatalog { source: moq_mux::Source, renditions: renditions::Producer, role: Role, + /// Drops protected renditions: their segments would lose the `pssh`, `senc`, `saiz`, and + /// `saio` a decrypting player needs. + clear: catalog::hang::Clear, /// The source's catalog broadcast, taken on the first poll, so the catalog, the media /// subscriptions, and the closed check all refer to the one broadcast it was built from. broadcast: Option, @@ -561,6 +564,7 @@ impl WatchCatalog { source, renditions, role, + clear: Default::default(), broadcast: None, delay: CATALOG_RETRY_MIN, state: Watch::Start, @@ -603,6 +607,7 @@ impl WatchCatalog { /// Reconcile the renditions with `catalog`. fn sync(&mut self, mut catalog: catalog::hang::Catalog) { + self.clear.retain(&mut catalog); match &self.role { Role::Root(Some(include)) => include.sync(&self.source, &catalog), Role::Root(None) => {} @@ -905,6 +910,36 @@ mod tests { assert!(renditions.get(Kind::Video, "video").is_none()); } + /// A protected rendition is not served: its segments would lose the `pssh`, `senc`, `saiz`, + /// and `saio` a decrypting player needs. Its clear sibling is. + #[tokio::test(start_paused = true)] + async fn protected_rendition_is_not_advertised() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let source = moq_mux::Source::new(produce_origin().consume(), broadcast.consume()); + let mut catalog = joined(); + let mut protected = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + protected.drm = vec!["1".into()]; + catalog.drm.insert( + "1".into(), + hang::catalog::drm::System::new( + hang::catalog::drm::system::CLEARKEY, + hang::catalog::drm::Scheme::Cenc, + hang::catalog::drm::Uuid::nil(), + ) + .into(), + ); + catalog.video.renditions.insert("protected".to_string(), protected); + catalog.video.renditions.insert( + "clear".to_string(), + hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8), + ); + + let renditions = renditions::Producer::spawned(Config::default().window); + WatchCatalog::new(source, renditions.clone(), Role::Root(None)).sync(catalog); + assert!(renditions.get(Kind::Video, "protected").is_none()); + assert!(renditions.get(Kind::Video, "clear").is_some()); + } + #[tokio::test(start_paused = true)] async fn audio_renditions_follow_catalog_quality_order() { let broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-msf/src/lib.rs b/rs/moq-msf/src/lib.rs index 81dd68c9bf2..bacbb7b5b1e 100644 --- a/rs/moq-msf/src/lib.rs +++ b/rs/moq-msf/src/lib.rs @@ -57,6 +57,12 @@ pub struct Catalog { /// The tracks in this catalog snapshot. pub tracks: Vec, + /// The DRM systems protecting this broadcast's tracks (CMSF 4.1.1). + /// + /// Tracks point at these entries by [`ContentProtection::ref_id`] through + /// [`Track::content_protection_ref_ids`]. + pub content_protections: Vec, + /// The application extension: root members beyond the ones MSF defines. pub ext: E, } @@ -90,7 +96,8 @@ pub struct Catalog { /// `serde_json::Map`, which keeps them verbatim. /// /// An extension MUST NOT name a member after one MSF defines (`version`, `generatedAt`, -/// `isComplete`, `tracks`, `initDataList`); the wire JSON would carry a duplicate key. +/// `isComplete`, `tracks`, `initDataList`, `contentProtections`); the wire JSON would carry a +/// duplicate key. pub trait CatalogExt: Serialize + serde::de::DeserializeOwned + Default + Clone + Send + Unpin + 'static {} // Blanket, so a caller writes no impl: naming the trait is only about readable bounds. @@ -186,6 +193,11 @@ pub struct Track { #[serde(rename = "maxObjSapStartingType")] pub max_obj_sap_starting_type: Option, + /// The [`ContentProtection::ref_id`]s of the catalog's entries that protect this track + /// (CMSF 4.1.2). Empty means the track is not encrypted with Common Encryption. + #[serde(default, rename = "contentProtectionRefIDs", skip_serializing_if = "Vec::is_empty")] + pub content_protection_ref_ids: Vec, + /// Jitter (non-standard extension; not in the MSF/CMSF drafts). /// /// Serialized as a JSON number of milliseconds, matching the hang catalog. @@ -218,6 +230,7 @@ impl Catalog { generated_at: None, is_complete: false, tracks, + content_protections: Vec::new(), ext, } } @@ -262,7 +275,7 @@ fn colliding_member(ext: &E) -> Option { pub fn reserved_root(name: &str) -> bool { matches!( name, - "version" | "generatedAt" | "isComplete" | "tracks" | "initDataList" + "version" | "generatedAt" | "isComplete" | "tracks" | "initDataList" | "contentProtections" ) } @@ -320,6 +333,7 @@ impl Serialize for Catalog { is_complete: self.is_complete, tracks, init_data_list: (!init_data_list.is_empty()).then_some(init_data_list), + content_protections: self.content_protections.clone(), ext: self.ext.clone(), } .serialize(serializer) @@ -346,6 +360,19 @@ impl<'de, E: CatalogExt> Deserialize<'de> for Catalog { } } + // A track's protection refers to a root entry by refID; one that names none would claim + // encryption the catalog cannot describe, so it is refused like a missing initRef. + let ref_ids: std::collections::HashSet<&str> = + wire.content_protections.iter().map(|cp| cp.ref_id.as_str()).collect(); + for track in &wire.tracks { + if let Some(missing) = (track.content_protection_ref_ids.iter()).find(|id| !ref_ids.contains(id.as_str())) { + return Err(serde::de::Error::custom(format!( + "MSF track {:?} references missing content protection {:?}", + track.name, missing + ))); + } + } + let tracks = wire .tracks .into_iter() @@ -386,6 +413,7 @@ impl<'de, E: CatalogExt> Deserialize<'de> for Catalog { generated_at: wire.generated_at, is_complete: wire.is_complete, tracks, + content_protections: wire.content_protections, ext: wire.ext, }) } @@ -408,6 +436,8 @@ struct Wire { #[serde(default)] tracks: Vec, init_data_list: Option>, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + content_protections: Vec, /// The extension's own root members, written flat alongside the ones above. #[serde(flatten)] @@ -514,12 +544,106 @@ impl Track { alt_group: None, max_grp_sap_starting_type: None, max_obj_sap_starting_type: None, + content_protection_ref_ids: Vec::new(), jitter: None, delay: None, } } } +/// One DRM system configuration protecting tracks of the broadcast (CMSF 4.1.1). +/// +/// The samples are encrypted with ISO Common Encryption; the track's initialization data +/// carries the matching `sinf`/`tenc` (CMSF 4.2). draft-ietf-moq-cmsf-01 names no member for +/// its authorization URL (4.1.1.4.4) or robustness (4.1.1.4.6), so neither is carried. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub struct ContentProtection { + /// The identifier tracks use to reference this entry. + #[serde(rename = "refID")] + pub ref_id: String, + + /// The default key IDs (`default_KID`) as UUID strings. + #[serde(rename = "defaultKID")] + pub default_kid: Vec, + + /// The Common Encryption scheme, such as `cenc` or `cbcs`. + pub scheme: String, + + /// The DRM system and where to obtain its license. + #[serde(rename = "drmSystem")] + pub drm_system: DrmSystem, +} + +impl ContentProtection { + /// An entry for `drm_system` under `scheme`, naming no default key yet. + pub fn new(ref_id: impl Into, scheme: impl Into, drm_system: DrmSystem) -> Self { + Self { + ref_id: ref_id.into(), + default_kid: Vec::new(), + scheme: scheme.into(), + drm_system, + } + } +} + +/// A DRM system description within a [`ContentProtection`] (CMSF 4.1.1.4). +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub struct DrmSystem { + /// The DRM system ID as a UUID string, e.g. Widevine's `edef8ba9-79d6-4ace-a3c8-27dcd51d21ed`. + #[serde(rename = "systemID")] + pub system_id: String, + + /// The license acquisition service. + #[serde(rename = "laURL")] + pub la_url: Option, + + /// The certificate service, required by systems such as FairPlay Streaming. + #[serde(rename = "certURL")] + pub cert_url: Option, + + /// A base64 `pssh` box with the system's initialization data. + pub pssh: Option, +} + +impl DrmSystem { + /// A DRM system with only its ID set. + pub fn new(system_id: impl Into) -> Self { + Self { + system_id: system_id.into(), + la_url: None, + cert_url: None, + pssh: None, + } + } +} + +/// A service URL in a [`DrmSystem`], with an optional protocol or MIME type. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[non_exhaustive] +pub struct ProtectionUrl { + /// The service URL. + pub url: String, + + /// The protocol or MIME type, e.g. `EME-1.0`. + #[serde(rename = "type")] + pub kind: Option, +} + +impl ProtectionUrl { + /// A URL without a type. + pub fn new(url: impl Into) -> Self { + Self { + url: url.into(), + kind: None, + } + } +} + /// Packaging mode for an MSF track. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Packaging { @@ -644,6 +768,81 @@ impl<'de> Deserialize<'de> for Role { #[cfg(test)] mod test { + /// The protected-video example of draft-ietf-moq-cmsf-01 section 5.2, trimmed to two DRM + /// systems, survives a parse and a serialize unchanged. + #[test] + fn content_protection_round_trips() { + let json = r#"{ + "version": "draft-01", + "contentProtections": [ + { + "refID": "1", + "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef"], + "scheme": "cbcs", + "drmSystem": { + "systemID": "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", + "laURL": { "url": "https://widevine-license.example.com/proxy" }, + "pssh": "AAAAP3Bzc2gAAAAA7e+LqXnWSs6jy" + } + }, + { + "refID": "3", + "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef"], + "scheme": "cbcs", + "drmSystem": { + "systemID": "94ce86fb-07ff-4f43-adb8-93d2fa968ca2", + "laURL": { "url": "https://fps-license.example.com/api/licenses" }, + "certURL": { "url": "https://fps-license.example.com/cert", "type": "application/pkcs7-mime" } + } + } + ], + "tracks": [ + { "name": "video_protected", "packaging": "cmaf", "isLive": true, "codec": "avc3.4D401F", "contentProtectionRefIDs": ["1", "3"] }, + { "name": "audio", "packaging": "cmaf", "isLive": true, "codec": "mp4a.40.2" } + ] + }"#; + let catalog: super::Catalog = json.parse().unwrap(); + assert_eq!(catalog.content_protections.len(), 2); + let fairplay = &catalog.content_protections[1].drm_system; + assert_eq!( + fairplay.cert_url.as_ref().unwrap().kind.as_deref(), + Some("application/pkcs7-mime") + ); + assert_eq!(catalog.tracks[0].content_protection_ref_ids, ["1", "3"]); + assert!(catalog.tracks[1].content_protection_ref_ids.is_empty()); + + let again: super::Catalog = catalog.to_json().unwrap().parse().unwrap(); + assert_eq!(again, catalog); + let wire: serde_json::Value = serde_json::from_str(&catalog.to_json().unwrap()).unwrap(); + assert!( + wire["tracks"][1].get("contentProtectionRefIDs").is_none(), + "an unprotected track carries no refs" + ); + assert_eq!( + wire["contentProtections"][0]["drmSystem"]["systemID"], + "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed" + ); + } + + /// A catalog without protection writes no `contentProtections` member at all. + #[test] + fn no_protection_writes_nothing() { + let catalog = super::Catalog::new(vec![super::Track::new("video", super::Packaging::Cmaf)]); + let wire: serde_json::Value = serde_json::from_str(&catalog.to_json().unwrap()).unwrap(); + assert!(wire.get("contentProtections").is_none()); + assert!(wire["tracks"][0].get("contentProtectionRefIDs").is_none()); + } + + /// A track that references an entry the root lacks is refused, like a missing initRef. + #[test] + fn a_dangling_protection_ref_is_refused() { + let json = r#"{ "version": "draft-01", "tracks": [ + { "name": "video", "packaging": "cmaf", "isLive": true, "contentProtectionRefIDs": ["9"] } + ] }"#; + let err = json.parse::().unwrap_err().to_string(); + assert!(err.contains("missing content protection"), "{err}"); + } + #[test] fn track_namespace_round_trips() { for version in ["1", "\"draft-01\""] { @@ -680,6 +879,7 @@ mod test { alt_group: None, max_grp_sap_starting_type: None, max_obj_sap_starting_type: None, + content_protection_ref_ids: Vec::new(), jitter: None, delay: None, } @@ -707,6 +907,7 @@ mod test { alt_group: None, max_grp_sap_starting_type: None, max_obj_sap_starting_type: None, + content_protection_ref_ids: Vec::new(), jitter: None, delay: None, } @@ -734,6 +935,7 @@ mod test { alt_group: None, max_grp_sap_starting_type: Some(1), max_obj_sap_starting_type: Some(2), + content_protection_ref_ids: Vec::new(), jitter: Some(Duration::from_millis(15)), delay: None, } diff --git a/rs/moq-mux/src/catalog/hang/container.rs b/rs/moq-mux/src/catalog/hang/container.rs index 0186bd8e140..b816e7ab63e 100644 --- a/rs/moq-mux/src/catalog/hang/container.rs +++ b/rs/moq-mux/src/catalog/hang/container.rs @@ -73,6 +73,55 @@ pub(crate) fn supported(rendition: &str, container: &hang::catalog::Container) - } } +/// Drops the protected video and audio renditions from each catalog snapshot (see [`protected`]). +/// +/// Their samples are encrypted, and the hang spec has a consumer that cannot decrypt a rendition +/// treat it as one it cannot decode. Nothing here decrypts, and a re-encoded file would also lose +/// the `pssh`, `senc`, `saiz`, and `saio` a decrypting player needs, so every player and binding in +/// this workspace keeps one per catalog stream instead of handing out undecryptable media. +/// +/// A rendition is logged once each time it becomes protected, not on every snapshot. Only the +/// previous snapshot's protected renditions are remembered, so the state is bounded by the catalog. +#[derive(Debug, Default)] +pub struct Clear { + hidden: std::collections::BTreeSet<(&'static str, String)>, +} + +impl Clear { + /// Drop the protected renditions from `catalog`, warning about each one newly protected. + pub fn retain(&mut self, catalog: &mut hang::Catalog) { + let mut hidden = std::collections::BTreeSet::new(); + let mut keep = |kind: &'static str, name: &String, drm: &[String], container: &hang::catalog::Container| { + let clear = !protected(drm, container); + if !clear { + hidden.insert((kind, name.clone())); + } + clear + }; + (catalog.video.renditions).retain(|name, config| keep("video", name, &config.drm, &config.container)); + (catalog.audio.renditions).retain(|name, config| keep("audio", name, &config.drm, &config.container)); + for (kind, rendition) in hidden.difference(&self.hidden) { + tracing::warn!(%rendition, kind, "ignoring encrypted rendition: decryption is not supported"); + } + self.hidden = hidden; + } +} + +/// Whether a rendition's samples are encrypted: it lists `drm` entries, or its CMAF init holds an +/// encrypted (`encv`/`enca`) sample entry. +/// +/// The init check catches a publisher that encrypts without signalling it, so a consumer never +/// reads such a rendition as clear and decodes ciphertext. +pub fn protected(drm: &[String], container: &hang::catalog::Container) -> bool { + if !drm.is_empty() { + return true; + } + match container { + hang::catalog::Container::Cmaf { init, .. } => fmp4::encrypted(init), + _ => false, + } +} + impl ContainerTrait for Container { type Error = crate::Error; diff --git a/rs/moq-mux/src/catalog/hang/ext.rs b/rs/moq-mux/src/catalog/hang/ext.rs index 1b6e4d8cddb..ddf8ed309c4 100644 --- a/rs/moq-mux/src/catalog/hang/ext.rs +++ b/rs/moq-mux/src/catalog/hang/ext.rs @@ -40,7 +40,7 @@ impl CatalogExt for () {} /// The default extension stays `()` (unknown sections dropped); opt into `Extra` explicitly. /// /// `version`, `video`, `audio`, `media`, `text`, `archive`, `clock`, `json`, `binary`, `stats`, -/// `echo`, and the retired `timeline` key are reserved, so decoding and [`set`](Self::set) reject +/// `echo`, `drm`, and the retired `timeline` key are reserved, so decoding and [`set`](Self::set) reject /// them to keep the wire JSON free of duplicate or retired keys. The exception is a root `clock`, /// which moved under `media`: an older publisher's is dropped on decode, so its media still plays. #[derive(Serialize, Clone, Default, Debug, PartialEq)] @@ -70,7 +70,7 @@ fn reserved(name: &str) -> bool { | "clock" | "json" | "binary" | "stats" | "echo" - | "timeline" + | "drm" | "timeline" ) || moq_msf::reserved_root(name) } @@ -235,7 +235,7 @@ mod test { .set_section("timeline", serde_json::json!({})), Err(crate::Error::ReservedSection(_)) )); - for name in ["media", "clock", "stats", "echo"] { + for name in ["media", "clock", "stats", "echo", "drm"] { assert!( matches!( producer.modify().unwrap().set_section(name, serde_json::json!({})), diff --git a/rs/moq-mux/src/catalog/hang/mod.rs b/rs/moq-mux/src/catalog/hang/mod.rs index ac0c170d728..94b64b4e3d8 100644 --- a/rs/moq-mux/src/catalog/hang/mod.rs +++ b/rs/moq-mux/src/catalog/hang/mod.rs @@ -11,7 +11,7 @@ mod container; mod ext; pub use consumer::Consumer; -pub use container::Container; pub(crate) use container::supported; +pub use container::{Clear, Container, protected}; pub use ext::{CatalogExt, Extra}; pub use hang::Catalog; diff --git a/rs/moq-mux/src/catalog/msf/consumer.rs b/rs/moq-mux/src/catalog/msf/consumer.rs index db515153e71..70dd34a55b7 100644 --- a/rs/moq-mux/src/catalog/msf/consumer.rs +++ b/rs/moq-mux/src/catalog/msf/consumer.rs @@ -105,10 +105,17 @@ impl From for Consumer { /// Fields with no representation in `hang::Catalog` (`generated_at`, `is_complete`, `is_live`, /// `render_group`, `alt_group`, `max_grp_sap_starting_type`, `max_obj_sap_starting_type`) are /// dropped. +/// +/// `contentProtections` become the `drm` section, each `refID` an entry ID, and a track's +/// `contentProtectionRefIDs` its rendition's `drm`. An entry the hang catalog cannot read (a +/// malformed ID, URL, or `pssh`, or other than one default key) becomes an +/// [`Unknown`](hang::catalog::drm::Entry::Unknown) entry holding the MSF entry's JSON, so the +/// tracks it protects stay protected. pub(crate) fn from_msf(msf: &moq_msf::Catalog, base: &moq_net::Path) -> Result> { let mut catalog = Catalog::default(); catalog.ext = msf.ext.clone(); let mut init_cache = InitDataCache::new(); + catalog.drm = drm_from_msf(msf); for track in &msf.tracks { // The track name is the rendition ID, so a later track with the name replaces the earlier @@ -141,6 +148,7 @@ pub(crate) fn from_msf(msf: &moq_msf::Catalog, base: &moq_net: moq_msf::Role::Video => match video_config_from_msf(track, &mut init_cache)? { Some(mut config) => { config.broadcast = broadcast; + config.drm = track.content_protection_ref_ids.clone(); catalog.video.renditions.insert(track.name.clone(), config); } None => { @@ -154,6 +162,7 @@ pub(crate) fn from_msf(msf: &moq_msf::Catalog, base: &moq_net: moq_msf::Role::Audio => match audio_config_from_msf(track, &mut init_cache)? { Some(mut config) => { config.broadcast = broadcast; + config.drm = track.content_protection_ref_ids.clone(); catalog.audio.renditions.insert(track.name.clone(), config); } None => { @@ -165,11 +174,17 @@ pub(crate) fn from_msf(msf: &moq_msf::Catalog, base: &moq_net: } }, moq_msf::Role::Caption | moq_msf::Role::Subtitle => { + if protected_text(track) { + continue; + } let mut config = text_config_from_msf(track, &mut init_cache)?; config.broadcast = broadcast; catalog.text.renditions.insert(track.name.clone(), config); } moq_msf::Role::Unknown(_) if matches!(track.codec.as_deref(), Some("vtt" | "ttml" | "utf8")) => { + if protected_text(track) { + continue; + } let mut config = text_config_from_msf(track, &mut init_cache)?; config.broadcast = broadcast; catalog.text.renditions.insert(track.name.clone(), config); @@ -183,6 +198,70 @@ pub(crate) fn from_msf(msf: &moq_msf::Catalog, base: &moq_net: Ok(catalog) } +/// Whether an MSF text track is protected, which a hang text rendition has no `drm` to say, so it +/// would read as clear: such a track is left out. +fn protected_text(track: &moq_msf::Track) -> bool { + let protected = !track.content_protection_ref_ids.is_empty(); + if protected { + tracing::debug!(track = %track.name, "skipping protected MSF text track"); + } + protected +} + +/// An MSF catalog's `contentProtections` as hang `drm` entries, keyed by `refID`. +/// +/// One the hang catalog cannot read becomes an [`Unknown`](hang::catalog::drm::Entry::Unknown) +/// entry holding the MSF entry's JSON, so the tracks it protects stay protected and the rest of the +/// catalog readable. Each entry maps onto at most one, so this is never larger than the MSF catalog. +fn drm_from_msf( + msf: &moq_msf::Catalog, +) -> std::collections::BTreeMap { + let mut drm = std::collections::BTreeMap::new(); + for cp in &msf.content_protections { + let entry = match drm_entry(cp) { + Ok(system) => system.into(), + Err(reason) => { + tracing::debug!(ref_id = %cp.ref_id, reason, "MSF content protection the hang catalog cannot read"); + let fields = match serde_json::to_value(cp) { + Ok(serde_json::Value::Object(fields)) => fields, + _ => Default::default(), + }; + hang::catalog::drm::Entry::Unknown(hang::catalog::drm::UnknownEntry::new(fields)) + } + }; + drm.insert(cp.ref_id.clone(), entry); + } + drm +} + +/// `cp` as the hang entry it mirrors. +/// +/// A hang entry names one key, so an entry naming several `defaultKID`s is not read: splitting it +/// would copy its `pssh` and servers once per key, and which key a track uses is in its init. +fn drm_entry(cp: &moq_msf::ContentProtection) -> std::result::Result { + use hang::catalog::drm; + + let [kid] = cp.default_kid.as_slice() else { + return Err("not exactly one defaultKID"); + }; + let kid = drm::Uuid::try_parse(kid).map_err(|_| "malformed defaultKID")?; + let system = drm::Uuid::try_parse(&cp.drm_system.system_id).map_err(|_| "malformed systemID")?; + let server = |url: &moq_msf::ProtectionUrl| -> std::result::Result { + let mut server = drm::Server::new(url.url.parse().map_err(|_| "malformed URL")?); + server.kind = url.kind.clone(); + Ok(server) + }; + let mut entry = drm::System::new(system, drm::Scheme::from(cp.scheme.as_str()), kid); + entry.license = cp.drm_system.la_url.as_ref().map(server).transpose()?; + entry.certificate = cp.drm_system.cert_url.as_ref().map(server).transpose()?; + entry.pssh = (cp.drm_system.pssh.as_ref()) + .map(|pssh| base64::engine::general_purpose::STANDARD.decode(pssh)) + .transpose() + .map_err(|_| "malformed pssh")? + .map(Into::into); + Ok(entry) +} + /// Decode the [`Container`] for a track based on its packaging and `init_data`. /// /// Returns `Ok(None)` when the packaging is unsupported (e.g. `MediaTimeline`, @@ -288,6 +367,8 @@ fn video_config_from_msf(track: &moq_msf::Track, init_cache: &mut InitDataCache) let mut config = VideoConfig::new(codec); config.description = match &container { + // The codec an encrypted entry wraps is out of reach, and nothing decodes the rendition. + Container::Cmaf { init } if crate::container::fmp4::encrypted(init) => None, Container::Cmaf { init } => cmaf_video_description(track, init, &config.codec)?, _ => legacy_description(track, init_cache)?, }; @@ -323,6 +404,11 @@ fn audio_config_from_msf(track: &moq_msf::Track, init_cache: &mut InitDataCache) let channel_count_from_field = track.channel_config.as_deref().and_then(|s| s.parse::().ok()); let (sample_rate, channel_count) = match (track.samplerate, channel_count_from_field) { (Some(sr), Some(cc)) => (sr, cc), + (_, _) if matches!(&container, Container::Cmaf { init } if crate::container::fmp4::encrypted(init)) => { + // The sample entry an encrypted one wraps is out of reach, so its parameters are too. + tracing::warn!(track = %track.name, "skipping encrypted MSF audio track without samplerate or channelConfig"); + return Ok(None); + } (sr_opt, cc_opt) => { let derived = derive_audio_params(track, &codec, init_cache)?; ( @@ -494,6 +580,69 @@ fn derive_from_cmaf_moov(track: &moq_msf::Track, init: bytes::Bytes) -> Result &hang::catalog::drm::System { + match entry { + hang::catalog::drm::Entry::Known(system) => system, + other => panic!("expected a known entry: {other:?}"), + } + } + + /// CMSF content protection maps onto the hang `drm` section, each `refID` an entry ID. An entry + /// the hang catalog cannot read, such as one naming two default keys or a malformed system, + /// stays as an unknown entry, so the video it protects stays listed and protected. + #[test] + fn content_protections_become_drm_entries() { + use hang::catalog::drm; + + let json = r#"{ + "version": "draft-01", + "contentProtections": [ + { "refID": "wv", "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef"], "scheme": "cbcs", + "drmSystem": { "systemID": "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", + "laURL": { "url": "https://wv.example.com/", "type": "EME-1.0" }, "pssh": "AAAA" } }, + { "refID": "ck", "defaultKID": ["0123456789ABCDEF0123456789ABCDEF"], + "scheme": "cens", "drmSystem": { "systemID": "{1077EFEC-C0B2-4D02-ACE3-3C1E52E2FB4B}" } }, + { "refID": "two", "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef", "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"], + "scheme": "cenc", "drmSystem": { "systemID": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b" } }, + { "refID": "bad", "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef"], + "scheme": "cenc", "drmSystem": { "systemID": "clearkey" } } + ], + "tracks": [ + { "name": "video", "packaging": "legacy", "isLive": true, "role": "video", "codec": "vp8", + "contentProtectionRefIDs": ["wv", "ck", "two", "bad"] }, + { "name": "audio", "packaging": "legacy", "isLive": true, "role": "audio", "codec": "opus", + "samplerate": 48000, "channelConfig": "2" }, + { "name": "words", "packaging": "loc", "isLive": true, "role": "caption", "codec": "vtt" }, + { "name": "sealed", "packaging": "loc", "isLive": true, "role": "caption", "codec": "vtt", + "contentProtectionRefIDs": ["wv"] } + ] + }"#; + let msf: moq_msf::Catalog = json.parse().unwrap(); + let catalog = from_msf(&msf, &moq_net::Path::empty()).unwrap(); + catalog.check_renditions().unwrap(); + + // A hang text rendition has no `drm`, so a protected one is left out rather than read as clear. + assert_eq!(catalog.text.renditions.keys().collect::>(), ["words"]); + + assert_eq!(catalog.drm.keys().collect::>(), ["bad", "ck", "two", "wv"]); + let wv = known(&catalog.drm["wv"]); + assert_eq!(wv.system, drm::system::WIDEVINE); + assert_eq!(wv.scheme, drm::Scheme::Cbcs); + assert_eq!(wv.license.as_ref().unwrap().kind.as_deref(), Some("EME-1.0")); + assert_eq!(wv.pssh.as_deref(), Some(&[0u8, 0, 0][..])); + + // Any UUID form MSF uses is read; a scheme a later draft adds is kept. + let ck = known(&catalog.drm["ck"]); + assert_eq!(ck.system, drm::system::CLEARKEY); + assert_eq!(ck.kid, drm::Uuid::from_u128(0x01234567_89ab_cdef_0123_456789abcdef)); + assert_eq!(ck.scheme, drm::Scheme::Other("cens".into())); + + assert!(matches!(catalog.drm["two"], drm::Entry::Unknown(_))); + assert!(matches!(catalog.drm["bad"], drm::Entry::Unknown(_))); + assert_eq!(catalog.video.renditions["video"].drm, ["wv", "ck", "two", "bad"]); + assert!(catalog.audio.renditions["audio"].drm.is_empty()); + } + #[test] fn received_metadata_is_bounded() { let track = moq_msf::Track::new("video", moq_msf::Packaging::Cmaf); diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index 7a0fa308224..a2bffc28d07 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -1357,8 +1357,36 @@ fn to_msf_media(catalog: &hang::Catalog, base: &moq_net::Path) -> Some((name.to_string(), namespace)) }; - let has_multiple_video = catalog.video.renditions.len() > 1; + let protections: BTreeMap<&String, moq_msf::ContentProtection> = (catalog.drm.iter()) + .filter_map(|(id, entry)| Some((id, msf_protection(id, entry)?))) + .collect(); + + // A rendition CMSF cannot mark as protected is left out rather than advertised with a dangling + // or missing protection, which would read as clear: one listing an entry with no CMSF form, or + // one only its encrypted init marks. + let signalled_quietly = |drm: &[String], container: &hang::catalog::Container| match drm { + [] => !crate::catalog::hang::protected(drm, container), + _ => drm.iter().all(|id| protections.contains_key(id)), + }; + let signalled = |id: &str, drm: &[String], container: &hang::catalog::Container| { + let signalled = signalled_quietly(drm, container); + if !signalled { + tracing::debug!( + rendition = id, + "MSF cannot mark this rendition as protected; leaving it out" + ); + } + signalled + }; + + let has_multiple_video = (catalog.video.renditions.values()) + .filter(|config| signalled_quietly(&config.drm, &config.container)) + .count() + > 1; for (name, config) in &catalog.video.renditions { + if !signalled(name, &config.drm, &config.container) { + continue; + } let packaging = packaging_of(&config.container); let init_data = match &config.container { @@ -1387,13 +1415,20 @@ fn to_msf_media(catalog: &hang::Catalog, base: &moq_net::Path) -> track.alt_group = if has_multiple_video { Some(1) } else { None }; track.max_grp_sap_starting_type = sap_type; track.max_obj_sap_starting_type = sap_type; + track.content_protection_ref_ids = config.drm.clone(); track.jitter = config.jitter; track.delay = config.delay.filter(|delay| !delay.is_zero()); tracks.push(track); } - let has_multiple_audio = catalog.audio.renditions.len() > 1; + let has_multiple_audio = (catalog.audio.renditions.values()) + .filter(|config| signalled_quietly(&config.drm, &config.container)) + .count() + > 1; for (name, config) in &catalog.audio.renditions { + if !signalled(name, &config.drm, &config.container) { + continue; + } let packaging = packaging_of(&config.container); let init_data = match &config.container { @@ -1420,6 +1455,7 @@ fn to_msf_media(catalog: &hang::Catalog, base: &moq_net::Path) -> track.alt_group = if has_multiple_audio { Some(1) } else { None }; track.max_grp_sap_starting_type = Some(1); track.max_obj_sap_starting_type = Some(1); + track.content_protection_ref_ids = config.drm.clone(); track.jitter = config.jitter; track.delay = config.delay.filter(|delay| !delay.is_zero()); tracks.push(track); @@ -1457,7 +1493,41 @@ fn to_msf_media(catalog: &hang::Catalog, base: &moq_net::Path) -> } } } - moq_msf::Catalog::with_ext(unique, E::default()) + let mut msf = moq_msf::Catalog::with_ext(unique, E::default()); + msf.content_protections = protections.into_values().collect(); + msf +} + +/// The CMSF `contentProtections` entry for a hang `drm` entry: a known one as the entry it mirrors, +/// or an unknown one that is already a CMSF entry, as one read from MSF with several default keys +/// is, so a catalog read from MSF renders back without losing it. +fn msf_protection(id: &str, entry: &hang::catalog::drm::Entry) -> Option { + match entry { + hang::catalog::drm::Entry::Known(system) => Some(content_protection(id, system)), + hang::catalog::drm::Entry::Unknown(unknown) => { + let fields = serde_json::Value::Object(unknown.fields().clone()); + let mut msf: moq_msf::ContentProtection = serde_json::from_value(fields).ok()?; + msf.ref_id = id.to_string(); + Some(msf) + } + } +} + +/// A hang `drm` entry as the CMSF `contentProtections` entry it mirrors (draft-ietf-moq-cmsf +/// section 4.1.1), its ID becoming the `refID` tracks reference. +fn content_protection(id: &str, entry: &hang::catalog::drm::System) -> moq_msf::ContentProtection { + let server = |server: &hang::catalog::drm::Server| { + let mut url = moq_msf::ProtectionUrl::new(server.url.as_str()); + url.kind = server.kind.clone(); + url + }; + let mut system = moq_msf::DrmSystem::new(entry.system.hyphenated().to_string()); + system.la_url = entry.license.as_ref().map(server); + system.cert_url = entry.certificate.as_ref().map(server); + system.pssh = (entry.pssh.as_ref()).map(|pssh| base64::engine::general_purpose::STANDARD.encode(pssh)); + let mut msf = moq_msf::ContentProtection::new(id, entry.scheme.as_str(), system); + msf.default_kid = vec![entry.kid.hyphenated().to_string()]; + msf } #[cfg(test)] @@ -1679,6 +1749,91 @@ mod test { assert_eq!(msf.tracks[2].namespace.as_deref(), Some("right")); } + /// hang `drm` entries render as the CMSF `contentProtections` each protected track references, + /// and a catalog read back from that MSF keeps them. An unknown entry that is already a CMSF + /// entry, as one read from MSF with several keys is, renders as it was. A rendition CMSF cannot + /// mark as protected is left out: one listing an entry with no CMSF form, or one only its + /// encrypted init marks. + #[test] + fn drm_entries_render_as_content_protections() { + let mut catalog = hang::Catalog::<()>::from_str( + r#"{ + "drm": { + "wv": {"system": "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed", "scheme": "cbcs", + "kid": "01234567-89ab-cdef-0123-456789abcdef", + "license": {"url": "https://wv.example.com/", "type": "EME-1.0"}}, + "two": {"refID": "two", "scheme": "cenc", + "defaultKID": ["01234567-89ab-cdef-0123-456789abcdef", "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90"], + "drmSystem": {"systemID": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b"}}, + "odd": {"system": "not-a-uuid"} + }, + "video": {"renditions": { + "clear": {"codec": "avc1.64001f", "container": {"kind": "legacy"}}, + "hd": {"codec": "avc1.64001f", "container": {"kind": "legacy"}, "drm": ["wv"]}, + "keys": {"codec": "avc1.64001f", "container": {"kind": "legacy"}, "drm": ["two"]}, + "odd": {"codec": "avc1.64001f", "container": {"kind": "legacy"}, "drm": ["odd"]} + }}, + "audio": {"renditions": { + "sound": {"codec": "opus", "sampleRate": 48000, "numberOfChannels": 2, + "container": {"kind": "legacy"}, "drm": ["wv"]} + }} + }"#, + ) + .unwrap(); + let mut sealed = catalog.video.renditions["clear"].clone(); + sealed.container = hang::catalog::Container::Cmaf { + init: encrypted_init().into(), + }; + catalog.video.renditions.insert("sealed".to_string(), sealed); + + let msf = to_msf_media::<()>(&catalog, &moq_net::Path::empty()); + let tracks: Vec<_> = (msf.tracks.iter()) + .map(|track| (track.name.as_str(), track.content_protection_ref_ids.clone())) + .collect(); + let refs = |ids: &[&str]| ids.iter().map(|id| id.to_string()).collect::>(); + assert_eq!( + tracks, + [ + ("clear", refs(&[])), + ("hd", refs(&["wv"])), + ("keys", refs(&["two"])), + ("sound", refs(&["wv"])) + ] + ); + + let ids: Vec<_> = msf.content_protections.iter().map(|cp| cp.ref_id.as_str()).collect(); + assert_eq!(ids, ["two", "wv"]); + let wv = &msf.content_protections[1]; + assert_eq!(wv.default_kid, ["01234567-89ab-cdef-0123-456789abcdef"]); + assert_eq!(wv.scheme, "cbcs"); + assert_eq!(wv.drm_system.system_id, "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed"); + let license = wv.drm_system.la_url.as_ref().unwrap(); + assert_eq!( + (license.url.as_str(), license.kind.as_deref()), + ("https://wv.example.com/", Some("EME-1.0")) + ); + assert_eq!(msf.content_protections[0].default_kid.len(), 2); + + let back = crate::catalog::msf::from_msf(&msf, &moq_net::Path::empty()).unwrap(); + back.check_renditions().unwrap(); + assert_eq!(back.drm.keys().collect::>(), ["two", "wv"]); + assert_eq!(back.video.renditions["keys"].drm, ["two"]); + } + + /// The init of `bbb.mp4` with its video entry renamed `encv`, standing in for an encrypted one. + fn encrypted_init() -> Vec { + const FILE: &[u8] = include_bytes!("../container/fmp4/test_data/bbb.mp4"); + let mut end = 0; + while &FILE[end + 4..end + 8] != b"moof" { + end += u32::from_be_bytes(FILE[end..end + 4].try_into().unwrap()) as usize; + } + let mut init = FILE[..end].to_vec(); + let moov = init.windows(4).position(|window| window == b"moov").unwrap(); + let entry = moov + init[moov..].windows(4).position(|window| window == b"avc1").unwrap(); + init[entry..entry + 4].copy_from_slice(b"encv"); + init + } + #[test] fn cross_broadcast_renditions_round_trip_through_msf() { let base = moq_net::Path::from_static("room/catalog"); diff --git a/rs/moq-mux/src/catalog/select.rs b/rs/moq-mux/src/catalog/select.rs index 4105e9f2446..9d83b371d22 100644 --- a/rs/moq-mux/src/catalog/select.rs +++ b/rs/moq-mux/src/catalog/select.rs @@ -3,6 +3,10 @@ //! [`Select`] wraps any [`Stream`] and applies a [`select::Broadcast`](crate::select::Broadcast) //! to each snapshot, dropping renditions that aren't selected before handing the //! catalog to an exporter. +//! +//! Protected renditions are dropped too (see [`Clear`](super::hang::Clear)), since nothing that +//! consumes a selection decrypts. A snapshot whose media is all protected reads as one with no +//! media yet. use std::task::{Poll, ready}; @@ -18,12 +22,17 @@ use crate::select; pub struct Select { inner: S, selection: select::Broadcast, + clear: super::hang::Clear, } impl Select { /// Wrap `inner`, narrowing every snapshot by `selection`. pub fn new(inner: S, selection: select::Broadcast) -> Self { - Self { inner, selection } + Self { + inner, + selection, + clear: Default::default(), + } } } @@ -31,11 +40,12 @@ impl Stream for Select { type Ext = S::Ext; fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll>>> { - let next = ready!(self.inner.poll_next(waiter))?; - Poll::Ready(Ok(next.map(|mut catalog| { - self.selection.retain(&mut catalog); - catalog - }))) + let Some(mut catalog) = ready!(self.inner.poll_next(waiter))? else { + return Poll::Ready(Ok(None)); + }; + self.clear.retain(&mut catalog); + self.selection.retain(&mut catalog); + Poll::Ready(Ok(Some(catalog))) } } @@ -48,14 +58,27 @@ mod tests { use super::super::hang::Catalog; use super::*; - /// A one-shot stream: yields its snapshot once, then ends. - struct Once(Option); + /// A stream that yields its snapshots in order, then ends. + struct Snapshots(std::collections::VecDeque); - impl Stream for Once { + impl Snapshots { + fn new(snapshots: impl IntoIterator) -> Self { + Self(snapshots.into_iter().collect()) + } + } + + impl Stream for Snapshots { type Ext = (); fn poll_next(&mut self, _: &kio::Waiter) -> Poll>> { - Poll::Ready(Ok(self.0.take())) + Poll::Ready(Ok(self.0.pop_front())) + } + } + + fn next(stream: &mut impl Stream) -> Catalog { + match stream.poll_next(&kio::Waiter::noop()) { + Poll::Ready(Ok(Some(catalog))) => catalog, + other => panic!("expected snapshot, got {other:?}"), } } @@ -70,13 +93,31 @@ mod tests { (name.to_string(), config) } + /// A protected rendition is dropped, and a snapshot whose media is all protected reads as one + /// with no media yet, so a clear rendition published later is still exported. + #[test] + fn protected_renditions_are_dropped() { + let mut catalog = Catalog::default(); + let (name, mut protected) = h264("protected"); + protected.drm = vec!["1".to_string()]; + catalog.video.renditions.insert(name, protected); + let only_protected = catalog.clone(); + let (name, clear) = h264("clear"); + catalog.video.renditions.insert(name, clear); + + let selection = select::Broadcast::default().video(select::Video::default()); + let mut stream = Snapshots::new([only_protected, catalog]).select(selection); + assert!(next(&mut stream).video.renditions.is_empty()); + assert_eq!(next(&mut stream).video.renditions.keys().collect::>(), ["clear"]); + } + #[test] fn narrows_each_snapshot() { let mut catalog = Catalog::default(); catalog.video.renditions = BTreeMap::from_iter(vec![h264("lo"), h264("hi")]); let selection = select::Broadcast::default().video(select::Video::default().name("hi")); - let mut stream = Once(Some(catalog)).select(selection); + let mut stream = Snapshots::new([catalog]).select(selection); let out = match stream.poll_next(&kio::Waiter::noop()) { Poll::Ready(Ok(Some(c))) => c, @@ -91,7 +132,7 @@ mod tests { let mut catalog = Catalog::default(); catalog.video.renditions = BTreeMap::from_iter(vec![h264("lo"), h264("hi")]); - let boxed: Box> = Box::new(Once(Some(catalog))); + let boxed: Box> = Box::new(Snapshots::new([catalog])); let selection = select::Broadcast::default().video(select::Video::default().name("lo")); let mut stream = boxed.select(selection); diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 091bafe4a63..f3140a691db 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -75,6 +75,30 @@ fn decode_init(init: &[u8]) -> (mp4_atom::Ftyp, mp4_atom::Moov) { (ftyp, moov) } +/// An init whose sample entry is encrypted (`encv`/`enca`) reads as protected even when the +/// catalog lists no `drm` entry, so a publisher that encrypts without signalling it is never read +/// as clear. +#[test] +fn an_encrypted_sample_entry_reads_as_protected() { + let (ftyp, moov) = decode_init(include_bytes!("test_data/bbb.mp4")); + let mut head = Vec::new(); + ftyp.encode(&mut head).unwrap(); + let mut body = Vec::new(); + moov.encode(&mut body).unwrap(); + let cmaf = |moov: &[u8]| Container::Cmaf { + init: [head.as_slice(), moov].concat().into(), + }; + assert!(!crate::catalog::hang::protected(&[], &cmaf(&body))); + + // Renaming the entry stands in for a real `encv`, which also wraps the clear entry's fields. + for (clear, encrypted) in [(b"avc1", b"encv"), (b"mp4a", b"enca")] { + let at = body.windows(4).position(|window| window == clear).unwrap(); + let mut renamed = body.clone(); + renamed[at..at + 4].copy_from_slice(encrypted); + assert!(crate::catalog::hang::protected(&[], &cmaf(&renamed))); + } +} + fn video_config(codec: mp4_atom::Codec) -> hang::catalog::VideoConfig { video_config_result(codec).unwrap() } diff --git a/rs/moq-mux/src/container/fmp4/mod.rs b/rs/moq-mux/src/container/fmp4/mod.rs index c545ea96e47..ed4e90f1119 100644 --- a/rs/moq-mux/src/container/fmp4/mod.rs +++ b/rs/moq-mux/src/container/fmp4/mod.rs @@ -25,6 +25,28 @@ pub use muxer::*; /// A major version bump of `mp4_atom` is a breaking change for moq-mux. pub use mp4_atom; +/// Whether a CMAF init segment holds an encrypted (`encv`/`enca`) sample entry. +/// +/// An init that fails to parse is not one, since no consumer reads it either way. +pub(crate) fn encrypted(init: &[u8]) -> bool { + use mp4_atom::{Any, Codec, DecodeMaybe, FourCC}; + + if metadata::check(init).is_err() { + return false; + } + // This mp4-atom has no Common Encryption boxes, so it keeps either entry as unknown. + let protected = [FourCC::new(b"encv"), FourCC::new(b"enca")]; + let mut cursor = std::io::Cursor::new(init); + while let Ok(Some(atom)) = Any::decode_maybe(&mut cursor) { + if let Any::Moov(moov) = atom { + return (moov.trak.iter()) + .flat_map(|trak| &trak.mdia.minf.stbl.stsd.codecs) + .any(|codec| matches!(codec, Codec::Unknown(kind, _) if protected.contains(kind))); + } + } + false +} + /// The largest text sample [`Import`] holds whole. /// /// A text sample is rewritten only once its last byte arrives, so a larger one is refused before diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index 3c6e2758c39..f87a5a55a20 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -266,15 +266,21 @@ impl Source { /// /// Every export runs this on each catalog snapshot, so a disabled rendition reads as /// absent: one that is disabled later leaves the snapshot, and one that re-enables - /// returns to it. Every section carrying renditions must be listed here; one left out - /// silently exempts its renditions from the containment check, exactly as on the - /// consumer side. + /// returns to it. A protected one reads as absent as well, since no export decrypts it + /// (see [`protected`](crate::catalog::hang::protected)). Every section carrying + /// renditions must be listed here; one left out silently exempts its renditions from the + /// containment check, exactly as on the consumer side. pub(crate) fn retain_selectable( &self, catalog: &mut crate::catalog::hang::Catalog, ) { - catalog.video.renditions.retain(|_, config| config.enabled); - catalog.audio.renditions.retain(|_, config| config.enabled); + // Nothing exported is decrypted, so a protected rendition reads as absent too. `Select`, + // which exports read through, logs it. + let selectable = |enabled: bool, drm: &[String], container: &hang::catalog::Container| { + enabled && !crate::catalog::hang::protected(drm, container) + }; + (catalog.video.renditions).retain(|_, config| selectable(config.enabled, &config.drm, &config.container)); + (catalog.audio.renditions).retain(|_, config| selectable(config.enabled, &config.drm, &config.container)); self.retain_valid_references("video", &mut catalog.video.renditions); self.retain_valid_references("audio", &mut catalog.audio.renditions); self.retain_valid_references("text", &mut catalog.text.renditions); @@ -1121,6 +1127,33 @@ mod tests { assert!(catalog.audio.renditions.is_empty()); } + /// A protected rendition is never exported, since nothing exported is decrypted, while its + /// clear sibling is. + #[test] + fn protected_rendition_is_removed_while_clear_sibling_remains() { + let origin = produce_origin(); + let source = created(&origin); + let clear = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0, + level: 0x1e, + inline: false, + }); + let mut protected = clear.clone(); + protected.drm = vec!["1".into()]; + let mut audio = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + audio.drm = vec!["1".into()]; + + let mut catalog = hang::Catalog::<()>::default(); + catalog.video.renditions.insert("protected".to_string(), protected); + catalog.video.renditions.insert("clear".to_string(), clear); + catalog.audio.renditions.insert("audio".to_string(), audio); + source.retain_selectable(&mut catalog); + + assert_eq!(catalog.video.renditions.keys().collect::>(), vec!["clear"]); + assert!(catalog.audio.renditions.is_empty()); + } + /// The filter covers every section carrying renditions, not just the media ones. Text /// is the section that only exists on one side of the containment check by default, so /// it is the one that silently goes unchecked when the two sides drift. diff --git a/rs/moq-rtmp/src/server.rs b/rs/moq-rtmp/src/server.rs index ffc4990937d..a23f88029d6 100644 --- a/rs/moq-rtmp/src/server.rs +++ b/rs/moq-rtmp/src/server.rs @@ -975,11 +975,16 @@ impl Play { /// Narrow a play to what the client can decode, or refuse it. /// /// A multitrack client receives every enabled rendition, so it must play them all. A -/// single-track client receives the best enabled rendition of each kind it can play. +/// single-track client receives the best enabled rendition of each kind it can play. A protected +/// rendition is never sent (the export drops it), so it is left out here too. fn play_selection( catalog: &moq_mux::catalog::hang::Catalog, capabilities: &ClientCapabilities, ) -> std::result::Result { + let mut catalog = catalog.clone(); + (catalog.video.renditions).retain(|_, config| !moq_mux::catalog::hang::protected(&config.drm, &config.container)); + (catalog.audio.renditions).retain(|_, config| !moq_mux::catalog::hang::protected(&config.drm, &config.container)); + let catalog = &catalog; let video_playable = |config: &VideoConfig| plays_video(capabilities, config.codec.kind()); let video_refused = if capabilities.multitrack { catalog @@ -2501,6 +2506,12 @@ mod tests { catalog.video.renditions.get_mut("b").unwrap().enabled = false; assert!(play_selection(&catalog, &h264_only).is_ok()); assert_eq!(best(&catalog, &h264_only).as_deref(), Some("a")); + + // A protected rendition is never sent, so one the client can't decode refuses nothing. + let b = catalog.video.renditions.get_mut("b").unwrap(); + b.enabled = true; + b.drm = vec!["1".into()]; + assert!(play_selection(&catalog, &h264_only).is_ok()); } /// A single-track client gets the best audio rendition it can play, not the first by name. diff --git a/rs/moq-transcode/src/catalog.rs b/rs/moq-transcode/src/catalog.rs index a1f77512202..4d33dd4066e 100644 --- a/rs/moq-transcode/src/catalog.rs +++ b/rs/moq-transcode/src/catalog.rs @@ -148,6 +148,7 @@ impl Decoders { let mut config = rendition.clone(); config.description = None; config.container = Container::Legacy; + config.drm.clear(); match &mut config.codec { VideoCodec::H264(h264) => h264.inline = true, VideoCodec::H265(h265) => h265.in_band = true, @@ -172,6 +173,8 @@ pub(crate) async fn choose_source(video: &Video, decoders: &mut Decoders) -> Res // A rendition that itself lives in another broadcast can't be subscribed // through this one; composing relative references is a follow-up. .filter(|(_, config)| config.broadcast.is_none()) + // A protected rendition's samples are encrypted, and nothing here decrypts them. + .filter(|(_, config)| !moq_mux::catalog::hang::protected(&config.drm, &config.container)) .filter_map(|(name, config)| Some((name, config, codec(config)?))); let mut refused = None; @@ -220,6 +223,7 @@ pub(crate) async fn follow_source( let mut kept = None; if let Some(config) = video.renditions.get(current) && config.broadcast.is_none() + && !moq_mux::catalog::hang::protected(&config.drm, &config.container) && dimensions(config).is_some() && let Some(codec) = codec(config) // The name can stay while the codec changes under it. @@ -359,6 +363,8 @@ pub(crate) fn populate( ) -> Result<(), Error> { out.video = Video::default(); out.audio = hang::catalog::Audio::default(); + // The rungs are clear; only the source renditions listed below may reference an entry. + out.drm.clear(); // The derivative republishes the child's timeline, so its timestamps only mean something under // the child's wall mapping. out.media.clock = source.media.clock; @@ -381,6 +387,8 @@ pub(crate) fn populate( if out.media.join.is_none() { out.media.join = source.media.join; } + // A protected source rendition keeps its `drm` IDs, so the entries come along. + out.drm = source.drm.clone(); for (name, config) in &source.video.renditions { if config.broadcast.is_some() { @@ -1076,4 +1084,37 @@ mod tests { }; assert_eq!(frame.timestamp.unwrap().as_millis(), adopted.now().as_millis()); } + + /// A protected rendition's samples are encrypted, so it is never the source, however well it + /// ranks; the derivative still lists it, with the `drm` entries it references. + #[tokio::test] + async fn a_protected_rendition_is_not_transcoded() { + use hang::catalog::drm; + + let mut child = moq_mux::catalog::hang::Catalog::<()>::default(); + child.drm.insert( + "1".into(), + drm::System::new(drm::system::CLEARKEY, drm::Scheme::Cbcs, drm::Uuid::nil()).into(), + ); + let mut protected = source(1920, 1080, None); + protected.drm = vec!["1".into()]; + child.video.insert("protected", protected).unwrap(); + child.video.insert("clear", source(640, 360, None)).unwrap(); + + let (name, _) = choose_source(&child.video, &mut decodes_all()).await.unwrap(); + assert_eq!(name, "clear"); + let (name, _) = follow_source(&child.video, "protected", &mut decodes_all()) + .await + .unwrap(); + assert_eq!(name, "clear"); + + let rel = Relative::new(".").unwrap(); + let mut out = moq_mux::catalog::hang::Catalog::<()>::default(); + populate(&mut out, &child, &[], Some(&rel)).unwrap(); + assert_eq!(out.drm, child.drm); + out.check_renditions().unwrap(); + + populate(&mut out, &child, &[], None).unwrap(); + assert!(out.drm.is_empty(), "only the rungs, which are clear"); + } } diff --git a/rs/moq-video/src/decode/decoder.rs b/rs/moq-video/src/decode/decoder.rs index 10fecbfaacb..100a80607e1 100644 --- a/rs/moq-video/src/decode/decoder.rs +++ b/rs/moq-video/src/decode/decoder.rs @@ -172,11 +172,17 @@ impl Decoder { /// Build a decoder for the catalog's video config. /// /// A codec or description this build cannot decode is - /// [`Error::UnsupportedCodec`], and so is a stream every decoder for its codec - /// refused because its device cannot decode it. When any of them failed to open - /// for another reason, such as a missing driver, the result is - /// [`Error::NoDecoder`], a fault rather than a property of the track. + /// [`Error::UnsupportedCodec`], as is a protected rendition (see [`moq_mux::catalog::hang::protected`]), whose + /// samples are encrypted, and a stream every decoder for its codec refused because its + /// device cannot decode it. When any of them failed to open for another reason, such as + /// a missing driver, the result is [`Error::NoDecoder`], a fault rather than a property + /// of the track. pub fn new(catalog: &VideoConfig, config: &Config) -> Result { + if moq_mux::catalog::hang::protected(&catalog.drm, &catalog.container) { + return Err(Error::UnsupportedCodec( + "the rendition is encrypted, and decryption is not supported".into(), + )); + } // CMAF samples are length-prefixed whatever the sample entry; Legacy and LOC // carry Annex-B exactly when the parameter sets are in band. let cmaf = matches!(catalog.container, Container::Cmaf { .. }); @@ -530,6 +536,23 @@ mod tests { crate::Size::new(320, 240) } + /// A protected rendition's samples are encrypted, so it is refused like a codec this build + /// cannot decode, before any backend opens. + #[test] + fn a_protected_rendition_is_unsupported() { + let mut catalog = hang::catalog::VideoConfig::new(hang::catalog::H264 { + inline: true, + profile: 0x42, + constraints: 0, + level: 0x1e, + }); + catalog.drm = vec!["1".into()]; + assert!(matches!( + super::Decoder::new(&catalog, &super::Config::new()), + Err(crate::Error::UnsupportedCodec(_)) + )); + } + #[test] #[cfg(feature = "openh264")] fn openh264_round_trip() { diff --git a/rs/moq-webrtc/src/egress.rs b/rs/moq-webrtc/src/egress.rs index a5722823352..a62989d52b6 100644 --- a/rs/moq-webrtc/src/egress.rs +++ b/rs/moq-webrtc/src/egress.rs @@ -112,9 +112,13 @@ impl EgressSource { /// which takes the receiver via [`Self::take_writes`]. pub async fn new(source: moq_mux::Source) -> Result { let mut consumer = source.catalog::<()>(moq_mux::catalog::CatalogFormat::Hang).await?; - let catalog = consumer.next().await?.ok_or(Error::CatalogClosed)?; + let mut catalog = consumer.next().await?.ok_or(Error::CatalogClosed)?; + // WebRTC egress would forward ciphertext as media; it does not decrypt. The first + // snapshot passes the same filter as the rest, which keeps it to log each rendition once. + let mut clear = moq_mux::catalog::hang::Clear::default(); + clear.retain(&mut catalog); let (catalog_tx, catalog) = watch::channel(catalog); - let catalog_end = tokio::spawn(follow_catalog(consumer, catalog_tx)); + let catalog_end = tokio::spawn(follow_catalog(consumer, catalog_tx, clear)); let (tx, rx) = mpsc::channel(64); Ok(Self { @@ -194,13 +198,18 @@ impl EgressSource { } } -/// Publish each catalog snapshot until the catalog ends or every pump is gone, failing with the -/// catalog's failure. -async fn follow_catalog(mut consumer: moq_mux::catalog::Consumer<()>, tx: watch::Sender) -> Result<()> { +/// Publish each catalog snapshot, without its protected renditions, until the catalog ends or +/// every pump is gone, failing with the catalog's failure. +async fn follow_catalog( + mut consumer: moq_mux::catalog::Consumer<()>, + tx: watch::Sender, + mut clear: moq_mux::catalog::hang::Clear, +) -> Result<()> { loop { tokio::select! { next = consumer.next() => match next { - Ok(Some(catalog)) => { + Ok(Some(mut catalog)) => { + clear.retain(&mut catalog); tx.send_replace(catalog); } Ok(None) => return Ok(()), @@ -922,6 +931,36 @@ mod tests { assert_eq!(written(&mut writes).await.as_ref(), b"high-1"); } + /// A protected rendition in the first and only snapshot is never served: the line takes its + /// clear sibling, as it would for a disabled one. + #[tokio::test(start_paused = true)] + async fn a_protected_rendition_in_the_first_snapshot_is_skipped() { + use hang::catalog::drm; + + let origin = produce_origin(); + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let mut high = vp8(&mut broadcast, &mut catalog, "high", 1080); + let mut low = vp8(&mut broadcast, &mut catalog, "low", 360); + { + let mut modify = catalog.modify().unwrap(); + let entry = drm::System::new(drm::system::CLEARKEY, drm::Scheme::Cenc, drm::system::CLEARKEY); + modify.drm.insert("1".to_string(), entry.into()); + modify.video.renditions.get_mut("high").unwrap().drm = vec!["1".to_string()]; + } + + let mut egress = EgressSource::new(moq_mux::Source::new(origin.consume(), broadcast.consume())) + .await + .unwrap(); + let mut writes = egress.take_writes(); + egress.on_track(Mid::from("0"), vec![format(Codec::Vp8, 96)]).unwrap(); + + high.write(frame(0, b"high-0", true)).unwrap(); + low.write(frame(0, b"low-0", true)).unwrap(); + assert_eq!(written(&mut writes).await.as_ref(), b"low-0"); + idle(&mut writes).await; + } + /// A rendition the catalog moves to another track, in its broadcast or a sibling one, keeps /// its media line: the line switches to the new track at its first keyframe past the /// playhead and serves nothing more of the track it left, even while that one still sends. diff --git a/rs/workspace-hack/Cargo.toml b/rs/workspace-hack/Cargo.toml index 838cb68d234..c846f596097 100644 --- a/rs/workspace-hack/Cargo.toml +++ b/rs/workspace-hack/Cargo.toml @@ -127,7 +127,7 @@ typenum = { version = "1", default-features = false, features = ["const-generics url = { version = "2", features = ["serde"] } usage-argv = { version = "7", default-features = false, features = ["complete", "diagnostics", "help-advanced"] } usage-rs = { version = "7", features = ["completions", "config"] } -uuid = { version = "1", features = ["v4", "v7"] } +uuid = { version = "1", features = ["serde", "v4", "v7"] } winnow-dff4ba8e3ae991db = { package = "winnow", version = "1", features = ["simd"] } zeroize = { version = "1", features = ["derive"] } @@ -242,7 +242,7 @@ typenum = { version = "1", default-features = false, features = ["const-generics url = { version = "2", features = ["serde"] } usage-argv = { version = "7", default-features = false, features = ["complete", "diagnostics", "help-advanced"] } usage-rs = { version = "7", features = ["completions", "config"] } -uuid = { version = "1", features = ["v4", "v7"] } +uuid = { version = "1", features = ["serde", "v4", "v7"] } winnow-ca01ad9e24f5d932 = { package = "winnow", version = "0.7" } winnow-dff4ba8e3ae991db = { package = "winnow", version = "1", features = ["simd"] } zeroize = { version = "1", features = ["derive"] } @@ -347,7 +347,6 @@ tokio = { version = "1", default-features = false, features = ["tracing"] } tokio-rustls = { version = "0.26", default-features = false, features = ["aws-lc-rs", "tls12"] } tower = { version = "0.5", default-features = false, features = ["retry", "timeout"] } tower-http = { version = "0.6", default-features = false, features = ["decompression-gzip", "follow-redirect"] } -uuid = { version = "1", default-features = false, features = ["serde"] } zerocopy = { version = "0.8", default-features = false, features = ["derive", "simd"] } [target.aarch64-unknown-linux-gnu.build-dependencies] @@ -379,7 +378,6 @@ tokio = { version = "1", default-features = false, features = ["tracing"] } tokio-rustls = { version = "0.26", default-features = false, features = ["aws-lc-rs", "tls12"] } tower = { version = "0.5", default-features = false, features = ["retry", "timeout"] } tower-http = { version = "0.6", default-features = false, features = ["decompression-gzip", "follow-redirect"] } -uuid = { version = "1", default-features = false, features = ["serde"] } zerocopy = { version = "0.8", default-features = false, features = ["derive", "simd"] } [target.x86_64-pc-windows-msvc.dependencies] @@ -458,7 +456,6 @@ tokio = { version = "1", default-features = false, features = ["tracing"] } tokio-rustls = { version = "0.26", default-features = false, features = ["aws-lc-rs", "tls12"] } tower = { version = "0.5", default-features = false, features = ["retry", "timeout"] } tower-http = { version = "0.6", default-features = false, features = ["decompression-gzip", "follow-redirect"] } -uuid = { version = "1", default-features = false, features = ["serde"] } zerocopy = { version = "0.8", default-features = false, features = ["derive", "simd"] } [target.x86_64-unknown-linux-gnu.build-dependencies] @@ -490,7 +487,6 @@ tokio = { version = "1", default-features = false, features = ["tracing"] } tokio-rustls = { version = "0.26", default-features = false, features = ["aws-lc-rs", "tls12"] } tower = { version = "0.5", default-features = false, features = ["retry", "timeout"] } tower-http = { version = "0.6", default-features = false, features = ["decompression-gzip", "follow-redirect"] } -uuid = { version = "1", default-features = false, features = ["serde"] } zerocopy = { version = "0.8", default-features = false, features = ["derive", "simd"] } ### END HAKARI SECTION