Configurar o AWS Encryption SDK - AWS Encryption SDK

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á.

Configurar o AWS Encryption SDK

OAWS Encryption SDKfoi projetado para ser fácil de usar. Embora oAWS Encryption SDKtem várias opções de configuração, os valores padrão são cuidadosamente escolhidos para serem práticos e seguros para a maioria das aplicações. No entanto, talvez seja necessário ajustar sua configuração para melhorar o desempenho ou incluir um recurso personalizado em seu design.

Ao configurar sua implementação, revise oAWS Encryption SDK práticas recomendadase implemente o máximo que puder.

Selecione uma linguagem de programação

OAWS Encryption SDKestá disponível em várioslinguagens de programação. As implementações de linguagem são projetadas para serem totalmente interoperáveis e oferecer os mesmos recursos, embora possam ser implementadas de maneiras diferentes. Normalmente, você usa a biblioteca que é compatível com seu aplicativo. No entanto, você pode selecionar uma linguagem de programação para uma implementação específica. Por exemplo, se você preferir trabalhar comchaveiros, você pode escolher oAWS Encryption SDK for Cou oAWS Encryption SDK para JavaScript.

Selecionar chaves de empacotamento

OAWS Encryption SDKO gera uma chave de dados simétricas exclusiva para criptografar cada mensagem. A menos que você esteja usandoarmazenamento em cache de chaves de dados, você não precisa configurar, gerenciar nem usar as chaves de dados. OAWS Encryption SDKfaz isso por você.

No entanto, você deve selecionar uma ou mais chaves de empacotamento para criptografar cada chave de dados. OAWS Encryption SDKsuporta chaves simétricas AES e chaves assimétricas RSA em tamanhos diferentes. Ele também suportaAWS Key Management Service(AWS KMS) criptografia simétricaAWS KMS keys. Você é responsável pela segurança e durabilidade de suas chaves de empacotamento, por isso recomendamos que você use uma chave de criptografia em um módulo de segurança de hardware ou em um serviço de infraestrutura de chaves, comoAWS KMS.

