Skip to content

Protect Data and Unprotect Data (the basics)

Jump to bottom
dlwyatt edited this page Oct 12, 2014 · 5 revisions

The Protect-Data and Unprotect-Data commands are what you use to encrypt and decrypt something that you want to keep secret. The current syntax of these commands looks like this:

Protect-Data [-InputObject] <Object> [[-CertificateThumbprint] <string[]>] [[-Certificate] <X509Certificate2[]>] 
[[-Password] <securestring[]>] [[-PasswordIterationCount] <int>] [-UseLegacyPadding] [-SkipCertificateVerification] 
[<CommonParameters>]


Unprotect-Data -InputObject <Object> -Certificate <X509Certificate2> [-SkipCertificateVerification] 
[<CommonParameters>]

Unprotect-Data -InputObject <Object> -CertificateThumbprint <string> [-SkipCertificateVerification] 
[<CommonParameters>]

Unprotect-Data -InputObject <Object> -Password <securestring> [-SkipCertificateVerification] [<CommonParameters>]

The -InputObject parameter of the Protect-Data command is the piece of secret data that you want to encrypt. This may only be one of the types specified by the Get-ProtectedDataSupportedTypes command; currently, these are String, SecureString, PSCredential, and Byte[] . If you want to encrypt a type of data other than strings / secure strings / pscredentials, you will need to handle the serialization to and from a byte array yourself, and the ProtectedData module will take care of encrypting that byte array. Protect-Data will output a custom object containing the encrypted payload, and enough other information to decrypt it when a user with a valid certificate or password requests to do so.

The -InputObject parameter of Unprotect-Data, on the other hand, is the object that was produced by the Protect-Data command, and the output of Unprotect-Data will be whatever object was originally encrypted (string, SecureString, PSCredential, or byte array.)

The Certificates referred to by either the -CertificateThumbprint or the -Certificate parameters can be either RSA certificates or ECDH (Elliptic Curve Diffie-Hellman) certificates. They must have, at a minimum, the Key Encipherment usage extension (for RSA) or the Key Agreement usage extension (for ECDH). You can encrypt the data using multiple certificates, if you like; any one of them can be used to decrypt the data later.

As a backup mechanism, you may also pass in one or more SecureString objects to the Password parameter. This allows you to decrypt the data later by specifying the same password(s). While this does not help you to protect secret data without user interaction, it does give you a way to recover data later should you somehow lose the certificate or its private key.

The other optional parameters modify the behavior in the following ways:

  • -SkipCertificateVerification: This switch causes the module to ignore the validity period of a certificate, and to not bother checking whether it was issued by a trusted publisher or has been revoked. This is mainly useful if you want to leverage a self-signed certificate for the ProtectedData module.

  • -UseLegacyPadding: When you encrypt data using an RSA certificate, by default, it uses the OAEP (Optional Asymmetric Encryption Padding) algorithm. Some certificates will allow you to encrypt data successfully using this scheme, but for some reason, will not decrypt the data. I don't yet know how to identify ahead of time whether this is going to be the case, but in those situations, you may use the -UseLegacyPadding switch to tell the module to use PKCS#1 v1.5 padding instead, which should work.

  • -PasswordIterationCount: When using the -Password parameter, an encryption key is derived from that password using the PBKDF2 algorithm. You can tweak the iteration count of this algorithm, if desired; a higher iteration count makes the key derivation take longer, making it harder to crack by brute force. The default number of iterations is 1000.

Clone this wiki locally