libfreemkv 1.1.0

Open source raw disc access library for optical drives
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! Structured resolution trace — what the unlock + key-resolution attempt did.
//!
//! No user-facing English. Every step's STATE is a typed enum variant;
//! applications RENDER these into localized text (the library never does). This
//! module only DEFINES the shape and is wired through the resolve/handshake
//! return path far enough to compile.
//!
//! The `who` of each step is the source's `label()` / unlocker's `name()` — a
//! stable identifier string (a NAME, like a codec id, NOT user-facing prose),
//! carried verbatim so an app renderer never has to match an enum back to a name
//! it already has. Only the OUTCOME / path enums are structured states the app
//! maps to i18n English.

/// The full trace of a resolution attempt: the unlock phase, then the
/// key-resolution phase.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct ResolutionTrace {
    /// One step per unlocker consulted, in consultation order.
    pub unlock: Vec<UnlockStep>,
    /// One step per key source consulted, in consultation order.
    pub keys: Vec<KeyStep>,
}

impl ResolutionTrace {
    /// An empty trace (no steps recorded).
    pub fn new() -> Self {
        Self::default()
    }
}

// ── Unlock phase ────────────────────────────────────────────────────────────

/// One unlocker's contribution to the unlock phase. `who` is the unlocker's
/// `name()` (a stable identifier, e.g. `"LibreDrive"`), carried verbatim.
#[derive(Debug, Clone, PartialEq)]
pub struct UnlockStep {
    pub who: String,
    pub outcome: UnlockOutcome,
}

/// What an unlocker did.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UnlockOutcome {
    /// The drive was unlocked (or already usable) and a VID is available.
    Unlocked,
    /// This unlocker cannot unlock this drive's firmware.
    FirmwareNotUnlockable,
    /// No non-revoked host cert was usable for the auth attempt. `mkb` is the
    /// disc MKB generation when known.
    NoUsableHostCert { mkb: Option<u32> },
    /// Every available host cert was revoked on this drive's HRL. `mkb` is the
    /// disc MKB generation when known.
    CertRevoked { mkb: Option<u32> },
    /// The drive rejected the auth handshake (non-revocation rejection / wedge).
    HandshakeRejected,
    /// Auth succeeded (or was skipped) but the Volume ID could not be read.
    VidUnavailable,
}

// ── Key-resolution phase ────────────────────────────────────────────────────

/// One key source's contribution to the key-resolution phase, including the
/// derivation path it walked. `who` is the source's `label()` (a stable
/// identifier, e.g. `"keydb"` / `"online"`), carried verbatim.
#[derive(Debug, Clone, PartialEq)]
pub struct KeyStep {
    pub who: String,
    pub path: Vec<KeyNode>,
    pub outcome: KeyOutcome,
}

/// A node on the derivation path a source walked. Ordered as encountered; not
/// every path hits every node.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeyNode {
    /// The source matched this disc (by hash / VID).
    MatchedDisc,
    /// The source had no entry for this disc.
    NoEntry,
    /// Pre-decrypted unit keys were found.
    FoundUnitKeys,
    /// A VUK was found.
    FoundVuk,
    /// A Media Key was found.
    FoundMediaKey,
    /// A VID is required to proceed.
    NeedVid,
    /// The VID came from the unlock phase.
    VidFromUnlock,
    /// The VID came from the keydb entry.
    VidFromKeydb,
    /// No VID was available.
    NoVid,
    /// A VUK was derived (from MK + VID).
    DerivedVuk,
    /// Unit keys were derived (from VUK).
    DerivedUnitKeys,
}

/// The terminal outcome of a source's resolution attempt.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeyOutcome {
    /// Usable unit keys were produced.
    Resolved,
    /// Derivation material existed but no VID was available to finish.
    MissingVid,
    /// No usable key from this source.
    NoKey,
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The trace types are constructible, derive the required traits, and an
    /// empty trace round-trips. Pins the structural contract apps build against.
    #[test]
    fn trace_is_constructible_and_comparable() {
        let t = ResolutionTrace {
            unlock: vec![UnlockStep {
                who: "AACS cert".to_string(),
                outcome: UnlockOutcome::NoUsableHostCert { mkb: Some(68) },
            }],
            keys: vec![KeyStep {
                who: "keydb".to_string(),
                path: vec![
                    KeyNode::MatchedDisc,
                    KeyNode::FoundVuk,
                    KeyNode::DerivedUnitKeys,
                ],
                outcome: KeyOutcome::Resolved,
            }],
        };
        // Clone + PartialEq (derive contract the renderers rely on).
        assert_eq!(t.clone(), t);
        // `who` is the source's name carried verbatim.
        assert_eq!(t.keys[0].who, "keydb");
        assert_eq!(t.unlock[0].who, "AACS cert");
        // Default / new is empty.
        assert_eq!(ResolutionTrace::new(), ResolutionTrace::default());
        assert!(ResolutionTrace::new().unlock.is_empty());
        assert!(ResolutionTrace::new().keys.is_empty());
    }
}