Como criptografar e descriptografar dados Como especificar uma chave mestra Como fornecer entrada Como especificar o local de saída Como usar um contexto de criptografia Como armazenar parâmetros em um arquivo de configuração

Como usar a interface de linha de comando do SDK de criptografia da AWS

Este tópico explica como usar os parâmetros na CLI de criptografia da AWS. Para ver exemplos, consulte Exemplos da interface de linha de comando do SDK de criptografia da AWS. Para obter a documentação completa, consulte Leia os documentos.

Tópicos

Como criptografar e descriptografar dados
Como especificar uma chave mestra
Como fornecer entrada
Como especificar o local de saída
Como usar um contexto de criptografia
Como armazenar parâmetros em um arquivo de configuração

Como criptografar e descriptografar dados

A CLI de criptografia da AWS usa os recursos do SDK de criptografia da AWS para facilitar a criptografia e a descriptografia de dados com segurança.

Quando você criptografa dados na CLI de criptografia da AWS, você especifica seus dados de texto simples e uma chave mestra, como uma Chave mestra do cliente (CMK) do AWS Key Management Service (AWS KMS) . Se estiver usando um provedor de chaves mestras personalizado, você precisará especificar o provedor. Você também especifica locais de saída para a mensagem criptografada e para os metadados sobre a operação de criptografia. Um contexto de criptografia é opcional, mas recomendado.
```
aws-encryption-cli --encrypt --input myPlaintextData \
                   --master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
                   --output myEncryptedMessage \
                   --metadata-output ~/metadata \
                   --encryption-context purpose=test 
```
A CLI de criptografia da AWS obtém uma chave de dados exclusiva da chave mestra e criptografa seus dados. Ela retorna uma mensagem criptografada e os metadados sobre a operação. A mensagem criptografada contém os dados criptografados (texto cifrado) e uma cópia criptografada da chave de dados. Você não precisa se preocupar com o armazenamento, o gerenciamento ou a perda da chave de dados.
Ao descriptografar os dados, você passa sua mensagem criptografada, o contexto de criptografia opcional e o local para a saída do texto não criptografado e os metadados. Se estiver usando um provedor de chaves mestras personalizado, você também fornece a chave mestra. Se estiver usando uma CMK do AWS KMS, o AWS KMS derivará a chave mestra da mensagem criptografada.
```
aws-encryption-cli --decrypt --input myEncryptedMessage \
                   --output myPlaintextData \
                   --metadata-output ~/metadata \
                   --encryption-context purpose=test
```
A CLI de criptografia da AWS usa a chave mestra para descriptografar a chave de dados na mensagem criptografada. Em seguida, ela usa a chave de dados para descriptografar os dados. Ela retorna os dados em texto não criptografado e os metadados sobre a operação.

Como especificar uma chave mestra

Ao criptografar dados na CLI de criptografia da AWS, você precisa especificar uma chave mestra. Você pode usar uma Chave mestra do cliente (CMK) do AWS KMS ou uma chave mestra de um provedor de chaves mestras personalizado. O provedor de chaves mestras personalizado pode ser qualquer provedor de chaves mestras compatível com o Python.

Para especificar uma chave mestra, use o parâmetro --master-keys (-m). Seu valor é uma coleção de atributos com o formato attribute=value. Os atributos que você usa dependem do provedor de chaves mestras e do comando.

AWS KMS. Em comandos de encriptação, tem de especificar um --master-keys parâmetro com um chave atributo. Os outros atributos são opcionais. Em comandos decrypt, o parâmetro --master-keys é opcional e só pode ter um atributo profile.
provedor de chaves mestras personalizado Você deve especificar o parâmetro --master-keys em cada comando. O valor do parâmetro deve ter os atributos key e provider.

Você pode incluir vários parâmetros --master-keys no mesmo comando.

Atributos do parâmetro de chave mestra

O valor do parâmetro --master-keys consiste nos seguintes atributos e seus valores.

Se um nome ou valor de atributo incluir espaços ou caracteres especiais, coloque o nome e o valor entre aspas. Por exemplo: --master-keys key=12345 "provider=my cool provider".

Chave Especifique uma chave mestra

Use o atributo key para identificar uma chave mestra. O valor pode ser qualquer identificador de chave que o provedor de chaves mestras reconheça.


--master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab

