libfreemkv/docs/keysource.md

keysource.rs — extended notes

Overflow rationale relocated from src/keysource.rs doc comments by the comment-guard (prose caps: 8 lines for pub-item rustdoc, 3 lines for internal comments). Each section below is pointed to by a short ////// comment at the corresponding site in the source.

Module overview — ownership split

libfreemkv still OWNS the crypto: the boil-down primitives and the AES live here. A source owns only PATH ORCHESTRATION — deciding which primitive to call with what input for the material it happens to hold. Source implementations are published in the companion freemkv-keysources crate, keeping key policy (which store, which order, online vs local) out of the library. It knows what material it holds (a DK / MK / VUK / pre-decrypted UK) and what it must fetch from the disc (VID, MKB, encrypted title keys, content samples) to get there.

MIN_SAMPLE_UNITS — why this many, why here

The key service identifies a key by which of the submitted units it decrypts, so too few samples — especially on FMTS, where a segment interleaves several variants at the unit level — can return a key that matches an incidental unit rather than the one asked about (a false positive). This many distinct units make the request unambiguous.

Canonical here (the base crate) so BOTH consumers agree on one value: the online source in freemkv-keysources (which refuses to send an under-sampled request) re-exports it, and libfreemkv's own FMTS forensic query ([crate::mux]) sizes its per-segment batch by it. Layering forbids the reverse import (keysources depends on libfreemkv, not vice versa), so the value lives at the lower layer both share.

DecodeSampleSet — parse, don't validate

"Parse, don't validate": the only constructor, DecodeSampleSet::new, returns None for an under-sized slice, so an online key request simply cannot be built from too few samples. The runtime len() < MIN_SAMPLE_UNITS check that used to live at the request site (and was silently forgotten by an under-sampling caller, reading as "key service down") becomes a compile-time obligation: a request builder that takes &DecodeSampleSet can never receive an unchecked Vec.

The count enforced here is a runtime property of the disc (how many encrypted units it yields); the requested count is a caller-side compile-time constant that callers pin to MIN_SAMPLE_UNITS (see e.g. autorip's SAMPLE_UNITS). Together the two make under-sampling unrepresentable at the request boundary.

The wrapped samples are on-disc AACS ciphertext — the same bytes the sibling DiscInputs::samples redacts as key MATERIAL — so Debug is hand-written and redacting.

DecodeSampleSet's hand-written Debug

A derived Debug dumped every wrapped sample verbatim: a DecodeSampleSet carries at least MIN_SAMPLE_UNITS 6144-byte aligned units (>= 49 KiB, in practice multi-MB) of AACS ciphertext plus each unit's clear 16-byte derivation seed, so one tracing::debug!("{set:?}") on a failed /decode request — or an assert_eq! whose panic message formats it — wrote all of it to the log that gets attached to a bug report. Same policy and same shape as DiscInputs's impl.

DiscInputs's hand-written Debug

Redacting Debug, per the policy aacs::types documents (and which aacs::types::Vid already applies to this very Volume ID). DiscInputs is public and returned by crate::Disc::inputs, so a consumer's tracing::debug!("{inputs:?}") used to print the Volume ID, the whole Unit_Key_RO.inf (the encrypted title keys), the entire MKB and every ciphertext sample verbatim into a log that ends up attached to a bug report. Only non-secret identity and shape (presence, lengths) is printed.

DiscInputsCtx::new — parse-failure policy

A present-but-malformed unit_key_ro (truncated / wrong magic / wrong stride) parses to an empty key set, so a later enc_title_keys returns Ok(&[]) indistinguishably from a disc that legitimately has no title keys — the parse failure is swallowed here, not surfaced as an error.

KeySource trait — the two resolve operations

Returning an empty Vec means "no key for this disc from this source"; an Err means the source itself failed (I/O, parse, network). The caller (resolve_and_apply) tries each source in order and validates the returned keys against real ciphertext before committing them, so a wrong key from one source transparently falls through to the next.

Two explicit resolve operations, one per key kind — never one overloaded call whose meaning depends on how many keys came back:

• get_unit_keys — the disc's base per-CPS-unit Unit Keys (index space = CPS-unit number). The common path for every disc.
• get_fmts_indexes — the AACS 2.1 forensic index keys (index space = forensic index 1..N). Defaults to empty: a source with no forensic material opts out, and only an FMTS disc ever asks.

What each source must do to answer is the source's own business: a keydb keys on disc_hash and reads no samples; the online source submits the ctx's content samples (a base batch for get_unit_keys, an index-1 anchor batch for get_fmts_indexes) to the key service.

resolve_unit_keys — de-conflating "no entry" from "matched, no key"

get_unit_keys returns a bare Vec<UnitKey>: an empty result cannot say WHETHER the source had no entry for this disc at all, or matched the disc and still derived nothing (the classic "matched but needs a VID this path can't supply"). resolve_unit_keys carries that distinction. It returns a UnitKeyResolution:

• keys: Vec<UnitKey> — the terminal Unit Keys produced (empty = none).
• matched: bool — the source matched this disc in its store (by hash / VID) even if it then derived no key; false is a genuine miss.
• miss_path: Vec<KeyNode> — when matched and keys is empty, the nodes walked AFTER the implicit MatchedDisc node (e.g. [NoVid] or [NoDerivableKey]); empty means the caller supplies a bare NoDerivableKey. Ignored unless matched and keys is empty.
• matched_entry: Option<MatchedEntry> — a booleans-and-lengths shape of the matched entry (no key material) for the application to log.
• store_entries: Option<usize> — per-disc entries loaded in this source's store, so a true-miss verdict can name the store size.

The trait's default is coarse: forward to get_unit_keys and report matched = false. A source that keys on a per-disc identity (a keydb) overrides it to set matched / miss_path / matched_entry, so the trace can render matched disc > no VID > NO KEY instead of a flat no entry. See docs/aacs-trace.md for the trace-node shapes.

resolve_and_apply_traced — one-shot semantics and CPS-unit numbering

One-shot per source: each source's KeySource::get_unit_keys is called exactly once with a DiscInputsCtx over inputs. Non-empty Unit Keys are mapped to terminal Key::Units and applied via crate::Disc::decrypt_with, which validates them against inputs.samples and only mutates the disc on success — so a wrong/partial key set is rejected and the loop continues.

CPS-unit numbering: a source returns Unit Keys carrying the POSITIONAL index from crate::aacs::derive::decrypt_unit_key; the library's canonical CPS-unit number is position + 1 (matching crate::aacs::inf::parse_unit_key_ro's (i + 1)), so the committed AacsState.unit_keys is byte-identical to the library-resolved path.

