Encrypts a string.
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>]
Strings can be encrypted with the Data Protection API (DPAPI) or RSA.
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).
You can specify the public key in three ways:
System.Security.Cryptography.X509Certificates.X509Certificate2
object, via the Certificate
parameterThumbprint
parameter, or via the PublicKeyPath
parameter cn be certificat provider path, e.g. it starts with cert:\
.PublicKeyPath
parameterName | 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 |
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 |
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.
$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
.
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.
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.
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.