Para especificar suas chaves de empacotamento para criptografia e descriptografia, você usa um chaveiro (C e JavaScript) ou um provedor de chave mestra (Java, Python,AWSCriptografia (CLI). Você pode especificar uma chave de empacotamento ou várias chaves de encapsulamento do mesmo tipo ou de tipos diferentes. Se você usar várias chaves de empacotamento para empacotar uma chave de dados, cada chave de empacotamento criptografará uma cópia da mesma chave de dados. As chaves de dados criptografadas (uma por chave de empacotamento) são armazenadas com os dados criptografados na mensagem criptografada que oAWS Encryption SDKRetorna. Para descriptografar os dados, oAWS Encryption SDKdeve primeiro usar uma das suas chaves de empacotamento para descriptografar uma chave de dados criptografada.

Para especificar umAWS KMS keyem um provedor de chaveiro ou chave mestra, use um suporteAWS KMSIdentificador da chave. Para obter detalhes sobre os identificadores de chave de umAWS KMSchave, vejaIdentificadores de chavenaAWS Key Management ServiceGuia do desenvolvedor do.

  • Ao criptografar com oAWS Encryption SDK for Java,AWS Encryption SDK para JavaScript,AWS Encryption SDK for Python, ou oAWSCLI de criptografia, você pode usar qualquer identificador de chave válido (ID de chave, ARN de chave, nome de alias ou ARN de alias) para uma chave do KMS. Ao criptografar com oAWS Encryption SDK for C, você só pode usar um ID de chave ou ARN de chave.

    Se você especificar um nome de alias ou ARN de alias para uma chave do KMS ao criptografar, oAWS Encryption SDKsalva o ARN da chave atualmente associado a esse alias; ele não salva o alias. As alterações no alias não afetam a chave KMS usada para descriptografar suas chaves de dados.

  • Ao descriptografar no modo estrito (onde você especifica chaves de encapsulamento específicas), você deve usar um ARN de chave para identificarAWS KMS keys. Esse requisito aplica-se a todas as implementações de linguagem do AWS Encryption SDK.

    Quando você criptografa com umAWS KMSchaveiro, oAWS Encryption SDKarmazena o ARN da chave doAWS KMS keynos metadados da chave de dados criptografada. Ao descriptografar no modo estrito, oAWS Encryption SDKverifica se o mesmo ARN de chave aparece no chaveiro (ou provedor de chave mestra) antes de tentar usar a chave de empacotamento para descriptografar a chave de dados criptografada. Se você usar um identificador de chave diferente, oAWS Encryption SDKnão reconhecerá nem usará oAWS KMS key, mesmo que os identificadores façam referência à mesma chave.

Para especificar umchave AES sem formataçãoou umPar de key pair RSA brutocomo uma chave de empacotamento em um chaveiro, você deve especificar um namespace e um nome. Em um provedor de chave mestra, oProvider IDé o equivalente ao namespace e aoKey IDé o equivalente ao nome. Ao descriptografar, você deve usar exatamente o mesmo namespace e nome para cada chave de empacotamento bruta usados na criptografia. Se você usar um namespace ou nome diferente, oAWS Encryption SDKnão reconhecerá nem usará a chave de empacotamento, mesmo que o material da chave seja o mesmo.

Usar várias regiõesAWS KMS keys

Você pode usarAWS Key Management Service(AWS KMS) Chaves de várias Regiões como chaves de encapsulamento noAWS Encryption SDK. Se você criptografar com uma chave de várias Regiões em umaRegião da AWS, você pode descriptografar usando uma chave multirregional relacionada em umRegião da AWS. O Support para chaves multirregionais foi introduzido na versão 2.3.xdoAWS Encryption SDKe versão 3.0.xdoAWSCLI de criptografia.

AWS KMSChaves de várias Regiões são um conjunto deAWS KMS keysno diferenteRegiões da AWSque têm o mesmo material de chave e ID de chave. Você pode usar essasrelacionadochaves como se fossem a mesma chave em diferentes regiões. As chaves multirregionais oferecem suporte a cenários comuns de recuperação e backup de desastres que exigem criptografia em uma região e descriptografia em outra região sem fazer uma chamada entre regiões paraAWS KMS. Para informações sobre chaves de várias Regiões, consulteUsar chaves de várias RegiõesnaAWS Key Management ServiceGuia do desenvolvedor do.

Para dar suporte a chaves de várias Regiões, oAWS Encryption SDKincluiAWS KMSChaveiros com reconhecimento de várias regiões e fornecedores de chaves mestras. O novo símbolo com reconhecimento de várias regiões em cada linguagem de programação oferece suporte a chaves de região única e de várias Regiões.

  • Para chaves de região única, o símbolo com reconhecimento de multirregião se comporta exatamente como o símbolo de região únicaAWS KMSprovedor de chaveiro e chave mestra. Ele tenta descriptografar texto cifrado somente com a chave de região única que criptografou os dados.

  • Para chaves multirregionais, o símbolo com reconhecimento de multirregião tenta descriptografar o texto cifrado com a mesma chave multirregional que criptografou os dados ou com a chave multirregional relacionada na região especificada.

Nos chaveiros com reconhecimento de várias regiões e provedores de chaves mestras que usam mais de uma chave KMS, você pode especificar várias chaves de região única e multirregional. No entanto, você pode especificar somente uma chave de cada conjunto de chaves de várias Regiões relacionadas. Se você especificar mais de um identificador de chave com o mesmo ID de chave, a chamada do construtor falhará.

Você também pode usar uma chave de várias Regiões com o padrão de Região únicaAWS KMSfornecedores de chaveiros e chaves mestras. No entanto, você deve usar a mesma chave multirregional na mesma região para criptografar e descriptografar. Os chaveiros de região única e os provedores de chaves mestras tentam descriptografar o texto cifrado somente com as chaves que criptografaram os dados.

Os exemplos a seguir mostram como criptografar e descriptografar dados usando chaves multirregionais e os novos chaveiros com reconhecimento de várias regiões e provedores de chaves mestras. Esses exemplos criptografam dados nous-east-1Regione e descriptografe os dados nous-west-2Região usando chaves de várias Regiões relacionadas em cada Região. Antes de executar esses exemplos, substitua o exemplo de ARN de chave de várias Regiões por um valor válido de seuConta da AWS.

C

Para criptografar com uma chave de várias Regiões, use aAws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()método para instanciar o chaveiro. Especifique uma chave de várias regiões.

Este exemplo simples não inclui umaContexto de criptografia do. Para ver um exemplo que usa um contexto de criptografia em C, consulteCriptografar e descriptografar strings.

Para obter um exemplo completo, consultekms_multi_region_keys.cppnaAWS Encryption SDK for CRepositório GitHub.

/* Encrypt with a multi-Region KMS key in us-east-1 */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Initialize a multi-Region keyring */ const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring); aws_cryptosdk_keyring_release(mrk_keyring); /* Encrypt the data * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Para criptografar com uma chave de várias regiões na região Leste dos EUA (Norte da Virgínia) (us-east-1), instancie umaCreateAwsKmsMrkKeyringInputobjeto com um identificador de chave para a chave multirregional e umAWS KMScliente para a região especificada. Então usar oCreateAwsKmsMrkKeyring()método para criar o chaveiro.

OCreateAwsKmsMrkKeyring()O método cria um chaveiro com exatamente uma chave multirregional. Para criptografar com várias chaves de empacotamento, incluindo uma chave multirregional, use oCreateAwsKmsMrkMultiKeyring()Método.

Para obter um exemplo completo, consulteAwsKmsMrkKeyringExample.csnaAWS Encryption SDKfor o repositório .NET GitHub.

//Encrypt with a multi-Region KMS key in us-east-1 Region // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Multi-Region keys have a distinctive key ID that begins with 'mrk' // Specify a multi-Region key in us-east-1 string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Create the keyring // You can specify the Region or get the Region from the key ARN var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1), KmsKeyId = mrkUSEast1 }; var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput); // Define the encryption context var encryptionContext = new Dictionary<string, string>() { {"purpose", "test"} }; // Encrypt your plaintext data. var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = mrkEncryptKeyring, EncryptionContext = encryptionContext }; var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Este exemplo criptografa ohello.txtarquivo sob uma chave de várias Regiões na região us-east-1. Como o exemplo especifica um ARN de chave com um elemento Região, este exemplo não usa oregiãoAtributo do--wrapping-keysparâmetro.

Quando o ID da chave de empacotamento não especifica uma região, você pode usar oregiãoAtributo do--wrapping-keyspara especificar a região, como--wrapping-keys key=$keyID region=us-east-1.

# Encrypt with a multi-Region KMS key in us-east-1 Region # To run this example, replace the fictitious key ARN with a valid value. $ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab $ aws-encryption-cli --encrypt \ --input hello.txt \ --wrapping-keys key=$mrkUSEast1 \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --output .
Java

Para criptografar com uma chave de várias Regiões, instancie umaAwsKmsMrkAwareMasterKeyProvidere especifique uma chave de várias Regiões.

Para obter um exemplo completo, consulteBasicMultiRegionKeyEncryptionExample.javanaAWS Encryption SDK for JavaRepositório GitHub.

//Encrypt with a multi-Region KMS key in us-east-1 Region // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // Multi-Region keys have a distinctive key ID that begins with 'mrk' // Specify a multi-Region key in us-east-1 final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Instantiate an AWS KMS master key provider in strict mode for multi-Region keys // Configure it to encrypt with the multi-Region key in us-east-1 final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider .builder() .buildStrict(mrkUSEast1); // Create an encryption context final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test"); // Encrypt your plaintext data final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData( kmsMrkProvider, encryptionContext, sourcePlaintext); byte[] ciphertext = encryptResult.getResult();
JavaScript Browser

Para criptografar com uma chave de várias Regiões, use abuildAwsKmsMrkAwareStrictMultiKeyringBrowser()método para criar o chaveiro e especificar uma chave de várias Regiões.

Para obter um exemplo completo, consultekms_multi_region_simple.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

/* Encrypt with a multi-Region KMS key in us-east-1 Region */ import { buildAwsKmsMrkAwareStrictMultiKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate an AWS KMS client * The AWS Encryption SDK para JavaScript gets the Region from the key ARN */ const clientProvider = (region: string) => new KMS({ region, credentials }) /* Specify a multi-Region key in us-east-1 */ const multiRegionUsEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Instantiate the keyring */ const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({ generatorKeyId: multiRegionUsEastKey, clientProvider, }) /* Set the encryption context */ const context = { purpose: 'test', } /* Test data to encrypt */ const cleartext = new Uint8Array([1, 2, 3, 4, 5]) /* Encrypt the data */ const { result } = await encrypt(encryptKeyring, cleartext, { encryptionContext: context, })
JavaScript Node.js

Para criptografar com uma chave de várias Regiões, use abuildAwsKmsMrkAwareStrictMultiKeyringNode()método para criar o chaveiro e especificar uma chave de várias Regiões.

Para obter um exemplo completo, consultekms_multi_region_simple.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

//Encrypt with a multi-Region KMS key in us-east-1 Region import { buildClient } from '@aws-crypto/client-node' /* Instantiate the AWS Encryption SDK client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) /* Test string to encrypt */ const cleartext = 'asdf' /* Multi-Region keys have a distinctive key ID that begins with 'mrk' * Specify a multi-Region key in us-east-1 */ const multiRegionUsEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Create an AWS KMS keyring */ const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({ generatorKeyId: multiRegionUsEastKey, }) /* Specify an encryption context */ const context = { purpose: 'test', } /* Create an encryption keyring */ const { result } = await encrypt(mrkEncryptKeyring, cleartext, { encryptionContext: context, })
Python

Para criptografar com umAWS KMSChave multirregional, use oMRKAwareStrictAwsKmsMasterKeyProvider()método e especifique uma chave de várias Regiões.

Para obter um exemplo completo, consultemrk_aware_kms_provider.pynaAWS Encryption SDK for PythonRepositório GitHub.

* Encrypt with a multi-Region KMS key in us-east-1 Region # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT) # Specify a multi-Region key in us-east-1 mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" # Use the multi-Region method to create the master key provider # in strict mode strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider( key_ids=[mrk_us_east_1] ) # Set the encryption context encryption_context = { "purpose": "test" } # Encrypt your plaintext data ciphertext, encrypt_header = client.encrypt( source=source_plaintext, encryption_context=encryption_context, key_provider=strict_mrk_key_provider )

Em seguida, mova seu texto cifrado para ous-west-2Região. Não é necessário criptografar novamente o texto cifrado.

Para descriptografar o texto cifrado no modo estrito nous-west-2Região, instancie o símbolo com reconhecimento de multirregião com a chave ARN da chave multirregional relacionada nous-west-2Região. Se você especificar o ARN da chave de uma chave multirregional relacionada em uma região diferente (incluindous-east-1, onde foi criptografado), o símbolo com reconhecimento de várias regiões fará uma chamada entre regiões para issoAWS KMS key.

Ao descriptografar no modo estrito, o símbolo com reconhecimento de várias regiões requer um ARN de chave. Ele aceita somente um ARN de chave de cada conjunto de chaves de várias Regiões relacionadas.

Antes de executar esses exemplos, substitua o exemplo de ARN de chave de várias Regiões por um valor válido de seuConta da AWS.

C

Para descriptografar no modo estrito com uma chave de várias Regiões, use aAws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()método para instanciar o chaveiro. Especifique a chave de várias Regiões relacionada na região local (us-west-2).

Para obter um exemplo completo, consultekms_multi_region_keys.cppnaAWS Encryption SDK for CRepositório GitHub.

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Initialize a multi-Region keyring */ const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring); aws_cryptosdk_session_set_commitment_policy(session, COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT); aws_cryptosdk_keyring_release(mrk_keyring); /* Decrypt the ciphertext * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Para descriptografar no modo estrito com uma única chave multirregional, use os mesmos construtores e métodos usados para montar a entrada e criar o chaveiro para criptografia. Instanciar umCreateAwsKmsMrkKeyringInputobjeto com a chave ARN de uma chave multirregional relacionada e umAWS KMScliente para a região Oeste dos EUA (Oregon) (us-west-2). Então usar oCreateAwsKmsMrkKeyring()método para criar um chaveiro multirregional com uma chave KMS multirregional.

Para obter um exemplo completo, consulteAwsKmsMrkKeyringExample.csnaAWS Encryption SDKfor o repositório .NET GitHub.

// Decrypt with a related multi-Region KMS key in us-west-2 Region // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Specify the key ARN of the multi-Region key in us-west-2 string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Instantiate the keyring input // You can specify the Region or get the Region from the key ARN var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2), KmsKeyId = mrkUSWest2 }; // Create the multi-Region keyring var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = mrkDecryptKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Para descriptografar com a chave multirregional relacionada na região us-west-2, use ochaveAtributo do--wrapping-keysparâmetro para especificar sua chave ARN.

# Decrypt with a related multi-Region KMS key in us-west-2 Region # To run this example, replace the fictitious key ARN with a valid value. $ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys key=$mrkUSWest2 \ --commitment-policy require-encrypt-require-decrypt \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output .
Java

Para descriptografar no modo estrito, instancie umAwsKmsMrkAwareMasterKeyProvidere especifique a chave de várias regiões relacionada na região local (us-west-2).

Para obter um exemplo completo, consulteBasicMultiRegionKeyEncryptionExample.javanaAWS Encryption SDK for JavaRepositório GitHub.

// Decrypt with a related multi-Region KMS key in us-west-2 Region // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field. String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Use the multi-Region method to create the master key provider // in strict mode AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder() .buildStrict(mrkUSWest2); // Decrypt your ciphertext CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData( kmsMrkProvider, ciphertext); byte[] decrypted = decryptResult.getResult();
JavaScript Browser

Para descriptografar no modo estrito, use obuildAwsKmsMrkAwareStrictMultiKeyringBrowser()método para criar o chaveiro e especificar a chave de várias regiões relacionada na região local (us-west-2).

Para obter um exemplo completo, consultekms_multi_region_simple.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ import { buildAwsKmsMrkAwareStrictMultiKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate an AWS KMS client * The AWS Encryption SDK para JavaScript gets the Region from the key ARN */ const clientProvider = (region: string) => new KMS({ region, credentials }) /* Specify a multi-Region key in us-west-2 */ const multiRegionUsWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Instantiate the keyring */ const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({ generatorKeyId: multiRegionUsWestKey, clientProvider, }) /* Decrypt the data */ const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)
JavaScript Node.js

