From 94ab7bc73c4979cfb5927362ebcd9dd7f83b090e Mon Sep 17 00:00:00 2001 From: MattJackson <1085847+MattJackson@users.noreply.github.com> Date: Tue, 2 Jun 2026 13:00:11 -0700 Subject: [PATCH] scan: genericize the caller-supplied unit-key docs (no external-source naming) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ScanOptions.unit_key path is a generic primitive — a caller-supplied Unit Key that bypasses keydb lookup. Doc comments + a tracing log named a specific external source; reworded to neutral 'out-of-band / external key service' so the library makes no assumptions about where the key came from. --- src/aacs/provider.rs | 2 +- src/disc/encrypt.rs | 4 ++-- src/disc/mod.rs | 30 ++++++++++++++---------------- src/mux/resolve.rs | 2 +- 4 files changed, 18 insertions(+), 20 deletions(-) diff --git a/src/aacs/provider.rs b/src/aacs/provider.rs index 5294a12..876399f 100644 --- a/src/aacs/provider.rs +++ b/src/aacs/provider.rs @@ -15,7 +15,7 @@ //! fastest/closest first. //! //! Default impls return empty / `None` so backends only override -//! the methods they actually support — an HTTP keyserver might +//! the methods they actually support — an external key service might //! implement only `lookup_disc_by_hash`, while a local file might //! implement all five. //! diff --git a/src/disc/encrypt.rs b/src/disc/encrypt.rs index 71b0715..bed5246 100644 --- a/src/disc/encrypt.rs +++ b/src/disc/encrypt.rs @@ -468,7 +468,7 @@ impl Disc { }) } - /// Resolve encryption from a caller-supplied Unit Key (the keyserver + /// Resolve encryption from a caller-supplied Unit Key (the external key service /// path). No keydb, no derivation: read `Unit_Key_RO.inf` for the disc /// hash + version/bus-encryption flags, then use `unit_key` directly as /// CPS unit 1's decryption key. The handshake (if any) still supplies the @@ -514,7 +514,7 @@ impl Disc { disc_hash = %aacs::disc_hash_hex(&dh), version, bus_encryption, - "using caller-supplied unit key (keyserver path)" + "using caller-supplied unit key" ); Ok(AacsState { diff --git a/src/disc/mod.rs b/src/disc/mod.rs index e9ce5a9..69d2f53 100644 --- a/src/disc/mod.rs +++ b/src/disc/mod.rs @@ -912,7 +912,7 @@ pub enum KeySource { /// Pre-decrypted unit keys taken directly from KEYDB by disc hash. /// No VUK present in the entry — `AacsState::vuk` is `None`. KeyDbUnitKeys, - /// Unit key supplied directly by the caller (the keyserver path). + /// Unit key supplied directly by the caller (the external Unit Key path). /// No keydb, no derivation — `AacsState::vuk` is `None`. ExternalUk, } @@ -945,12 +945,11 @@ pub struct ScanOptions { /// Path to KEYDB.cfg for AACS key lookup. /// If None, searches standard locations ($HOME/.config/aacs/ and /etc/aacs/). pub keydb_path: Option, - /// Caller-supplied Unit Key — the second, mutually-exclusive key source - /// (the online-keyserver path). When set, libfreemkv skips keydb lookup - /// and all derivation and uses this key directly to decrypt. Takes - /// precedence over `keydb_path` if both are set. The caller obtains it - /// however it likes (e.g. POSTing the disc's `Unit_Key_RO.inf` + MKB to a - /// keyserver); libfreemkv stays free of any network dependency. + /// Caller-supplied Unit Key — an alternative to keydb lookup. When set, + /// libfreemkv skips keydb lookup and all derivation and uses this key + /// directly to decrypt; it takes precedence over `keydb_path`. The caller + /// obtains the key however it likes; libfreemkv stays free of any network + /// dependency. pub unit_key: Option<[u8; 16]>, } @@ -1152,10 +1151,10 @@ impl Disc { } /// Read a disc's AACS key-input files from an ISO image: returns - /// `(Unit_Key_RO.inf, MKB)` raw bytes. For callers that resolve keys - /// out-of-band (the keyserver path) — POST these to the keyserver, get the - /// Unit Key, then scan with `ScanOptions { unit_key: Some(uk), .. }`. - /// libfreemkv itself never makes the network call. + /// `(Unit_Key_RO.inf, MKB)` raw bytes. For callers that resolve a Unit Key + /// out-of-band: obtain the key however you like, then scan with + /// `ScanOptions { unit_key: Some(uk), .. }`. libfreemkv never makes a + /// network call. pub fn read_aacs_inputs(iso_path: &std::path::Path) -> Result<(Vec, Vec)> { let mut reader = crate::io::file_sector_source::FileSectorSource::open(iso_path) .map_err(|_| Error::AacsNoKeys)?; @@ -1171,10 +1170,9 @@ impl Disc { Ok((inf, mkb)) } - /// Same as [`Disc::read_aacs_inputs`] but reads from a live drive. Keys are - /// needed *during* scan and the ISO only exists post-rip, so the keyserver - /// path fetches the disc's key files from the live drive before - /// [`Disc::scan`], POSTs them, then scans with + /// Same as [`Disc::read_aacs_inputs`] but reads from a live drive. The + /// out-of-band Unit Key path fetches the disc's key files from the drive, + /// resolves a key from them however it likes, then scans with /// `ScanOptions { unit_key: Some(uk), .. }`. These files are plaintext UDF /// metadata — no AACS handshake or keys are required to read them. pub fn read_aacs_inputs_from_drive(drive: &mut Drive) -> Result<(Vec, Vec)> { @@ -1213,7 +1211,7 @@ impl Disc { (None, None) } else if let Some(unit_key) = opts.unit_key { // Second key source: caller supplied the Unit Key directly - // (keyserver path). Skip keydb entirely. + // (external Unit Key). Skip keydb entirely. match Self::resolve_encryption_static(&udf_fs, reader, unit_key, handshake.as_ref()) { Ok(state) => (Some(state), None), Err(e) => (None, Some(e)), diff --git a/src/mux/resolve.rs b/src/mux/resolve.rs index 2601938..b9031a6 100644 --- a/src/mux/resolve.rs +++ b/src/mux/resolve.rs @@ -163,7 +163,7 @@ fn validate_network_addr(addr: &str) -> io::Result<()> { #[derive(Default)] pub struct InputOptions { pub keydb_path: Option, - /// Caller-supplied Unit Key (keyserver path) — the second, mutually + /// Caller-supplied Unit Key (external Unit Key) — the second, mutually /// exclusive key source. Takes precedence over `keydb_path`. pub unit_key: Option<[u8; 16]>, pub title_index: Option,