Impacket dpapi.py
Back to the category index / Back to the command index
Overview
Section titled “Overview”Parses and decrypts DPAPI master keys, credentials, Vault data, CREDHIST, and related structures. Some operations retrieve key material from a remote host.
| Item | Details |
|---|---|
| Implementation | examples/dpapi.py |
| Category | Secrets / DPAPI / registry / file analysis |
| Size | 633 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and input
Section titled “CLI and input”Run python examples/dpapi.py -h for the current option definitions.
Subcommands: backupkeys, masterkey, credential, vault, unprotect, credhist
| Argument | Description |
|---|---|
-debug | Enable debug output |
-ts | Add a timestamp to each log message |
-t / --target | [[domain/]username[:password]@] |
-hashes | NTLM hashes in LMHASH:NTHASH format |
-no-pass | Do not prompt for a password (useful with -k) |
-k | Use Kerberos authentication. Look for matching credentials in the ccache file named by KRB5CCNAME; if none are valid, use those specified on the command line |
-aesKey | AES key for Kerberos authentication (128 or 256 bits) |
-dc-ip | Domain controller IP address; if omitted, use the domain name (FQDN) from the target parameter |
--export | Export keys to a file |
-file | Master key file to parse; required |
-sid | User SID |
-pvk | Domain backup private key for decryption |
-key | Specific key for decryption |
-password | User password; if a SID is specified without a password, prompt for it |
-system | SYSTEM hive to parse |
-security | SECURITY hive to parse |
-vcrd | Vault credential file |
-vpol | Vault policy file |
-entropy | Extra entropy string required for decryption |
-entropy-file | File containing binary entropy; overrides -entropy |
-outfile | Save bytes decrypted by unprotect to a file; if omitted, display a hex dump |
-entry | Entry index in CREDHIST |
Related technology: the master key hierarchy, deriveKeysFromUser, and Vault in DPAPI / SAM / LSA / NTDS.
Detailed processing flow
Section titled “Detailed processing flow”The subcommands backupkeys, masterkey, credential, vault, unprotect, and credhist select the input structure. The tool parses each binary file with its corresponding structure, derives candidate keys from sources such as passwords, SIDs, user keys, domain PVKs, and DPAPI_SYSTEM, verifies MACs or signatures, and decrypts and displays the results.
How it works
Section titled “How it works”DPAPI does not encrypt every secret directly with a single password. Instead, it protects master keys with user or machine keys and uses those master keys to protect individual credentials and Vault blobs. The subcommands differ by which file in this hierarchy is available and which key sources are known.
masterkey parses a MasterKeyFile header and its sections, then derives decryption
keys from SID plus password, NT/SHA keys, DPAPI_SYSTEM, domain backup private keys,
and other sources. credential and unprotect accept a master key’s SHA1 or
equivalent, then inspect each DPAPI_BLOB’s algorithm and salt, verify its HMAC, and decrypt its ciphertext.
credhist is a format for tracing a chain of user keys from before password changes.
A Vault policy file (vpol) contains encrypted Vault keys, which decrypt attributes
in credential records (vcrd). The domain backup key path retrieves and converts
private key material through remote BKRP/LSA. Match blobs to master keys by GUID
and never display a plaintext candidate as a success when MAC verification fails;
this matters for every subcommand.
Key implementation elements
Section titled “Key implementation elements”| Symbol | Location | Where to trace its responsibility |
|---|---|---|
DPAPI | 64 | __init__(), getDPAPI_SYSTEM(), getLSA(), run() |
Dependencies
Section titled “Dependencies”Within Impacket
Section titled “Within Impacket”| Module | Main names used |
|---|---|
impacket.uuid | bin_to_string |
impacket | crypto, version |
impacket.smbconnection | SMBConnection |
impacket.dcerpc.v5 | bkrp, lsad, transport |
impacket.dcerpc.v5.rpcrt | RPC_C_AUTHN_GSS_NEGOTIATE, RPC_C_AUTHN_LEVEL_PKT_PRIVACY |
impacket.examples | logger |
impacket.examples.utils | parse_target |
impacket.examples.secretsdump | LSASecrets, LocalOperations |
impacket.structure | hexdump |
impacket.dpapi | CREDENTIAL_BLOB, CREDHIST_FILE, CredHist, CredentialFile, DPAPI_BLOB, DPAPI_DOMAIN_RSA_MASTER_KEY, DomainKey, MasterKey, MasterKeyFile, PREFERRED_BACKUP_KEY, PRIVATE_KEY_BLOB, PVK_FILE_HDR, P_BACKUP_KEY, VAULT_KNOWN_SCHEMAS, VAULT_VCRD, VAULT_VPOL, VAULT_VPOL_KEYS, deriveKeysFromUser, deriveKeysFromUserkey, privatekeyblob_to_pkcs1 |
External packages (used directly)
Section titled “External packages (used directly)”| Import name | Distribution package | Import path and declaration status |
|---|---|---|
Cryptodome | pycryptodomex | Imported directly; declared |
six | six | Imported directly; declared |
Output, side effects, and required privileges
Section titled “Output, side effects, and required privileges”- The tool primarily makes queries and authentication attempts. Frequent runs can affect audit logs, account lockouts, and target load.
- Options may create or update local files. Check how existing files are handled and the permissions on output containing secrets.
Failure paths and cleanup
Section titled “Failure paths and cleanup”- On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.
When changing the implementation
Section titled “When changing the implementation”The code depends on impacket.dpapi, crypto, Cryptodome, SMB/RPC bkrp and lsad, and examples.secretsdump. The main points are action dispatch and key source priority in DPAPI.run().
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/dpapi.py - CLI:
python examples/dpapi.py -h - Related test:
tests/misc/test_dpapi.py - Related test:
tests/SMB_RPC/test_rpcrt.py - Related test:
tests/misc/test_dcerpc_v5_ndr.py - Related test:
tests/misc/test_structure.py