ConvertTo-SecureString

Convert an encrypted standard string into a secure string, can also convert plain text into a secure string.

Syntax
      ConvertTo-SecureString [-String] String 
         [[-secureKey] SecureString]
            [CommonParameters]
    
      ConvertTo-SecureString [-String] String 
         [-key Byte[]]
            [CommonParameters]

      ConvertTo-SecureString [-String] String 
         [[-asPlainText] [-force]]
            [CommonParameters]

key
   -String SecureString
       The string to convert to a secure string
        
   -secureKey SecureString
       The encryption key as a secure string,
       this is converted to a byte array before being used as the key.
       Valid key lengths are 16, 24, and 32 bytes
        
   -key Byte
       The encryption key as a byte array.
       Valid key lengths are 16, 24, and 32 bytes.

   -asPlainText 
       A plain text string to convert to a secure string.
       The text is not encrypted so the input is not protected/confidential.
       To use this option, you must also specify -Force
        
    -force 
       Set this to confirm that you understand the security risks of using PlainText

If the standard string being converted was previously encrypted with ConvertFrom-SecureString using a specified key, that same key must be provided as the value of the -Key or -SecureKey parameter of ConvertTo-SecureString.

The specified encryption key must have a length of 128, 192, or 256 bits because those are the key lengths supported by the AES encryption algorithm. If no key is specified, the Windows Data Protection API (DPAPI) is used to encrypt the standard string representation.

By default, ConvertTo-SecureString will use the current user’s password to generate an encryption key, which it will store in the user profile (eg. %Userprofile%\Application Data\Microsoft\Crypto\RSA\User SID for RSA key).

However, unless this user account has been set as roaming profile, the encryption key on one computer will not synchronize with another.

Examples

Create a secure string from plain text, you should not actually do this because the string "P@ssW0rD!" is readable in the script:

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

Create a secure string using the Read-Host cmdlet:

PS C:\> $secure = read-host "Please enter your secure code" -assecurestring
PS C:\> # now encrypt the string:
PS C:\> $encrypted = convertfrom-securestring $secure
PS C:\> # and save it to disc:
PS C:\> $encrypted > password.txt

Read an encrypted string from disc and convert to a secure string:

PS C:\> $secure = convertto-securestring (get-content password.txt)

“Happy as we are, times may alter; we may be bitten with some impulse towards change, and many things may seem too wonderful for us to resist, too exciting not to catch at, if we do not know that they are but phases of what has been before and withal ruinous, deceitful, and sordid” - William Morris

Related PowerShell Cmdlets

ConvertFrom-SecureString - Convert a secure string into an encrypted standard string.
Get-Credential - Get a security credential (username/password).
Read-Host - Read a line of input from the host console.
CIPER - Encrypt or Decrypt files and folders.


 
Copyright © 1999-2024 SS64.com
Some rights reserved