Em um comando encrypt, cada valor do parâmetro --master-keys deve incluir pelo menos um atributo key e um valor. Você pode usar vários atributos key em cada valor do parâmetro --master-keys.


aws-encryption-cli --encrypt --master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d

Em comandos encrypt que usam CMKs do AWS KMS, o valor da chave pode ser o ID da chave, o ARN da chave, um nome de alias ou um ARN de alias. Por exemplo, este comando encrypt usa um ARN do alias no valor do atributo key. Para obter detalhes sobre os identificadores de chave para uma CMK do AWS KMS, consulte Identificadores de chave no AWS Key Management Service Developer Guide.


aws-encryption-cli --encrypt --master-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias

Em comandos decrypt que usam um provedor de chaves mestras personalizado, os atributos key e provider são necessários. O atributo key não é permitido em comandos decrypt que usam uma CMK do AWS KMS.


aws-encryption-cli --decrypt --master-keys provider='myProvider' key='100101'

: Provider Especifique o provedor de chaves mestras

O atributo provider identifica o provedor de chaves mestras. O valor padrão é aws-kms que representa o AWS KMS. Se você estiver usando um provedor de chaves mestras diferente, o atributo provider será obrigatório.


--master-keys key=12345 provider=my_custom_provider

Para obter mais informações sobre o uso de provedores de chaves mestras personalizados (não do AWS KMS), consulte o tópico Configuração avançada no arquivo README do repositório da CLI do AWS Encryption SDK.

Região Especifique um AWS Região

Use o atributo region para especificar a região da AWS de uma CMK do AWS KMS. Esse atributo é válido apenas em comandos encrypt e somente quando o provedor de chaves mestras for o AWS KMS.


--encrypt --master-keys key=alias/primary-key region=us-east-2

Os comandos do CLI de criptografia da AWS usa a região da AWS especificada no valor de atributo da chave se ele incluir uma região, como uma ARN. Se o valor da chave especificar uma região da AWS, o atributo da região é ignorado.

O atributo region tem precedência sobre outras especificações de região. Se você não usar um atributo region, os comandos da CLI de criptografia da AWS usarão a região da AWS especificada em seu perfil nomeado da AWS CLI, se existir, ou seu perfil padrão.

Perfil Especificar um perfil designado

Use o atributo profile para especificar um perfil nomeado da AWS CLI. Os perfis nomeados podem incluir credenciais e uma região da AWS. Esse atributo é válido somente quando o provedor de chaves mestras é o AWS KMS.


--master-keys key=alias/primary-key profile=admin-1

Você pode usar o atributo profile para especificar credenciais alternativas em comandos encrypt e decrypt. Em um comando encrypt, a CLI de criptografia da AWS usa a região da AWS no perfil nomeado apenas quando o valor de key não inclui uma região e não há nenhum atributo region. Em um comando decrypt, a região da AWS no perfil de nome é ignorada.

Como especificar várias chaves mestras

Você pode especificar várias chaves mestras em cada comando.

Se você especificar mais de uma chave mestra, a primeira chave mestra gerará (e criptografará) a chave de dados usada para criptografar seus dados. As outras chaves mestras só criptografam a chave de dados. A mensagem criptografada resultante contém os dados criptografados ("texto cifrado") e uma coleção de chaves de dados criptografadas, criptografadas por cada chave mestra. Qualquer uma das chaves mestras podem descriptografar uma chave de dados e descriptografar os dados.

Há duas maneiras de especificar várias chaves mestras:

Incluir vários atributos key em um valor do parâmetro --master-keys.


$cmk_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$cmk_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef

--master-keys key=$cmk_oregon key=$cmk_ohio

Incluir vários parâmetros --master-keys no mesmo comando. Use essa sintaxe quando os valores dos atributos que você especificar não se aplicarem a todas as chaves mestras no comando.
```
--master-keys region=us-east-2 key=alias/primary_CMK \
--master-keys region=us-west-1 key=alias/primary_CMK
```

Como fornecer entrada

A operação de criptografia na CLI de criptografia da AWS usa os dados de texto não criptografado como entrada e retorna uma mensagem criptografada. A operação de descriptografia usa uma mensagem criptografada como entrada e retorna dados de texto não criptografado.

O parâmetro --input (-i), que informa à CLI de criptografia da AWS onde localizar a entrada, é necessário em todos os comandos da CLI de criptografia da AWS.

