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á. # AWS Encryption SDK interface de linha de comando A interface de linha de AWS Encryption SDK comando (CLI de AWS criptografia) permite que você use o para AWS Encryption SDK criptografar e descriptografar dados interativamente na linha de comando e em scripts. Você não precisa ter competência em criptografia ou em programação. **nota** [Versões da CLI de AWS criptografia anteriores à 4.0.0 estão em fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) Você pode atualizar com segurança a partir da versão 2.1.*x* e posteriores até a versão mais recente da CLI de criptografia da AWS sem realizar alterações no código ou nos dados. No entanto, os [novos atributos de segurança](about-versions.md#version-2) introduzidos na versão 2.1.*x* não são compatíveis com versões anteriores. Para atualizar a partir da versão 1.7. *x* ou anterior, você deve primeiro atualizar para a última 1. versão *x* da CLI AWS de criptografia. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). 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. Como todas as implementações do AWS Encryption SDK, o AWS Encryption CLI oferece recursos avançados de proteção de dados. Os atributos incluem [criptografia envelopada](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption), dados autenticados adicionais (AAD) e [pacotes de algoritmos](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html) de chave simétrica segura e autenticada, como o AES-GCM de 256 bits com derivação de chave, [confirmação de chave](concepts.md#key-commitment) e assinatura. A CLI de AWS criptografia é baseada no [AWS Encryption SDK for Python](python.md)e é compatível com Linux, macOS e Windows. Você pode executar comandos e scripts para criptografar e descriptografar seus dados no shell de sua preferência no Linux ou macOS, em uma janela do prompt de comando (cmd.exe) no Windows e em um console em qualquer sistema. PowerShell Todas as implementações específicas de linguagem do AWS Encryption SDK, incluindo a AWS CLI de criptografia, são interoperáveis. Por exemplo, você pode criptografar dados com o [AWS Encryption SDK for Java](java.md)e descriptografá-los com a CLI de criptografia. AWS Este tópico apresenta a CLI de AWS criptografia, explica como instalá-la e usá-la e fornece vários exemplos para ajudar você a começar. Para começar rapidamente, consulte [Como criptografar e descriptografar seus dados com a AWS CLI de criptografia no blog](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/) de segurança. AWS Para obter informações mais detalhadas, consulte [Leia os documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/) e junte-se a nós no desenvolvimento da CLI de AWS criptografia [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)no repositório em. GitHub **desempenho** A CLI de AWS criptografia é baseada no. AWS Encryption SDK for Python Cada vez que executa a CLI, você inicia uma nova instância do runtime do Python. Para melhorar o desempenho, sempre que possível, use um único comando em vez de uma série de comandos independentes. Por exemplo, execute um comando que processe os arquivos em um diretório de forma recursiva, em vez de executar comandos separados para cada arquivo. **Topics** + [Instalar a CLI do](crypto-cli-install.md) + [Como usar a CLI](crypto-cli-how-to.md) + [Exemplos](crypto-cli-examples.md) + [Referência da sintaxe e de parâmetros](crypto-cli-reference.md) + [Versões](crypto-cli-versions.md) # Instalando a interface de linha de AWS Encryption SDK comando Este tópico explica como instalar a CLI AWS de criptografia. Para obter informações detalhadas, consulte o [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositório GitHub e [leia os documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/). **Topics** + [Instalar os pré-requisitos](#crypto-cli-prerequisites) + [Instalar a CLI do](#install-sdk-cli) ## Instalar os pré-requisitos A CLI de AWS criptografia é baseada no. AWS Encryption SDK for Python Para instalar a CLI do AWS Encryption, você precisa do Python e da ferramenta de gerenciamento de pacotes `pip` do Python. O Python e o `pip` estão disponíveis em todas as plataformas compatíveis. Instale os seguintes pré-requisitos antes de instalar a CLI de criptografia AWS , **Python** O Python 3.8 ou posterior é exigido pelas versões 4.2.0 e posteriores do Encryption AWS CLI. As versões anteriores da CLI de AWS criptografia oferecem suporte ao Python 2.7 e 3.4 e versões posteriores, mas recomendamos que você use a versão mais recente da CLI de criptografia. AWS O Python está incluído na maioria das instalações do Linux e do macOS, mas é necessário atualizar para o Python 3.6 ou versões posteriores. É recomendável usar a versão mais recente do Python. No Windows, você precisa instalar o Python: ele não é instalado por padrão. Para fazer download do Python, consulte [Downloads do Python](https://www.python.org/downloads/). Para determinar se o Python está instalado, na linha de comando, digite: ``` python ``` Para verificar a versão do Python, use o parâmetro `-V` (V maiúsculo). ``` python -V ``` No Windows, depois de instalar o Python, adicione o caminho para o arquivo `Python.exe` ao valor da variável de ambiente **Path**. Por padrão, o Python é instalado em todos os diretórios de usuário ou em um diretório de perfil de usuário (`$home` ou `%userprofile%`) no subdiretório `AppData\Local\Programs\Python`. Para encontrar o local do arquivo `Python.exe` no sistema, verifique uma das seguintes chaves de registro. Você pode usar PowerShell para pesquisar o registro. ``` PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath # -or- PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath ``` **pip** `pip` é o gerenciador de pacotes do Python. Para instalar a CLI de AWS criptografia e suas dependências, você precisa da `pip` versão 8.1 ou posterior. Para obter ajuda para instalar ou atualizar o `pip`, consulte [Instalação](https://pip.pypa.io/en/latest/installing/) na documentação do `pip`. Nas instalações do Linux, as versões `pip` anteriores à 8.1 não podem criar a biblioteca de **criptografia exigida** pela CLI de AWS criptografia. Se você optar por não atualizar sua versão do `pip`, poderá instalar as ferramentas de compilação separadamente. Para obter mais informações, consulte [Criação de criptografia no Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux). **AWS Command Line Interface** O AWS Command Line Interface (AWS CLI) é necessário somente se você estiver usando AWS KMS keys in AWS Key Management Service (AWS KMS) com a CLI de AWS criptografia. Se você estiver usando um [provedor de chave mestra](concepts.md#master-key-provider) diferente, AWS CLI isso não é obrigatório. Para usar AWS KMS keys com a CLI de AWS criptografia, você precisa [instalar](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) e [configurar o.](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration) AWS CLI A configuração disponibiliza as credenciais que você usa para autenticar para a AWS KMS AWS CLI de criptografia. ## Instalando e atualizando a CLI AWS de criptografia Instale a versão mais recente da CLI AWS de criptografia. [Quando você usa `pip` para instalar a CLI de AWS criptografia, ela instala automaticamente as bibliotecas de que a CLI precisa, incluindo a biblioteca de criptografia Python e a. [AWS Encryption SDK for Python[AWS SDK para Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)](python.md)](https://cryptography.io/en/latest/) **nota** [Versões da CLI de AWS criptografia anteriores à 4.0.0 estão em fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) Você pode atualizar com segurança a partir da versão 2.1.*x* e posteriores até a versão mais recente da CLI de criptografia da AWS sem realizar alterações no código ou nos dados. No entanto, os [novos atributos de segurança](about-versions.md#version-2) introduzidos na versão 2.1.*x* não são compatíveis com versões anteriores. Para atualizar a partir da versão 1.7. *x* ou anterior, você deve primeiro atualizar para a última 1. versão *x* da CLI AWS de criptografia. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). 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 instalar a versão mais recente da CLI AWS de criptografia** ``` pip install aws-encryption-sdk-cli ``` **Para atualizar para a versão mais recente da CLI de AWS criptografia** ``` pip install --upgrade aws-encryption-sdk-cli ``` **Para encontrar os números de versão da sua CLI de AWS criptografia e AWS Encryption SDK** ``` aws-encryption-cli --version ``` A saída lista os números de versão de ambas as bibliotecas. ``` aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0 ``` **Para atualizar para a versão mais recente da CLI de AWS criptografia** ``` pip install --upgrade aws-encryption-sdk-cli ``` A instalação da CLI de AWS criptografia também instala a versão mais recente do AWS SDK para Python (Boto3), se ainda não estiver instalada. Se o Boto3 estiver instalado, o instalador verifica a versão do Boto3 e a atualiza, se necessário. **Para encontrar sua versão instalada do Boto3** ``` pip show boto3 ``` **Para atualizar para a versão mais recente do Boto3** ``` pip install --upgrade boto3 ``` Para instalar a versão da CLI de AWS criptografia atualmente em desenvolvimento, consulte o [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositório em. GitHub Para obter mais detalhes sobre o uso do `pip` para instalar e atualizar pacotes do Python, consulte a [documentação do pip](https://pip.pypa.io/en/stable/quickstart/). # Como usar a CLI AWS de criptografia Este tópico explica como usar os parâmetros na CLI AWS de criptografia. Para obter exemplos, consulte [Exemplos da CLI AWS de criptografia](crypto-cli-examples.md). Para obter a documentação completa, consulte [Leia os documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/). A sintaxe mostrada nesses exemplos é para a versão 2.1 do AWS Encryption CLI. *x* e mais tarde. **nota** [Versões da CLI de AWS criptografia anteriores à 4.0.0 estão em fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) Você pode atualizar com segurança a partir da versão 2.1.*x* e posteriores até a versão mais recente da CLI de criptografia da AWS sem realizar alterações no código ou nos dados. No entanto, os [novos atributos de segurança](about-versions.md#version-2) introduzidos na versão 2.1.*x* não são compatíveis com versões anteriores. Para atualizar a partir da versão 1.7. *x* ou anterior, você deve primeiro atualizar para a última 1. versão *x* da CLI AWS de criptografia. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). 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** + [Como criptografar e descriptografar dados](#crypto-cli-e-d-intro) + [Como especificar chaves de encapsulamento](#crypto-cli-master-key) + [Como fornecer entrada](#crypto-cli-input) + [Como especificar o local de saída](#crypto-cli-output) + [Como usar um contexto de criptografia](#crypto-cli-encryption-context) + [Como especificar uma política de compromisso](#crypto-cli-commitment-policy) + [Como armazenar parâmetros em um arquivo de configuração](#crypto-cli-config-file) ## Como criptografar e descriptografar dados A CLI de AWS criptografia usa os recursos do AWS Encryption SDK para facilitar a criptografia e a descriptografia de dados com segurança. **nota** O parâmetro `--master-keys` foi descontinuado na versão 1.8. *x* da CLI de criptografia da AWS e removido na versão 2.1.*x.*. Em vez disso, use o parâmetro `--wrapping-keys`. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` passou a ser necessário ao criptografar e descriptografar. Para obter detalhes, consulte [AWS Encryption SDK Referência de sintaxe e parâmetros da CLI](crypto-cli-reference.md). + Ao criptografar dados na CLI de AWS criptografia, você especifica seus dados de texto sem formatação e [uma chave de encapsulamento](concepts.md#master-key) (*ou chave mestra*), como in (). AWS KMS key AWS Key Management Service AWS KMS Se estiver usando um provedor de chaves mestras personalizado, você também precisará especificar o provedor. Você também especifica locais de saída para a [mensagem criptografada](concepts.md#message) e para os metadados sobre a operação de criptografia. Um [contexto de criptografia](concepts.md#encryption-context) é opcional, mas recomendado. Na versão 1.8.*x*, o parâmetro `--commitment-policy` é obrigatório quando você usar o parâmetro `--wrapping-keys`; caso contrário ele não será válido. A partir da versão 2.1*x*, o parâmetro `--commitment-policy` passou a ser opcional, mas é recomendado. ``` aws-encryption-cli --encrypt --input myPlaintextData \ --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \ --output myEncryptedMessage \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt ``` A CLI de AWS criptografia criptografa seus dados com uma chave de dados exclusiva. Em seguida, ele criptografa cada chave de dados sob a chave de encapsulamento especificada. Ela retorna uma [mensagem criptografada](concepts.md#message) 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. Você também especifica as chaves de encapsulamento que a CLI de AWS criptografia pode usar para descriptografar a mensagem ou informa à CLI de AWS criptografia que ela pode usar qualquer chave de encapsulamento que criptografe a mensagem. A partir da versão 1.8.*x*, o parâmetro `--wrapping-keys` passou a ser opcional, mas é recomendado. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` passou a ser necessário ao criptografar e descriptografar. Ao descriptografar, você pode usar o atributo **key** do parâmetro `--wrapping-keys` para especificar as chaves de encapsulamento que descriptografam seus dados. Especificar uma chave de AWS KMS encapsulamento ao descriptografar é opcional, mas é uma [prática recomendada](best-practices.md) que impede que você use uma chave que você não pretendia usar. Se estiver usando um provedor de chaves mestras personalizado, você deverá especificar o provedor. Se você não usar o atributo de **chave**, deverá definir o atributo de [**descoberta**](#discovery-cli-attribute) do `--wrapping-keys` parâmetro como`true`, o que permite que a CLI de AWS criptografia seja descriptografada usando qualquer chave de encapsulamento que criptografou a mensagem. É 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). O parâmetro `--buffer` retorna texto simples somente após o processamento de todas as entradas, incluindo a verificação da assinatura digital, se houver uma. O parâmetro `--decrypt-unsigned` descriptografa o texto cifrado e garante que as mensagens não sejam assinadas antes de serem descriptografadas. Use esse parâmetro se você usou o parâmetro `--algorithm` e selecionou um pacote de algoritmos sem assinatura digital para criptografar dados. Se o texto cifrado for assinado, a descriptografia falhará. Você pode usar `--decrypt` ou `--decrypt-unsigned` para fazer a descriptografia, mas não ambos. ``` aws-encryption-cli --decrypt --input myEncryptedMessage \ --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \ --output myPlaintextData \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt ``` A CLI de AWS criptografia usa a chave de empacotamento 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 chaves de encapsulamento Ao criptografar dados na CLI de AWS criptografia, você precisa especificar pelo menos [uma chave de encapsulamento (*ou* chave mestra](concepts.md#master-key)). Você pode usar AWS KMS keys in AWS Key Management Service (AWS KMS), agrupar chaves de um [provedor de chave mestra](concepts.md#master-key-provider) personalizado ou ambos. O provedor de chaves mestras personalizado pode ser qualquer provedor de chaves mestras compatível com o Python. Para especificar as chaves de encapsulamento nas versões 1.8.*x* e posteriores, use o parâmetro `--wrapping-keys` (`-w`). O valor deste parâmetro é uma coleção de [atributos](#cli-master-key-attributes) com o formato `attribute=value`. Os atributos que você usa dependem do provedor de chaves mestras e do comando. + **AWS KMS**. Em comandos encrypt, você deve especificar um parâmetro `--wrapping-keys` com um atributo **key**. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` também passou a ser necessário em comandos de descriptografia. Ao descriptografar, o parâmetro `--wrapping-keys` deve ter um atributo **key** ou um atributo **discovery** (mas não os dois) com o valor de `true`. Todos os outros atributos são opcionais. + **Provedor de chaves mestres personalizado**. Você deve especificar um parâmetro `--wrapping-keys` em cada comando. O valor do parâmetro deve ter os atributos **key** e **provider**. Você pode incluir [vários parâmetros `--wrapping-keys`](#cli-many-cmks) e vários atributos **key** no mesmo comando. ### Encapsulando os atributos dos parâmetros de chave O valor do parâmetro `--wrapping-keys` consiste nos seguintes atributos e seus valores. Um parâmetro `--wrapping-keys` (ou parâmetro `--master-keys`) é necessário em todos os comandos de criptografia. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` também passou a ser necessário em comandos de descriptografia. Se um nome ou valor de atributo incluir espaços ou caracteres especiais, coloque o nome e o valor entre aspas. Por exemplo, .`--wrapping-keys key=12345 "provider=my cool provider"` **Chave: especifique uma chave de encapsulamento** Use o atributo **key** para identificar uma chave de encapsulamento. Ao criptografar, o valor pode ser qualquer identificador de chave que o provedor de chaves mestras reconhece. ``` --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab ``` Em um comando encrypt, cada valor do parâmetro você deve incluir pelo menos um atributo **key** e um valor. Para criptografar sua chave de dados em várias chaves de encapsulamento, use [vários atributos **key**](#cli-many-cmks). ``` aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d ``` Nos comandos de criptografia usados AWS KMS keys, o valor da **chave pode ser o ID da chave**, o ARN da chave, um nome de alias ou o ARN do alias. Por exemplo, este comando encrypt usa um ARN do alias no valor do atributo **key**. 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*. ``` aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias ``` Em comandos decrypt que usam um provedor de chaves mestres personalizado, os atributos **key** e **provider** são necessários. ``` \\ Custom master key provider aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101' ``` Nos comandos de descriptografia usados AWS KMS, você pode usar o atributo **chave** para especificar o a ser usado AWS KMS keys para descriptografia ou o [atributo de **descoberta**](#discovery-cli-attribute) com um valor de, `true` que permite que a AWS CLI de criptografia use qualquer AWS KMS key um que tenha sido usado para criptografar a mensagem. Se você especificar um AWS KMS key, ele deverá ser uma das chaves de encapsulamento usadas para criptografar a mensagem. A especificação da chave de encapsulamento é uma [AWS Encryption SDK prática recomendada](best-practices.md). Isso garante que você use o AWS KMS key que pretende usar. Em um comando decrypt, o valor do atributo **key** deve ser um [ARN de chave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) ``` \\ AWS KMS key aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab ``` **Descoberta: use qualquer um AWS KMS key ao descriptografar** Se você não precisar limitar o uso AWS KMS keys ao descriptografar, você pode usar o atributo de **descoberta** com um valor de. `true` Um valor de `true` permite que a CLI de AWS criptografia decodifique usando qualquer AWS KMS key uma que criptografe a mensagem. Se você não especificar um atributo **discovery**, a descoberta será `false` (padrão). O atributo de **descoberta** é válido somente em comandos de descriptografia e somente quando a mensagem foi criptografada com. AWS KMS keys O atributo **discovery** com o valor definido como `true` é uma alternativa ao uso do atributo **key** para especificar uma AWS KMS keys. Ao descriptografar uma mensagem criptografada com AWS KMS keys, cada `--wrapping-keys` parâmetro deve ter um **atributo-chave** ou um atributo de **descoberta** com um valor de`true`, mas não ambos. Quando a descoberta é verdadeira, é uma prática recomendada usar os atributos **discovery-partition** e **discovery-account** para limitar o AWS KMS keys uso aos atributos especificados por você. Contas da AWS No exemplo a seguir, os atributos de **descoberta** permitem que a CLI de AWS criptografia use qualquer um dos atributos AWS KMS key especificados. Contas da AWS ``` aws-encryption-cli --decrypt --wrapping-keys \ discovery=true \ discovery-partition=aws \ discovery-account=111122223333 \ discovery-account=444455556666 ``` **Provider: especifique o provedor de chaves mestras** O atributo **provider** identifica o [provedor de chaves mestres](concepts.md#master-key-provider). O valor padrão é `aws-kms` que representa o AWS KMS. Se estiver usando outro provedor de chaves mestres, o atributo **provider** será necessário. ``` --wrapping-keys key=12345 provider=my_custom_provider ``` Para obter mais informações sobre o uso de provedores de chaves mestras personalizadas (que não sejam AWS KMS), consulte o tópico **Configuração avançada** no arquivo [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) do repositório da [CLI e criptografia da AWS](https://github.com/aws/aws-encryption-sdk-cli/). **Região: Especifique uma Região da AWS** Use o atributo de **região** para especificar o Região da AWS de um AWS KMS key. Esse atributo é válido apenas em comandos encrypt e somente quando o provedor de chaves mestras é o AWS KMS. ``` --encrypt --wrapping-keys key=alias/primary-key region=us-east-2 ``` AWS Os comandos CLI de criptografia usam o Região da AWS que é especificado no valor do atributo **chave** se incluir uma região, como um ARN. Se o valor da **chave** especificar um Região da AWS, o atributo **região** será ignorado. O atributo **region** tem precedência sobre outras especificações de região. Se você não usar um atributo de região, os comandos da CLI de AWS criptografia usarão o Região da AWS especificado em seu [perfil AWS CLI nomeado](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles), se houver, ou em seu perfil padrão. **Profile: especifique um perfil nomeado** Use o atributo **profile** para especificar um AWS CLI perfil nomeado[ da ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles). 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. ``` --wrapping-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 AWS criptografia usa Região da AWS o no perfil nomeado somente quando o valor **da** chave não inclui uma região e não há **nenhum** atributo de região. Em um comando decrypt, o perfil Região da AWS in the name é ignorado. ### Como especificar várias chaves mestras Você pode especificar várias chaves de encapsulamento (ou *chaves mestras*) em cada comando. Se você especificar mais de uma chave de encapsulamento, a primeira chave de encapsulamento gerará (e criptografará) a chave de dados usada para criptografar seus dados. As outras chaves de encapsulamento criptografam a mesma chave de dados. A [mensagem criptografada](concepts.md#message) resultante contém os dados criptografados ("texto cifrado") e uma coleção de chaves de dados criptografadas, criptografadas por cada chave de encapsulamento. Qualquer uma das chaves de encapsulamento podem descriptografar uma chave de dados e descriptografar os dados. Há duas maneiras de especificar várias chaves de encapsulamento: + Incluir vários atributos **key** no valor do parâmetro `--wrapping-keys`. ``` $key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef --wrapping-keys key=$key_oregon key=$key_ohio ``` + Incluir vários parâmetros `--wrapping-keys` no mesmo comando. Use essa sintaxe quando os valores dos atributos que você especificar não se aplicarem a todas as chaves de encapsulamento no comando. ``` --wrapping-keys region=us-east-2 key=alias/test_key \ --wrapping-keys region=us-west-1 key=alias/test_key ``` O atributo de **descoberta** com um valor de `true` permite que a CLI de AWS criptografia use qualquer um AWS KMS key que criptografe a mensagem. Se você usar vários parâmetros `--wrapping-keys` no mesmo comando, o uso de `discovery=true` em qualquer parâmetro `--wrapping-keys` substituirá efetivamente os limites do atributo **key** em outros parâmetros `--wrapping-keys`. Por exemplo, no comando a seguir, o atributo **chave** no primeiro `--wrapping-keys` parâmetro limita a CLI de AWS criptografia ao especificado. AWS KMS key No entanto, o atributo de **descoberta** no segundo `--wrapping-keys` parâmetro permite que a CLI de AWS criptografia use qualquer AWS KMS key uma das contas especificadas para descriptografar a mensagem. ``` aws-encryption-cli --decrypt \ --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --wrapping-keys discovery=true \ discovery-partition=aws \ discovery-account=111122223333 \ discovery-account=444455556666 ``` ## Como fornecer entrada [A operação de AWS criptografia na CLI de criptografia usa dados de texto simples como entrada e retorna uma mensagem criptografada.](concepts.md#message) A operação de descriptografia usa uma mensagem criptografada como entrada e retorna dados de texto não criptografado. O `--input` parâmetro (`-i`), que informa à CLI de AWS criptografia onde encontrar a entrada, é obrigatório em todos os comandos da AWS CLI de criptografia. 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 `--output` parâmetro informa à CLI de AWS criptografia onde gravar os resultados da operação de criptografia ou descriptografia. É necessário em todos os comandos da CLI de AWS criptografia. 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 AWS criptografia imprime um aviso e, em seguida, sobrescreve 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, use `--quiet`. Para capturar erros e avisos da CLI de AWS criptografia, use `2>&1` o operador de redirecionamento para gravá-los no 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 é um diretório (sem nomes de arquivo), a CLI de AWS criptografia cria nomes de arquivos de saída com base nos nomes dos arquivos de entrada mais um sufixo. As operações de criptografia acrescentam `.encrypted` ao nome do arquivo de entrada e as operações de descriptografia acrescentam `.decrypted`. Para alterar o sufixo, use o parâmetro `--suffix`. Por exemplo, se você criptografar `file.txt`, o comando encrypt criará `file.txt.encrypted`. Se você descriptografar `file.txt.encrypted`, o comando decrypt criará `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 AWS criptografia permite que você forneça um contexto de criptografia nos comandos de criptografia e descriptografia. 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](concepts.md#crypt-materials-manager) adicionar, é associado de maneira criptográfica aos dados criptografados. Ele também é incluído (em não criptografado) na [mensagem criptografada](concepts.md#encryption-context) que o comando retorna. Se você estiver usando um AWS KMS key, o contexto de criptografia também poderá aparecer em texto simples em registros e registros de auditoria, como. 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 AWS criptografia 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" "Região da AWS=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 especificar uma política de compromisso Para definir a [política de compromisso](concepts.md#commitment-policy) para o comando, use o [parâmetro `--commitment-policy`](crypto-cli-reference.md#syntax-commitment-policy). Esse parâmetro foi apresentado na versão 1.8.*x.*. Ele 'é válido em comandos de criptografia e descriptografia. A política de compromisso que você definir será válida somente para o comando no qual ela aparece. Se você não definir uma política de compromisso para um comando, a CLI de AWS criptografia usará o valor padrão. Por exemplo, o valor do parâmetro a seguir define a política de compromisso como `require-encrypt-allow-decrypt`, que sempre criptografa com o confirmação de chave, mas descriptografa um texto cifrado criptografado com ou sem confirmação de chave. ``` --commitment-policy require-encrypt-allow-decrypt ``` ## 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 da CLI de AWS criptografia usados com frequência nos arquivos de configuração. Um *arquivo de configuração* é um arquivo de texto que contém parâmetros e valores para um comando CLI de AWS criptografia. 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, `key.conf`, especifica duas AWS KMS keys em diferentes regiões. ``` --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab --wrapping-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 PowerShell console, use um caractere de crase para escapar do sinal arroba (``@`). Este comando de exemplo usa o arquivo `key.conf` em um comando encrypt. ------ #### [ Bash ] ``` $ aws-encryption-cli -e @key.conf -i hello.txt -o testdir ``` ------ #### [ PowerShell ] ``` PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir ``` ------ **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 uma craqueta para escapar da `@` placa, mesmo dentro 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`. ------ #### [ Bash ] ``` $ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf ``` ------ #### [ PowerShell ] ``` PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf ``` ------ **Próximo:** [ Experimente os exemplos da CLI de criptografia da AWS](crypto-cli-examples.md) # 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 ``` # AWS Encryption SDK Referência de sintaxe e parâmetros da CLI Este tópico fornece diagramas da sintaxe e breves descrições dos parâmetros para ajudá-lo a usar a interface da linha de comando (CLI) do AWS Encryption SDK . 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 exemplos, consulte [Exemplos da CLI AWS de criptografia](crypto-cli-examples.md). Para obter a documentação completa, consulte [Leia os documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/). **Topics** + [AWS Sintaxe da CLI de criptografia](#crypto-cli-syntax) + [AWS Parâmetros de linha de comando da CLI de criptografia](#crypto-cli-parameters) + [Parâmetros avançados](#cli-advanced-parameters) ## AWS Sintaxe da CLI de criptografia Esses diagramas de sintaxe da CLI de AWS criptografia mostram a sintaxe de cada tarefa que você executa com a CLI de criptografia. AWS Eles representam a sintaxe recomendada na versão 2.1 do AWS Encryption CLI. *x* e mais tarde. 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. **nota** A menos que indicado na descrição do parâmetro, cada parâmetro ou atributo pode ser usado apenas uma vez em cada comando. Se você usar um atributo que um parâmetro não suporta, a CLI de AWS criptografia ignora esse atributo não suportado sem um aviso ou erro. **Obter ajuda** Para obter a sintaxe completa da CLI de AWS criptografia com descrições de parâmetros, use ou. `--help` `-h` ``` aws-encryption-cli (--help | -h) ``` **Obter a versão** Para obter o número da versão da sua instalação do AWS Encryption CLI, use. `--version` Certifique-se de incluir a versão ao fazer perguntas, relatar problemas ou compartilhar dicas sobre como usar a CLI de AWS criptografia. ``` aws-encryption-cli --version ``` **Criptografar dados** O diagrama da sintaxe a seguir mostra os parâmetros usados por um comando **encrypt**. ``` aws-encryption-cli --encrypt --input [--recursive] [--decode] --output [--interactive] [--no-overwrite] [--suffix []] [--encode] --wrapping-keys [--wrapping-keys] ... key= [key=] ... [provider=] [region=] [profile=] --metadata-output [--overwrite-metadata] | --suppress-metadata] [--commitment-policy ] [--encryption-context [ ...]] [--max-encrypted-data-keys ] [--algorithm ] [--caching ] [--frame-length ] [-v | -vv | -vvv | -vvvv] [--quiet] ``` **Descriptografar dados** O diagrama da sintaxe a seguir mostra os parâmetros usados por um comando **decrypt**. Na versão 1.8.*x*, o parâmetro `--wrapping-keys` é opcional ao descriptografar, mas é recomendado. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` passou a ser necessário ao criptografar e descriptografar. Para AWS KMS keys, você pode usar o atributo **key** para especificar chaves de encapsulamento (prática recomendada) ou definir o atributo **discovery** como`true`, o que não limita as chaves de encapsulamento que podem ser usadas pela CLI de criptografia da AWS . ``` aws-encryption-cli --decrypt (or [--decrypt-unsigned]) --input [--recursive] [--decode] --output [--interactive] [--no-overwrite] [--suffix []] [--encode] --wrapping-keys [--wrapping-keys] ... [key=] [key=] ... [discovery={true|false}] [discovery-partition= discovery-account= [discovery-account=] ...] [provider=] [region=] [profile=] --metadata-output [--overwrite-metadata] | --suppress-metadata] [--commitment-policy ] [--encryption-context [ ...]] [--buffer] [--max-encrypted-data-keys ] [--caching ] [--max-length ] [-v | -vv | -vvv | -vvvv] [--quiet] ``` **Usar arquivos de configuração** Você pode fazer referência a arquivos de configuração que contêm parâmetros e seus valores. Isso é equivalente a digitar os parâmetros e os valores no comando. Para ver um exemplo, consulte [Como armazenar parâmetros em um arquivo de configuração](crypto-cli-how-to.md#crypto-cli-config-file). ``` aws-encryption-cli @ # In a PowerShell console, use a backtick to escape the @. aws-encryption-cli `@ ``` ## AWS Parâmetros de linha de comando da CLI de criptografia Essa lista fornece uma descrição básica dos parâmetros do comando AWS Encryption CLI. Para obter uma descrição completa, consulte a [aws-encryption-sdk-clidocumentação](http://aws-encryption-sdk-cli.readthedocs.io/en/latest/). **--encrypt (-e)** Criptografa os dados de entrada. Cada comando deve ter um parâmetro `--encrypt`, `--decrypt` ou `--decrypt-unsigned`. **--decrypt (-d)** Descriptografa os dados de entrada. Cada comando deve ter um parâmetro `--encrypt`, `--decrypt` ou `--decrypt-unsigned`. **--decrypt-unsigned [Introduzido nas versões 1.9.*x* e 2.2.*x*]** O parâmetro `--decrypt-unsigned` descriptografa o texto cifrado e garante que as mensagens não sejam assinadas antes de serem descriptografadas. Use esse parâmetro se você usou o parâmetro `--algorithm` e selecionou um pacote de algoritmos sem assinatura digital para criptografar dados. Se o texto cifrado for assinado, a descriptografia falhará. Você pode usar `--decrypt` ou `--decrypt-unsigned` para fazer a descriptografia, mas não ambos. **--wrapping-keys (-w) [Introduzido na versão 1.8.*x*]** Especifica as [chaves de encapsulamento](concepts.md#master-key) (ou *chaves mestras*) usadas em operações de criptografia e descriptografia. Você pode usar [vários parâmetros de `--wrapping-keys`](crypto-cli-how-to.md#cli-many-cmks) em cada comando. A partir da versão 2.1.*x*, o parâmetro `--wrapping-keys` passou a ser necessário ao criptografar e descriptografar comandos. Na versão 1.8. *x*, os comandos encrypt requerem um parâmetro `--wrapping-keys` ou `--master-keys`. Nos comandos decrypt fs versão 1.8. *x* um parâmetro `--wrapping-keys` é opcional, mas recomendado. Ao usar usam um provedor de chaves mestres personalizado, os comandos encrypt e decrypt exigem os atributos **key** e **provider**. Ao usar AWS KMS keys, os comandos de criptografia exigem um atributo **chave**. Os comandos decrypt exigem que um atributo**key** ou um atributo **discovery** sejam definidos com um valor de `true` (mas não ambos). Usar o atributo **key** ao descriptografar é uma [prática recomendada do AWS Encryption SDK](best-practices.md). Ela particularmente importante se você estiver descriptografando lotes de mensagens desconhecidas, como aquelas em um bucket do Amazon S3 ou em uma fila do Amazon SQS. Para ver um exemplo de como usar chaves AWS KMS multirregionais como chaves de agrupamento, consulte. [Usando várias regiões AWS KMS keys](configure.md#config-mrks) **Attributes**: o valor do parâmetro `--wrapping-keys` consiste nos seguintes atributos. O formato é `attribute_name=value`. **key** Identifica a chave de encapsulamento usada na operação. O formato é um par de **key**=ID. Você pode especificar vários atributos **key** em cada valor do parâmetro `--wrapping-keys`. + **Comandos encrypt**: todos os comandos encrypt exigem o atributo **key**. Quando você usa um comando AWS KMS key in a encrypt, o valor do atributo **chave** pode ser um ID de chave, ARN de chave, nome de alias ou ARN de alias. Para obter descrições dos identificadores de AWS KMS chave, consulte [Identificadores de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) no Guia do *AWS Key Management Service desenvolvedor*. + **Comandos decrypt**: ao descriptografar com as AWS KMS keys, o parâmetro `--wrapping-keys` exige que o valor de um atributo**key** seja definido como um [ARN de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) ou que o valor de um atributo **discovery** seja definido como `true` (mas não ambos). Usar o atributo **key** é uma [prática recomendada do AWS Encryption SDK](best-practices.md). Ao descriptografar com um provedor de chave mestra personalizado, o atributo **key** é obrigatório. **nota** Para especificar uma chave de AWS KMS encapsulamento em um comando de descriptografia, o valor do atributo **chave deve ser um ARN de chave**. Se você usar um ID de chave, nome de alias ou ARN de alias, a AWS CLI de criptografia não reconhecerá a chave de empacotamento. Você pode especificar vários atributos **key** em cada valor do parâmetro `--wrapping-keys`. No entanto, qualquer atributo **provider**, **region** e **profile** em um parâmetro `--wrapping-keys` será aplicável a todas chaves de encapsulamento no valor desse parâmetro. Para especificar chaves de encapsulamento com diferentes valores de atributos, use vários parâmetros `--wrapping-keys` no comando. **discovery** Permite que a CLI de AWS criptografia use qualquer uma para AWS KMS key descriptografar a mensagem. O valor de **discovery** pode ser `true` ou`false`. O valor padrão é `false`. O atributo **discovery** é válido apenas em comandos decrypt e somente quando o provedor de chaves mestras for do AWS KMS. Ao descriptografar com AWS KMS keys, o `--wrapping-keys` parâmetro requer um **atributo-chave** ou um atributo de **descoberta** com um valor de `true` (mas não ambos). Se você usar o atributo **key**, poderá usar um atributo de **discovery** com um valor definido como `false` para rejeitar explicitamente a descoberta. + `False`(padrão) — Quando o atributo de **descoberta** não é especificado ou seu valor é`false`, a CLI de AWS criptografia descriptografa a mensagem usando somente o AWS KMS keys especificado pelo **atributo-chave** do parâmetro. `--wrapping-keys` Se você não especificar um atributo **key** quando discovery for `false`, o comando decrypt falhará. [Esse valor oferece suporte a uma prática AWS recomendada de CLI de criptografia.](best-practices.md) + `True`— Quando o valor do atributo de **descoberta** é`true`, a CLI de AWS criptografia obtém os metadados AWS KMS keys da mensagem criptografada e os usa AWS KMS keys para descriptografar a mensagem. O atributo de **descoberta** com um valor de `true` se comporta como as versões da AWS CLI de criptografia antes da versão 1.8. *x* que não permitia que você especificasse uma chave de empacotamento ao descriptografar. No entanto, sua intenção de usar qualquer um AWS KMS key é explícita. Se você especificar um atributo **key** quando discovery for `true`, o comando decrypt falhará. O `true` valor pode fazer com que a CLI de AWS criptografia seja usada AWS KMS keys em diferentes Contas da AWS regiões ou tente usar algo AWS KMS keys que o usuário não esteja autorizado a usar. Quando a **descoberta** é`true`, é uma prática recomendada usar os atributos **discovery-partition** e **discovery-account** para limitar o AWS KMS keys uso aos atributos especificados por você. Contas da AWS **discovery-account** Limita o AWS KMS keys usado para descriptografia aos especificados. Conta da AWS O único valor válido para esse atributo é um [ID de Conta da AWS](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html). Esse atributo é opcional e válido somente em comandos de descriptografia com os AWS KMS keys quais o atributo de **descoberta** está definido `true` e o atributo de partição **de descoberta é especificado**. Cada atributo **da conta descoberta** usa apenas uma Conta da AWS ID, mas você pode especificar vários atributos da **conta descoberta** no mesmo parâmetro. `--wrapping-keys` Todas as contas especificadas em um determinado parâmetro `--wrapping-keys` devem estar na partição da AWS especificada. **discovery-partition** Especifica a AWS partição das contas no atributo **discovery-account**. Seu valor deve ser uma AWS partição`aws`, como`aws-cn`, ou`aws-gov-cloud`. Para obter mais informações, consulte [Nomes de atributo da Amazon](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) no *Referência geral da AWS*. Esse atributo é obrigatório quando você usa o atributo **discovery-account**. Você pode especificar somente um atributo **discovery-partition** em cada parâmetro `--wrapping keys`. Para especificar Contas da AWS em várias partições, use um `--wrapping-keys` parâmetro adicional. **provider** Identifica o [provedor de chaves mestres](concepts.md#master-key-provider). O formato é um par de **provider**=ID. O valor padrão, **aws-kms**, representa. AWS KMS Esse atributo é necessário somente quando o provedor da chave mestra não é AWS KMS. **region** Identifica o Região da AWS de um AWS KMS key. Esse atributo é válido somente para AWS KMS keys. É usado apenas quando o identificador da **chave** não especifica uma região; caso contrário, é ignorado. Quando usado, ele substitui a região padrão no perfil chamado AWS CLI. **perfil** Identifica um [perfil AWS CLI nomeado](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html). Esse atributo é válido somente para AWS KMS keys. A região no perfil é usada apenas quando o identificador da chave não especifica uma região e não há nenhum atributo **region** no comando. **--input (-i)** Especifica o local dos dados a serem criptografados ou descriptografados. Esse parâmetro é obrigatório. O valor pode ser um caminho para um arquivo ou diretório ou um nome de arquivo padrão. Se você estiver redirecionando a entrada para o comando (stdin), use `-`. Se a entrada não existir, o comando é concluído com êxito sem erro ou aviso. **--recursive (-r, -R)** Executa a operação nos arquivos no diretório de entrada e em seus subdiretórios. Esse parâmetro é necessário quando o valor de `--input` é um diretório. **--decode** Decodifica entrada codificada em Base64. Se estiver descriptografando uma mensagem que foi criptografada e, em seguida, codificado, você deverá decodificar a mensagem antes de descriptografá-la. Esse parâmetro faz isso para você. Por exemplo, se você tiver usado o parâmetro `--encode` em um comando encrypt, use o parâmetro `--decode` no comando decrypt correspondente. Você também pode usar esse parâmetro para decodificar a entrada codificada em Base64 antes de criptografá-la. **--output (-o)** Especifica um destino para a saída. Esse parâmetro é obrigatório. O valor pode ser um nome de arquivo, um diretório existente ou `-`, que grava a saída na linha de comando (stdout). Se o diretório de saída especificado não existir, o comando falhará. Se a entrada contiver subdiretórios, a AWS CLI de criptografia reproduzirá os subdiretórios no diretório de saída que você especificar. Por padrão, a CLI AWS de criptografia sobrescreve arquivos com o mesmo nome. Para alterar esse comportamento, use os parâmetros `--interactive` ou `--no-overwrite`. Para suprimir o aviso de substituição, use o parâmetro `--quiet`. Se um comando que deve substituir um arquivo de saída falhar, o arquivo de saída será excluído. **--interactive** Solicita antes de substituir o arquivo. **--no-overwrite** Não substitui arquivos. Em vez disso, se o arquivo de saída existir, a CLI de AWS criptografia ignora a entrada correspondente. **--sufixo** Especifica um sufixo de nome de arquivo personalizado para arquivos criados pela AWS CLI de criptografia. Para indicar nenhum sufixo, use o parâmetro sem um valor (`--suffix`). Por padrão, quando o parâmetro `--output` não especifica um nome de arquivo, o nome do arquivo de saída tem o mesmo nome que o nome do arquivo de entrada mais o sufixo. O sufixo para comandos encrypt é `.encrypted`. O sufixo para comandos decrypt é `.decrypted`. **--encode** Aplica codificação de Base64 (de binário para texto) à saída. A codificação impede que o programa shell do host interprete incorretamente caracteres não ASCII no texto de saída. Use esse parâmetro ao gravar uma saída criptografada em stdout (`--output -`), especialmente em um PowerShell console, mesmo quando estiver canalizando a saída para outro comando ou salvando-a em uma variável. **--metadata-output** Especifica um local para metadados sobre as operações de criptografia. Insira um caminho e um nome de arquivo. Se o diretório não existir, o comando falhará. Para gravar os metadados na linha de comando (stdout), use `-`. Você não pode gravar a saída do comando (`--output`) e a saída dos metadados (`--metadata-output`) em stdout no mesmo comando. Além disso, quando o valor de `--input` ou `--output` for um diretório (sem nomes de arquivos), você não poderá gravar a saída de metadados no mesmo diretório ou em qualquer subdiretório desse diretório. Se você especificar um arquivo existente, por padrão, a CLI de AWS criptografia anexará novos registros de metadados a qualquer conteúdo do arquivo. Esse recurso permite que você crie um único arquivo que contém os metadados de todas as suas operações de criptografia. Para substituir o conteúdo em um arquivo existente, use o parâmetro `--overwrite-metadata`. A CLI de AWS criptografia retorna um registro de metadados formatado em JSON para cada operação de criptografia ou descriptografia que o comando executa. Cada registro de metadados inclui os caminhos completos para os arquivos de entrada e de saída, o contexto de criptografia, o pacote de algoritmos e outras informações valiosas que você pode usar para rever a operação e verificar se ela atende a seus padrões de segurança. **--overwrite-metadata** Substitui o conteúdo no arquivo de saída de metadados. Por padrão, o parâmetro `--metadata-output` acrescenta metadados a qualquer conteúdo existente no arquivo. **--suppress-metadata (-S)** Suprime os metadados sobre a operação de criptografia ou de descriptografia. **--commitment-policy** Especifica a [política de compromisso](concepts.md#commitment-policy) para comandos encrypt e decrypt. A política de compromisso determina se sua mensagem será criptografada e descriptografada com o atributo de segurança [confirmação de chave](concepts.md#key-commitment). O parâmetro `--commitment-policy` foi introduzido na versão 1.8.*x.*. Ele 'é válido em comandos de criptografia e descriptografia. **Na versão 1.8. ***x*, a CLI de AWS criptografia usa a política de `forbid-encrypt-allow-decrypt` compromisso para todas as operações de criptografia e descriptografia. Quando você usa o parâmetro `--wrapping-keys` em um comando encrypt ou decrypt, é obrigatório que um parâmetro `--commitment-policy` seja definido com o valor `forbid-encrypt-allow-decrypt`. Se você não usar o parâmetro`--wrapping-keys`, o parâmetro `--commitment-policy` será inválido. Definir uma política de compromisso explicitamente impede que sua política de compromisso seja alterada automaticamente para `require-encrypt-require-decrypt` quando você atualizar para a versão 2.1.*x* A partir da **versão 2.1.***x*, todos os valores da política de compromisso são compatíveis. O parâmetro `--commitment-policy` é opcional e o valor padrão é `require-encrypt-require-decrypt`. Esse parâmetro tem os valores a seguir: + `forbid-encrypt-allow-decrypt`: não é possível criptografar com confirmação de chave. Ele pode descriptografar textos cifrados criptografados com ou sem confirmação de chave. Na versão 1.8.*x*, esse é o único valor válido. A CLI de AWS criptografia usa a política de `forbid-encrypt-allow-decrypt` compromisso para todas as operações de criptografia e descriptografia. + `require-encrypt-allow-decrypt`: criptografa somente com confirmação de chave. Descriptografa com e sem compromisso chave. Esse valor foi introduzido na versão 2.1.*x.*. + `require-encrypt-require-decrypt` (padrão): criptografa e descriptografa somente com confirmação de chave. Esse valor foi introduzido na versão 2.1.*x.*. É o valor padrão em versões 2.1.*x.* e posteriores. Com esse valor, a CLI de AWS criptografia não descriptografará nenhum texto cifrado que tenha sido criptografado com versões anteriores do. AWS Encryption SDK Para obter informações detalhadas sobre como definir sua política de compromisso, consulte [Migrando seu AWS Encryption SDK](migration.md). **--encryption-context (-c)** Especifica um [contexto de criptografia](crypto-cli-how-to.md#crypto-cli-encryption-context) para a operação. Esse parâmetro não é obrigatório, mas é recomendado. + Em um comando `--encrypt`, insira um ou mais pares de `name=value`. Use espaços para separar os pares. + Em um comando `--decrypt`, insira pares de `name=value`, elementos `name` sem valores ou ambos. Se o `name` ou o `value` em um par de `name=value` incluir espaços ou caracteres especiais, coloque o par inteiro entre aspas. Por exemplo, .`--encryption-context "department=software development"` **--buffer (-b) [Introduzido nas versões 1.9.*x* e 2.2.*x*]** Retorna texto simples somente após o processamento de todas as entradas, incluindo a verificação da assinatura digital, se houver uma. **-- max-encrypted-data-keys [Introduzido nas versões 1.9. *x* e 2.2. *x*]** Especifica o número máximo de chaves de dados criptografadas em uma mensagem criptografada. Esse parâmetro é opcional. Os valores válidos são 1–65.535. Se você omitir esse parâmetro, a CLI de AWS criptografia não impõe nenhum máximo. Uma mensagem criptografada pode conter até 65.535 (2^16 - 1) chaves de dados criptografadas. Você pode usar esse parâmetro em comandos encrypt para evitar a malformação de uma mensagem. Você pode usá-lo em comandos decrypt para detectar mensagens maliciosas e evitar descriptografar mensagens com várias chaves de dados criptografadas que você não pode descriptografar. Para obter detalhes e um exemplo, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys). **--help (-h)** Imprime o uso e a sintaxe na linha de comando. **--version** Obtém a versão da CLI AWS de criptografia. **-v \$1 -vv \$1 -vvv \$1 -vvvv** Exibe informações, avisos e mensagens de depuração detalhados. Os detalhes na saída aumentam com o número de `v`s no parâmetro. A configuração mais detalhada (`-vvvv`) retorna dados em nível de depuração da AWS CLI de criptografia e de todos os componentes que ela usa. **--quiet (-q)** Suprime mensagens de aviso, como a mensagem que aparece quando você substitui um arquivo de saída. **--master-keys (-m) [Descontinuado]** O parâmetro --master-keys foi descontinuado na versão 1.8.*x* foi removido na versão 2.1.*x*. Em vez dele, use o parâmetro [--wrapping-keys](#wrapping-keys). Especifica as [chaves mestres](concepts.md#master-key) usadas em operações de criptografia e descriptografia. Você pode usar vários parâmetros de chaves mestras em cada comando. O parâmetro `--master-keys` é necessário em comandos encrypt. Ele é necessário em comandos decrypt somente quando você estiver usando um provedor de chaves mestras personalizado (que não seja do AWS KMS). **Attributes**: o valor do parâmetro `--master-keys` consiste nos seguintes atributos. O formato é `attribute_name=value`. **key** Identifica a [chave de encapsulamento](concepts.md#master-key) usada na operação. O formato é um par de **key**=ID. O atributo **key** é obrigatório em todos os comandos encrypt. Quando você usa um comando AWS KMS key in a encrypt, o valor do atributo **chave** pode ser um ID de chave, ARN de chave, nome de alias ou ARN de alias. Para obter detalhes sobre identificadores de AWS KMS chave, 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 atributo **key** é necessário em comandos decrypt quando o provedor de chaves mestras não for o AWS KMS. O atributo **key** não é permitido em comandos que descriptografam dados que foram criptografados com uma AWS KMS key. Você pode especificar vários atributos **key** em cada valor do parâmetro `--master-keys`. No entanto, qualquer atributo **provider**, **region** e **profile** aplica-se a todas as chaves mestres no valor do parâmetro. Para especificar chaves mestras com diferentes valores de atributos, use vários parâmetros `--master-keys` no comando. **provider** Identifica o [provedor de chaves mestres](concepts.md#master-key-provider). O formato é um par de **provider**=ID. O valor padrão, **aws-kms**, representa. AWS KMS Esse atributo é necessário somente quando o provedor da chave mestra não é AWS KMS. **region** Identifica o Região da AWS de um AWS KMS key. Esse atributo é válido somente para AWS KMS keys. É usado apenas quando o identificador da **chave** não especifica uma região; caso contrário, é ignorado. Quando usado, ele substitui a região padrão no perfil chamado AWS CLI. **perfil** Identifica um [perfil AWS CLI nomeado](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html). Esse atributo é válido somente para AWS KMS keys. A região no perfil é usada apenas quando o identificador da chave não especifica uma região e não há nenhum atributo **region** no comando. ## Parâmetros avançados **--algorithm** Especifica um [pacote de algoritmos](concepts.md#crypto-algorithm) alternativo. Esse parâmetro é opcional e válido apenas em comandos encrypt. Se você omitir esse parâmetro, a CLI de AWS criptografia usará um dos conjuntos de algoritmos padrão para AWS Encryption SDK o apresentado na versão 1.8. *x.* Ambos os algoritmos padrão usam o AES-GCM com um [HKDF](https://en.wikipedia.org/wiki/HKDF), uma assinatura ECDSA e uma chave de criptografia de 256 bits. Um usa confirmação de chave; o outro não. A escolha do pacote de algoritmos padrão é determinada pela [política de compromisso](concepts.md#commitment-policy) do comando. Os pacotes de algoritmo padrão são recomendados para a maioria das operações de criptografia. Para obter uma lista de valores válidos, consulte os valores do parâmetro `algorithm` em [Leia os documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/index.html#execution). **--frame-length** Cria uma saída com o tamanho da moldura especificado. Esse parâmetro é opcional e válido apenas em comandos encrypt. Digite um valor em bytes. Os valores válidos são 0 e 1–2^31-1. Um valor igual a 0 indica dados sem moldura. O padrão é 4.096 (bytes). Sempre que possível, use dados com moldura. O AWS Encryption SDK suporta dados não emoldurados somente para uso antigo. Algumas implementações de linguagem do ainda AWS Encryption SDK podem gerar texto cifrado sem moldura. Todas as implementações de linguagem compatíveis podem descriptografar texto cifrado e não emoldurado. **--max-length** Indica o tamanho máximo da moldura (ou o tamanho máximo do conteúdo de mensagens sem moldura) a ser lido em mensagens criptografadas. Esse parâmetro é opcional e válido apenas em comandos decrypt. Ele foi projetado para proteção contra a descriptografia de texto cifrado mal-intencionado extremamente grande. Digite um valor em bytes. Se você omitir esse parâmetro, o AWS Encryption SDK não limitará o tamanho do quadro ao descriptografar. **--caching** Habilita o recurso de [armazenamento em cache de chaves de dados](data-key-caching.md), que reutiliza chaves de dados, em vez de gerar uma nova chave de dados para cada arquivo de entrada. Esse parâmetro é compatível com um cenário avançado. Não deixe de ler a documentação [Armazenamento em cache de chaves de dados](data-key-caching.md) antes de usar esse recurso. O parâmetro `--caching` tem os seguintes atributos. **capacity (obrigatório)** Determina o número máximo de entradas no cache. O valor mínimo é 1. Não há um valor máximo. **max\$1age (obrigatório)** Determina o tempo em que as entradas do cache são usadas, em segundos, a partir do momento em que são adicionadas ao cache. Digite um valor maior que 0. Não há um valor máximo. **max\$1messages\$1encrypted (opcional)** Determina o número máximo de mensagens que uma entrada armazenada em cache pode criptografar. Os valores válidos são 1–2^32. O valor padrão é 2^32 (mensagens). **max\$1bytes\$1encrypted (opcional)** Determina o número máximo de bytes que uma entrada armazenada em cache pode criptografar. Os valores válidos são 0 e 1–2^63 - 1. O valor padrão é 2^63 - 1 (mensagens). Um valor de 0 permite usar armazenamento em cache de chaves de dados somente quando você está criptografando strings de mensagem vazias. # Versões da CLI AWS de criptografia Recomendamos que você use a versão mais recente da CLI de AWS criptografia. **nota** [Versões da CLI de AWS criptografia anteriores à 4.0.0 estão em fase. end-of-support](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) Você pode atualizar com segurança a partir da versão 2.1.*x* e posteriores até a versão mais recente da CLI de criptografia da AWS sem realizar alterações no código ou nos dados. No entanto, os [novos atributos de segurança](about-versions.md#version-2) introduzidos na versão 2.1.*x* não são compatíveis com versões anteriores. Para atualizar a partir da versão 1.7. *x* ou anterior, você deve primeiro atualizar para a última 1. versão *x* da CLI AWS de criptografia. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). 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 informações sobre versões significativas do AWS Encryption SDK, consulte[Versões do AWS Encryption SDK](about-versions.md). **Qual versão devo usar?** Se você é novo na CLI AWS de criptografia, use a versão mais recente. Para descriptografar dados criptografados por uma versão AWS Encryption SDK anterior à 1.7. *x*, migre primeiro para a versão mais recente da CLI de AWS criptografia. Faça [todas as alterações recomendadas](migration-guide.md) antes de atualizar para a versão 2.1.*x* ou versões posteriores. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). **Saiba mais** + Para obter informações detalhadas sobre as alterações e orientações para migrar para essas novas versões, consulte [Migrando seu AWS Encryption SDK](migration.md). + Para obter descrições dos novos parâmetros e atributos da CLI de AWS criptografia, consulte. [AWS Encryption SDK Referência de sintaxe e parâmetros da CLI](crypto-cli-reference.md) As listas a seguir descrevem a alteração na CLI de AWS criptografia nas versões 1.8. *x* e 2.1. *x.* ## Versão 1.8. *x* mudanças na CLI AWS de criptografia + Descontinua o parâmetro `--master-keys`. Em vez disso, use o parâmetro `--wrapping-keys`. + Adiciona o parâmetro `--wrapping-keys` (`-w`). Compatível com todos os atributos do parâmetro `--master-keys`. Também adiciona os seguintes atributos opcionais, que são válidos somente ao descriptografar com AWS KMS keys. + **discovery** + **discovery-partition** + **discovery-account** Para provedores de chaves mestras personalizadas, os comandos `--encrypt` e-`-decrypt` exigem um parâmetro `--wrapping-keys` ou um parâmetro `--master-keys` (mas não ambos). Além disso, um `--encrypt` comando com AWS KMS keys requer um `--wrapping-keys` parâmetro ou um `--master-keys` parâmetro (mas não ambos). Em um `--decrypt` comando com AWS KMS keys, o `--wrapping-keys` parâmetro é opcional, mas recomendado, pois é obrigatório na versão 2.1. *x.* Se você usá-lo, deverá especificar o **key** ou o atributo **discovery** com um valor definido como `true` (mas não ambos). + Adiciona o parâmetro `--commitment-policy`. O único valor válido é `forbid-encrypt-allow-decrypt`. A política de compromisso `forbid-encrypt-allow-decrypt` é usada em todos os comandos encrypt e decrypt. Na versão 1.8.*x*, quando você usa o parâmetro `--wrapping-keys`, é necessário definir um parâmetro `--commitment-policy` com o valor `forbid-encrypt-allow-decrypt`. Definir o valor explicitamente impede que sua [política de compromisso](concepts.md#commitment-policy) seja alterada automaticamente para `require-encrypt-require-decrypt` quando você atualizar para a versão 2.1.*x.* ## Versão 2.1. *x* mudanças na CLI AWS de criptografia + Remove o parâmetro `--master-keys`. Em vez disso, use o parâmetro `--wrapping-keys`. + O parâmetro `--wrapping-keys` é obrigatório em comandos encrypt. Você deve especificar o atributo **key** ou o atributo **discovery** com um valor definido como `true` (mas não ambos). + O parâmetro `--commitment-policy` oferece suporte aos seguintes valores: Para obter detalhes, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md). + `forbid-encrypt-allow-decrypt` + `require-encrypt-allow-decrypt` + `require-encrypt-require decrypt` (padrão) + O parâmetro `--commitment-policy` é opcional na versão 2.1.*x.*. O valor padrão é `require-encrypt-require-decrypt`. ## Versão 1.9. *x* e 2.2. *x* mudanças na CLI AWS de criptografia + Adiciona o parâmetro `--decrypt-unsigned`. Para obter detalhes, consulte [Versão 2.2*x*](about-versions.md#version2.2.x). + Adiciona o parâmetro `--buffer`. Para obter detalhes, consulte [Versão 2.2*x*](about-versions.md#version2.2.x). + Adiciona o parâmetro `--max-encrypted-data-keys`. Para obter detalhes, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys). ## Versão 3.0. *x* mudanças na CLI AWS de criptografia + Adiciona suporte para chaves AWS KMS multirregionais. Para obter mais detalhes, consulte [Usando várias regiões AWS KMS keys](configure.md#config-mrks).