Configuración del AWS Encryption SDK - AWS Encryption SDK
Selección de un lenguaje de programaciónSeleccionar las claves de encapsulamientoUso de varias regiones AWS KMS keysElección de un conjunto de algoritmosLimitar las claves de datos cifradosCrear un filtro de detecciónEstablecer una política de compromisoTrabajo con datos de streamingClaves de datos de almacenamiento en caché

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configuración del AWS Encryption SDK

AWS Encryption SDK Está diseñado para ser fácil de usar. Aunque AWS Encryption SDK tiene varias opciones de configuración, los valores predeterminados se eligen cuidadosamente para que sean prácticos y seguros para la mayoría de las aplicaciones. Sin embargo, es posible que deba ajustar la configuración para mejorar el rendimiento o incluir una característica personalizada en el diseño.

Al configurar la implementación, revise las prácticas AWS Encryption SDK recomendadas e implemente tantas como pueda.

Selección de un lenguaje de programación

AWS Encryption SDK Está disponible en varios lenguajes de programación. Las implementaciones del lenguaje están diseñadas para ser totalmente interoperables y ofrecer las mismas características, aunque pueden implementarse de diferentes maneras. Por lo general, se utiliza la biblioteca que es compatible con su aplicación. Sin embargo, puede seleccionar un lenguaje de programación para una implementación concreta. Por ejemplo, si prefiere trabajar con llaveros, puede elegir el SDK de cifrado de AWS para C o el SDK de cifrado de AWS para JavaScript.

Seleccionar las claves de encapsulamiento

AWS Encryption SDK Genera una clave de datos simétrica única para cifrar cada mensaje. A menos que utilice el almacenamiento en caché de claves de datos, no necesita configurar, administrar ni usar las claves de datos. Lo AWS Encryption SDK hace por ti.

Sin embargo, debe seleccionar una o más claves de encapsulamiento para cifrar cada clave de datos. AWS Encryption SDK Admite teclas AES simétricas y RSA asimétricas de diferentes tamaños. También admite el cifrado simétrico AWS Key Management Service (AWS KMS) AWS KMS keys. Usted es responsable de la seguridad y durabilidad de sus claves de empaquetado, por lo que le recomendamos que utilice una clave de cifrado en un módulo de seguridad de hardware o en un servicio de infraestructura de claves, como. AWS KMS

Para especificar las claves de empaquetado para el cifrado y el descifrado, utilice un conjunto de claves (C y JavaScript) o un proveedor de claves maestras (Java, Python, AWS EncryptionCLI). Puede especificar una clave de encapsulamiento o varias claves de encapsulamiento del mismo tipo o de diferentes tipos. Si utiliza varias claves de encapsulamiento para empaquetar una clave de datos, cada clave de encapsulamiento cifrará una copia de la misma clave de datos. Las claves de datos cifrados (una por clave de empaquetado) se almacenan junto con los datos cifrados en el mensaje cifrado que devuelven. AWS Encryption SDK Para descifrar los datos, el AWS Encryption SDK debe utilizar primero una de las claves de encapsulamiento para descifrar una clave de datos cifrada.

Para especificar una AWS KMS key en un conjunto de claves o en un proveedor de claves maestras, utilice un identificador de AWS KMS clave compatible. Para obtener más información sobre los identificadores clave de una AWS KMS clave, consulte los identificadores clave en la AWS Key Management Service Guía para desarrolladores.

  • Al cifrar con SDK de cifrado de AWS para Java, SDK de cifrado de AWS para JavaScript, SDK de cifrado de AWS para Python o con el AWS cifradoCLI, puede utilizar cualquier identificador de clave válido (identificador de clave, claveARN, alias o aliasARN) como clave. KMS Al cifrar con SDK de cifrado de AWS para C, solo puede utilizar un identificador o una clave clave. ARN

    Si especifica un nombre de alias o un alias ARN para una KMS clave al cifrar, AWS Encryption SDK guarda la clave ARN actualmente asociada a ese alias; no guarda el alias. Los cambios en el alias no afectan a la KMS clave utilizada para descifrar las claves de datos.

  • Al descifrar en modo estricto (en el que se especifican determinadas claves de empaquetado), debe utilizar una clave ARN para identificarlo. AWS KMS keys Este requisito se aplica a todas las implementaciones de lenguaje del AWS Encryption SDK.

    Al cifrar con un AWS KMS anillo de claves, AWS Encryption SDK almacena la clave AWS KMS key en los metadatos ARN de la clave de datos cifrados. Al descifrar en modo estricto, AWS Encryption SDK comprueba que la misma clave ARN aparezca en el anillo de claves (o en el proveedor de claves maestras) antes de intentar utilizar la clave de empaquetado para descifrar la clave de datos cifrados. Si utiliza un identificador de clave diferente, no AWS Encryption SDK lo reconocerá ni utilizará AWS KMS key, aunque los identificadores hagan referencia a la misma clave.

