Configurar o AWS Encryption SDK - AWS Encryption SDK
Seleção de uma linguagem de programaçãoSeleção de chaves de encapsulamentoUsar AWS KMS keys multirregionaisEscolher um pacote de algoritmoLimitar as chaves de dados criptografadasCriação de um filtro de descobertaComo definir uma política de compromissoTrabalhar com streaming de dadosArmazenamento em cache de chaves de dados

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

O AWS Encryption SDK foi projetado para ser fácil de usar. Embora AWS Encryption SDK tenha 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 a performance ou incluir um atributo personalizado em seu design.

Ao configurar sua implementação, analise as prática recomendadas do AWS Encryption SDK e as implemente o máximo possível.

Seleção de uma linguagem de programação

O AWS Encryption SDK está disponível em várias linguagens de programação. As implementações de linguagem são projetadas para serem totalmente interoperáveis e oferecer os mesmos atributos, embora possam ser implementadas de maneiras diferentes. Normalmente, você usa a biblioteca compatível com sua aplicação. No entanto, pode selecionar uma linguagem de programação para uma implementação específica. Por exemplo, se você preferir trabalhar com tokens de autenticação, pode escolher o AWS Encryption SDK for C ou o AWS Encryption SDK para JavaScript.

Seleção de chaves de encapsulamento

O AWS Encryption SDK gera uma chave de dados simétrica exclusiva para criptografar cada mensagem. A menos que você esteja usando o armazenamento em cache de chaves de dados, você não precisa configurar, gerenciar ou usar as chaves de dados. O AWS Encryption SDK faz isso por você.

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

Para especificar suas chaves de encapsulamento para criptografia e descriptografia, use um token de autenticação (C e JavaScript) ou um provedor de chave mestra (Java, Python, CLI de criptografia da AWS). É possível especificar uma chave de encapsulamento ou várias chaves de encapsulamento do mesmo tipo ou de tipos diferentes. Se você usar várias chaves de encapsulamento para empacotar uma chave de dados, cada chave de encapsulamento criptografará uma cópia da mesma chave de dados. As chaves de dados criptografadas (uma por chave de encapsulamento) são armazenadas com os dados criptografados na mensagem criptografada que o AWS Encryption SDK retorna. Para descriptografar os dados, o AWS Encryption SDK deve primeiro usar uma de suas chaves de encapsulamento para descriptografar uma chave de dados criptografada.

Para especificar uma AWS KMS key em um token de autenticação ou provedor de chave mestra, use um identificador de chave compatível com o AWS KMS. Para obter detalhes sobre os identificadores de chave de uma chave AWS KMS, consulte Identificadores de chave no Guia do desenvolvedor do AWS Key Management Service.

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

    Se você especificar um nome de alias ou ARN de alias para uma chave KMS ao criptografar, o AWS Encryption SDK salvará o ARN da chave atualmente associado a esse alias; ele não salvará o alias. As alterações no alias não afetam a chave do 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 identificar as AWS KMS keys. Esse requisito aplica-se a todas as implementações de linguagem do AWS Encryption SDK.

    Quando você criptografa com um token de autenticação do AWS KMS, o AWS Encryption SDK armazena o ARN de chave da AWS KMS key nos metadados da chave de dados criptografada. Ao descriptografar no modo estrito, o AWS Encryption SDK verifica se o mesmo ARN de chave aparece no token de autenticação (ou no provedor da chave mestra) antes de tentar usar a chave de encapsulamento para descriptografar a chave de dados criptografada. Se você usar um identificador de chave diferente, o AWS Encryption SDK não reconhecerá nem usará o AWS KMS key, mesmo que os identificadores se refiram à mesma chave.

Para especificar uma chave AES bruta ou um par de chaves RSA brutas como chave de agrupamento em um token de autenticação, você deve especificar um namespace e um nome. Em um provedor de chave mestra, o Provider ID é o equivalente do namespace e o Key ID é o equivalente do nome. Ao descriptografar, você deve usar exatamente o mesmo namespace e nome para cada chave de encapsulamento bruta que você usou ao criptografar. Se você usar um namespace ou nome diferente, o AWS Encryption SDK não reconhecerá nem usará a chave de encapsulamento, mesmo que o material da chave seja o mesmo.

