Protect-String

Encrypts a string.

Syntax

Protect-String [-String] <String> -ForUser [<CommonParameters>]
Protect-String [-String] <String> -ForComputer [<CommonParameters>]
Protect-String [-String] <String> -Credential <PSCredential> [<CommonParameters>]
Protect-String [-String] <String> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-String [-String] <String> -Thumbprint <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-String [-String] <String> -PublicKeyPath <String> [-UseDirectEncryptionPadding] [<CommonParameters>]

Description

Strings can be encrypted with the Data Protection API (DPAPI) or RSA.

DPAPI

The DPAPI hides the encryptiong/decryption keys from you. As such, anything encrpted with via DPAPI can only be decrypted on the same computer it was encrypted on. Use the ForUser switch so that only the user who encrypted can decrypt. Use the ForComputer switch so that any user who can log into the computer can decrypt. To encrypt as a specific user on the local computer, pass that user's credentials with the Credential parameter. (Note this method doesn't work over PowerShell remoting.)

RSA

RSA is an assymetric encryption/decryption algorithm, which requires a public/private key pair. The secret is encrypted with the public key, and can only be decrypted with the corresponding private key. The secret being encrypted can't be larger than the RSA key pair's size/length, usually 1024, 2048, or 4096 bits (128, 256, and 512 bytes, respectively).

You can specify the public key in three ways:

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
String String

The text to encrypt.

true true (ByValue)
ForUser SwitchParameter

Encrypts for the current user so that only he can decrypt.

true false False
ForComputer SwitchParameter

Encrypts for the current computer so that any user logged into the computer can decrypt.

true false False
Credential PSCredential

Encrypts for a specific user.

true false
Certificate X509Certificate2

The public key to use for encrypting.

true false
Thumbprint String

The thumbprint of the certificate, found in one of the Windows certificate stores, to use when encrypting. All certificate stores are searched.

true false
PublicKeyPath String

The path to the public key to use for encrypting. Must be to an X509Certificate2 object.

true 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

Protect-String -String 'TheStringIWantToEncrypt' -ForUser | Out-File MySecret.txt

Encrypts the given string and saves the encrypted string into MySecret.txt. Only the user who encrypts the string can unencrypt it.

EXAMPLE 2

$cipherText = Protect-String -String "MySuperSecretIdentity" -ForComputer

Encrypts the given string and stores the value in $cipherText. Because the encryption scope is set to LocalMachine, any user logged onto the local computer can decrypt $cipherText.

EXAMPLE 3

Protect-String -String 's0000p33333r s33333cr33333t' -Credential (Get-Credential 'builduser')

Demonstrates how to use Protect-String to encrypt a secret as a specific user. This is useful for situation where a secret needs to be encrypted by a user other than the user running Protect-String. Encrypting as a specific user won't work over PowerShell remoting.

EXAMPLE 4

Protect-String -String 'the secret sauce' -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 5

Protect-String -String 'the secret sauce' -Thumbprint '44A7C27F3353BC53F82318C14490D7E2500B6D9E'

Demonstrates how to encrypt a secret using RSA with a certificate in one of the Windows certificate stores. All local machine and user stores are searched.

EXAMPLE 6

ProtectString -String 'the secret sauce' -PublicKeyPath '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 7

ProtectString -String 'the secret sauce' -PublicKeyPath 'cert:\LocalMachine\My\44A7C27F3353BC53F82318C14490D7E2500B6D9E'

Demonstrates how to encrypt a secret using RSA with a certificate in the store, giving its exact path.