As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Exemplos da CLI AWS de criptografia
Use os exemplos a seguir para testar a CLI de AWS criptografia na plataforma de sua preferência. Para obter ajuda com chaves mestras e outros parâmetros, consulte [Como usar a CLI AWS de criptografia](crypto-cli-how-to.md). Para obter uma referência rápida, consulte [AWS Encryption SDK Referência de sintaxe e parâmetros da CLI](crypto-cli-reference.md).
**nota**
Os exemplos a seguir usam a sintaxe da AWS Encryption CLI versão 2.1. *x.*
Novos recursos de segurança foram lançados originalmente nas versões 1.7 do AWS Encryption CLI. *x* e 2.0. *x.* No entanto, a versão AWS 1.8 do Encryption CLI. *x* substitui a versão 1.7. *x* e CLI de AWS criptografia 2.1. *x* substitui 2.0. *x.* Para obter detalhes, consulte a [consultoria de segurança](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) relevante no [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositório em GitHub.
Para obter um exemplo de como usar o atributo de segurança que limita as chaves de dados criptografadas, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys).
Para ver um exemplo de como usar chaves AWS KMS multirregionais, consulte[Usando várias regiões AWS KMS keys](configure.md#config-mrks).
**Topics**
+ [Criptografar um arquivo](#cli-example-encrypt-file)
+ [Descriptografar um arquivo](#cli-example-decrypt-file)
+ [Criptografar todos os arquivos em um diretório](#cli-example-encrypt-directory)
+ [Descriptografar todos os arquivos em um diretório](#cli-example-decrypt-directory)
+ [Criptografar e descriptografar na linha de comando](#cli-example-stdin)
+ [Uso de várias chaves mestras](#cli-example-multimaster)
+ [Criptografar e descriptografar em scripts](#cli-example-script)
+ [Usar o armazenamento em cache de chaves de dados](#cli-example-caching)
## Criptografar um arquivo
Este exemplo usa a CLI de AWS criptografia para criptografar o conteúdo do `hello.txt` arquivo, que contém uma string “Hello World”.
Quando você executa um comando de criptografia em um arquivo, a CLI de AWS criptografia obtém o conteúdo do arquivo, gera uma chave de [dados exclusiva](concepts.md#DEK), criptografa o conteúdo do arquivo sob a chave de dados e, em seguida, grava [a mensagem criptografada](concepts.md#message) em um novo arquivo.
O primeiro comando salva a chave ARN de an AWS KMS key na `$keyArn` variável. Ao criptografar com um AWS KMS key, você pode identificá-lo usando um ID de chave, ARN da chave, nome do alias ou ARN do alias. Para obter detalhes sobre os identificadores de chave de um AWS KMS key, consulte [Identificadores de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) no Guia do *AWS Key Management Service desenvolvedor*.
O segundo comando criptografa o conteúdo do arquivo. O comando usa o parâmetro `--encrypt` para especificar a operação, e o parâmetro `--input` para indicar o arquivo a ser criptografado. O [`--wrapping-keys`parâmetro](crypto-cli-how-to.md#crypto-cli-master-key) e seu atributo de **chave** obrigatório fazem com que o comando use o AWS KMS key representado pela chave ARN.
O comando usa o parâmetro `--metadata-output` para especificar um arquivo de texto para os metadados sobre a operação de criptografia. Como prática recomendada, o comando usa o parâmetro `--encryption-context` para especificar um [contexto de criptografia](crypto-cli-how-to.md#crypto-cli-encryption-context).
Esse comando também usa o [parâmetro `--commitment-policy`](crypto-cli-reference.md#syntax-commitment-policy) para definir explicitamente a política de compromisso. Na versão 1.8. *x*, ele é necessário quando você usa o parâmetro `--wrapping-keys`. A partir da versão 2.1*x*, o parâmetro `--commitment-policy` passou a ser opcional, mas é recomendado.
O valor do parâmetro `--output`, um ponto (.), informa o comando para gravar o arquivo de saída no diretório atual.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output .
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input Hello.txt `
--wrapping-keys key=$keyArn `
--metadata-output $home\Metadata.txt `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--output .
```
------
Quando o comando encrypt é bem-sucedido, ele não retorna nenhuma saída. Para determinar se o comando foi bem-sucedido, verifique o valor booliano na variável `$?`. Quando o comando é bem-sucedido, o valor de `$?` é `0` (Bash) ou `True` (PowerShell). Quando o comando falha, o valor de `$?` é diferente de zero (Bash) ou `False` (PowerShell).
------
#### [ Bash ]
```
$ echo $?
0
```
------
#### [ PowerShell ]
```
PS C:\> $?
True
```
------
Você também pode usar um comando de listagem de diretório para ver se o comando encrypt criou um novo arquivo, `hello.txt.encrypted`. Como o comando encrypt não especificou um nome de arquivo para a saída, a CLI de AWS criptografia gravou a saída em um arquivo com o mesmo nome do arquivo de entrada mais `.encrypted` um sufixo. Para usar outro sufixo ou suprimir o sufixo, use o parâmetro `--suffix`.
O arquivo `hello.txt.encrypted` contém uma [mensagem criptografada](concepts.md#message) que inclui o texto cifrado do arquivo `hello.txt`, uma cópia criptografada da chave de dados e metadados adicionais incluindo o contexto de criptografia.
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
```
------
## Descriptografar um arquivo
Este exemplo usa a CLI de AWS criptografia para descriptografar o conteúdo do `Hello.txt.encrypted` arquivo que foi criptografado no exemplo anterior.
O comando decrypt usa o parâmetro `--decrypt` para indicar a operação, e o parâmetro `--input` para identificar o arquivo a ser descriptografado. O valor do parâmetro `--output` é um ponto que representa o diretório atual.
O parâmetro `--wrapping-keys` com um atributo **key** especifica a chave de encapsulamento usada para descriptografar a mensagem criptografada. [Em comandos de descriptografia com AWS KMS keys, o valor do atributo chave deve ser um ARN de chave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) O parâmetro `--wrapping-keys` é obrigatório em comandos encrypt. Se você usar AWS KMS keys, poderá usar o atributo **key** prara especificar AWS KMS keys para descritografar ou o atributo **discovery** com um valor definido como`true` (mas não ambos). Se estiver usando outro provedor de chaves mestras, os atributos **key** e **provider** serão necessários.
A partir da versão 2.1[x](crypto-cli-reference.md#syntax-commitment-policy), o *parâmetro `--commitment-policy`* passou a ser opcional, mas é recomendado. Usá-lo explicitamente deixa clara sua intenção, mesmo se você especificar o valor padrão, `require-encrypt-require-decrypt`.
O parâmetro `--encryption-context` é opcional no comando decrypt, mesmo quando um [contexto de criptografia](crypto-cli-how-to.md#crypto-cli-encryption-context) é fornecido no comando encrypt. Nesse caso, o comando decrypt usa o mesmo contexto de criptografia que foi fornecido no comando encrypt. Antes de descriptografar, a AWS CLI de criptografia verifica se o contexto de criptografia na mensagem criptografada inclui um par. `purpose=test` Caso contrário, o comando decrypt falhará.
O parâmetro `--metadata-output` especifica um arquivo de metadados sobre a operação de descriptografia. O valor do parâmetro `--output`, um ponto (.), grava o arquivo de saída no diretório atual.
É uma prática recomendada usar o parâmetro `--max-encrypted-data-keys`, para evitar a descriptografia de uma mensagem malformada com um número excessivo de chaves de dados criptografadas. Especifique o número esperado de chaves de dados criptografadas (um para cada chave de encapsulamento usada na criptografia) ou uma quantidade máxima razoável (como 5). Para obter detalhes, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys).
Ele `--buffer` retorna texto sem formatação somente após o processamento de todas as entradas, incluindo a verificação da assinatura digital, se houver uma.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
```
------
#### [ PowerShell ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input Hello.txt.encrypted `
--wrapping-keys key=$keyArn `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output .
```
------
Quando um comando decrypt é bem-sucedido, ele não retorna nenhuma saída. Para determinar se o comando foi bem-sucedido, obtenha o valor da variável `$?`. Você também pode usar um comando de listagem de diretório para ver se o comando criou um novo arquivo com um sufixo `.decrypted`. Para ver o conteúdo de texto não criptografado, use um comando para obter o conteúdo do arquivo, como `cat` ou [Get-Content](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content).
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted
$ cat hello.txt.encrypted.decrypted
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 1:01 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
-a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted
PS C:\> Get-Content Hello.txt.encrypted.decrypted
Hello World
```
------
## Criptografar todos os arquivos em um diretório
Este exemplo usa a CLI de AWS criptografia para criptografar o conteúdo de todos os arquivos em um diretório.
Quando um comando afeta vários arquivos, a CLI de AWS criptografia processa cada arquivo individualmente. Ela obtém o conteúdo do arquivo, obtém uma [chave de dados](concepts.md#DEK) exclusiva para o arquivo da chave mestre, criptografa o conteúdo do arquivo sob a chave de dados e grava os resultados em um novo arquivo no diretório de saída. Como resultado, você pode descriptografar os arquivos de saída de maneira independente.
Essa listagem do diretório `TestDir` mostra os arquivos de texto não criptografado que desejamos criptografar.
------
#### [ Bash ]
```
$ ls testdir
cool-new-thing.py hello.txt employees.csv
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestDir
Directory: C:\TestDir
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:44 PM 46 Employees.csv
```
------
O primeiro comando salva o [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) de an AWS KMS key na `$keyArn` variável.
O segundo comando criptografa o conteúdo dos arquivos no diretório `TestDir` e grava os arquivos de conteúdo criptografado no `TestEnc`. Se o diretório `TestEnc` não existir, o comando falhará. Como o local de entrada é um diretório, o parâmetro `--recursive` é obrigatório.
O [parâmetro `--wrapping-keys`](crypto-cli-how-to.md#crypto-cli-master-key) e seu atributo-**chave** obrigatório especificam a chave de encapsulamento a ser usada. O comando encrypt inclui um [contexto de criptografia](crypto-cli-how-to.md#crypto-cli-encryption-context), `dept=IT`. Quando você especifica um contexto de criptografia em um comando que criptografa vários arquivos, o mesmo contexto de criptografia é usado para todos os arquivos.
O comando também tem um `--metadata-output` parâmetro para informar à CLI de AWS criptografia onde gravar os metadados sobre as operações de criptografia. A CLI de AWS criptografia grava um registro de metadados para cada arquivo criptografado.
A partir da versão 2.1.*x*, o [`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy) passou a ser opcional, mas é recomendado. Se o comando ou script falhar porque não consegue decifrar um texto cifrado, a configuração explícita da política de compromisso pode ajudar a detectar o problema rapidamente.
Quando o comando é concluído, a CLI de AWS criptografia grava os arquivos criptografados `TestEnc` no diretório, mas não retorna nenhuma saída.
O último comando lista os arquivos no diretório `TestEnc`. Há um arquivo de saída de conteúdo criptografado para cada arquivo de entrada de conteúdo de texto não criptografado. Como o comando não especificou um sufixo alternativo, o comando encrypt acrescentou `.encrypted` a cada um dos nomes de arquivos de entrada.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input testdir --recursive\
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--output testenc
$ ls testenc
cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
PS C:\> aws-encryption-cli --encrypt `
--input .\TestDir --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output .\Metadata\Metadata.txt `
--output .\TestEnc
PS C:\> dir .\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
## Descriptografar todos os arquivos em um diretório
Este exemplo descriptografa todos os arquivos em um diretório. Ele começa com os arquivos no diretório `TestEnc` que foram criptografados no exemplo anterior.
------
#### [ Bash ]
```
$ ls testenc
cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
Esse comando decrypt descriptografa todos os arquivos no TestEnc diretório e grava os arquivos de texto simples no diretório. TestDec O `--wrapping-keys` parâmetro com um atributo de **chave** e um valor de [ARN de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) informa à AWS CLI de criptografia qual usar AWS KMS keys para descriptografar os arquivos. O comando usa o `--interactive` parâmetro para fazer com que a CLI de AWS criptografia avise você antes de sobrescrever um arquivo com o mesmo nome.
Esse comando também usa o contexto de criptografia que foi fornecido quando os arquivos foram criptografados. Ao descriptografar vários arquivos, a AWS CLI de criptografia verifica o contexto de criptografia de cada arquivo. Se a verificação do contexto de criptografia em qualquer arquivo falhar, a CLI de AWS criptografia rejeitará o arquivo, gravará um aviso, registrará a falha nos metadados e continuará verificando os arquivos restantes. Se a CLI de AWS criptografia falhar ao descriptografar um arquivo por qualquer outro motivo, todo o comando decrypt falhará imediatamente.
Neste exemplo, as mensagens criptografadas em todos os arquivos de entrada contêm o elemento do contexto de criptografia de `dept=IT`. No entanto, se você estiver descriptografando mensagens com diferentes contextos de criptografia, você ainda poderá verificar parte do contexto de criptografia. Por exemplo, se algumas mensagens tiverem um contexto de criptografia de `dept=finance` e outras tiverem `dept=IT`, você poderá verificar se o contexto de criptografia sempre contém um nome `dept` sem especificar o valor. Se desejar ser mais específico, você poderá descriptografar os arquivos em comandos separados.
O comando decrypt não retorna nenhuma saída, mas você pode usar um comando de listagem de diretórios para ver se ele criou novos arquivos com o sufixo `.decrypted`. Para ver o conteúdo de texto não criptografado, use um comando para obter o conteúdo do arquivo.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input testenc --recursive \
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output testdec --interactive
$ ls testdec
cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input C:\TestEnc --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output C:\TestDec --interactive
PS C:\> dir .\TestDec
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted
```
------
## Criptografar e descriptografar na linha de comando
Estes exemplos mostram como redirecionar a entrada para comandos (stdin) e gravar a saída na linha de comando (stdout). Eles explicam como representar stdin e stdout em um comando e como usar ferramentas de codificação Base64 internas para impedir que o shell interprete caracteres não ASCII incorretamente.
Este exemplo redireciona uma string de texto não criptografado para um comando encrypt e salva a mensagem criptografada em uma variável. Em seguida, ele redireciona a mensagem criptografada na variável para um comando decrypt, que grava sua saída no pipeline (stdout).
O exemplo consiste em três comandos:
+ O primeiro comando salva a [chave ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) de an AWS KMS key na `$keyArn` variável.
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
```
------
+ O segundo comando redireciona a string `Hello World` para o comando encrypt e salva o resultado na variável `$encrypted`.
Os parâmetros `--input` e `--output` são obrigatórios em todos os comandos da CLI de criptografia da AWS . Para indicar que a entrada está sendo redirecionada para o comando (stdin), use um hífen (`-`) para o valor do parâmetro `--input`. Para enviar a saída para a linha de comando (stdout), use um hífen para o valor do parâmetro `--output`.
O parâmetro `--encode` codifica a saída em Base64 antes de retorná-la. Isso evita que o shell interprete incorretamente os caracteres não ASCII na mensagem criptografada.
Como esse comando é apenas uma prova de conceito, omitimos o contexto de criptografia e suprimimos os metadados (`-S`).
------
#### [ Bash ]
```
$ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \
--input - --output - --encode \
--wrapping-keys key=$keyArn )
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S `
--input - --output - --encode `
--wrapping-keys key=$keyArn
```
------
+ O terceiro comando redireciona a mensagem criptografada na variável `$encrypted` para descriptografar o comando.
Esse comando decrypt usa `--input -` para indicar que a entrada é proveniente do pipeline (stdin) e do `--output -` para enviar a saída para o pipeline (stdout). (O parâmetro de entrada usa o local da entrada, não os bytes reais da entrada. Portanto, você não pode usar a variável `$encrypted` como o valor do parâmetro `--input`.)
Este exemplo usa o atributo de **descoberta** do `--wrapping-keys` parâmetro para permitir que a CLI de AWS criptografia use qualquer um para AWS KMS key descriptografar os dados. Ele não especifica uma [política de compromisso](concepts.md#commitment-policy), portanto, usa o valor padrão para a versão 2.1.*x* e posteriores, `require-encrypt-require-decrypt`.
Como a saída foi criptografada e, em seguida, codificada, o comando decrypt usa o parâmetro `--decode` para decodificar a entrada codificada em Base64 antes de descriptografá-la. Você também pode usar o parâmetro `--decode` para decodificar a entrada codificada em Base64 antes de criptografá-la.
Novamente, o comando omite o contexto de criptografia e suprime os metadados (-`S`).
------
#### [ Bash ]
```
$ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S
Hello World
```
------
Você também pode executar operações de criptografia e descriptografia em um único comando sem a variável de intervenção.
Como no exemplo anterior, os parâmetros `--input` e `--output` têm um valor `-` e o comando usa o parâmetro `--encode` para codificar a saída, e o parâmetro `--decode` para decodificar a entrada.
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ echo 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S
Hello World
```
------
## Uso de várias chaves mestras
Este exemplo mostra como usar várias chaves mestras ao criptografar e descriptografar dados na CLI de criptografia. AWS
Quando você usa várias chaves mestras para criptografar dados, qualquer uma das chaves mestras pode ser usada para descriptografar os dados. Essa estratégia garante que você possa descriptografar os dados mesmo que uma das chaves mestras esteja indisponível. Se você estiver armazenando os dados criptografados em vários Regiões da AWS, essa estratégia permite usar uma chave mestra na mesma região para descriptografar os dados.
Quando você criptografa com várias chaves mestras, a primeira chave mestra desempenha uma função especial. Ela gera a chave de dados que é usada para criptografar os dados. As demais chaves mestras criptografam a chave de dados de texto não criptografado. A [mensagem criptografada](concepts.md#message) resultante inclui os dados criptografados e uma coleção de chaves de dados criptografadas, uma para cada chave mestre. Embora a primeira chave mestra tenha gerado a chave de dados, qualquer uma das chaves mestras poderá descriptografar uma das chaves de dados, que pode ser usada para descriptografar os dados.
**Criptografia com três chaves mestres**
Este comando de exemplo usa três chaves de encapsulamento para criptografar o arquivo `Finance.log`, uma em cada uma das três Regiões da AWS.
Ele grava a mensagem criptografada no diretório `Archive`. O comando usa o parâmetro `--suffix` sem nenhum valor para suprimir o sufixo. Portanto, os nomes dos arquivos de entrada e saída serão o mesmos.
O comando usa o parâmetro `--wrapping-keys` com três atributos **key**. Você também pode usar vários parâmetros `--wrapping-keys` no mesmo comando.
Para criptografar o arquivo de log, a CLI de AWS criptografia solicita que a primeira chave de encapsulamento na lista`$key1`,, gere a chave de dados que ela usa para criptografar os dados. Em seguida, ela usa cada uma das outras chaves de encapsulamento para criptografar uma cópia de texto não criptografado da mesma chave de dados. A mensagem criptografada no arquivo de saída inclui todas as três chaves de dados criptografadas.
------
#### [ Bash ]
```
$ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
$ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
$ aws-encryption-cli --encrypt --input /logs/finance.log \
--output /archive --suffix \
--encryption-context class=log \
--metadata-output ~/metadata \
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
#### [ PowerShell ]
```
PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef'
PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d'
PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log `
--output D:\Archive --suffix `
--encryption-context class=log `
--metadata-output $home\Metadata.txt `
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
Este comando descriptografa a cópia criptografada do arquivo `Finance.log` e grava-o em um arquivo `Finance.log.clear` no diretório `Finance`. Para descriptografar dados criptografados abaixo de três AWS KMS keys, você pode especificar os mesmos três AWS KMS keys ou qualquer subconjunto deles. Este exemplo especifica somente um dos AWS KMS keys.
Para informar à CLI de AWS criptografia qual usar AWS KMS keys para descriptografar seus dados, use o atributo **chave** do parâmetro. `--wrapping-keys` [Ao descriptografar com AWS KMS keys, o valor do atributo **chave** deve ser um ARN da chave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)
Você deve ter permissão para chamar a [API Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) no que você especificar. AWS KMS keys Para obter mais informações, consulte [Autenticação e controle de acesso do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html).
Como prática recomendada, estes exemplos usam o parâmetro `--max-encrypted-data-keys` para evitar a descriptografia de uma mensagem malformada com um número excessivo de chaves de dados criptografadas. Embora o exemplo use somente uma chave de encapsulamento para decodificação, a mensagem criptografada tem três (3) chaves de dados criptografadas; uma para cada uma das três chaves de encapsulamento usadas na criptografia. Especifique o número esperado de chaves de dados criptografadas ou um valor máximo razoável, como 5. Se especificar um valor máximo menor que 3, o comando falhará. Para obter detalhes, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys).
------
#### [ Bash ]
```
$ aws-encryption-cli --decrypt --input /archive/finance.log \
--wrapping-keys key=$key1 \
--output /finance --suffix '.clear' \
--metadata-output ~/metadata \
--max-encrypted-data-keys 3 \
--buffer \
--encryption-context class=log
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli --decrypt `
--input D:\Archive\Finance.log `
--wrapping-keys key=$key1 `
--output D:\Finance --suffix '.clear' `
--metadata-output .\Metadata\Metadata.txt `
--max-encrypted-data-keys 3 `
--buffer `
--encryption-context class=log
```
------
## Criptografar e descriptografar em scripts
Este exemplo mostra como usar a CLI AWS de criptografia em scripts. Você pode escrever scripts que apenas criptografam e descriptografam dados ou scripts que criptografam ou descriptografam como parte de um processo de gerenciamento de dados.
Neste exemplo, o script obtém uma coleção de arquivos de log, compacta-os, criptografa-os e, em seguida, copia os arquivos criptografados em um bucket do Amazon S3. Esse script processa cada arquivo separadamente, para que você possa descriptografá-los e expandi-los de maneira independente.
Ao compactar e criptografar arquivos, certifique-se de compactar antes de criptografar. Dados criptografados corretamente não podem ser compactados.
**Atenção**
Tenha cuidado ao compactar dados que incluam segredos e dados que possam ser controlados por um ator mal-intencionado. O tamanho final dos dados compactados pode revelar inadvertidamente informações confidenciais sobre seu conteúdo.
------
#### [ Bash ]
```
# Continue running even if an operation fails.
set +e
dir=$1
encryptionContext=$2
s3bucket=$3
s3folder=$4
masterKeyProvider="aws-kms"
metadataOutput="/tmp/metadata-$(date +%s)"
compress(){
gzip -qf $1
}
encrypt(){
# -e encrypt
# -i input
# -o output
# --metadata-output unique file for metadata
# -m masterKey read from environment variable
# -c encryption context read from the second argument.
# -v be verbose
aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v
}
s3put (){
# copy file argument 1 to s3 location passed into the script.
aws s3 cp ${1} ${s3bucket}/${s3folder}
}
# Validate all required arguments are present.
if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then
# Is $dir a valid directory?
test -d "${dir}"
if [ $? -ne 0 ]; then
echo "Input is not a directory; exiting"
exit 1
fi
# Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run).
for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do
echo "Working on $f"
compress ${f}
encrypt ${f}.gz
rm -f ${f}.gz
s3put ${f}.gz.encrypted
done;
else
echo "Arguments: "
echo " and ENV var \$masterKey must be set"
exit 255
fi
```
------
#### [ PowerShell ]
```
#Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive
Param
(
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String[]]
$FilePath,
[Parameter()]
[Switch]
$Recurse,
[Parameter(Mandatory=$true)]
[String]
$wrappingKeyID,
[Parameter()]
[String]
$masterKeyProvider = 'aws-kms',
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$ZipDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$EncryptDirectory,
[Parameter()]
[String]
$EncryptionContext,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$MetadataDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-S3Bucket -BucketName $_})]
[String]
$S3Bucket,
[Parameter()]
[String]
$S3BucketFolder
)
BEGIN {}
PROCESS {
if ($files = dir $FilePath -Recurse:$Recurse)
{
# Step 1: Compress
foreach ($file in $files)
{
$fileName = $file.Name
try
{
Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip
}
catch
{
Write-Error "Zip failed on $file.FullName"
}
# Step 2: Encrypt
if (-not (Test-Path "$ZipDirectory\$filename.zip"))
{
Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip"
}
else
{
# 2>&1 captures command output
$err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" `
-o $EncryptDirectory `
-m key=$wrappingKeyID provider=$masterKeyProvider `
-c $EncryptionContext `
--metadata-output $MetadataDirectory `
-v) 2>&1
# Check error status
if ($? -eq $false)
{
# Write the error
$err
}
elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted")
{
# Step 3: Write to S3 bucket
if ($S3BucketFolder)
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted"
}
else
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted"
}
}
}
}
}
}
```
------
## Usar o armazenamento em cache de chaves de dados
Este exemplo usa o [armazenamento em cache de chaves de dados](data-key-caching.md) em um comando que criptografa um grande número de arquivos.
Por padrão, a CLI de AWS criptografia (e outras versões da AWS Encryption SDK) gera uma chave de dados exclusiva para cada arquivo criptografado. Embora o uso de uma chave de dados exclusiva para cada operação seja uma prática recomendada de criptografia, a reutilização limitada de chaves de dados é aceitável em algumas situações. Se você estiver considerando o armazenamento em cache de chaves de dados, consulte um engenheiro de segurança para compreender os requisitos de segurança do seu aplicativo e determinar os limites de segurança apropriados para você.
Neste exemplo, o armazenamento em cache de chaves de dados acelera a operação de criptografia reduzindo a frequência de solicitações ao provedor de chaves mestras.
O comando neste exemplo criptografa um diretório grande com vários subdiretórios que contêm um total de aproximadamente 800 pequenos arquivos de log. O primeiro comando salva o ARN da AWS KMS key em uma variável `keyARN`. O segundo comando criptografa todos os arquivos no diretório de entrada (recursivamente) e os grava em um diretório de arquivo morto. O comando usa o parâmetro `--suffix` para especificar o sufixo `.archive`.
O parâmetro `--caching` permite o armazenamento em cache da chave de dados. O atributo **capacity**, que limita o número de chaves de dados no cache, está definido como 1, porque o processamento de arquivos seriais nunca usa mais de uma chave de dados de cada vez. O atributo **max\$1age**, que determina por quanto tempo a chave de dados armazenada em cache pode ser usada, está definido como 10 segundos.
O atributo opcional **max\$1messages\$1encrypted** está definido como 10 mensagens, portanto, uma única chave de dados nunca é usada para criptografar mais de 10 arquivos. A limitação do número de arquivos criptografados por cada chave de dados reduz o número de arquivos que devem ser afetados no caso improvável de uma chave de dados estar comprometida.
Para executar esse comando em arquivos de log gerados pelo sistema operacional, você pode precisar de permissões de administrador (`sudo` no Linux; **Run as Administrator (Executar como administrador)** no Windows).
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input /var/log/httpd --recursive \
--output ~/archive --suffix .archive \
--wrapping-keys key=$keyArn \
--encryption-context class=log \
--suppress-metadata \
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
#### [ PowerShell ]
```
PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
Para testar o efeito do armazenamento em cache da chave de dados, este exemplo usa o cmdlet [Measure-Command em](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command). PowerShell Ao executar esse exemplo sem o armazenamento em cache da chave de dados, ele demora cerca de 25 segundos para ser concluído. Esse processo gera uma nova chave de dados para cada arquivo no diretório.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata }
Days : 0
Hours : 0
Minutes : 0
Seconds : 25
Milliseconds : 453
Ticks : 254531202
TotalDays : 0.000294596298611111
TotalHours : 0.00707031116666667
TotalMinutes : 0.42421867
TotalSeconds : 25.4531202
TotalMilliseconds : 25453.1202
```
O armazenamento em cache da chave de dados acelera o processo, mesmo quando você limita cada chave de dados para um máximo de 10 arquivos. O comando agora demora menos de 12 segundos para ser concluído e reduz o número de chamadas ao provedor de chaves mestras para 1/10 do valor original.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 813
Ticks : 118132640
TotalDays : 0.000136727592592593
TotalHours : 0.00328146222222222
TotalMinutes : 0.196887733333333
TotalSeconds : 11.813264
TotalMilliseconds : 11813.264
```
Se você eliminar a restrição `max_messages_encrypted`, todos os arquivos serão criptografados com a mesma chave de dados. Essa alteração aumenta o risco de reutilização de chaves de dados sem tornar o processo muito mais rápido. No entanto, ela reduz o número de chamadas ao provedor de chaves mestras para 1.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 10
Milliseconds : 252
Ticks : 102523367
TotalDays : 0.000118661304398148
TotalHours : 0.00284787130555556
TotalMinutes : 0.170872278333333
TotalSeconds : 10.2523367
TotalMilliseconds : 10252.3367
```