PowerShell - Protect-String

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:

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 PublicKeyPath parameter cn be certificat provider path, e.g. it starts with cert:\.
with a X509 certificate file, via the PublicKeyPath parameter

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

EXAMPLE 1

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

EXAMPLE 2

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

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

EXAMPLE 3

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

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

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

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

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

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

EXAMPLE 9

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

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

EXAMPLE 11

Demonstrates that you can use an array of bytes as the key, password, or passphrase. This functionality was added in Carbon 2.3.0.

Protect-String

Syntax

Description