ConvertTo-SecureString
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.SecureStringO 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 -ForceAtençã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
Você pode canalizar uma cadeia de caracteres criptografada padrão para este cmdlet.
Saídas
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.