Usar AWS KMS keys multirregionais

Você pode usar chaves multirregionais AWS Key Management Service (AWS KMS) como chaves de encapsulamento no.AWS Encryption SDK Se você criptografar com uma chave multirregional em uma Região da AWS, poderá descriptografar usando uma chave multirregional relacionada em outra Região da AWS. O suporte para chaves multirregionais foi introduzido na versão 2.3.x do AWS Encryption SDK e na versão 3.0. x da CLI de criptografia da AWS.

As chaves do AWS KMS multirregionais são um conjunto de AWS KMS keys em diferentes Regiões da AWS que têm o mesmo ID de chave e material de chave. É possível usar essas chaves relacionadas como se fossem a mesma chave em regiões diferentes. As chaves multirregionais oferecem suporte a cenários comuns de recuperação de desastres e backup que exigem criptografia em uma região e descriptografia em uma região diferente sem fazer uma chamada entre regiões para AWS KMS. Para obter mais informações sobre chaves multirregionais, consulte Usar chaves multirregionais no Guia do Desenvolvedor do AWS Key Management Service.

Para oferecer suporte a chaves multirregionais, o AWS Encryption SDK inclui tokens de autenticação compatíveis com várias regiões e fornecedores de chaves mestras do AWS KMS. O novo símbolo de reconhecimento de várias regiões em cada linguagem de programação é compatível com a chaves de região única e de várias regiões.

  • Para chaves de região única, o símbolo de reconhecimento de várias regiões se comporta da mesma forma que o token de autenticação de região única do AWS KMS e o provedor da chave mestra. Ele tenta descriptografar o texto cifrado somente com a chave de região única que criptografou os dados.

  • Para chaves multirregionais, o símbolo de reconhecimento de várias regiões 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 tokens de autenticação com reconhecimento de várias regiões e nos provedores de chaves mestras que usam mais de uma chave KMS, você pode especificar várias chaves de região única e multirregionais. No entanto, é possível 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 multirregional com tokens de autenticação e provedores de chaves mestras do AWS KMS padrões e de região única. No entanto, deve usar a mesma chave multirregional na mesma região para criptografar e descriptografar. Os tokens de autenticação 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 de tokens de autenticação e provedores de chaves mestras compatíveis com várias regiões. Esses exemplos criptografam dados na região us-east-1 e descriptografam os dados na região us-west-2 usando chaves multirregionais relacionadas em cada região. Antes de executar esses exemplos, substitua o exemplo de ARN de chave multirregional por um valor válido da sua Conta da AWS.

C

Para criptografar com uma chave multirregional, use o método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() para instanciar o token de autenticação. Especifique uma chave multirregional.

Esse exemplo simples não inclui um contexto de criptografia. Para obter um exemplo que usa um contexto de criptografia em C, consulte Criptografar e descriptografar strings.

Para ver um exemplo completo, consulte kms_multi_region_keys.cpp no repositório do AWS Encryption SDK for C no 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 multirregional na região Leste dos EUA (Norte da Virgínia) (us-east-1), instancie um objeto CreateAwsKmsMrkKeyringInput com um identificador de chave para a chave multirregional e um cliente AWS KMS para a região especificada. Em seguida, use o método CreateAwsKmsMrkKeyring() para criar o token de autenticação.

O método CreateAwsKmsMrkKeyring() cria um token de autenticação com exatamente uma chave multirregional. Para criptografar com várias chaves de encapsulamento, incluindo uma chave multirregional, use o método CreateAwsKmsMrkMultiKeyring().

Para ver um exemplo completo, consulte AwsKmsMrkKeyringExample.cs no repositório do AWS Encryption SDK para .NET no 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 o arquivo hello.txt com uma chave multirregional na região us-east-1. Como o exemplo especifica um ARN de chave que tem um elemento de região, esse exemplo não usa oatributo region do parâmetro --wrapping-keys.

Quando o ID da chave de encapsulamento não especifica uma região, você pode usar o atributo region de --wrapping-keys para 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 multirregional, instancie uma chave AwsKmsMrkAwareMasterKeyProvider e especifique uma chave multirregional.

