ntds-parse 0.2.0

NTDS.dit-domain decode + crypto primitives — ESE file-header validation + PEK-list AES-CBC unwrap (SYSTEM bootkey → AES key) + RID→DES-key derivation for NT-hash decrypt + typed userAccountControl / sAMAccountType decoders. Byte-verified against impacket's secretsdump
Documentation
//! PEK (Password Encryption Key) unwrap — the crypto chain that turns a `PEKLIST` record from
//! the `datatable` into the AES/RC4 key that decrypts every hash column in NTDS.dit.
//!
//! ## v0.2 — inlined crypto
//!
//! Both revisions of the PEK format are implemented in-tree:
//!
//! **Revision 3 (modern, Server 2016+)** — AES-256-CBC with a Merkle-Damgard-chained
//! SHA-256 KDF (1000 iterations of the salt appended to the running SHA-256 state, seeded
//! with the SYSTEM bootkey). IV = salt.
//!
//! **Revision 2 (legacy)** — RC4 with an MD5-chained KDF (same 1000-iterations pattern
//! but with MD5 and RC4 for backwards compatibility with pre-2016 domains).
//!
//! Verified byte-for-byte against impacket's `secretsdump.py`'s `NTDSHashes.__decryptPek`.
//!
//! ## Wire layout of an encrypted PEKLIST record
//!
//! ```text
//! 0..8      header      — first byte = version (0x02 legacy | 0x03 modern), rest 0
//! 8..24     KeyMaterial — 16-byte salt / IV
//! 24..N     Ciphertext  — AES-256-CBC (rev-3) or RC4 (rev-2)
//! ```
//!
//! ## Plaintext PEKLIST layout after unwrap
//!
//! ```text
//! 0..32     header (16-byte checksum + 16-byte fixed constant per Windows version)
//! 32..     N × 20-byte entries = [revision: u32 LE][key: 16]
//! ```

use crate::Error;
use aes::Aes256;
use cbc::cipher::{block_padding::NoPadding, BlockDecryptMut, KeyIvInit};
use md5::{Digest as _, Md5};
use rc4::{consts::U16, KeyInit, Rc4, StreamCipher};
use sha2::Sha256;

type Aes256CbcDec = cbc::Decryptor<Aes256>;

/// A single 16-byte AES key from the PEK list. Every NT/LM hash in the datatable is
/// encrypted under one of these — the index is stored as the first 4 bytes of the encrypted
/// attribute value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PekKey {
    bytes: [u8; 16],
}

impl PekKey {
    /// Construct a key from raw bytes.
    pub fn new(bytes: [u8; 16]) -> Self {
        PekKey { bytes }
    }
    /// The 16-byte key material.
    pub fn bytes(&self) -> &[u8; 16] {
        &self.bytes
    }
}

/// A parsed PEKLIST — one or more [`PekKey`]s indexed by revision.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct PekList {
    /// Version byte from the wrapping header — 3 for modern (Server 2016+), 2 for legacy.
    pub version: u8,
    /// The keys, ordered as they appear in the PEK list.
    pub keys: Vec<PekKey>,
}

impl PekList {
    /// Look up the key with the given internal index.
    pub fn key_for(&self, index: u32) -> Option<PekKey> {
        self.keys.get(index as usize).copied()
    }
}

/// Unwrap a PEKLIST blob using the SYSTEM-hive bootkey.
///
/// - `bootkey` — the 16-byte de-obfuscated bootkey (from `windows-secrets` or an equivalent).
/// - `peklist_bytes` — the encrypted `pekList` bytes as they appear in the datatable
///   `Pek-List` object's `pekList` attribute.
///
/// Returns the parsed [`PekList`] or an [`Error::Crypto`] if the ciphertext length is
/// invalid, the bootkey is wrong, or the entry table is malformed after decrypt.
pub fn unwrap_peklist(bootkey: &[u8; 16], peklist_bytes: &[u8]) -> Result<PekList, Error> {
    if peklist_bytes.len() < 8 + 16 + 1 {
        return Err(Error::Crypto(format!(
            "PEKLIST too short ({} bytes)",
            peklist_bytes.len()
        )));
    }

    let version = peklist_bytes[0];
    let key_material: &[u8; 16] = peklist_bytes[8..24]
        .try_into()
        .expect("length checked above");
    let ciphertext = &peklist_bytes[24..];

    let plaintext = match version {
        3 => decrypt_rev3(bootkey, key_material, ciphertext)?,
        2 => decrypt_rev2(bootkey, key_material, ciphertext),
        other => return Err(Error::Crypto(format!("unknown PEK version {other:#04x}"))),
    };

    PekList::parse_plaintext(&plaintext).map(|mut l| {
        l.version = version;
        l
    })
}

