ConvertFrom-SecureString
SYNOPSIS
Converts a secure string into an encrypted standard string.
SYNTAX
ConvertFrom-SecureString [-secureString] <SecureString> [[-secureKey] <SecureString>] [<CommonParameters>]
ConvertFrom-SecureString [-secureString] <SecureString> [-key <Byte[]>] [<CommonParameters>]
DETAILED DESCRIPTION
Converts a secure string (System.Security.SecureString) into an encrypted standard string (System.String). Unlike a secure string, the encrypted standard string can be saved in a file for later use. The encrypted standard string can be converted back to its secure string format by using the ConvertTo-SecureStringCmdlet. If an encryption key is explicitly specified by using the Key or SecureKey parameters, the Rijndael encryption algorithm is used. The key specified must have a length of 128, 192 or 256 bits because those are the key lengths supported by the Rijndael encryption algorithm. If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation.
PARAMETERS
-secureString <SecureString>
Specifies the secure string to convert to an encrypted standard string.
|
Required? |
true |
|
Position? |
1 |
|
Default value |
null |
|
Accept pipeline input? |
true (ByValue) |
|
Accept wildcard characters? |
false |
-secureKey <SecureString>
Specifies the encryption key as a secure string. The secure string value is converted to a byte array before being used as the key.
|
Required? |
false |
|
Position? |
2 |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-key <Byte[]>
Specifies the encryption key as a byte array.
|
Required? |
false |
|
Position? |
named |
|
Default value |
null |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".
INPUT TYPE
SecureString
RETURN TYPE
String
NOTES
For more information, type "Get-Help ConvertFrom-SecureString -detailed". For technical information, type "Get-Help ConvertFrom-SecureString -full".
When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".
Use the Read-Host Cmdlet, with the asSecureString parameter specified, to create a secure string by typing at the command prompt.
When you specify a key explicity by using the Key or SecureKey parameters, the key length must be correct. For example, a key of 128 bits can be specified as a byte array of 16 digits. Similarly, 192 and 256 bit keys correspond to byte arrays of 24 and 32 digits.
EXAMPLE 1
$securestring = read-host -assecurestring
This command enables you to create a secure string by typing at the command prompt. After entering the command, type the string you want to store as a secure string. An asterisk (*) will be displayed in response to each character you type.
EXAMPLE 2
$standardstring = convertfrom-securestring $securestring
This command converts a secure string stored in the $securestring variable to an encrypted standard string. The resulting encrypted standard string is stored in the $standardstring variable and can be displayed by typing $standard string.
EXAMPLE 3
$key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43)
$standardstring = convertfrom-securestring $securestring -key $key
This command converts a secure string stored in the $securestring variable to an encrypted standard string using the Rijndael algorithm with a 192 bit key. The resulting encrypted standard string is stored in the $standardstring variable and can be displayed by typing $standardstring. The key is stored in the $key variable and passed to the Cmdlet as the value of the Key parameter. The key is an array of 24 digits, all of which are less than 256. There are 24 because each represents a byte (8 bits) and 8 bits*24= 192 bits, which is a valid key length for the Rijndael algorithm. Each individual value is less than 256 because that is the maximum value that can be stored in an unsigned byte.
RELATED LINKS