ConvertTo-SecureString
Converte texto sem formatação 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. 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 cmdlet ConvertFrom-SecureString. 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 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.
Nota
Para obter mais informações sobre a proteção de dados SecureString, consulte Qual é o nível de segurança de 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 da entrada do usuário, converter a cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada e 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 que você digitar serão convertidos em uma cadeia de caracteres segura e 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 de uma cadeia de caracteres criptografada em um arquivo
Este exemplo mostra como criar uma cadeia de caracteres segura 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 que você digitar serão convertidos em uma cadeia de caracteres segura e 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 o 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 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 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 -ForceCuidado
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 protegem texto confidencial. O texto é criptografado para privacidade e é excluído da memória do computador depois de 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.
| Tipo: | SwitchParameter |
| Cargo: | 1 |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | 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.
| Tipo: | SwitchParameter |
| Cargo: | 2 |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | 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[] |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | 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 de 8, 12 e 16 pontos de código.
| Tipo: | SecureString |
| Cargo: | 1 |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-String
Especifica a cadeia de caracteres a ser convertida em uma cadeia de caracteres segura.
| Tipo: | String |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
Entradas
Você pode canalizar uma cadeia de caracteres criptografada padrão para este 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.
