< Back
Protect-Data
Post
NAME Protect-Data
SYNOPSIS
Encrypts an object using one or more digital certificates and/or passwords.
SYNTAX
Protect-Data [-InputObject] <Object> [-Certificate <Object[]>] [-UseLegacyPadding] [-Password <SecureString[]>]
[-PasswordIterationCount <Int32>] [-SkipCertificateVerification] [<CommonParameters>]
DESCRIPTION
Encrypts an object using a randomly-generated AES key. AES key information is encrypted using one or more
certificate public keys and/or password-derived keys, allowing the data to be securely shared among multiple users
and computers.
If certificates are used, they must be installed in either the local computer or local user's certificate stores,
and the certificates' Key Usage extension must allow Key Encipherment (for RSA) or Key Agreement (for ECDH). The
private keys are not required for Protect-Data.
PARAMETERS
-InputObject <Object>
The object that is to be encrypted. The object must be of one of the types returned by the
Get-ProtectedDataSupportedTypes command.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Certificate <Object[]>
Zero or more RSA or ECDH certificates that should be used to encrypt the data. The data can later be decrypted
by using the same certificate (with its private key.) You can pass an X509Certificate2 object to this
parameter, or you can pass in a string which contains either a path to a certificate file on the file system,
a path to the certificate in the Certificate provider, or a certificate thumbprint (in which case the
certificate provider will be searched to find the certificate.)
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-UseLegacyPadding [<SwitchParameter>]
Optional switch specifying that when performing certificate-based encryption, PKCS#1 v1.5 padding should be
used instead of the newer, more secure OAEP padding scheme. Some certificates may not work properly with OAEP
padding
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Password <SecureString[]>
Zero or more SecureString objects containing password that will be used to derive encryption keys. The data
can later be decrypted by passing in a SecureString with the same value.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-PasswordIterationCount <Int32>
Optional positive integer value specifying the number of iteration that should be used when deriving
encryption keys from the specified password(s). Defaults to 50000.
Higher values make it more costly to crack the passwords by brute force.
Required? false
Position? named
Default value 50000
Accept pipeline input? false
Accept wildcard characters? false
-SkipCertificateVerification [<SwitchParameter>]
Deprecated parameter, which will be removed in a future release. Specifying this switch will generate a
warning.
Required? false
Position? named
Default value False
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
Object
Object must be one of the types returned by the Get-ProtectedDataSupportedTypes command.
OUTPUTS
PSObject
The output object contains the following properties:
CipherText : An array of bytes containing the encrypted data
Type : A string representation of the InputObject's original type (used when decrypting back to the original
object later.)
KeyData : One or more structures which contain encrypted copies of the AES key used to protect the ciphertext, and
other identifying information about the way this copy of the keys was protected, such as Certificate Thumbprint,
Password Hash, Salt values, and Iteration count.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>$encryptedObject = Protect-Data -InputObject $myString -CertificateThumbprint
CB04E7C885BEAE441B39BC843C85855D97785D25 -Password (Read-Host -AsSecureString -Prompt 'Enter password to encrypt')
Encrypts a string using a single RSA or ECDH certificate, and a password. Either the certificate or the password
can be used when decrypting the data.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>$credential | Protect-Data -CertificateThumbprint 'CB04E7C885BEAE441B39BC843C85855D97785D25',
'B5A04AB031C24BCEE220D6F9F99B6F5D376753FB'
Encrypts a PSCredential object using two RSA or ECDH certificates. Either private key can be used to later decrypt
the data.
RELATED LINKS
Unprotect-Data
Add-ProtectedDataCredential
Remove-ProtectedDataCredential
Get-ProtectedDataSupportedTypes
SYNOPSIS
Encrypts an object using one or more digital certificates and/or passwords.
SYNTAX
Protect-Data [-InputObject] <Object> [-Certificate <Object[]>] [-UseLegacyPadding] [-Password <SecureString[]>]
[-PasswordIterationCount <Int32>] [-SkipCertificateVerification] [<CommonParameters>]
DESCRIPTION
Encrypts an object using a randomly-generated AES key. AES key information is encrypted using one or more
certificate public keys and/or password-derived keys, allowing the data to be securely shared among multiple users
and computers.
If certificates are used, they must be installed in either the local computer or local user's certificate stores,
and the certificates' Key Usage extension must allow Key Encipherment (for RSA) or Key Agreement (for ECDH). The
private keys are not required for Protect-Data.
PARAMETERS
-InputObject <Object>
The object that is to be encrypted. The object must be of one of the types returned by the
Get-ProtectedDataSupportedTypes command.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Certificate <Object[]>
Zero or more RSA or ECDH certificates that should be used to encrypt the data. The data can later be decrypted
by using the same certificate (with its private key.) You can pass an X509Certificate2 object to this
parameter, or you can pass in a string which contains either a path to a certificate file on the file system,
a path to the certificate in the Certificate provider, or a certificate thumbprint (in which case the
certificate provider will be searched to find the certificate.)
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-UseLegacyPadding [<SwitchParameter>]
Optional switch specifying that when performing certificate-based encryption, PKCS#1 v1.5 padding should be
used instead of the newer, more secure OAEP padding scheme. Some certificates may not work properly with OAEP
padding
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Password <SecureString[]>
Zero or more SecureString objects containing password that will be used to derive encryption keys. The data
can later be decrypted by passing in a SecureString with the same value.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-PasswordIterationCount <Int32>
Optional positive integer value specifying the number of iteration that should be used when deriving
encryption keys from the specified password(s). Defaults to 50000.
Higher values make it more costly to crack the passwords by brute force.
Required? false
Position? named
Default value 50000
Accept pipeline input? false
Accept wildcard characters? false
-SkipCertificateVerification [<SwitchParameter>]
Deprecated parameter, which will be removed in a future release. Specifying this switch will generate a
warning.
Required? false
Position? named
Default value False
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
Object
Object must be one of the types returned by the Get-ProtectedDataSupportedTypes command.
OUTPUTS
PSObject
The output object contains the following properties:
CipherText : An array of bytes containing the encrypted data
Type : A string representation of the InputObject's original type (used when decrypting back to the original
object later.)
KeyData : One or more structures which contain encrypted copies of the AES key used to protect the ciphertext, and
other identifying information about the way this copy of the keys was protected, such as Certificate Thumbprint,
Password Hash, Salt values, and Iteration count.
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>$encryptedObject = Protect-Data -InputObject $myString -CertificateThumbprint
CB04E7C885BEAE441B39BC843C85855D97785D25 -Password (Read-Host -AsSecureString -Prompt 'Enter password to encrypt')
Encrypts a string using a single RSA or ECDH certificate, and a password. Either the certificate or the password
can be used when decrypting the data.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>$credential | Protect-Data -CertificateThumbprint 'CB04E7C885BEAE441B39BC843C85855D97785D25',
'B5A04AB031C24BCEE220D6F9F99B6F5D376753FB'
Encrypts a PSCredential object using two RSA or ECDH certificates. Either private key can be used to later decrypt
the data.
RELATED LINKS
Unprotect-Data
Add-ProtectedDataCredential
Remove-ProtectedDataCredential
Get-ProtectedDataSupportedTypes