Para descriptografar no modo estrito, use obuildAwsKmsMrkAwareStrictMultiKeyringNode()método para criar o chaveiro e especificar a chave de várias regiões relacionada na região local (us-west-2).

Para obter um exemplo completo, consultekms_multi_region_simple.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ import { buildClient } from '@aws-crypto/client-node' /* Instantiate the client const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) /* Multi-Region keys have a distinctive key ID that begins with 'mrk' * Specify a multi-Region key in us-east-1 */ const multiRegionUsWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Create an AWS KMS keyring */ const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({ generatorKeyId: multiRegionUsWestKey, }) /* Decrypt your ciphertext */ const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
Python

Para descriptografar no modo estrito, use oMRKAwareStrictAwsKmsMasterKeyProvider()método para criar o provedor de chave mestra. Especifique a chave de várias Regiões relacionada na região local (us-west-2).

Para obter um exemplo completo, consultemrk_aware_kms_provider.pynaAWS Encryption SDK for PythonRepositório GitHub.

# Decrypt with a related multi-Region KMS key in us-west-2 Region # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT) # Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" # Use the multi-Region method to create the master key provider # in strict mode strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider( key_ids=[mrk_us_west_2] ) # Decrypt your ciphertext plaintext, _ = client.decrypt( source=ciphertext, key_provider=strict_mrk_key_provider )

