libfreemkv/docs/lfsr.md

# CSS content cipher (`src/css/lfsr.rs`)

## Module overview

The algorithm is the publicly documented CSS stream cipher, described in the
open CSS cryptanalysis literature. It is implemented here from that public
description; its constants (see [`super::tables`]) are the cipher's own
defined values. Nothing in this file is copied or translated from any
particular CSS software.

The cipher uses two table-driven linear-feedback circuits:
- **LFSR1** — a 17-bit register (a 9-bit and an 8-bit half seeded from
  `key[0..2] XOR seed[0..2]`), stepped through `TAB2`/`TAB3`/`TAB5`.
- **LFSR0** — a 24-bit feedback register (seeded from `key[2..5] XOR
  seed[2..5]`), stepped through a feedback polynomial and `TAB4`.

Each output byte is the sum-with-carry of the two register outputs. A body
byte is recovered as `plain = TAB1[cipher] ^ keystream` — a `TAB1`
substitution of the ciphertext byte followed by an XOR with the keystream
(so the cipher is deliberately not its own inverse).

## `descramble_sector`

The two feedback registers are seeded **directly** from
`title_key XOR sector_seed` (bytes `0x54..0x59`) — there is no title-key
mangling on the content path (that belongs to the disc/title-key hierarchy,
not the sector cipher). Only the body, bytes `0x80..0x800`, is transformed:
`body[i] = TAB1[body[i]] ^ (keystream & 0xff)`.

The scramble flag at byte `0x14` (bits 4-5) marks an encrypted sector. This
routine CLEARS that flag after unscrambling, so a descrambled sector reads as
`sector[0x14] & 0x30 == 0`; callers and tests use that to tell it from
ciphertext, and re-running descramble on an already-cleared sector is a no-op
(the flag guard below skips it). Clearing does not affect the recovered body.

`sector.len() < 2048` (the encrypted region `0x80..0x800` not fully present):
callers chunk by 2048, so a trailing partial chunk is left untouched. The
`debug_assert!` flags this misuse in debug/test builds; a DVD sector is
always exactly 2048 bytes.

## `scramble_sector` (test helper)

Exact inverse of `descramble_sector`: turn a plaintext sector body into
CSS ciphertext under `title_key`.

Descramble computes `plain = TAB1[cipher] ^ (keystream & 0xff)`, so the
inverse is `cipher = TAB1_INV[plain ^ (keystream & 0xff)]` with the identical
keystream. The keystream derivation is the same as `descramble_sector`;
only the final substitution differs. Bytes `0x80..0x800` are rewritten in
place; the scramble flag is set to `0x10` so a subsequent descramble runs.

Not on any production read path — it exists so the key-recovery tests (and
any caller that needs a known CSS-encrypted sector) can build genuine
ciphertext rather than approximating it.

## Test notes

### `descramble_produces_the_reference_css_vector`

Regression vector: the deterministic output of the CSS content cipher for
a fixed key/seed/body. The value is generated by this implementation and
is self-consistent with the scramble/descramble round-trip test — any
correct CSS descrambler yields the same bytes, since the cipher is
deterministic. Pins the implementation against accidental change.

key = 42 13 37 BE EF, seed (0x54..0x59) = DE AD BE EF 42, body = 0xAA.

### `css_descramble_inverts_scramble_over_body`

The content cipher is NOT a plain XOR involution (it applies TAB1 to the
ciphertext: `plain = TAB1[cipher] ^ ks`). The true inverse is
`scramble_sector`. Scrambling a plaintext body and then descrambling
with the same key must reproduce the original body exactly.

### `css_tab1_is_permutation`

Verify the structure of TAB1: it is a substitution table used in key
mangling. Check that no two inputs map to the same output (TAB1 is a
permutation of 0..255).

### `descramble_treats_high_bits_of_0x14_as_clear`

