ConvertTo-SecureString
Converte texto sem formatação ou cadeias de caracteres criptografadas em cadeias de caracteres seguras.
Syntax
ConvertTo-SecureString
[-String] <String>
[[-SecureKey] <SecureString>]
[<CommonParameters>]
ConvertTo-SecureString
[-String] <String>
[-AsPlainText]
[-Force]
[<CommonParameters>]
ConvertTo-SecureString
[-String] <String>
[-Key <Byte[]>]
[<CommonParameters>]
Description
O ConvertTo-SecureString
cmdlet converte cadeias de caracteres padrão criptografadas em cadeias de caracteres seguras. Também pode converter o texto sem formatação em cadeias de caracteres seguras. Ele é usado com ConvertFrom-SecureString
e Read-Host
. A cadeia de caracteres segura criada pelo cmdlet pode ser usada com cmdlets ou funções que exigem um parâmetro do tipo SecureString. A cadeia de caracteres segura pode ser convertida novamente em uma cadeia de caracteres padrão criptografada usando o ConvertFrom-SecureString
cmdlet . Isso permite que ele seja armazenada em um arquivo para uso posterior.
Se a cadeia de caracteres padrão que está sendo convertida foi criptografada com ConvertFrom-SecureString
usando uma chave especificada, essa mesma chave deve ser fornecida como o valor do parâmetro Key ou SecureKey do ConvertTo-SecureString
cmdlet.
Observação
Observe que, por DotNet, o conteúdo de um SecureString não é criptografado em sistemas não Windows.
Exemplos
Exemplo 1: converter uma cadeia de caracteres segura em uma cadeia de caracteres criptografada
Este exemplo mostra como criar uma cadeia de caracteres segura da entrada do usuário, converter a cadeia de caracteres segura em uma cadeia de caracteres criptografada padrão e converter a cadeia de caracteres criptografada padrão novamente em uma cadeia de caracteres segura.
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
O primeiro comando usa o parâmetro AsSecureString do Read-Host
cmdlet para criar uma cadeia de caracteres segura. Depois de inserir o comando, todos os caracteres que você digitar serão convertidos em uma cadeia de caracteres segura e salvos na $Secure
variável .
O segundo comando exibe o conteúdo da $Secure
variável. Como a $Secure
variável contém uma cadeia de caracteres segura, o PowerShell exibe apenas o tipo System.Security.SecureString .
O terceiro comando usa o ConvertFrom-SecureString
cmdlet para converter a cadeia de caracteres segura na $Secure
variável em uma cadeia de caracteres padrão criptografada. Ele salva o resultado na $Encrypted
variável .
O quarto comando exibe a cadeia de caracteres criptografada no valor da $Encrypted
variável.
O quinto comando usa o ConvertTo-SecureString
cmdlet para converter a cadeia de caracteres padrão criptografada na $Encrypted
variável de volta em uma cadeia de caracteres segura. Ele salva o resultado na $Secure2
variável .
O sexto comando exibe o valor da $Secure2
variável. O tipo SecureString indica que o comando foi bem-sucedido.
Exemplo 2: Create uma cadeia de caracteres segura de uma cadeia de caracteres criptografada em um arquivo
Este exemplo mostra como criar uma cadeia de caracteres segura de uma cadeia de caracteres criptografada padrão que é salva em um arquivo.
$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)
O primeiro comando usa o parâmetro AsSecureString do Read-Host
cmdlet para criar uma cadeia de caracteres segura. Depois de inserir o comando, todos os caracteres que você digitar serão convertidos em uma cadeia de caracteres segura e salvos na $Secure
variável .
O segundo comando usa o ConvertFrom-SecureString
cmdlet para converter a cadeia de caracteres segura na variável em $Secure
uma cadeia de caracteres padrão criptografada usando a chave especificada. O conteúdo é salvo na $Encrypted
variável .
O terceiro comando usa um operador de pipeline (|
) para enviar o valor da $Encrypted
variável para o Set-Content
cmdlet , que salva o valor no arquivo Encrypted.txt.
O quarto comando usa o Get-Content
cmdlet para obter a cadeia de caracteres padrão criptografada no arquivo Encrypted.txt. O comando usa um operador de pipeline para enviar a cadeia de caracteres criptografada para o cmdlet , que a ConvertTo-SecureString
converte em uma cadeia de caracteres segura usando a chave especificada.
Os resultados são salvos na $Secure2
variável .
Exemplo 3: converter uma cadeia de caracteres de texto sem formatação em uma cadeia de caracteres segura
Esse comando converte a cadeia de caracteres de texto sem formatação P@ssW0rD!
em uma cadeia de caracteres segura e armazena o resultado na $Secure_String_Pwd
variável .
A partir do PowerShell 7, o parâmetro Force não é necessário ao usar o parâmetro AsPlainText . No entanto, incluir o parâmetro Force garante que a instrução seja compatível com versões anteriores.
$Secure_String_Pwd = ConvertTo-SecureString "P@ssW0rD!" -AsPlainText -Force
Cuidado
Evite usar cadeias de caracteres de texto sem formatação no script ou na linha de comando. O texto sem formatação pode aparecer nos logs de eventos e nos logs de histórico de comandos.
Parâmetros
-AsPlainText
Especifica uma cadeia de caracteres de texto sem formatação para converter em uma cadeia de caracteres segura. Os cmdlets de cadeia de caracteres segura protegem texto confidencial. O texto é criptografado para privacidade e é excluído da memória do computador depois que ele é usado. Se você usar esse parâmetro para fornecer texto sem formatação como entrada, o sistema não poderá proteger essa entrada dessa maneira.
Type: | SwitchParameter |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
A partir do PowerShell 7, o parâmetro Force não é mais necessário ao usar o parâmetro AsPlainText . Embora o parâmetro não seja usado, ele não foi removido para fornecer compatibilidade com versões anteriores do PowerShell.
Type: | SwitchParameter |
Position: | 2 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Key
Especifica a chave de criptografia usada para converter a cadeia de caracteres segura original na cadeia de caracteres padrão criptografada. Os comprimentos de chave válidos são de 16, 24 e 32 bytes.
Type: | Byte[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SecureKey
Especifica a chave de criptografia usada para converter a cadeia de caracteres segura original na cadeia de caracteres padrão criptografada. A chave deve ser fornecida no formato de uma cadeia de caracteres segura. A cadeia de caracteres segura será convertida em uma matriz de bytes a ser usada como a chave. Os comprimentos de chave segura válidos são 8, 12 e 16 pontos de código.
Type: | SecureString |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-String
Especifica a cadeia de caracteres a ser convertida em uma cadeia de caracteres segura.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Entradas
Você pode redirecionar uma cadeia de caracteres criptografada padrão para esse cmdlet.
Saídas
Esse cmdlet retorna o objeto SecureString criado.
Observações
Alguns caracteres, como emoticons, correspondem a vários pontos de código na cadeia de caracteres que os contém. Evite usar esses caracteres porque eles podem causar problemas e mal-entendidos quando usados em uma senha.