Você também pode descriptografar noModo descobertacomAWS KMSChaves de várias Regiões. Ao descriptografar no modo de descoberta, você não especifica nenhumaAWS KMS keys. (Para obter informações sobre uma única regiãoAWS KMSchaveiros de descoberta, vejaUsar um token de autenticação de descoberta do AWS KMS.)

Se você tiver criptografado com uma chave multirregional, o símbolo com reconhecimento de multirregião no modo de descoberta tentará descriptografar usando uma chave multirregional relacionada na região local. Se não existir nenhum, a chamada falhará. No modo de descoberta, oAWS Encryption SDKnão tentará fazer uma chamada entre regiões para a chave multirregional usada para criptografia.

nota

Se você usar um símbolo com reconhecimento de várias regiões no modo de descoberta para criptografar dados, a operação de criptografia falhará.

O exemplo a seguir mostra como descriptografar com o símbolo com reconhecimento de várias regiões no modo de descoberta. Porque você não especifica umAWS KMS key, oAWS Encryption SDKdeve obter a região de uma fonte diferente. Quando possível, especifique explicitamente a região local. Caso contrário, oAWS Encryption SDKobtém a região local da região configurada noAWSSDK para sua linguagem de programação.

Antes de executar esses exemplos, substitua o exemplo de ID da conta e ARN de chave de várias regiões por valores válidos de seuConta da AWS.