Para ver um exemplo completo, consulte BasicMultiRegionKeyEncryptionExample.java no repositório do AWS Encryption SDK for Java no 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 mulirregional, use o método buildAwsKmsMrkAwareStrictMultiKeyringBrowser() para criar o token de autenticação e especificar uma chave multirregional.

Para ver um exemplo completo, consulte kms_multi_region_simple.ts no repositório do AWS Encryption SDK para JavaScript no 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 mulirregional, use o método buildAwsKmsMrkAwareStrictMultiKeyringNode() para criar o token de autenticação e especificar uma chave multirregional.

Para ver um exemplo completo, consulte kms_multi_region_simple.ts no repositório do AWS Encryption SDK para JavaScript no 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 uma chave AWS KMS multirregional, use o método MRKAwareStrictAwsKmsMasterKeyProvider() e especifique uma chave multirregional.

Para ver um exemplo completo, consulte mrk_aware_kms_provider.py no repositório do AWS Encryption SDK for Python no 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 a região us-west-2. Não é necessário recriptografar o texto cifrado.

Para descriptografar o texto cifrado no modo estrito na região us-west-2, instancie o símbolo de reconhecimento de várias regiões com o ARN da chave multirregional relacionada na região us-west-2. Se você especificar o ARN da chave de uma chave multirregional relacionada em uma região diferente (incluindo us-east-1), o símbolo compatível com várias regiões fará uma chamada entre regiões para essa AWS 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 multirregional por um valor válido da sua Conta da AWS.

C

Para descriptografar no modo estrito com uma chave multirregional, use o método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() para instanciar o token de autenticação. Especifique a chave multirregional relacionada na região local (us-west-2).

Para ver um exemplo completo, consulte kms_multi_region_keys.cpp no repositório do AWS Encryption SDK for C no 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 token de autenticação para criptografia. Instancie um objeto CreateAwsKmsMrkKeyringInput com o ARN de chave de uma chave multirregional relacionada e um cliente AWS KMS para a região Oeste dos EUA (Oregon) (us-west-2). Em seguida, use o método CreateAwsKmsMrkKeyring() para criar um token de autenticação multirregional com uma chave do KMS multirregional.

Para ver um exemplo completo, consulte AwsKmsMrkKeyringExample.cs no repositório do AWS Encryption SDK para .NET no 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 o atributo key do parâmetro --wrapping-keys para especificar o ARN da chave. 

# 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 uma AwsKmsMrkAwareMasterKeyProvider e especifique a chave multirregional na região local (us-west-2).

Para ver um exemplo completo, consulte BasicMultiRegionKeyEncryptionExample.java no repositório do AWS Encryption SDK for Java no 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 em modo estrito, use o método buildAwsKmsMrkAwareStrictMultiKeyringBrowser() para criar o token de autenticação e especifique a chave multirregional na região local (us-west-2).

Para ver um exemplo completo, consulte kms_multi_region_simple.ts no repositório do AWS Encryption SDK para JavaScript no 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 em modo estrito, use o método buildAwsKmsMrkAwareStrictMultiKeyringNode() para criar o token de autenticação e especifique a chave multirregional na região local (us-west-2).

Para ver um exemplo completo, consulte kms_multi_region_simple.ts no repositório do AWS Encryption SDK para JavaScript no 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 o método MRKAwareStrictAwsKmsMasterKeyProvider() para criar o provedor de chave mestra. Especifique a chave multirregional relacionada na região local (us-west-2).

Para ver um exemplo completo, consulte mrk_aware_kms_provider.py no repositório do AWS Encryption SDK for Python no 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 no modo de descoberta com chaves AWS KMSmultirregionais. Ao descriptografar no modo de descoberta, você não especifica nenhuma AWS KMS keys. (Para obter informações sobre tokens de autenticação de descoberta do AWS KMS de região única, consulte Usar um token de autenticação de descoberta do AWS KMS.)

