Unprotect-String

Decrypts a string.

Syntax

Unprotect-String [-ProtectedString] <String> [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding] [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -Thumbprint <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Unprotect-String [-ProtectedString] <String> -PrivateKeyPath <String> [-Password <String>] [-UseDirectEncryptionPadding] [<CommonParameters>]

Description

Decrypts a string encrypted via the Data Protection API (DPAPI) or RSA.

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 machien scope.

RSA

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:

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 String The password for the private key, if it has one. It really should. 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

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.