Decrypts a string.
Unprotect-String [-ProtectedString] <String> [-AsSecureString] [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding] [-AsSecureString] [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -Thumbprint <String> [-UseDirectEncryptionPadding] [-AsSecureString] [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -PrivateKeyPath <String> [-Password <Object>] [-UseDirectEncryptionPadding] [-AsSecureString] [<CommonParameters>]
Unprotect-String
decrypts a string encrypted via the Data Protection API (DPAPI) or RSA. It uses the DP/RSA APIs to decrypted the secret into an array of bytes, which is then converted to a UTF8 string. Beginning with Carbon 2.0, after conversion, the decrypted array of bytes is cleared in memory.
Also beginning in Carbon 2.0, use the AsSecureString
switch to cause Unprotect-String
to return the decrypted string as a System.Security.SecureString
, thus preventing your secret from hanging out in memory. When converting to a secure string, the secret is decrypted to an array of bytes, and then converted to an array of characters. Each character is appended to the secure string, after which it is cleared in memory. When the conversion is complete, the decrypted byte array is also cleared out in memory.
Unprotect-String
can decrypt using the following techniques.
This is the default. The string must have also been encrypted with the DPAPI. The string must have been encrypted at the current user's scope or the local machien scope.
RSA is an assymetric encryption/decryption algorithm, which requires a public/private key pair. This method decrypts a secret that was encrypted with the public key using the private key.
You can specify the private key in three ways:
System.Security.Cryptography.X509Certificates.X509Certificate2
object, via the Certificate
parameterThumbprint
parameter, or via the PrivateKeyPath
parameter, which can be a certificat provider path, e.g. it starts with cert:\
.PrivateKeyPath
parameterName | Type | Description | Required? | Pipeline Input | Default Value |
---|---|---|---|---|---|
ProtectedString | String | The text to decrypt. |
true | true (ByValue) | |
Certificate | X509Certificate2 | The private key to use for decrypting. |
true | false | |
Thumbprint | String | The thumbprint of the certificate, found in one of the Windows certificate stores, to use when decrypting. All certificate stores are searched. The current user must have permission to the private key. |
true | false | |
PrivateKeyPath | String | The path to the private key to use for encrypting. Must be to an |
true | false | |
Password | Object | The password for the private key, if it has one. It really should. Can be a |
false | false | |
UseDirectEncryptionPadding | SwitchParameter | If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding. See Encrypt for information. |
false | false | False |
AsSecureString | SwitchParameter | Returns the unprotected string as a secure string. The original decrypted bytes are zeroed out to limit the memory exposure of the decrypted secret, i.e. the decrypted secret will never be in a |
false | false | False |
$password = Unprotect-String -ProtectedString $encryptedPassword
Decrypts a protected string which was encrypted at the current user or default scopes using the DPAPI. The secret must have been encrypted at the current user's scope or at the local computer's scope.
Protect-String -String 'NotSoSecretSecret' -ForUser | Unprotect-String
Demonstrates how Unprotect-String takes input from the pipeline. Adds 'NotSoSecretSecret' to the pipeline.
Unprotect-String -ProtectedString $ciphertext -Certificate $myCert
Demonstrates how to encrypt a secret using RSA with a System.Security.Cryptography.X509Certificates.X509Certificate2
object. You're responsible for creating/loading it. The New-RsaKeyPair
function will create a key pair for you, if you've got a Windows SDK installed.
Unprotect-String -ProtectedString $ciphertext -Thumbprint '44A7C27F3353BC53F82318C14490D7E2500B6D9E'
Demonstrates how to decrypt a secret using RSA with a certificate in one of the Windows certificate stores. All local machine and user stores are searched. The current user must have permission/access to the certificate's private key.
Unprotect -ProtectedString $ciphertext -PrivateKeyPath 'C:\Projects\Security\publickey.cer'
Demonstrates how to encrypt a secret using RSA with a certificate file. The file must be loadable by the System.Security.Cryptography.X509Certificates.X509Certificate
class.
Unprotect -ProtectedString $ciphertext -PrivateKeyPath 'cert:\LocalMachine\My\44A7C27F3353BC53F82318C14490D7E2500B6D9E'
Demonstrates how to encrypt a secret using RSA with a certificate in the store, giving its exact path.