Skip to main content

dpapi_offline/
masterkey.rs

1//! DPAPI user **masterkey file** parsing and decryption.
2//!
3//! On disk at `%APPDATA%\Microsoft\Protect\<SID>\<GUID>`. The file wraps an encrypted 64-byte
4//! masterkey; recovering it from the user's password + SID follows MS-DPAPI (structures and the
5//! derivation match impacket's `dpapi.py`, the intended byte-oracle for validation):
6//!
7//! 1. `pwdhash  = SHA1(UTF16LE(password))`                    (local/standalone user)
8//! 2. `pwdkey   = HMAC-SHA1(pwdhash, UTF16LE(SID + "\0"))`
9//! 3. `derived  = PBKDF2(HMAC-<hash>, pwdkey, salt, rounds, keyLen+ivLen)`
10//! 4. `cleartext = CBC-decrypt(derived[..keyLen], derived[keyLen..], encryptedKey)`  (no padding)
11//! 5. verify: `HMAC(HMAC(pwdkey, hmacSalt), masterkey) == storedHmac`; masterkey = last 64 bytes.
12
13use crate::crypto::{CipherAlgo, HashAlgo};
14use crate::DpapiError;
15
16fn u32le(b: &[u8], o: usize) -> Option<u32> {
17    Some(u32::from_le_bytes(b.get(o..o + 4)?.try_into().ok()?))
18}
19fn u64le(b: &[u8], o: usize) -> Option<u64> {
20    Some(u64::from_le_bytes(b.get(o..o + 8)?.try_into().ok()?))
21}
22
23/// The parsed masterkey-file header plus the embedded encrypted masterkey.
24#[derive(Debug, Clone)]
25pub struct MasterKeyFile {
26    /// The `{guid}` this file is named after (identifies which key a blob needs).
27    pub guid: String,
28    /// The encrypted masterkey subfield, if present (MasterKeyLen > 0).
29    pub master_key: Option<MasterKey>,
30}
31
32impl MasterKeyFile {
33    /// Parse the 128-byte header + subfields. Only the MasterKey subfield is decoded;
34    /// BackupKey/CredHist/DomainKey are skipped.
35    ///
36    /// Header layout (verified byte-for-byte against real Windows Server 2025 masterkey
37    /// files at `C:\Users\<u>\AppData\Roaming\Microsoft\Protect\<SID>\<GUID>`):
38    /// ```text
39    ///   0..4    Version   (u32 = 2 on modern Windows)
40    ///   4..8    Unk1
41    ///   8..12   Unk2
42    ///  12..84   Guid      (72 bytes UTF-16LE, the file's own {guid} name)
43    ///  84..88   Unk3
44    ///  88..92   Policy
45    ///  92..96   Flags     (u32 — impacket had this as u64 in older versions; MODERN is u32)
46    ///  96..104  MasterKeyLen  (u64)
47    /// 104..112  BackupKeyLen  (u64)
48    /// 112..120  CredHistLen   (u64)
49    /// 120..128  DomainKeyLen  (u64)
50    /// 128..     [ MasterKey ][ BackupKey ][ CredHist ][ DomainKey ]  concatenated
51    /// ```
52    pub fn parse(data: &[u8]) -> Result<Self, DpapiError> {
53        if data.len() < 128 {
54            return Err(DpapiError::Parse("masterkey file too short".into()));
55        }
56        // Guid: 72 bytes UTF-16LE at offset 12.
57        let guid_units: Vec<u16> = data[12..12 + 72]
58            .chunks_exact(2)
59            .map(|c| u16::from_le_bytes([c[0], c[1]]))
60            .collect();
61        let guid = String::from_utf16_lossy(&guid_units)
62            .trim_end_matches('\0')
63            .to_string();
64        let mk_len = u64le(data, 96).ok_or_else(|| DpapiError::Parse("mk len".into()))? as usize;
65        let master_key = if mk_len > 0 {
66            let start = 128usize;
67            let end = start
68                .checked_add(mk_len)
69                .filter(|&e| e <= data.len())
70                .ok_or_else(|| DpapiError::Parse("mk subfield out of bounds".into()))?;
71            Some(MasterKey::parse(&data[start..end])?)
72        } else {
73            None
74        };
75        Ok(MasterKeyFile { guid, master_key })
76    }
77}
78
79/// The encrypted masterkey subfield: Version(4) Salt(16) Rounds(4) HashAlgo(4) CryptAlgo(4) data.
80#[derive(Debug, Clone)]
81pub struct MasterKey {
82    pub salt: [u8; 16],
83    pub rounds: u32,
84    pub hash_algo: HashAlgo,
85    pub cipher_algo: CipherAlgo,
86    pub ciphertext: Vec<u8>,
87}
88
89impl MasterKey {
90    pub fn parse(data: &[u8]) -> Result<Self, DpapiError> {
91        if data.len() < 32 {
92            return Err(DpapiError::Parse("masterkey subfield too short".into()));
93        }
94        let salt: [u8; 16] = data[4..20].try_into().unwrap();
95        let rounds = u32le(data, 20).unwrap();
96        let hash_id = u32le(data, 24).unwrap();
97        let crypt_id = u32le(data, 28).unwrap();
98        let hash_algo = HashAlgo::from_alg_id(hash_id)
99            .ok_or_else(|| DpapiError::Unsupported(format!("hash alg 0x{hash_id:04x}")))?;
100        let cipher_algo = CipherAlgo::from_alg_id(crypt_id)
101            .ok_or_else(|| DpapiError::Unsupported(format!("cipher alg 0x{crypt_id:04x}")))?;
102        Ok(MasterKey {
103            salt,
104            rounds,
105            hash_algo,
106            cipher_algo,
107            ciphertext: data[32..].to_vec(),
108        })
109    }
110
111    /// Decrypt with an already-derived key (`HMAC-SHA1(SHA1(pw), SID)`, MD4-derived, or the
112    /// Protected-Users PBKDF2-SHA256 equivalent). Returns the 64-byte masterkey on success;
113    /// verifies the trailing HMAC. Uses [`crate::crypto::ms_derive_key`] (MS-DPAPI variant),
114    /// **not** RFC 8018 PBKDF2 — standard PBKDF2 fails HMAC verification on every real
115    /// Windows masterkey.
116    pub fn decrypt_with_key(&self, pwdkey: &[u8]) -> Result<[u8; 64], DpapiError> {
117        let key_len = self.cipher_algo.key_len();
118        let iv_len = self.cipher_algo.iv_len();
119        let derived = crate::crypto::ms_derive_key(
120            self.hash_algo,
121            pwdkey,
122            &self.salt,
123            self.rounds,
124            key_len + iv_len,
125        );
126        let clear = self
127            .cipher_algo
128            .cbc_decrypt_nopad(&derived[..key_len], &derived[key_len..], &self.ciphertext)
129            .ok_or(DpapiError::Decrypt)?;
130
131        // cleartext = hmacSalt(16) || storedHmac(digestLen) || ... || masterkey(64)
132        let dlen = self.hash_algo.digest_len();
133        if clear.len() < 16 + dlen + 64 {
134            return Err(DpapiError::Decrypt);
135        }
136        let hmac_salt = &clear[..16];
137        let stored = &clear[16..16 + dlen];
138        let masterkey: [u8; 64] = clear[clear.len() - 64..].try_into().unwrap();
139
140        let hmac1 = self.hash_algo.hmac(pwdkey, hmac_salt);
141        let computed = self.hash_algo.hmac(&hmac1, &masterkey);
142        if computed == stored {
143            Ok(masterkey)
144        } else {
145            Err(DpapiError::HmacMismatch)
146        }
147    }
148
149    /// Decrypt a local/standalone user's masterkey from their cleartext password + SID string
150    /// (e.g. `S-1-5-21-…-1001`).
151    pub fn decrypt_with_password(&self, password: &str, sid: &str) -> Result<[u8; 64], DpapiError> {
152        let pwdkey = derive_local_prekey(password, sid);
153        self.decrypt_with_key(&pwdkey)
154    }
155}
156
157/// `HMAC-SHA1(SHA1(UTF16LE(password)), UTF16LE(SID + "\0"))` — the local-user pre-key
158/// (standalone / non-domain-joined). Matches impacket `deriveKeysFromUser` `key1`.
159pub fn derive_local_prekey(password: &str, sid: &str) -> [u8; 20] {
160    use sha1::{Digest, Sha1};
161    let pw16: Vec<u8> = password.encode_utf16().flat_map(u16::to_le_bytes).collect();
162    let pwdhash = Sha1::digest(&pw16);
163    let mut sid16: Vec<u8> = sid.encode_utf16().flat_map(u16::to_le_bytes).collect();
164    sid16.extend_from_slice(&[0, 0]); // trailing NUL, UTF-16LE
165    crate::crypto::hmac_sha1(&pwdhash, &sid16)
166}
167
168/// `HMAC-SHA1(MD4(UTF16LE(password)), UTF16LE(SID + "\0"))` — the domain-user pre-key on
169/// pre-Server 2019 accounts (uses the NT-hash as the inner secret). Matches impacket's
170/// `deriveKeysFromUser` `key2`.
171pub fn derive_domain_prekey_md4(password: &str, sid: &str) -> [u8; 20] {
172    let pw16: Vec<u8> = password.encode_utf16().flat_map(u16::to_le_bytes).collect();
173    let nt = crate::crypto::md4(&pw16);
174    let mut sid16: Vec<u8> = sid.encode_utf16().flat_map(u16::to_le_bytes).collect();
175    sid16.extend_from_slice(&[0, 0]);
176    crate::crypto::hmac_sha1(&nt, &sid16)
177}
178
179/// Protected-Users pre-key: two-stage PBKDF2-SHA256 hardening of the NT-hash + SID, then
180/// HMAC-SHA1 with the SID+"\0" to produce the final 20-byte pwdkey.
181///
182/// ```text
183///   nt      = MD4(UTF16LE(password))
184///   tmp1    = PBKDF2-SHA256(nt,   UTF16LE(SID), 10000, dklen=32)
185///   tmp2    = PBKDF2-SHA256(tmp1, UTF16LE(SID),     1, dklen=32)[..16]
186///   pwdkey  = HMAC-SHA1(tmp2, UTF16LE(SID + "\0"))[..20]
187/// ```
188///
189/// This is what modern Server 2019+ accounts (and every account explicitly in the
190/// **Protected Users** group) use for their DPAPI pwdkey — the plain MD4 path
191/// [`derive_domain_prekey_md4`] returns 20 bytes that will fail HMAC verification against
192/// their masterkeys. Matches impacket `deriveKeysFromUser` `key3`.
193pub fn derive_domain_prekey_protected(password: &str, sid: &str) -> [u8; 20] {
194    let pw16: Vec<u8> = password.encode_utf16().flat_map(u16::to_le_bytes).collect();
195    let nt = crate::crypto::md4(&pw16);
196    let sid16: Vec<u8> = sid.encode_utf16().flat_map(u16::to_le_bytes).collect();
197    let tmp1 = crate::crypto::pbkdf2_sha256(&nt, &sid16, 10000, 32);
198    let tmp2 = crate::crypto::pbkdf2_sha256(&tmp1, &sid16, 1, 32);
199    let mut sid16_nul: Vec<u8> = sid.encode_utf16().flat_map(u16::to_le_bytes).collect();
200    sid16_nul.extend_from_slice(&[0, 0]);
201    crate::crypto::hmac_sha1(&tmp2[..16], &sid16_nul)
202}
203
204#[cfg(test)]
205mod tests {
206    use super::*;
207
208    fn hex(b: &[u8]) -> String {
209        b.iter().fold(String::with_capacity(b.len() * 2), |mut s, x| {
210            use std::fmt::Write;
211            write!(s, "{x:02x}").unwrap();
212            s
213        })
214    }
215
216    fn hex_decode(s: &str) -> Vec<u8> {
217        (0..s.len())
218            .step_by(2)
219            .map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap())
220            .collect()
221    }
222
223    // ---------- End-to-end KAT with SYNTHETIC inputs -----------------------
224    //
225    // 0.1.1 embedded a KAT lifted from a real Server 2025 Administrator
226    // masterkey (real password, real SID, real ciphertext). That publish
227    // leaked lab credential-derived material to crates.io and was yanked.
228    // 0.1.2 replaces it with SYNTHETIC inputs generated deterministically by
229    // `docs/synthetic_kat.py` — throwaway password, obviously-fake SID,
230    // deterministic salt / plaintext / hmac_salt. The oracle is still the
231    // same impacket-style algorithm (MS-DPAPI PBKDF2 variant + AES256-CBC +
232    // HMAC), so a byte-level regression in `ms_derive_key` / the parser /
233    // the HMAC-verify still trips this test — but the KAT itself doesn't
234    // carry any real user's credentials.
235    //
236    // Regenerate by running `python3 docs/synthetic_kat.py` and pasting the
237    // output. Everything below is deterministic; the same inputs → the same
238    // bytes on every run.
239    const KAT_MK_SUBFIELD: [u8; 176] = [
240        0x02, 0x00, 0x00, 0x00, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a,
241        0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x40, 0x1f, 0x00, 0x00, 0x0e, 0x80, 0x00, 0x00, 0x10, 0x66,
242        0x00, 0x00, 0xc6, 0x29, 0x59, 0x58, 0xdb, 0x97, 0x1f, 0xe7, 0x63, 0x89, 0x60, 0x79, 0x12,
243        0xc2, 0x57, 0x8e, 0x1f, 0xa2, 0x8b, 0x02, 0xe7, 0x99, 0x97, 0x63, 0x85, 0xe7, 0x93, 0x37,
244        0xbd, 0xf4, 0x14, 0xd4, 0x08, 0x0c, 0x00, 0x70, 0xc9, 0xc3, 0x1d, 0x67, 0x5c, 0x71, 0xcb,
245        0x3f, 0x83, 0xfe, 0xb2, 0x20, 0x73, 0x85, 0xae, 0x04, 0x9c, 0x3a, 0xd1, 0x4a, 0x47, 0x4c,
246        0x97, 0xf6, 0xf2, 0x24, 0x1a, 0x92, 0xd6, 0xae, 0xf7, 0xcf, 0x58, 0xb1, 0x25, 0xf2, 0x2a,
247        0x34, 0xf8, 0xe9, 0x5b, 0x65, 0xb7, 0xaa, 0x63, 0xdf, 0x37, 0x5c, 0xd0, 0xed, 0x5d, 0x59,
248        0xa6, 0x11, 0x1f, 0x24, 0xa5, 0xd8, 0xf5, 0xde, 0xdf, 0xca, 0x4f, 0x88, 0x7b, 0x19, 0x45,
249        0xb3, 0xf5, 0x32, 0x38, 0xb9, 0xa0, 0x0e, 0xcc, 0xae, 0x0a, 0x2b, 0x8f, 0x06, 0x9a, 0xf3,
250        0x30, 0xc4, 0x7c, 0x3e, 0xbc, 0xcb, 0x44, 0x57, 0x75, 0xe1, 0xfd, 0xc3, 0x11, 0x95, 0xc7,
251        0xdf, 0xb8, 0x09, 0xd6, 0xbc, 0xed, 0xf3, 0x73, 0xbf, 0xa9, 0x99,
252    ];
253    const KAT_PASSWORD: &str = "SyntheticTestPassword-DoNotUse-2026";
254    const KAT_SID: &str = "S-1-5-21-1111111111-2222222222-3333333333-1000";
255    const KAT_PWDKEY_PROTECTED: &str = "e71d3b00909db78ad315f60171cf4f0873ecb9fe";
256    // Deterministic plaintext MK = 0xAA repeated 64 times.
257    const KAT_MASTERKEY: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
258
259    #[test]
260    fn derive_domain_prekey_protected_matches_impacket_synthetic() {
261        // Cross-check the Protected-Users pre-key derivation against the same
262        // synthetic (password, SID) computed by docs/synthetic_kat.py.
263        assert_eq!(
264            hex(&derive_domain_prekey_protected(KAT_PASSWORD, KAT_SID)),
265            KAT_PWDKEY_PROTECTED
266        );
267    }
268
269    #[test]
270    fn decrypt_with_key_end_to_end_synthetic() {
271        let mk = MasterKey::parse(&KAT_MK_SUBFIELD).expect("parse mk subfield");
272        let pwdkey = hex_decode(KAT_PWDKEY_PROTECTED);
273        let out = mk.decrypt_with_key(&pwdkey).expect("decrypt with key");
274        assert_eq!(hex(&out), KAT_MASTERKEY);
275    }
276
277    #[test]
278    fn unlock_masterkey_end_to_end_synthetic() {
279        // Full public API: parses the raw file, tries all three pre-key
280        // derivations, returns the plaintext MK.
281        let mut file = vec![0u8; 128];
282        // Header: MasterKeyLen = KAT_MK_SUBFIELD.len() at offset 96.
283        file[96..104].copy_from_slice(&(KAT_MK_SUBFIELD.len() as u64).to_le_bytes());
284        file.extend_from_slice(&KAT_MK_SUBFIELD);
285        let out = crate::unlock_masterkey(&file, KAT_PASSWORD, KAT_SID).expect("unlock synthetic MK");
286        assert_eq!(hex(&out), KAT_MASTERKEY);
287    }
288
289    // Structure/parse tests (deterministic). NOTE: these do NOT validate the crypto chain — see
290    // the crate-level VALIDATION STATUS. A real masterkey + impacket oracle is required for that.
291    #[test]
292    fn parses_header_guid_and_subfield_lengths() {
293        let mut f = vec![0u8; 128];
294        f[0] = 2; // Version
295        let guid = "{DEADBEEF-0000-0000-0000-000000000000}";
296        let g16: Vec<u8> = guid.encode_utf16().flat_map(u16::to_le_bytes).collect();
297        f[12..12 + g16.len()].copy_from_slice(&g16);
298        // MasterKeyLen (offset 96) = 32-byte header + 16-byte ciphertext.
299        f[96..104].copy_from_slice(&48u64.to_le_bytes());
300        // Append a MasterKey subfield: Version, Salt, Rounds, HashAlgo=SHA512, CryptAlgo=AES256, 16 ct.
301        let mut mk = vec![0u8; 32];
302        mk[0] = 2;
303        mk[20..24].copy_from_slice(&8000u32.to_le_bytes());
304        mk[24..28].copy_from_slice(&0x800eu32.to_le_bytes()); // SHA512
305        mk[28..32].copy_from_slice(&0x6610u32.to_le_bytes()); // AES256
306        mk.extend_from_slice(&[0xAB; 16]);
307        f.extend_from_slice(&mk);
308
309        let parsed = MasterKeyFile::parse(&f).unwrap();
310        assert!(parsed.guid.starts_with("{DEADBEEF"));
311        let k = parsed.master_key.unwrap();
312        assert_eq!(k.rounds, 8000);
313        assert_eq!(k.hash_algo, HashAlgo::Sha512);
314        assert_eq!(k.cipher_algo, CipherAlgo::Aes256);
315        assert_eq!(k.ciphertext, vec![0xAB; 16]);
316    }
317
318    #[test]
319    fn prekey_is_deterministic_and_20_bytes() {
320        let a = derive_local_prekey("Passw0rd!", "S-1-5-21-1-2-3-1001");
321        let b = derive_local_prekey("Passw0rd!", "S-1-5-21-1-2-3-1001");
322        assert_eq!(a, b);
323        assert_ne!(a, derive_local_prekey("Passw0rd!", "S-1-5-21-1-2-3-1002"));
324    }
325
326    #[test]
327    fn rejects_short_and_bad_alg() {
328        assert!(MasterKeyFile::parse(&[0u8; 10]).is_err());
329        let mut mk = vec![0u8; 32];
330        mk[24..28].copy_from_slice(&0xDEADu32.to_le_bytes()); // bogus hash alg
331        assert!(matches!(
332            MasterKey::parse(&mk),
333            Err(DpapiError::Unsupported(_))
334        ));
335    }
336}