Para especificar una AESclave sin procesar o un par de RSA claves sin procesar como clave de empaquetado en un anillo de claves, debe especificar un espacio de nombres y un nombre. En un proveedor de claves maestras, el Provider ID es el equivalente al espacio de nombre y el Key ID es el equivalente al nombre. Al descifrar, debe utilizar exactamente el mismo espacio de nombre y el mismo nombre para cada clave de encapsulamiento sin procesar que utilizó al cifrar. Si utiliza un nombre o un espacio de nombres diferente, no reconocerá ni AWS Encryption SDK utilizará la clave de empaquetado, aunque el material de la clave sea el mismo.

Uso de varias regiones AWS KMS keys

Puede utilizar claves AWS Key Management Service multirregionales (AWS KMS) como claves de empaquetado en el. AWS Encryption SDK Si cifra con una clave multirregional en una Región de AWS, puede desencriptar utilizando una clave multirregional relacionada en otra diferente. Región de AWS La compatibilidad con claves multirregionales se introdujo en la versión 2.3. x de la AWS Encryption SDK y la versión 3.0. x del AWS cifradoCLI.

AWS KMS Las claves multirregionales son un conjunto de AWS KMS keys diferentes claves Regiones de AWS que tienen el mismo material y el mismo identificador de clave. Puede usar estas claves relacionadas como si fueran la misma clave en diferentes regiones. Las claves multirregionales son compatibles con los escenarios habituales de recuperación ante desastres y copias de seguridad, que requieren el cifrado en una región y el descifrado en una región diferente sin necesidad de realizar una llamada entre regiones. AWS KMS Para obtener más información sobre las claves de regiones múltiples, consulte Uso de claves de multirregiones en la Guía para desarrolladores de AWS Key Management Service .

Para admitir claves multirregionales, AWS Encryption SDK incluye conjuntos de claves compatibles con AWS KMS múltiples regiones y proveedores de claves maestras. El nuevo símbolo de compatibilidad con múltiples regiones en cada lenguaje de programación es compatible con claves de una sola región y multirregionales.

En los conjuntos de claves compatibles con múltiples regiones y en los proveedores de claves maestras que utilizan más de una clave, puede especificar varias claves de una o varias regiones. KMS Sin embargo, solo puede especificar una clave de cada conjunto de claves de réplica multirregionales relacionadas. Si especifica más de un identificador de clave con el mismo ID de clave, se produce un error en la llamada al constructor.

También puede utilizar una clave multirregional con los conjuntos de claves estándar de una sola región y AWS KMS los proveedores de claves maestras. Sin embargo, debe usar la misma clave multirregional en la misma región para cifrar y descifrar. Los conjuntos de claves de una sola región y los proveedores de claves maestras intentan descifrar el texto cifrado únicamente con las claves que cifraron los datos.

Los siguientes ejemplos muestran cómo cifrar y descifrar datos mediante claves multirregionales y los nuevos conjuntos de claves compatibles con múltiples regiones y proveedores de claves maestras. En estos ejemplos se cifran los datos de la us-east-1 región y se descifran los datos de la us-west-2 región mediante claves de réplica multirregionales relacionadas en cada región. Antes de ejecutar estos ejemplos, sustituya la clave multirregional del ejemplo por un ARN valor válido suyo. Cuenta de AWS

C

Para cifrar con una clave multirregional, utilice el método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() para crear una instancia del conjunto de claves. Especifique una clave multirregional.

