ConvertTo-SecureString

  • Referência
Módulo:
Microsoft.PowerShell.Security

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. É 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 o uso de uma chave especificada, essa mesma chave deverá ser fornecida como o valor do parâmetro Key ou SecureKey do ConvertTo-SecureString cmdlet.

Observação

Observe que, de acordo com o DotNet, o conteúdo de um SecureString não é criptografado em sistemas que não sejam 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 digitados são convertidos em uma cadeia de caracteres segura e, em seguida, salvos na $Secure variável.

O segundo comando exibe o conteúdo da $Secure variável. Como a variável contém uma cadeia de caracteres segura, o $Secure 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 $Encrypted resultado na 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 variável de volta em $Encrypted uma cadeia de caracteres segura. Ele salva o $Secure2 resultado na variável. O sexto comando exibe o $Secure2 valor da variável. O tipo SecureString indica que o comando foi bem-sucedido.

Exemplo 2: Criar uma cadeia de caracteres segura a partir 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 digitados são convertidos em uma cadeia de caracteres segura e, em seguida, salvos na $Secure variável.

O segundo 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 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 ConvertTo-SecureString cmdlet, que a 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 P@ssW0rD! de texto sem formatação em uma cadeia de caracteres segura e armazena $Secure_String_Pwd o resultado na variável.

A partir do PowerShell 7, o parâmetro Force não é necessário ao usar o parâmetro AsPlainText . No entanto, a inclusão do 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 em logs de eventos e 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 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 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

String

Você pode canalizar uma cadeia de caracteres criptografada padrão para esse cmdlet.

Saídas

SecureString

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.