Protect-String

Encrypts a string.

Syntax

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

Description

The Protect-String function encrypts a string using the Data Protection API (DPAPI), RSA, or AES. In Carbon 2.3.0 or earlier, the plaintext string to encrypt is passed to the String parameter. Beginning in Carbon 2.4.0, you can also pass a SecureString. When encrypting a SecureString, it is converted to an array of bytes, encrypted, then the array of bytes is cleared from memory (i.e. the plaintext version of the SecureString is only in memory long enough to encrypt it).

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

You can specify the public key in three ways:

You can generate an RSA public/private key pair with the New-RsaKeyPair function.

AES

AES is a symmetric encryption/decryption algorithm. You supply a 16-, 24-, or 32-byte key/password/passphrase with the Key parameter, and that key is used to encrypt. There is no limit on the size of the data you want to encrypt. Protect-String encrypts with .NET's System.Security.Cryptography.AesCryptoServiceProvider class.

Symmetric encryption requires a random, unique initialization vector (i.e. IV) everytime you encrypt something. Protect-String generates one for you. This IV must be known to decrypt the secret, so it is pre-pendeded to the encrypted text.

This code demonstrates how to generate a key:

$key = (New-Object 'Security.Cryptography.AesManaged').Key

You can save this key as a string by encoding it as a base-64 string:

$base64EncodedKey = [Convert]::ToBase64String($key)

If you base-64 encode your string, it must be converted back to bytes before passing it to Protect-String.

Protect-String -String 'the secret sauce' -Key ([Convert]::FromBase64String($base64EncodedKey))

The ability to encrypt with AES was added in Carbon 2.3.0.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
String Object

The string to encrypt. Any non-string object you pass will be converted to a string before encrypting by calling the object's ToString method.

Beginning in Carbon 2.4.0, this can also be a SecureString object. The SecureString is converted to an array of bytes, the bytes are encrypted, then the plaintext bytes are cleared from memory (i.e. the plaintext password is in memory for the amount of time it takes to encrypt it).

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

The key to use to encrypt the secret. Can be a SecureString, a String, or an array of bytes. Must be 16, 24, or 32 characters/bytes in length.

true 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

Protect-String -String $credential.Password -ForUser | Out-File MySecret.txt

Demonstrates that Protect-String can encrypt a SecureString. This functionality was added in Carbon 2.4.0.

EXAMPLE 3

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

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 5

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 6

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 7

Protect-String -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 8

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

EXAMPLE 9

Protect-String -String 'the secret sauce' -Key 'gT4XPfvcJmHkQ5tYjY3fNgi7uwG4FB9j'

Demonstrates how to encrypt a secret with a key, password, or passphrase. In this case, we are encrypting with a plaintext password. This functionality was added in Carbon 2.3.0.

EXAMPLE 10

Protect-String -String 'the secret sauce' -Key (Read-Host -Prompt 'Enter password (must be 16, 24, or 32 characters long):' -AsSecureString)

Demonstrates that you can use a SecureString as the key, password, or passphrase. This functionality was added in Carbon 2.3.0.

EXAMPLE 11

Protect-String -String 'the secret sauce' -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 that you can use an array of bytes as the key, password, or passphrase. This functionality was added in Carbon 2.3.0.