Compartilhar via

ConvertFrom-SecureString

Módulo:
Microsoft.PowerShell.Security Module

Converte uma cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada.

Sintaxe

Secure (Padrão) 

ConvertFrom-SecureString
    [-SecureString] <SecureString>
    [[-SecureKey] <SecureString>]
    [<CommonParameters>]

AsPlainText 

ConvertFrom-SecureString
    [-SecureString] <SecureString>
    [-AsPlainText]
    [<CommonParameters>]

Open 

ConvertFrom-SecureString
    [-SecureString] <SecureString>
    [-Key <Byte[]>]
    [<CommonParameters>]

Description

O cmdlet ConvertFrom-SecureString converte uma cadeia de caracteres segura (System.Security.SecureString) em uma cadeia de caracteres padrão criptografada (System.String). Ao contrário de uma cadeia de caracteres segura, uma cadeia de caracteres padrão criptografada pode ser salva em um arquivo para uso posterior. A cadeia de caracteres padrão criptografada pode ser convertida novamente em seu formato de cadeia de caracteres segura usando o cmdlet ConvertTo-SecureString.

Se uma chave de criptografia for especificada usando os parâmetros Key ou SecureKey, o algoritmo de criptografia AES (Advanced Encryption Standard) será usado. A chave especificada deve ter um comprimento de 128, 192 ou 256 bits, pois esses são os comprimentos de chave compatíveis com o algoritmo de criptografia AES. Se nenhuma chave for especificada, a DPAPI (API de Proteção de Dados do Windows) será usada para criptografar a representação de cadeia de caracteres padrão.

Observação

Para obter mais informações sobre a proteção de dados do SecureString, consulte Quão seguro é o SecureString?.

Exemplos

Exemplo 1: Criar uma cadeia de caracteres segura

$SecureString = Read-Host -AsSecureString

Esse comando cria uma cadeia de caracteres segura a partir de caracteres que você digita no prompt de comando. Depois de inserir o comando, digite a cadeia de caracteres que você deseja armazenar como uma cadeia de caracteres segura. Um asterisco (*) é exibido para representar cada caractere que você digitar.

Exemplo 2: Converter uma cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada

$StandardString = ConvertFrom-SecureString $SecureString

Esse comando converte a cadeia de caracteres segura na variável $SecureString em uma cadeia de caracteres padrão criptografada. A cadeia de caracteres padrão criptografada resultante é armazenada na variável $StandardString.

Exemplo 3: Converter uma cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada com uma chave de 192 bits

$Key = (3,4,2,3,56,34,254,222,1,1,2,23,42,54,33,233,1,34,2,7,6,5,35,43)
$StandardString = ConvertFrom-SecureString $SecureString -Key $Key

Esses comandos usam o algoritmo AES (Advanced Encryption Standard) para converter a cadeia de caracteres segura armazenada na variável $SecureString em uma cadeia de caracteres padrão criptografada com uma chave de 192 bits. A cadeia de caracteres padrão criptografada resultante é armazenada na variável $StandardString.

O primeiro comando armazena uma chave na variável $Key. A chave é uma matriz de 24 numerais decimais, cada um deles deve ter menos de 256 para caber em um único byte não assinado.

Como cada numeração decimal representa um único byte (8 bits), a chave tem 24 dígitos para um total de 192 bits (8 x 24). Esse é um comprimento de chave válido para o algoritmo AES.

O segundo comando usa a chave na variável $Key para converter a cadeia de caracteres segura em uma cadeia de caracteres padrão criptografada.

Exemplo 4: Converter uma cadeia de caracteres segura diretamente em uma cadeia de caracteres de texto sem formatação

$secureString = ConvertTo-SecureString -String 'Example' -AsPlainText
$secureString # 'System.Security.SecureString'
ConvertFrom-SecureString -SecureString $secureString -AsPlainText # 'Example'

Parâmetros

-AsPlainText

Quando configurado, ConvertFrom-SecureString converterá cadeias de caracteres seguras em texto simples descriptografado como saída.

Esse parâmetro foi adicionado no PowerShell 7.0.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

AsPlainText
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Key

Especifica a chave de criptografia como uma matriz de bytes.

Propriedades do parâmetro

Tipo:

Byte[]

Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Open
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SecureKey

Especifica a chave de criptografia como uma cadeia de caracteres segura. O valor da cadeia de caracteres segura é convertido em uma matriz de bytes antes de ser usado como a chave.

Propriedades do parâmetro

Tipo:SecureString
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

Secure
Cargo:1
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SecureString

Especifica a cadeia de caracteres segura a ser convertida em uma cadeia de caracteres padrão criptografada.

Propriedades do parâmetro

Tipo:SecureString
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:True
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

SecureString

Você pode canalizar um objeto SecureString para este cmdlet.

Saídas

String

Esse cmdlet retorna a cadeia de caracteres de texto sem formatação criada.

Observações

  • Para criar uma cadeia de caracteres segura com base em caracteres digitados no prompt de comando, use o parâmetro AsSecureString do cmdlet Read-Host.
  • Quando você usa os parâmetros Key ou SecureKey para especificar uma chave, o comprimento da chave deve estar correto. Por exemplo, uma chave de 128 bits pode ser especificada como uma matriz de bytes de 16 numerais decimais. Da mesma forma, as chaves de 192 bits e 256 bits correspondem a matrizes de bytes de 24 e 32 numerais decimais, respectivamente.
  • 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.