Este sencillo ejemplo no incluye un contexto de cifrado. Para ver un ejemplo que utiliza un contexto de cifrado en C, consulte Cifrado y descifrado de cadenas.

Para ver un ejemplo completo, consulte kms_multi_region_keys.cpp en el SDK de cifrado de AWS para C repositorio de 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 cifrar con una clave multirregional en la región EE.UU. Este (Norte de Virginia) (us-east-1), cree una instancia de un CreateAwsKmsMrkKeyringInput objeto con un identificador de clave para la clave multirregión y un cliente para la región especificada. AWS KMS A continuación, utilice el método CreateAwsKmsMrkKeyring() para crear el conjunto de claves.

El método CreateAwsKmsMrkKeyring() crea un conjunto de claves con exactamente una clave multirregional. Para cifrar con varias claves de encapsulamiento, incluida una clave multirregional, utilice el método CreateAwsKmsMrkMultiKeyring().

Para ver un ejemplo completo, consulte .cs en el formulario. AwsKmsMrkKeyringExample AWS Encryption SDK NETrepositorio en. 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

En este ejemplo, se cifra el archivo de hello.txt con una clave multirregional en la región us-east-1. Como en el ejemplo se especifica una clave ARN con un elemento Region, en este ejemplo no se utiliza el atributo region del --wrapping-keys parámetro.

Si el ID de clave de la clave de encapsulamiento no especifica una región, puede utilizar el atributo region de --wrapping-keys para especificar la región, por ejemplo, --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 cifrar con una clave multirregional, cree una instancia de AwsKmsMrkAwareMasterKeyProvider y especifique una clave multirregional.

Para ver un ejemplo completo, consulte BasicMultiRegionKeyEncryptionExample.javaen el SDK de cifrado de AWS para Java repositorio de 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 cifrar con una clave multirregional, use el método buildAwsKmsMrkAwareStrictMultiKeyringBrowser() para crear el conjunto de claves y especificar una clave multirregional.

Para ver un ejemplo completo, consulte kms_multi_region_simple.ts en el repositorio de. SDK de cifrado de AWS 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 SDK de cifrado de AWS 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 cifrar con una clave multirregional, use el método buildAwsKmsMrkAwareStrictMultiKeyringNode() para crear el conjunto de claves y especificar una clave multirregional.

Para ver un ejemplo completo, consulte kms_multi_region_simple.ts en el repositorio de. SDK de cifrado de AWS 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 cifrar con una clave multirregional, utilice el método y especifique una clave AWS KMS multirregional. MRKAwareStrictAwsKmsMasterKeyProvider()

Para ver un ejemplo completo, consulte mrk_aware_kms_provider.py en el repositorio de SDK de cifrado de AWS para Python . 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
)

A continuación, mueva el texto cifrado a la región us-west-2. No es necesario volver a cifrar el texto cifrado.

Para descifrar el texto cifrado en modo estricto en la us-west-2 región, cree una instancia del símbolo multirregional con la clave de la clave multirregional relacionada ARN de la región. us-west-2 Si especificas la clave ARN de una clave multirregional relacionada en una región diferente (incluido el lugar en el que se cifró)us-east-1, el símbolo multirregional hará una llamada interregional para dicha clave. AWS KMS key

Al descifrar en modo estricto, el símbolo compatible con varias regiones requiere una clave. ARN Solo acepta una clave de cada conjunto ARN de claves multirregionales relacionadas.

Antes de ejecutar estos ejemplos, sustituya la clave ARN multirregional del ejemplo por un valor válido de su. Cuenta de AWS

C

Para cifrar en el modo estricto con una clave multirregional, utilice el método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() para crear una instancia del conjunto de claves. Especifique la clave multirregional relacionada en la región local (us-west-2).

Para ver un ejemplo completo, consulte kms_multi_region_keys.cpp en el SDK de cifrado de AWS para C repositorio de 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 descifrar en modo estricto con una sola clave multirregional, use los mismos constructores y métodos que usó para ensamblar la entrada y crear el conjunto de claves para el cifrado. Cree una instancia de un CreateAwsKmsMrkKeyringInput objeto con la clave ARN de una clave multirregión relacionada y un AWS KMS cliente para la región EE.UU. Oeste (Oregón) (us-west-2). A continuación, utilice el CreateAwsKmsMrkKeyring() método para crear un conjunto de claves multirregional con una clave multirregional. KMS

