ConvertTo-SecureString

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

Converte texto simples 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. Ele também pode converter texto sem formatação em cadeias de caracteres seguras. É utilizado 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 armazenado em um arquivo para uso posterior.

Se a cadeia de caracteres padrão que está sendo convertida foi criptografada usando ConvertFrom-SecureString uma chave especificada, essa mesma chave deve ser fornecida como o valor do parâmetro Key ou SecureKey do ConvertTo-SecureString cmdlet.

Nota

Observe que, por 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 a partir da entrada do usuário, converter a cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada e, em seguida, converter a cadeia de caracteres padrão criptografada de volta 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 Read-Host parâmetro AsSecureString do 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 $Secure conteúdo da 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 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 novamente em uma cadeia de caracteres segura. Ele salva o resultado na $Secure2 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 a partir de uma cadeia de caracteres padrão criptografada 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 Read-Host parâmetro AsSecureString do 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 texto simples em uma cadeia de caracteres segura

Este comando converte a cadeia de texto P@ssW0rD! 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, 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

Atenção

Você deve evitar o uso de 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 ajudam a proteger texto confidencial. O texto é encriptado para privacidade e é eliminado da memória do computador depois de ser utilizado. 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 para ser usada como chave. Os comprimentos de chave seguros 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 este cmdlet.

Saídas

SecureString

Este cmdlet retorna o objeto SecureString criado.

Notas

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.