powershellscripts.com

Tutorials  PowerShell Cmdlet Help for ConvertTo-SecureString



NAME
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 [-Key ] [-String] []

ConvertTo-SecureString [[-AsPlainText]] [[-Force]] [-String] []

ConvertTo-SecureString [[-SecureKey] ] [-String] []


DESCRIPTION
The ConvertTo-SecureString cmdlet converts encrypted standard strings into secure strings. It can also convert plai
n text to secure strings. It is used with ConvertFrom-SecureString and 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 b
e 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
-AsPlainText []
Specifies a plain text string to convert to a secure string. The secure string cmdlets help protect confidentia
l text. The text is encrypted for privacy and is deleted from computer memory after it is used. If you use thi
s 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 []
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

-Key
Specifies the encryption key to use when converting a secure string into an encrypted standard string. Valid ke
y lengths are 16, 24, and 32 bytes.

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

-SecureKey
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

-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


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.String
You can pipe a standard encrypted string to ConvertTo-SecureString.


OUTPUTS
System.Security.SecureString
ConvertTo-SecureString returns a SecureString object.


NOTES





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

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

C:\PS> $secure
System.Security.SecureString

C:\PS> $encrypted = convertfrom-securestring -securestring $secure
C:\PS> $encrypted
01000000d08c9ddf0115d1118c7a00c04fc297eb010000001a114d45b8dd3f4aa11ad7c0abdae9800000000002000000000003660000a800000
0100000005df63cea84bfb7d70bd6842e7
efa79820000000004800000a000000010000000f10cd0f4a99a8d5814d94e0687d7430b100000008bf11f1960158405b2779613e9352c6d1400
0000e6b7bf46a9d485ff211b9b2a2df3bd
6eb67aae41

C:\PS> $secure2 = convertto-securestring -string $encrypted
C:\PS> $secure2
System.Security.SecureString


Description
-----------
This example shows how to create a secure string from user input, convert the secure string to an encrypted standar
d string, and then convert the encrypted standard string back to a secure string.

The first command uses the AsSecureString parameter of the Read-Host cmdlet to create a secure string. After you en
ter the command, any characters that you type are converted into a secure string and then saved in the $secure vari
able.

The second command displays the contents of the $secure variable. Because the $secure variable contains a secure st
ring, Windows PowerShell displays only the System.Security.SecureString type.

The third command uses the ConvertFrom-SecureString cmdlet to convert the secure string in the $secure variable int
o an encrypted standard string. It saves the result in the $encrypted variable. The fourth command displays the enc
rypted string in the value of the $encrypted variable.

The fifth command uses the ConvertTo-SecureString cmdlet to convert the encrypted standard string in the $encrypted
variable back into a secure string. It saves the result in the $secure2 variable. The sixth command displays the v
alue of the $secure2 variable. The SecureString type indicates that the command was successful.





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

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

C:\PS> $encrypted = convertfrom-securestring -secureString $secure -key (1..16)

C:\PS> $encrypted | set-content encrypted.txt

C:\PS> $secure2 = get-content encrypted.txt | convertto-securestring -key (1..16)


Description
-----------
This example shows how to create a secure string from an encrypted standard string that is saved in a file.

The first command uses the AsSecureString parameter of the Read-Host cmdlet to create a secure string. After you en
ter the command, any characters that you type are converted into a secure string and then saved in the $secure vari
able.

The second command uses the ConvertFrom-SecureString cmdlet to convert the secure string in the $secure variable in
to an encrypted standard string by using the specified key. The contents are saved in the $encrypted variable.

The third command uses a pipeline operator (|) to send the value of the $encrypted variable to the Set-Content cmdl
et, which saves the value in the Encrypted.txt file.

The fourth command uses the Get-Content cmdlet to get the encrypted standard string in the Encrypted.txt file. The
command uses a pipeline operator to send the encrypted string to the ConvertTo-SecureString cmdlet, which converts
it to a secure string by using the specified key. The results are saved in the $secure2 variable.





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

C:\PS>$secure_string_pwd = convertto-securestring "P@ssW0rD!" -asplaintext -force


Description
-----------
This command converts the plain text string "P@ssW0rD!" into a secure string and stores the result in the $secure_s
tring_pwd variable. To use the AsPlainText parameter, the Force parameter must also be included in the command.






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