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á.
# Migrando seu AWS Encryption SDK
O AWS Encryption SDK suporta várias [implementações de linguagem de programação](programming-languages.md) interoperáveis, cada uma delas desenvolvida em um repositório de código aberto no. GitHub Como [prática recomendada](best-practices.md), recomendamos que você use a versão mais recente do AWS Encryption SDK para cada idioma.
Você pode atualizar com segurança a partir da versão 2.0. *x* ou posterior AWS Encryption SDK para a versão mais recente. No entanto, o 2.0. A versão *x* do AWS Encryption SDK introduz novos recursos de segurança significativos, alguns dos quais são mudanças significativas. Para atualizar de versões anteriores à 1.7.*x* para a versão 2.0.*x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente. Os tópicos desta seção foram elaborados para ajudar você a entender as alterações, selecionar a versão correta para a aplicação e migrar com segurança e sucesso para as versões mais recentes do AWS Encryption SDK.
Para obter informações sobre versões significativas do AWS Encryption SDK, consulte[Versões do AWS Encryption SDK](about-versions.md).
**Importante**
Não atualize diretamente de uma versão anterior à 1.7*x* para a versão 2.0.*x* ou posterior sem primeiro atualizar para a mais recente versão 1*x.*. Se você atualizar diretamente para a versão 2.0. *x* ou posterior e habilite todos os novos recursos imediatamente, eles não AWS Encryption SDK conseguirão descriptografar texto cifrado criptografado em versões mais antigas do. AWS Encryption SDK
**nota**
A versão mais antiga do AWS Encryption SDK para.NET é a versão 3.0. *x.* Todas as versões do AWS Encryption SDK para.NET oferecem suporte às melhores práticas de segurança introduzidas na versão 2.0. *x* do AWS Encryption SDK. É possível atualizar com segurança para a versão mais recente sem fazer alterações no código ou nos dados.
AWS CLI de criptografia: ao ler este guia de migração, use a versão 1.7. *x* instruções de migração para o AWS Encryption CLI 1.8. *x* e use o 2.0. *x* instruções de migração para o AWS Encryption CLI 2.1. *x.* Para obter detalhes, consulte [Versões da CLI AWS de criptografia](crypto-cli-versions.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.
**Novos usuários**
Se você é novo no AWS Encryption SDK, instale a versão mais recente do AWS Encryption SDK para sua linguagem de programação. Os valores padrão habilitam todos os recursos de segurança do AWS Encryption SDK, incluindo criptografia com assinatura, derivação de [chave e comprometimento de chave](concepts.md#key-commitment). AWS Encryption SDK
**Usuários atuais**
Recomendamos atualizar da versão atual para a versão mais recente disponível assim que possível. Todos os 1. As versões *x* do AWS Encryption SDK estão em [end-of-support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), assim como as versões posteriores em algumas linguagens de programação. Para obter detalhes sobre o status de suporte e manutenção do AWS Encryption SDK em sua linguagem de programação, consulte [Suporte e manutenção](introduction.md#support).
AWS Encryption SDK versões 2.0. *x* e versões posteriores fornecem novos recursos de segurança para ajudar a proteger seus dados. No entanto, AWS Encryption SDK a versão 2.0. *x* inclui alterações significativas que não são compatíveis com versões anteriores. Para garantir uma transição segura, comece migrando da sua versão atual para a mais recente 1.*x* na sua linguagem de programação. Quando a versão 1.*x* estiver totalmente implantada e operando com sucesso, você poderá migrar com segurança para as versões 2.0.*x* e posteriores. Esse [processo de duas etapas](migration-guide.md) é essencial, especialmente para aplicações distribuídas.
*Para obter mais informações sobre os recursos AWS Encryption SDK de segurança subjacentes a essas mudanças, consulte [Criptografia aprimorada do lado do cliente: compromisso explícito KeyIds e fundamental](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/) no Blog de Segurança.AWS *
Procurando ajuda para usar o AWS Encryption SDK for Java com o AWS SDK for Java 2.x? Consulte [Pré-requisitos](java.md#java-prerequisites).
**Topics**
+ [Como migrar e implantar o AWS Encryption SDK](migration-guide.md)
+ [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md)
+ [Atualizando AWS KMS chaveiros](migrate-keyrings-v2.md)
+ [Como definir sua política de compromisso](migrate-commitment-policy.md)
+ [Solução de problemas de migração para as versões mais recentes](troubleshooting-migration.md)
# Como migrar e implantar o AWS Encryption SDK
Ao migrar de uma AWS Encryption SDK versão anterior à 1.7. *x* até a versão 2.0. *x* ou mais tarde, você deve fazer a transição segura para a criptografia com [comprometimento de chave](concepts.md#key-commitment). Caso contrário, a aplicação encontrará textos cifrados que não poderá descriptografar. Se você estiver usando provedores de chave AWS KMS mestra, deverá atualizar para novos construtores que criam provedores de chave mestra no modo estrito ou no modo de descoberta.
**nota**
Este tópico foi desenvolvido para usuários que estão migrando de versões anteriores do AWS Encryption SDK para a versão 2.0. *x* posterior. Se você é novo no AWS Encryption SDK, pode começar a usar a versão mais recente disponível imediatamente com as configurações padrão.
Para evitar uma situação crítica na qual você não possa descriptografar o texto cifrado que precisa ler, recomendamos que você migre e implante em várias etapas distintas. Verifique se cada etapa está completa e totalmente implantada antes de iniciar a próxima etapa. Isso é particularmente importante para aplicações distribuídas com vários hosts.
## Etapa 1: atualize a aplicação para a versão 1.*x* mais recente
Atualize para a versão 1.*x* mais recente para sua linguagem de programação. Teste com cuidado, implante suas alterações e confirme se a atualização foi propagada para todos os hosts de destino antes de iniciar a etapa 2.
**Importante**
Verifique se a sua versão 1.*x* mais recente é a versão 1.7.*x* ou versão posterior do AWS Encryption SDK.
O mais recente 1. As versões *x* do AWS Encryption SDK são compatíveis com versões anteriores do AWS Encryption SDK e versões anteriores com as versões 2.0. *x* e mais tarde. Elas incluem os novos atributos presentes na versão 2.0.*x*, mas inclui padrões seguros projetados para essa migração. Eles permitem que você atualize seus provedores de chave AWS KMS mestra, se necessário, e implante totalmente pacotes de algoritmos que podem decifrar texto cifrado com comprometimento de chave.
+ Substitua elementos descontinuados, incluindo construtores para provedores de chaves metras do AWS KMS herdados. Em Python,ative os [avisos de descontinuidade](https://docs.python.org/3/library/warnings.html). Elementos de código que foram descontinuados na mais recente versão 1.*x* foram removidos das versões 2.0. *x* e posteriores.
+ Defina explicitamente sua política de compromisso como `ForbidEncryptAllowDecrypt`. Embora esse seja o único valor válido no último 1. Nas versões *x*, essa configuração é necessária quando você usa a APIs introduzida nesta versão. Isso impede que a aplicação rejeite texto cifrado criptografado sem confirmação de chave quando você migra para a versão 2.0.*x* e versões posteriores. Para obter detalhes, consulte [Como definir sua política de compromisso](migrate-commitment-policy.md).
+ Se você usa provedores de chave AWS KMS mestra, deve atualizar seus provedores de chave mestra legados para provedores de chave mestra que ofereçam suporte ao *modo estrito* e ao *modo de descoberta*. Essa atualização é necessária para o AWS Encryption SDK for Java AWS Encryption SDK for Python, e para a CLI AWS de criptografia. Se você usa provedores de chave mestra no modo de descoberta, recomendamos que implemente o filtro de descoberta que limita as chaves de encapsulamento usadas àquelas presentes em Contas da AWS. Essa atualização é opcional, mas é uma [prática recomendada](best-practices.md) que incentivamos. Para obter detalhes, consulte [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md).
+ Se você usa [token de autenticação de descoberta do AWS KMS](use-kms-keyring.md#kms-keyring-discovery), recomendamos que inclua um filtro de descoberta que limite as chaves de encapsulamento usadas na descriptografia a aquelas em particular. Contas da AWS Essa atualização é opcional, mas é uma [prática recomendada](best-practices.md) que incentivamos. Para obter detalhes, consulte [Atualizando AWS KMS chaveiros](migrate-keyrings-v2.md).
## Etapa 2: atualize a aplicação para a versão mais recente
Depois que a implantação da mais recente versão 1.*x* for bem-sucedida em todos os hosts, você pode atualizar para as versões 2.0. *x* e posteriores. Versão 2.0. *x* inclui alterações significativas em todas as versões anteriores do AWS Encryption SDK. No entanto, se você fizer as alterações de código recomendadas na etapa 1, poderá evitar erros ao migrar para a versão mais recente.
Antes de atualizar para a versão mais recente, verifique se sua política de compromisso está consistentemente definida como `ForbidEncryptAllowDecrypt`. Em seguida, dependendo da configuração de dados, você pode migrar no seu próprio ritmo para `RequireEncryptAllowDecrypt` e depois para a configuração padrão, `RequireEncryptRequireDecrypt`. Recomendamos uma série de etapas de transição, como o padrão a seguir.
1. Comece com sua [política de compromisso](migrate-commitment-policy.md) definida como `ForbidEncryptAllowDecrypt`. O AWS Encryption SDK pode descriptografar mensagens com confirmação de chave, mas ainda não descriptografa com confirmação de chave.
1. Quando estiver pronto, atualize a política de compromisso para `RequireEncryptAllowDecrypt`. AWS Encryption SDK Começa a criptografar seus dados com um [compromisso fundamental](concepts.md#key-commitment). Ele poderá descriptografar textos cifrados criptografados com ou sem confirmação de chave.
Antes de atualizar sua política de compromisso para `RequireEncryptAllowDecrypt`, verifique se sua versão 1*x* mais recente foi implantada em todos os hosts, incluindo os hosts de qualquer aplicação que decodifique o texto cifrado que você produz. Versões AWS Encryption SDK anteriores à versão 1.7. *x* não pode descriptografar mensagens criptografadas com comprometimento de chave.
Esse também é um bom momento para adicionar métricas à sua aplicação para medir se você ainda está processando texto cifrado sem confirmação de chave. Isso ajudará você a determinar quando é seguro atualizar sua configuração de política de compromisso para `RequireEncryptRequireDecrypt`. Para algumas aplicações, como aquelas que criptografam mensagens em uma fila do Amazon SQS, isso pode significar esperar tempo suficiente para que todo o texto cifrado criptografado nas versões antigas seja recriptografado ou excluído. Para outras aplicações, como objetos criptografados do S3, talvez seja necessário baixar, recriptografar e recarregar todos os objetos.
1. Quando tiver certeza de que não tem nenhuma mensagem criptografada sem confirmação de chave, você pode atualizar sua política de compromisso para `RequireEncryptRequireDecrypt`. Esse valor garante que seus dados sejam sempre criptografados e descriptografados com o confirmação de chave. Essa configuração é a padrão, então você não precisa defini-la explicitamente, mas recomendamos que faça isso. Uma configuração explícita [ajudará na depuração](troubleshooting-migration.md) e em quaisquer possíveis reversões que possam ser necessárias se a aplicação encontrar texto cifrado criptografado sem confirmação de chave.
# Atualizando provedores de chaves AWS KMS mestras
Para migrar para o mais recente 1. versão *x* do e AWS Encryption SDK, em seguida, para a versão 2.0. *x* ou posterior, você deve substituir os provedores de chave AWS KMS mestra legados por provedores de chave mestra criados explicitamente no [*modo estrito ou no modo* de *descoberta*](about-versions.md#changes-to-mkps). Os provedores de chave mestra herdados foram descontinuados na versão 1.7.*x* e foram removidos na versão 2.0. *x.* Essa alteração é necessária para aplicações e scripts que usam o [AWS Encryption SDK for Java](java.md), o [AWS Encryption SDK for Python](python.md) e a [CLI de criptografia da AWS](crypto-cli.md). Os exemplos nesta seção mostrarão como atualizar seu código.
**nota**
Em Python, [ative os avisos de obsolescência](https://docs.python.org/3/library/warnings.html). Isso ajudará você a identificar as partes do código que precisa atualizar.
Se você estiver usando uma chave AWS KMS mestra (não um provedor de chave mestra), você pode pular esta etapa. AWS KMS as chaves mestras não estão obsoletas nem foram removidas. Elas criptografam e descriptografam somente com as chaves de encapsulamento que você especificar.
Os exemplos nesta seção se concentram nos elementos do seu código precisam ser alterados. Para obter um exemplo completo do código atualizado, consulte a seção Exemplos do GitHub repositório da sua [linguagem de programação](programming-languages.md). Além disso, esses exemplos normalmente usam ARNs a chave para representar AWS KMS keys. Ao criar um provedor de chave mestra para criptografia, você pode usar qualquer [identificador de AWS KMS chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) válido para representar um AWS KMS key . Ao criar um provedor de chave mestra para descriptografia, você deve usar um ARN de chave.
**Saiba mais sobre migração**
Para todos os AWS Encryption SDK usuários, saiba como definir sua política de compromisso em[Como definir sua política de compromisso](migrate-commitment-policy.md).
Para AWS Encryption SDK para JavaScript usuários AWS Encryption SDK for C e usuários, saiba mais sobre uma atualização opcional dos chaveiros em[Atualizando AWS KMS chaveiros](migrate-keyrings-v2.md).
**Topics**
+ [Migração para o modo estrito](#migrate-mkp-strict-mode)
+ [Migrar para o modo de descoberta](#migrate-mkp-discovery-mode)
## Migração para o modo estrito
Depois de atualizar para o mais recente 1. versão *x* do AWS Encryption SDK, substitua seus provedores de chave mestra legados por provedores de chave mestra no modo estrito. No modo estrito, você deve especificar as chaves de encapsulamento a serem usadas ao criptografar e descriptografar. O AWS Encryption SDK usa somente as chaves de empacotamento que você especificar. Provedores de chaves mestras obsoletas podem descriptografar dados usando qualquer um AWS KMS key que criptografe uma chave de dados, inclusive em diferentes regiões. AWS KMS keys Contas da AWS
Os provedores de chaves mestras no modo estrito são introduzidos na AWS Encryption SDK versão 1.7. *x.* Eles substituem os provedores de chaves mestras herdados, que foram suspensos na versão 1.7.*x* e removidos na versão 2.0.*x.*. Usar provedores de chave mestra no modo estrito é uma [prática AWS Encryption SDK recomendada](best-practices.md).
O código a seguir cria um provedor de chave mestra no modo estrito que você pode usar para criptografar e descriptografar.
------
#### [ Java ]
Este exemplo representa o código em uma aplicação que usa a versão 1.6.2 ou anterior do AWS Encryption SDK for Java.
Esse código usa o `KmsMasterKeyProvider.builder()` método para instanciar um provedor de chave AWS KMS mestra que usa um AWS KMS key como chave de encapsulamento.
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
Este exemplo representa o código em uma aplicação que usa a versão 1.7.*x* ou versões posteriores do AWS Encryption SDK for Java . Para ver um exemplo completo, consulte [BasicEncryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)
Os métodos `Builder.build()` e `Builder.withKeysForEncryption()` usados no exemplo anterior foram suspensos na versão 1.7.*x* e removidos da versão 2.0.*x.*.
Para atualizar para um provedor de chave mestra de modo estrito, esse código substitui as chamadas para métodos suspensos por uma chamada para o novo método `Builder.buildStrict()`. Este exemplo especifica uma AWS KMS key como chave de empacotamento, mas o `Builder.buildStrict()` método pode usar uma lista de várias. AWS KMS keys
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your Conta da AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
Este exemplo representa o código em uma aplicação que usa a versão 1.4.1 do AWS Encryption SDK for Python. Esse código usa `KMSMasterKeyProvider`, que foi suspenso na versão 1.7. *x* e removido da versão 2.0.*x.*. Ao descriptografar, ele usa qualquer uma AWS KMS key que criptografe uma chave de dados sem levar em conta o AWS KMS keys que você especificar.
Observe que `KMSMasterKey` não foi suspenso nem removido. Ao criptografar e descriptografar, ele usa somente o que você especifica. AWS KMS key
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
Este exemplo representa o código em uma aplicação que usa a versão 1.7.*x* do AWS Encryption SDK for Python. Para ver um exemplo completo, consulte [basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py).
Para atualizar para um provedor de chave mestra de modo estrito, esse código substitui a chamada para `KMSMasterKeyProvider()` com uma chamada para `StrictAwsKmsMasterKeyProvider()`.
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your Conta da AWS
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
Este exemplo mostra como criptografar e descriptografar usando a versão 1.1.7 ou anterior do Encryption AWS CLI.
Na versão 1.1.7 e anteriores, ao criptografar, você especifica uma ou mais chaves mestras (ou *chaves de encapsulamento*), como uma AWS KMS key. Ao descriptografar, você não pode especificar nenhuma chave de encapsulamento, a menos que esteja usando um provedor de chave mestra personalizado. A CLI de AWS criptografia pode usar qualquer chave de empacotamento que criptografe uma chave de dados.
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
Este exemplo mostra como criptografar e descriptografar usando a versão 1.7 do Encryption AWS CLI. *x* ou mais tarde. Para obter exemplos completos, consulte [Exemplos da CLI AWS de criptografia](crypto-cli-examples.md).
O parâmetro `--master-keys` foi suspenso na versão 1.7.*x* e removido na versão 2.0.*x.*. Ele foi substituído pelo parâmetro `--wrapping-keys`, que é exigido nos comandos de encrypt e decrypt. Esse parâmetro é compatível com o modo estrito e o modo de descoberta. O modo estrito é uma prática AWS Encryption SDK recomendada que garante que você use a chave de encapsulamento desejada.
Para atualizar para o *modo estrito*, use o atributo **key** do parâmetro `--wrapping-keys` para especificar uma chave de encapsulamento ao criptografar e descriptografar.
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## Migrar para o modo de descoberta
A partir da versão 1.7. *x*, é uma [prática AWS Encryption SDK recomendada](best-practices.md) usar o *modo estrito* para provedores de chaves AWS KMS mestras, ou seja, especificar chaves de agrupamento ao criptografar e descriptografar. Você deve sempre especificar as chaves de encapsulamento ao criptografar. Mas há situações em que especificar a chave ARNs AWS KMS keys para descriptografar é impraticável. Por exemplo, se você estiver usando aliases para identificar AWS KMS keys ao criptografar, perderá o benefício dos aliases se precisar listar a chave ARNs ao descriptografar. Além disso, como os provedores de chave mestra no modo de descoberta se comportam como os provedores de chave mestra originais, você pode usá-los temporariamente como parte de sua estratégia de migração e, posteriormente, atualizar para provedores de chave mestra no modo estrito.
Em casos como esse, você pode usar provedores de chaves mestras no *modo de descoberta*. Esses provedores de chaves mestras não permitem que você especifique chaves de encapsulamento, portanto, você não pode usá-los para criptografar. Ao descriptografar, eles podem usar qualquer chave de encapsulamento que criptografe uma chave de dados. Mas, diferentemente dos provedores de chaves mestras herdados, que se comportam da mesma maneira, você cria esses provedores explicitamente no modo de descoberta. Ao usar provedores de chave mestra no modo de descoberta, você pode limitar as chaves de encapsulamento que podem ser usadas para aquelas que estão presentes em Contas da AWS específicas. Esse filtro de descoberta é opcional, mas é uma prática recomendada que incentivamos. Para obter informações sobre partições e contas da AWS , consulte [Nomes do atributo da Amazon](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) no *Referência geral da AWS*.
Os exemplos a seguir criam um provedor de chave AWS KMS mestra no modo estrito para criptografia e um provedor de chave AWS KMS mestra no modo de descoberta para descriptografia. O provedor da chave mestra no modo de descoberta usa um filtro de descoberta para limitar as chaves de encapsulamento usadas para descriptografar à partição `aws` e ao exemplo específico de Contas da AWS. Embora o filtro de conta não seja necessário neste exemplo bastante simples, é uma prática recomendada muito benéfica quando uma aplicação criptografa os dados e outra diferente os descriptografa.
------
#### [ Java ]
Este exemplo representa o código em uma aplicação que usa a versão 1.7.*x* ou versões posteriores do AWS Encryption SDK for Java. Para ver um exemplo completo, consulte [DiscoveryDecryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)
Para instanciar um provedor de chave mestra no modo estrito para criptografar, este exemplo usa o método `Builder.buildStrict()`. Para instanciar um provedor de chave mestra no modo de descoberta para descriptografar ele usa o método `Builder.buildDiscovery()`. O `Builder.buildDiscovery()` método usa um `DiscoveryFilter` que limita o AWS Encryption SDK to AWS KMS keys na AWS partição e nas contas especificadas.
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your Conta da AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
Este exemplo representa o código em uma aplicação que usa a versão 1.7.*x* ou versões posteriores do AWS Encryption SDK for Python . Para obter um exemplo completo, consulte: [discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py).
Para criar um provedor de chave mestra no modo estrito para criptografar, este exemplo usa o método `StrictAwsKmsMasterKeyProvider`. Para criar um provedor de chave mestra no modo de descoberta para descriptografia, ele usa `DiscoveryAwsKmsMasterKeyProvider` um `DiscoveryFilter` que limita o AWS Encryption SDK to AWS KMS keys na AWS partição e nas contas especificadas.
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your Conta da AWS.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
Este exemplo mostra como criptografar e descriptografar usando a versão 1.7 do Encryption AWS CLI. *x* ou mais tarde. A partir da versão 1.7.*x*, o parâmetro `--wrapping-keys` passou a ser necessário ao criptografar e descriptografar. O parâmetro `--wrapping-keys` é compatível com o modo estrito e o modo de descoberta. Para obter exemplos completos, consulte [Exemplos da CLI AWS de criptografia](crypto-cli-examples.md).
Ao criptografar, este exemplo especifica uma chave de encapsulamento, que é obrigatória. Ao descriptografar, ele escolhe explicitamente o *modo de descoberta* usando o atributo `discovery` do parâmetro `--wrapping-keys` com um valor definido como `true`.
Para limitar as chaves de encapsulamento que AWS Encryption SDK podem ser usadas no modo de descoberta àquelas em particular Contas da AWS, este exemplo usa os `discovery-account` atributos `discovery-partition` e do `--wrapping-keys` parâmetro. Esses atributos opcionais são válidos somente quando o atributo `discovery` for definido como `true`. Você deve usar os atributos `discovery-partition` e `discovery-account` juntos. Nenhum deles é válido sozinho.
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
# Atualizando AWS KMS chaveiros
Os AWS KMS chaveiros do [AWS Encryption SDK for C](c-language.md), do [AWS Encryption SDK para o.NET](dot-net.md) e do [AWS Encryption SDK para JavaScript](javascript.md)oferecem suporte [às melhores práticas](best-practices.md), permitindo que você especifique chaves de agrupamento ao criptografar e descriptografar. Se você criar um [token de autenticação de descoberta do AWS KMS](use-kms-keyring.md#kms-keyring-discovery), você o fará de maneira explícita.
**nota**
A versão mais antiga do AWS Encryption SDK para.NET é a versão 3.0. *x.* Todas as versões do AWS Encryption SDK para.NET oferecem suporte às melhores práticas de segurança introduzidas na versão 2.0. *x* do AWS Encryption SDK. É possível atualizar com segurança para a versão mais recente sem fazer alterações no código ou nos dados.
Quando você atualiza para o mais recente 1. Na versão *x* do AWS Encryption SDK, você pode usar um [filtro de descoberta](use-kms-keyring.md#kms-keyring-discovery) para limitar as chaves de agrupamento que um chaveiro de [AWS KMS descoberta ou um chaveiro](use-kms-keyring.md#kms-keyring-discovery) de [descoberta AWS KMS regional](use-kms-keyring.md#kms-keyring-regional) usa ao descriptografar para aquelas em particular. Contas da AWS Filtrar um chaveiro de descoberta é uma prática AWS Encryption SDK [recomendada](best-practices.md).
Os exemplos nesta seção mostram como adicionar o filtro de descoberta a um token de autenticação de descoberta regional do AWS KMS .
**Saiba mais sobre migração**
Para todos os AWS Encryption SDK usuários, saiba como definir sua política de compromisso em[Como definir sua política de compromisso](migrate-commitment-policy.md).
Para usuários da CLI de AWS criptografia e AWS Encryption SDK for Java AWS Encryption SDK for Python, saiba mais sobre uma atualização necessária para os provedores de chaves mestras em. [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md)
Você pode ter um código como o seguinte na aplicação. Este exemplo cria um token de autenticação de descoberta regional do AWS KMS que só pode usar chaves de encapsulamento na região Oeste dos EUA (Oregon) (us-west-2). Este exemplo representa o código em AWS Encryption SDK versões anteriores à 1.7. *x.* No entanto, ele ainda é válido nas versões 1.7*x* e posteriores.
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
A partir da versão 1.7. *x*, você pode adicionar um filtro de descoberta a qualquer chaveiro de AWS KMS descoberta. Esse filtro de descoberta limita o AWS KMS keys que eles AWS Encryption SDK podem usar para decodificação àqueles na partição e nas contas especificadas. Antes de usar esse código, altere a partição, se necessário, e substitua a conta IDs de exemplo por outras válidas.
------
#### [ C ]
Para obter um exemplo completo, consulte: [kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp).
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
Para obter um exemplo completo, consulte: [kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts).
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# Como definir sua política de compromisso
O [confirmação de chave](concepts.md#key-commitment) assegura que seus dados criptografados sempre sejam descriptografados para o mesmo texto simples. Para fornecer essa propriedade de segurança, começando na versão 1.7. *x*, o AWS Encryption SDK usa novos [conjuntos de algoritmos](supported-algorithms.md) com comprometimento fundamental. Para determinar se seus dados são criptografados e descriptografados com confirmação de chave, use a definição de configuração da [política de compromisso](concepts.md#commitment-policy). Criptografar e descriptografar dados com [confirmação de chave](best-practices.md) é uma prática recomendada do AWS Encryption SDK .
Definir uma política de compromisso é uma parte importante da segunda etapa do processo de migração — migrar da última 1. versões *x* das AWS Encryption SDK duas versões 2.0. *x* e mais tarde. Após definir e alterar sua política de compromisso, certifique-se de testar a aplicação minuciosamente antes de implantá-la em produção. Para obter orientação sobre migração, consulte [Como migrar e implantar o AWS Encryption SDK](migration-guide.md).
A configuração da política de compromisso tem três valores válidos nas versões 2.0. *x* posteriores. Nas versões 1.*x* mais recentes (a partir da versão 1.7.*x*), somente `ForbidEncryptAllowDecrypt` é válido.
+ `ForbidEncryptAllowDecrypt`— Eles AWS Encryption SDK não podem criptografar com comprometimento chave. Ele pode descriptografar textos cifrados criptografados com ou sem confirmação de chave.
Na mais recente versão 1.*x*, esse é o único valor válido. Isso garante que você não criptografe com confirmação de chave até que esteja totalmente preparado para descriptografar com confirmação de chave. Definir o valor explicitamente impede que sua política de compromisso seja alterada automaticamente para `require-encrypt-require-decrypt` quando você atualizar para as versões 2.0.*x* ou posteriores. Em vez disso, você pode [migrar sua política de compromisso](#migrate-commitment-policy) em etapas.
+ `RequireEncryptAllowDecrypt`— AWS Encryption SDK Sempre criptografa com comprometimento fundamental. Ele pode descriptografar textos cifrados criptografados com ou sem confirmação de chave. Esse valor foi adicionado na versão 2.0.*x.*.
+ `RequireEncryptRequireDecrypt`— AWS Encryption SDK Sempre criptografa e descriptografa com comprometimento fundamental. Esse valor foi adicionado na versão 2.0.*x.*. É o valor padrão em versões 2.0.*x.* e posteriores.
Na versão 1.*x* mais recente, o único valor de política de compromisso válido é `ForbidEncryptAllowDecrypt`. Depois de migrar para a versão 2.0. *x* ou posterior, você pode [alterar sua política de compromisso em etapas](migration-guide.md) conforme estiver pronto. Não atualize sua política de compromisso `RequireEncryptRequireDecrypt` até ter certeza de que não tem nenhuma mensagem criptografada sem o confirmação de chave.
Esses exemplos mostram como definir sua política de compromisso na última versão 1.*x* e nas versões 2.0.*x* posteriores. A técnica depende da sua linguagem de programação.
**Saiba mais sobre migração**
Para AWS Encryption SDK for Java, AWS Encryption SDK for Python, e a CLI de AWS criptografia, saiba mais sobre as mudanças necessárias nos provedores de chaves mestras em. [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md)
Para AWS Encryption SDK for C e AWS Encryption SDK para JavaScript, saiba mais sobre uma atualização opcional dos chaveiros em[Atualizando AWS KMS chaveiros](migrate-keyrings-v2.md).
## Como definir sua política de compromisso
A técnica que você usa para definir sua política de compromisso difere um pouco em cada implementação de linguagem. Esses exemplos .mostram a você como fazer isso. Antes de alterar sua política de compromisso, revise a abordagem de vários estágios em [Como migrar e implantar](migration-guide.md).
------
#### [ C ]
A partir da versão 1.7. *x* do AWS Encryption SDK for C, você usa a `aws_cryptosdk_session_set_commitment_policy` função para definir a política de compromisso em suas sessões de criptografia e descriptografia. A política de compromisso que você define se aplica a todas as operações de criptografia e descriptografia chamadas na sua sessão.
As funções `aws_cryptosdk_session_new_from_keyring` e `aws_cryptosdk_session_new_from_cmm` foram descontinuadas na versão 1.7.*x* e foram removidas na versão 2.0.*x.*. Essas funções foram substituídas pelas funções `aws_cryptosdk_session_new_from_keyring_2` e `aws_cryptosdk_session_new_from_cmm_2` que retornam uma sessão.
Ao usar `aws_cryptosdk_session_new_from_keyring_2` e `aws_cryptosdk_session_new_from_cmm_2` na versão 1.*x* mais recentes, você deve chamar a função `aws_cryptosdk_session_set_commitment_policy` com o valor da política de compromisso `COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT`. Nas versões 2.0.*x* e posteriores, chamar essa função é opcional, e ela aceita todos os valores válidos. A política de compromisso padrão para as versões 2.0. *x* e posteriores é `COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Para obter um exemplo completo, consulte [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp).
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
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);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
O `require-encrypt-require-decrypt` valor é a política de compromisso padrão em todas as versões do AWS Encryption SDK para.NET. Você pode definir isso explicitamente como uma prática recomendadas, mas isso não é necessário. No entanto, se você estiver usando o for.NET AWS Encryption SDK para descriptografar texto cifrado que foi criptografado por outra implementação de linguagem do AWS Encryption SDK sem compromisso de chave, você precisará alterar o valor da política de compromisso para ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Caso contrário, ocorrerá uma falha na tentativa de descriptografar o texto cifrado.
No AWS Encryption SDK para.NET, você define a política de compromisso em uma instância do AWS Encryption SDK. Instancie um `AwsEncryptionSdkConfig` objeto com um `CommitmentPolicy` parâmetro e use o objeto de configuração para criar a AWS Encryption SDK instância. Em seguida, chame os `Decrypt()` métodos `Encrypt()` e da AWS Encryption SDK instância configurada.
Este exemplo define a política de compromisso como `require-encrypt-allow-decrypt`.
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
Para definir uma política de compromisso na CLI de AWS criptografia, use o `--commitment-policy` parâmetro. Esse parâmetro foi apresentado na versão 1.8.*x.*.
No versão 1.*x* mais recente, quando você usa o parâmetro `--wrapping-keys` em um comando `--encrypt`ou `--decrypt`, é necessário um parâmetro `--commitment-policy` com o valor `forbid-encrypt-allow-decrypt`. Caso contrário, o parâmetro `--commitment-policy` será inválido.
Nas versões 2.1.*x* e posteriores, o parâmetro `--commitment-policy` é opcional e usa como padrão o valor `require-encrypt-require-decrypt`, que não criptografará nem descriptografará nenhum texto cifrado criptografado sem confirmação de chave. No entanto, recomendamos definir a política de compromisso de forma explícita em todas as chamadas de criptografia e descriptografia, para ajudar na manutenção e na solução de problemas.
Este exemplo define a política de compromisso como . Ele também usa o parâmetro `--wrapping-keys`, que substituiu o parâmetro `--master-keys` a partir da versão 1.8.*x.*. Para obter detalhes, consulte [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md). Para obter exemplos completos, consulte [Exemplos da CLI AWS de criptografia](crypto-cli-examples.md).
```
\\ 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
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
A partir da versão 1.7. *x* do AWS Encryption SDK for Java, você define a política de compromisso em sua instância do `AwsCrypto` objeto que representa o AWS Encryption SDK cliente. Essa definição política de compromisso se aplica a todas as operações de criptografia e descriptografia chamadas nesse cliente.
O `AwsCrypto()` construtor está obsoleto na última versão 1. As versões *x* do AWS Encryption SDK for Java e são removidas na versão 2.0. *x.* Ele foi substituído por uma nova classe `Builder`, um método `Builder.withCommitmentPolicy()` e pelo tipo enumerado `CommitmentPolicy`.
Nas versões 1.*x* mais recentes, a classe `Builder` requer o método `Builder.withCommitmentPolicy()` e o argumento`CommitmentPolicy.ForbidEncryptAllowDecrypt`. A partir da versão 2.0.*x*, o método `Builder.withCommitmentPolicy()` é opcional. O valor padrão é `CommitmentPolicy.RequireEncryptRequireDecrypt`.
Para ver um exemplo completo, consulte [SetCommitmentPolicyExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
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.
Nas versões 1.*x* mais recentes, a função `buildClient` requer o argumento `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`. A partir da versão 2.0.*x*, o argumento da política de compromisso é opcional, e o valor padrão é `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
O código para Node.js e o navegador são idênticos para essa finalidade, exceto que o navegador precisa de uma instrução para definir as credenciais.
O exemplo a seguir criptografa os dados com um AWS KMS chaveiro. A nova função `buildClient` define a política de compromisso como`FORBID_ENCRYPT_ALLOW_DECRYPT`, o valor padrão nas versões 1.*x.* mais recentes. A funções `encrypt` e `decrypt` atualizadas retornadas por `buildClient` reforçam a política de compromisso que você definiu.
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
A partir da versão 1.7. *x* do AWS Encryption SDK for Python, você define a política de compromisso em sua instância de`EncryptionSDKClient`, um novo objeto que representa o AWS Encryption SDK cliente. A política de compromisso que você define se aplica a todas as chamadas `encrypt` e `decrypt` que usam essa instância do cliente.
Nas versões 1.*x* mais recentes, o construtor `EncryptionSDKClient` requer o valor enumerado `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`. A partir da versão 2.0.*x*, o argumento da política de compromisso é opcional, e o valor padrão é `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Este exemplo usa o novo construtor`EncryptionSDKClient` e define a política de compromisso como o valor padrão de 1.7.*x*. O construtor instancia um cliente que representa o AWS Encryption SDK. Quando você chama os métodos `encrypt`,`decrypt` ou `stream` desse cliente, eles aplicam a política de compromisso que você definiu. Esse exemplo também usa o novo construtor da `StrictAwsKmsMasterKeyProvider` classe, que especifica AWS KMS keys quando criptografar e descriptografar.
Para obter um exemplo completo, consulte [set\$1commitment.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py).
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
O `require-encrypt-require-decrypt` valor é a política de compromisso padrão em todas as versões do AWS Encryption SDK for Rust. Você pode definir isso explicitamente como uma prática recomendadas, mas isso não é necessário. No entanto, se você estiver usando o for Rust AWS Encryption SDK para descriptografar texto cifrado que foi criptografado por outra implementação de linguagem do AWS Encryption SDK sem compromisso de chave, você precisará alterar o valor da política de compromisso para ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Caso contrário, ocorrerá uma falha na tentativa de descriptografar o texto cifrado.
No AWS Encryption SDK for Rust, você define a política de compromisso em uma instância do AWS Encryption SDK. Instancie um `AwsEncryptionSdkConfig` objeto com um `comitment_policy` parâmetro e use o objeto de configuração para criar a AWS Encryption SDK instância. Em seguida, chame os `Decrypt()` métodos `Encrypt()` e da AWS Encryption SDK instância configurada.
Este exemplo define a política de compromisso como `forbid-encrypt-allow-decrypt`.
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
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()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
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?;
// Decrypt your ciphertext
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?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"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",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# Solução de problemas de migração para as versões mais recentes
Antes de atualizar seu aplicativo para a versão 2.0. *x* ou posterior do AWS Encryption SDK, atualize para a última 1. versão *x* do AWS Encryption SDK e implante-a completamente. Isso ajudará você a evitar a maioria dos erros que pode encontrar ao atualizar para as versões 2.0.*x* e posteriores. Para obter orientações detalhadas, incluindo exemplos, consulte [Migrando seu AWS Encryption SDK](migration.md).
**Importante**
Verifique se a sua versão 1.*x* mais recente é a versão 1.7.*x* ou versão posterior do AWS Encryption SDK.
**nota**
**AWS CLI de criptografia**: referências neste guia à versão 1.7. *x* do AWS Encryption SDK se aplica à versão 1.8. *x* da CLI AWS de criptografia. Referências neste guia para a versão 2.0. *x* do AWS Encryption SDK se aplica a 2.1. *x* da CLI AWS de criptografia.
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.
Este tópico foi criado para ajudar você a reconhecer e solucionar os erros mais comuns que pode encontrar.
**Topics**
+ [Objetos descontinuados ou removidos](#deprecated-removed)
+ [Conflito de configuração: política de compromisso e pacote de algoritmos](#configuration-conflict_1)
+ [Conflito de configuração: política de compromisso e texto cifrado](#configuration-conflict_2)
+ [Falha na validação do confirmação de chave](#commitment-failed)
+ [Outras falhas de criptografia](#encrypt-failed)
+ [Outras falhas de decriptografia](#decrypt-failed)
+ [Considerações sobre reversão](#migration-rollback)
## Objetos descontinuados ou removidos
A versão 2.0.*x* inclui várias alterações importantes, incluindo a remoção de construtores, métodos, funções e classes herdados que foram descontinuados na versão 1.7.*x.*. Para evitar erros do compilador, erros de importação, erros de sintaxe e erros de símbolo não encontrado (dependendo da sua linguagem de programação), atualize primeiro para a mais recente 1. versão *x* do AWS Encryption SDK para sua linguagem de programação. (Deve ser a versão 1.7.*x* ou posterior) Ao usar a versão 1.*x* mais recente, você pode começar a usar os elementos de substituição antes que os símbolos originais sejam removidos.
Se precisar atualizar para a versão 2.0. *x* ou posterior imediatamente, [consulte o changelog](about-versions.md) da sua linguagem de programação e substitua os símbolos herdados pelos símbolos recomendados pelo changelog.
## Conflito de configuração: política de compromisso e pacote de algoritmos
Se você especificar um pacote de algoritmos que entre em conflito com sua [política de compromisso](concepts.md#commitment-policy), a chamada para criptografar falhará com um erro de *conflito de configuração*.
Para evitar esse tipo de erro, não especifique um pacote de algoritmos. Por padrão, o AWS Encryption SDK escolhe o algoritmo mais seguro que seja compatível com sua política de compromisso. No entanto, se você precisar especificar um pacote de algoritmos, como um sem assinatura, certifique-se de escolher um pacote de algoritmos que seja compatível com sua política de compromisso.
| Política de compromisso | Pacotes de algoritmos compatíveis |
| --- | --- |
| ForbidEncryptAllowDecrypt | Qualquer pacote de algoritmos *sem* confirmação de chave, como:AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384 ([03 78](algorithms-reference.md)) (com assinatura) `AES_256_GCM_IV12_TAG16_HKDF_SHA256` ([01 78](algorithms-reference.md)) (sem assinatura) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | Qualquer pacote de algoritmos *com* confirmação de chave, como:AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384 ([05 78](algorithms-reference.md)) (com assinatura) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY` ([04 78](algorithms-reference.md)) (sem assinatura) |
Se você encontrar esse erro sem ter especificado um pacote de algoritmos, o pacote de algoritmos conflitante pode ter sido escolhido pelo seu [gerenciador de materiais criptográficos](concepts.md#crypt-materials-manager) (CMM). O CMM padrão não selecionará um pacote de algoritmos conflitantes, mas um CMM personalizado pode fazer isso. Para obter ajuda, consulte a documentação do seu CMM personalizado.
## Conflito de configuração: política de compromisso e texto cifrado
A [política de compromisso `RequireEncryptRequireDecrypt`](concepts.md#commitment-policy) não permite que o AWS Encryption SDK descriptografe uma mensagem que foi criptografada sem [confirmação de chave.](concepts.md#key-commitment) Se você pedir AWS Encryption SDK para decifrar uma mensagem sem o compromisso da chave, ele retornará um erro de conflito de *configuração*.
Para evitar esse erro, antes de definir a política de compromisso `RequireEncryptRequireDecrypt`, certifique-se de que todos os textos cifrados criptografados sem confirmação de chave sejam descriptografados e recriptografados com confirmação de chave ou sejam manipulados por uma aplicação diferente. Se você encontrar esse erro, poderá retornar um erro para o texto cifrado conflitante ou alterar temporariamente sua política de compromisso para `RequireEncryptAllowDecrypt`.
Se estiver encontrando esse erro porque você atualizou para a versão 2.0.*x* ou posterior a partir uma versão anterior à 1.7.*x* sem ter atualizado primeiro para a versão 1*x* mais recente (versão 1.7. *x* ou posterior), considere [reverter](#migration-rollback) para a versão 1.*x* mais recente e implantar essa versão em todos os hosts antes de atualizar para a versão 2.0.*x* ou posterior. Para obter ajuda, consulte [Como migrar e implantar o AWS Encryption SDK](migration-guide.md).
## Falha na validação do confirmação de chave
Ao descriptografar mensagens criptografadas com confirmação de chave, você pode receber uma mensagem de erro de *Falha na validação da confirmação de chave*. Isso indica que a chamada de descriptografia falhou porque a chave de dados em uma [mensagem criptografada](concepts.md#DEK) não é idêntica à chave de dados exclusiva da mensagem. Ao validar a chave de dados durante a descriptografia, a [confirmação de chave](concepts.md#key-commitment) protege você de descriptografar uma mensagem que pode resultar em mais de um texto simples.
Esse erro indica que a mensagem criptografada que você estava tentando descriptografar não foi retornada pelo AWS Encryption SDK. Pode ser uma mensagem criada manualmente ou o resultado de dados corrompidos. Se você encontrar esse erro, a aplicação poderá rejeitar a mensagem e prosseguir ou interromper o processamento de novas mensagens.
## Outras falhas de criptografia
A criptografia pode falhar por vários motivos. Você não pode usar um [token de autenticação de descoberta do AWS KMS](use-kms-keyring.md#kms-keyring-discovery) ou um [provedor de chave mestra em modo de descoberta](migrate-mkps-v2.md) para criptografar uma mensagem.
Certifique-se de especificar um provedor de token de autenticação ou de chave mestra com chaves de encapsulamento que deem [permissão para usar](use-kms-keyring.md#kms-keyring-permissions) para criptografia. Para obter ajuda com as permissões AWS KMS keys, consulte [Visualizar uma política de chaves](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html) e [Determinar o acesso a uma AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html) no *Guia do AWS Key Management Service desenvolvedor*.
## Outras falhas de decriptografia
Se sua tentativa de descriptografar uma mensagem criptografada falhar, isso significa que o AWS Encryption SDK não conseguiu (ou não pôde) descriptografar alguma das chaves de dados criptografadas na mensagem.
Se você usou um provedor de chaveiro ou chave mestra que especifica chaves de encapsulamento, ele AWS Encryption SDK usa somente as chaves de encapsulamento que você especificar. Verifique se está usando as chaves de encapsulamento pretendidas e se tem permissão `kms:Decrypt` em pelo menos uma das chaves de encapsulamento. Se você estiver usando AWS KMS keys, como alternativa, tente descriptografar a mensagem com um [chaveiro de AWS KMS descoberta ou um provedor de chave](use-kms-keyring.md#kms-keyring-discovery) [mestra](migrate-mkps-v2.md) no modo de descoberta. Se a operação for bem-sucedida, antes de retornar o texto simples, verifique se a chave usada para descriptografar a mensagem é confiável.
## Considerações sobre reversão
Se a aplicação não conseguir criptografar ou descriptografar dados, geralmente, é possível resolver o problema atualizando os símbolos de código, os tokens de autenticação, os provedores de chaves mestras ou a [política de compromisso.](concepts.md#commitment-policy) No entanto, em alguns casos, você pode decidir que é melhor reverter a aplicação para uma versão anterior do AWS Encryption SDK.
Se você precisar reverter, faça isso com cuidado. Versões AWS Encryption SDK anteriores à 1.7. *x* [não pode decifrar texto cifrado criptografado com comprometimento de chave.](concepts.md#key-commitment)
+ Geralmente, é seguro reverter da versão 1.*x* mais recente para uma versão anterior do AWS Encryption SDK . Talvez seja necessário desfazer as alterações feitas no código para usar símbolos e objetos que não são compatíveis com as versões anteriores.
+ Depois de começar a criptografar com confirmação de chave (definindo sua política de compromisso como `RequireEncryptAllowDecrypt`) na versão 2.0.*x* ou posterior, você poderá reverter para a versão 1.7.*x*, mas não para alguma versão anterior a ela. Versões AWS Encryption SDK anteriores à 1.7. *x* [não pode decifrar texto cifrado criptografado com comprometimento de chave.](concepts.md#key-commitment)
Se você acidentalmente ativar a criptografia com confirmação de chave antes de que todos os hosts possam descriptografar com confirmação de chave, talvez seja melhor continuar com a implantação em vez de revertê-la. Se as mensagens forem transitórias ou puderem ser descartadas com segurança, considere fazer uma reversão com perda de mensagens. Se for necessária uma reversão, considere criar uma ferramenta que descriptografe e recriptografe todas as mensagens.