libfreemkv/docs/css-mod.md

# `src/css/mod.rs` — extended notes

Overflow detail relocated from doc comments in `src/css/mod.rs` (kept short
there per the comment-guard caps). Function/item names below match the code.

## `CSS_LOCKED_BAIL`

The bus-auth read gate is global (all-or-nothing), so a run this long of
`05/6F/03` (CSS-locked) reads means the gate is shut and nothing here is
crackable — bail instead of grinding the full 50_000-sector budget. That
grind is what made rc5 appear to hang on a wedged USB bridge.

## `crack_key`

Recovers the CSS title key with no keys, by scanning scrambled sectors and
running the known-plaintext attack (see the `keyless` module). The crib comes
from the periodic-run detector: a scrambled sector's cleartext region
(bytes 0x00..0x80) often ends in a short-period repeating run (stuffing /
constant fill); the attack assumes that run continues across the 0x80
boundary into the encrypted region, giving the known plaintext the 2^16 LFSR
recovery needs. Scans up to 50000 sectors across the extents and returns the
first sector that yields a key — no player keys, no disc-key crack. Works on
a live drive (after bus-auth unlocks reads) and on disc images alike.

This convenience form runs to completion (no cancellation) and returns just
the key; callers needing an operator-Stop / watchdog cancel, or the
three-way `CrackOutcome` (to distinguish "unencrypted" from
"encrypted-but-uncracked"), use `crack_key_outcome`, which takes a `halt`
token.

## `CrackOutcome`

Distinguishes the three cases the bare `Option<CssState>` conflated (and
which caused a silent-failure bug: scrambled-but-uncracked content was
treated as "unencrypted" and muxed as plaintext garbage at exit 0):

- `Cracked` — a scrambled sector yielded a title key.
- `Unencrypted` — NO scrambled sector was seen across the scanned extents
  (`is_scrambled_pack` never true): the content is genuinely plaintext, so
  proceeding without a key is correct.
- `ScrambledUncracked` — scrambled sectors WERE seen but no key could be
  recovered (the recovery found no crackable crib, or the scrambled region
  was unreadable). The content is encrypted; muxing it as plaintext would
  emit garbage, so callers MUST surface a hard error instead of falling
  through to "unencrypted" — the per-title `crate::error::Error::CssKeyMissing`
  when it is ONE title's own re-crack that failed (skippable: a sibling VTS
  may still crack), or the disc-level `crate::error::Error::CssNoDiscKey`
  when it is the disc-wide scan (`Disc::css_error`, every title fails
  identically).

## `resolve_dvd_title_key`

The SINGLE place every DVD read path obtains a title key, so the file-backed
mux highway (`crate::build_iso_pipeline`) and the live-drive single-pass
`crate::DiscStream` descramble a DVD identically ("reading is reading"). CSS
keys are per-VTS and crackable from the scrambled data itself, so a
`None`/MPEG-PS title cracks its own key here, in playback order over
`extents`. Everything else is left untouched:

- AACS keys (HD-DVD `.evo` is also MPEG-PS but arrives as `Aacs`) — no CSS.
- a title that already carries a key — nothing to resolve.
- a genuinely clear DVD (no scrambled sector) — stays `None`, a mux no-op.

A scrambled-but-uncrackable title is a hard `crate::error::Error::CssKeyMissing`,
never a silent scrambled-passthrough mux. That code is the PER-TITLE one
(`error::is_skippable_title_stub`), which is correct here: this function
cracks ONE title's own extents, and another VTS on the same disc may still
yield its key, so an all-titles rip skips this title and finishes the rest.
The whole-disc failure is `crate::error::Error::CssNoDiscKey`, raised by
`Disc::ensure_decryptable_keys` from the scan's `css_error`.

## `crack_key_scan` (private)

Tracks a `saw_scrambled` flag so a scrambled-but-uncracked disc is
distinguished from a genuinely-unencrypted one (the `crack_key` `Option`
wrapper collapses both to `None` via `CrackOutcome::into_state`).

## `descramble_sector`

A no-op unless the sector is a scrambled MPEG-2 PS PACK. The pack start code
is checked, not just the byte 0x14 flag bits, for the same reason
`descramble_region` checks it: 0x14 only means "scrambling control" inside a
pack, and in an IFO it is whatever that format stores there. A real
`VIDEO_TS.IFO` sector holds 0x15 there while starting `00 26 00 00`;
descrambling it destroyed 1912 of its 2048 bytes, and because that sector
carries TT_SRPT the disc enumerated 38 titles while an image decrypted from
it enumerated 10, silently, at exit 0.