C

Para descriptografar no modo de descoberta com uma chave de várias regiões, use aAws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder()Método. Para especificar a região local, defina umClientConfiguratione especifique-o naAWS KMScliente.

Para obter um exemplo completo, consultekms_multi_region_keys.cppnaAWS Encryption SDK for CRepositório GitHub.

/* Decrypt in discovery mode with a multi-Region KMS key */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct a discovery filter for the account and partition. The * filter is optional, but it's a best practice that we recommend. */ const char *account_id = "111122223333"; const char *partition = "aws"; const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter = Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build(); /* Create an AWS KMS client in the desired region. */ const char *region = "us-west-2"; Aws::Client::ClientConfiguration client_config; client_config.region = region; const std::shared_ptr<Aws::KMS::KMSClient> kms_client = Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config); struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() .WithKmsClient(kms_client) .BuildDiscovery(region, discovery_filter); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring); aws_cryptosdk_keyring_release(mrk_keyring); commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT /* Decrypt the ciphertext * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Para criar um chaveiro de descoberta com reconhecimento de várias Regiões noAWS Encryption SDKfor .NETCreateAwsKmsMrkDiscoveryKeyringInputobjeto que leva umAWS KMScliente para um determinadoRegião da AWSe um filtro de descoberta opcional que limita as chaves do KMS a um determinadoAWSpartição e conta. Então ligue para oCreateAwsKmsMrkDiscoveryKeyring()método com o objeto de entrada. Para obter um exemplo completo, consulteAwsKmsMrkDiscoveryKeyringExample.csnaAWS Encryption SDKfor o repositório .NET GitHub.

Para criar um chaveiro de descoberta com reconhecimento de várias regiões para mais de umRegião da AWS, usar oCreateAwsKmsMrkDiscoveryMultiKeyring()método para criar um chaveiro múltiplo ou usarCreateAwsKmsMrkDiscoveryKeyring()para criar vários chaveiros de descoberta com reconhecimento de várias regiões e, em seguida, usar oCreateMultiKeyring()método para combiná-los em um chaveiro múltiplo.

Para obter um exemplo, consulteAwsKmsMrkDiscoveryMultiKeyringExample.cs.

// Decrypt in discovery mode with a multi-Region KMS key // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); List<string> account = new List<string> { "111122223333" }; // Instantiate the discovery filter DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter() { AccountIds = account, Partition = "aws" } // Create the keyring var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2), DiscoveryFilter = mrkDiscoveryFilter }; var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = mrkDiscoveryKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Para descriptografar no modo de descoberta, use odetecçãoAtributo do--wrapping-keysparâmetro. Oconta descobertaepartição)os atributos criam um filtro de descoberta que é opcional, mas recomendado.

Para especificar a região, esse comando inclui oregiãoAtributo do--wrapping-keysparâmetro.

# Decrypt in discovery mode with a multi-Region KMS key $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys discovery=true \ discovery-account=111122223333 \ discovery-partition=aws \ region=us-west-2 \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output .
Java

Para especificar a região local, use obuilder().withDiscoveryMrkRegionparâmetro. Caso contrário, oAWS Encryption SDKobtém a região local da região configurada noAWS SDK for Java.

Para obter um exemplo completo, consulteDiscoveryMultiRegionDecryptionExample.javanaAWS Encryption SDK for JavaRepositório GitHub.

// Decrypt in discovery mode with a multi-Region KMS key // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333); AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider .builder() .withDiscoveryMrkRegion(Region.US_WEST_2) .buildDiscovery(discoveryFilter); // Decrypt your ciphertext final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto .decryptData(mrkDiscoveryProvider, ciphertext);
JavaScript Browser

Para descriptografar no modo de descoberta com uma chave multirregional simétrica, use oAwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser()Método.

Para obter um exemplo completo, consultekms_multi_region_discovery.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

/* Decrypt in discovery mode with a multi-Region KMS key */ import { AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { decrypt } = buildClient() declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate the KMS client with an explicit Region */ const client = new KMS({ region: 'us-west-2', credentials }) /* Create a discovery filter */ const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] } /* Create an AWS KMS discovery keyring */ const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({ client, discoveryFilter, }) /* Decrypt the data */ const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)
JavaScript Node.js

Para descriptografar no modo de descoberta com uma chave multirregional simétrica, use oAwsKmsMrkAwareSymmetricDiscoveryKeyringNode()Método.

Para obter um exemplo completo, consultekms_multi_region_discovery.tsnaAWS Encryption SDK para JavaScriptRepositório GitHub.

