< Back
Protect-CString
Post
NAME Protect-CString
SYNOPSIS
Encrypts a string.
SYNTAX
Protect-CString [-String] <Object> -ForUser [<CommonParameters>]
Protect-CString [-String] <Object> -ForComputer [<CommonParameters>]
Protect-CString [-String] <Object> -Credential <PSCredential> [<CommonParameters>]
Protect-CString [-String] <Object> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding]
[<CommonParameters>]
Protect-CString [-String] <Object> -Thumbprint <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-CString [-String] <Object> -PublicKeyPath <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-CString [-String] <Object> -Key <Object> [<CommonParameters>]
DESCRIPTION
The `Protect-CString` 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-CString` 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-CRsaKeyPair` 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-CString` 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-CString` 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-CString`.
Protect-CString -String 'the secret sauce' -Key ([Convert]::FromBase64String($base64EncodedKey))
The ability to encrypt with AES was added in Carbon 2.3.0.
PARAMETERS
-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).
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-ForUser [<SwitchParameter>]
Encrypts for the current user so that only he can decrypt.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-ForComputer [<SwitchParameter>]
Encrypts for the current computer so that any user logged into the computer can decrypt.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Encrypts for a specific user.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Certificate <X509Certificate2>
The public key to use for encrypting.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PublicKeyPath <String>
The path to the public key to use for encrypting. Must be to an `X509Certificate2` object.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-UseDirectEncryptionPadding [<SwitchParameter>]
If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding.
See [Encrypt](http://msdn.microsoft.com/en-us/library ... ovider.enc
rypt(v=vs.110).aspx) for information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -String $credential.Password -ForUser | Out-File MySecret.txt
Demonstrates that `Protect-CString` can encrypt a `SecureString`. This functionality was added in Carbon 2.4.0.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>$cipherText = Protect-CString -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 --------------------------
PS C:\\>Protect-CString -String 's0000p33333r s33333cr33333t' -Credential (Get-Credential 'builduser')
Demonstrates how to use `Protect-CString` 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-CString`. Encrypting as a
specific user won't work over PowerShell remoting.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>Protect-CString -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-CRsaKeyPair` function will create a key pair for you, if you've got a Windows SDK installed.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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.
RELATED LINKS
New-CRsaKeyPair
Unprotect-CString
http://msdn.microsoft.com/en-us/library ... ddata.aspx
SYNOPSIS
Encrypts a string.
SYNTAX
Protect-CString [-String] <Object> -ForUser [<CommonParameters>]
Protect-CString [-String] <Object> -ForComputer [<CommonParameters>]
Protect-CString [-String] <Object> -Credential <PSCredential> [<CommonParameters>]
Protect-CString [-String] <Object> -Certificate <X509Certificate2> [-UseDirectEncryptionPadding]
[<CommonParameters>]
Protect-CString [-String] <Object> -Thumbprint <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-CString [-String] <Object> -PublicKeyPath <String> [-UseDirectEncryptionPadding] [<CommonParameters>]
Protect-CString [-String] <Object> -Key <Object> [<CommonParameters>]
DESCRIPTION
The `Protect-CString` 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-CString` 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-CRsaKeyPair` 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-CString` 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-CString` 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-CString`.
Protect-CString -String 'the secret sauce' -Key ([Convert]::FromBase64String($base64EncodedKey))
The ability to encrypt with AES was added in Carbon 2.3.0.
PARAMETERS
-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).
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-ForUser [<SwitchParameter>]
Encrypts for the current user so that only he can decrypt.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-ForComputer [<SwitchParameter>]
Encrypts for the current computer so that any user logged into the computer can decrypt.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Encrypts for a specific user.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Certificate <X509Certificate2>
The public key to use for encrypting.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PublicKeyPath <String>
The path to the public key to use for encrypting. Must be to an `X509Certificate2` object.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-UseDirectEncryptionPadding [<SwitchParameter>]
If true, uses Direct Encryption (PKCS#1 v1.5) padding. Otherwise (the default), uses OAEP (PKCS#1 v2) padding.
See [Encrypt](http://msdn.microsoft.com/en-us/library ... ovider.enc
rypt(v=vs.110).aspx) for information.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? 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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -String $credential.Password -ForUser | Out-File MySecret.txt
Demonstrates that `Protect-CString` can encrypt a `SecureString`. This functionality was added in Carbon 2.4.0.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>$cipherText = Protect-CString -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 --------------------------
PS C:\\>Protect-CString -String 's0000p33333r s33333cr33333t' -Credential (Get-Credential 'builduser')
Demonstrates how to use `Protect-CString` 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-CString`. Encrypting as a
specific user won't work over PowerShell remoting.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>Protect-CString -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-CRsaKeyPair` function will create a key pair for you, if you've got a Windows SDK installed.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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 --------------------------
PS C:\\>Protect-CString -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.
RELATED LINKS
New-CRsaKeyPair
Unprotect-CString
http://msdn.microsoft.com/en-us/library ... ddata.aspx