Only bits 4-5 of byte 0x14 are the CSS scramble flag: the code reads
`sector[0x14] & 0x30 == 0` (bits 6-7, i.e. 0x40/0x80, are masked out by
0x30). A sector with 0x14 == 0x40 or 0x80 must therefore be treated as
UNSCRAMBLED and left byte-for-byte unchanged. This guards against a
too-wide mask silently "descrambling" (and thus corrupting) clear data.

Grounding: CSS sector header byte 0x14 — copyright/scramble bits live in
bits 4-5; the masked value 0 means not scrambled.
Mutation: widen the mask `0x30` to `0x70`/`0xF0` -> 0x40/0x80 would be
seen as scrambled and the body would change.

### `descramble_triggers_on_either_flag_bit`

Each individual scramble bit (4 and 5) independently marks the sector as
encrypted: 0x10 and 0x20 must both trigger descrambling.

Grounding: `(0x10 >> 4) & 3 == 1`, `(0x20 >> 4) & 3 == 2` — both nonzero.
Mutation: change `!= 0` early-return condition to `== 3` -> a sector
flagged only 0x10 or 0x20 would be skipped and left scrambled.

### `descramble_clear_preserves_high_bits_of_0x14`

After descrambling, ONLY the two scramble bits are cleared (`& 0xCF`);
bits 6 and 7 of byte 0x14 must be preserved. A sector with 0x14 == 0xF0
becomes 0xC0 (bits 6,7 kept, bits 4,5 cleared), NOT 0x00.

Grounding: code does `sector[0x14] &= 0xCF`; 0xF0 & 0xCF == 0xC0.
Mutation: change `&= 0xCF` to `= 0` or `&= 0x0F` -> the preserved high
bits assert fails.

### `descramble_leaves_header_and_seed_intact`

The encrypted region is exactly bytes 0x80..0x800. Bytes 0x00..0x80 (the
header) must NOT be modified by the keystream — except byte 0x14 whose
flag is cleared. In particular the sector-seed bytes 0x54..0x59 (which
live inside the header) must survive untouched, since the descrambler
reads them but never writes them.

Grounding: loop is `sector.iter_mut().take(2048).skip(128)` -> indices
128..2048 only.
Mutation: change `.skip(128)` to `.skip(0)` -> header bytes (incl. the
seed) get XORed and this fails.

### `descramble_covers_final_body_byte`

The descrambler must touch the WHOLE body 0x80..0x800, not just a prefix.
With a constant body and constant key, the keystream is non-degenerate
enough that the very last sector byte (index 2047) is altered. This guards
the loop bound `.take(2048)` against an off-by-one that would leave the
final byte(s) scrambled.

Grounding: encrypted region end is 0x800 == 2048 (exclusive).
Mutation: change `.take(2048)` to `.take(2047)` -> last byte unchanged,
assert fires (this body is all-zero so any keystream XOR shows).

### `descramble_processes_the_first_sector_of_an_over_long_buffer`

The length guard is a FLOOR, not a ceiling: `descramble_sector` is a
no-op below one sector, and processes the FIRST sector of anything at
least that long (the loop is `.take(2048)`). `css::descramble_sector` is
a public entry taking `&mut [u8]` of any length, so a caller handing it a
multi-sector buffer must get its first sector descrambled — a guard that
rejected over-long buffers would hand that caller its ciphertext back
unchanged, with the scramble flag cleared as if it had worked.

### `descramble_output_depends_on_title_key`

Descramble is keyed by `title_key XOR seed`: two different title keys
produce two different bodies for the same scrambled input. A cipher that
ignored the title key (or mixed it in wrongly) would yield identical
output — silent wrong-key decryption.

Grounding: per-sector key = title_key[i] ^ sector[0x54+i].
Mutation: in the `key` array drop the `title_key[i] ^` term -> both keys
give the same body, assert fires.

### `descramble_output_depends_on_seed`

Descramble is keyed by the sector seed too: same title key, different
seed -> different body. Pins that bytes 0x54..0x59 actually feed the
keystream (not just the per-sector XOR key).

Mutation: replace `seed` array reads with a constant -> both seeds give
the same body, assert fires.