/* Decrypt in discovery mode with a multi-Region KMS key */ import { AwsKmsMrkAwareSymmetricDiscoveryKeyringNode, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-node' /* Instantiate the Encryption SDK client const { decrypt } = buildClient() /* Instantiate the KMS client with an explicit Region */ const client = new KMS({ region: 'us-west-2' }) /* Create a discovery filter */ const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] } /* Create an AWS KMS discovery keyring */ const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({ client, discoveryFilter, }) /* Decrypt your ciphertext */ const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
Python

Para descriptografar no modo de descoberta com uma chave de várias regiões, use aMRKAwareDiscoveryAwsKmsMasterKeyProvider()Método.

Para obter um exemplo completo, consultemrk_aware_kms_provider.pynaAWS Encryption SDK for PythonRepositório GitHub.

# Decrypt in discovery mode with a multi-Region KMS key # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient() # Create the discovery filter and specify the region decrypt_kwargs = dict( discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"), discovery_region="us-west-2", ) # Use the multi-Region method to create the master key provider # in discovery mode mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs) # Decrypt your ciphertext plaintext, _ = client.decrypt( source=ciphertext, key_provider=mrk_discovery_key_provider )

Escolher um conjunto de algoritmos

OAWS Encryption SDKsuporta váriasAlgoritmos de criptografia simétricas e assimétricaspara criptografar suas chaves de dados sob as chaves de encapsulamento que você especificar. No entanto, quando usa essas chaves de dados para criptografar seus dados, oAWS Encryption SDKPadronizado como umconjunto de algoritmos recomendadoque usa o algoritmo AES-GCM comderivação da chave,assinaturas digitais, eCompromisso key. Embora o conjunto de algoritmos padrão provavelmente seja adequado para a maioria dos aplicativos, você pode escolher um conjunto de algoritmos alternativo. Por exemplo, alguns modelos de confiança seriam satisfeitos por um conjunto de algoritmos semassinaturas digitais. Para obter informações sobre os conjuntos de algoritmos que oAWS Encryption SDKsuportes, vejaPacotes de algoritmos compatíveis no AWS Encryption SDK.

Os exemplos a seguir mostram como selecionar um conjunto de algoritmos alternativo ao criptografar. Esses exemplos selecionam um conjunto de algoritmos AES-GCM recomendado com derivação e comprometimento de chaves, mas sem assinaturas digitais. Ao criptografar com um conjunto de algoritmos que não inclui assinaturas digitais, use o modo de descriptografia somente sem assinatura ao descriptografar. Esse modo, que falha se encontrar um texto cifrado assinado, é mais útil na decodificação de streaming.

C

Para especificar um conjunto de algoritmos alternativo naAWS Encryption SDK for C, você deve criar uma CMM explicitamente. Então usar oaws_cryptosdk_default_cmm_set_alg_idcom o CMM e o conjunto de algoritmos selecionado.

/* Specify an algorithm suite without signing */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); /* To set an alternate algorithm suite, create an cryptographic materials manager (CMM) explicitly */ struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); /* Specify the algorithm suite for the CMM */ aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY); /* Construct the session with the CMM, then release the CMM reference */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm); aws_cryptosdk_cmm_release(cmm); /* Encrypt the data Use aws_cryptosdk_session_process_full with non-streaming data */ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full( session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len)) { aws_cryptosdk_session_destroy(session); return AWS_OP_ERR; }

Ao descriptografar dados que foram criptografados sem assinaturas digitais, useAWS_CRYPTOSDK_DECRYPT_UNSIGNED. Isso faz com que a descriptografia falhe se encontrar texto cifrado assinado.

/* Decrypt unsigned streaming data */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); /* Create a session for decrypting with the AWS KMS keyring Then release the keyring reference */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); if (!session) { return AWS_OP_ERR; } /* Limit encrypted data keys */ aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1); /* Decrypt Use aws_cryptosdk_session_process_full with non-streaming data */ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)) { aws_cryptosdk_session_destroy(session); return AWS_OP_ERR; }
C# / .NET

Para especificar um conjunto de algoritmos alternativo naAWS Encryption SDKfor .NETAlgorithmSuiteIdpropriedade de umEncryptInputobjeto. OAWS Encryption SDKfor .NETconstantesque você pode usar para identificar seu conjunto de algoritmos preferido.

OAWS Encryption SDKpara .NET não tem um método para detectar texto cifrado assinado durante a decodificação de streaming porque essa biblioteca não suporta streaming de dados.

// Specify an algorithm suite without signing // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Create the keyring var keyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput); // Encrypt your plaintext data var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = keyring, AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY }; var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Ao criptografar ohello.txtarquivo, este exemplo usa o--algorithmparâmetro para especificar um conjunto de algoritmos sem assinaturas digitais.

# Specify an algorithm suite without signing # To run this example, replace the fictitious key ARN with a valid value. $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --encrypt \ --input hello.txt \ --wrapping-keys key=$keyArn \ --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt \ --output hello.txt.encrypted \ --decode

Ao descriptografar, este exemplo usa o--decrypt-unsignedparâmetro. Esse parâmetro é recomendado para garantir que você esteja descriptografando texto cifrado não assinado, especialmente com a CLI, que está sempre transmitindo entrada e saída.

