Unprotect-String

Decrypts a string.

Syntax

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 [-ProtectedString] <String> -Key <Object> [-AsSecureString] [<CommonParameters>]

Description

Unprotect-String 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-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.

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-String decrypts with .NET's System.Security.Cryptography.RSACryptoServiceProvider class.

You can specify the private key in three ways:

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-String 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-String 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-String 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.

Related Commands

Parameters

Name 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 X509Certificate2 file or a certificate in a certificate store.

true false
Password Object

The password for the private key, if it has one. It really should. Can be a [string] or a [securestring].

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
Key Object

The key to use to decrypt the secret. Must be a SecureString, string, or an array of bytes.

true 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.

false false False

EXAMPLE 1

$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.

EXAMPLE 2

Protect-String -String 'NotSoSecretSecret' -ForUser | Unprotect-String

Demonstrates how Unprotect-String takes input from the pipeline. Adds 'NotSoSecretSecret' to the pipeline.

EXAMPLE 3

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.

EXAMPLE 4

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.

EXAMPLE 5

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

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

Unprotect-String -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

Unprotect-String -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

Unprotect-String -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.