Para ver un ejemplo completo, consulte AwsKmsMrkKeyringExample.cs en el formulario. AWS Encryption SDK NETrepositorio en. 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 descifrar con la clave multirregión relacionada en la región us-west-2, utilice el atributo key del parámetro para especificar su clave. --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 descifrar en modo estricto, cree una instancia AwsKmsMrkAwareMasterKeyProvider y especifique la clave multirregional relacionada en la región local (us-west-2).

Para ver un ejemplo completo, consulte BasicMultiRegionKeyEncryptionExample.java en el repositorio de. SDK de cifrado de AWS para Java 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 descifrar en modo estricto, utilice el método buildAwsKmsMrkAwareStrictMultiKeyringBrowser() para crear el conjunto de claves y especifique la clave multirregional relacionada en la región local (us-west-2).

Para ver un ejemplo completo, consulte kms_multi_region_simple.ts en el repositorio de. SDK de cifrado de AWS 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 SDK de cifrado de AWS 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 descifrar en modo estricto, utilice el método buildAwsKmsMrkAwareStrictMultiKeyringNode() para crear el conjunto de claves y especifique la clave multirregional relacionada en la región local (us-west-2).

Para ver un ejemplo completo, consulte kms_multi_region_simple.ts en el repositorio de. SDK de cifrado de AWS 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-west-2
 */
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 descifrar en modo estricto, use el método MRKAwareStrictAwsKmsMasterKeyProvider() para crear el proveedor de claves maestras. Especifique la clave multirregional relacionada en la región local (us-west-2).

Para ver un ejemplo completo, consulte mrk_aware_kms_provider.py en el repositorio de. SDK de cifrado de AWS para Python 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
)

También puede descifrar en modo de detección con claves de múltiples regiones de AWS KMS . Al descifrar en modo de detección, no especifique ningún AWS KMS keys. (Para obtener información sobre los conjuntos de claves de AWS KMS detección de una sola región, consulteUso de un anillo de claves de detección AWS KMS.)

Si ha cifrado con una clave multirregional, el símbolo multirregional del modo de detección intentará descifrarlo utilizando una clave multirregional relacionada en la región local. Si no existe ninguno, se produce un error en la llamada. En el modo de detección, no AWS Encryption SDK intentará realizar una llamada entre regiones para obtener la clave multirregional utilizada para el cifrado.

nota

Si utiliza un símbolo de compatibilidad con múltiples regiones en el modo de detección para cifrar los datos, la operación de cifrado fallará.

El siguiente ejemplo muestra cómo descifrar con el símbolo de compatibilidad con múltiples regiones en el modo de detección. Como no especificas una AWS KMS key, AWS Encryption SDK deben obtener la región de una fuente diferente. Cuando sea posible, especifique la región local de forma explícita. De lo contrario, AWS Encryption SDK obtiene la región local de la región configurada AWS SDK para su lenguaje de programación.

Antes de ejecutar estos ejemplos, sustituya el identificador de cuenta y la clave ARN multirregional del ejemplo por valores válidos de su Cuenta de AWS cuenta.

C

Para descifrar en modo de detección con una clave multirregional, utilice el método Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() para crear el conjunto de claves y el método Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() para crear el filtro de detección. Para especificar la región local, defina un ClientConfiguration y especifíquelo en el cliente de AWS KMS .

Para ver un ejemplo completo, consulta kms_multi_region_keys.cpp en el SDK de cifrado de AWS para C repositorio de 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 crear un conjunto de claves de detección compatible con varias regiones en el formulario. AWS Encryption SDK NET, cree una instancia de un CreateAwsKmsMrkDiscoveryKeyringInput objeto que utilice un AWS KMS cliente para un objeto concreto Región de AWS y un filtro de detección opcional que limite KMS las claves a una partición y una cuenta determinadas. AWS Luego, llame al método CreateAwsKmsMrkDiscoveryKeyring() con el objeto de entrada. Para ver un ejemplo completo, consulte AwsKmsMrkDiscoveryKeyringExample.cs en el formulario. AWS Encryption SDK NETrepositorio en. GitHub