Se você criptografou com uma chave multirregional, o símbolo compatível com várias regiões no modo de descoberta tentará descriptografar usando uma chave multirregional relacionada na região local. Se não existir nenhuma, a chamada falhará. No modo de descoberta, o AWS Encryption SDK nã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 de reconhecimento de várias regiões no modo de descoberta. Como você não especifica um AWS KMS key, o AWS Encryption SDK deve obter a região de uma fonte diferente. Quando possível, especifique explicitamente a região local. Caso contrário, o AWS Encryption SDK obtém a região local da região configurada no SDK da AWS para sua linguagem de programação.

Antes de executar esses exemplos, substitua o exemplo do ID de conta e do ARN de chave multirregional por valores válidos da sua Conta da AWS.

C

Para descriptografar no modo de descoberta com uma chave multirregional, use o método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()para criar o token de autenticação e o método Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() para criar o filtro de descoberta. Para especificar a região local, defina uma ClientConfiguration e especifique-a no AWS KMS cliente.

Para ver um exemplo completo, consulte kms_multi_region_keys.cpp no repositório do AWS Encryption SDK for C no 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 token de autenticação de descoberta compatível com várias regiões no AWS Encryption SDK para .NET, instancie um objeto CreateAwsKmsMrkDiscoveryKeyringInput que leve um cliente AWS KMS para uma determinada partição da Região da AWS e um filtro de descoberta opcional que limita as chaves do KMS a uma partição e conta específica da AWS. Em seguida, chame o método CreateAwsKmsMrkDiscoveryKeyring() do objeto . Para ver um exemplo completo, consulte AwsKmsMrkDiscoveryKeyringExample.cs no repositório do AWS Encryption SDK para .NET no GitHub.

Para criar um token de autenticação de descoberta compatível com várias regiões para mais de uma Região da AWS, use o método CreateAwsKmsMrkDiscoveryMultiKeyring() para criar um multitoken de autenticação ou use CreateAwsKmsMrkDiscoveryKeyring() para criar vários tokens de autenticação de descoberta compatíveis com várias regiões e, em seguida, use o método CreateMultiKeyring() para combiná-los em um multitoken de autenticação.

Para ver um exemplo, consulte AwsKmsMrkDiscoveryMultiKeyringExample.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 o atributo discovery do parâmetro. --wrapping-keys Os atributos discovery-account e discovery-partition criam um filtro de descoberta que é opcional, mas recomendado.

Para especificar a região, esse comando inclui o atributo region do parâmetro --wrapping-keys.

# 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 o parâmetro builder().withDiscoveryMrkRegion. Caso contrário, o AWS Encryption SDK obtém a região local da região configurada no AWS SDK for Java.

Para ver um exemplo completo, consulte DiscoveryMultiRegionDecryptionExample.java no repositório do AWS Encryption SDK for Java no 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 o método AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser().

Para ver um exemplo completo, consulte kms_multi_region_discovery.ts no repositório do AWS Encryption SDK para JavaScript no 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 o método AwsKmsMrkAwareSymmetricDiscoveryKeyringNode().

Para ver um exemplo completo, consulte kms_multi_region_discovery.ts no repositório do AWS Encryption SDK para JavaScript no 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 multirregional, use o método MRKAwareDiscoveryAwsKmsMasterKeyProvider().

Para ver um exemplo completo, consulte mrk_aware_kms_provider.py no repositório do AWS Encryption SDK for Python no 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 pacote de algoritmo

O AWS Encryption SDK é compatível com vários algoritmos de criptografia simétrica e assimétrica para criptografar suas chaves de dados sob as chaves de encapsulamento que você especificar. No entanto, quando ele usa essas chaves de dados para criptografar seus dados, é padrão do AWS Encryption SDK um pacote de algoritmos recomendado que usa o algoritmoAES-GCM com derivação de chave, assinaturas digitais e confirmação de chave. Embora o pacote de algoritmos padrão seja adequado para a maioria das aplicações, você pode escolher um conjunto alternativo de algoritmos. Por exemplo, alguns modelos de confiança seriam satisfeitos com um pacote de algoritmos sem assinaturas digitais. Para obter informações sobre os pacotes de algoritmos compatíveis com o AWS Encryption SDK, consulte Pacotes de algoritmos compatíveis no AWS Encryption SDK.

