ConvertTo-SecureString

模組:

Microsoft.PowerShell.Security

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

語法

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

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

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 的值。

注意

如需 SecureString 數據保護的詳細資訊，請參閱 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
Position:	1
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Force

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

類型:	SwitchParameter
Position:	2
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Key

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

類型:	Byte[]
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SecureKey

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

類型:	SecureString
Position:	1
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-String

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

類型:	String
Position:	0
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

輸入

String

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

輸出

SecureString

此 Cmdlet 會傳回建立 SecureString 物件。

備註

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

相關連結

• ConvertFrom-SecureString
• Read-Host