# Decrypt unsigned streaming data # To run this example, replace the fictitious key ARN with a valid value. $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --decrypt-unsigned \ --input hello.txt.encrypted \ --wrapping-keys key=$keyArn \ --max-encrypted-data-keys 1 \ --commitment-policy require-encrypt-require-decrypt \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
Java

Para especificar um conjunto de algoritmos alternativo, use oAwsCrypto.builder().withEncryptionAlgorithm()Método. Este exemplo especifica um conjunto de algoritmos alternativo sem assinaturas digitais.

// Specify an algorithm suite without signing // Instantiate the client AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) .build(); String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a master key provider in strict mode KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder() .buildStrict(awsKmsKey); // Create an encryption context to identify this ciphertext Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming"); // Encrypt your plaintext data CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData( masterKeyProvider, sourcePlaintext, encryptionContext); byte[] ciphertext = encryptResult.getResult();

Ao transmitir dados para decodificação, use ocreateUnsignedMessageDecryptingStream()método para garantir que todo o texto cifrado que você está descriptografando não esteja assinado.

// Decrypt unsigned streaming data // Instantiate the client AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withMaxEncryptedDataKeys(1) .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); // Decrypt the encrypted message FileInputStream in = new FileInputStream(srcFile + ".encrypted"); CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in); // Return the plaintext data // Write the plaintext data to disk FileOutputStream out = new FileOutputStream(srcFile + ".decrypted"); IOUtils.copy(decryptingStream, out); decryptingStream.close();
JavaScript Browser

Para especificar um conjunto de algoritmos alternativo, use osuiteIdparâmetro com umAlgorithmSuiteIdentifierenumeração.

// Specify an algorithm suite without signing // Instantiate the client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Specify a KMS key const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a keyring with the KMS key const keyring = new KmsKeyringBrowser({ generatorKeyId }) // Encrypt your plaintext data const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Ao descriptografar, use o padrãodecryptMétodo.AWS Encryption SDK para JavaScriptno navegador não tem umdecrypt-unsignedmodo porque o navegador não suporta streaming.

// Decrypt unsigned streaming data // Instantiate the client const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Create a keyring with the same KMS key used to encrypt const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; const keyring = new KmsKeyringBrowser({ generatorKeyId }) // Decrypt the encrypted message const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)
JavaScript Node.js

Para especificar um conjunto de algoritmos alternativo, use osuiteIdparâmetro com umAlgorithmSuiteIdentifierenumeração.

// Specify an algorithm suite without signing // Instantiate the client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Specify a KMS key const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a keyring with the KMS key const keyring = new KmsKeyringNode({ generatorKeyId }) // Encrypt your plaintext data const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Ao descriptografar dados que foram criptografados sem assinaturas digitais, use decryptUnsignedMessageARN. Esse método falhará se encontrar texto cifrado assinado.

// Decrypt unsigned streaming data // Instantiate the client const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Create a keyring with the same KMS key used to encrypt const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; const keyring = new KmsKeyringNode({ generatorKeyId }) // Decrypt the encrypted message const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))
Python

Para especificar um algoritmo de criptografia alternativo, use aalgorithmparâmetro com umAlgorithmenumeração.

# Specify an algorithm suite without signing # Instantiate a client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, max_encrypted_data_keys=1) # 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 the plaintext using an alternate algorithm suite ciphertext, encrypted_message_header = client.encrypt( algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider )

Ao descriptografar mensagens que foram criptografadas sem assinaturas digitais, use odecrypt-unsignedmodo de streaming, especialmente ao descriptografar durante a transmissão.

# Decrypt unsigned streaming data # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, max_encrypted_data_keys=1) # 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] ) # Decrypt with decrypt-unsigned with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext: with client.stream(mode="decrypt-unsigned", source=ciphertext, key_provider=master_key_provider) as decryptor: for chunk in decryptor: plaintext.write(chunk) # Verify that the encryption context assert all( pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items() ) return ciphertext_filename, cycled_plaintext_filename

Limitar chaves de dados criptografadas

Você pode limitar o número de chaves de dados criptografadas em uma mensagem criptografada. Esse recurso de melhores práticas pode ajudá-lo a detectar um chaveiro mal configurado ao criptografar ou um texto cifrado malicioso ao descriptografar. Também evita chamadas desnecessárias, caras e potencialmente exaustivas para sua infraestrutura principal. Limitar as chaves de dados criptografadas é mais valioso quando você está descriptografando mensagens de uma fonte não confiável.

Embora a maioria das mensagens criptografadas tenha uma chave de dados criptografada para cada chave de empacotamento usada na criptografia, uma mensagem criptografada pode conter até 65.535 chaves de dados criptografadas. Um agente mal-intencionado pode criar uma mensagem criptografada com milhares de chaves de dados criptografadas, nenhuma das quais pode ser descriptografada. Como resultado, oAWS Encryption SDKtentaria descriptografar cada chave de dados criptografada até esgotar as chaves de dados criptografadas na mensagem.

Para limitar as chaves de dados criptografadas, use oMaxEncryptedDataKeysparâmetro. Esse parâmetro está disponível para todas as linguagens de programação suportadas a partir da versão 1.9.xe 2.2.xdoAWS Encryption SDK. É opcional e válido ao criptografar e descriptografar. Os exemplos a seguir decodificam dados que foram criptografados em três chaves de empacotamento diferentes. OMaxEncryptedDataKeyso valor é definido como 3.