Os exemplos a seguir mostram como selecionar um pacote de algoritmos alternativo ao criptografar. Esses exemplos selecionam um pacote de algoritmos recomendado AES-GCM com derivação e confirmação de chaves, mas sem assinaturas digitais. Ao criptografar com um pacote 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 ao transmitir a decodificação.

C

Para especificar um pacote de algoritmos alternativo no AWS Encryption SDK for C, você deve criar um CMM explicitamente. Em seguida, use o aws_cryptosdk_default_cmm_set_alg_id com o CMM e o pacote 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, use. AWS_CRYPTOSDK_DECRYPT_UNSIGNED Isso faz com que a descriptografia falhe se encontrar um 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 pacote de algoritmos alternativo no AWS Encryption SDK para.NET, especifique a propriedade AlgorithmSuiteId de um objeto EncryptInput. O AWS Encryption SDK para .NET inclui constantes que você pode usar para identificar seu pacote de algoritmos preferido.

O AWS Encryption SDK para .NET não tem um método para detectar texto cifrado assinado durante a transmissão de descriptografia porque essa biblioteca não é compatível com dados de streaming.

// 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 o arquivo hello.txt, este exemplo usa o parâmetro --algorithm para especificar um pacote 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 parâmetro --decrypt-unsigned. 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 pacote ade algoritmos alternativo, use o método AwsCrypto.builder().withEncryptionAlgorithm(). Este exemplo usa um pacote 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 descriptografia, use o método createUnsignedMessageDecryptingStream() para garantir que todo 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 pacote de algoritmos alternativo, use o parâmetro suiteId com um valor enum AlgorithmSuiteIdentifier.

// 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 método padrão decrypt. O AWS Encryption SDK para JavaScript no navegador não tem um modo decrypt-unsignedporque o navegador não é compatível com 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 pacote de algoritmos alternativo, use o parâmetro suiteId com um valor enum AlgorithmSuiteIdentifier.

// 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 decryptUnsignedMessageStream. 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 o parâmetro algorithm com um valor enum Algorithm. 

# 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 o modo de decrypt-unsigned streaming, especialmente ao descriptografar durante o streaming. 

# 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 as chaves de dados criptografadas

Você pode limitar o número de chaves de dados criptografadas em uma mensagem criptografada. Esse atributo de práticas recomendadas pode ajudar você a detectar um token de autenticação mal configurado ao criptografar ou um texto cifrado malicioso ao descriptografar. Isso também evita chamadas desnecessárias, caras e potencialmente exaustivas para sua infraestrutura principal. Limitar as chaves de dados criptografadas tem mais valor 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 encapsulamento 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 delas capaz de ser descriptografada. Como resultado, o AWS Encryption SDK tentaria descriptografar cada chave de dados criptografada até esgotar as chaves de dados criptografadas na mensagem.

Para limitar as chaves de dados criptografadas, use o parâmetro MaxEncryptedDataKeys. Esse parâmetro está disponível para todas as linguagens de programação compatíveis a partir das versões 1.9.x e 2.2.x doAWS Encryption SDK. Ele é opcional e válido ao criptografar e descriptografar. Os exemplos a seguir descriptografam dados que foram criptografados sob três chaves de encapsulamento diferentes. O valor de MaxEncryptedDataKeys foi 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 no AWS Encryption SDK para.NET, instancie um cliente AWS Encryption SDK para .NET e defina seu parâmetro MaxEncryptedDataKeys opcional com o valor desejado. Em seguida, chame o métodoDecrypt() na instância do AWS Encryption SDK configurada.

// 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)

Criação de um filtro de descoberta

Ao descriptografar dados criptografados com chaves KMS, é uma prática recomendada descriptografar no modo estrito, ou seja, limitar as chaves de encapsulamento usadas somente às que você especificar. No entanto, se necessário, você também poderá descriptografar no modo de descoberta, onde você não especifica nenhuma chave de encapsulamento. Nesse modo, o AWS KMS pode descriptografar a chave de dados criptografada usando a chave KMS que a criptografou, independentemente de quem possui ou tem acesso a essa chave KMS.