Você pode fornecer entrada de qualquer uma das seguintes formas:

Usar um arquivo.
```
--input myData.txt
```
Usar um padrão de nome de arquivo.
```
--input testdir/*.xml
```
Use um diretório ou um padrão de nome de diretório. Quando a entrada é um diretório, o parâmetro --recursive (-r, -R) é necessário.
```
--input testdir --recursive
```
Redirecionar a entrada para o comando (stdin). Use um valor de - para o parâmetro --input. (O parâmetro --input sempre é necessário.)
```
echo 'Hello World' | aws-encryption-cli --encrypt --input -
```

Como especificar o local de saída

O parâmetro --output informa à CLI de criptografia da AWS onde gravar os resultados da operação de criptografia ou descriptografia. Ele é necessário em todos os comandos da CLI de criptografia da AWS. A CLI de criptografia da AWS cria um novo arquivo de saída para cada arquivo de entrada na operação.

Se um arquivo de saída já existir, por padrão, a CLI de criptografia da AWS imprime um aviso e, em seguida, substitui o arquivo. Para evitar a substituição, use o parâmetro --interactive, que solicita sua confirmação antes de substituir, ou --no-overwrite, que ignora a entrada se a saída puder provocar uma substituição. Para suprimir o aviso de substituição, utilize --quiet. Para capturar erros e avisos do CLI de criptografia da AWS, utilize o 2>&1 operador de redirecionamento para os escrever para o fluxo de saída.

nota

Os comandos que substituem arquivos de saída começam excluindo o arquivo de saída. Se o comando falhar, o arquivo de saída talvez já tenha sido excluído.

Você pode definir o local da saída de várias maneiras.

Especificar um nome de arquivo. Se você especificar um caminho para o arquivo, todos os diretórios no caminho devem existir antes do comando ser executado.
```
--output myEncryptedData.txt
```
Especificar um diretório. O diretório de saída deve existir antes do comando ser executado.

Se a entrada contiver subdiretórios, o comando reproduzirá os subdiretórios no diretório especificado.
```
--output Test
```
Quando o local de saída for um diretório (sem nomes de arquivos), a CLI de criptografia da AWS cria nomes de arquivos de saída com base nos nomes de arquivo de entrada mais um sufixo. Adicionar operações de encriptação .encrypted para o nome do ficheiro de entrada e as operações do desencripto .decrypted. Para alterar o sufixo, utilize o --suffix parâmetro.

Por exemplo, se encriptar file.txt, o comando encriptado cria file.txt.encrypted. Se descodificar file.txt.encrypted, o comando decrippt cria file.txt.encrypted.decrypted.
Gravar na linha de comando (stdout). Insira um valor de - para o parâmetro --output. Você pode usar --output - para redirecionar a saída em outro comando ou programa.
```
--output -
```

Como usar um contexto de criptografia

A CLI de criptografia da AWS permite que você forneça um contexto de criptografia em comandos encrypt e decrypt. Ele não é necessário, mas é uma melhor prática criptográfica que recomendamos.

Um contexto de criptografia é um tipo de dados autenticados adicionais arbitrários e que não são segredos. Na CLI de criptografia da AWS, o contexto de criptografia consiste em uma coleção de pares name=value. Você pode usar qualquer conteúdo nos pares, incluindo informações sobre os arquivos; dados que o ajudam a encontrar a operação de criptografia em logs; ou dados que suas concessões ou políticas exigem.

Em um comando encrypt

O contexto de criptografia que você especifica em um comando encrypt, junto com qualquer par que o CMM adicionar, é associado de maneira criptográfica aos dados criptografados. Ele também é incluído (em não criptografado) na mensagem criptografada que o comando retorna. Se você estiver usando uma Chave mestra do cliente (CMK) do AWS KMS, o contexto de criptografia também poderá ser exibido em texto simples em registros e logs de auditoria, como o AWS CloudTrail.

O exemplo a seguir mostra um contexto de criptografia com três pares name=value.


--encryption-context purpose=test dept=IT class=confidential

Em um comando decrypt

Em um comando decrypt, o contexto de criptografia ajuda a confirmar se você está descriptografando a mensagem criptografada correta.

