powershellscripts.com

Tutorials  PowerShell Cmdlet Help for ConvertFrom-SecureString



NAME
ConvertFrom-SecureString

SYNOPSIS
Converts a secure string into an encrypted standard string.

SYNTAX
ConvertFrom-SecureString [-Key ] [-SecureString] []

ConvertFrom-SecureString [[-SecureKey] ] [-SecureString] []


DESCRIPTION
The ConvertFrom-SecureString cmdlet converts a secure string (System.Security.SecureString) into an encrypted stand
ard string (System.String). Unlike a secure string, an encrypted standard string can be saved in a file for later u
se. The encrypted standard string can be converted back to its secure string format by using the ConvertTo-SecureSt
ring cmdlet. If an encryption key is specified by using the Key or SecureKey parameters, the Rijndael encryption al
gorithm is used. The specified key must have a length of 128, 192, or 256 bits because those are the key lengths su
pported by the Rijndael encryption algorithm. If no key is specified, the Windows Data Protection API (DPAPI) is us
ed to encrypt the standard string representation.


PARAMETERS
-Key
Specifies the encryption key as a byte array.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-SecureKey
Specifies the encryption key as a secure string. The secure string value is converted to a byte array before be
ing used as the key.

Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false

-SecureString
Specifies the secure string to convert to an encrypted standard string.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.Security.SecureString
You can pipe a SecureString object to ConvertFrom-SecureString.


OUTPUTS
System.String
ConvertFrom-SecureString returns a standard string object.


NOTES


To create a secure string from characters that are typed at the command prompt, use the AsSecureString paramete
r of the Read-Host cmdlet.

When you use the Key or SecureKey parameters to specify a key, the key length must be correct. For example, a k
ey of 128 bits can be specified as a byte array of 16 digits. Similarly, 192-bit and 256-bit keys correspond to
byte arrays of 24 and 32 digits, respectively.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>$securestring = read-host -assecurestring


Description
-----------
This command creates a secure string from characters that you type at the command prompt. After entering the comman
d, type the string you want to store as a secure string. An asterisk (*) will be displayed to represent each charac
ter that you type.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>$standardstring = convertfrom-securestring $securestring


Description
-----------
This command converts the secure string in the $securestring variable to an encrypted standard string. The resultin
g encrypted standard string is stored in the $standardstring variable.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$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)

C:\PS> $standardstring = convertfrom-securestring $securestring -key $key


Description
-----------
These commands use the Rijndael algorithm to convert the secure string stored in the $securestring variable to an e
ncrypted standard string with a 192-bit key. The resulting encrypted standard string is stored in the $standardstri
ng variable.

The first command stores a key in the $key variable. The key is an array of 24 digits, all of which are less than 2
56.

Because each digit represents a byte (8 bits), the key has 24 digits for a total of 192 bits (8 x 24). This is a va
lid key length for the Rijndael algorithm. Each individual value is less than 256, which is the maximum value that
can be stored in an unsigned byte.

The second command uses the key in the $key variable to convert the secure string to an encrypted standard string.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113287
ConvertTo-SecureString
Read-Host