This function has no callers inside the crate, but the module-level example
prescribes it — so the crate's own documented guidance led straight into
that defect. Making the guard part of the function, rather than something
each caller must remember, is what keeps the safe path the easy one.

## `descramble_region`

Descrambles a whole CSS buffer in place, re-cracking the title key on a VOB
region boundary. `title_key` is a CACHE of the last crack, not a fixed disc
key: it changes per VTS/VOB region, so it is validated on every scrambled
sector and re-cracked on a miss (the standard on-demand per-region rekey).

This CSS key acquisition is intrinsic to the cipher — CSS has no external key
source, the ONLY way to a title key is cracking the data — so it lives with
the CSS primitives and runs inside `decrypt::decrypt_sectors` (a public,
self-contained CSS decrypt), NOT at the post-decrypt recovery seam that AACS
key-fetch and FMTS segment-skip use (those consume external inputs).

The clear header (`<0x80`) is never scrambled, so its periodic crib predicts
the plaintext at `0x80`. Descramble with the cached key; if the crib fails to
reappear the key region changed (or the primed key was wrong) — restore the
ciphertext, re-crack from this very sector, and descramble again. A crib-less
sector (no periodic run) can be neither validated nor cracked, so it rides
the cached key — correct, because it lives in the same region as the nearby
crib sector that set the cache.

This section used to document an `Error::DecryptFailed` for the case where a
sector's crib rejects the cached key and the re-crack from that sector also
fails. That behaviour was tried and REVERTED: crib mismatch plus crack
failure is the signature of a crib FALSE POSITIVE, not of a stale key, and
failing there made real discs unrippable. The code now descrambles with the
cached key and returns `Ok`.

## `has_scramble_flag_bits`

Deliberately NOT called `is_scrambled`. Byte 0x14 only means "scrambling
control" inside an MPEG-2 Program Stream pack; in an IFO, UDF or ISO 9660
sector it is whatever that format stores there. Treating the flag alone as
proof of scrambling is what destroyed 1912 bytes of a real disc's
`VIDEO_TS.IFO` — the sector carrying TT_SRPT — so the disc enumerated 38
titles and an image decrypted from it enumerated 10, silently, at exit 0.

Callers want `is_scrambled_pack`. It asks the same question and also
requires the pack start code, which every genuinely scrambled VOB sector
carries and no IFO sector does.

It stays public only because an integration test asserts the flag
extraction directly. It has no production callers, and its previous doc
comment claimed one (`decrypt::decrypt_sectors`) that did not exist — so the
name was an invitation and the documentation was an argument for accepting
it.

## `is_scrambled_pack`

The HARDENED test the crack scan uses to set its `saw_scrambled` evidence
flag (Fix 3).

`has_scramble_flag_bits` keys solely on bits 4-5 of byte 0x14. That byte is
only meaningful inside a real DVD sector — an MPEG-2 Program Stream pack,
which ALWAYS begins with the 32-bit pack-start code `00 00 01 BA` at offset
0x00. A tiny clear / nav-only stub (a 0.5 s menu loop, an FBI-warning title)
can carry arbitrary bytes that happen to set bits 4-5 of byte 0x14; trusting
byte 0x14 alone there would flip the scan's `saw_scrambled` gate and make a
genuinely-UNENCRYPTED title report `ScrambledUncracked` — a false E7023.

Requiring the pack-start signature FIRST means only a sector that is
structurally a DVD video pack can be counted as scramble evidence. This does
NOT weaken the genuine "encrypted but uncrackable" hard-fail: a real
scrambled feature is made of valid PS packs, so its scrambled sectors still
pass this check and still drive `ScrambledUncracked` when no key cracks.

The pack-start check alone is not enough, and the sector's PES `stream_id`
(offset 0x11, the byte after the 14-byte pack header's `00 00 01` PES
prefix) is the second load-bearing gate. CSS scrambles ONLY elementary
streams — video (`0xE0..=0xEF`) and private_stream_1 audio/subpicture
(`0xBD`) — and it never touches the clear header, so byte 0x11 is the TRUE
stream_id even on a scrambled sector. The MPEG-PS structural packets that
are never CSS-scrambled — system_header (`0xBB`), padding (`0xBE`) and
private_stream_2 (`0xBF`, DVD PCI/DSI navigation) — must be excluded,
because on those the byte at 0x14 is NOT a PES scrambling-control field but
raw payload/structure whose bits 4-5 land set by chance.

