mirror of
https://github.com/freemkv/libfreemkv.git
synced 2026-10-07 18:13:10 +00:00
Matthew Jackson
6e14fc0c0c
Security - Remove the unsafe Vec::set_len over recycled sector buffers — UB reachable from safe code (GHSA-j8ww-f5fg-9pmh, low). Uses Vec::resize; pooling unchanged. CI / tooling - clippy on stable with the MSRV single-sourced from Cargo.toml; cargo-deny dependency-audit gate with first-party git sources allowed (#15); audience-based comment-guard (#17). Docs - README (keydb ownership, BD-J parser count), drive-access transport/reset notes, mux timeline module-doc links.
54 lines
2.2 KiB
Markdown
54 lines
2.2 KiB
Markdown
# libfreemkv Crate Overview
|
|
|
|
Overflow detail for the `src/lib.rs` crate-level doc comment, which is capped
|
|
by `ci/comment-guard.py`. Pointed to by the `//!` header there.
|
|
|
|
## Unlocking
|
|
|
|
Unlocking -- removing bus encryption (firmware unlock, AACS cert handshake,
|
|
CSS bus-auth) -- lives entirely in the `freemkv-unlock` crate; libfreemkv
|
|
consumes it privately and exposes none of it, so clients are oblivious to
|
|
unlockers (just as they are to the SCSI layer).
|
|
|
|
## Why a live `disc://` can't go through `input()`
|
|
|
|
A live `disc://` cannot be opened via [`input`] -- it returns
|
|
[`Error::DiscUrlNotDirect`] by design (use `Drive` + `Disc::scan` +
|
|
`DiscStream::new` directly for a live drive). Any file-backed source
|
|
(`iso://`, `m2ts://`) opens through [`input`].
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
Drive -- open, identify, unlock, read sectors
|
|
├── ScsiTransport -- SG_IO (Linux), IOKit (macOS)
|
|
├── DriveId -- INQUIRY + GET_CONFIG identification
|
|
└── unlock_bridge -- private seam to the `freemkv-unlock` crate
|
|
(firmware / AACS cert / CSS bus-auth unlockers)
|
|
|
|
Disc -- scan titles, streams, AACS state
|
|
├── UDF reader -- Blu-ray UDF 2.50 with metadata partitions
|
|
├── MPLS parser -- playlists → titles + clips + STN streams
|
|
├── CLPI parser -- clip info → EP map → sector extents
|
|
├── JAR parser -- BD-J audio track labels
|
|
└── AACS -- encryption: key resolution + content decrypt
|
|
├── aacs -- KEYDB, VUK, MKB, unit decrypt
|
|
└── host_certs -- collect host certs (cert handshake lives in freemkv-unlock)
|
|
```
|
|
|
|
See also `docs/architecture.md` for the fuller design-level writeup.
|
|
|
|
## AACS Encryption
|
|
|
|
Disc scanning automatically detects and handles AACS encryption.
|
|
If a KEYDB.cfg is available (via `ScanOptions` or standard paths),
|
|
the library resolves keys and decrypts content transparently.
|
|
|
|
Supports AACS 1.0 (Blu-ray) and AACS 2.0 (UHD, with fallback).
|
|
|
|
## Error Codes
|
|
|
|
All errors are structured with numeric codes. No user-facing English
|
|
text -- applications format their own messages. See `docs/error-codes.md`
|
|
for the full range table.
|