The NUMBER itself is not what descramble indexes by — but the ORDER is load-bearing, so a source must return its keys in CPS-unit order. Trial decrypt-and-check was deliberately deleted (see crate::decrypt::AacsKeyMap: decryption is driven by the disc's CPS-unit / FMTS-segment structure, "never by trial-decrypt-and-check per unit"), and decrypt_sectors_mapped indexes the committed pool POSITIONALLY — unit_keys[key_idx].1, where key_idx is a POSITION in the Vec a source returned, recorded by resolve_mux_key_map_cached / resolve_fmts_key_map. Return the same keys in a different order and every AacsKeyMap points at the wrong key: the whole title decrypts under a neighbour's key, or a forensic range trips the is_clean net into DecryptFailed. (The doc used to say the number "is cosmetic for descramble (the decrypt path strips it and tries every key)", which is what the DELETED trial-decrypt path did; the only place that still tries every key is Disc::decrypt_with's sample VALIDATION, which does not descramble content.)

fetch_unit_keys — the two callers

This is exactly what both paths do — only the samples differ:

• at disc open, ctx carries reachable-content samples → resolves the up-front CPS units (the common one),
• in the read, on a decrypt miss, ctx carries the FAILING unit's ciphertext → resolves the CPS unit that wasn't sampled up front.

Same sources, same call; there is no separate "fetch". Unlike resolve_and_apply this does not validate/commit to a disc — the read's decorator re-decrypts with the returned keys, which is the validation.

FetchOutcome — the error-signal struct

Whether a driver run resolved keys, and — when it did NOT — whether the miss was a genuine "no source holds this key" (errored == false) or at least one source FAILED (errored == true, e.g. a network source was unreachable). The distinction gates negative-result memoization: an empty-because-absent result is safe to cache, an empty-because-a-source-was-down result is transient and must NOT be cached (the key may resolve once the source recovers).

drive_unit_keys

fetch_unit_keys plus the error signal: drive sources in order, return the first source's non-empty Unit Keys, and flag whether any source that failed to answer did so with an Err (a source failure) rather than an empty Ok (genuine absence — see KeySource::get_unit_keys).

key_fetch — one builder, memoization policy

One builder, used by every read path (sweep / patch / mux) and every consumer (CLI, autorip) — neither application contains the fetch logic, only its key-source config. Cheap to clone; build once, clone into each read path. make_sources is invoked per fetch (the cold path) so the resolver stays Send + Sync without requiring KeySource: Send.

Each operation is memoized per sample-batch fingerprint (keys are disc-level, so repeats hit cache). A genuinely-empty reply is cached, but a source FAILURE is not — a transient miss (see FetchOutcome::errored).

read_encrypted_units — why here, and the CPI selection rule

Lives in the library, not a key-source crate: reading the disc and carving AACS units is decryption mechanism (unit geometry anchored at each extent's start_lba), which the library owns. A key source is handed these bytes via DiscInputs.samples; it never reads the disc itself.

"Encrypted" is decided by crate::aacs::content::aacs_unit_encrypted — the AACS Copy Permission Indicator (CPI) in the top 2 bits of byte 0, the spec-correct signal (buf[0] & 0xc0). NOT the is_clean TS-sync heuristic: a unit lacking clean TS syncs does not imply encryption (an FMTS variant frame or an odd clear unit can lack syncs yet be unencrypted), and a clear unit sent to a key server yields nothing to validate against — the "0 encrypted units" rejection. A clip opens with clear navigation units (PAT/PMT, menus) whose CPI is clear; only CPI-flagged content units are collected — probing several points spread across EACH extent so a title whose encrypted body starts late (or whose midpoint lands in clear nav) still yields samples. CPI is read at each extent's start_lba (clip-file-anchored), so byte 0 is a real unit start and the flag is meaningful.

Test doc overflow

key_source_host_certs_defaults_to_empty

Spec: a source holding no cert returns the empty vec; the mkb param is forward-looking and the default ignores it. Mutation: a default returning a non-empty vec would inject phantom certs into the OEM handshake.

errored_empty_is_not_cached_and_retries_when_source_recovers

A transient source outage must NOT be memoized as a permanent "no key": a fingerprint whose first fetch failed because the source errored must be re-asked, and once the source recovers the key resolves. Regression guard for the negative-result memoization fix — caching the errored empty would permanently drop a recoverable unit for the rest of the op.

key_fetch_routes_unit_and_fmts_to_distinct_source_methods

The two KeyFetch operations route to the two DISTINCT trait methods: unit_keys drives get_unit_keys, fmts_indexes drives get_fmts_indexes. A source that returns different keys per method proves the seam no longer collapses "1 base key" and "the forensic set" into one overloaded call — the operation, not the return length, decides which.

read_encrypted_units_finds_scrambled_content_off_the_midpoint

#4 regression: encrypted content NOT at the extent midpoint (a late-starting feature, or a midpoint landing in clear nav) must still be sampled — empty samples make decrypt_with skip wrong-key validation. The old midpoint-and-forward sampler returned empty; the probe-spread finds the early scrambled band.

read_encrypted_units_selects_by_cpi_not_ts_sync

DISCRIMINATING: selection is by the AACS CPI (byte 0), NOT the TS-sync clarity heuristic. Half the units lack TS syncs but are CPI-CLEAR (byte0 & 0xC0 == 0) — genuinely UNencrypted units that merely lack TS syncs; the old sampler collected these and the key server rejected the POST as "0 encrypted units". read_encrypted_units must skip them and return ONLY CPI-flagged units. A regression to selecting by TS-sync clarity would collect the CPI-clear units too and fail the & 0xC0 assertion.

disc_inputs_ctx_parses_unit_keys_at_the_version_stride

Audit #5 — a DISCRIMINATING test for the version→stride fix. A 2-key Unit_Key_RO.inf whose SECOND key sits at the V20 (64-byte) offset; a V10 (48-byte) parse reads a DIFFERENT region. Confirms DiscInputsCtx parses at the stride for inputs.version — a swapped from_major branch or a hardcoded stride (the exact bug 1.2.0 fixes) would fail this, where the prior single-key fixtures passed regardless of stride.

disc_inputs_debug_is_redacted

DiscInputs is public and returned by Disc::inputs, so any consumer's tracing::debug!("{inputs:?}") prints it. A derived Debug printed the Volume ID (the value aacs::types::Vid deliberately renders as Vid(<redacted>)), the whole Unit_Key_RO.inf (the encrypted title keys), the entire MKB and every ciphertext sample verbatim. Sentinel byte 0xD5 = decimal 213, matching aacs::types::redaction_tests. Mutation guard: restoring #[derive(Debug)] fails this.

decode_sample_set_debug_is_redacted

DecodeSampleSet is public and wraps the SAME on-disc ciphertext the sibling DiscInputs redacts, so a derived Debug dumped >= MIN_SAMPLE_UNITS x 6144 bytes of verbatim AACS ciphertext (plus every unit's clear 16-byte derivation seed) into any log that formatted it. Sentinel byte 0xD5 = decimal 213, matching aacs::types::redaction_tests and the DiscInputs test above. Mutation guard: restoring #[derive(Debug)] fails this.