ConvertTo-SecureString

模組:

Microsoft.PowerShell.Security

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

Syntax

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

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

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

Description

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

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

注意

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

範例

範例 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 AsSecureString 參數來建立安全字串。 輸入命令之後，您輸入的任何字元都會轉換成安全字串，然後儲存在變數中 $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 AsSecureString 參數來建立安全字串。 輸入命令之後，您輸入的任何字元都會轉換成安全字串，然後儲存在變數中 $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 可協助保護機密文字。 文字會加密以取得隱私權，並在使用計算機記憶體之後從計算機記憶體中刪除。 如果您使用此參數提供純文本做為輸入，系統就無法以這種方式保護該輸入。

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

-Force

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

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

-Key

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

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

-SecureKey

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

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

-String

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

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

輸入

String

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

輸出

SecureString

此 Cmdlet 會傳回已建立 的 SecureString 物件。

備註

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

相關連結

• ConvertFrom-SecureString
• Read-Host