Creating and managing keys is an important part of the cryptographic process. Symmetric algorithms require the creation of a key and an initialization vector (IV). The key must be kept secret from anyone who should not decrypt your data. The IV does not have to be secret, but should be changed for each session.

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

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.

Note

Note that per DotNet, thecontents of a SecureString are not encrypted on non-Windows systems.

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, 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.

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.

Generate Secret Key From 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 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.

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

This command converts the plain text string [email protected]!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.

Parameters

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.

Type:SwitchParameter
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Confirms that you understand the implications of using the AsPlainText parameter and still want to use it.

Type:SwitchParameter
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

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.

Type:Byte[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

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.

Type:SecureString
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Specifies the string to convert to a secure string.

String
Type:String
Position:0
Default value:None
Accept pipeline input:True (ByValue)
Accept wildcard characters:False

Inputs

You can pipe a standard encrypted string to ConvertTo-SecureString.

Outputs

ConvertTo-SecureString returns a SecureString object.

Related Links

There are multiple ways of generating an encryption key. Most implementations rely on a random object. All examples mentioned here use a secure cryptographic randomizer.

PowerShell

Base64

Hex

C#

The code snippets below can be run from LINQPad or by copying the following code into a new project and referencing System.Security.

Generate String From Regex

Base64

Hex

OpenSSL

OpenSSL is well known for its ability to generate certificates but it can also be used to generate random data.

Base64

Generates 32 random bytes (256bits) in a base64 encoded output:

Plaintext

Generates 32 random characters (256bits):

Be aware that strings parsed by NServiceBus do not use extended ASCII which limits the key range to 7 bits per character.

Related Articles

  • Message Property Encryption
    Encrypt message fragments using property encryption.
  • Security
    Security features for messages, transports, and persisters.
Coments are closed
Scroll to top