1pub use dpapi_core;
14
15use std::path::PathBuf;
16
17use clap::{Parser, Subcommand};
18use serde::Serialize;
19
20use dpapi_core::{
21 decrypt_credential, decrypt_local_state_key, decrypt_v10_cookie, decrypt_vcrd_attribute,
22 decrypt_vpol_keys, decrypt_wlan_key_material, detect_chrome_cookie_encoding,
23 extract_key_material, parse_credential_file, parse_dpapi_blob, parse_internet_explorer,
24 parse_local_state_encrypted_key, parse_vcrd_attributes, parse_vpol_file, ChromeCookieEncoding,
25 DpapiError,
26};
27
28#[derive(Debug)]
30pub enum CliError {
31 Dpapi(DpapiError),
33 Io(String),
35 BadMasterKey(String),
37 Locked { store: String, mk_guid: String },
40}
41
42impl std::fmt::Display for CliError {
43 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44 match self {
45 CliError::Dpapi(e) => write!(f, "decode failed: {e}"),
46 CliError::Io(s) => write!(f, "io error: {s}"),
47 CliError::BadMasterKey(s) => write!(f, "bad master key: {s}"),
48 CliError::Locked { store, mk_guid } => write!(
49 f,
50 "{store} store present but LOCKED: no usable master key (master-key GUID {mk_guid}); supply the key for that GUID"
51 ),
52 }
53 }
54}
55
56impl std::error::Error for CliError {}
57
58impl From<DpapiError> for CliError {
59 fn from(e: DpapiError) -> Self {
60 CliError::Dpapi(e)
61 }
62}
63
64#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
66pub struct StoreResult {
67 pub store: String,
69 pub label: String,
71 pub secret: String,
73 pub account: Option<String>,
75}
76
77#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
79pub struct CliReport {
80 pub results: Vec<StoreResult>,
81}
82
83#[derive(Debug, Parser)]
85#[command(name = "dpapi4n6", version, about = "Forensic DPAPI store auditor")]
86pub struct Cli {
87 #[command(subcommand)]
88 pub command: Command,
89 #[arg(long, global = true)]
91 pub json: bool,
92}
93
94#[derive(Debug, clap::Args)]
97pub struct MasterKeyArg {
98 #[arg(long = "master-key", value_name = "HEX")]
100 pub master_key_hex: String,
101}
102
103#[derive(Debug, Subcommand)]
104pub enum Command {
105 Browser {
107 #[arg(long)]
109 local_state: PathBuf,
110 #[arg(long)]
112 cookie: Option<PathBuf>,
113 #[command(flatten)]
114 key: MasterKeyArg,
115 },
116 Credman {
118 #[arg(long)]
120 file: PathBuf,
121 #[command(flatten)]
122 key: MasterKeyArg,
123 },
124 Vault {
126 #[arg(long)]
128 vpol: PathBuf,
129 #[arg(long)]
131 vcrd: PathBuf,
132 #[command(flatten)]
133 key: MasterKeyArg,
134 },
135 Wifi {
137 #[arg(long)]
139 profile: PathBuf,
140 #[command(flatten)]
141 key: MasterKeyArg,
142 },
143}
144
145pub fn parse_master_key_hex(hex: &str) -> Result<Vec<u8>, CliError> {
147 let s = hex.strip_prefix("0x").unwrap_or(hex);
148 if s.len() % 2 != 0 {
149 return Err(CliError::BadMasterKey(format!(
150 "odd length ({} chars)",
151 s.len()
152 )));
153 }
154 let bytes = s.as_bytes();
155 let mut out = Vec::with_capacity(s.len() / 2);
156 let mut i = 0;
157 while i < bytes.len() {
158 let hi = nibble(bytes[i])?;
159 let lo = nibble(bytes[i + 1])?;
160 out.push((hi << 4) | lo);
161 i += 2;
162 }
163 Ok(out)
164}
165
166fn nibble(b: u8) -> Result<u8, CliError> {
167 match b {
168 b'0'..=b'9' => Ok(b - b'0'),
169 b'a'..=b'f' => Ok(b - b'a' + 10),
170 b'A'..=b'F' => Ok(b - b'A' + 10),
171 other => Err(CliError::BadMasterKey(format!("non-hex byte {other:#04x}"))),
172 }
173}
174
175fn locked_or_err(store: &str, blob_bytes: &[u8], e: DpapiError) -> CliError {
179 match e {
180 DpapiError::HmacMismatch
181 | DpapiError::DecryptionFailed
182 | DpapiError::DomainBackupUnsupported => {
183 let mk_guid = parse_dpapi_blob(blob_bytes).map_or_else(
184 |_| "unknown".to_string(),
185 |b| guid_to_string(&b.master_key_guid),
186 );
187 CliError::Locked {
188 store: store.to_string(),
189 mk_guid,
190 }
191 }
192 other => CliError::Dpapi(other),
193 }
194}
195
196fn guid_to_string(g: &[u8; 16]) -> String {
202 uuid::Uuid::from_bytes_le(*g).to_string()
203}
204
205pub fn decode_browser(
215 local_state_json: &str,
216 cookie_blob: Option<&[u8]>,
217 master_key: &[u8],
218) -> Result<Vec<StoreResult>, CliError> {
219 let value: serde_json::Value = serde_json::from_str(local_state_json)
220 .map_err(|e| CliError::Io(format!("Local State is not valid JSON: {e}")))?;
221 let encrypted_key_b64 = value
222 .get("os_crypt")
223 .and_then(|o| o.get("encrypted_key"))
224 .and_then(serde_json::Value::as_str)
225 .ok_or_else(|| CliError::Io("Local State has no os_crypt.encrypted_key".to_string()))?;
226
227 let key_blob = parse_local_state_encrypted_key(encrypted_key_b64.as_bytes())?;
228 let cookie_key = decrypt_local_state_key(&key_blob, master_key)
229 .map_err(|e| locked_or_err("browser", &key_blob, e))?;
230
231 let mut results = vec![StoreResult {
232 store: "browser".to_string(),
233 label: "cookie-key".to_string(),
234 secret: hex_encode(&cookie_key),
235 account: None,
236 }];
237
238 if let Some(blob) = cookie_blob {
239 let plaintext = match detect_chrome_cookie_encoding(blob) {
240 ChromeCookieEncoding::V10 { nonce, ciphertext }
241 | ChromeCookieEncoding::V20 { nonce, ciphertext } => {
242 decrypt_v10_cookie(&nonce, &ciphertext, &cookie_key)?
243 }
244 ChromeCookieEncoding::DpapiBlob(_) | ChromeCookieEncoding::Raw => {
245 return Err(CliError::Io(
246 "cookie value is not a v10/v20 AES-GCM blob".to_string(),
247 ))
248 }
249 };
250 results.push(StoreResult {
251 store: "browser".to_string(),
252 label: "cookie".to_string(),
253 secret: String::from_utf8_lossy(&plaintext).into_owned(),
254 account: None,
255 });
256 }
257 Ok(results)
258}
259
260pub fn decode_credman(file_bytes: &[u8], master_key: &[u8]) -> Result<Vec<StoreResult>, CliError> {
262 let blob = parse_credential_file(file_bytes)?;
263 let cred =
264 decrypt_credential(&blob, master_key).map_err(|e| locked_or_err("credman", &blob, e))?;
265 Ok(vec![StoreResult {
266 store: "credman".to_string(),
267 label: cred.target,
268 secret: cred.secret,
269 account: Some(cred.username),
270 }])
271}
272
273pub fn decode_vault(
275 vpol_bytes: &[u8],
276 vcrd_bytes: &[u8],
277 master_key: &[u8],
278) -> Result<Vec<StoreResult>, CliError> {
279 let vpol_blob = parse_vpol_file(vpol_bytes)?;
280 let keys = decrypt_vpol_keys(&vpol_blob, master_key)
281 .map_err(|e| locked_or_err("vault", &vpol_blob, e))?;
282
283 let attrs = parse_vcrd_attributes(vcrd_bytes)?;
284 let mut results = Vec::new();
285 for attr in &attrs {
286 let Ok(cleartext) = decrypt_vcrd_attribute(attr, &keys.key1) else {
288 continue;
289 };
290 if let Ok(cred) = parse_internet_explorer(&cleartext) {
291 results.push(StoreResult {
292 store: "vault".to_string(),
293 label: cred.resource,
294 secret: cred.password,
295 account: Some(cred.username),
296 });
297 }
298 }
299 Ok(results)
300}
301
302pub fn decode_wifi(profile_xml: &str, master_key: &[u8]) -> Result<Vec<StoreResult>, CliError> {
304 let key_material = extract_key_material(profile_xml)
305 .ok_or_else(|| CliError::Io("profile XML has no <keyMaterial>".to_string()))?;
306 let blob = hex_decode(key_material)?;
308 let psk = decrypt_wlan_key_material(key_material, master_key)
309 .map_err(|e| locked_or_err("wifi", &blob, e))?;
310 Ok(vec![StoreResult {
311 store: "wifi".to_string(),
312 label: "PSK".to_string(),
313 secret: psk,
314 account: None,
315 }])
316}
317
318impl Cli {
319 pub fn run(&self) -> Result<CliReport, CliError> {
322 let results = match &self.command {
323 Command::Browser {
324 local_state,
325 cookie,
326 key,
327 } => {
328 let mk = parse_master_key_hex(&key.master_key_hex)?;
329 let json = read_to_string(local_state)?;
330 let cookie_bytes = match cookie {
331 Some(p) => Some(read_bytes(p)?),
332 None => None,
333 };
334 decode_browser(&json, cookie_bytes.as_deref(), &mk)?
335 }
336 Command::Credman { file, key } => {
337 let mk = parse_master_key_hex(&key.master_key_hex)?;
338 decode_credman(&read_bytes(file)?, &mk)?
339 }
340 Command::Vault { vpol, vcrd, key } => {
341 let mk = parse_master_key_hex(&key.master_key_hex)?;
342 decode_vault(&read_bytes(vpol)?, &read_bytes(vcrd)?, &mk)?
343 }
344 Command::Wifi { profile, key } => {
345 let mk = parse_master_key_hex(&key.master_key_hex)?;
346 decode_wifi(&read_to_string(profile)?, &mk)?
347 }
348 };
349 Ok(CliReport { results })
350 }
351}
352
353fn read_to_string(path: &std::path::Path) -> Result<String, CliError> {
355 std::fs::read_to_string(path).map_err(|e| CliError::Io(format!("{}: {e}", path.display())))
356}
357
358fn read_bytes(path: &std::path::Path) -> Result<Vec<u8>, CliError> {
360 std::fs::read(path).map_err(|e| CliError::Io(format!("{}: {e}", path.display())))
361}
362
363fn hex_encode(bytes: &[u8]) -> String {
365 use std::fmt::Write as _;
366 let mut s = String::with_capacity(bytes.len() * 2);
367 for b in bytes {
368 let _ = write!(s, "{b:02x}");
369 }
370 s
371}
372
373fn hex_decode(s: &str) -> Result<Vec<u8>, CliError> {
375 let bytes = s.as_bytes();
376 if bytes.len() % 2 != 0 {
377 return Err(CliError::BadMasterKey(format!(
378 "odd-length hex ({} chars)",
379 bytes.len()
380 )));
381 }
382 let mut out = Vec::with_capacity(bytes.len() / 2);
383 let mut i = 0;
384 while i < bytes.len() {
385 out.push((nibble(bytes[i])? << 4) | nibble(bytes[i + 1])?);
386 i += 2;
387 }
388 Ok(out)
389}
390
391pub fn render_text(report: &CliReport) -> String {
393 use std::fmt::Write as _;
394 let mut out = String::new();
395 if report.results.is_empty() {
396 return "No secrets recovered.\n".to_string();
397 }
398 for r in &report.results {
399 let account = r.account.as_deref().unwrap_or("-");
400 let _ = writeln!(
401 out,
402 "[{}] {} | account={} | secret={}",
403 r.store, r.label, account, r.secret
404 );
405 }
406 out
407}
408
409#[cfg(test)]
410mod tests {
411 use super::*;
412
413 fn hex(s: &str) -> Vec<u8> {
414 (0..s.len())
415 .step_by(2)
416 .map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap())
417 .collect()
418 }
419
420 const MASTER_KEY_HEX: &str = "9828d9873735439e823dbd216205ff88266d28ad685a413970c640d5ee943154bbade31fada673d542c72d707a163bb3d1bceb0c50465b359ae06998481b0ce3";
422
423 const ENCRYPTED_KEY_B64: &str = "RFBBUEkBAAAA0Iyd3wEV0RGMegDAT8KX6wEAAAAz8Z9e40C+SoouK05ivQzGAAAAAAIAAAAAABBmAAAAAQAAIAAAAAARIjNEVWZ3iJmqu8zd7v8AESIzRFVmd4iZqrvM3e7/AAAAAA6AAAAAAgAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwAAAA+t/5261X1EPXoNd8+fv91ognzpGyym/1M78vdGfOMphl2Zzre4QfJx4U0fUIzjosQAAAAP5yd3Yln699MQCEn7TqSfxp/Ba+vR7Ji1pSJ7TPr7zimD/5Slev0vK6H5r6Mq46ohSMEPLzAWzKvD5xxvJt1sA=";
425 const V10_COOKIE_HEX: &str = "7631300102030405060708090a0b0c1b5af334ffe7a1fe676c5ab453c8848232ab94aa630c69bae71883958ba23e4dfe4cc5faff526ce54b";
426 const V10_PLAINTEXT: &str = "forensic-session-token-42";
427
428 const CRED_FILE_HEX: &str = "01000000b60100000000000001000000d08c9ddf0115d1118c7a00c04fc297eb0100000033f19f5ee340be4a8a2e2b4e62bd0cc600000000020000000000106600000001000020000000aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899000000000e800000000200004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0000000e2d6d8670704ca1daecd786fe94c133a68fd50708f3ed0ca7013b5e0bc5f61296b5a32b935d6b5404a2162bc26cf561cb7b45f58c7cc8d18305c9dd068860bd4f6cea89ea34db4acde8ebae4606ec1261e8006b104d96eb42975e0df1042aa1161e6c70af5530507238141080d7d7ea1f16a9609963b296143504a4af284826e1436641c74c6dc00d0b1731794887426fc4e4f4d440416c1874aaf34b6a74411d9ed966d73b6a8d05c8546329e7bb4222d2518ab8e2e7d8c47624ec64ecc8a0040000000e0585a675fef9ed63f72673bd9408684dc7fc86ad4926a76c432af933aeab68447e56860b1715cff46516cf38433a856b28a5d0653313a11664b98f2361e8cca";
430 const CRED_EXPECT_TARGET: &str = "Domain:target=TERMSRV/fileserver01";
431 const CRED_EXPECT_SECRET: &str = "S3cr3t-P@ssw0rd!";
432
433 const WIFI_KEY_MATERIAL_HEX: &str = "01000000D08C9DDF0115D1118C7A00C04FC297EB0100000033F19F5EE340BE4A8A2E2B4E62BD0CC600000000020000000000106600000001000020000000DEADBEEFCAFEBABE0011223344556677DEADBEEFCAFEBABE0011223344556677000000000E8000000002000040000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000051E2C9E20723EF48230A95FCEBBA31AF8BC567EDABBBD958F6E42E4CCE9236C240000000538815E34921B886D09A9CEAD4024E596A73C9C3B53E37A4481D05D7097751049323C613F78C8BD0D8A3AAAB8BF9FBC966E87526245734D0C781DFE0214B1D70";
435 const WIFI_EXPECT_PSK: &str = "CorrectHorseBatteryStaple";
436
437 fn local_state_json() -> String {
438 format!("{{\"os_crypt\":{{\"encrypted_key\":\"{ENCRYPTED_KEY_B64}\"}}}}")
439 }
440
441 fn wifi_xml() -> String {
442 format!("<WLANProfile><MSM><security><sharedKey><keyMaterial>{WIFI_KEY_MATERIAL_HEX}</keyMaterial></sharedKey></security></MSM></WLANProfile>")
443 }
444
445 #[test]
448 fn cli_parses_browser_subcommand() {
449 let cli = Cli::try_parse_from([
450 "dpapi4n6",
451 "browser",
452 "--local-state",
453 "/tmp/Local State",
454 "--master-key",
455 MASTER_KEY_HEX,
456 ])
457 .expect("parse");
458 assert!(matches!(cli.command, Command::Browser { .. }));
459 }
460
461 #[test]
462 fn cli_version_flag_supported() {
463 let err = Cli::try_parse_from(["dpapi4n6", "--version"]).unwrap_err();
465 assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);
466 }
467
468 #[test]
469 fn master_key_hex_parses_and_rejects_bad() {
470 assert_eq!(parse_master_key_hex("0a0b").unwrap(), vec![0x0a, 0x0b]);
471 assert_eq!(parse_master_key_hex("0x0a0b").unwrap(), vec![0x0a, 0x0b]);
472 assert!(parse_master_key_hex("0a0").is_err()); assert!(parse_master_key_hex("zz").is_err()); }
475
476 #[test]
479 fn browser_decodes_cookie_to_plaintext() {
480 let mk = hex(MASTER_KEY_HEX);
481 let results =
482 decode_browser(&local_state_json(), Some(&hex(V10_COOKIE_HEX)), &mk).expect("ok");
483 assert!(results.iter().any(|r| r.secret == V10_PLAINTEXT));
484 }
485
486 #[test]
487 fn credman_decodes_target_and_secret() {
488 let mk = hex(MASTER_KEY_HEX);
489 let results = decode_credman(&hex(CRED_FILE_HEX), &mk).expect("ok");
490 let r = &results[0];
491 assert_eq!(r.label, CRED_EXPECT_TARGET);
492 assert_eq!(r.secret, CRED_EXPECT_SECRET);
493 }
494
495 #[test]
496 fn wifi_decodes_psk() {
497 let mk = hex(MASTER_KEY_HEX);
498 let results = decode_wifi(&wifi_xml(), &mk).expect("ok");
499 assert_eq!(results[0].secret, WIFI_EXPECT_PSK);
500 }
501
502 #[test]
505 fn locked_store_reports_guid_not_a_secret() {
506 let bad_mk = [0u8; 64];
507 let err = decode_wifi(&wifi_xml(), &bad_mk).unwrap_err();
508 match err {
509 CliError::Locked { store, mk_guid } => {
510 assert_eq!(store, "wifi");
511 assert!(mk_guid.contains('-'), "GUID surfaced: {mk_guid}");
512 }
513 other => panic!("expected Locked, got {other:?}"),
514 }
515 }
516
517 #[test]
518 fn guid_to_string_renders_mixed_endian() {
519 let g = [
523 0x44, 0x33, 0x22, 0x11, 0x66, 0x55, 0x88, 0x77, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE,
524 0xFF, 0x00,
525 ];
526 assert_eq!(guid_to_string(&g), "11223344-5566-7788-99aa-bbccddeeff00");
527 }
528
529 #[test]
530 fn json_report_serializes() {
531 let report = CliReport {
532 results: vec![StoreResult {
533 store: "wifi".into(),
534 label: "PSK".into(),
535 secret: WIFI_EXPECT_PSK.into(),
536 account: None,
537 }],
538 };
539 let json = serde_json::to_string(&report).expect("json");
540 assert!(json.contains(WIFI_EXPECT_PSK));
541 }
542}