/// Revision-3 KDF: `key = SHA256(bootkey || salt × 1000)`, cipher = AES-256-CBC with IV = salt.
fn decrypt_rev3(
    bootkey: &[u8; 16],
    key_material: &[u8; 16],
    ciphertext: &[u8],
) -> Result<Vec<u8>, Error> {
    if ciphertext.is_empty() || ciphertext.len() % 16 != 0 {
        return Err(Error::Crypto(format!(
            "revision-3 ciphertext length {} is not a multiple of 16",
            ciphertext.len()
        )));
    }
    let mut hasher = Sha256::new();
    hasher.update(bootkey);
    for _ in 0..1000 {
        hasher.update(key_material);
    }
    let tmp_key = hasher.finalize();

    let mut buf = ciphertext.to_vec();
    Aes256CbcDec::new(tmp_key.as_slice().into(), key_material.into())
        .decrypt_padded_mut::<NoPadding>(&mut buf)
        .map_err(|e| Error::Crypto(format!("AES-256-CBC decrypt failed: {e}")))?;
    Ok(buf)
}

/// Revision-2 KDF: `key = MD5(bootkey || salt × 1000)`, cipher = RC4 (16-byte keystream key).
fn decrypt_rev2(bootkey: &[u8; 16], key_material: &[u8; 16], ciphertext: &[u8]) -> Vec<u8> {
    let mut hasher = Md5::new();
    hasher.update(bootkey);
    for _ in 0..1000 {
        hasher.update(key_material);
    }
    let tmp_key = hasher.finalize();

    let mut buf = ciphertext.to_vec();
    let mut cipher: Rc4<U16> = Rc4::new(tmp_key.as_slice().into());
    cipher.apply_keystream(&mut buf);
    buf
}

