Cmdlets

Choose a cmdlet from the list on the left or search for a specific cmdlet. Choose a cmdlet from the list or search for a specific cmdlet.
About Help  Providers  Aliases  Modules
 

ConvertTo-SecureString

ConvertTo-SecureString

Microsoft.PowerShell.Core

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] [-AsPlainText] [-Force] [<CommonParameters>]

ConvertTo-SecureString [-String] [-Key] [<CommonParameters>]

ConvertTo-SecureString [-String] [-SecureKey] [<CommonParameters>]

Detailed Description

The ConvertTo-SecureString cmdlet converts encrypted standard strings into secure strings. It can also convert plain 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 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

-AsPlainText <SwitchParameter>

Aliases

none

Required?

false

Position

1

Default value

False

Accept pipeline input?

False

Accept wildcard characters?

false

-Force <SwitchParameter>

Aliases

none

Required?

false

Position

2

Default value

False

Accept pipeline input?

False

Accept wildcard characters?

false

-Key <Byte[]>

Aliases

none

Required?

false

Position

named

Default value

None

Accept pipeline input?

False

Accept wildcard characters?

false

-SecureKey <SecureString>

Aliases

none

Required?

false

Position

1

Default value

None

Accept pipeline input?

False

Accept wildcard characters?

false

-String <String>

Aliases

none

Required?

true

Position

0

Default value

None

Accept pipeline input?

True (ByValue)

Accept wildcard characters?

false

Input Type

System.String

Return Type

System.Security.SecureString

Notes

Examples

Example 1: Convert a secure string to an encrypted string

This example shows how to create a secure string from user input, convert the secure string to an encrypted standard 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 enter the command, any characters that you type are converted into a secure string and then saved in the $Secure variable.

The second command displays the contents of the $Secure variable. Because the $Secure variable contains a secure string, 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 into an encrypted standard string. It saves the result in the $Encrypted variable.

The fourth command displays the encrypted 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 value of the $Secure2 variable. The SecureString type indicates that the command was successful.

PS C:\>$Secure = Read-Host -AsSecureString
PS C:\>$Secure
System.Security.SecureString PS C:\>$Encrypted = ConvertFrom-SecureString -SecureString $Secure
PS C:\>$Encrypted
01000000d08c9ddf0115d1118c7a00c04fc297eb010000001a114d45b8dd3f4aa11ad7c0abdae9800000000002000000000003660000a8000000100000005df63cea84bfb7d70bd6842e7
efa79820000000004800000a000000010000000f10cd0f4a99a8d5814d94e0687d7430b100000008bf11f1960158405b2779613e9352c6d14000000e6b7bf46a9d485ff211b9b2a2df3bd
6eb67aae41 PS C:\>$Secure2 = ConvertTo-SecureString -String $Encrypted
PS C:\>$Secure2
System.Security.SecureString

Example 2: Create a secure string from an encrypted string in a file

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 enter the command, any characters that you type are converted into a secure string and then saved in the $Secure variable.

The second command uses the ConvertFrom-SecureString cmdlet to convert the secure string in the $Secure variable into 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 cmdlet, 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.

PS C:\>$Secure = Read-Host -AsSecureString
PS C:\>$Encrypted = ConvertFrom-SecureString -SecureString $Secure -Key (1..16)
PS C:\>$Encrypted | Set-Content Encrypted.txt
PS C:\>$Secure2 = Get-Content Encrypted.txt | ConvertTo-SecureString -Key (1..16)

Example 3: Convert a plain text string to a secure string

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 Force parameter must also be included in the command.

PS C:\>$Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force

Online Version
ConvertFrom-SecureString