SecretManagement.DpapiNG

A PowerShell module that can be used to encrypt and decrypt data using DPAPI NG also known as CNG DPAPI. The module also implements a SecretManagement extension that can be used for interacting with a DPAPI-NG vault registered with the SecretManagement module.

See SecretManagement.DpapiNG index for more details.

Requirements

These cmdlets have the following requirements

• PowerShell v5.1 or newer

Currently this module only works on Windows, it cannot be used on Linux or macOS.

Examples

To encrypt a string with DPAPI-NG use the following:

# Encrypts the secret so only the current user on the current host can decrypt.
ConvertTo-DpapiNGSecret MySecret

# Encrypts the secret so only the current domain user on any host can decrypt.
ConvertTo-DpapiNGSecret MySecret -CurrentSid

# Encrypts the secret so only Domain Admins on any host can decrypt.
ConvertTo-DpapiNGSecret MySecret -Sid 'DOMAIN\Domain Admins'

The -CurrentSid and -Sid options can be used on domain joined hosts to protect a secret for that domain user/group specified. This secret can be decrypted by that user or member of the group specified on any domain joined host.

To decrypt the DPAPI-NG blob back:

# Decrypts back as a SecureString
ConvertFrom-DpapiNGSecret $secret

# Decrypts back as a String
ConvertFrom-DpapiNGSecret $secret -AsString

See ConvertTo-DpapiNGSecret and ConvertFrom-DpapiNGSecret for more details.

To register a DPAPI-NG vault for use with SecretManagement:

# Registers a DPAPI-NG vault with the default path in the user profile.
Register-SecretVault -Name DpapiNG -ModuleName SecretManagement.DpapiNG

# Registers a DPAPI-NG vault with a custom vault path.
$vaultParams = @{
    Name = 'MyVault'
    ModuleName = 'SecretManagement.DpapiNG'
    VaultParameters = @{
        Path = 'C:\path\to\vault_file'
    }
}
Register-SecretVault @vaultParams

The vault name that was registered can now be used with Set-Secret and Get-Secret to get and set secrets using DPAPI-NG.

# Uses the default protection of 'LOCAL=user'
Set-Secret -Name MySecret -Vault MyVault -Secret password

# Uses a custom protection descriptor to protect for the current user
$desc = New-DpapiNGDescriptor |
    Add-DpapiNGDescriptor -CurrentSid
Set-Secret -Name MySecret -Vault MyVault -Secret password @desc

# Uses a custom protection descriptor as a manual string
Set-Secret -Name MySecret -Vault MyVault -Secret password -Metadata @{
    ProtectionDescriptor = "SID=..."
}

# Get the secret value
Get-Secret -Name MySecret -Vault MyVault

See about_DpapiNGSecretManagement for more information on how to use this module with SecretManagement.

Installing

The easiest way to install this module is through PowerShellGet.

You can install this module by running either of the following Install-PSResource or Install-Module command.

# Install for only the current user
Install-PSResource -Name SecretManagement.DpapiNG, Microsoft.PowerShell.SecretManagement -Scope CurrentUser
Install-Module -Name SecretManagement.DpapiNG, Microsoft.PowerShell.SecretManagement -Scope CurrentUser

# Install for all users
Install-PSResource -Name SecretManagement.DpapiNG, Microsoft.PowerShell.SecretManagement -Scope AllUsers
Install-Module -Name SecretManagement.DpapiNG, Microsoft.PowerShell.SecretManagement -Scope AllUsers

If the SecretManagement implementation is not needed, the Microsoft.PowerShell.SecretManagement package can be omitted during the install. The Install-PSResource cmdlet is part of the new PSResourceGet module from Microsoft available in newer versions while Install-Module is present on older systems.

Contributing

Contributing is quite easy, fork this repo and submit a pull request with the changes. To build this module run .\build.ps1 -Task Build in PowerShell. To test a build run .\build.ps1 -Task Test in PowerShell. This script will ensure all dependencies are installed before running the test suite.