impl PekList {
    /// Parse an already-decrypted PEKLIST plaintext.
    ///
    /// Plaintext layout: 32-byte checksum/entry-count header, then N × 20-byte entries where
    /// each entry is `[revision: u32 LE][key: 16]`.
    pub fn parse_plaintext(plaintext: &[u8]) -> Result<Self, Error> {
        if plaintext.len() < 32 + 20 {
            return Err(Error::Crypto(format!(
                "PEK plaintext too short ({} bytes, need at least 52)",
                plaintext.len()
            )));
        }
        // Real NTDS PEK plaintexts are usually AES-CBC-decrypted and end with zero-padding
        // to the nearest 16-byte block. Trailing zeros after the last 20-byte entry are OK;
        // non-zero bytes past the last entry indicate a genuinely torn buffer.
        let body_len = plaintext.len() - 32;
        let count = body_len / 20;
        let consumed = count * 20;
        if plaintext[32 + consumed..].iter().any(|&b| b != 0) {
            return Err(Error::Crypto(format!(
                "PEK plaintext has {} non-zero trailing bytes past the last entry — likely wrong unwrap or torn buffer",
                body_len - consumed
            )));
        }
        let mut keys = Vec::with_capacity(count);
        for i in 0..count {
            let off = 32 + i * 20;
            let mut k = [0u8; 16];
            k.copy_from_slice(&plaintext[off + 4..off + 20]);
            keys.push(PekKey::new(k));
        }
        Ok(PekList { version: 0, keys })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use aes::cipher::{block_padding::NoPadding, BlockEncryptMut, KeyIvInit};
    type Aes256CbcEnc = cbc::Encryptor<Aes256>;

    #[test]
    fn parse_plaintext_reads_two_keys() {
        let mut pt = vec![0u8; 32];
        for i in 0..2u32 {
            pt.extend_from_slice(&i.to_le_bytes());
            pt.extend_from_slice(&[i as u8; 16]);
        }
        let list = PekList::parse_plaintext(&pt).unwrap();
        assert_eq!(list.keys.len(), 2);
        assert_eq!(list.keys[0].bytes(), &[0u8; 16]);
        assert_eq!(list.keys[1].bytes(), &[1u8; 16]);
        assert_eq!(list.key_for(1), Some(PekKey::new([1u8; 16])));
        assert_eq!(list.key_for(2), None);
    }

    #[test]
    fn parse_plaintext_rejects_short() {
        assert!(matches!(
            PekList::parse_plaintext(&[0u8; 30]).unwrap_err(),
            Error::Crypto(_)
        ));
    }

    #[test]
    fn parse_plaintext_accepts_zero_padded_tail() {
        // 32 header + 20 entry + 12 trailing zeros = 64 bytes (AES-block aligned) — should
        // parse to 1 entry, ignoring the zero-padded tail.
        let mut pt = vec![0u8; 32];
        pt.extend_from_slice(&0u32.to_le_bytes());
        pt.extend_from_slice(&[0xEE; 16]);
        pt.extend_from_slice(&[0u8; 12]); // padding
        let list = PekList::parse_plaintext(&pt).unwrap();
        assert_eq!(list.keys.len(), 1);
        assert_eq!(list.keys[0].bytes(), &[0xEE; 16]);
    }

    #[test]
    fn parse_plaintext_rejects_nonzero_ragged_tail() {
        // 32 header + 20 entry + 1 non-zero byte → torn buffer, should error.
        let mut pt = vec![0u8; 32];
        pt.extend_from_slice(&0u32.to_le_bytes());
        pt.extend_from_slice(&[0xEE; 16]);
        pt.push(0x42); // suspicious trailing non-zero byte
        assert!(matches!(
            PekList::parse_plaintext(&pt).unwrap_err(),
            Error::Crypto(_)
        ));
    }

    #[test]
    fn unwrap_peklist_reports_unknown_revision() {
        let mut blob = vec![0u8; 32];
        blob[0] = 42;
        let err = unwrap_peklist(&[0u8; 16], &blob).unwrap_err();
        assert!(format!("{err}").contains("unknown PEK version"));
    }

    /// End-to-end: build the plaintext PEKLIST, wrap it with revision-3 (SHA-256 + AES-CBC),
    /// then unwrap and verify we get the same keys back.
    #[test]
    fn unwrap_peklist_rev3_roundtrip() {
        let bootkey = [0xABu8; 16];
        let salt = [0x11u8; 16];

        // Build plaintext: 32-byte header + 2 × 20-byte entries.
        let mut plaintext = vec![0u8; 32];
        for i in 0..2u32 {
            plaintext.extend_from_slice(&i.to_le_bytes());
            plaintext.extend_from_slice(&[0xC0u8 + i as u8; 16]);
        }
        // Pad plaintext to a 16-byte AES block boundary.
        while plaintext.len() % 16 != 0 {
            plaintext.push(0);
        }

        // Compute the same KDF the unwrapper will run.
        let mut hasher = Sha256::new();
        hasher.update(bootkey);
        for _ in 0..1000 {
            hasher.update(salt);
        }
        let key = hasher.finalize();

        // Encrypt.
        let mut ct = plaintext.clone();
        let ct_len = ct.len();
        Aes256CbcEnc::new(key.as_slice().into(), &salt.into())
            .encrypt_padded_mut::<NoPadding>(&mut ct, ct_len)
            .unwrap();

        // Wrap in the header format the unwrapper expects.
        let mut blob = vec![0u8; 8];
        blob[0] = 3;
        blob.extend_from_slice(&salt);
        blob.extend_from_slice(&ct);

        // Unwrap + verify.
        let list = unwrap_peklist(&bootkey, &blob).unwrap();
        assert_eq!(list.version, 3);
        assert_eq!(list.keys.len(), 2);
        assert_eq!(list.keys[0].bytes(), &[0xC0u8; 16]);
        assert_eq!(list.keys[1].bytes(), &[0xC1u8; 16]);
    }

    /// End-to-end for legacy revision-2 (MD5 + RC4).
    #[test]
    fn unwrap_peklist_rev2_roundtrip() {
        use md5::{Digest, Md5};
        let bootkey = [0x33u8; 16];
        let salt = [0x77u8; 16];

        let mut plaintext = vec![0u8; 32];
        plaintext.extend_from_slice(&0u32.to_le_bytes());
        plaintext.extend_from_slice(&[0xEFu8; 16]);

        let mut hasher = Md5::new();
        hasher.update(bootkey);
        for _ in 0..1000 {
            hasher.update(salt);
        }
        let key = hasher.finalize();

        // RC4 is symmetric — encrypt = decrypt with the same key.
        let mut ct = plaintext.clone();
        let mut cipher: Rc4<U16> = Rc4::new(key.as_slice().into());
        cipher.apply_keystream(&mut ct);

        let mut blob = vec![0u8; 8];
        blob[0] = 2;
        blob.extend_from_slice(&salt);
        blob.extend_from_slice(&ct);

        let list = unwrap_peklist(&bootkey, &blob).unwrap();
        assert_eq!(list.version, 2);
        assert_eq!(list.keys.len(), 1);
        assert_eq!(list.keys[0].bytes(), &[0xEFu8; 16]);
    }
}