Files

T

matthew dc174e2c3d aacs: libredrive raw-read VID path + revert v0.25.9 built-ins + walker fix follow-through

Three coherent threads landing for v0.25.11:

1. Libredrive raw-read VID path. When Mt1959::do_unlock sees both the
   MMkv active-mode marker at [12..16] and the LbDr mode-ID marker at
   [16..20], Drive::is_libredrive_active() returns true and
   do_handshake skips the AACS cert dance — VID is retrieved via
   READ_DISC_STRUCTURE format 0x80 with AGID=0 and bus encryption is
   already off. This unblocks UHD ripping on drives whose leaked host
   cert is on the AACS HRL.

   - platform/mt1959/mod.rs: detection + active flag + 4 unit tests.
   - platform/mod.rs: PlatformDriver::is_libredrive_active trait method.
   - drive/mod.rs: Drive::is_libredrive_active accessor.
   - disc/encrypt.rs: do_handshake branches on the flag; new
     read_volume_id_libredrive helper. Return type widened to
     (Option<HandshakeResult>, Option<Error>) so callers see which
     specific failure happened.
   - disc/mod.rs: scan_with plumbs the new tuple through and preserves
     handshake errors as disc.aacs_error.

2. Revert v0.25.9 built-in AACS keys + plugin slot. Single source of
   AACS truth: keydb.cfg. The compiled-in DKs/PKs were a slim
   convenience that didn't move the hard problem (no v77+ DKs) and
   added a maintenance surface. Plugin slot was overlapping
   functionality with the main keydb.

   - Deleted src/aacs/builtin_keys.rs (4 DKs + 3 PKs).
   - Removed KeyDb::with_builtins, load_or_builtins, merge_from,
     merge_local_plugin, local_plugin_path, internal dedup helpers.
     KeyDb::empty kept for unit-test use.
   - KeyDb::load reverts to pre-0.25.9 form: read file or return I/O
     error; no fallback.
   - disc::encrypt::resolve_encryption keydb_path back to required
     (&Path), not Option<&Path>.
   - disc::scan_with surfaces KeydbLoad { path: "<no keydb in search
     paths>" } sentinel when encrypted + no keydb — same sentinel
     autorip's message switch already handles.
   - CSS player keys in src/css/auth.rs stay compiled in; they're
     1999-era public inputs separate from AACS and pre-date the 0.25.9
     additions.

3. Walker fix follow-through (libaacs-parity validate_processing_key,
   cvalues 0x07-then-0x05 preference, path-2/3/4 short-circuit on
   zero VID) + NIST AES-CMAC KAT + VID MAC round-trip / mutation /
   zero-rejection tests.

5 new Error variants for finer-grained AACS failure reporting:
AacsHostCertRejected (E7015), AacsLibredriveUnsupported (E7016),
AacsVidUnavailable (E7017), AacsMkUnavailable (E7018),
AacsVukNotInKeydb (E7019). Lets CLIs/UIs render which piece of the
AACS chain failed instead of always saying "no keys."

2026-05-21 11:10:35 -07:00

6.9 KiB

Raw Permalink Blame History

libfreemkv — Rules

No English in library code

The library contains ZERO user-facing English text. All errors use numeric codes from error.rs. Applications (CLI, GUI, server) handle i18n.

io::Error::new(kind, "english string") — NEVER. Use Error::VariantName.into().
If you need a new error, add a variant to error.rs with a code, not a string.
Acceptable strings: debug/trace logging, test assertions, comments, data format strings (paths, codec IDs).
Error implements From<Error> for io::Error — use ? or .into() anywhere an io::Error is expected.

Architecture

Streams are PES. Every stream reads its format → PES frames out, or PES frames in → writes its format. One type per format.
Disc::copy() for sector dumps. disc→ISO is NOT a stream. It's Disc::copy().
DiscStream = any disc. Physical drive or ISO file. Same type, different SectorReader.
No IOStream. Deleted. No byte-level Read/Write on streams.
Streams don't know their size. Progress/file_size is a CLI concern.
One method per action. No foo_with_X variants. Use Option<T> params.
Streams impl Read only (conceptually). No Seek, no File backing.
Functions return errors, only main() exits. No process::exit in library code.

Device rules

Always use /dev/sg* not /dev/sr* for SCSI.
--raw only skips decryption. Init/probe/speed still run.
Each function does one thing. One runner orchestrates the sequence.

AACS key sources

Single source: keydb.cfg. Located at ~/.config/freemkv/keydb.cfg by default, or pointed at via ScanOptions::keydb_path. The file holds all DKs, PKs, host certs, and per-disc VUK entries. No keys are compiled into the binary.

CSS player keys (DVD) remain compiled in — they're 1999-era public inputs separate from the AACS key pipeline and have always lived in src/css/auth.rs.

The library treats a missing keydb.cfg for an AACS-encrypted disc as Error::KeydbLoad with the sentinel path <no keydb in search paths>. CLIs render this as "no KEYDB.cfg found"; consumers can disambiguate on the sentinel string.

macOS IOKit transport

The macOS SCSI transport uses exclusive IOKit access, not hybrid MMC+pread.

C shim (src/scsi/macos_shim.c):
- shim_open_exclusive(bsd_name): diskutil unmountDisk force on target device only → find IOBDServices matching BSD name via IOKit registry walk → MMCDeviceInterface → SCSITaskDeviceInterface → ObtainExclusiveAccess → raw CDB dispatch.
- shim_list_drives(): registry-based enumeration. Walks all IOBDServices entries, reads "Device Characteristics" for vendor/model/firmware, walks child chain to IOMedia for BSD name. Zero SCSI, zero exclusive access, zero unmounts.
- shim_execute() / shim_close(): raw CDB dispatch and cleanup.
Build (build.rs): compiles shim via cc into static lib, linked by Cargo. NOT the cc crate (produces object code that breaks IOKit exclusive access).
Rust (src/scsi/macos.rs): FFI to shim_open_exclusive, shim_close, shim_execute, shim_list_drives. list_drives() uses registry-based enumeration. MacScsiTransport::open() uses exclusive access only when ripping a specific device.
IOBDServices parent chain: IOSCSIPeripheralDeviceType05 → IOBDServices → IOBDBlockStorageDriver → IOMedia (has "BSD Name"). The shim walks this chain to match BSD name to IOBDServices.
IOKit lookup order: (1) iterate all IOBDServices → match child IOMedia BSD name, (2) fallback: find IOMedia by BSD name → walk parent chain to IOBDServices, (3) fallback: first IOBDServices (single-drive systems).
Test disc: DUNE_PART_TWO UHD, /dev/disk6, ~84.6 GB.

Bad-sector handling (BU40N + Initio INIC-1618L)

Three failure modes on this USB bridge:

NOT READY (sense_key=2, ASC=0x04, ASCQ=0x3E) — most common on BU40N for bad sectors. Pause 3s, retry up to 3x, then mark NonTrimmed.
Transport failure (status=0xFF) — bridge crash, auto-recovers ~15s. Aborts copy.
INCOMPATIBLE FORMAT (ASC=0x30) wedge — ALL sectors fail, requires power cycle.

Damage-jump algorithm (Pass 1 sweep)

When skip_on_error=true (multipass mode):

Read each ECC block sequentially. Track a sliding window of the last 16 ECC block results.
On error: zero-fill, mark NonTrimmed, push false to window.
On success: write data, mark Finished, push true to window. Track consecutive good count.
When ≥12% of the 16-block window are failures → jump ahead by JUMP_BASE_SECTORS (1024) × batch × multiplier sectors. For UHD encrypted ECC (batch=32) that's a 64 MiB base jump. Zero-fill the gap as NonTrimmed. Double the multiplier (64→128→256→512 MiB...) up to MAX_JUMP_MULTIPLIER=64 (4 GiB cap). Plus a separate wedge-skip path of WEDGE_JUMP_SECTORS=524288 (1 GiB) for HARDWARE_ERROR / ILLEGAL_REQUEST senses, capped at 16 consecutive wedges.
When 16 consecutive good reads → reset multiplier to 1, restore max read speed.
Only transport failures (bridge crash) abort the pass.

Tuning knobs: DAMAGE_WINDOW=16 and DAMAGE_THRESHOLD_PCT=12%. Calibrated from live BU40N data: old 50/25% was too diluted by good reads between sparse failures; 16/12% triggers on the 2nd scattered failure (2/16 = 12.5% ≥ 12%).

Patch (Pass N) — `disc/mod.rs:1910`

Default: reverse mode. Walks bad ranges from highest LBA to lowest, and within each range from end to start. Rationale: sweep jumps forward with escalating gaps, so NonTrimmed ranges have good data at their tail (where the jump landed). Reverse hits good data first, converges on actual bad block boundaries.
Single-sector reads with 60 s timeout (READ_RECOVERY_TIMEOUT_MS).
NOT_READY (sense=2, ASC ∈ {0x02, 0x03, 0x04}): 15 s pause, retry without immediate Unreadable mark.
Non-marginal SCSI sense → mark Unreadable and continue.
Skip escalation: damage window 16, PASSN_DAMAGE_THRESHOLD_PCT=6, skip PASSN_SKIP_SECTORS_BASE (32) << escalation sectors capped at PASSN_SKIP_SECTORS_CAP=4096; MAX_SKIPS_PER_RANGE=10, then mark range Unreadable.
Wedge exit: 50 consecutive failures and ≥ 2 ranges attempted (single-range stalls don't kill the pass).
Whole-pass watchdog: STALL_SECS = 3600 on bytes_good. Per-range watchdog: proportional range_sectors × SECONDS_PER_SECTOR(25), capped at RANGE_BUDGET_CAP_SECS=1800 (replaces the old flat 180s/range — tiny ranges got starved).

Constants live in disc/patch.rs::Disc::patch (PASSN_*, STALL_SECS, SECONDS_PER_SECTOR, RANGE_BUDGET_CAP_SECS, MAX_SKIPS_PER_RANGE). The full algorithm is documented in freemkv-private/memory/project_recovery_v0_16.md.

Public repo rules

No internal docs. Audit reports, test plans, roadmaps, TODOs go in freemkv-private, never here.
No Co-Authored-By in commit messages. One contributor: MattJackson.
No private references. No Gitea URLs, no /data/code paths, no internal IPs in code.

6.9 KiB Raw Permalink Blame History Unescape Escape