Se você for descriptografar em modo de descoberta, recomendamos que sempre use um filtro de descoberta para limitar as chaves do KMS que podem ser utilizadas às chaves em uma Conta da AWS especificada e na partição. O filtro de descoberta é opcional, mas é uma prática recomendada.

Use a tabela a seguir para determinar o valor da partição do seu filtro de descoberta.

região Partition
Regiões da AWS aws
Regiões da China aws-cn
AWS GovCloud (US) Regions aws-us-gov

Os exemplos nesta seção mostram como criar um filtro de descoberta. Antes de usar o código, substitua os valores de exemplo por valores válidos para a Conta da AWS e partição.

C

Para obter um exemplo completo, consulte: kms_discovery.cpp no AWS Encryption SDK for C.

/* Create a discovery filter for an AWS account and partition */
    
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();
C# / .NET

Para obter um exemplo completo, consulte DiscoveryFilterExample.cs no AWS Encryption SDK para .NET.

// Create a discovery filter for an AWS account and partition

List<string> account = new List<string> { "111122223333" };

DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}
AWS Encryption CLI
# Decrypt in discovery mode with a discovery filter

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Para obter um exemplo completo, consulte:DiscoveryDecryptionExample.java no AWS Encryption SDK for Java.

// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
JavaScript (Node and Browser)

Para obter exemplos completos, consulte kms_filtered_discovery.ts (Node.js) e kms_multi_region_discovery.ts (Navegador) no.AWS Encryption SDK para JavaScript.

/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = { 
  accountIDs: ['111122223333'], 
  partition: 'aws',
}
Python

Para obter um exemplo completo, consulte discovery_kms_provider.py no AWS Encryption SDK for Python.

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

Como definir uma política de compromisso

Uma política de compromisso é uma definição de configuração que determina se sua aplicação criptografa e descriptografa com confirmação de chave. Criptografar e descriptografar com o confirmação de chave é uma prática recomendada do AWS Encryption SDK.

Definir e ajustar sua política de compromisso é uma etapa fundamental na migração das versões 1.7.x e anteriores do AWS Encryption SDK àz versões 2.0x posteriores. Essa progressão é explicada em detalhes no tópico de migração.

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

Trabalhar com streaming de dados

Ao transmitir dados para descriptografia, lembre-se de que o AWS Encryption SDK retornaa texto simples descriptografado após a conclusão das verificações de integridade, mas antes da verificação da assinatura digital. Para garantir que você não retorne ou use texto simples até que a assinatura seja verificada, recomendamos que você armazene o texto simples transmitido até que todo o processo de descriptografia seja concluído.

Esse problema surge somente quando você está transmitindo texto cifrado para decodificação e somente quando você está usando um pacote de algoritmos, como opacote de algoritmos padrão, que inclui assinaturas digitais.

Para facilitar o armazenamento em buffer, algumas implementações de linguagem do AWS Encryption SDK, como AWS Encryption SDK para JavaScript no Node.js, incluem um atributo de buffer como parte do método decrypt. A CLI de criptografia da AWS, que sempre transmite entrada e saída, introduziu um parâmetro --buffer nas versões 1.9.x e 2.2.x.. Em outras implementações de linguagem, você pode usar os atributos de buffer existentes. (O AWS Encryption SDK para .NET não é compatível com streaming.)

Se você estiver usando um pacote de algoritmos sem assinaturas digitais, certifique-se de usar o atributo decrypt-unsigned em cada implementação de linguagem. Esse atributo descriptografa o texto cifrado, mas falhará se encontrar um texto cifrado assinado. Para obter mais detalhes, consulte Escolher um pacote de algoritmo.

Armazenamento em cache de chaves de dados

Em geral, a reutilização de chaves de dados não é incentivada, mas o AWS Encryption SDK oferece uma opção de armazenamento em cache de chaves de dados que fornece reutilização limitada de chaves de dados. O armazenamento em cache de chaves de dados pode melhorar a performance de algumas aplicações e reduzir as chamadas para sua infraestrutura de chaves. Antes de usar o armazenamento em cache de chaves de dados em produção, ajuste os limites de segurança e teste, para garantir que os benefícios superem as desvantagens da reutilização de chaves de dados.