ConvertTo-SecureString
將純文字或加密字串轉換為安全字串。
語法
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 指令長將加密的標準字串轉換為安全字串。 它也能將純文字轉換為安全字串。 它與 以及 一起使用ConvertFrom-SecureStringRead-Host。 由 cmdlet 建立的安全字串可用於需要 SecureString 參數的 cmdlet 或函式。 安全字串可利用 ConvertFrom-SecureString cmdlet 轉換回加密的標準字串。 這讓它能儲存在檔案中以供日後使用。
若被轉換的標準字串是用 ConvertFrom-SecureString 指定金鑰加密，則該金鑰必須作為 cmdlet 的 金鑰 或 SecureKey 參數 ConvertTo-SecureString 值提供。 若您在建立安全字串時未指定金鑰，該字串會被 Windows 資料保護 API（DPAPI）加密。
Note
SecureString 的內容在非 Windows 系統上並未加密。 如需 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 指令碼，指令碼會將該值儲存在 Encrypted.txt 檔案中。
第四個指令使用 Get-Content cmdlet 取得 Encrypted.txt 檔案中的加密標準字串。 該指令使用管線運算子將加密字串傳送至 ConvertTo-SecureString cmdlet，並利用指定金鑰將其轉換為安全字串。
結果會儲存在變數中 $Secure2 。
範例 3：將純文字字串轉換為安全字串
此指令將純文字串 P@ssW0rD! 轉換為安全字串，並將結果儲存在變數中 $Secure_String_Pwd 。
從 PowerShell 7 開始，使用 AsPlainText 參數時不再需要 Force 參數。 然而，加入 Force 參數可確保該語句與早期版本相容。
$Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force
Caution
你應該避免在腳本或命令列中使用純文字字串。 純文字可以顯示在事件日誌和指令歷史日誌中。
參數
-AsPlainText
指定一個純文字字串，要轉換成安全字串。 安全字串指令小子有助於保護機密文字。 文字會加密以保障隱私，使用後會從電腦記憶體中刪除。 如果你用這個參數提供純文字作為輸入，系統就無法以這種方式保護該輸入。
參數屬性
| 類型: | 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 物件。
備註
有些字元，例如表情符號，對應包含它們的字串中的多個代碼點。 避免使用這些字元，因為在密碼中使用時可能會造成問題和誤解。
