Problem
You want to request sensitive information from the user, but want to do this as securely as possible.
Solution
To securely handle sensitive information, store it in a SecureString whenever possible. The ReadHost cmdlet (with the –AsSecureString parameter) lets you prompt the user for (and handle) sensitive information by returning the user’s response as a SecureString:
PS >$secureInput = ReadHost AsSecureString "Enter your private key" Enter your private key: ******************* PS >$secureInput System.Security.SecureString
Discussion
When you use any string in the .NET Framework (and therefore PowerShell), it retains that string so that it can efficiently reuse it later. Unlike most .NET data, unused strings persist even after you finish using them. When this data is in memory, there is always the chance that it could get captured in a crash dump, or swapped to disk in a paging operation. Because some data (such as passwords and other confidential information) may be sensitive, the .NET Framework includes the SecureString class—a container for text data that the framework encrypts when it stores it in memory. Code that needs to interact with the plaintext data inside a SecureString does so as securely as possible.
When a cmdlet author asks you for sensitive data (for example, an encryption key), the best practice is to designate that parameter as a SecureString to help keep your information confidential. You can provide the parameter with a SecureString variable as input, or the host prompts you for the SecureString if you do not provide one. PowerShell also supports two cmdlets (ConvertToSecureString and ConvertFromSecureString) that allow you to securely persist this data to disk.
Credentials are a common source of sensitive information.
By default, the SecureString cmdlets use Windows’ data protection API when they convert your SecureString to and from its text representation. The key it uses to encrypt your data is based on your Windows logon credentials, so only you can decrypt the data that you’ve encrypted. If you want the exported data to work on another system or separate user account, you can use the cmdlet options that let you provide an explicit key. PowerShell treats this sensitive data as an opaque blob—and so should you.
However, there are many instances when you may want to automatically provide the SecureString input to a cmdlet rather than have the host prompt you for it. In these situations, the ideal solution is to use the ConvertToSecureString cmdlet to import a previously exported SecureString from disk. This retains the confidentiality of your data and still lets you automate the input.
If the data is highly dynamic (for example, coming from a CSV), then the ConvertToSecureString cmdlet supports an –AsPlainText parameter:
$secureString = ConvertToSecureString "Kinda Secret" AsPlainText –Force
Since you’ve already provided plaintext input in this case, placing this data in a SecureString no longer provides a security benefit. To prevent a false sense of security, the cmdlet requires the Force parameter to convert plaintext data into a SecureString.
Once you have data in a SecureString, you may want to access its plaintext representation. PowerShell doest’t provide a direct way to do this, as that defeats the purpose of a SecureString. If you still want to convert a SecureString to plain text, you have two options:
1. Use the GetNetworkCredential() method of the PsCredential class
$secureString = ReadHost AsSecureString $temporaryCredential = NewObject ` System.Management.Automation.PsCredential "TempUser",$secureString $unsecureString = $temporaryCredential.GetNetworkCredential().Password
2. Use the .NET Framework’s Marshal class
$secureString = ReadHost AsSecureString $unsecureString = [Runtime.InteropServices.Marshal]::PtrToStringAuto( [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureString))
