dpapi-ng 0.2.0

Pure-Rust DPAPI-NG (CNG group protection) — decrypt Windows LAPS, gMSA and dMSA password blobs without a Windows host. Delegates the MS-GKDI key tree and ISDKey RPC to the `ms-gkdi` crate
Documentation
# dpapi-ng

[![Crates.io](https://img.shields.io/crates/v/dpapi-ng.svg)](https://crates.io/crates/dpapi-ng)
[![Docs.rs](https://docs.rs/dpapi-ng/badge.svg)](https://docs.rs/dpapi-ng)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

DPAPI-NG (CNG "group protection"), in pure Rust. Decrypt Windows LAPS
(`msLAPS-EncryptedPassword`), gMSA and dMSA managed passwords off the wire, from Linux/macOS,
with no `bcrypt.dll`, no FFI, no Windows host in the loop.

## Status

**`0.2.0-dev`** — actively developed. Part of the
[icedracon Rust offensive AD ecosystem](https://github.com/icedracon) and dogfooded by
[`adhammer`](https://crates.io/crates/adhammer) (the `dump laps` / `dump gmsa` commands).

### What's new in 0.2.0-dev

The MS-GKDI structures (`KeyIdentifier`, `GroupKeyEnvelope`, the SP800-108 KDF, the L0/L1/L2
tree walk, the `ISDKey::GetKey` RPC) have moved out to the
[`ms-gkdi`](https://crates.io/crates/ms-gkdi) crate. This crate's `gkdi`, `kdf` and (`rpc`
feature-gated) `rpc` modules become **thin `pub use` shims marked `#[deprecated]`** — 0.1.x code
compiles unchanged, and `ms_gkdi::GkdiError` lifts into `DpapiError` via `From` so existing `?`
call sites stay wired.

This is a coordinated no-yank release path: 0.1.1 stays live on crates.io for anyone pinned to
it, and new callers get the split cleanly on their next `cargo update`. `dpapi-ng 0.2.x` will
keep the shims through the deprecation window, then drop them in `0.3.0`.

## What it does

Windows LAPS, gMSA and dMSA managed passwords are all protected the same way: a CMS
`EnvelopedData` whose content key is wrapped under a KEK derived from a **KDS root key** that
lives on the domain controllers. The blob carries no key — only a *key identifier*: which root
key, and which node of its L0/L1/L2 tree. A principal allowed to read the secret asks a DC for
that node (`GetKey` over MS-GKDI) and derives downwards.

This crate does everything except the RPC call.

## Usage

```rust
use dpapi_ng::{decrypt, laps_password_from_json, LapsBlob};
use ms_gkdi::gkdi::GroupKeyEnvelope;

# fn go(attr_value: &[u8], get_key_response: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
// 1. Split the LAPS attribute header and parse the CMS blob.
let laps = LapsBlob::parse(attr_value)?;
let blob = laps.protected()?;

// 2. Ask a DC for the node named in blob.key_identifier (your DCE/RPC, not ours).
let envelope = GroupKeyEnvelope::parse(get_key_response)?;

// 3. Derive down the tree and open the content.
let plaintext = decrypt(&blob, &envelope)?;
if let Some(pw) = laps_password_from_json(&plaintext) {
    println!("LAPS password: {pw}");
}
# Ok(()) }
```

If the DC round-trip isn't your concern and you already have the L2 seed key, call
[`decrypt_with_seed_key`] directly; if you already know the exact KEK derivation your
environment uses, call [`decrypt_with_kek`] and skip the retry loop.

## What is in here

- `cms::ProtectedBlob` — the CMS `EnvelopedData`, its `KEKRecipientInfo` and the AES-GCM
  content parameters, parsed on a small hand-written DER reader (`der.rs`, ~200 LOC) rather
  than a codegen'd ASN.1 stack.
- `LapsBlob` + `laps_password_from_json` — the Windows LAPS attribute header
  (`update_timestamp` FILETIME + blob length) and the UTF-16LE JSON payload
  (`{"n":"…","t":"…","p":"…"}`) — extracted without a JSON dependency.
- `decrypt` / `decrypt_with_seed_key` / `decrypt_with_kek` / `decrypt_content` — the four
  entry points into the crypto: full envelope path, seed-key-known path, KEK-known path, and
  raw AES-256-GCM open with a pre-unwrapped CEK.
- `gkdi` / `kdf` / (feature `rpc`) `rpc` — thin `#[deprecated]` re-export shims over
  [`ms-gkdi`]https://crates.io/crates/ms-gkdi so 0.1.x import paths keep compiling.

## Transport is deliberately out of scope

`GetKey` is one MS-GKDI RPC call over `\pipe\lsass` with authentication and sealing, and every
project that needs this already has a DCE/RPC stack. Make the call (via `dcerpc` +
`smb2-client` + `ntlmssp`, or `ms-gkdi::rpc` if you'd rather not roll your own), hand the
response bytes to `GroupKeyEnvelope::parse`, and keep this crate free of a transport
dependency.

If you *want* the RPC caller re-exported anyway — because you're upgrading 0.1.x code that
already imported `dpapi_ng::rpc::get_key` — enable the `rpc` feature:

```toml
dpapi-ng = { version = "0.2", features = ["rpc"] }
```

## What works / what does not (this version)

- ✅ CMS `EnvelopedData` parser + AES key-unwrap + AES-256-GCM open, unit-tested end-to-end
  (build a real envelope, decrypt it, byte-compare).
- ✅ `LapsBlob` header split + LAPS JSON password extraction, validated against real
  `msLAPS-EncryptedPassword` attributes captured from a lab DC.
- ✅ Multi-candidate seed-key → KEK derivation: because Windows has used more than one
  derivation across versions, `decrypt_with_seed_key` tries known candidates in order. This
  is *safe* rather than sloppy — AES key-wrap and AES-GCM are both authenticated, so a wrong
  KEK fails loudly instead of yielding plausible garbage.
- ⚠ `gkdi`, `kdf`, `rpc` are `#[deprecated]` shims for the 0.2.x line only. New code should
  depend on [`ms-gkdi`]https://crates.io/crates/ms-gkdi directly.
- ⚠ Only the CNG group-protection profile is implemented — legacy DPAPI (`CryptProtectData`,
  per-user master keys) is a different protocol and out of scope.

## Example — inspect a captured blob

```sh
cargo run --example inspect_blob -- laps.bin
cargo run --example inspect_blob -- --raw enveloped.bin   # for a bare CMS blob
```

Prints the key identifier (root key, L0/L1/L2 node, KDF hash, secret algorithm, domain/forest)
and the content parameters (nonce, tag length, wrapped-key + ciphertext sizes). Everything
shown is derived without any key — this is public metadata.

## Related icedracon crates

- [`ms-gkdi`]https://crates.io/crates/ms-gkdi — the MS-GKDI structures, KDF, tree walk and
  `ISDKey::GetKey` RPC that this crate's shims re-export.
- [`dcerpc`]https://crates.io/crates/dcerpc — the RPC stack you'd normally use to make the
  `GetKey` call (`\pipe\lsass`, `PKT_PRIVACY`).
- [`smb2-client`]https://crates.io/crates/smb2-client +
  [`ntlmssp`]https://crates.io/crates/ntlmssp — the transport + auth layers under `dcerpc`.
- [`windows-sddl`]https://crates.io/crates/windows-sddl — `Sid`/`Guid` types you'll want on
  the LDAP side to resolve the principal that owns a LAPS-protected computer object.
- [`adhammer`]https://crates.io/crates/adhammer — the AD security-assessment toolkit whose
  `dump laps` / `dump gmsa` commands wire this all together end-to-end.

## License

MIT © 2026 [zevs](https://github.com/icedracon).

Authorized-testing / research / education use only.