This is the DETECTION defect a decrypted HD-DVD tripped: an HD-DVD `.evo` is
MPEG-PS exactly like a DVD `.vob`, and its RDI navigation packs are
private_stream_2 (`0xBF`) whose payload byte at 0x14 routinely has bits 4-5
set. With no `0x11` gate those nav packs flipped the crack scan's
`saw_scrambled` flag on a disc that carries no CSS at all; the crack then
found no key (there is none) and the scan returned `ScrambledUncracked`,
hard-failing a perfectly good HD-DVD with `CssKeyMissing` — E7023. Excluding
`0xBB/0xBE/0xBF` at 0x11 makes the evidence gate match what the crack itself
can act on (the recovery only recovers a key from a scrambled ES pack), so a
decrypted HD-DVD now scans to `Unencrypted` and muxes cleanly.

This does NOT weaken the genuine "encrypted but uncrackable" hard-fail on a
real DVD: a scrambled DVD feature is made of video (`0xE0..`) and
private_stream_1 (`0xBD`) packs, none of which are excluded, so its
scrambled sectors still set `saw_scrambled` and still drive
`ScrambledUncracked` when no key cracks. Byte 0x11 is in the clear header,
so a scrambled DVD pack can never masquerade as `0xBB/0xBE/0xBF`.

The DESCRAMBLE path gates on this same function — `descramble_sector` and
`descramble_region` both call it, not the raw flag test — because the raw
test does not merely mis-skip a sector there: it descrambles one that was
never scrambled and destroys it. The measured case is written up above under
`descramble_region`: a `VIDEO_TS.IFO` sector holding 0x15 at offset 0x14 lost
1912 of its 2048 bytes, taking TT_SRPT with it, and the disc's 38 titles
became 10 — silently, at exit 0. One gate, both paths.

## Tests (`mod tests`)

Detail relocated from test doc comments:

- `a_crib_false_positive_keeps_the_cached_key_rather_than_failing`:
  `attack_crib` is a heuristic — it finds a periodic run in the unscrambled
  header and predicts the run continues past 0x80. When that prediction does
  not hold, the crib reports a mismatch even though the cached key is
  correct, and the re-crack then fails BECAUSE the crib was never valid. So
  this combination is the signature of a crib false positive, not of a stale
  key, and the cached key remains the best available evidence. This test
  exists because a prior round read the same code as "descrambling with a
  key we just proved stale" and made it `DecryptFailed` to match the AACS
  path; real DVDs hit this constantly, and the change made a real disc
  unrippable (no unit test caught it — the real-media acceptance gate did).
  CSS is not AACS: an AACS unit key either opens a unit or does not, whereas
  a CSS title key is recovered from data whose recoverability varies sector
  by sector.

- `has_scramble_flag_bits_short_buffer_is_false_no_panic`: grounding —
  `sector.len() >= 2048 && (sector[0x14] >> 4) & 0x03 != 0` short-circuits so
  a short buffer never reads index 0x14. Mutation: swapping operand order
  would panic indexing a 20-byte slice; this test catches it.

- `has_scramble_flag_bits_uses_bits_4_5_only`: grounding —
  `(sector[0x14] >> 4) & 0x03`. Mutation: widening the mask to `& 0x0F` makes
  0x40 report scrambled; the 0x40 assert catches it.

- `has_scramble_flag_bits_exact_sector_length_accepted`: grounding —
  `sector.len() >= 2048`. Mutation: `>= 2048` → `> 2048` makes an exact
  2048-byte scrambled sector report false; this catches it.

- `is_scrambled_pack_requires_pack_start_signature`: Fix 3 hardening —
  `is_scrambled_pack` requires BOTH the pack-start code and the 0x14 bits, so
  a clear/nav-only stub with stray 0x14 bits isn't scramble evidence (else a
  genuinely unencrypted title reports the false E7023).

- `is_scrambled_pack_excludes_nav_and_structural_stream_ids`: detection fix —
  `is_scrambled_pack` must exclude system_header/padding/private_stream_2 by
  `stream_id` at 0x11, since CSS never scrambles those and byte 0x14 there is
  raw payload, not a scrambling-control field. This is the exact
  decrypted-HD-DVD defect (an `.evo` RDI pack is 0xBF with pack-start and
  0x14 bits set); the video/private_stream_1 cases prove the exclusion
  doesn't weaken real-DVD detection.