Para crear un conjunto de claves de detección compatible con múltiples regiones para más de un Región de AWS, use el método CreateAwsKmsMrkDiscoveryMultiKeyring() para crear un conjunto de claves múltiple o use CreateAwsKmsMrkDiscoveryKeyring() para crear varios conjuntos de claves de detección compatible con múltiples regiones y luego use el método CreateMultiKeyring() para combinarlos en un conjunto de claves múltiple.

Para ver un ejemplo, 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 descifrar en modo de detección, utilice el atributo discovery del parámetro --wrapping-keys. Los atributos discovery-account y discovery-partition crean un filtro de detección que es opcional, pero recomendado.

Para especificar la región, este comando incluye el atributo region del 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 la región local, utilice el parámetro builder().withDiscoveryMrkRegion. De lo contrario, el AWS Encryption SDK obtiene la región local de la región configurada en el AWS SDK for Java.

Para ver un ejemplo completo, consulte DiscoveryMultiRegionDecryptionExample.java en el SDK de cifrado de AWS para Java repositorio de. 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 descifrar en modo de detección con una clave simétrica multirregional, use el método de AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser().

Para ver un ejemplo completo, consulte kms_multi_region_discovery.ts en el repositorio de. SDK de cifrado de AWS 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 descifrar en modo de detección con una clave simétrica multirregional, use el método de AwsKmsMrkAwareSymmetricDiscoveryKeyringNode().

Para ver un ejemplo completo, consulte kms_multi_region_discovery.ts en el repositorio de. SDK de cifrado de AWS 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 descifrar en modo de detección con una clave multirregional, use el método de MRKAwareDiscoveryAwsKmsMasterKeyProvider().

Para ver un ejemplo completo, consulte mrk_aware_kms_provider.py en el repositorio de. SDK de cifrado de AWS para Python 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
)

Elección de un conjunto de algoritmos

AWS Encryption SDK Admite varios algoritmos de cifrado simétricos y asimétricos para cifrar las claves de datos con las claves de empaquetado que especifique. Sin embargo, cuando utiliza esas claves de datos para cifrar los datos, utiliza de AWS Encryption SDK forma predeterminada un conjunto de algoritmos recomendado que utiliza el AES GCM algoritmo con derivación de claves, firmas digitales y compromiso de claves. Aunque es probable que el conjunto de algoritmos predeterminado sea adecuado para la mayoría de las aplicaciones, puede elegir un conjunto de algoritmos alternativo. Por ejemplo, algunos modelos de confianza quedarían satisfechos con un conjunto de algoritmos sin firmas digitales. Para obtener información sobre los conjuntos de algoritmos compatibles con el AWS Encryption SDK , consulte Conjuntos de algoritmos admitidos en el AWS Encryption SDK.

En los siguientes ejemplos se muestra cómo seleccionar un conjunto de algoritmos alternativo al cifrar. En estos ejemplos se selecciona un conjunto de GCM algoritmos recomendado AES con derivación y compromiso de claves, pero sin firmas digitales. Al cifrar con un conjunto de algoritmos que no incluye firmas digitales, utilice el modo de descifrado solo sin firma al descifrar. Este modo, que falla si encuentra texto cifrado firmado, es el más útil al transmitir el descifrado.

C

Para especificar un conjunto de algoritmos alternativo en el SDK de cifrado de AWS para C, debe crear uno de CMM forma explícita. A continuación, úselo aws_cryptosdk_default_cmm_set_alg_id con el conjunto de algoritmos seleccionado CMM y con el conjunto de algoritmos seleccionado.

