dpapi-offline 0.1.1

Pure-Rust offline Windows DPAPI decryption (DonPAPI/dploot-class): parse and decrypt user masterkey files (password/SID-derived) and DPAPI data blobs. No FFI, no live host.
Documentation
//! DPAPI data-blob (`DPAPI_BLOB`) parsing and decryption.
//!
//! A blob is what `CryptProtectData` emits — the shape stored in Credential files, Vaults,
//! browser "Login Data", etc. Given the decrypted masterkey it references (see [`crate::masterkey`]):
//!
//! 1. `sessionKey = HMAC-<hash>(masterkey, salt [+ entropy])`
//! 2. `derived    = CryptDeriveKey(sessionKey, cipher, hash)`   (ipad/opad if too short)
//! 3. `cleartext  = PKCS7-unpad(CBC-decrypt(derived[..keyLen], derived[keyLen..], data))`
//!
//! Structure and derivation follow impacket's `dpapi.py` (`DPAPI_BLOB`) — the byte-oracle.

use crate::crypto::{unpad_pkcs7, CipherAlgo, HashAlgo};
use crate::DpapiError;

fn u32le(b: &[u8], o: usize) -> Option<u32> {
    Some(u32::from_le_bytes(b.get(o..o + 4)?.try_into().ok()?))
}

/// A parsed `DPAPI_BLOB`. Only the fields decryption needs are retained.
#[derive(Debug, Clone)]
pub struct DpapiBlob {
    /// GUID of the masterkey required to decrypt this blob (match to a `MasterKeyFile`).
    pub guid_masterkey: [u8; 16],
    pub hash_algo: HashAlgo,
    pub cipher_algo: CipherAlgo,
    pub salt: Vec<u8>,
    pub data: Vec<u8>,
    pub sign: Vec<u8>,
}

impl DpapiBlob {
    /// Parse the variable-length `DPAPI_BLOB` structure.
    pub fn parse(b: &[u8]) -> Result<Self, DpapiError> {
        let err = |m: &str| DpapiError::Parse(m.into());
        // Version(4) providerGuid(16) mkVersion(4) guidMasterKey(16) flags(4) descLen(4) desc..
        let mut p = 0usize;
        let need = |p: usize, n: usize| -> Result<(), DpapiError> {
            if p + n > b.len() {
                Err(DpapiError::Parse("blob truncated".into()))
            } else {
                Ok(())
            }
        };
        need(p, 4 + 16 + 4)?;
        p += 4 + 16 + 4; // Version, providerGuid, mkVersion
        need(p, 16)?;
        let guid_masterkey: [u8; 16] = b[p..p + 16].try_into().unwrap();
        p += 16;
        need(p, 8)?;
        p += 4; // flags
        let desc_len = u32le(b, p).ok_or_else(|| err("descLen"))? as usize;
        p += 4;
        need(p, desc_len)?;
        p += desc_len; // Description

        let crypt_id = u32le(b, p).ok_or_else(|| err("cryptAlgo"))?;
        p += 4;
        p += 4; // CryptAlgoLen
        let salt_len = u32le(b, p).ok_or_else(|| err("saltLen"))? as usize;
        p += 4;
        need(p, salt_len)?;
        let salt = b[p..p + salt_len].to_vec();
        p += salt_len;

        let hmac_key_len = u32le(b, p).ok_or_else(|| err("hmacKeyLen"))? as usize;
        p += 4;
        need(p, hmac_key_len)?;
        p += hmac_key_len; // HMacKey

        let hash_id = u32le(b, p).ok_or_else(|| err("hashAlgo"))?;
        p += 4;
        p += 4; // HashAlgoLen
        let hmac2_key_len = u32le(b, p).ok_or_else(|| err("hmac2KeyLen"))? as usize;
        p += 4;
        need(p, hmac2_key_len)?;
        p += hmac2_key_len; // HMac2Key

        let data_len = u32le(b, p).ok_or_else(|| err("dataLen"))? as usize;
        p += 4;
        need(p, data_len)?;
        let data = b[p..p + data_len].to_vec();
        p += data_len;

        let sign_len = u32le(b, p).ok_or_else(|| err("signLen"))? as usize;
        p += 4;
        need(p, sign_len)?;
        let sign = b[p..p + sign_len].to_vec();

        let hash_algo = HashAlgo::from_alg_id(hash_id)
            .ok_or_else(|| DpapiError::Unsupported(format!("blob hash 0x{hash_id:04x}")))?;
        let cipher_algo = CipherAlgo::from_alg_id(crypt_id)
            .ok_or_else(|| DpapiError::Unsupported(format!("blob cipher 0x{crypt_id:04x}")))?;
        Ok(DpapiBlob {
            guid_masterkey,
            hash_algo,
            cipher_algo,
            salt,
            data,
            sign,
        })
    }

    /// Decrypt the blob with its (already-decrypted) 64-byte masterkey and optional entropy.
    pub fn decrypt(&self, masterkey: &[u8], entropy: Option<&[u8]>) -> Result<Vec<u8>, DpapiError> {
        let mut msg = self.salt.clone();
        if let Some(e) = entropy {
            msg.extend_from_slice(e);
        }
        let session_key = self.hash_algo.hmac(masterkey, &msg);
        let derived = crypt_derive_key(&session_key, self.cipher_algo, self.hash_algo);
        let key_len = self.cipher_algo.key_len();
        let iv_len = self.cipher_algo.iv_len();
        if derived.len() < key_len + iv_len {
            return Err(DpapiError::Decrypt);
        }
        let clear = self
            .cipher_algo
            .cbc_decrypt_nopad(
                &derived[..key_len],
                &derived[key_len..key_len + iv_len],
                &self.data,
            )
            .ok_or(DpapiError::Decrypt)?;
        unpad_pkcs7(&clear).ok_or(DpapiError::Decrypt)
    }
}

