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>]

说明

该 cmdlet 将 ConvertTo-SecureString 加密的标准字符串转换为安全字符串。 它还可以将纯文本转换为安全字符串。 它与 ConvertFrom-SecureString 和 Read-Host. cmdlet 创建的安全字符串可用于需要 SecureString 类型的参数的 cmdlet 或函数。 可以使用 cmdlet 将安全字符串转换回加密的标准字符串 ConvertFrom-SecureString 。 这样，就可以将其存储在文件中供以后使用。

如果使用指定的密钥对转换的标准字符串进行了 ConvertFrom-SecureString 加密，则必须提供该密钥作为 cmdlet 的 Key 或 SecureKey 参数 ConvertTo-SecureString 的值。 如果在创建安全字符串时未指定密钥，则字符串由 Windows 数据保护 API（DPAPI）加密。

注释

非Windows系统上不会加密 SecureString 的内容。 有关 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，该 cmdlet 将该值保存在 Encrypted.txt 文件中。

第四个命令使用 Get-Content cmdlet 获取 Encrypted.txt 文件中的加密标准字符串。 该命令使用管道运算符将加密字符串发送到 cmdlet，该 cmdlet ConvertTo-SecureString 使用指定的密钥将其转换为安全字符串。 结果保存在变量中 $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 对象。

备注

某些字符（如表情符号）对应于包含它们的字符串中的多个代码点。 避免使用这些字符，因为它们可能会导致密码中使用时出现问题和误解。

相关链接

• ConvertFrom-SecureString
• Read-Host