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

ConvertFrom-SecureString

Read-Host