/* 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;
}

Al descifrar datos que se cifraron sin firmas digitales, utilice AWS_CRYPTOSDK_DECRYPT_UNSIGNED. Esto provoca un error en el descifrado si encuentra texto cifrado firmado.

/* 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 un conjunto de algoritmos alternativo en AWS Encryption SDK el formulario. NET, especifique la AlgorithmSuiteId propiedad de un EncryptInputobjeto. El AWS Encryption SDK para. NETincluye constantes que puede utilizar para identificar su conjunto de algoritmos preferido.

El AWS Encryption SDK para. NETno tiene un método para detectar el texto cifrado firmado al transmitir el descifrado porque esta biblioteca no admite la transmisión de datos.

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

Al cifrar el archivo hello.txt, en este ejemplo se utiliza el parámetro --algorithm para especificar un conjunto de algoritmos sin firmas digitales. 

# 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

Al descifrar, en este ejemplo se utiliza el parámetro --decrypt-unsigned. Se recomienda utilizar este parámetro para garantizar que se está descifrando el texto cifrado sin firmar, especialmente con elCLI, que siempre transmite entradas y salidas.

# 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 un conjunto de algoritmos alternativo, utilice el método AwsCrypto.builder().withEncryptionAlgorithm(). Este ejemplo especifica un conjunto de algoritmos alternativo sin firmas digitales.

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

Cuando transmitir datos para descifrarlos, utilice el método createUnsignedMessageDecryptingStream() para asegurarse de que todo el texto cifrado que vaya a descifrar no esté firmado.

// 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 un conjunto de algoritmos alternativo, utilice el parámetro suiteId con un valor de 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, })

Al descifrar, utilice el método estándar decrypt. SDK de cifrado de AWS para JavaScript en el navegador no tiene un modo decrypt-unsigned porque el navegador no admite el 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 un conjunto de algoritmos alternativo, utilice el parámetro suiteId con un valor de 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, })

Al descifrar datos cifrados sin firmas digitales, utilice Stream. decryptUnsignedMessage Este método produce un error si encuentra texto cifrado firmado.

// 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 un algoritmo de cifrado alternativo, utilice el parámetro algorithm con un valor de 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
)

Al descifrar mensajes cifrados sin firmas digitales, utilice el modo de streaming de decrypt-unsigned, especialmente al descifrar durante el 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 las claves de datos cifrados

Puede limitar el número de claves de datos cifrados en un mensaje cifrado. Esta característica de práctica recomendada puede ayudarle a detectar un conjunto de claves mal configurado al cifrar o a identificar un texto cifrado malicioso al descifrar. También evita las llamadas innecesarias, costosas y potencialmente exhaustivas a su infraestructura de claves. Limitar las claves de datos cifradas es más valioso al descifrar los mensajes de una fuente que no sea de confianza.

Aunque la mayoría de los mensajes cifrados tienen una clave de datos cifrada para cada clave de encapsulamiento utilizada en el cifrado, un mensaje cifrado puede contener hasta 65 535 claves de datos cifrados. Un agente malicioso podría crear un mensaje cifrado con miles de claves de datos cifradas, sin que se puedan descifrar. Como resultado, AWS Encryption SDK intentaría descifrar cada clave de datos cifrados hasta agotar las claves de datos cifrados del mensaje.

Para limitar las claves de datos cifradas, utilice el parámetro MaxEncryptedDataKeys. Este parámetro está disponible para todos los lenguajes de programación compatibles a partir de la versión 1.9.x y 2.2.x del AWS Encryption SDK. Es opcional y válido para cifrar y descifrar. Los siguientes ejemplos descifran los datos que se cifraron con tres claves de encapsulamiento diferentes. El valor MaxEncryptedDataKeys se establece en 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 las claves de datos cifrados en formato AWS Encryption SDK . NET, cree una instancia de un cliente para el AWS Encryption SDK formulario. NETy defina su MaxEncryptedDataKeys parámetro opcional en el valor deseado. A continuación, llame al método Decrypt() en la instancia 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)

Crear un filtro de detección

Al descifrar datos cifrados con KMS claves, se recomienda descifrarlos en modo estricto, es decir, limitar las claves de empaquetado utilizadas únicamente a las que especifique. Sin embargo, si es necesario, también puede descifrar en el modo de detección, en el que no se especifica ninguna clave de encapsulamiento. En este modo, AWS KMS puede descifrar la clave de datos cifrados utilizando la KMS clave que la cifró, independientemente de quién sea el propietario o tenga acceso a esa clave. KMS

Si debe descifrar en modo de descubrimiento, le recomendamos que utilice siempre un filtro de descubrimiento, que limite las KMS claves que se pueden usar a las de una partición Cuenta de AWS AND específica. El filtro de detección es opcional, pero es una práctica recomendada.

Utilice la siguiente tabla para determinar el valor de partición de su filtro de detección.

Región Partición
Regiones de AWS aws
Regiones de China aws-cn
AWS GovCloud (US) Regions aws-us-gov

En los ejemplos de esta sección se muestra cómo crear un filtro de detección. Antes de usar el código, sustituya los valores de ejemplo por valores válidos para la partición Cuenta de AWS y.

C

Para ver ejemplos completos, consulte kms_discovery.cpp en el SDK de cifrado de AWS para 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 ver un ejemplo completo, consulte DiscoveryFilterExample.cs en el formulario 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 ver un ejemplo completo, consulte DiscoveryDecryptionExample.java en. SDK de cifrado de AWS para Java

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

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

Para ver ejemplos completos, consulte kms_filtered_discovery.ts (Node.js) y kms_multi_region_discovery.ts (Navegador) en el SDK de cifrado de AWS para JavaScript.

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

Para ver un ejemplo completo, consulte discovery_kms_provider.py en el SDK de cifrado de AWS para 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",
    )

Establecer una política de compromiso

Una política de compromiso es una configuración que determina si su aplicación cifra y descifra con compromiso clave. Cifrar y descifrar los datos con un compromiso clave es una práctica recomendada de AWS Encryption SDK.

Establecer y ajustar la política de compromisos es un paso fundamental a la hora de migrar desde las versiones 1.7.x y anteriores del AWS Encryption SDK a la versión 2.0.x y posteriores. Esta progresión se explica en detalle en el tema de migración.

El valor predeterminado de la política de compromiso en las últimas versiones del AWS Encryption SDK (a partir de la versión 2.0.x), RequireEncryptRequireDecrypt, es ideal para la mayoría de las situaciones. Sin embargo, si necesita descifrar un texto cifrado que se cifró sin compromiso clave, puede que tenga que cambiar su política de compromiso a. RequireEncryptAllowDecrypt Para ver ejemplos de cómo establecer una política de compromiso en cada lenguaje de programación, consulte Establecer su política de compromiso.

Trabajo con datos de streaming

Cuando transmita datos para descifrarlos, tenga en cuenta que AWS Encryption SDK devuelve el texto sin formato descifrado una vez finalizadas las comprobaciones de integridad, pero antes de comprobar la firma digital. Para asegurarse de no devolver ni utilizar texto no cifrado hasta que se compruebe la firma, le recomendamos que almacene en búfer el texto no cifrado transmitido hasta que se complete todo el proceso de descifrado.

Este problema surge únicamente cuando se transmite texto cifrado para su descifrado y solo cuando se utiliza un conjunto de algoritmos, como el conjunto de algoritmos predeterminado, que incluye firmas digitales.

Para facilitar el almacenamiento en búfer, algunas implementaciones AWS Encryption SDK lingüísticas, como SDK de cifrado de AWS para JavaScript en Node.js, incluyen una función de almacenamiento en búfer como parte del método de descifrado. El AWS cifradoCLI, que siempre transmite la entrada y la salida, introdujo un parámetro en las versiones 1.9. --buffer x y 2.2. x. En las implementaciones de otros lenguajes, puede utilizar las características de almacenamiento en búfer existentes. (El AWS Encryption SDK cuatro. NETno admite la transmisión.)

Si utiliza un conjunto de algoritmos sin firmas digitales, asegúrese de utilizar la característica de decrypt-unsigned en cada implementación lingüística. Esta característica descifra el texto cifrado, pero no lo consigue si encuentra texto cifrado firmado. Para obtener más información, consulte Elección de un conjunto de algoritmos.

Claves de datos de almacenamiento en caché

En general, no se recomienda reutilizar las claves de datos, pero AWS Encryption SDK ofrece una opción de almacenamiento en caché de claves de datos que permite una reutilización limitada de las claves de datos. El almacenamiento en caché de las claves de datos puede mejorar el rendimiento de algunas aplicaciones y reducir las llamadas a su infraestructura clave. Antes de utilizar el almacenamiento en caché de claves de datos en producción, ajuste los umbrales de seguridad y compruebe que las ventajas superan las desventajas de la reutilización de las claves de datos.