Encrypts a string.
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>]
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).
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 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
You can specify the public key in three ways:
System.Security.Cryptography.X509Certificates.X509Certificate2object, via the
Thumbprintparameter, or via the
PublicKeyPathparameter cn be certificat provider path, e.g. it starts with
You can generate an RSA public/private key pair with the
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
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 -String 'the secret sauce' -Key ([Convert]::FromBase64String($base64EncodedKey))
The ability to encrypt with AES was added in Carbon 2.3.0.
|Name||Type||Description||Required?||Pipeline Input||Default Value|
The string to encrypt. Any non-string object you pass will be converted to a string before encrypting by calling the object's
Beginning in Carbon 2.4.0, this can also be a
Encrypts for the current user so that only he can decrypt.
Encrypts for the current computer so that any user logged into the computer can decrypt.
Encrypts for a specific user.
The public key to use for encrypting.
The thumbprint of the certificate, found in one of the Windows certificate stores, to use when encrypting. All certificate stores are searched.
The path to the public key to use for encrypting. Must be to an
If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding. See Encrypt for information.
The key to use to encrypt the secret. Can be a
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.
Protect-String -String $credential.Password -ForUser | Out-File MySecret.txt
Protect-String can encrypt a
SecureString. This functionality was added in Carbon 2.4.0.
$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
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.
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.
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.
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
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.
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.
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.
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.