/// `CryptDeriveKey`: if the session key already yields enough bytes, slice it; otherwise expand
/// via the HMAC ipad/opad construction (MS-DPAPI, matching impacket's `deriveKey`).
fn crypt_derive_key(session_key: &[u8], cipher: CipherAlgo, hash: HashAlgo) -> Vec<u8> {
    let need = cipher.key_len() + cipher.iv_len();
    if session_key.len() >= need {
        return session_key[..need].to_vec();
    }
    let bs = hash.block_size();
    let mut sk = session_key.to_vec();
    if sk.len() > bs {
        sk = raw_digest(hash, &sk);
    }
    let mut ipad = vec![0x36u8; bs];
    let mut opad = vec![0x5cu8; bs];
    for (i, &b) in sk.iter().enumerate() {
        ipad[i] ^= b;
        opad[i] ^= b;
    }
    let mut out = raw_digest(hash, &ipad);
    out.extend_from_slice(&raw_digest(hash, &opad));
    out
}

fn raw_digest(hash: HashAlgo, msg: &[u8]) -> Vec<u8> {
    match hash {
        HashAlgo::Sha1 => {
            use sha1::{Digest, Sha1};
            Sha1::digest(msg).to_vec()
        }
        HashAlgo::Sha512 => {
            use sha2::{Digest, Sha512};
            Sha512::digest(msg).to_vec()
        }
    }
}

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

    // Deterministic parse test only. NOTE: does NOT validate the crypto chain — see the crate-level
    // VALIDATION STATUS. Decryption correctness needs a real blob + impacket oracle.
    #[test]
    fn parses_variable_length_fields() {
        // Build a minimal well-formed DPAPI_BLOB with SHA512/AES256, salt=8, data=16, sign=4.
        let mut b = Vec::new();
        b.extend_from_slice(&2u32.to_le_bytes()); // Version
        b.extend_from_slice(&[0x11; 16]); // providerGuid
        b.extend_from_slice(&1u32.to_le_bytes()); // mkVersion
        b.extend_from_slice(&[0x22; 16]); // guidMasterKey
        b.extend_from_slice(&0u32.to_le_bytes()); // flags
        b.extend_from_slice(&0u32.to_le_bytes()); // descLen
        b.extend_from_slice(&0x6610u32.to_le_bytes()); // CryptAlgo = AES256
        b.extend_from_slice(&256u32.to_le_bytes()); // CryptAlgoLen
        b.extend_from_slice(&8u32.to_le_bytes()); // saltLen
        b.extend_from_slice(&[0xAA; 8]); // Salt
        b.extend_from_slice(&0u32.to_le_bytes()); // HMacKeyLen
        b.extend_from_slice(&0x800eu32.to_le_bytes()); // HashAlgo = SHA512
        b.extend_from_slice(&512u32.to_le_bytes()); // HashAlgoLen
        b.extend_from_slice(&0u32.to_le_bytes()); // HMac2KeyLen
        b.extend_from_slice(&16u32.to_le_bytes()); // DataLen
        b.extend_from_slice(&[0xCC; 16]); // Data
        b.extend_from_slice(&4u32.to_le_bytes()); // SignLen
        b.extend_from_slice(&[0xDD; 4]); // Sign

        let blob = DpapiBlob::parse(&b).unwrap();
        assert_eq!(blob.guid_masterkey, [0x22; 16]);
        assert_eq!(blob.hash_algo, HashAlgo::Sha512);
        assert_eq!(blob.cipher_algo, CipherAlgo::Aes256);
        assert_eq!(blob.salt, vec![0xAA; 8]);
        assert_eq!(blob.data, vec![0xCC; 16]);
        assert_eq!(blob.sign, vec![0xDD; 4]);
    }

    #[test]
    fn truncated_blob_is_error_not_panic() {
        let full = {
            let mut b = vec![2u8, 0, 0, 0];
            b.extend_from_slice(&[0; 16 + 4 + 16 + 4 + 4]);
            b
        };
        for cut in 0..full.len() {
            let _ = DpapiBlob::parse(&full[..cut]);
        }
    }

    // CryptDeriveKey: SHA512 session key (64B) is long enough for AES256 (48B) → direct slice.
    #[test]
    fn derive_key_direct_for_sha512_aes256() {
        let sk = [0x5au8; 64];
        let d = crypt_derive_key(&sk, CipherAlgo::Aes256, HashAlgo::Sha512);
        assert_eq!(d, sk[..48].to_vec());
    }

    // SHA1 session key (20B) too short for 3DES (32B) → ipad/opad expansion to 40B.
    #[test]
    fn derive_key_expands_for_sha1_3des() {
        let sk = [0x01u8; 20];
        let d = crypt_derive_key(&sk, CipherAlgo::TripleDes, HashAlgo::Sha1);
        assert_eq!(d.len(), 40); // SHA1(ipad)=20 + SHA1(opad)=20
    }
}