ConvertTo-SecureString
SYNOPSIS
Converts encrypted standard strings to secure strings. It can also convert plain text to secure strings. It is used with ConvertFrom-SecureString and Read-Host.
SYNTAX
ConvertTo-SecureString [-string] <string> [[-secureKey] <SecureString>] [<CommonParameters>]
ConvertTo-SecureString [-string] <string> [-key <Byte[]>] [<CommonParameters>]
ConvertTo-SecureString [-string] <string> [[-asPlainText]] [[-force]] [<CommonParameters>]
DETAILED DESCRIPTION
Converts encrypted standard strings into secure strings. It can also convert plain text to secure strings. It is used with ConvertFrom-SecureStringand Read-Host. The secure string created by the cmdlet can be used with cmdlets or functions that require a parameter of type SecureString. The secure string can be converted back to an encrypted, standard string using the ConvertFrom-SecureString cmdlet. This enables it to be stored in a file for later use.
If the standard string being converted was encrypted with ConvertFrom-SecureString using a specified key, that same key must be provided as the value of the Key or SecureKey parameter of the ConvertTo-SecureString cmdlet.
PARAMETERS
-string <string>
Specifies the string to convert to a secure string.
Required? |
true |
Position? |
1 |
Default value |
|
Accept pipeline input? |
true (ByValue) |
Accept wildcard characters? |
false |
-secureKey <SecureString>
Specifies the encryption key to use when converting a secure string into an encrypted standard string. The key must be provided in the format of a secure string. The secure string is converted to a byte array before being used as the key. Valid key lengths are 16, 24, and 32 bytes.
Required? |
false |
Position? |
2 |
Default value |
|
Accept pipeline input? |
False |
Accept wildcard characters? |
false |
-key <Byte[]>
Specifies the encryption key to use when converting a secure string into an encrypted standard string. Valid key lengths are 16, 24, and 32 bytes.
Required? |
false |
Position? |
named |
Default value |
null |
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-asPlainText <SwitchParameter>
Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidential text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use this parameter to provide plain text as input, the system cannot protect that input in this manner. To use this parameter, you must also specify the Force parameter.
Required? |
false |
Position? |
2 |
Default value |
|
Accept pipeline input? |
false |
Accept wildcard characters? |
false |
-force <SwitchParameter>
Confirms that you understand the implications of using the AsPlainText parameter and still want to use it.
Required? |
false |
Position? |
3 |
Default value |
|
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
String
RETURN TYPE
Secure String
NOTES
For more information, type "Get-Help ConvertTo-SecureString -detailed". For technical information, type "Get-Help ConvertTo-SecureString -full".
When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-na me> <value1>, <value2>".
EXAMPLE 1
$pwd = read-host -assecurestring
$pwd
$pwd = convertfrom-securestring $pwd
$pwd
$pwd = convertto-securestring $pwd
$pwd
This command creates a secure string using the Read-Hostcmdlet. To create a secure string, you must type some characters and press the Enter key following the first command. It then displays the result that is stored in the $pwd variable. Because it is a secure string, the result is just the type System.Security.SecureString. It then converts the contents of the $pwd variable to an encrypted standard string by using the ConvertFrom-SecureString cmdlet. In the fourth line, it displays that encrypted, standard string. In the fifth line, it uses the ConvertTo-SecureString cmdlet to convert the encrypted standard string stored in the $pwd variable back into a secure string. The last line of the command attempts to display the secure string. The result is that the type System.Security.SecureString is displayed, confirming that the contents of the $pwd variable has been converted back to a secure string.
EXAMPLE 2
$pwd = read-host -assecurestring
$pwd
$pwd = convertfrom-securestring $pwd -key (1..16)
$pwd
$pwd > enc_pwd.txt
$pwd = convertto-securestring (get-content enc_pwd.txt) -key (1..16)
$pwd
This command creates a secure string using the Read-Hostcmdlet. To create a secure string, you must type some characters and press the Enter key following the first command. It then displays the result that is stored in the $pwd variable. Because it is a secure string, the result is just the type System.Security.SecureString. It then converts the contents of the $pwd variable to an encrypted standard string with a key value of (1..16) by using the ConvertFrom-SecureString cmdlet. In the fourth line, it displays that encrypted, standard string. In the fifth line, it uses the ConvertTo-SecureString cmdlet to convert the encrypted standard string stored in the $pwd variable back into a secure string. The last line of the command attempts to display the secure string. The result is that the type System.Security.SecureString is displayed, confirming that the contents of the $pwd variable has been converted back to a secure string.
EXAMPLE 3
$secure_string_pwd = convertto-securestring "P@ssW0rD!" -asplaintext -force
This command converts the plain text string "P@ssW0rD!" into a secure string and stores the result in the $secure_string_pwd variable. To use the AsPlainText parameter, the command must also include the Force parameter.
RELATED LINKS