Como atualizar provedores de chaves mestras do AWS KMS

Para migrar para a versão 1.x mais recente do AWS Encryption SDK, e, em seguida, para a versão 2.0.x ou posteriores, você deve substituir os provedores de chave mestra herdados do AWS KMS por provedores de chave mestra criados explicitamente no modo estrito ou no modo de descoberta. 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, o AWS Encryption SDK for Python e a CLI de criptografia da AWS. Os exemplos nesta seção mostrarão como atualizar seu código.

nota

Em Python, ative os avisos de obsolescência. Isso ajudará você a identificar as partes do código que precisa atualizar.

Se estiver usando uma chave mestra do AWS KMS (que não seja um provedor de chave mestra), você pode ignorar esta etapa. As chaves mestras do AWS KMS 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 ver um exemplo completo do código atualizado, consulte a seção Exemplos do repositório do GitHub para sua linguagem de programação. Além disso, esses exemplos normalmente usam ARNs de chave para representar AWS KMS keys. Ao criar um provedor de chave mestra para criptografia, você pode usar qualquer identificador de chave do AWS KMS válido para representar uma AWS KMS key. Ao criar um provedor de chave mestra para descriptografia, você deve usar um ARN de chave.

Saiba mais sobre migração

Todos os usuários do AWS Encryption SDK podem saber como definir sua política de compromisso em Como definir sua política de compromisso.

Usuários do AWS Encryption SDK for C e do AWS Encryption SDK para JavaScript podem saber mais sobre uma atualização opcional dos token de autenticação em Atualizar tokens de autenticação do AWS KMS.

Migração para o modo estrito

Depois de atualizar para a versão 1.x doAWS Encryption SDK, substitua seus provedores de chave mestra herdados 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 encapsulamento que você especificar. Provedores de chaves mestras obsoletas podem descriptografar dados usando qualquer AWS KMS key que criptografe uma chave de dados, inclusive AWS KMS keys em diferentes Contas da AWS e regiões.

Os provedores de chaves mestras no modo estrito foram introduzidos na versão 1.7.x do AWS Encryption SDK. 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 chaves mestras no modo estrito é uma prática recomendada do AWS Encryption SDK.

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 método KmsMasterKeyProvider.builder() para instanciar um provedor de chave mestra do AWS KMS que usa uma 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.

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 a chave de encapsulamento, mas o método Builder.buildStrict() 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 doAWS 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 AWS KMS key que criptografe uma chave de dados sem levar em conta a AWS KMS keys que você especificar.

Observe que KMSMasterKey não foi suspenso nem removido. Ao criptografar e descriptografar, ele usa somente a AWS KMS key que você especificar.

# 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_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 versões anteriores da CLI de criptografia AWS.

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 criptografia da AWS pode usar qualquer chave de encapsulamento 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.x ou versões posteriores da CLI de criptografia da AWS. Para obter exemplos completos, consulte Exemplos da CLI de criptografia da AWS.

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 recomendada do AWS Encryption SDK que garante que você use a chave de encapsulamento que pretende utilizar.

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 recomendada doAWS Encryption SDK usar o modo estrito para provedores de chaves mestras do AWS KMS, ou seja, especificar chaves de encapsulamento ao criptografar e descriptografar. Você deve sempre especificar as chaves de encapsulamento ao criptografar. Mas há situações em que não é viável especificar os ARNs de chave das AWS KMS keys para descriptografar. Por exemplo, se você estiver usando aliases para identificar as AWS KMS keys ao criptografar, perderá o benefício dos aliases se precisar listar os ARNs de chave 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 no Referência geral da AWS.

Os exemplos a seguir criam um provedor de chave mestra do AWS KMS no modo estrito para criptografar e um provedor de chave mestra do AWS KMS no modo de descoberta para descriptografar. 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 obter um exemplo completo, consulte: DiscoveryDecryptionExample.java.

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 método Builder.buildDiscovery() usa um DiscoveryFilter que limita o AWS Encryption SDK às AWS KMS keys presentes na partição nas contas da AWS 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_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 descriptografar, ele usa DiscoveryAwsKmsMasterKeyProvider com um DiscoveryFilter que limita o AWS Encryption SDK às AWS KMS keys presentes na partição e nas contas da AWS 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.x ou versões posteriores da CLI de criptografia da AWS. 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 de criptografia da AWS.

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 podem ser usadas peloAWS Encryption SDK no modo de descoberta àquelas presentes em Contas da AWS específicas, este exemplo usa os atributos discovery-partition e discovery-account do parâmetro --wrapping-keys. 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 .