C
/* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 }); /* Create a session */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); /* Limit encrypted data keys */ aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3); /* Decrypt */ size_t ciphertext_consumed_output; aws_cryptosdk_session_process(session, plaintext_output, plaintext_buf_sz_output, &plaintext_len_output, ciphertext_input, ciphertext_len_input, &ciphertext_consumed_output); assert(aws_cryptosdk_session_is_done(session)); assert(ciphertext_consumed == ciphertext_len);
C# / .NET

Para limitar as chaves de dados criptografadas naAWS Encryption SDKpara .NET, instancie um cliente para oAWS Encryption SDKpara .NET e defina seu opcionalMaxEncryptedDataKeysparâmetro ao valor desejado. Em seguida, ligue para oDecrypt()método no configuradoAWS Encryption SDKexemplo.

// Decrypt with limited data keys // Instantiate the material providers var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Configure the commitment policy on the AWS Encryption SDK instance var config = new AwsEncryptionSdkConfig { MaxEncryptedDataKeys = 3 }; var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config); // Create the keyring string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; var createKeyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = decryptKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI
# Decrypt with limited encrypted data keys $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \ --buffer \ --max-encrypted-data-keys 3 \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
Java
// Construct a client with limited encrypted data keys final AwsCrypto crypto = AwsCrypto.builder() .withMaxEncryptedDataKeys(3) .build(); // Create an AWS KMS master key provider final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder() .buildStrict(keyArn1, keyArn2, keyArn3); // Decrypt final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
JavaScript Browser
// Construct a client with limited encrypted data keys const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 }) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) // Create an AWS KMS keyring const keyring = new KmsKeyringBrowser({ clientProvider, keyIds: [keyArn1, keyArn2, keyArn3], }) // Decrypt const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
JavaScript Node.js
// Construct a client with limited encrypted data keys const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 }) // Create an AWS KMS keyring const keyring = new KmsKeyringBrowser({ keyIds: [keyArn1, keyArn2, keyArn3], }) // Decrypt const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
Python
# Instantiate a client with limited encrypted data keys client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3) # Create an AWS KMS master key provider master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider( key_ids=[key_arn1, key_arn2, key_arn3]) # Decrypt plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

Definindo uma política de compromisso

UMApolítica de compromissoé uma configuração que determina se seu aplicativo criptografa e descriptografa comCompromisso key. Criptografar e descriptografar com comprometimento fundamental é umaAWS Encryption SDKprática recomendada.

Definir e ajustar sua política de compromisso é uma etapa críticamigrandodas versões 1.7.xe mais cedo doAWS Encryption SDKpara a versão 2.0.xe depois. Essa progressão é explicada em detalhes notópico sobre migração.

O valor padrão da política de compromisso nas versões mais recentes doAWS Encryption SDK(começando na versão 2.0.x),RequireEncryptRequireDecrypt, é ideal para a maioria das situações. No entanto, se você precisar descriptografar o texto cifrado que foi criptografado sem o comprometimento da chave, talvez seja necessário alterar sua política de compromisso paraRequireEncryptAllowDecrypt. Para exemplos de como definir uma política de compromisso em cada linguagem de programação, consulteDefinindo sua política de compromisso.

Trabalhe com dados de streaming

Ao transmitir dados para decodificação, esteja ciente de que oAWS Encryption SDKretorna texto sem formatação descriptografado após a conclusão das verificações de integridade, mas antes que a assinatura digital seja verificada. Para garantir que você não retorne ou use texto sem formatação até que a assinatura seja verificada, recomendamos que você armazene o texto sem formatação transmitido até que todo o processo de descriptografia seja concluído.

Esse problema ocorre somente quando você está transmitindo texto cifrado para descriptografia e somente quando está usando um conjunto de algoritmos, como oconjunto de algoritmos padrão, que incluiassinaturas digitais.

Para facilitar o armazenamento em buffer, algunsAWS Encryption SDKimplementações de linguagem, comoAWS Encryption SDK para JavaScriptem Node.js, inclua um recurso de buffer como parte do método de descriptografia. OAWSA CLI de criptografia, que sempre transmite entrada e saída, introduziu um--bufferparâmetro nas versões 1.9.xe 2.2.x. Em outras implementações de linguagem, você pode usar os recursos de buffer existentes. (OAWS Encryption SDKpara .NET não suporta streaming.)

Se você estiver usando um conjunto de algoritmos sem assinaturas digitais, certifique-se de usar odecrypt-unsignedrecurso em cada implementação de linguagem. Esse recurso descriptografa o texto cifrado, mas falha se encontrar um texto cifrado assinado. Para obter detalhes, consulte Escolher um conjunto de algoritmos.

Chaves de dados em cache

Em geral, a reutilização de chaves de dados não é recomendada, mas aAWS Encryption SDKoferece umarmazenamento em cache de chaves de dadosopção que fornece reutilização limitada de chaves de dados. O cache de chaves de dados pode melhorar o desempenho de alguns aplicativos e reduzir as chamadas para sua infraestrutura de chaves. Antes de usar o cache de chaves de dados na produção, ajuste olimites de segurançae teste para ter certeza de que os benefícios superam as desvantagens de reutilizar chaves de dados.