共用方式為

ConvertTo-SecureString

模組:
Microsoft.PowerShell.Security Module

將純文字或加密字串轉換為安全字串。

語法

Secure (預設值) 

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

PlainText 

ConvertTo-SecureString
    [-String] <String>
    [-AsPlainText]
    [-Force]
    [<CommonParameters>]

Open 

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

Description

ConvertTo-SecureString Cmdlet 會將加密的標準字串轉換成安全字串。 它也可以將純文字轉換成安全字串。 它與 ConvertFrom-SecureString 和 Read-Host搭配使用。 Cmdlet 所建立的安全字串可以搭配需要類型參數的 Cmdlet 或函式搭配使用，SecureString。 安全字串可以使用 ConvertFrom-SecureString Cmdlet 轉換回加密的標準字串。 這可讓它儲存在檔案中以供日後使用。

如果轉換的標準字串是使用指定的密鑰來加密 ConvertFrom-SecureString，則必須提供相同的密鑰作為 Key 或 SecureKey 參數 ConvertTo-SecureString Cmdlet 的值。

備註

請注意，根據 dotNet ，非 Windows 系統上不會加密 SecureString 的內容。

範例

範例 1：將安全字串轉換為加密字串

此範例示範如何從使用者輸入建立安全字串、將安全字串轉換成加密的標準字串，然後將加密的標準字串轉換回安全字串串。

PS C:\> $Secure = Read-Host -AsSecureString
PS C:\> $Secure
System.Security.SecureString
PS C:\> $Encrypted = ConvertFrom-SecureString -SecureString $Secure
PS C:\> $Encrypted
01000000d08c9ddf0115d1118c7a00c04fc297eb010000001a114d45b8dd3f4aa11ad7c0abdae98000000000
02000000000003660000a8000000100000005df63cea84bfb7d70bd6842e7efa79820000000004800000a000
000010000000f10cd0f4a99a8d5814d94e0687d7430b100000008bf11f1960158405b2779613e9352c6d1400
0000e6b7bf46a9d485ff211b9b2a2df3bd6eb67aae41
PS C:\> $Secure2 = ConvertTo-SecureString -String $Encrypted
PS C:\> $Secure2
System.Security.SecureString

第一個命令會使用 Cmdlet 的 Read-Host 參數來建立安全字串。 輸入命令之後，您輸入的任何字元都會轉換成安全字串，然後儲存在 $Secure 變數中。

第二個命令會顯示 $Secure 變數的內容。 因為 $Secure 變數包含安全字串，PowerShell 只會顯示 system.Security.SecureString 類型的。

第三個命令會使用 ConvertFrom-SecureString Cmdlet，將 $Secure 變數中的安全字串轉換成加密的標準字串。 它會將結果儲存在 $Encrypted 變數中。

第四個命令會在 $Encrypted 變數的值中顯示加密的字串。

第五個命令會使用 ConvertTo-SecureString Cmdlet，將 $Encrypted 變數中的加密標準字串轉換為安全字串。 它會將結果儲存在 $Secure2 變數中。 第六個命令會顯示 $Secure2 變數的值。 SecureString 類型表示命令成功。

範例 2：從檔案中的加密字串建立安全字串

此範例示範如何從儲存在檔案中的加密標準字串建立安全字串。

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

第一個命令會使用 Cmdlet 的 Read-Host 參數來建立安全字串。 輸入命令之後，您輸入的任何字元都會轉換成安全字串，然後儲存在 $Secure 變數中。

第二個命令會使用 ConvertFrom-SecureString Cmdlet，使用指定的金鑰，將 $Secure 變數中的安全字串轉換成加密的標準字串。 內容會儲存在 $Encrypted 變數中。

第三個命令會使用管線運算符 （|） 將 $Encrypted 變數的值傳送至 Set-Content Cmdlet，以將值儲存在 Encrypted.txt 檔案中。

第四個命令會使用 Get-Content Cmdlet 來取得 Encrypted.txt 檔案中的加密標準字串。 命令會使用管線運算符將加密字串傳送至 ConvertTo-SecureString Cmdlet，該 Cmdlet 會使用指定的金鑰將它轉換成安全字串。 結果會儲存在 $Secure2 變數中。

範例 3：將純文字字串轉換成安全字串

此命令會將純文字字串 P@ssW0rD! 轉換成安全字串，並將結果儲存在 $Secure_String_Pwd 變數中。

從 PowerShell 7 開始，使用 AsPlainText 參數時，不需要 Force 參數。 不過，包含 Force 參數可確保語句與舊版相容。

$Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force

謹慎

您應該避免在文稿或命令列中使用純文字字串。 純文本會顯示在事件記錄檔和命令歷程記錄中。

參數

-AsPlainText

指定要轉換成安全字串的純文字字串。 安全字串 Cmdlet 可協助保護機密文字。 文字會被加密以保護隱私，並在使用後從電腦記憶體中刪除。 如果您使用此參數提供純文本做為輸入，系統就無法以這種方式保護該輸入。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

PlainText
Position:1
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Force

從 PowerShell 7 開始，使用 AsPlainText 參數時，不再需要 Force 參數。 未使用 參數時，不會移除它以提供與舊版 PowerShell 的相容性。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

PlainText
Position:2
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Key

指定用來將原始安全字串轉換成加密標準字串的加密金鑰。 有效的金鑰長度為 16、24 和 32 個字節。

參數屬性

類型:

Byte[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

Open
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-SecureKey

指定用來將原始安全字串轉換成加密標準字串的加密金鑰。 金鑰必須以安全字串的格式提供。 安全字串會轉換成用作金鑰的位元組陣列。 有效的安全金鑰長度為 8、12 和 16 個代碼點。

參數屬性

類型:SecureString
預設值:None
支援萬用字元:False
不要顯示:False

參數集

Secure
Position:1
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-String

指定要轉換成安全字串的字串。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:0
必要:True
來自管線的值:True
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

String

您可以使用管道將標準加密字串傳送至此 Cmdlet。

輸出

SecureString

此 Cmdlet 會傳回建立 SecureString 物件。

備註

某些字元，例如表情符號，會對應至包含這些字元的字串中的數個碼位。 避免使用這些字元，因為它們可能會在密碼中使用時造成問題和誤解。