< Back
Unprotect-CString
Post
NAME Unprotect-CString
SYNOPSIS
Decrypts a string.
SYNTAX
Unprotect-CString [-ProtectedString] <String> [-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding]
[-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Thumbprint <String> [-UseDirectEncryptionPadding] [-AsSecureString]
[<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -PrivateKeyPath <String> [-Password <Object>]
[-UseDirectEncryptionPadding] [-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Key <Object> [-AsSecureString] [<CommonParameters>]
DESCRIPTION
`Unprotect-CString` decrypts a string encrypted via the Data Protection API (DPAPI), RSA, or AES. 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-CString` 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-CString` can decrypt using the following techniques.
## DPAPI
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 machine scope.
## RSA
RSA is an assymetric encryption/decryption algorithm, which requires a public/private key pair. It uses a private
key to decrypt a secret encrypted with the public key. Only the private key can decrypt secrets. `Protect-CString`
decrypts with .NET's `System.Security.Cryptography.RSACryptoServiceProvider` class.
You can specify the private key in three ways:
* with a `System.Security.Cryptography.X509Certificates.X509Certificate2` object, via the `Certificate` parameter
* with a certificate in one of the Windows certificate stores, passing its unique thumbprint via the `Thumbprint`
parameter, or via the `PrivateKeyPath` parameter, which can be a certificat provider path, e.g. it starts with
`cert:\\`.
* with an X509 certificate file, via the `PrivateKeyPath` parameter
## AES
AES is a symmetric encryption/decryption algorithm. You supply a 16-, 24-, or 32-byte key, password, or passphrase
with the `Key` parameter, and that key is used to decrypt. You must decrypt with the same key you used to encrypt.
`Unprotect-CString` decrypts with .NET's `System.Security.Cryptography.AesCryptoServiceProvider` class.
Symmetric encryption requires a random, unique initialization vector (i.e. IV) everytime you encrypt something. If
you encrypted your original string with Carbon's `Protect-CString` function, that IV was pre-pended to the
encrypted secret. If you encrypted the secret yourself, you'll need to ensure the original IV is pre-pended to the
protected string.
The help topic for `Protect-CString` demonstrates how to generate an AES key and how to encode it as a base-64
string.
The ability to decrypt with AES was added in Carbon 2.3.0.
PARAMETERS
-ProtectedString <String>
The text to decrypt.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Certificate <X509Certificate2>
The private key to use for decrypting.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PrivateKeyPath <String>
The path to the private key to use for encrypting. Must be to an `X509Certificate2` file or a certificate in a
certificate store.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Password <Object>
The password for the private key, if it has one. It really should. Can be a `[string]` or a `[securestring]`.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-UseDirectEncryptionPadding [<SwitchParameter>]
If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding.
See [Encrypt](http://msdn.microsoft.com/en-us/library ... ovider.enc
rypt(v=vs.110).aspx) for information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Key <Object>
The key to use to decrypt the secret. Must be a `SecureString`, `string`, or an array of bytes.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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 `string` object.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS>$password = Unprotect-CString -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.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Protect-CString -String 'NotSoSecretSecret' -ForUser | Unprotect-CString
Demonstrates how Unprotect-CString takes input from the pipeline. Adds 'NotSoSecretSecret' to the pipeline.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Unprotect-CString -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-CRsaKeyPair` function will create a key pair for you, if you've got a Windows SDK installed.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Unprotect-CString -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.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>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.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>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.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Unprotect-CString -ProtectedString 'dNC+yiKdSMAsG2Y3DA6Jzozesie3ZToQT24jB4CU/9eCGEozpiS5MR7R8s3L+PWV' -Key
'gT4XPfvcJmHkQ5tYjY3fNgi7uwG4FB9j'
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase. In this case, we are
decrypting with a plaintext password. This functionality was added in Carbon 2.3.0.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>Unprotect-CString -ProtectedString '19hNiwW0mmYHRlbk65GnSH2VX7tEziazZsEXvOzZIyCT69pp9HLf03YBVYGfg788' -Key
(Read-Host -Prompt 'Enter password (must be 16, 24, or 32 characters long):' -AsSecureString)
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase. In this case, we are
prompting the user for the password. This functionality was added in Carbon 2.3.0.
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Unprotect-CString -ProtectedString 'Mpu90IhBq9NseOld7VO3akcJX+nCIZmJv8rz8qfyn7M9m26owetJVzAfhFr0w0Vj' -Key (
[byte[]]@(163,163,185,174,205,55,157,219,121,146,251,116,43,203,63,38,73,154,230,112,82,112,151,29,189,135,254,187,
164,104,45,30))
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase as an array of bytes.
This functionality was added in Carbon 2.3.0.
RELATED LINKS
New-CRsaKeyPair
Protect-CString
http://msdn.microsoft.com/en-us/library ... ddata.aspx
SYNOPSIS
Decrypts a string.
SYNTAX
Unprotect-CString [-ProtectedString] <String> [-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding]
[-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Thumbprint <String> [-UseDirectEncryptionPadding] [-AsSecureString]
[<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -PrivateKeyPath <String> [-Password <Object>]
[-UseDirectEncryptionPadding] [-AsSecureString] [<CommonParameters>]
Unprotect-CString [-ProtectedString] <String> -Key <Object> [-AsSecureString] [<CommonParameters>]
DESCRIPTION
`Unprotect-CString` decrypts a string encrypted via the Data Protection API (DPAPI), RSA, or AES. 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-CString` 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-CString` can decrypt using the following techniques.
## DPAPI
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 machine scope.
## RSA
RSA is an assymetric encryption/decryption algorithm, which requires a public/private key pair. It uses a private
key to decrypt a secret encrypted with the public key. Only the private key can decrypt secrets. `Protect-CString`
decrypts with .NET's `System.Security.Cryptography.RSACryptoServiceProvider` class.
You can specify the private key in three ways:
* with a `System.Security.Cryptography.X509Certificates.X509Certificate2` object, via the `Certificate` parameter
* with a certificate in one of the Windows certificate stores, passing its unique thumbprint via the `Thumbprint`
parameter, or via the `PrivateKeyPath` parameter, which can be a certificat provider path, e.g. it starts with
`cert:\\`.
* with an X509 certificate file, via the `PrivateKeyPath` parameter
## AES
AES is a symmetric encryption/decryption algorithm. You supply a 16-, 24-, or 32-byte key, password, or passphrase
with the `Key` parameter, and that key is used to decrypt. You must decrypt with the same key you used to encrypt.
`Unprotect-CString` decrypts with .NET's `System.Security.Cryptography.AesCryptoServiceProvider` class.
Symmetric encryption requires a random, unique initialization vector (i.e. IV) everytime you encrypt something. If
you encrypted your original string with Carbon's `Protect-CString` function, that IV was pre-pended to the
encrypted secret. If you encrypted the secret yourself, you'll need to ensure the original IV is pre-pended to the
protected string.
The help topic for `Protect-CString` demonstrates how to generate an AES key and how to encode it as a base-64
string.
The ability to decrypt with AES was added in Carbon 2.3.0.
PARAMETERS
-ProtectedString <String>
The text to decrypt.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Certificate <X509Certificate2>
The private key to use for decrypting.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PrivateKeyPath <String>
The path to the private key to use for encrypting. Must be to an `X509Certificate2` file or a certificate in a
certificate store.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Password <Object>
The password for the private key, if it has one. It really should. Can be a `[string]` or a `[securestring]`.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-UseDirectEncryptionPadding [<SwitchParameter>]
If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding.
See [Encrypt](http://msdn.microsoft.com/en-us/library ... ovider.enc
rypt(v=vs.110).aspx) for information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Key <Object>
The key to use to decrypt the secret. Must be a `SecureString`, `string`, or an array of bytes.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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 `string` object.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS>$password = Unprotect-CString -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.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Protect-CString -String 'NotSoSecretSecret' -ForUser | Unprotect-CString
Demonstrates how Unprotect-CString takes input from the pipeline. Adds 'NotSoSecretSecret' to the pipeline.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Unprotect-CString -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-CRsaKeyPair` function will create a key pair for you, if you've got a Windows SDK installed.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Unprotect-CString -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.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>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.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>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.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Unprotect-CString -ProtectedString 'dNC+yiKdSMAsG2Y3DA6Jzozesie3ZToQT24jB4CU/9eCGEozpiS5MR7R8s3L+PWV' -Key
'gT4XPfvcJmHkQ5tYjY3fNgi7uwG4FB9j'
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase. In this case, we are
decrypting with a plaintext password. This functionality was added in Carbon 2.3.0.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>Unprotect-CString -ProtectedString '19hNiwW0mmYHRlbk65GnSH2VX7tEziazZsEXvOzZIyCT69pp9HLf03YBVYGfg788' -Key
(Read-Host -Prompt 'Enter password (must be 16, 24, or 32 characters long):' -AsSecureString)
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase. In this case, we are
prompting the user for the password. This functionality was added in Carbon 2.3.0.
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Unprotect-CString -ProtectedString 'Mpu90IhBq9NseOld7VO3akcJX+nCIZmJv8rz8qfyn7M9m26owetJVzAfhFr0w0Vj' -Key (
[byte[]]@(163,163,185,174,205,55,157,219,121,146,251,116,43,203,63,38,73,154,230,112,82,112,151,29,189,135,254,187,
164,104,45,30))
Demonstrates how to decrypt a secret that was encrypted with a key, password, or passphrase as an array of bytes.
This functionality was added in Carbon 2.3.0.
RELATED LINKS
New-CRsaKeyPair
Protect-CString
http://msdn.microsoft.com/en-us/library ... ddata.aspx