CNGDPAPI.psm1
|
# ---------------------------------------- # Module: CngDpapi # Description: Encrypts and decrypts strings using DPAPI-NG via NCrypt APIs. # OS Requirement: Windows (requires ncrypt.dll) # ---------------------------------------- # Load the .NET wrapper for native NCrypt functions Add-Type -TypeDefinition @" using System; using System.Runtime.InteropServices; public class DpapiNgHelper { [DllImport("ncrypt.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern int NCryptCreateProtectionDescriptor( string pwszDescriptorString, uint dwFlags, out IntPtr phDescriptor); [DllImport("ncrypt.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern int NCryptProtectSecret( IntPtr hDescriptor, uint dwFlags, byte[] pbData, int cbData, IntPtr pMemPara, IntPtr hWnd, out IntPtr ppbProtectedBlob, out int pcbProtectedBlob); [DllImport("ncrypt.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern int NCryptUnprotectSecret( IntPtr hDescriptor, uint dwFlags, byte[] pbProtectedBlob, int cbProtectedBlob, IntPtr pMemPara, IntPtr hWnd, out IntPtr ppbData, out int pcbData); [DllImport("ncrypt.dll")] public static extern int NCryptCloseProtectionDescriptor(IntPtr hDescriptor); [DllImport("ncrypt.dll")] public static extern int NCryptFreeBuffer(IntPtr pvBuffer); } "@ -ErrorAction Stop function Protect-CngDpapiString { <# .SYNOPSIS Encrypts a string using DPAPI-NG (CNG). .DESCRIPTION Uses the NCryptProtectSecret API to encrypt a UTF-8 string and return it as a Base64-encoded string. You can specify a user/group principal, or directly supply a descriptor rule string. .PARAMETER String The plaintext string you want to encrypt. .PARAMETER Principal The user or group (name or SID) allowed to decrypt the secret. Will be converted to a protection descriptor like "SID=S-1-5-32-544". .PARAMETER Descriptor A custom protection descriptor rule string (e.g. "SID=S-1-5-32-544" or "LOCAL=user"). https://learn.microsoft.com/en-us/windows/win32/seccng/protection-descriptors .EXAMPLE "Secret" | Protect-CngDpapiString -Principal "DOMAIN\ADGroup" .EXAMPLE "Secret" | Protect-CngDpapiString -Descriptor "LOCAL=user" .NOTES Exactly one of -Principal or -Descriptor must be provided. #> [CmdletBinding(DefaultParameterSetName="Principal")] [OutputType([string])] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string]$String, [Parameter(Mandatory = $true, ParameterSetName="Principal")] [string]$Principal, [Parameter(Mandatory = $true, ParameterSetName="Descriptor")] [string]$Descriptor ) process { $hDescriptor = [IntPtr]::Zero $ppbProtectedBlob = [IntPtr]::Zero $pcbProtectedBlob = [IntPtr]::Zero try { if ($Principal) { $account = New-Object System.Security.Principal.NTAccount($Principal) $sid = $account.Translate([System.Security.Principal.SecurityIdentifier]) $descriptorString = "SID=$($sid.Value)" } else { $descriptorString = $Descriptor } Write-Verbose "Using protection descriptor: $descriptorString" $result = [DpapiNgHelper]::NCryptCreateProtectionDescriptor($descriptorString, 0, [ref]$hDescriptor) if ($result -ne 0) { throw "NCryptCreateProtectionDescriptor failed (0x$($result.ToString('X8')))" } $data = [Text.Encoding]::UTF8.GetBytes($String) $result = [DpapiNgHelper]::NCryptProtectSecret( $hDescriptor, 0, $data, $data.Length, [IntPtr]::Zero, [IntPtr]::Zero, [ref]$ppbProtectedBlob, [ref]$pcbProtectedBlob ) if ($result -ne 0) { throw "NCryptProtectSecret failed (0x$($result.ToString('X8')))" } $encryptedData = New-Object byte[] $pcbProtectedBlob [System.Runtime.InteropServices.Marshal]::Copy($ppbProtectedBlob, $encryptedData, 0, $pcbProtectedBlob) | Out-Null return [Convert]::ToBase64String($encryptedData) } finally { if ($hDescriptor -ne [IntPtr]::Zero) { [DpapiNgHelper]::NCryptCloseProtectionDescriptor($hDescriptor) | Out-Null } if ($ppbProtectedBlob -ne [IntPtr]::Zero) { [DpapiNgHelper]::NCryptFreeBuffer($ppbProtectedBlob) | Out-Null } } } } function Unprotect-CngDpapiString { <# .SYNOPSIS Decrypts a Base64-encoded string previously encrypted using DPAPI-NG. .DESCRIPTION Uses the NCryptUnprotectSecret API to decrypt data that was encrypted using Protect-CngDpapiString. .PARAMETER EncryptedString A Base64-encoded string previously returned by Protect-CngDpapiString. .EXAMPLE $plaintext = Unprotect-CngDpapiString -EncryptedString $ciphertext #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [string]$EncryptedString ) process { $ppbData = [IntPtr]::Zero $pcbData = [IntPtr]::Zero try { $encryptedData = [Convert]::FromBase64String($EncryptedString) $result = [DpapiNgHelper]::NCryptUnprotectSecret([IntPtr]::Zero, 0, $encryptedData, $encryptedData.Length, [IntPtr]::Zero, [IntPtr]::Zero, [ref]$ppbData, [ref]$pcbData) if ($result -ne 0) { throw "NCryptUnprotectSecret failed (0x$($result.ToString('X8')))" } $decryptedData = New-Object byte[] $pcbData [System.Runtime.InteropServices.Marshal]::Copy($ppbData, $decryptedData, 0, $pcbData) | Out-Null return [Text.Encoding]::UTF8.GetString($decryptedData) } finally { if ($ppbData -ne [IntPtr]::Zero) { [DpapiNgHelper]::NCryptFreeBuffer($ppbData) | Out-Null } } } } Export-ModuleMember -Function Protect-CngDpapiString, Unprotect-CngDpapiString |