Home

ProtectedData is a Windows PowerShell module which makes it easy to encrypt secret data, in such a way that it can be accessed by more than one user or computer.

If you've been working with PowerShell for a while, you've likely encountered the Export-Clixml / Import-Clixml and the ConvertFrom-SecureString / ConvertTo-SecureString cmdlets. These allow you to encrypt and save data on your computer, but with some limitations. First, these commands only encrypt SecureString objects, and second, they do so using the Data Protection API (DPAPI) by default. DPAPI is a great, user-friendly interface for encrypting and decrypting data without having to worry one bit about managing or protecting the encryption keys. The operating system takes care of all of that for you. However, DPAPI keys are stored in a user's profile; it is not possible to share the encrypted files with other users, and unless you have roaming profiles or Credential Roaming enabled, you also can't read the encrypted file yourself on any computer other than the one where it was encrypted.

The ConvertFrom-SecureString and ConvertTo-SecureString cmdlets do allow you to encrypt the data without using DPAPI, by way of their -Key or -SecureKey parameters, but then you're stuck figuring out how to protect that key. All you've really done is moved the target.

The ProtectedData module helps to solve this problem by exposing an easy-to-use interface for encryption and decryption, just like DPAPI, but one that can be used to securely share the data. It accomplishes this by using digital certificates: when you encrypt a piece of data, you specify one or more certificates that are allowed to decrypt the data. People who have those certificates (and their associated private keys) will be able to decrypt the data, but for everyone else, it's unreadable. Key management and protection has been pushed back to the operating system again; it takes care of protecting the private keys of certificates that you have installed, and you can password-protect any exported copies of those keys.

The most basic scenario for using the ProtectedData module looks like this:

$credentials = Get-Credential

$credentials |
Protect-Data -Certificate '<Your Certificate Thumbprint>' |
Export-Clixml .\SavedCredentials.xml

# It is safe to send SavedCredentials.xml in the clear to its intended recipients.
# Any user that has the same certificate installed, including its private key, can
# run this command to obtain the PSCredential object from the copy of
# SavedCredentials.xml

$credentials = Import-Clixml .\SavedCredentials.xml |
               Unprotect-Data -Certificate '<Your Certificate Thumbprint>'

There are several other parameters and commands in the module which build on this basic functionality, and I'll be adding more wiki pages documenting those functions as time allows. You can also find quite a bit of information within the module itself, starting with Get-Help about_ProtectedData. Each exported command from the module also includes comment-based help.