PowerShell How-To

How To Save and Read Sensitive Data with PowerShell

If you deal with private data, automate how you access it with this handy tip.

• By Adam Bertram
• 07/20/2017

Unfortunately, IT professionals have to deal with sensitive information all the time. That information could be in the form of passwords, proprietary company information or anything that you'd rather the world not see. When performing work manually, we deal with this information by interactively working with it. We fill in password prompts, access a "secret" folder while logged in as a domain administrator and so on. This works fine but what happens when we need to automate these processes? Interactivity is the enemy of automation!

We need to automatically read this information without our intervention. This is where you sometimes see people get lazy and add passwords in plain text into the script. That's a big no-no, and there's a better way.

PowerShell has native support for something called the data protection API (DPAPI). DPAPI is a built-in way Windows users can use certificates to encrypt and decrypt information on the fly which is perfect for PowerShell scripting. No username and password required. We simply need a certificate installed which can be self-signed.

Credentials
Saving and retrieving credentials are the most common reason to encrypt sensitive information. Luckily, PowerShell gives us a built-in way to both store and retrieve username and passwords securely using the commands Get-Credential, Export-CliXml and Import-CliXml.

Let's say I have a script that requires an alternate username and password to run some process. I want this process automated so I can't prompt for the password when needed and I definitely don't want to get lazy and store it in plain text! I need to save it somewhere before the process runs so I can securely retrieve it when I need to.

To save a PSCredential object to the file system, we'll use Get-Credential to provide an interactive input to supply the username and password and then we'll use Export-CliXml to export that credential object to the file system encrypted. The encryption is done automatically when Export-CliXml is invoked.

Here's how you'd save a PSCredential object to a file:

Get-Credential | Export-CliXml  -Path MyCredential.xml

That's it! I'll now look at the XML file generated. Notice that the username (userhere) is not encrypted but the password is. PowerShell is smart enough to automatically encrypt the password.

<Objs  Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">

  <Obj RefId="0">

  <TN RefId="0">

  <T>System.Management.Automation.PSCredential</T>

  <T>System.Object</T>

  </TN>

  <ToString>System.Management.Automation.PSCredential</ToString>

  <Props>

  <S N="UserName">userhere</S>

  <SS N="Password">01000000d08c9ddf0115d1118c7a00c04fc297eb01000000a3b8761fb71df340a3482fbcd5a052a6000000000200000000001066000000010000200000003ae416571efa69efb8966aca5613d0be8a2d7f1a77b4c05f44c46a338d30d9ab000000000e800000000200002000000010dcd8455d68a4c4a758cf1efa40055c29b1e146f0323d51e0e3c80532fdfd4720000000e3ca95d7d6af9eb454c1dd0ee1ee2a389c01f4306e29a3e8e55bc71a434f0d26400000002d48bff96293d7f0407933703efa038c409a7bb8f3b715d30b1423a57754251b895210357df13a3acc584a73c011359362b625f2a465f6c7c181b73016c7a9f6</SS>

  </Props>

  </Obj>

</Objs>

Once the credential is saved, you'd place this file somewhere where your script has access to. Then, inside of the script, instead of using plain-text passwords, you'd have a line that looks like this:

$credential = Import-CliXml -Path  <PathToXml>\MyCredential.xml

At this point, you can use use the PSCredential object using any -Credential parameter you desire. If, for some reason, you don't need a PSCredential object and would like to just retrieve the password, this can also be done using:

$credential.GetNetworkCredential().Password

Simple Strings
If just needing to encrypt text, you may not want to store an entire object on the file system like we did with credentials. Storing and retieving encrypted text is a little bit different. PowerShell doesn't have a built-in way to store encrypted text to the file system but it can encrypt text in memory. It's just up to you to store it somewhere either in a file, a database, wherever. Encrypting strings in PowerShell comes in the form of the ConvertTo-SecureString cmdlet. This is a cmdlet that "converts" text into a secure string in memory.

Perhaps I have some sensitive text I need to encrypt. To do that, I simply need to run ConvertTo-SecureString using a few parameters.

'nuclearlaunchcodes' | ConvertTo-SecureString  -AsPlainText -Force

  

  PS> 'nuclearlaunchcodes' | ConvertTo-SecureString  -AsPlainText -Force

System.Security.SecureString

This isn't going to help much in our script because it's not saved anywhere and it's in the form of an object. We need an encrypted string and we need it saved to a file. To do that, we can do this:

'nuclearlaunchcodes' |  ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString |  Set-Content -Path secretstuff.txt

This gives us a file that looks like this:

01000000d08c9ddf0115d1118c7a00c04fc297eb01000000a3b8761fb71df340a3482fbcd5a052a600000000020000000000106600000001000020000000e0770395880f1007c2244c889ceb789afc49bed31e6aa0432212c7a073077dd6000000000e80000000020000200000009f0d2e635c40f44787ecac307202ca5a94c0003a6f3cf1ae04e82ae43379d74c30000000232de4f35495e40bb284fc24238d5af05bbeb2ae477039da49096d1376b6a0b451b39bb9ed44afd51103c236e13833714000000033aaad98afc8f629ec41ca195b1df1473e0e1bb62d0e3bdffa72003ec23f5919e5e3c1a1499e68a1872c5243fe73341decc4237a9a39fcb3c8a70d4414ddffc4

Now that the encrypted string is saved, it's time to retrieve it. Unfortunately, there's no good way to do this with PowerShell and we're forced to use some messy .NET but wrap this little snippet in a function and you'll never have to worry about it again.

PS> $secretStuff = Get-Content  -Path secretstuff.txt | ConvertTo-SecureString

  PS>  [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((($secretStuff))))

nuclearlaunchcodes