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. 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 aplicativos e scripts que usam a AWS Encryption SDK for JavaAWS Encryption SDK for Python, e a AWS criptografia CLI. 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 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. 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 válido para representar um AWS KMS key . Ao criar um provedor de chave mestra para decodificação, você deve usar uma chave. ARN

Saiba mais sobre migração

Para todos os AWS Encryption SDK usuários, saiba como definir sua política de compromisso emComo definir sua política de compromisso.

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 emAtualizar tokens de autenticação do AWS KMS.

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. Os provedores de chaves mestras obsoletas podem descriptografar dados usando qualquer uma 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.

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.

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_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 CLI versão 1.1.7 ou anterior da AWS Criptografia.

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 AWS criptografia CLI 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 da AWS Criptografia. CLI x ou mais tarde. 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 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 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 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.

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_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 da AWS Criptografia. 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 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 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 .