- `MockSource` fields `lock_all`, `crackable`, `short_read`, `stream_id`: model
  a CSS-locked drive (`05/6F/03` on every read), a designated crackable LBA
  serving a full synthetic scrambled sector, a short-read count (the
  `recovery: true` short-read contract, `Some(0)` being the degenerate
  spin-guard case), and the PES `stream_id` written at 0x11 (used to model an
  HD-DVD `.evo` RDI nav pack via `PRIVATE_STREAM_2`).

- `crackable_sector`: builds a crackable scrambled sector whose cleartext
  header (0x59..0x80) carries a periodic run continuing across the 0x80
  boundary, mirroring the `synth_periodic_sector` fixture in the keyless
  tests but built from the crate-internal `scramble_sector`.

- `a_source_that_returns_zero_sectors_still_obeys_the_scan_budget`: `tried`
  increments only per inspected sector inside `for s in 0..usable`; an
  `Ok(0)` never runs that loop, so `advance` is forced to 1 to keep the
  cursor moving and the extent's full declared length is walked. Mutation:
  deleting the `tried` charge in the `usable == 0` arm goes red at 60,000
  reads for a misbehaving/adversarial source.

- `crack_key_caps_total_tries_at_50000`: grounding — `max_tries = 50_000`,
  `tried += 1` before the read, loop guard `tried < max_tries`. Mutation:
  widening the cap, or removing the increment, both go red.

- `crack_key_budget_is_shared_across_extents`: grounding — `tried` is
  declared outside the extent loop with a shared `if tried >= max_tries`
  break. Mutation: moving the declaration inside the loop would give each
  extent its own budget (80,000 total instead of 50,000).

- `crack_key_scans_from_extent_start_lba`: grounding —
  `reader.read_sectors(ext.start_lba + i, ...)`. Mutation: dropping
  `ext.start_lba +` would start LBAs at 0 instead of the extent's start.

- `crack_key_continues_past_read_errors`: grounding — a read `Err` falls
  through to the next sector rather than aborting. Mutation: propagating the
  error with `?` would stop the scan after the first failure.

- `crack_key_empty_extent_reads_nothing` / `crack_key_no_extents_is_none`:
  grounding — `while i < ext.sector_count` / `for ext in extents` are no-ops
  on empty input; an off-by-one (`<=`) or a pre-loop read would break these.

- `crack_outcome_reaches_cracked_with_span`: audit gap "MockSource never
  yields a crackable sector" — drives the full `crack_key_scan` over a
  synthetic ISO to exercise the `Cracked` branch and `crack_span` recording
  end-to-end, previously untested.

- `is_scrambled_uncracked_is_true_for_that_case_and_false_for_the_other_two`:
  a prior round introduced the three-way split precisely because conflating
  the cases made an uncrackable disc exit 0 with garbage output; earlier
  tests only asserted the TRUE direction, so a predicate answering "yes"
  unconditionally was indistinguishable from a correct one. All three
  outcomes here come from real `crack_key_outcome` scans, not hand-built enum
  values.

- `resolve_dvd_title_key_*` tests: `resolve_dvd_title_key` is the SINGLE
  shared per-title CSS step both read paths (`build_iso_pipeline` multi-pass
  and `DiscStream::new` single-pass) call, so these pin its full contract at
  the shared boundary — crack success, hard-fail on scrambled-uncrackable
  (never leaving `keys` as `None`, which would mux scrambled bytes as
  plaintext), the decrypted-HD-DVD RDI-pack regression (end to end), `--raw`
  passthrough, the AACS-keys-untouched gate, the clear-DVD no-op, and the
  halt-cancellation-surfaces-as-Halted fix (not a truncated-scan verdict).

- `all_locked_synthetic_iso_yields_css_key_missing_signal`: audit §2/§5 #7 —
  pins that an all-locked synthetic ISO across MULTIPLE extents produces
  `ScrambledUncracked`, the exact signal `disc/mod.rs` converts into
  `disc.css_error = Some(Error::CssKeyMissing)`.

- `recrack_succeeds_on_other_vts_extents`: audit gap "success path missing"
  — the prior re-crack test only covered the locked→None path; this proves a
  key cracked for one VTS is genuinely re-derived (not reused) for another.