Não é necessário fornecer um contexto de criptografia em um comando decrypt, mesmo que um contexto de criptografia tenha sido usado na criptografia. No entanto, se você fizer isso, a CLI de criptografia da AWS verificará se cada elemento no contexto de criptografia do comando decrypt corresponde a um elemento no contexto de criptografia da mensagem criptografada. Se um elemento não corresponder, o comando decrypt falhará.

Por exemplo, o comando a seguir descriptografa a mensagem criptografada somente se o contexto de criptografia incluir dept=IT.


aws-encryption-cli --decrypt --encryption-context dept=IT ...

Um contexto de criptografia é uma parte importante de sua estratégia de segurança. No entanto, ao escolher um contexto de criptografia, lembre-se de que seus valores não são secretos. Não inclua dados confidenciais no contexto de criptografia.

Como especificar um contexto de criptografia

Em um comando encrypt, use o parâmetro --encryption-context com um ou mais pares name=value. Use um espaço para separar cada par.
```
--encryption-context name=value [name=value] ...
```
Em um comando decrypt, o valor do parâmetro --encryption-context pode incluir pares name=value, elementos name (sem valores) ou uma combinação de ambos.
```
--encryption-context name[=value] [name] [name=value] ...
```

Se o name ou o value em um par de name=value incluir espaços ou caracteres especiais, coloque o par inteiro entre aspas.


--encryption-context "department=software engineering" "AWS Region=us-west-2"

Por exemplo, este comando encrypt inclui um contexto de criptografia com dois pares, purpose=test e dept=23.


aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...

Esse comando decrypt tem êxito. O contexto de criptografia em cada comando é um subconjunto do contexto de criptografia original.


\\ Any one or both of the encryption context pairs
aws-encryption-cli --decrypt --encryption-context dept=23 ...

\\ Any one or both of the encryption context names
aws-encryption-cli --decrypt --encryption-context purpose ...

\\ Any combination of names and pairs
aws-encryption-cli --decrypt --encryption-context dept purpose=test ...

No entanto, esses comandos decrypt falharão. O contexto de criptografia na mensagem criptografada não contém os elementos específicos.


aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...

Como armazenar parâmetros em um arquivo de configuração

Você pode economizar tempo e evitar erros de digitação salvando os parâmetros e valores usados com frequência na CLI de criptografia da AWS em arquivos de configuração.

Um arquivo de configuração é um arquivo de texto que contém parâmetros e valores para um comando da CLI de criptografia da AWS. Ao fazer referência a um arquivo de configuração em um comando da CLI de criptografia da AWS, a referência é substituída pelos parâmetros e valores no arquivo de configuração. O efeito será o mesmo como se você tivesse digitado o conteúdo do arquivo na linha de comando. Um arquivo de configuração pode ter qualquer nome e pode ser localizado em qualquer diretório que o usuário atual pode acessar.

O arquivo de configuração de exemplo a seguir, cmk.conf, especifica duas CMKs do AWS KMS em diferentes regiões.


--master-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
--master-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef

Para usar o arquivo de configuração em um comando, prefixe o nome do arquivo com uma arroba (@). Em um console do PowerShell, use um caractere backtick para escape da arroba (`@).

Este comando de exemplo usa o arquivo cmk.conf em um comando encrypt.

Regras do arquivo de configuração

As regras para uso de arquivos de configuração são:

Você pode incluir vários parâmetros em cada arquivo de configuração e listá-los em qualquer ordem. Liste cada parâmetro com seus valores (se houver) em uma linha separada.
Use # para adicionar um comentário a toda ou a parte de uma linha.
Você pode incluir referências a outros arquivos de configuração. Não use um backtick para escape do sinal @, mesmo no PowerShell.
Se você usar aspas em um arquivo de configuração, o texto entre aspas não pode abranger várias linhas.

Por exemplo, este é o conteúdo de um arquivo encrypt.conf de exemplo.


# Archive Files
--encrypt
--output /archive/logs
--recursive
--interactive
--encryption-context class=unclassified dept=IT
--suffix  # No suffix
--metadata-output ~/metadata
@caching.conf  # Use limited caching

Você também pode incluir vários arquivos de configuração em um comando. Este comando de exemplo usa os arquivos de configuração encrypt.conf e master-keys.conf.

Próximo: Experimente o CLI de criptografia da AWS exemplos

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Instalar a CLI do

Exemplos: