ConvertTo-SecureString
Converte texto simples ou cadeias de caracteres criptografadas em cadeias de caracteres seguras.
Sintaxe
ConvertTo-SecureString
[-String] <String>
[[-SecureKey] <SecureString>]
[<CommonParameters>] ConvertTo-SecureString
[-String] <String>
[-AsPlainText]
[-Force]
[<CommonParameters>] ConvertTo-SecureString
[-String] <String>
[-Key <Byte[]>]
[<CommonParameters>] Description
O cmdlet ConvertTo-SecureString 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 cmdlet ConvertFrom-SecureString. Isso permite que ele seja armazenado em um arquivo para uso posterior.
Se a cadeia de caracteres padrão que está a ser convertida foi criptografada com ConvertFrom-SecureString usando uma chave especificada, essa mesma chave deve ser fornecida como o valor do parâmetro Chave ou SecureKey do cmdlet ConvertTo-SecureString.
Observação
Para obter mais informações sobre SecureString proteção de dados, consulte Quão seguro é o SecureString?.
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 parâmetro AsSecureString do cmdlet Read-Host 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 variável $Secure.
O segundo comando exibe o conteúdo da variável $Secure. Como a variável $Secure contém uma cadeia de caracteres segura, o PowerShell exibe apenas o tipo de System.Security.SecureString.
O terceiro comando usa o cmdlet ConvertFrom-SecureString para converter a cadeia de caracteres segura na variável $Secure em uma cadeia de caracteres padrão criptografada. Ele salva o resultado na variável $Encrypted.
O quarto comando exibe a cadeia de caracteres criptografada no valor da variável $Encrypted.
O quinto comando usa o cmdlet ConvertTo-SecureString para converter a cadeia de caracteres padrão criptografada na variável $Encrypted novamente em uma cadeia de caracteres segura. Ele salva o resultado na variável $Secure2. O sexto comando exibe o valor da variável $Secure2. 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 parâmetro AsSecureString do cmdlet Read-Host 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 variável $Secure.
O segundo comando usa o cmdlet ConvertFrom-SecureString para converter a cadeia de caracteres segura na variável $Secure em uma cadeia de caracteres padrão criptografada usando a chave especificada. O conteúdo é salvo na variável $Encrypted.
O terceiro comando usa um operador de pipeline (|) para enviar o valor da variável $Encrypted para o cmdlet Set-Content, que salva o valor no arquivo Encrypted.txt.
O quarto comando usa o cmdlet Get-Content 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 ConvertTo-SecureString, que a converte em uma cadeia de caracteres segura usando a chave especificada.
Os resultados são salvos na variável $Secure2.
Exemplo 3: Converter uma cadeia de texto simples em uma cadeia de caracteres segura
Este comando converte a cadeia de caracteres de texto sem formatação P@ssW0rD! em uma cadeia de caracteres segura e armazena o resultado na variável $Secure_String_Pwd.
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 -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 cadeias de caracteres seguras 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.
| Tipo: | SwitchParameter |
| Position: | 1 |
| Default value: | None |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Force
A partir do PowerShell 7, o parâmetro Force deixa de ser 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.
| Tipo: | SwitchParameter |
| Position: | 2 |
| Default value: | None |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | Byte[] |
| Position: | Named |
| Default value: | None |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | 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.
| Tipo: | SecureString |
| Position: | 1 |
| Default value: | None |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-String
Especifica a cadeia de caracteres a ser convertida em uma cadeia de caracteres segura.
| Tipo: | String |
| Position: | 0 |
| Default value: | None |
| Necessário: | True |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | 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.
