Adding or removing recipient keys from a piece of data you've already encrypted

Overview

---

Once you've used the Protect-Data command, you get back a custom object which contains all of the information needed to decrypt the payload, provided the caller can provide the correct certificate / private key, or password (depending on what parameters were used when Protect-Data was called.)

You may wish to add new certificates or passwords to this encrypted data later, or remove certificates / passwords that were originally used. These operations are covered by the Add-ProtectedDataCredential and Remove-ProtectedDataCredential commands, which have the following syntax:

Add-ProtectedDataCredential -InputObject <Object> -Certificate <X509Certificate2> [-UseLegacyPaddingForDecryption] [-NewCertificate <Object[]>] [-UseLegacyPadding] [-NewPassword <securestring[]>] 
[-PasswordIterationCount <int>] [-Passthru] [<CommonParameters>]

Add-ProtectedDataCredential -InputObject <Object> -Password <securestring> [-NewCertificate <Object[]>] [-UseLegacyPadding] [-NewPassword <securestring[]>] [-PasswordIterationCount <int>] [-Passthru] [<CommonParameters>]


Remove-ProtectedDataCredential [-InputObject] <Object> [[-Certificate] <Object[]>] [[-Password] <securestring[]>] [-Passthru] [<CommonParameters>]

In both of these commands, the -InputObject parameter accepts an object that was created by Protect-Data earlier, and this object may be piped in.

As you can see, Add-ProtectedDataCredential has a set of parameters that is essentially a combination of those used in Protect-Data and Unprotect-Data. The -Certificate or -Password parameters are used to decrypt the key information from the original protected data, and the -NewCertificate and -NewPassword parameters are used to specify the new certs or passwords that are to be added. Aside from that, all of the parameters do the same things as the parameters of the same names in Protect-Data and Unprotect-Data, with one exception. Add-ProtectedDataCredential has a -Passthru switch, which causes the ProtectedData object to be output on the pipeline. By default, this command just modifies the object in memory and produces no output, similar to Add-Member.

Remove-ProtectedDataCredential is much simpler; just specify the input object and the password, certificate or thumbprint that you want to remove, and it'll be done. Like with Add-ProtectedDataCredential, Remove-ProtectedDataCredential has a -Passthru switch.

Examples

---

$firstCert = 'Cert:\CurrentUser\My\26C4800B0B39DF1B06CEEA30DEB546AFFA62D464'
$secondCert = 'Cert:\CurrentUser\My\464D26AFFA645BED03AEEC60B1FD93B0B0084C62'

$secret = 'This is a secret.'

$protectedData | Protect-Data -Certificate $firstCert

# Adding the second certificate

$protectedData | Add-ProtectedDataCredential -Certificate $firstCert -NewCertificate $secondCert

# At this point, $protectedData can be decrypted by either certificate.
# Now, we'll remove the first certificate.

$protectedData | Remove-ProtectedDataCredential -Certificate $firstCert

# Now the $protectedData object can only be decrypted by the second certificate.

$decryptedString = $protectedData | Unprotect-Data -Certificate $secondCert