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 linguagens de programação O AWS Encryption SDK está disponível para as seguintes linguagens de programação. As implementações de linguagem são interoperáveis É possível criptografar com uma implementação de linguagem e descriptografar com outra. A interoperabilidade pode estar sujeita às restrições de linguagem. Em caso afirmativo, essas restrições estarão descritas no tópico sobre a implementação de linguagem. Além disso, ao criptografar e descriptografar, é necessário usar tokens de autenticação compatíveis ou chaves mestras e provedores de chaves mestras. Para obter mais detalhes, consulte [Compatibilidade dos tokens de autenticação](choose-keyring.md#keyring-compatibility). **Topics** + [C](c-language.md) + [.NET](dot-net.md) + [Go](go.md) + [Java](java.md) + [JavaScript](javascript.md) + [Python](python.md) + [Rust](rust.md) + [Interface de linha de comando](crypto-cli.md) # AWS Encryption SDK for C O AWS Encryption SDK for C fornece uma biblioteca de criptografia do lado do cliente para desenvolvedores que estão escrevendo aplicativos em C. Ela também serve como base para implementações de linguagens de programação de nível superior. AWS Encryption SDK Como todas as implementações do AWS Encryption SDK, o AWS Encryption SDK for C oferece recursos avançados de proteção de dados. Os recursos incluem [criptografia de envelope](concepts.md#envelope-encryption), AAD (additional authenticated data - dados autenticados adicionais) e [pacotes de algoritmos](concepts.md#crypto-algorithm) de chave simétrica segura e autenticada, como o AES-GCM de 256 bits com derivação de chave e assinatura. Todas as implementações específicas de linguagem do AWS Encryption SDK são totalmente interoperáveis. [Por exemplo, você pode criptografar dados com o AWS Encryption SDK for C e descriptografá-los com [qualquer implementação de linguagem compatível](programming-languages.md), incluindo a CLI de criptografia.AWS](crypto-cli.md) AWS Encryption SDK for C Isso requer que AWS SDK para C\$1\$1 o interaja com AWS Key Management Service (AWS KMS). Você precisa usá-lo somente se estiver usando o [AWS KMS token de autenticação](use-kms-keyring.md) opcional. No entanto, AWS Encryption SDK não requer AWS KMS nenhum outro AWS serviço. **Saiba mais** + Para obter detalhes sobre a programação com o AWS Encryption SDK for C, consulte os [exemplos em C](c-examples.md), os [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) no [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em GitHub e a [documentação da AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/). + Para uma discussão sobre como usar o para criptografar dados AWS Encryption SDK for C para que você possa descriptografá-los em vários Regiões da AWS, consulte [Como descriptografar textos cifrados em várias regiões com o em C](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/) no Blog de Segurança. AWS Encryption SDK AWS **Topics** + [Instalar](c-language-installation.md) + [Uso do C SDK](c-language-using.md) + [Exemplos](c-examples.md) # Instalando o AWS Encryption SDK for C Instale a versão mais recente do AWS Encryption SDK for C. **nota** Todas as versões AWS Encryption SDK for C anteriores à 2.0.0 estão em [end-of-supportfase](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.0.*x* e posteriores até a versão mais recente do AWS Encryption SDK for C 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.0.*x* não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.*x* até a versão 2.0. *x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente do AWS Encryption SDK for C. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). Você pode encontrar instruções detalhadas para instalar e criar o AWS Encryption SDK for C no [arquivo README](https://github.com/aws/aws-encryption-sdk-c/#readme) do [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositório. Ele inclui instruções para criar nas plataformas Amazon Linux, Ubuntu, macOS e Windows. Antes de começar, decida se deseja usar [tokens de autenticação do AWS KMS](use-kms-keyring.md) no AWS Encryption SDK. Se você usa um AWS KMS chaveiro, você precisa instalar o. AWS SDK para C\$1\$1 O AWS SDK é necessário para interagir com [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS). Quando você AWS Encryption SDK usa AWS KMS chaveiros, eles usam AWS KMS para gerar e proteger as chaves de criptografia que protegem seus dados. Você não precisa instalar o AWS SDK para C\$1\$1 se estiver usando outro tipo de chaveiro, como um chaveiro AES bruto, um chaveiro RSA bruto ou um chaveiro múltiplo que não inclua um chaveiro. AWS KMS No entanto, ao usar um tipo de token de autenticação bruto, você precisa gerar e proteger suas próprias chaves de encapsulamento brutas. Se você estiver com problemas com a instalação, [registre um problema](https://github.com/aws/aws-encryption-sdk-c/issues) no repositório do `aws-encryption-sdk-c` ou use os links de feedback desta página. # Usando o AWS Encryption SDK for C Este tópico explica alguns dos recursos do AWS Encryption SDK for C que não são suportados em outras implementações de linguagem de programação. Esses exemplos mostram como usar a versão 2.0.[*x*](about-versions.md) e versões posteriores do AWS Encryption SDK for C. Para exemplos que usam versões anteriores, encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-c/releases) do [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em. GitHub Para obter detalhes sobre a programação com o AWS Encryption SDK for C, consulte os [exemplos em C](c-examples.md), os [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) no [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em GitHub e a [documentação da AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/). Consulte também: [Tokens de autenticação](choose-keyring.md) **Topics** + [ ## Padrões para criptografar e descriptografar dados ](#c-language-using-pattern) + [ ## Contagem de referências ](#c-language-using-release) ## Padrões para criptografar e descriptografar dados Ao usar o AWS Encryption SDK for C, você segue um padrão semelhante a este: cria um [chaveiro](concepts.md#keyring), cria um [CMM](concepts.md#crypt-materials-manager) que usa o chaveiro, cria uma sessão que usa o CMM (e o chaveiro) e, em seguida, processa a sessão. 1. Carregar sequências de erro. Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração. Você só precisa chamá-lo uma vez, como no método `main`. ``` /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); ``` 2. Crie um token de autenticação. Configure o [token de autenticação](concepts.md#keyring) com as chaves de empacotamento que você deseja usar para criptografar suas chaves de dados. Este exemplo usa um [AWS KMS chaveiro](use-kms-keyring.md) com um AWS KMS key, mas você pode usar qualquer tipo de chaveiro em seu lugar. Para identificar um AWS KMS key em um chaveiro de criptografia no AWS Encryption SDK for C, especifique o ARN da [chave ou o ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) do [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn). Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter detalhes, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id). ``` const char * KEY_ARN = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(KEY_ARN); ``` 3. Crie uma sessão. No AWS Encryption SDK for C, você usa uma *sessão* para criptografar uma única mensagem de texto simples ou descriptografar uma única mensagem de texto cifrado, independentemente do tamanho. A sessão mantém o estado da mensagem durante todo o processamento. Configure a sessão com um alocador, um token de autenticação e um modo: `AWS_CRYPTOSDK_ENCRYPT` ou `AWS_CRYPTOSDK_DECRYPT`. Se você precisar alterar o modo da sessão, use o método `aws_cryptosdk_session_reset`. Quando você cria uma sessão com um chaveiro, ele cria AWS Encryption SDK for C automaticamente um gerenciador de materiais criptográficos (CMM) padrão para você. Você não precisa criar, manter ou destruir esse objeto. Por exemplo, a sessão a seguir usa o alocador e o token de autenticação definido na etapa 1. Ao criptografar dados, o modo é o `AWS_CRYPTOSDK_ENCRYPT`. ``` struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring); ``` 4. Criptografe ou descriptografe os dados. Para processar os dados na sessão, use o método `aws_cryptosdk_session_process`. Se o buffer de entrada for grande o suficiente para conter todo o texto simples, e o buffer de saída for grande o suficiente para conter todo o texto cifrado, você pode chamar `aws_cryptosdk_session_process_full`. No entanto, se precisar lidar com dados de streaming, você poderá chamar `aws_cryptosdk_session_process` em um loop. Para obter um exemplo, consulte o [file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp) . O `aws_cryptosdk_session_process_full` é introduzido nas AWS Encryption SDK versões 1.9. *x* e 2.2. *x.* Quando a sessão é configurada para criptografar dados, os campos em texto simples descrevem a entrada e os campos de texto cifrado descrevem a saída. O campo `plaintext` contém a mensagem que você deseja criptografar, e o campo `ciphertext` obtém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia. ``` /* Encrypting data */ aws_cryptosdk_session_process_full(session, ciphertext, ciphertext_buffer_size, &ciphertext_length, plaintext, plaintext_length) ``` Quando a sessão é configurada para descriptografar dados, os campos em texto cifrado descrevem a entrada e os campos em texto cifrado descrevem a saída. O campo `ciphertext` contém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia, e o campo `plaintext` obtém a mensagem em texto simples retornada pelo método de descriptografia. Para descriptografar os dados, chame o método `aws_cryptosdk_session_process_full`. ``` /* Decrypting data */ aws_cryptosdk_session_process_full(session, plaintext, plaintext_buffer_size, &plaintext_length, ciphertext, ciphertext_length) ``` ## Contagem de referências Para evitar vazamentos de memória, libere as referências a todos os objetos que você criou ao concluir. Caso contrário, ocorrerão vazamentos de memória. O SDK fornece métodos para facilitar essa tarefa. Sempre que você criar um objeto pai com um dos seguintes objetos filho, o objeto pai obtém e mantém uma referência ao objeto filho, da seguinte forma: + Um [token de autenticação](concepts.md#keyring), como criar uma sessão com um token de autenticação + Um [ gerenciador de materiais criptográficos](concepts.md#crypt-materials-manager) (CMM) padrão, como criar uma sessão ou um CMM personalizado com um CMM padrão + Um [cache de chaves de dados](data-key-caching.md), como criar um CMM de armazenamento em cache com um token de autenticação e um cache A menos que precise de uma referência independente ao objeto filho, você pode liberar a referência ao objeto filho assim que criar o objeto pai. A referência restante ao objeto filho é liberada quando o objeto pai é destruído. Esse padrão garante que você mantenha a referência a cada objeto somente pelo tempo necessário e não ocorra vazamento de memória causado por referências não liberadas. Você só é responsável por liberar referências aos objetos filho que cria explicitamente. Você não é responsável por gerenciar referências a objetos criados pelo SDK para você. Se o SDK criar um objeto, como o CMM padrão que o método `aws_cryptosdk_caching_cmm_new_from_keyring` adiciona a uma sessão, o SDK gerenciará a criação e a destruição do objeto e suas referências. No exemplo a seguir, ao criar uma sessão com um [token de autenticação](concepts.md#keyring), a sessão obtém uma referência ao token de autenticação e mantém essa referência até que a sessão seja destruída. Se você não precisar manter uma referência adicional ao token de autenticação, poderá usar o método `aws_cryptosdk_keyring_release` para liberar o objeto do token de autenticação assim que a sessão for criada. Esse método diminui a contagem de referências para o token de autenticação. A referência da sessão ao token de autenticação é liberada quando você chama `aws_cryptosdk_session_destroy` para destruir a sessão. ``` // The session gets a reference to the keyring. struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring); // After you create a session with a keyring, release the reference to the keyring object. aws_cryptosdk_keyring_release(keyring); ``` Para tarefas mais complexas, como reutilizar um token de autenticação para várias sessões ou especificar um pacote de algoritmos em um CMM, talvez seja necessário manter uma referência independente ao objeto. Se assim for, não chame os métodos de liberação imediatamente. Em vez disso, libere as referências quando você não estiver mais usando os objetos, além de destruir a sessão. Essa técnica de contagem de referência também funciona quando você está usando alternativas CMMs, como o CMM de cache para armazenamento em cache de [chaves de dados](data-key-caching.md). Ao criar um CMM de armazenamento em cache de um cache e de um token de autenticação, o CMM de armazenamento em cache obtém uma referência aos dois objetos. A menos que precise delas para outra tarefa, você pode liberar suas referências independentes para cache e o token de autenticação assim que o CMM de armazenamento em cache for criado. Depois, ao criar uma sessão com o CMM de armazenamento em cache, você pode liberar sua referência para o CMM de armazenamento em cache. Observe que você só é responsável por liberar referências a objetos que cria explicitamente. Os objetos criados pelos métodos para você, como o CMM padrão que é subjacente ao CMM de armazenamento em cache, são gerenciados pelo método. ``` / Create the caching CMM from a cache and a keyring. struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS); // Release your references to the cache and the keyring. aws_cryptosdk_materials_cache_release(cache); aws_cryptosdk_keyring_release(kms_keyring); // Create a session with the caching CMM. struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm); // Release your references to the caching CMM. aws_cryptosdk_cmm_release(caching_cmm); // ... aws_cryptosdk_session_destroy(session); ``` # AWS Encryption SDK for C exemplos Os exemplos a seguir mostram como usar o para AWS Encryption SDK for C criptografar e descriptografar dados. Esses exemplos mostram como usar as versões 2.0.*x* e posteriores do AWS Encryption SDK for C. Para exemplos que usam versões anteriores, encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-c/releases) do [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em. GitHub Quando você instala e constrói o AWS Encryption SDK for C, o código-fonte desses e de outros exemplos é incluído no `examples` subdiretório e eles são compilados e incorporados ao `build` diretório. Você também pode encontrá-los no subdiretório de [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) do [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositório em. GitHub **Topics** + [ ## Criptografar e descriptografar strings ](#c-example-strings) ## Criptografar e descriptografar strings O exemplo a seguir mostra como usar o para AWS Encryption SDK for C criptografar e descriptografar uma string. Este exemplo apresenta o [AWS KMS chaveiro](use-kms-keyring.md), um tipo de chaveiro que usa um AWS KMS key in [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) para gerar e criptografar chaves de dados. O exemplo inclui código escrito em C\$1\$1. AWS Encryption SDK for C Isso exige que AWS SDK para C\$1\$1 você ligue AWS KMS ao usar AWS KMS chaveiros. Se você estiver usando um chaveiro que não interage com AWS KMS, como um chaveiro AES bruto, um chaveiro RSA bruto ou um chaveiro múltiplo que não inclui um AWS KMS chaveiro, isso não é necessário. AWS SDK para C\$1\$1 Para obter ajuda na criação de um AWS KMS key, consulte [Criação de chaves](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) no *Guia do AWS Key Management Service desenvolvedor*. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte[Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id). **Consulte o exemplo de código completo**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp) **Topics** + [ ### Criptografar uma string ](#c-example-string-encrypt) + [ ### Descriptografar uma string ](#c-example-string-decrypt) ### Criptografar uma string A primeira parte deste exemplo usa um AWS KMS chaveiro com um AWS KMS key para criptografar uma string de texto sem formatação. Etapa 1. Carregar sequências de erro. Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração. Você só precisa chamá-lo uma vez, como no método `main`. ``` /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); ``` Etapa 2: estruturar o token de autenticação. Crie um AWS KMS chaveiro para criptografia. O chaveiro neste exemplo é configurado com um AWS KMS key, mas você pode configurar um AWS KMS chaveiro com vários AWS KMS keys, inclusive AWS KMS keys em contas diferentes Regiões da AWS e diferentes. Para identificar um AWS KMS key em um chaveiro de criptografia no AWS Encryption SDK for C, especifique o ARN da [chave ou o ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) do [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn). Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter detalhes, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id). [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id) Ao criar um chaveiro com vários AWS KMS keys, você especifica o AWS KMS key usado para gerar e criptografar a chave de dados de texto simples e uma matriz opcional de outros AWS KMS keys que criptografam a mesma chave de dados de texto sem formatação. Nesse caso, você especifica somente o gerador AWS KMS key. Antes de executar esse código, substitua o ARN da chave de exemplo por um válido. ``` const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); ``` Etapa 3: Criar uma sessão. Crie uma sessão usando o alocador, um enumerador de modo e o token de autenticação. Cada sessão requer um modo: `AWS_CRYPTOSDK_ENCRYPT` para criptografar ou `AWS_CRYPTOSDK_DECRYPT` para descriptografar. Para alterar o modo de uma sessão existente, use o método `aws_cryptosdk_session_reset`. Depois de criar um sessão com o token de autenticação, você poderá liberar sua referência ao token de autenticação usando o método fornecido pelo SDK. A sessão retém uma referência ao objeto token de autenticação durante sua vida útil. Referências ao token de autenticação e aos objetos de sessão são liberadas quando você destrói a sessão. Essa técnica de [contagem de referência](c-language-using.md#c-language-using-release) ajuda a evitar vazamentos de memória e a evitar que os objetos sejam liberados enquanto estão em uso. ``` struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring); /* When you add the keyring to the session, release the keyring object */ aws_cryptosdk_keyring_release(kms_keyring); ``` Etapa 4: Definir o contexto de criptografia. Um [contexto de criptografia](concepts.md#encryption-context) são dados autenticados adicionais arbitrários e que não são secretos. Quando você fornece um contexto de criptografia na criptografia, ele vincula AWS Encryption SDK criptograficamente o contexto de criptografia ao texto cifrado, de forma que o mesmo contexto de criptografia seja necessário para descriptografar os dados. O uso de um contexto de criptografia é opcional, mas o recomendamos como uma melhor prática. Primeiro, crie uma tabela de hash que inclua as strings de contexto de criptografia. ``` /* Allocate a hash table for the encryption context */ int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx) // Create encryption context strings AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example"); AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String"); AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company"); AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp"); // Put the key-value pairs in the hash table aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created) aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created) ``` Obtenha um ponteiro mutável para o contexto de criptografia na sessão. Depois, use a função `aws_cryptosdk_enc_ctx_clone` para copiar o contexto de criptografia na sessão. Mantemos a cópia em `my_enc_ctx` para que possamos validar o valor depois de descriptografar os dados. O contexto de criptografia faz parte da sessão, não é um parâmetro transmitido para a função de processo da sessão. Isso garante que o mesmo contexto de criptografia seja usado para todos os segmentos de uma mensagem, mesmo se a função de processo de sessão for chamada várias vezes para criptografar a mensagem inteira. ``` struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session); aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx) ``` Etapa 5: Criptografar a string. Para criptografar a string em texto simples, use o método `aws_cryptosdk_session_process_full` com a sessão no modo de criptografia. Esse método, introduzido nas AWS Encryption SDK versões 1.9. *x* e 2.2. *x*, foi projetado para criptografia e decodificação sem streaming. Para lidar com dados de streaming, chame o `aws_cryptosdk_session_process` continuamente. Na criptografia, os campos em texto simples são campos de entrada; os campos em texto cifrado são campos de saída. Concluído o processamento, o campo `ciphertext_output` conterá a [mensagem criptografada](concepts.md#message), incluindo o texto cifrado real, as chaves de dados criptografadas e o contexto de criptografia. Você pode descriptografar essa mensagem criptografada usando o AWS Encryption SDK para qualquer linguagem de programação compatível. ``` /* Gets the length of the plaintext that the session processed */ size_t ciphertext_len_output; if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session, ciphertext_output, ciphertext_buf_sz_output, &ciphertext_len_output, plaintext_input, plaintext_len_input)) { aws_cryptosdk_session_destroy(session); return 8; } ``` Passo 6: Limpar a sessão. A etapa final destroi a sessão, inclusive as referências ao CMM e ao token de autenticação. Se você preferir, em vez de destruir a sessão, reutilize-a com o mesmo token de autenticação e CMM para descriptografar a string, ou para criptografar ou descriptografar outras mensagens. Para usar a sessão para descriptografia, use o método `aws_cryptosdk_session_reset` para alterar o modo para `AWS_CRYPTOSDK_DECRYPT`. ### Descriptografar uma string A segunda parte deste exemplo descriptografa uma mensagem criptografada que contém o texto cifrado da string original. Etapa 1: carregar sequências de erro. Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração. Você só precisa chamá-lo uma vez, como no método `main`. ``` /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); ``` Etapa 2: estruturar o token de autenticação. Ao descriptografar dados AWS KMS, você passa a [mensagem criptografada](concepts.md#message) que a API de criptografia retornou. A [API Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) não aceita uma AWS KMS key entrada. Em vez disso, AWS KMS usa o mesmo AWS KMS key para descriptografar o texto cifrado usado para criptografá-lo. No entanto, AWS Encryption SDK permite que você especifique um AWS KMS chaveiro sem AWS KMS keys criptografar e descriptografar. Ao descriptografar, você pode configurar um chaveiro apenas com o AWS KMS keys que deseja usar para descriptografar a mensagem criptografada. Por exemplo, talvez você queira criar um chaveiro apenas com o AWS KMS key que é usado por uma função específica em sua organização. Eles nunca AWS Encryption SDK usarão um, AWS KMS key a menos que apareça no chaveiro de decodificação. Se o SDK não conseguir descriptografar as chaves de dados criptografadas usando o AWS KMS keys chaveiro fornecido por você, seja porque nada do chaveiro foi usado para criptografar nenhuma das AWS KMS keys chaves de dados ou porque o chamador não tem permissão para usar o chaveiro para descriptografar, a chamada de descriptografia falhará. AWS KMS keys [Ao especificar um AWS KMS key para um chaveiro de decodificação, você deve usar o ARN da chave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) Os [alias ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) são permitidos somente em chaveiros de criptografia. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte[Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id). Neste exemplo, especificamos um chaveiro configurado com o mesmo AWS KMS key usado para criptografar a string. Antes de executar esse código, substitua o ARN da chave de exemplo por um válido. ``` const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); ``` Etapa 3: Criar uma sessão. Crie uma sessão usando o alocador e o token de autenticação. Para configurar a sessão para descriptografia, configure a sessão com o modo `AWS_CRYPTOSDK_DECRYPT`. Depois de criar uma sessão com um token de autenticação, você poderá liberar sua referência ao token de autenticação usando o método fornecido pelo SDK. A sessão mantém uma referência ao objeto token de autenticação durante sua vida útil, e a sessão e o token de autenticação são liberados quando você destrói a sessão. Essa técnica de contagem de referência ajuda a evitar vazamentos de memória e a evitar que os objetos sejam liberados enquanto estão em uso. ``` struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring); /* When you add the keyring to the session, release the keyring object */ aws_cryptosdk_keyring_release(kms_keyring); ``` Etapa 4: Descriptografar a string. Para descriptografar a string, use o método `aws_cryptosdk_session_process_full` com a sessão configurada para descriptografia. Esse método, introduzido nas versões 1.9.*x* e 2.2.*x* do AWS Encryption SDK , foi projetado para criptografia e descriptografia que não sejam de streaming. Para lidar com dados de streaming, chame o `aws_cryptosdk_session_process` continuamente. Na descriptografia, os campos em texto cifrado são campos de entrada, e os campos em texto simples são campos de saída. O campo `ciphertext_input` contém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia. Quando o processamento for concluído, o campo `plaintext_output` conterá a string em texto simples (descriptografada). ``` size_t plaintext_len_output; if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session, plaintext_output, plaintext_buf_sz_output, &plaintext_len_output, ciphertext_input, ciphertext_len_input)) { aws_cryptosdk_session_destroy(session); return 13; } ``` Etapa 5: Verificar o contexto de criptografia. Verifique se o contexto de criptografia real, o que foi usado para descriptografar a mensagem, contém o contexto de criptografia fornecido ao criptografar a mensagem. O contexto de criptografia real pode incluir pares extras porque o [gerenciador de materiais criptográficos](concepts.md#crypt-materials-manager) (CMM) pode adicionar pares ao contexto de criptografia fornecido antes de criptografar a mensagem. No AWS Encryption SDK for C, você não precisa fornecer um contexto de criptografia ao descriptografar porque o contexto de criptografia está incluído na mensagem criptografada que o SDK retorna. No entanto, antes que a mensagem em texto simples seja retornada, sua função de descriptografia deve verificar se todos os pares no contexto de criptografia fornecido aparecem no contexto que foi usado para descriptografar a mensagem. Primeiro, obtenha um ponteiro somente leitura para a tabela de hash na sessão. Essa tabela de hash contém o contexto de criptografia que foi usado para descriptografar a mensagem. ``` const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session); ``` Depois, percorra o contexto na tabela de hash `my_enc_ctx` que você copiou ao efetuar a criptografia. Verifique se cada par na tabela de hash `my_enc_ctx` que foi usada para efetuar a criptografia aparece na tabela de hash `session_enc_ctx` que foi usada para efetuar a descriptografia. Se alguma chave estiver ausente ou se essa chave tiver um valor diferente, interrompa o processamento e escreva uma mensagem de erro. ``` for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter); aws_hash_iter_next(&iter)) { struct aws_hash_element *session_enc_ctx_kv_pair; aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair) if (!session_enc_ctx_kv_pair || !aws_string_eq( (struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) { fprintf(stderr, "Wrong encryption context!\n"); abort(); } } ``` Passo 6: Limpar a sessão. Depois de verificar o contexto de criptografia, destrua a sessão ou a reutilize. Se precisar reconfigurá-la, use o método `aws_cryptosdk_session_reset`. ``` aws_cryptosdk_session_destroy(session); ``` # AWS Encryption SDK para o.NET O AWS Encryption SDK for .NET é uma biblioteca de criptografia do lado do cliente para desenvolvedores que estão escrevendo aplicativos em C\$1 e em outras linguagens de programação.NET. É compatível com Windows, macOS e Linux. **nota** A versão 4.0.0 do AWS Encryption SDK para.NET se desvia da Especificação da AWS Encryption SDK Mensagem. Como resultado, as mensagens criptografadas pela versão 4.0.0 só podem ser descriptografadas pela versão 4.0.0 ou posterior do para.NET. AWS Encryption SDK Eles não podem ser descriptografados por nenhuma outra implementação de linguagem de programação. A versão 4.0.1 do AWS Encryption SDK para.NET grava mensagens de acordo com a Especificação da AWS Encryption SDK Mensagem e é interoperável com outras implementações de linguagem de programação. Por padrão, a versão 4.0.1 pode ler mensagens criptografadas pela versão 4.0.0. No entanto, se você não quiser descriptografar mensagens criptografadas pela versão 4.0.0, você pode especificar a propriedade [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) para impedir que o cliente leia essas mensagens. Para obter mais informações, consulte as [notas de versão v4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) no aws-encryption-sdk repositório em. GitHub O AWS Encryption SDK for .NET difere de algumas das outras implementações de linguagem de programação do AWS Encryption SDK das seguintes maneiras: + Não há suporte para [armazenamento em cache de chaves de dados](data-key-caching.md) **nota** Versão 4. O *x* of the AWS Encryption SDK for.NET suporta o [AWS KMS chaveiro hierárquico](use-hierarchical-keyring.md), uma solução alternativa de cache de materiais criptográficos. + Não há suporte para streaming de dados + [Não há registros ou rastreamentos de pilha](#dot-net-debugging) do AWS Encryption SDK para .NET + [Requer o AWS SDK para .NET](#dot-net-install) O AWS Encryption SDK para o.NET inclui todos os recursos de segurança introduzidos nas versões 2.0. *x* e posteriores de outras implementações de linguagem do AWS Encryption SDK. No entanto, se você estiver usando o for.NET AWS Encryption SDK para descriptografar dados que foram criptografados por uma versão pré-2.0. versão *x* outra implementação de linguagem do AWS Encryption SDK, talvez seja necessário ajustar sua [política de compromisso](concepts.md#commitment-policy). Para obter detalhes, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md#migrate-commitment-step1). O AWS Encryption SDK for .NET é um produto do AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), uma linguagem de verificação formal na qual você escreve especificações, o código para implementá-las e as provas para testá-las. O resultado é uma biblioteca que implementa os atributos do AWS Encryption SDK em uma estrutura que garante a correção funcional. **Saiba mais** + Para ver exemplos que mostram como configurar opções no AWS Encryption SDK, como especificar um conjunto alternativo de algoritmos, limitar chaves de dados criptografadas e usar chaves AWS KMS multirregionais, consulte. [Configurando o AWS Encryption SDK](configure.md) + Para obter detalhes sobre a programação com o AWS Encryption SDK para.NET, consulte o [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)diretório do aws-encryption-sdk repositório em GitHub. **Topics** + [Instalar e compilar](#dot-net-install) + [Depuração](#dot-net-debugging) + [Exemplos](dot-net-examples.md) ## Instalando o AWS Encryption SDK para o.NET O AWS Encryption SDK para o.NET está disponível como [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)pacote em NuGet. Para obter detalhes sobre como instalar e criar o AWS Encryption SDK para.NET, consulte o arquivo [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) no repositório. `aws-encryption-sdk-net` **Versão 3.x** Versão 3. *x* do AWS Encryption SDK para o.NET oferece suporte a o.NET Framework 4.5.2 — 4.8 somente no Windows. É compatível com o .NET Core 3.0\$1 e o .NET 5.0 e versões posteriores em todos os sistemas operacionais compatíveis. **Versão 4.x** Versão 4. *x* do AWS Encryption SDK para o.NET oferece suporte a o.NET 6.0 e o.NET Framework net48 e versões posteriores. Versão 4. *x* requer o AWS SDK para .NET v3. **Versão 5.x** Versão 5. *x* do AWS Encryption SDK para o.NET oferece suporte a o.NET 6.0 e o.NET Framework net48 e versões posteriores. Versão 5. *x* requer a versão 2. *x* da Material Providers Library (MPL) e do AWS SDK para .NET v4. O AWS Encryption SDK for .NET exige o SDK para .NET mesmo se você não estiver usando as chaves AWS Key Management Service (AWS KMS). Ele é instalado com o NuGet pacote. No entanto, a menos que você esteja usando AWS KMS chaves, AWS Encryption SDK o.NET não exige AWS credenciais ou interação com nenhum AWS serviço. Conta da AWS Para obter ajuda para configurar uma AWS conta, se necessário, consulte[Usando o AWS Encryption SDK com AWS KMS](getting-started.md). ## Depurando o para o.NET AWS Encryption SDK O AWS Encryption SDK for.NET não gera nenhum registro. As exceções no AWS Encryption SDK for.NET geram uma mensagem de exceção, mas nenhum rastreamento de pilha. Para ajudar na depuração, certifique-se de habilitar o login no SDK para .NET. Os registros e mensagens de erro do SDK para .NET podem ajudá-lo a distinguir os erros decorrentes do e os SDK para .NET do para.NET. AWS Encryption SDK Para obter ajuda com o SDK para .NET registro, consulte [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)o *Guia do AWS SDK para .NET desenvolvedor*. (Para ver o tópico, expanda a seção **Abrir para ver o conteúdo do .NET Framework**.) # AWS Encryption SDK para exemplos do.NET Os exemplos a seguir mostram os padrões básicos de codificação que você usa ao programar com o AWS Encryption SDK para o.NET. Especificamente, você instancia a biblioteca AWS Encryption SDK e os fornecedores de materiais. Em seguida, antes de chamar cada método, você deve instanciar um objeto que define a entrada para o método. Isso é muito parecido com o padrão de codificação usado no SDK para .NET. Para ver exemplos que mostram como configurar opções no AWS Encryption SDK, como especificar um conjunto alternativo de algoritmos, limitar chaves de dados criptografadas e usar chaves AWS KMS multirregionais, consulte. [Configurando o AWS Encryption SDK](configure.md) Para obter mais exemplos de programação com o AWS Encryption SDK para.NET, consulte os [exemplos](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) no `aws-encryption-sdk-net` diretório do `aws-encryption-sdk` repositório em GitHub. ## Criptografando dados no AWS Encryption SDK for.NET Este exemplo mostra o padrão básico para criptografar dados. Ele criptografa um pequeno arquivo com chaves de dados protegidas por uma chave de AWS KMS empacotamento. Etapa 1: Instanciar a biblioteca AWS Encryption SDK e a biblioteca dos fornecedores de materiais. Comece instanciando a biblioteca AWS Encryption SDK e a biblioteca dos fornecedores de materiais. Você usará os métodos do AWS Encryption SDK para criptografar e descriptografar dados. Você usará os métodos na biblioteca de fornecedores de materiais para criar os tokens de autenticação que especificam quais chaves protegem seus dados. A forma como você instancia a biblioteca AWS Encryption SDK e a biblioteca de fornecedores de materiais difere entre as versões 3. *x* e 4. *x* do AWS Encryption SDK para o.NET. Todas as etapas a seguir são as mesmas para ambas as versões 3. *x* e 4. *x* do AWS Encryption SDK para o.NET. ``` // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); ``` ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` Etapa 2: crie um objeto de entrada para o token de autenticação. Cada método que cria um token de autenticação tem uma classe de objeto de entrada correspondente. Por exemplo, para criar o objeto de entrada para o método `CreateAwsKmsKeyring()`, crie uma instância da classe `CreateAwsKmsKeyringInput`. Embora a entrada desse token de autenticação não especifique uma [chave geradora](use-kms-keyring.md#kms-keyring-encrypt), a única chave do KMS especificada pelo parâmetro `KmsKeyId` é a chave geradora. Ela gera e criptografa a chave de dados que criptografa os dados. Esse objeto de entrada requer um AWS KMS cliente para Região da AWS a chave KMS. Para criar um AWS KMS cliente, instancie a `AmazonKeyManagementServiceClient` classe no. SDK para .NET Chamar o construtor `AmazonKeyManagementServiceClient()` sem parâmetros cria um cliente com os valores padrão. Em um AWS KMS chaveiro usado para criptografar com o.NET, você pode [identificar as chaves KMS usando o](use-kms-keyring.md#kms-keyring-id) ID da chave, o ARN da chave, o nome do alias ou o ARN do alias. AWS Encryption SDK Em um AWS KMS chaveiro usado para descriptografia, você deve usar um ARN de chave para identificar cada chave KMS. Se você planeja reutilizar seu token de autenticação de criptografia para descriptografar, use um identificador ARN de chave para todas as chaves KMS. ``` string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Instantiate the keyring input object var kmsKeyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; ``` Etapa 3: criar o token de autenticação. Para criar o token de autenticação, chame o método do token de autenticação com o objeto de entrada do token de autenticação. Este exemplo usa o método `CreateAwsKmsKeyring()`, que usa apenas uma chave do KMS. ``` var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput); ``` Etapa 4: defina um contexto de criptografia. Um [contexto de criptografia](concepts.md#encryption-context) é um elemento opcional, mas altamente recomendado, de operações criptográficas no AWS Encryption SDK. Você pode definir um ou mais pares de chave-valor não secretos. Com a versão 4. *No AWS Encryption SDK caso do.NET, você pode exigir um contexto de criptografia em todas as solicitações de criptografia com o [contexto de criptografia necessário CMM](configure.md#config-required-encryption-context-cmm).* ``` // Define the encryption context var encryptionContext = new Dictionary() { {"purpose", "test"} }; ``` Etapa 5: crie o objeto de entrada para a criptografia. Antes de chamar o método `Encrypt()`, crie uma instância da classe `EncryptInput`. ``` string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt"); // Define the encrypt input var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = keyring, EncryptionContext = encryptionContext }; ``` Etapa 6: criptografe o texto sem formatação. Use o `Encrypt()` método do AWS Encryption SDK para criptografar o texto simples usando o chaveiro que você definiu. O `EncryptOutput` que o método `Encrypt() ` retorna tem métodos para obter a mensagem criptografada (`Ciphertext`), o contexto de criptografia e o pacote de algoritmos. ``` var encryptOutput = encryptionSdk.Encrypt(encryptInput); ``` Etapa 7: obtenha a mensagem criptografada. O `Decrypt()` método no AWS Encryption SDK for.NET usa o `Ciphertext` membro da `EncryptOutput` instância. O membro `Ciphertext` do objeto `EncryptOutput` é a [mensagem criptografada](concepts.md#message), um objeto portátil que inclui dados criptografados, chaves de dados criptografadas e metadados, incluindo o contexto de criptografia. É possível armazenar com segurança a mensagem criptografada por um período prolongado ou enviá-la ao método `Decrypt()` para recuperar o texto sem formatação. ``` var encryptedMessage = encryptOutput.Ciphertext; ``` ## Descriptografando em modo estrito no para.NET AWS Encryption SDK As práticas recomendadas indicam que você especifique as chaves usadas para descriptografar dados, uma opção conhecida como *modo estrito.* O AWS Encryption SDK usa somente as chaves KMS que você especifica em seu chaveiro para descriptografar o texto cifrado. As chaves no token de autenticação de descriptografia devem incluir pelo menos uma das chaves que criptografaram os dados. Este exemplo mostra o padrão básico de descriptografia no modo estrito com o AWS Encryption SDK para .NET. Etapa 1: Instanciar a biblioteca AWS Encryption SDK e os fornecedores de materiais. ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` Etapa 2: criar o objeto de entrada para seu token de autenticação. Para especificar os parâmetros do método do token de autenticação, crie um objeto de entrada. Cada método de chaveiro no AWS Encryption SDK for.NET tem um objeto de entrada correspondente. Como esse exemplo usa o método `CreateAwsKmsKeyring()` para criar o token de autenticação, ele instancia a classe `CreateAwsKmsKeyringInput` para a entrada. Em um token de autenticação de descriptografia, você deve usar um ARN de chave para identificar chaves do KMS. ``` string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Instantiate the keyring input object var kmsKeyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; ``` Etapa 3: criar o token de autenticação. Para criar o token de autenticação da descriptografia, este exemplo usa o método `CreateAwsKmsKeyring()` e o objeto de entrada do token de autenticação. ``` var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput); ``` Etapa 4: crie o objeto de entrada para descriptografar. Para criar o objeto de entrada para o método `Decrypt()`, instancie a classe `DecryptInput`. O parâmetro `Ciphertext` do construtor `DecryptInput()` usa o membro `Ciphertext` do objeto `EncryptOutput` que o método `Encrypt()` retornou. A propriedade `Ciphertext` representa a [mensagem criptografada](concepts.md#message), que inclui os dados criptografados, as chaves de dados criptografadas e os metadados que o AWS Encryption SDK necessita para descriptografar a mensagem. Com a versão 4. *No AWS Encryption SDK caso do.NET, você pode usar o `EncryptionContext` parâmetro opcional para especificar seu contexto de criptografia no `Decrypt()` método.* Use o parâmetro `EncryptionContext` para verificar se o contexto de criptografia usado na criptografia *está incluído* no contexto de criptografia usado para descriptografar o texto cifrado. AWS Encryption SDK Isso adiciona pares ao contexto de criptografia, incluindo a assinatura digital, se você estiver usando um conjunto de algoritmos com assinatura, como o conjunto de algoritmos padrão. ``` var encryptedMessage = encryptOutput.Ciphertext; var decryptInput = new DecryptInput { Ciphertext = encryptedMessage, Keyring = keyring, EncryptionContext = encryptionContext // OPTIONAL }; ``` Etapa 5: descriptografe o texto cifrado. ``` var decryptOutput = encryptionSdk.Decrypt(decryptInput); ``` Etapa 6: verifique o contexto de criptografia – versão 3.*x* O `Decrypt()` método da versão 3. *x* do AWS Encryption SDK for.NET não usa um contexto de criptografia. Ele obtém os valores do contexto de criptografia dos metadados na mensagem criptografada. No entanto, antes de retornar ou usar o texto simples, é recomendável verificar se o contexto de criptografia usado para descriptografar o texto cifrado inclui o contexto de criptografia que você forneceu ao criptografar. Verifique se o contexto de criptografia usado na criptografia *está incluído* no contexto de criptografia usado para descriptografar o texto cifrado. AWS Encryption SDK Isso adiciona pares ao contexto de criptografia, incluindo a assinatura digital, se você estiver usando um conjunto de algoritmos com assinatura, como o conjunto de algoritmos padrão. ``` // Verify the encryption context string contextKey = "purpose"; string contextValue = "test"; if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue) || !decryptContextValue.Equals(contextValue)) { throw new Exception("Encryption context does not match expected values"); } ``` ## Descriptografando com um chaveiro de descoberta no for.NET AWS Encryption SDK Em vez de especificar as chaves KMS para a descriptografia, você pode fornecer um *token de autenticação de descoberta do AWS KMS *, que é um token de autenticação que não especifica nenhuma chave KMS. Um chaveiro de descoberta permite AWS Encryption SDK descriptografar os dados usando qualquer chave KMS criptografada, desde que o chamador tenha permissão de descriptografia na chave. Para obter as melhores práticas, adicione um filtro de descoberta que limita as chaves KMS que podem ser usadas para aquelas específicas Contas da AWS de uma partição especificada. O AWS Encryption SDK for.NET fornece um chaveiro de descoberta básico que requer um AWS KMS cliente e um chaveiro de descoberta múltiplo que exige que você especifique um ou mais. Regiões da AWS Tanto o cliente quanto as regiões limitam as chaves do KMS que podem ser usadas para descriptografar a mensagem criptografada. Os objetos de entrada dos dois tokens de autenticação usam o filtro de descoberta recomendado. O exemplo a seguir mostra o padrão para descriptografar dados com um token de autenticação de descoberta do AWS KMS e um filtro de descoberta. Etapa 1: Instanciar a biblioteca AWS Encryption SDK e a biblioteca dos fornecedores de materiais. ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` Etapa 2: criar o objeto de entrada para o token de autenticação. Para especificar os parâmetros do método do token de autenticação, crie um objeto de entrada. Cada método de chaveiro no AWS Encryption SDK for.NET tem um objeto de entrada correspondente. Como esse exemplo usa o método `CreateAwsKmsDiscoveryKeyring()` para criar o token de autenticação, ele instancia a classe `CreateAwsKmsDiscoveryKeyringInput` para a entrada. ``` List accounts = new List { "111122223333" }; var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), DiscoveryFilter = new DiscoveryFilter() { AccountIds = accounts, Partition = "aws" } }; ``` Etapa 3: criar o token de autenticação. Para criar o token de autenticação da descriptografia, este exemplo usa o método `CreateAwsKmsDiscoveryKeyring()` e o objeto de entrada do token de autenticação. ``` var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput); ``` Etapa 4: crie o objeto de entrada para descriptografar. Para criar o objeto de entrada para o método `Decrypt()`, instancie a classe `DecryptInput`. O valor do parâmetro `Ciphertext` é o membro `Ciphertext` do objeto `EncryptOutput` que o método `Encrypt()` retorna. Com a versão 4. *No AWS Encryption SDK caso do.NET, você pode usar o `EncryptionContext` parâmetro opcional para especificar seu contexto de criptografia no `Decrypt()` método.* Use o parâmetro `EncryptionContext` para verificar se o contexto de criptografia usado na criptografia *está incluído* no contexto de criptografia usado para descriptografar o texto cifrado. AWS Encryption SDK Isso adiciona pares ao contexto de criptografia, incluindo a assinatura digital, se você estiver usando um conjunto de algoritmos com assinatura, como o conjunto de algoritmos padrão. ``` var ciphertext = encryptOutput.Ciphertext; var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = discoveryKeyring, EncryptionContext = encryptionContext // OPTIONAL }; var decryptOutput = encryptionSdk.Decrypt(decryptInput); ``` Etapa 5: verificar o contexto de criptografia - versão 3.*x* O `Decrypt()` método da versão 3. *x* do AWS Encryption SDK for.NET não usa um contexto de criptografia`Decrypt()`. Ele obtém os valores do contexto de criptografia dos metadados na mensagem criptografada. No entanto, antes de retornar ou usar o texto simples, é recomendável verificar se o contexto de criptografia usado para descriptografar o texto cifrado inclui o contexto de criptografia que você forneceu ao criptografar. Verifique se o contexto de criptografia usado na criptografia *foi incluído* no contexto de criptografia usado para descriptografar o texto cifrado. AWS Encryption SDK Isso adiciona pares ao contexto de criptografia, incluindo a assinatura digital, se você estiver usando um conjunto de algoritmos com assinatura, como o conjunto de algoritmos padrão. ``` // Verify the encryption context string contextKey = "purpose"; string contextValue = "test"; if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue) || !decryptContextValue.Equals(contextValue)) { throw new Exception("Encryption context does not match expected values"); } ``` # AWS Encryption SDK para Go Este tópico explica como instalar e usar o AWS Encryption SDK for Go. Para obter detalhes sobre a programação com o AWS Encryption SDK for Go, consulte o diretório [go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/) do aws-encryption-sdk repositório on GitHub. O AWS Encryption SDK for Go difere de algumas das outras implementações de linguagem de programação do AWS Encryption SDK das seguintes maneiras: + Não há suporte para armazenamento em [cache de chaves de dados](data-key-caching.md). No entanto, o AWS Encryption SDK for Go suporta o [AWS KMS chaveiro hierárquico](use-hierarchical-keyring.md), uma solução alternativa de cache de materiais criptográficos. + Não há suporte para streaming de dados O AWS Encryption SDK for Go inclui todos os recursos de segurança introduzidos nas versões 2.0. *x* e posteriores de outras implementações de linguagem do AWS Encryption SDK. No entanto, se você estiver usando o for Go AWS Encryption SDK para descriptografar dados que foram criptografados por uma versão pré-2.0. versão *x* outra implementação de linguagem do AWS Encryption SDK, talvez seja necessário ajustar sua [política de compromisso](concepts.md#commitment-policy). Para obter detalhes, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md#migrate-commitment-step1). O AWS Encryption SDK for Go é um produto do AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), uma linguagem de verificação formal na qual você escreve especificações, o código para implementá-las e as provas para testá-las. O resultado é uma biblioteca que implementa os atributos do AWS Encryption SDK em uma estrutura que garante a correção funcional. **Saiba mais** + Para ver exemplos que mostram como configurar opções no AWS Encryption SDK, como especificar um conjunto alternativo de algoritmos, limitar chaves de dados criptografadas e usar chaves AWS KMS multirregionais, consulte. [Configurando o AWS Encryption SDK](configure.md) + Para ver exemplos de como configurar e usar o AWS Encryption SDK for Go, consulte os [exemplos de Go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/examples) no aws-encryption-sdk repositório em GitHub. **Topics** + [ ## Pré-requisitos ](#prerequisites-go) + [ ## Instalação ](#go-installation) ## Pré-requisitos Antes de instalar o AWS Encryption SDK for Go, verifique se você tem os seguintes pré-requisitos. **Uma versão compatível do Go** O Go 1.23 ou posterior é exigido pelo AWS Encryption SDK for Go. Para obter mais informações sobre como baixar e instalar o Go, consulte [Instalação do Go](https://go.dev/doc/install). ## Instalação Instale a versão mais recente do AWS Encryption SDK for Go. Para obter detalhes sobre como instalar e criar o AWS Encryption SDK for Go, consulte o [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/README.md) no diretório go do repositório em. aws-encryption-sdk GitHub **Para instalar a versão mais recente** + Instale o AWS Encryption SDK for Go ``` go get github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk@latest ``` + Instale a [Biblioteca de Provedores de Material Criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) ``` go get github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl ``` # AWS Encryption SDK for Java Este tópico explica como instalar e usar o AWS Encryption SDK for Java. Para obter detalhes sobre a programação com o AWS Encryption SDK for Java, consulte o [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)repositório em GitHub. Para obter a documentação da API, consulte o [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) para AWS Encryption SDK for Java. **Topics** + [ ## Pré-requisitos ](#java-prerequisites) + [ ## Instalação ](#java-installation) + [Exemplos](java-example-code.md) ## Pré-requisitos Antes de instalar o AWS Encryption SDK for Java, verifique se você tem os seguintes pré-requisitos. **Um ambiente de desenvolvimento Java** Você precisará do Java 8 ou posterior. No site da Oracle, acesse [Java SE Downloads](https://www.oracle.com/java/technologies/downloads/) e faça download e instale o Java SE Development Kit (JDK). Se você usa o Oracle JDK, também precisara fazer download e instalar os [arquivos de política de jurisdição de força ilimitada JCE (Java Cryptography Extension)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html). **Bouncy Castle** AWS Encryption SDK for Java Isso requer o [Bouncy Castle.](https://www.bouncycastle.org/download/bouncy-castle-java/) + AWS Encryption SDK for Java as versões 1.6.1 e posteriores usam o Bouncy Castle para serializar e desserializar objetos criptográficos. Você pode usar o Bouncy Castle ou o [Bouncy Castle FIPS](https://www.bouncycastle.org/about/bouncy-castle-fips-faq/) para atender a esse requisito. **Para obter ajuda na instalação e configuração do Bouncy Castle FIPS, consulte a [documentação do BC FIPS](https://www.bouncycastle.org/documentation/), especialmente os Guias **do Usuário** e a Política de Segurança.** PDFs + As versões anteriores do AWS Encryption SDK for Java usam a API de criptografia do Bouncy Castle para Java. Este requisito só é atendido por não FIPS Bouncy Castle. Se você não tiver o Bouncy Castle, acesse [Baixar Bouncy Castle for Java para](https://bouncycastle.org/download/bouncy-castle-java/) baixar o arquivo do provedor que corresponde ao seu JDK. [Você também pode usar o [Apache Maven](https://maven.apache.org/) para obter o artefato para o provedor padrão do Bouncy Castle ([bcprov-ext-jdk15on](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk15on)) ou o artefato para o Bouncy Castle FIPS (bc-fips).](https://mvnrepository.com/artifact/org.bouncycastle/bc-fips) **AWS SDK para Java** Versão 3. *x* of the AWS Encryption SDK for Java requer o AWS SDK for Java 2.x, mesmo se você não usar AWS KMS chaveiros. Versão 2. *x* ou anterior do AWS Encryption SDK for Java não requer AWS SDK para Java o. No entanto, AWS SDK para Java é necessário usar [AWS Key Management Service](https://aws.amazon.com/kms/)(AWS KMS) como provedor de chave mestra. A partir da AWS Encryption SDK for Java versão 2.4.0, o AWS Encryption SDK for Java suporta as versões 1.x e 2.x do. AWS SDK para Java AWS Encryption SDK os códigos para AWS SDK para Java 1.x e 2.x são interoperáveis. Por exemplo, você pode criptografar dados com AWS Encryption SDK código compatível com AWS SDK para Java 1.x e descriptografá-los usando código compatível AWS SDK for Java 2.x (ou vice-versa). As versões AWS Encryption SDK for Java anteriores à 2.4.0 suportam apenas AWS SDK para Java 1.x. Para obter informações sobre como atualizar sua versão do AWS Encryption SDK, consulte[Migrando seu AWS Encryption SDK](migration.md). Ao atualizar seu AWS Encryption SDK for Java código de AWS SDK para Java 1.x para AWS SDK for Java 2.x, substitua as referências à [`AWSKMS`interface](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/kms/package-summary.html) em AWS SDK para Java 1.x por referências à [`KmsClient`interface](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/package-summary.html) em. AWS SDK for Java 2.x O AWS Encryption SDK for Java não suporta a [`KmsAsyncClient`interface](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/KmsAsyncClient.html). Além disso, atualize seu código para usar os objetos relacionados ao AWS KMS no namespace `kmssdkv2`, em vez do namespace `kms`. Para instalar o AWS SDK para Java, use o Apache Maven. + Para [importar todo o AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) como uma dependência, declare-o no arquivo `pom.xml`. + Para criar uma dependência somente para o AWS KMS módulo na AWS SDK para Java versão 1.x, siga as instruções para [especificar módulos específicos](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html#modules-dependencies) e defina o. `artifactId` `aws-java-sdk-kms` + Para criar uma dependência somente para o AWS KMS módulo na AWS SDK para Java versão 2.x, siga as instruções para [especificar](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies) módulos específicos. Defina o `groupId` como `software.amazon.awssdk` e `artifactId` como `kms`. Para ver mais mudanças, consulte [O que há de diferente entre a AWS SDK para Java versão 1.x e a 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-whats-different.html) no Guia do AWS SDK for Java 2.x desenvolvedor. Os exemplos de Java no Guia do AWS Encryption SDK Desenvolvedor usam AWS SDK for Java 2.x o. ## Instalação Instalar a versão mais recente do AWS Encryption SDK for Java. **nota** Todas as versões AWS Encryption SDK for Java anteriores à 2.0.0 estão em [end-of-supportfase](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.0.*x* e posteriores até a versão mais recente do AWS Encryption SDK for Java 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.0.*x* não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.*x* até a versão 2.0. *x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente do AWS Encryption SDK. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). Você pode instalar o AWS Encryption SDK for Java das seguintes maneiras. **Manualmente** Para instalar o AWS Encryption SDK for Java, clone ou baixe o [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) GitHubrepositório. **Uso do Apache Maven** O AWS Encryption SDK for Java está disponível por meio do [Apache Maven](https://maven.apache.org/) com a seguinte definição de dependência. ``` com.amazonaws aws-encryption-sdk-java 3.0.0 ``` Depois de instalar o SDK, comece examinando o [exemplo de código Java](java-example-code.md) neste guia e o [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) ativado. GitHub # AWS Encryption SDK for Java exemplos Os exemplos a seguir mostram como usar o para AWS Encryption SDK for Java criptografar e descriptografar dados. Esses exemplos mostram como usar a versão 3. *x* e posterior do AWS Encryption SDK for Java. Versão 3. *x* do AWS Encryption SDK for Java requer AWS SDK for Java 2.x o. Versão 3. *x* do AWS Encryption SDK for Java substitui os [fornecedores de chaves mestras](concepts.md#master-key-provider) por [chaveiros](concepts.md#keyring). Para exemplos que usam versões anteriores, encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-java/releases) do [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)repositório em GitHub. **Topics** + [Strings](#java-example-strings) + [streams de bytes](#java-example-streams) + [Fluxos de bytes com vários provedores de chaves mestres](#java-example-multiple-providers) ## Criptografar e descriptografar strings O exemplo a seguir mostra como usar a versão 3. *x* do AWS Encryption SDK for Java para criptografar e descriptografar strings. Antes de usar a string, converta-a em uma matriz de bytes. Este exemplo usa um [AWS KMS chaveiro.](use-kms-keyring.md) Ao criptografar com um AWS KMS chaveiro, você pode usar um ID de chave, ARN de chave, nome de alias ou ARN de alias para identificar as chaves KMS. Ao descriptografar, você deve usar um ARN de chave para identificar as chaves KMS. Quando você chama o método `encryptData()`, ele retorna uma [mensagem criptografada](concepts.md#message) (`CryptoResult`) que inclui o texto cifrado, as chaves de dados criptografadas e o contexto de criptografia. Quando você chama `getResult` no objeto `CryptoResult`, ele retorna uma versão de cadeia codificada em base 64 da [mensagem criptografada](message-format.md) que você pode passar para o método `decryptData()`. Da mesma forma, quando você chama`decryptData()`, o `CryptoResult` objeto que ele retorna contém a mensagem de texto sem formatação e um AWS KMS key ID. Antes que seu aplicativo retorne o texto sem formatação, verifique se o AWS KMS key ID e o contexto de criptografia na mensagem criptografada são os que você espera. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoResult; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import java.nio.charset.StandardCharsets; import java.util.Arrays; import java.util.Collections; import java.util.Map; /** * Encrypts and then decrypts data using an AWS KMS Keyring. * *

Arguments: * *

    *
  1. Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master * key (CMK), see 'Viewing Keys' at * http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html *
*/ public class BasicEncryptionKeyringExample { private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8); public static void main(final String[] args) { final String keyArn = args[0]; encryptAndDecryptWithKeyring(keyArn); } public static void encryptAndDecryptWithKeyring(final String keyArn) { // 1. Instantiate the SDK // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders materialProviders = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build(); final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create an encryption context // We recommend using an encryption context whenever possible // to protect integrity. This sample uses placeholder values. // For more information see: // blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management final Map encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue"); // 4. Encrypt the data final CryptoResult encryptResult = crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext); final byte[] ciphertext = encryptResult.getResult(); // 5. Decrypt the data final CryptoResult decryptResult = crypto.decryptData( kmsKeyring, ciphertext, // Verify that the encryption context in the result contains the // encryption context supplied to the encryptData method encryptionContext); // 6. Verify that the decrypted plaintext matches the original plaintext assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA); } } ``` ## Criptografar e descriptografar streams de bytes O exemplo a seguir mostra como usar o para AWS Encryption SDK criptografar e descriptografar fluxos de bytes. Este exemplo usa um [chaveiro AES bruto](use-raw-aes-keyring.md). Ao criptografar, o método `AwsCrypto.builder() .withEncryptionAlgorithm()` é usado para especificar um conjunto de algoritmos sem [assinaturas digitais](concepts.md#digital-sigs). Ao descriptografar, para garantir que o texto cifrado não esteja assinado, este exemplo usa o método `createUnsignedMessageDecryptingStream()`. O `createUnsignedMessageDecryptingStream()` método falhará se encontrar um texto cifrado com uma assinatura digital. Se você estiver criptografando com o conjunto de algoritmos padrão, que inclui assinaturas digitais, use o método `createDecryptingStream()` em seu lugar, conforme mostrado no próximo exemplo. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoAlgorithm; import com.amazonaws.encryptionsdk.CryptoInputStream; import com.amazonaws.encryptionsdk.jce.JceMasterKey; import com.amazonaws.util.IOUtils; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.AesWrappingAlg; import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.IOException; import java.nio.ByteBuffer; import java.security.SecureRandom; import java.util.Collections; import java.util.Map; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; /** *

* Encrypts and then decrypts a file under a random key. * *

* Arguments: *

    *
  1. Name of file containing plaintext data to encrypt *
* *

* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to * encrypt and decrypt streaming data. */ public class FileStreamingKeyringExample { private static String srcFile; public static void main(String[] args) throws IOException { srcFile = args[0]; // In this example, we generate a random key. In practice, // you would get a key from an existing store SecretKey cryptoKey = retrieveEncryptionKey(); // Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm final MaterialProviders materialProviders = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder() .wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded())) .keyNamespace("Example") .keyName("RandomKey") .wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16) .build(); IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput); // Instantiate the SDK. // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. // This example encrypts with an algorithm suite that doesn't include signing for faster decryption, // since this use case assumes that the contexts that encrypt and decrypt are equally trusted. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) .build(); // Create an encryption context to identify the ciphertext Map context = Collections.singletonMap("Example", "FileStreaming"); // Because the file might be too large to load into memory, we stream the data, instead of //loading it all at once. FileInputStream in = new FileInputStream(srcFile); CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context); FileOutputStream out = new FileOutputStream(srcFile + ".encrypted"); IOUtils.copy(encryptingStream, out); encryptingStream.close(); out.close(); // Decrypt the file. Verify the encryption context before returning the plaintext. // Since the data was encrypted using an unsigned algorithm suite, use the recommended // createUnsignedMessageDecryptingStream method, which only accepts unsigned messages. in = new FileInputStream(srcFile + ".encrypted"); CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in); // Does it contain the expected encryption context? if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) { throw new IllegalStateException("Bad encryption context"); } // Write the plaintext data to disk. out = new FileOutputStream(srcFile + ".decrypted"); IOUtils.copy(decryptingStream, out); decryptingStream.close(); out.close(); } /** * In practice, this key would be saved in a secure location. * For this demo, we generate a new random key for each operation. */ private static SecretKey retrieveEncryptionKey() { SecureRandom rnd = new SecureRandom(); byte[] rawKey = new byte[16]; // 128 bits rnd.nextBytes(rawKey); return new SecretKeySpec(rawKey, "AES"); } } ``` ## Criptografando e descriptografando fluxos de bytes com um chaveiro múltiplo O exemplo a seguir mostra como usar o AWS Encryption SDK com um [chaveiro múltiplo](use-multi-keyring.md). Quando você usa um multitoken de autenticação para criptografar dados, qualquer uma das chaves de empacotamento em qualquer um de seus tokens de autenticação pode descriptografar esses dados. Este exemplo usa um [AWS KMS chaveiro e um chaveiro](use-kms-keyring.md) [RSA bruto como chaveiros](use-raw-rsa-keyring.md) secundários. Este exemplo criptografa com o [pacote de algoritmos padrão](supported-algorithms.md), que inclui uma [assinatura digital](concepts.md#digital-sigs). Durante o streaming, ele AWS Encryption SDK libera texto sem formatação após as verificações de integridade, mas antes de verificar a assinatura digital. Para evitar o uso do texto simples até que a assinatura seja verificada, este exemplo armazena o texto simples em buffer e o grava no disco somente após a conclusão da descriptografia e da verificação. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoOutputStream; import com.amazonaws.util.IOUtils; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import software.amazon.cryptography.materialproviders.model.PaddingScheme; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.FileInputStream; import java.io.FileOutputStream; import java.nio.ByteBuffer; import java.security.GeneralSecurityException; import java.security.KeyPair; import java.security.KeyPairGenerator; import java.util.Collections; /** *

* Encrypts a file using both AWS KMS Key and an asymmetric key pair. * *

* Arguments: *

    *
  1. Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key, * see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html * *
  2. Name of file containing plaintext data to encrypt *
*

* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but * still want the option of decrypting your data offline independently of AWS KMS. This sample * demonstrates one way to do this. *

* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair * so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However, * at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS. *

* This sample uses the RawRsaKeyring to generate a RSA public-private key pair * and saves the key pair in memory. In practice, you would store the private key in a secure offline * location, such as an offline HSM, and distribute the public key to your development team. */ public class EscrowedEncryptKeyringExample { private static ByteBuffer publicEscrowKey; private static ByteBuffer privateEscrowKey; public static void main(final String[] args) throws Exception { // This sample generates a new random key for each operation. // In practice, you would distribute the public key and save the private key in secure // storage. generateEscrowKeyPair(); final String kmsArn = args[0]; final String fileName = args[1]; standardEncrypt(kmsArn, fileName); standardDecrypt(kmsArn, fileName); escrowDecrypt(fileName); } private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception { // Encrypt with the KMS key and the escrowed public key // 1. Instantiate the SDK // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder() .generator(kmsArn) .build(); IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create the Raw Rsa Keyring with Public Key. final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .build(); IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 4. Create the multi-keyring. final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder() .generator(kmsKeyring) .childKeyrings(Collections.singletonList(rsaPublicKeyring)) .build(); IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput); // 5. Encrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName); final FileOutputStream out = new FileOutputStream(fileName + ".encrypted"); final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out); IOUtils.copy(in, encryptingStream); in.close(); encryptingStream.close(); } private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception { // Decrypt with the AWS KMS key and the escrow public key. // 1. Instantiate the SDK. // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder() .generator(kmsArn) .build(); IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create the Raw Rsa Keyring with Public Key. final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .build(); IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 4. Create the multi-keyring. final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder() .generator(kmsKeyring) .childKeyrings(Collections.singletonList(rsaPublicKeyring)) .build(); IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput); // 5. Decrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".decrypted"); // Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file, // to ensure that the trailing signature is verified before writing any untrusted plaintext to disk. final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream(); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray()); IOUtils.copy(plaintextReader, out); out.close(); } private static void escrowDecrypt(final String fileName) throws Exception { // You can decrypt the stream using only the private key. // This method does not call AWS KMS. // 1. Instantiate the SDK final AwsCrypto crypto = AwsCrypto.standard(); // 2. Create the Raw Rsa Keyring with Private Key. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .privateKey(privateEscrowKey) .build(); IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 3. Decrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed"); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); } private static void generateEscrowKeyPair() throws GeneralSecurityException { final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA"); kg.initialize(4096); // Escrow keys should be very strong final KeyPair keyPair = kg.generateKeyPair(); publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic()); privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate()); } } ``` # AWS Encryption SDK para JavaScript O foi AWS Encryption SDK para JavaScript projetado para fornecer uma biblioteca de criptografia do lado do cliente para desenvolvedores que estão escrevendo aplicativos de navegador da Web JavaScript ou aplicativos de servidor Web em Node.js. Como todas as implementações do AWS Encryption SDK, o AWS Encryption SDK para JavaScript oferece recursos avançados de proteção de dados. Os recursos incluem [criptografia de envelope](concepts.md#envelope-encryption), AAD (additional authenticated data - dados autenticados adicionais) e [pacotes de algoritmos](concepts.md#crypto-algorithm) de chave simétrica segura e autenticada, como o AES-GCM de 256 bits com derivação de chave e assinatura. Todas as implementações específicas do AWS Encryption SDK idioma foram projetadas para serem interoperáveis, sujeitas às restrições da linguagem. Para obter detalhes sobre as restrições de linguagem para JavaScript, consulte. [Compatibilidade do AWS Encryption SDK para JavaScript](javascript-compatibility.md) **Saiba mais** + Para obter detalhes sobre a programação com o AWS Encryption SDK para JavaScript, consulte o [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositório em GitHub. + Para exemplos de programação, consulte os [AWS Encryption SDK para JavaScript exemplos](js-examples.md) módulos [example-browser e [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node)](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) no repositório. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) + Para ver um exemplo real do uso do AWS Encryption SDK para JavaScript para criptografar dados em um aplicativo da Web, consulte [Como habilitar a criptografia em um navegador com o AWS Encryption SDK para JavaScript e o Node.js](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/) no blog de segurança. AWS **Topics** + [Compatibilidade](javascript-compatibility.md) + [Instalação](javascript-installation.md) + [Módulos](javascript-modules.md) + [Exemplos](js-examples.md) # Compatibilidade do AWS Encryption SDK para JavaScript O foi AWS Encryption SDK para JavaScript projetado para ser interoperável com outras implementações de linguagem do. AWS Encryption SDK[Na maioria dos casos, você pode criptografar dados com o AWS Encryption SDK para JavaScript e descriptografá-los com qualquer outra implementação de linguagem, incluindo a AWS Encryption SDK interface de linha de comando.](crypto-cli.md) E você pode usar o AWS Encryption SDK para JavaScript para descriptografar [mensagens criptografadas](concepts.md#message) produzidas por outras implementações de linguagem do. AWS Encryption SDK No entanto, ao usar o AWS Encryption SDK para JavaScript, você precisa estar ciente de alguns problemas de compatibilidade na implementação da JavaScript linguagem e nos navegadores da Web. Além disso, ao usar implementações de linguagem diferentes, configure provedores de chaves mestras, chaves mestras e tokens de autenticação compatíveis. Para obter detalhes, consulte [Compatibilidade dos tokens de autenticação](choose-keyring.md#keyring-compatibility). ## AWS Encryption SDK para JavaScript compatibilidade A JavaScript implementação do AWS Encryption SDK difere das implementações de outras linguagens das seguintes maneiras: + A operação de criptografia do AWS Encryption SDK para JavaScript não retorna texto cifrado sem moldura. No entanto, o AWS Encryption SDK para JavaScript decifrará o texto cifrado emoldurado e não emoldurado retornado por outras implementações de linguagem do. AWS Encryption SDK + Começando com o Node.js versão 12.9.0, o Node.js é compatível com as seguintes opções de empacotamento de chave RSA: + OAEP com SHA1, SHA256, ou SHA384 SHA512 + OAEP com e com SHA1 MGF1 SHA1 + PKCS1v15 + Antes da versão 12.9.0, o Node.js era compatível apenas com as seguintes opções de empacotamento de chave RSA: + OAEP com e com SHA1 MGF1 SHA1 + PKCS1v15 ## Compatibilidade do navegador Alguns navegadores da Web não são compatíveis com operações de criptografia básicas exigidas pelo AWS Encryption SDK para JavaScript . Você pode compensar algumas das operações ausentes configurando um substituto para a WebCrypto API que o navegador implementa. **Limitações de navegador da Web** As seguintes limitações são comuns a todos os navegadores da Web: + A WebCrypto API não oferece suporte ao encapsulamento de PKCS1v15 chaves. + Os navegadores não são compatíveis com chaves de 192 bits. **Operações de criptografia necessárias** AWS Encryption SDK para JavaScript Isso requer as seguintes operações em navegadores da web. Se um navegador não for compatível com estas operações, ele será incompatível com o AWS Encryption SDK para JavaScript. + O navegador deve incluir `crypto.getRandomValues()`, que é um método para gerar valores de criptografia aleatórios. Para obter informações sobre as versões do navegador da Web compatíveis`crypto.getRandomValues()`, consulte [Posso usar criptografia. getRandomValues()?](https://caniuse.com/#feat=getrandomvalues) . **Fallback necessário** O AWS Encryption SDK para JavaScript requer as seguintes bibliotecas e operações em navegadores da web. Se você oferecer suporte a um navegador da Web que não atenda a esses requisitos, deverá configurar um fallback. Caso contrário, as tentativas de usar o AWS Encryption SDK para JavaScript com o navegador falharão. + A WebCrypto API, que executa operações criptográficas básicas em aplicativos da web, não está disponível para todos os navegadores. Para obter informações sobre as versões do navegador da Web compatíveis com a criptografia da Web, consulte [Posso usar criptografia da Web?](https://caniuse.com/#feat=cryptography). + As versões modernas do navegador Safari não oferecem suporte à criptografia AES-GCM de zero bytes, o que é necessário. AWS Encryption SDK Se o navegador implementa a WebCrypto API, mas não consegue usar o AES-GCM para criptografar zero bytes, ele AWS Encryption SDK para JavaScript usa a biblioteca de fallback somente para criptografia de zero bytes. Ele usa a WebCrypto API para todas as outras operações. Para configurar um fallback para qualquer limitação, adicione as seguintes instruções ao seu código. Na função [configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78) especifique uma biblioteca que seja compatível com os recursos ausentes. O exemplo a seguir usa a Microsoft Research JavaScript Cryptography Library (`msrcrypto`), mas você pode substituí-la por uma biblioteca compatível. Para obter um exemplo completo, consulte [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts). ``` import { configureFallback } from '@aws-crypto/client-browser' configureFallback(msrCrypto) ``` # Instalando o AWS Encryption SDK para JavaScript O AWS Encryption SDK para JavaScript consiste em uma coleção de módulos interdependentes. Vários dos módulos são apenas coleções de módulos projetados para funcionar em conjunto. Alguns módulos são projetados para funcionar de forma independente. Alguns módulos são necessários para todas as implementações; alguns outros são necessários apenas para casos especiais. Para obter informações sobre os módulos no AWS Encryption SDK formulário JavaScript, consulte [Módulos no AWS Encryption SDK para JavaScript](javascript-modules.md) e o `README.md` arquivo em cada um dos módulos no [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules)repositório em GitHub. **nota** Todas as versões AWS Encryption SDK para JavaScript anteriores à 2.0.0 estão em [end-of-supportfase](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.0.*x* e posteriores até a versão mais recente do AWS Encryption SDK para JavaScript 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.0.*x* não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.*x* até a versão 2.0. *x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente do AWS Encryption SDK para JavaScript. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). Para instalar os módulos, use o [gerenciador de pacotes npm](https://www.npmjs.com/get-npm). Por exemplo, para instalar o `client-node` módulo, que inclui todos os módulos que você precisa programar com o AWS Encryption SDK para JavaScript no Node.js, use o comando a seguir. ``` npm install @aws-crypto/client-node ``` Para instalar o `client-browser` módulo, que inclui todos os módulos que você precisa programar com o AWS Encryption SDK para JavaScript no navegador, use o comando a seguir. ``` npm install @aws-crypto/client-browser ``` Para exemplos práticos de como usar o AWS Encryption SDK para JavaScript, consulte os exemplos nos `example-browser` módulos `example-node` e no [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositório em GitHub. # Módulos no AWS Encryption SDK para JavaScript Os módulos do AWS Encryption SDK para JavaScript facilitam a instalação do código necessário para seus projetos. ## Módulos para JavaScript Node.js [nó do cliente](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node) Inclui todos os módulos que você precisa programar com o AWS Encryption SDK para JavaScript em Node.js. [caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node) Exporta funções que oferecem suporte ao recurso de [cache de chaves de dados](data-key-caching.md) AWS Encryption SDK para JavaScript no Node.js. [decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node) Exporta funções que descriptografam e verificam mensagens criptografadas que representam dados e streams de dados. Incluído no módulo `client-node`. [encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node) Exporta funções que criptografam e assinam diferentes tipos de dados. Incluído no módulo `client-node`. [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) Exporta exemplos funcionais de programação com o AWS Encryption SDK para JavaScript em Node.js. Inclui exemplos de diferentes tipos de tokens de autenticação e diferentes tipos de dados. [hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node) Exporta uma [função de derivação de chave (HKDF) baseada em HMAC](https://en.wikipedia.org/wiki/HKDF) que o Node.js usa AWS Encryption SDK para JavaScript em conjuntos de algoritmos específicos. O AWS Encryption SDK para JavaScript no navegador usa a função HKDF nativa na WebCrypto API. [integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node) Define testes que verificam se o AWS Encryption SDK para JavaScript em Node.js é compatível com outras implementações de linguagem do AWS Encryption SDK. [kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node) Exporta funções que oferecem suporte a AWS KMS chaveiros no Node.js. [raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node) Exporta funções que são compatíveis com [tokens de autenticação brutos do AES](use-raw-aes-keyring.md) no Node.js. [raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node) Exporta funções compatíveis com [tokens de autenticação brutos do RSA ](use-raw-rsa-keyring.md) em Node.js. ## Módulos para JavaScript navegador [client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser) Inclui todos os módulos que você precisa programar com o AWS Encryption SDK para JavaScript no navegador. [caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser) Exporta funções que oferecem suporte ao recurso de [cache de chave de dados](data-key-caching.md) para JavaScript o navegador. [decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser) Exporta funções que descriptografam e verificam mensagens criptografadas que representam dados e streams de dados. [encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser) Exporta funções que criptografam e assinam diferentes tipos de dados. [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) Exemplos práticos de programação com o AWS Encryption SDK para JavaScript no navegador. Inclui exemplos de diferentes tipos de tokens de autenticação e diferentes tipos de dados. [integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser) Define testes que verificam se o AWS Encryption SDK for Java script no navegador é compatível com outras implementações de linguagem do AWS Encryption SDK. [kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser) Exporta funções compatíveis com [tokens de autenticação do AWS KMS](use-kms-keyring.md) no navegador. [raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser) Exporta funções compatíveis com [tokens de autenticação brutos do AES ](use-raw-aes-keyring.md) no navegador. [raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser) Exporta funções compatíveis com [tokens de autenticação brutos do RSA ](use-raw-rsa-keyring.md) no navegador. ## Módulos para todas as implementações [cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material) É compatível com o recurso de [armazenamento em cache de chaves de dados](data-key-caching.md). Fornece código para montar o material de criptografia que é armazenado em cache com cada chave de dados. [kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring) Exporta funções compatíveis com [tokens de autenticação do KMS](use-kms-keyring.md). [material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management) Implementa o [gerenciador de material de criptografia](concepts.md#crypt-materials-manager) (CMM). [raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring) Exporta funções necessárias para tokens de autenticação brutos do AES e do RSA. [serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize) Exporta funções que o SDK usa para serializar sua saída. [web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend) Exporta funções que usam a WebCrypto API AWS Encryption SDK para JavaScript no navegador. # AWS Encryption SDK para JavaScript exemplos Os exemplos a seguir mostram como usar o AWS Encryption SDK para JavaScript para criptografar e descriptografar dados. Você pode encontrar mais exemplos de uso do AWS Encryption SDK para JavaScript nos módulos [example-node e [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) no repositório em. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) GitHub Esses módulos de exemplo não são instalados quando você instala os módulos `client-browser` ou `client-node`. **Consulte os exemplos de código completos**: nó: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts), navegador: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts) **Topics** + [ ## Criptografando dados com um chaveiro AWS KMS ](#javascript-example-encrypt) + [ ## Descriptografando dados com um chaveiro AWS KMS ](#javascript-example-decrypt) ## Criptografando dados com um chaveiro AWS KMS O exemplo a seguir mostra como usar o para AWS Encryption SDK para JavaScript criptografar e descriptografar uma string curta ou uma matriz de bytes. Este exemplo apresenta um [AWS KMS chaveiro](use-kms-keyring.md), um tipo de chaveiro que usa um AWS KMS key para gerar e criptografar chaves de dados. Para obter ajuda na criação de um AWS KMS key, consulte [Criação de chaves](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) no *Guia do AWS Key Management Service desenvolvedor*. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id) Etapa 1: defina a política de compromisso. A partir da versão 1.7. *x* do AWS Encryption SDK para JavaScript, você pode definir a política de compromisso ao chamar a nova `buildClient` função que instancia um AWS Encryption SDK cliente. A função `buildClient` assume um valor enumerado que representa sua política de compromisso. Ela retorna as funções `encrypt` e `decrypt` atualizadas, que reforçam sua política de compromisso quando você criptografa e descriptografa. Os exemplos a seguir usam a `buildClient` função para especificar a [política de compromisso padrão](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. Você também pode usar o `buildClient` para limitar o número de chaves de dados criptografadas em uma mensagem criptografada. Para obter mais informações, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys). ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` Etapa 2: estruturar o token de autenticação. Crie um AWS KMS chaveiro para criptografia. Ao criptografar com um AWS KMS chaveiro, você deve especificar uma *chave geradora*, ou seja, uma AWS KMS key que seja usada para gerar a chave de dados em texto simples e criptografá-la. Você também pode especificar zero ou mais *chaves adicionais* que criptografam a mesma chave de dados de texto simples. O chaveiro retorna a chave de dados em texto simples e uma cópia criptografada dessa chave de dados para cada um AWS KMS key no chaveiro, incluindo a chave do gerador. Para descriptografar os dados, você precisa descriptografar qualquer uma das chaves de dados criptografadas. Para especificar o AWS KMS keys para um chaveiro de criptografia no AWS Encryption SDK para JavaScript, você pode usar [qualquer identificador de AWS KMS chave compatível](use-kms-keyring.md#kms-keyring-id). Este exemplo usa uma chave geradora, que é identificada por seu [ARN de alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN), e uma chave adicional, que é identificada por um [ARN de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). Se você planeja reutilizar seu AWS KMS chaveiro para descriptografar, você deve usar a chave para identificar o que está no ARNs chaveiro. AWS KMS keys Antes de executar esse código, substitua os identificadores de exemplo por AWS KMS key identificadores válidos. Você deve ter as [permissões necessárias para usar as AWS KMS keys](use-kms-keyring.md#kms-keyring-permissions) no token de autenticação. Comece fornecendo suas credenciais para o navegador. Os AWS Encryption SDK para JavaScript exemplos usam o [webpack. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), que substitui as constantes de credenciais por suas credenciais reais. Mas você pode usar qualquer método para fornecer suas credenciais. Em seguida, use as credenciais para criar um AWS KMS cliente. ``` declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) ``` Em seguida, especifique AWS KMS keys a chave do gerador e a chave adicional. Em seguida, crie um AWS KMS chaveiro usando o AWS KMS cliente e o. AWS KMS keys ``` const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds }) ``` ``` const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ generatorKeyId, keyIds }) ``` Etapa 3: defina o contexto de criptografia. Um [contexto de criptografia](concepts.md#encryption-context) são dados autenticados adicionais arbitrários e que não são secretos. Quando você fornece um contexto de criptografia na criptografia, ele vincula AWS Encryption SDK criptograficamente o contexto de criptografia ao texto cifrado, de forma que o mesmo contexto de criptografia seja necessário para descriptografar os dados. O uso de um contexto de criptografia é opcional, mas o recomendamos como uma melhor prática. Crie um objeto simples que inclua os pares de contexto de criptografia. A chave e o valor em cada par devem ser uma string. ``` const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' } ``` ``` const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' } ``` Etapa 4: criptografar os dados. Para criptografar os dados de texto simples, chame a função `encrypt`. Passe o AWS KMS chaveiro, os dados em texto simples e o contexto de criptografia. A função `encrypt` retorna uma [mensagem criptografada](concepts.md#message) (`result`) que contém os dados criptografados, as chaves de dados criptografadas e metadados importantes, incluindo o contexto de criptografia e a assinatura. Você pode [descriptografar essa mensagem criptografada](#javascript-example-decrypt) usando o AWS Encryption SDK para qualquer linguagem de programação compatível. ``` const plaintext = new Uint8Array([1, 2, 3, 4, 5]) const { result } = await encrypt(keyring, plaintext, { encryptionContext: context }) ``` ``` const plaintext = 'asdf' const { result } = await encrypt(keyring, plaintext, { encryptionContext: context }) ``` ## Descriptografando dados com um chaveiro AWS KMS Você pode usar o AWS Encryption SDK para JavaScript para descriptografar a mensagem criptografada e recuperar os dados originais. Neste exemplo, descriptografamos os dados que criptografamos no exemplo [Criptografando dados com um chaveiro AWS KMS](#javascript-example-encrypt). Etapa 1: defina a política de compromisso. A partir da versão 1.7. *x* do AWS Encryption SDK para JavaScript, você pode definir a política de compromisso ao chamar a nova `buildClient` função que instancia um AWS Encryption SDK cliente. A função `buildClient` assume um valor enumerado que representa sua política de compromisso. Ela retorna as funções `encrypt` e `decrypt` atualizadas, que reforçam sua política de compromisso quando você criptografa e descriptografa. Os exemplos a seguir usam a `buildClient` função para especificar a [política de compromisso padrão](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. Você também pode usar o `buildClient` para limitar o número de chaves de dados criptografadas em uma mensagem criptografada. Para obter mais informações, consulte [Limitar as chaves de dados criptografadas](configure.md#config-limit-keys). ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` Etapa 2: estruturar o token de autenticação. Para descriptografar os dados, passe a [mensagem criptografada](concepts.md#message) (`result`) que a função `encrypt` retornou. A mensagem criptografada inclui os dados criptografados, as chaves de dados criptografadas e metadados importantes, incluindo o contexto de criptografia e a assinatura. Você também deve especificar um [ token de autenticação do AWS KMS](use-kms-keyring.md) ao descriptografar. Você pode usar o mesmo token de autenticação usado para criptografar os dados ou um token de autenticação diferente. Para ter sucesso, pelo menos um AWS KMS key no chaveiro de decodificação deve ser capaz de descriptografar uma das chaves de dados criptografadas na mensagem criptografada. Como nenhuma chave de dados é gerada, você não precisa especificar uma chave geradora em um token de autenticação de descriptografia. Se você fizer isso, a chave geradora e as chaves adicionais serão tratadas da mesma maneira. [Para especificar um AWS KMS key para um chaveiro de decodificação no AWS Encryption SDK para JavaScript, você deve usar a chave ARN.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) Caso contrário, AWS KMS key o não será reconhecido. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id) Se você usar o mesmo chaveiro para criptografar e descriptografar, use a chave ARNs para identificar o que está no chaveiro. AWS KMS keys Neste exemplo, criamos um chaveiro que inclui apenas um dos do AWS KMS keys chaveiro de criptografia. Antes de executar esse código, substitua o ARN da chave de exemplo por um válido. Você deve ter a permissão `kms:Decrypt` na AWS KMS key. Comece fornecendo suas credenciais para o navegador. Os AWS Encryption SDK para JavaScript exemplos usam o [webpack. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), que substitui as constantes de credenciais por suas credenciais reais. Mas você pode usar qualquer método para fornecer suas credenciais. Em seguida, use as credenciais para criar um AWS KMS cliente. ``` declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) ``` Em seguida, crie um AWS KMS chaveiro usando o AWS KMS cliente. Este exemplo usa apenas um dos AWS KMS keys do chaveiro de criptografia. ``` const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, keyIds }) ``` ``` const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ keyIds }) ``` Etapa 3: decifrar os dados. Chame a função `decrypt`. Passe o token de autenticação de descriptografia que você acabou de criar (`keyring`) e a [mensagem criptografada](concepts.md#message) que a função `encrypt` retornou (`result`). O AWS Encryption SDK usa o chaveiro para descriptografar uma das chaves de dados criptografadas. Ele usa a chave de dados de texto simples para descriptografar os dados. Se a chamada for bem-sucedida, o campo `plaintext` conterá os dados de texto simples (descriptografados). O campo `messageHeader` contém metadados sobre o processo de descriptografia, incluindo o contexto de criptografia usado para descriptografar os dados. ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` Etapa 4: Verifique o contexto de criptografia. O [contexto de criptografia](concepts.md#encryption-context) que foi usado para descriptografar os dados é incluído no cabeçalho da mensagem (`messageHeader`) que a função `decrypt` retorna. Antes do aplicativo retornar os dados de texto simples, verifique se o contexto de criptografia fornecido durante a criptografia está incluído no contexto de criptografia usado ao descriptografar. Uma incompatibilidade pode indicar que os dados foram adulterados ou que você não descriptografou o texto cifrado correto. Ao verificar o contexto de criptografia, não exija uma correspondência exata. Ao usar um algoritmo de criptografia com a assinatura, o [gerenciador de material de criptografia](concepts.md#crypt-materials-manager) (CMM) adiciona a chave de assinatura pública ao contexto de criptografia antes de criptografar a mensagem. Mas todos os pares de contexto de criptografia que você enviou devem ser incluídos no contexto de criptografia que foi retornado. Primeiro, obtenha o contexto de criptografia do cabeçalho da mensagem. Depois, verifique se cada par de chave-valor no contexto de criptografia original (`context`) corresponde a um par de chave-valor no contexto de criptografia retornado (`encryptionContext`). ``` const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') }) ``` ``` const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') }) ``` Se a verificação de contexto de criptografia for bem-sucedida, você poderá retornar os dados de texto simples. # AWS Encryption SDK for Python Este tópico explica como instalar e usar o AWS Encryption SDK for Python. Para obter detalhes sobre a programação com o AWS Encryption SDK for Python, consulte o [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositório em GitHub. Para obter a documentação da API, consulte [Ler os documentos](https://aws-encryption-sdk-python.readthedocs.io/en/latest/). **Topics** + [ ## Pré-requisitos ](#python-prerequisites) + [ ## Instalação ](#python-installation) + [Exemplos](python-example-code.md) ## Pré-requisitos Antes de instalar o AWS Encryption SDK for Python, verifique se você tem os seguintes pré-requisitos. **Uma versão compatível do Python** O Python 3.8 ou posterior é exigido pelas AWS Encryption SDK for Python versões 3.2.0 e posteriores. A [Biblioteca de Provedores de Material AWS Criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) é uma dependência opcional para a AWS Encryption SDK for Python introduzida na versão 4. *x.* Se você pretende instalar o MPL, você deve usar o Python 3.11 ou posterior. As versões anteriores do AWS Encryption SDK oferecem suporte ao Python 2.7 e ao Python 3.4 e posteriores, mas recomendamos que você use a versão mais recente do. AWS Encryption SDK Para fazer download do Python, consulte [Downloads do Python](https://www.python.org/downloads/). **A ferramenta de instalação do pip para Python** O Python 3.6 e versões posteriores incluem `pip`, embora você possa querer atualizá-lo. Para obter mais informações sobre a atualização ou a instalação do `pip` consulte [Instalação](https://pip.pypa.io/en/latest/installation/) na documentação do `pip`. ## Instalação Instalar a versão mais recente do AWS Encryption SDK for Python. **nota** Todas as versões AWS Encryption SDK for Python anteriores à 3.0.0 estão em [end-of-supportfase](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.0.*x* e posteriores até a versão mais recente do AWS Encryption SDK 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.0.*x* não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.*x* até a versão 2.0. *x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente do AWS Encryption SDK. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md). Use `pip` para instalar o AWS Encryption SDK for Python, conforme mostrado nos exemplos a seguir. **Para instalar a versão mais recente** ``` pip install "aws-encryption-sdk[MPL]" ``` O `[MPL]` sufixo instala a [Biblioteca de Provedores de Material AWS Criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL). O MPL contém construções para criptografar e descriptografar seus dados. O MPL é uma dependência opcional para o AWS Encryption SDK for Python introduzido na versão 4. *x.* É altamente recomendável instalar o MPL. No entanto, se você não pretende usar o MPL, pode omitir o `[MPL]` sufixo. Para obter mais detalhes sobre o uso do pip para instalar e atualizar pacotes, consulte [Instalação de pacotes](https://packaging.python.org/tutorials/installing-packages/). AWS Encryption SDK for Python Isso requer a [biblioteca de criptografia (pyca/cryptography](https://cryptography.io/en/latest/)) em todas as plataformas. Todas as versões do `pip` instalam e criam automaticamente a biblioteca `cryptography` no Windows. O `pip` 8.1 e versões posteriores instala e compila `cryptography` automaticamente no Linux. Se você usar uma versão anterior do `pip` e seu ambiente Linux não tiver as ferramentas necessárias para criar a biblioteca `cryptography`, será necessário instalá-las. Para obter mais informações, consulte [Building Cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux). As versões 1.10.0 e 2.5.0 do AWS Encryption SDK for Python fixam a dependência [criptográfica](https://cryptography.io/en/latest/) entre 2.5.0 e 3.3.2. Outras versões do AWS Encryption SDK for Python instalam a versão mais recente da criptografia. Se você precisar de uma versão do cryptography posterior à 3.3.2, recomendamos que use a versão principal mais recente do AWS Encryption SDK for Python. Para obter a versão de desenvolvimento mais recente do AWS Encryption SDK for Python, acesse o [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositório em GitHub. Depois de instalar o AWS Encryption SDK for Python, comece examinando o [código de exemplo do Python](python-example-code.md) neste guia. # AWS Encryption SDK for Python código de exemplo Os exemplos a seguir mostram como usar o para AWS Encryption SDK for Python criptografar e descriptografar dados. Os exemplos nesta seção mostram como usar a versão 4. *x* do AWS Encryption SDK for Python com a dependência opcional da [Biblioteca de Provedores de Material Criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) ()`aws-cryptographic-material-providers`. Para ver exemplos que usam versões anteriores ou instalações sem a biblioteca de fornecedores de materiais (MPL), encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-python/releases) do [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositório em. GitHub Quando você usa a versão 4. *x* do AWS Encryption SDK for Python com o MPL, ele usa [chaveiros para realizar a criptografia](choose-keyring.md) de [envelopes](concepts.md#envelope-encryption). AWS Encryption SDK Fornece chaveiros compatíveis com os fornecedores de chaves mestras que você usou nas versões anteriores. Para obter mais informações, consulte [Compatibilidade dos tokens de autenticação](choose-keyring.md#keyring-compatibility). Para exemplos de migração de provedores de chaves mestras para chaveiros, consulte [Exemplos de migração](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration) no `aws-encryption-sdk-python` repositório em; GitHub **Topics** + [Strings](#python-example-strings) + [streams de bytes](#python-example-streams) ## Criptografar e descriptografar strings O exemplo a seguir mostra como usar o para criptografar e AWS Encryption SDK descriptografar cadeias de caracteres. Este exemplo usa um [AWS KMS chaveiro](use-kms-keyring.md) com uma chave KMS de criptografia simétrica. Este exemplo instancia o AWS Encryption SDK cliente com a [política de compromisso padrão](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obter mais informações, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md). ``` # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example sets up the KMS Keyring The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA with an encryption context. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings of the same or a different type. """ import boto3 from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput from aws_cryptographic_material_providers.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy EXAMPLE_DATA: bytes = b"Hello World" def encrypt_and_decrypt_with_keyring( kms_key_id: str ): """Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring. Usage: encrypt_and_decrypt_with_keyring(kms_key_id) :param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and decryption of your data keys. :type kms_key_id: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. Create a boto3 client for KMS. kms_client = boto3.client('kms', region_name="us-west-2") # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "encryption": "context", "is not": "secret", "but adds": "useful metadata", "that can help you": "be confident that", "the data you are handling": "is what you think it is", } # 4. Create your keyring mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput( kms_key_id=kms_key_id, kms_client=kms_client ) kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring( input=keyring_input ) # 5. Encrypt the data with the encryptionContext. ciphertext, _ = client.encrypt( source=EXAMPLE_DATA, keyring=kms_keyring, encryption_context=encryption_context ) # 6. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert ciphertext != EXAMPLE_DATA, \ "Ciphertext and plaintext data are the same. Invalid encryption" # 7. Decrypt your encrypted data using the same keyring you used on encrypt. plaintext_bytes, _ = client.decrypt( source=ciphertext, keyring=kms_keyring, # Provide the encryption context that was supplied to the encrypt method encryption_context=encryption_context, ) # 8. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert plaintext_bytes == EXAMPLE_DATA, \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption" ``` ## Criptografar e descriptografar streams de bytes O exemplo a seguir mostra como usar o para AWS Encryption SDK criptografar e descriptografar fluxos de bytes. Este exemplo usa um [chaveiro AES bruto](use-raw-aes-keyring.md). Este exemplo instancia o AWS Encryption SDK cliente com a [política de compromisso padrão](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obter mais informações, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md). ``` # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example demonstrates file streaming for encryption and decryption. File streaming is useful when the plaintext or ciphertext file/data is too large to load into memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it all at once in memory. In this example, we demonstrate file streaming for encryption and decryption using a Raw AES keyring. However, you can use any keyring with streaming. This example creates a Raw AES Keyring and then encrypts an input stream from the file `plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`. It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. See raw_aes_keyring_example.py in the same directory for another raw AES keyring example in the AWS Encryption SDK for Python. """ import filecmp import secrets from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput from aws_cryptographic_material_providers.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy def encrypt_and_decrypt_with_keyring( plaintext_filename: str, ciphertext_filename: str, decrypted_filename: str ): """Demonstrate a streaming encrypt/decrypt cycle. Usage: encrypt_and_decrypt_with_keyring(plaintext_filename ciphertext_filename decrypted_filename) :param plaintext_filename: filename of the plaintext data :type plaintext_filename: string :param ciphertext_filename: filename of the ciphertext data :type ciphertext_filename: string :param decrypted_filename: filename of the decrypted data :type decrypted_filename: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. The key namespace and key name are defined by you. # and are used by the Raw AES keyring to determine # whether it should attempt to decrypt an encrypted data key. key_name_space = "Some managed raw keys" key_name = "My 256-bit AES wrapping key" # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "encryption": "context", "is not": "secret", "but adds": "useful metadata", "that can help you": "be confident that", "the data you are handling": "is what you think it is", } # 4. Generate a 256-bit AES key to use with your keyring. # In practice, you should get this key from a secure key management system such as an HSM. # Here, the input to secrets.token_bytes() = 32 bytes = 256 bits static_key = secrets.token_bytes(32) # 5. Create a Raw AES keyring # We choose to use a raw AES keyring, but any keyring can be used with streaming. mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput( key_namespace=key_name_space, key_name=key_name, wrapping_key=static_key, wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16 ) raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring( input=keyring_input ) # 6. Encrypt the data stream with the encryptionContext with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file: with client.stream( mode='e', source=pt_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as encryptor: for chunk in encryptor: ct_file.write(chunk) # 7. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \ "Ciphertext and plaintext data are the same. Invalid encryption" # 8. Decrypt your encrypted data stream using the same keyring you used on encrypt. with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file: with client.stream( mode='d', source=ct_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as decryptor: for chunk in decryptor: pt_file.write(chunk) # 10. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert filecmp.cmp(plaintext_filename, decrypted_filename), \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption" ``` # AWS Encryption SDK para Rust Este tópico explica como instalar e usar o AWS Encryption SDK for Rust. Para obter detalhes sobre a programação com o AWS Encryption SDK for Rust, consulte o diretório [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) do aws-encryption-sdk repositório em. GitHub O AWS Encryption SDK for Rust difere de algumas das outras implementações de linguagem de programação do das seguintes AWS Encryption SDK maneiras: + Não há suporte para armazenamento em [cache de chaves de dados](data-key-caching.md). No entanto, o AWS Encryption SDK for Rust suporta o [AWS KMS chaveiro hierárquico](use-hierarchical-keyring.md), uma solução alternativa de cache de materiais criptográficos. + Não há suporte para streaming de dados O AWS Encryption SDK for Rust inclui todos os recursos de segurança introduzidos nas versões 2.0. *x* e posteriores de outras implementações de linguagem do AWS Encryption SDK. No entanto, se você estiver usando o for Rust AWS Encryption SDK para descriptografar dados que foram criptografados por um pré-2.0. versão *x* outra implementação de linguagem do AWS Encryption SDK, talvez seja necessário ajustar sua [política de compromisso](concepts.md#commitment-policy). Para obter detalhes, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md#migrate-commitment-step1). O AWS Encryption SDK for Rust é um produto do AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), uma linguagem de verificação formal na qual você escreve especificações, o código para implementá-las e as provas para testá-las. O resultado é uma biblioteca que implementa os atributos do AWS Encryption SDK em uma estrutura que garante a correção funcional. **Saiba mais** + Para ver exemplos que mostram como configurar opções no AWS Encryption SDK, como especificar um conjunto alternativo de algoritmos, limitar chaves de dados criptografadas e usar chaves AWS KMS multirregionais, consulte. [Configurando o AWS Encryption SDK](configure.md) + Para exemplos que mostram como configurar e usar o AWS Encryption SDK for Rust, consulte os [exemplos do Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples) no aws-encryption-sdk repositório em. GitHub **Topics** + [ ## Pré-requisitos ](#prerequisites-rust) + [ ## Instalação ](#rust-installation) + [Exemplos](rust-examples.md) ## Pré-requisitos Antes de instalar o AWS Encryption SDK for Rust, verifique se você tem os seguintes pré-requisitos. **Instale Rust and Cargo** Instale a versão estável atual do [Rust](https://www.rust-lang.org/) usando o [rustup](https://rustup.rs/). Para obter mais informações sobre como baixar e instalar o rustup, consulte os [procedimentos de instalação](https://doc.rust-lang.org/cargo/getting-started/installation.html) no The Cargo Book. ## Instalação O AWS Encryption SDK for Rust está disponível como caixa em [https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk)Crates.io. Para obter detalhes sobre como instalar e construir o AWS Encryption SDK para Rust, consulte o [README.md no repositório](https://github.com/aws/aws-encryption-sdk/tree/mainline) em. aws-encryption-sdk GitHub Você pode instalar o AWS Encryption SDK for Rust das seguintes maneiras. **Manualmente** Para instalar o AWS Encryption SDK for Rust, clone ou baixe o [aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub repositório. **Usando Crates.io** Execute o seguinte comando Cargo no diretório do seu projeto: ``` cargo add aws-esdk ``` Ou adicione a seguinte linha ao seu Cargo.toml: ``` aws-esdk = "" ``` # AWS Encryption SDK para código de exemplo de Rust Os exemplos a seguir mostram os padrões básicos de codificação que você usa ao programar com o AWS Encryption SDK for Rust. Especificamente, você instancia a biblioteca AWS Encryption SDK e os fornecedores de materiais. Em seguida, antes de chamar cada método, você instancia o objeto que define a entrada para o método. Para exemplos que mostram como configurar opções no AWS Encryption SDK, como especificar um conjunto alternativo de algoritmos e limitar chaves de dados criptografadas, consulte os [exemplos de Rust no aws-encryption-sdk repositório](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/) em. GitHub ## Criptografando e descriptografando dados no for Rust AWS Encryption SDK Este exemplo mostra o padrão básico para criptografar e descriptografar dados. Ele criptografa um pequeno arquivo com chaves de dados protegidas por uma chave de AWS KMS empacotamento. **Etapa 1: Instancie o. AWS Encryption SDK** Você usará os métodos do AWS Encryption SDK para criptografar e descriptografar dados. ``` let esdk_config = AwsEncryptionSdkConfig::builder().build()?; let esdk_client = esdk_client::Client::from_conf(esdk_config)?; ``` **Etapa 2: Crie um AWS KMS cliente.** ``` let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await; let kms_client = aws_sdk_kms::Client::new(&sdk_config); ``` **Opcional: crie seu contexto de criptografia.** ``` let encryption_context = HashMap::from([ ("encryption".to_string(), "context".to_string()), ("is not".to_string(), "secret".to_string()), ("but adds".to_string(), "useful metadata".to_string()), ("that can help you".to_string(), "be confident that".to_string()), ("the data you are handling".to_string(), "is what you think it is".to_string()), ]); ``` **Etapa 3: Instanciar a biblioteca de fornecedores de materiais.** Você usará os métodos na biblioteca de fornecedores de materiais para criar os tokens de autenticação que especificam quais chaves protegem seus dados. ``` let mpl_config = MaterialProvidersConfig::builder().build()?; let mpl = mpl_client::Client::from_conf(mpl_config)?; ``` **Etapa 4: Crie um AWS KMS chaveiro.** Para criar o token de autenticação, chame o método do token de autenticação com o objeto de entrada do token de autenticação. Este exemplo usa o `create_aws_kms_keyring()` método e especifica uma chave KMS. ``` let kms_keyring = mpl .create_aws_kms_keyring() .kms_key_id(kms_key_id) .kms_client(kms_client) .send() .await?; ``` **Etapa 5: criptografar o texto sem formatação.** ``` let plaintext = example_data.as_bytes(); let encryption_response = esdk_client.encrypt() .plaintext(plaintext) .keyring(kms_keyring.clone()) .encryption_context(encryption_context.clone()) .send() .await?; let ciphertext = encryption_response .ciphertext .expect("Unable to unwrap ciphertext from encryption response"); ``` **Etapa 6: descriptografe seus dados criptografados usando o mesmo chaveiro que você usou na criptografia.** ``` let decryption_response = esdk_client.decrypt() .ciphertext(ciphertext) .keyring(kms_keyring) // Provide the encryption context that was supplied to the encrypt method .encryption_context(encryption_context) .send() .await?; let decrypted_plaintext = decryption_response .plaintext .expect("Unable to unwrap plaintext from decryption response"); ``` # 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).