Configurando o AWS Encryption SDK - AWS Encryption SDK
Seleção de uma linguagem de programaçãoSeleção de chaves de encapsulamentoUsando a multirregião AWS KMS keysEscolher 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á.

Configurando o AWS Encryption SDK

O foi AWS Encryption SDK projetado para ser fácil de usar. Embora o 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 dos aplicativos. 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 AWS Encryption SDK melhores práticas e 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 chaveiros, você pode escolher o AWS Encryption SDK for C ou o. AWS Encryption SDK para JavaScript

Seleção de chaves de encapsulamento

Isso 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. Ele AWS Encryption SDK faz isso por você.

No entanto, você deve selecionar uma ou mais chaves de encapsulamento para criptografar cada chave de dados. AWS Encryption SDK Ele suporta teclas AES simétricas e chaves RSA assimétricas em tamanhos diferentes. Ele também suporta criptografia AWS KMS keys simétrica AWS Key Management Service(AWS KMS). 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, como AWS KMS.

Para especificar suas chaves de agrupamento para criptografia e descriptografia, você usa um chaveiro (C e JavaScript) ou um provedor de chave mestra (Java, Python, Criptografia). AWS CLI É 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 empacotamento) são armazenadas com os dados criptografados na mensagem criptografada que elas AWS Encryption SDK retornam. 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 um AWS KMS key em um chaveiro ou provedor de chave mestra, use um identificador de AWS KMS chave compatível. Para obter detalhes sobre os identificadores de chave de uma AWS KMS chave, consulte Identificadores de chave no Guia do AWS Key Management Service desenvolvedor.

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

    Se você especificar um nome de alias ou alias ARN para uma KMS chave durante a criptografia, o AWS Encryption SDK salvará a chave ARN atualmente associada a esse alias; ele não salvará o alias. As alterações no alias não afetam a KMS chave usada para descriptografar suas chaves de dados.

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

    Quando você criptografa com um AWS KMS chaveiro, ele AWS Encryption SDK armazena a chave ARN do AWS KMS key nos metadados da chave de dados criptografada. Ao descriptografar no modo estrito, ele AWS Encryption SDK verifica se a mesma chave ARN aparece no chaveiro (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, eles não AWS Encryption SDK reconhecerão nem usarão o AWS KMS key, mesmo que os identificadores se refiram à mesma chave.

Para especificar uma AESchave bruta ou um par de RSA chaves brutas como chave de agrupamento em um chaveiro, 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, eles não AWS Encryption SDK reconhecerão nem usarão a chave de encapsulamento, mesmo que o material da chave seja o mesmo.

Usando a multirregião AWS KMS keys

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 versão 3.0. x da AWS criptografiaCLI.

AWS KMS As chaves multirregionais são um conjunto de AWS KMS keys chaves diferentes Regiões da AWS que têm o mesmo material de chave e ID 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, AWS Encryption SDK inclui chaveiros com AWS KMS reconhecimento de várias regiões e fornecedores de chaves mestras. 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 chaveiros com reconhecimento de várias regiões e nos provedores de chaves mestras que usam mais de uma KMS chave, você pode especificar várias chaves de região única e multirregião. 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 os fornecedores padrão de AWS KMS chaveiros de região única e chave mestra. 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 chave multirregional ARN por um valor válido do seu 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 AWS Encryption SDK for C repositório em 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 CreateAwsKmsMrkKeyringInput objeto com um identificador de chave para a chave multirregional e um cliente para a região especificada. AWS KMS 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 obter um exemplo completo, consulte AwsKmsMrkKeyringExample.cs no formulário AWS Encryption SDK . NETrepositório ativado. 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 uma chave ARN com um elemento Região, esse exemplo não usa o atributo região do --wrapping-keys parâmetro.

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.javano AWS Encryption SDK for Java repositório em. 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 em. AWS Encryption SDK para JavaScript 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 em. AWS Encryption SDK para JavaScript 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 MRKAwareStrictAwsKmsMasterKeyProvider() método e especifique uma chave multirregional.

Para ver um exemplo completo, consulte mrk_aware_kms_provider.py no AWS Encryption SDK for Python repositório em 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 decifrar o texto cifrado no modo estrito na us-west-2 região, instancie o símbolo compatível com várias regiões com a chave da chave multirregional relacionada na região. ARN us-west-2 Se você especificar a chave ARN de uma chave multirregional relacionada em uma região diferente (inclusive us-east-1 onde ela foi criptografada), o símbolo compatível com várias regiões fará uma chamada entre regiões para essa chave. AWS KMS key

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

Antes de executar esses exemplos, substitua o exemplo de chave multirregional ARN por um valor válido do seu 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 AWS Encryption SDK for C repositório em 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 CreateAwsKmsMrkKeyringInput objeto com a chave ARN de uma chave multirregional relacionada e um AWS KMS cliente para a região Oeste dos EUA (Oregon) (us-west-2). Em seguida, use o CreateAwsKmsMrkKeyring() método para criar um chaveiro multirregional com uma chave KMS multirregional.

Para obter um exemplo completo, consulte AwsKmsMrkKeyringExample.cs no formulário AWS Encryption SDK . NETrepositório ativado. 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 para especificar sua chave. --wrapping-keys 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 uma AwsKmsMrkAwareMasterKeyProvider e especifique a chave multirregional na região local (us-west-2).

Para ver um exemplo completo, consulte BasicMultiRegionKeyEncryptionExample.java no AWS Encryption SDK for Java repositório em. 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 em. AWS Encryption SDK para JavaScript 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 em. AWS Encryption SDK para JavaScript 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 AWS Encryption SDK for Python repositório em 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 KMS multirregionais. Ao descriptografar no modo de descoberta, você não especifica nenhuma AWS KMS keys. (Para obter informações sobre chaveiros de AWS KMS descoberta de uma única região, consulteUsando um chaveiro AWS KMS Discovery.)

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, eles não AWS Encryption SDK tentarão 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, eles AWS Encryption SDK devem obter a região de uma fonte diferente. Quando possível, especifique explicitamente a região local. Caso contrário, AWS Encryption SDK obtém a região local da região configurada em AWS SDK para sua linguagem de programação.

Antes de executar esses exemplos, substitua o exemplo de ID da conta e chave multirregional ARN por valores válidos do seu 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 AWS Encryption SDK for C repositório em 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 compatível com várias regiões no formulário. AWS Encryption SDK NET, instancie um CreateAwsKmsMrkDiscoveryKeyringInput objeto que leva um AWS KMS cliente para um determinado Região da AWS e um filtro de descoberta opcional que limita KMS as chaves para uma AWS partição e conta específicas. Em seguida, chame o método CreateAwsKmsMrkDiscoveryKeyring() do objeto . Para obter um exemplo completo, consulte AwsKmsMrkDiscoveryKeyringExample.cs no formulário AWS Encryption SDK . NETrepositório ativado. 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 AWS Encryption SDK for Java repositório em. 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 em. AWS Encryption SDK para JavaScript 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 em. AWS Encryption SDK para JavaScript 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 AWS Encryption SDK for Python repositório em 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 suporta 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, o AWS Encryption SDK padrão é um conjunto de algoritmos recomendado que usa o GCM algoritmo AES - com derivação de chaves, assinaturas digitais e comprometimento de chaves. 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 conjunto recomendado AES de GCM algoritmos com derivação e comprometimento 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 conjunto alternativo de algoritmos 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 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, 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 conjunto alternativo de algoritmos no AWS Encryption SDK formulário. NET, especifique a AlgorithmSuiteId propriedade de um EncryptInputobjeto. O AWS Encryption SDK para. NETinclui constantes que você pode usar para identificar seu conjunto de algoritmos preferido.

O AWS Encryption SDK para. NETnão tem um método para detectar texto cifrado assinado ao transmitir a decodificação porque essa biblioteca não oferece suporte a 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 oCLI, 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 o Stream. decryptUnsignedMessage 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, eles AWS Encryption SDK tentariam 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 do AWS 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 formulário. NET, instancie um cliente para o AWS Encryption SDK for. NETe defina seu MaxEncryptedDataKeys parâmetro opcional para 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 KMS chaves, é 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 empacotamento. Nesse modo, AWS KMS pode descriptografar a chave de dados criptografada usando a KMS chave que a criptografou, independentemente de quem possui ou tem acesso a essa chave. KMS

Se você precisar descriptografar no modo de descoberta, recomendamos que você sempre use um filtro de descoberta, que limita as KMS chaves que podem ser usadas às de uma partição especificada Conta da AWS . 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 partição Conta da AWS e.

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 formulário AWS Encryption SDK . 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 decodificação, lembre-se de que eles AWS Encryption SDK retornam 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 AWS Encryption SDK linguagem, como AWS Encryption SDK para JavaScript no Node.js, incluem um recurso de buffer como parte do método decrypt. A AWS criptografiaCLI, que sempre transmite entrada e saída, introduziu um --buffer parâmetro 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. NETnão suporta 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 detalhes, consulte Escolher um pacote de algoritmo.

Armazenamento em cache de chaves de dados

Em geral, a reutilização de chaves de dados é desencorajada, mas 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.