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.
# Conjuntos de claves
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
[El SDK AWS de cifrado de bases de datos utiliza *anillos de claves* para realizar el cifrado de sobres.](concepts.md#envelope-encryption) Los conjuntos de claves generan, cifran y descifran claves de datos. Según el conjunto de claves que se utilice, se determinará el origen de las claves de datos únicas que protegen cada registro cifrado y las [claves de encapsulación](concepts.md#wrapping-key) que cifran dichas claves de datos. Al cifrar especifica un conjunto de claves y al descifrar usa ese mismo conjunto de claves u otro conjunto de claves.
Puede utilizar cada conjunto de claves de forma individual o combinar conjuntos de claves en un [conjunto de claves múltiple](use-multi-keyring.md). Aunque la mayoría de los conjuntos de claves pueden generar, cifrar y descifrar claves de datos, podría crear un conjunto de claves que realice solo una operación particular, por ejemplo, un conjunto de claves que solo genere claves de datos y utilizar dicho conjunto de claves en combinación con otros.
Le recomendamos que utilice un anillo de claves que proteja las claves de empaquetado y lleve a cabo operaciones criptográficas dentro de un límite seguro, como el anillo de AWS KMS claves, que utiliza AWS KMS keys ese anillo que nunca deja [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)() sin cifrar.AWS KMS También puede crear un conjunto de claves que utilice claves empaquetadoras almacenadas en los módulos de seguridad del hardware (HSMs) o protegidas por otros servicios de claves maestras.
Su conjunto de claves determina las claves de encapsulamiento que protegen sus claves de datos y, en última instancia, sus datos. Utilice las claves de encapsulación más seguras que resulten prácticas para su tarea. Siempre que sea posible, utilice las claves de encapsulación que están protegidas por un módulo de seguridad de hardware (HSM) o una infraestructura de administración de claves, como las claves KMS en [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) o claves de cifrado en [AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/).
El SDK AWS de cifrado de bases de datos proporciona varios llaveros y configuraciones de llaveros, y usted puede crear sus propios llaveros personalizados. También puede crear un [conjunto de claves múltiple](use-multi-keyring.md) que incluya uno o más conjuntos de claves del mismo tipo o de uno diferente.
**Topics**
+ [Cómo funcionan los conjuntos de claves](#using-keyrings)
+ [AWS KMS llaveros](use-kms-keyring.md)
+ [AWS KMS Llaveros jerárquicos](use-hierarchical-keyring.md)
+ [AWS KMS Llaveros ECDH](use-kms-ecdh-keyring.md)
+ [Conjunto de claves de AES sin formato](use-raw-aes-keyring.md)
+ [Conjunto de claves de RSA sin formato](use-raw-rsa-keyring.md)
+ [Llaveros ECDH sin procesar](use-raw-ecdh-keyring.md)
+ [Conjuntos de claves múltiples](use-multi-keyring.md)
## Cómo funcionan los conjuntos de claves
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
Al cifrar y firmar un campo de la base de datos, el SDK de cifrado de bases de AWS datos solicita al conjunto de claves los materiales de cifrado. Este devuelve una clave en texto no cifrado, una copia de dicha clave cifrada por cada una de las claves de encapsulación del conjunto de claves y una clave MAC que está asociada a la clave de datos. El SDK AWS de cifrado de bases de datos utiliza la clave de texto sin formato para cifrar los datos y, a continuación, elimina la clave de datos de texto sin formato de la memoria lo antes posible. A continuación, el SDK de cifrado de bases de datos de AWS agrega una [descripción](concepts.md#material-description) que incluye las claves de datos cifrados y otra información, como las instrucciones de cifrado y firma. El SDK AWS de cifrado de bases de datos utiliza la clave MAC para calcular los códigos de autenticación de mensajes basados en hash (HMACs) mediante la canonicalización de la descripción del material y de todos los campos marcados con o. `ENCRYPT_AND_SIGN` `SIGN_ONLY`
Al descifrar datos, puede utilizar el mismo conjunto de claves que utilizó para cifrar los datos o uno diferente. Para descifrar los datos, un conjunto de claves de descifrado debe tener acceso al menos una clave de encapsulación del conjunto de claves de cifrado.
El SDK AWS de cifrado de bases de datos pasa las claves de datos cifradas de la descripción del material al conjunto de claves y pide al conjunto de claves que descifre cualquiera de ellas. El conjunto de claves utiliza sus claves de encapsulación para descifrar una de las claves de datos cifradas y devuelve una clave de datos en texto no cifrado. El SDK de cifrado de bases de datos de AWS utiliza la clave de datos en texto no cifrado para descifrar los datos. Si ninguna de las claves de encapsulación del conjunto de claves puede descifrar ninguna de las claves de datos cifradas, se producirá un error en la operación de descifrado.
Puede utilizar un único conjunto de claves o además combinar conjuntos de claves del mismo tipo o de un tipo distinto en un [conjunto de claves múltiple](use-multi-keyring.md). Al cifrar los datos, el conjunto de claves múltiple devuelve una copia de la clave de datos cifrada por todas las claves de encapsulación en todos los conjuntos de claves que componen el conjunto de claves múltiples y una clave MAC que está asociada a la clave de datos. Puede descifrar los datos utilizando un conjunto de claves configurado con cualquiera de las claves de encapsulación del conjunto de claves múltiples.
# AWS KMS llaveros
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
Un conjunto de AWS KMS claves utiliza el cifrado simétrico o el RSA asimétrico [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)para generar, cifrar y descifrar las claves de datos. AWS Key Management Service (AWS KMS) protege las claves KMS y realiza operaciones criptográficas dentro del límite del FIPS. Siempre que sea posible, le recomendamos que utilice un AWS KMS anillo de claves o un anillo de claves con propiedades de seguridad similares.
También puede usar una clave KMS simétrica multirregional en un anillo de claves. AWS KMS Para obtener más detalles y ejemplos sobre el uso de varias AWS KMS keys regiones, consulte. [Uso de varias regiones AWS KMS keys](#config-mrks) Para obtener más información sobre las claves de regiones múltiples, consulte [Uso de claves de multirregiones](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) en la *Guía para desarrolladores de AWS Key Management Service *.
AWS KMS Los llaveros pueden incluir dos tipos de llaves de embalaje:
+ **Clave generadora**: genera una clave de datos en texto no cifrado y la cifra. Un conjunto de claves que cifra datos debe tener una clave generadora.
+ **Claves adicionales**: cifra la clave de datos de texto sin formato que generó la clave del generador. AWS KMS los llaveros pueden tener cero o más claves adicionales.
Debe tener una clave generadora para cifrar los registros. Cuando un conjunto de AWS KMS claves tiene solo una AWS KMS clave, esa clave se usa para generar y cifrar la clave de datos.
Como todos los llaveros, los AWS KMS llaveros se pueden utilizar de forma independiente o en un [llavero múltiple con otros llaveros](use-multi-keyring.md) del mismo tipo o de un tipo diferente.
**Topics**
+ [AWS KMS Permisos necesarios para los llaveros](#kms-keyring-permissions)
+ [Identificarse AWS KMS keys en un AWS KMS llavero](#kms-keyring-id)
+ [Crear un anillo de claves AWS KMS](#kms-keyring-create)
+ [Uso de varias regiones AWS KMS keys](#config-mrks)
+ [Uso de un anillo de claves de detección AWS KMS](#kms-keyring-discovery)
+ [Uso de un anillo de claves de detección AWS KMS regional](#kms-keyring-regional)
## AWS KMS Permisos necesarios para los llaveros
El SDK AWS de cifrado de bases de Cuenta de AWS datos no requiere ni depende de ninguno Servicio de AWS. Sin embargo, para usar un AWS KMS conjunto de claves, necesita tener Cuenta de AWS los siguientes permisos mínimos AWS KMS keys en su conjunto de claves.
+ Para cifrar con un AWS KMS anillo de claves, necesita el GenerateDataKey permiso [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) en la clave del generador. Necesita el permiso [KMS:Encrypt para](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) todas las claves adicionales del anillo de claves. AWS KMS
+ Para descifrar con un AWS KMS anillo de claves, necesita el permiso [KMS:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) en al menos una clave del anillo de claves. AWS KMS
+ Para cifrar con un conjunto de claves múltiples compuesto por AWS KMS anillos de claves, necesita el permiso [kms](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html): en la clave generadora del conjunto de claves del generador. GenerateDataKey Necesita el permiso [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) para el resto de claves de todos los demás conjuntos de claves. AWS KMS
+ Para cifrar con un AWS KMS anillo de claves RSA asimétrico, no necesita [kms: GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) ni [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) porque debe especificar el material de clave pública que desea utilizar para el cifrado al crear el anillo de claves. No se realizan llamadas AWS KMS al cifrar con este anillo de claves. [Para descifrar con un AWS KMS anillo de claves RSA asimétrico, necesita el permiso KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
*Para obtener información detallada sobre los permisos AWS KMS keys, consulte [Autenticación](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) y control de acceso en la Guía para desarrolladores.AWS Key Management Service *
## Identificarse AWS KMS keys en un AWS KMS llavero
Un AWS KMS llavero puede incluir uno o más. AWS KMS keys Para especificar un elemento AWS KMS key en un conjunto de AWS KMS claves, utilice un identificador de AWS KMS clave compatible. Los identificadores clave que puede utilizar para identificar un elemento de un AWS KMS key conjunto de claves varían según la operación y la implementación del idioma. Para obtener más información sobre los identificadores clave de una AWS KMS key, consulte [Identificadores clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) en la *Guía para desarrolladores de AWS Key Management Service *.
Como práctica recomendada, utilice el identificador de clave más práctico que sea práctico para su tarea.
+ Para cifrar con un AWS KMS anillo de claves, puede utilizar un [ID de clave, un ARN de clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id), un [nombre de alias o un [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) de alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) para cifrar los datos[.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN)
**nota**
Si especifica un nombre de alias o un ARN de alias para una clave de KMS en un conjunto de claves de cifrado, la operación de cifrado guarda el ARN de clave actualmente asociado al alias en los metadatos de la clave de datos cifrada. No guarda el alias. Los cambios en el alias no afectan a la clave de KMS utilizada para descifrar las claves de datos cifrados.
+ Para descifrar con un AWS KMS anillo de claves, debe usar un ARN de clave para identificarlo. AWS KMS keys Para obtener más información, consulte [Seleccionar las claves de encapsulamiento](configure.md#config-keys).
+ En un conjunto de claves usado para cifrar y descifrar, debe usar el ARN de una clave para identificar AWS KMS keys.
Al descifrar, el SDK de cifrado de AWS bases de datos busca en el conjunto de AWS KMS claves una AWS KMS key que pueda descifrar una de las claves de datos cifrados. En concreto, el SDK AWS de cifrado de bases de datos utiliza el siguiente patrón para cada clave de datos cifrada de la descripción del material.
+ El SDK AWS de cifrado de bases de datos obtiene la clave ARN de la clave AWS KMS key que cifró la clave de datos de los metadatos de la descripción del material.
+ El SDK AWS de cifrado de bases de datos busca en el conjunto de claves de descifrado un ARN AWS KMS key con una clave coincidente.
+ Si encuentra un ARN AWS KMS key con una clave coincidente en el anillo de claves, el SDK de cifrado de AWS bases de datos solicita usar la clave KMS AWS KMS para descifrar la clave de datos cifrados.
+ De lo contrario, pasa a la siguiente clave de datos cifrada, si la hay.
## Crear un anillo de claves AWS KMS
Puede configurar cada AWS KMS llavero con uno AWS KMS key o varios AWS KMS keys en la misma o en una diferente Cuentas de AWS . Regiones de AWS La AWS KMS key debe ser una clave de cifrado simétrico (`SYMMETRIC_DEFAULT`) o una clave asimétrica RSA KMS. También puede utilizar una [clave KMS de múltiples regiones](#config-mrks) de cifrado simétrico. [Puedes usar uno o más AWS KMS llaveros en un llavero múltiple.](use-multi-keyring.md)
Puede crear un conjunto de AWS KMS claves que cifre y descifre los datos, o puede crear anillos de AWS KMS claves específicos para cifrar o descifrar. Al crear un conjunto de AWS KMS claves para cifrar datos, debe especificar una *clave generadora, que es aquella que se utiliza para generar una clave* de datos en AWS KMS key texto plano y cifrarla. La clave de datos no está relacionada matemáticamente con la clave de KMS. A continuación, si lo desea, puede especificar otras AWS KMS keys que cifren la misma clave de datos en texto plano. Para descifrar un campo cifrado protegido por este anillo de claves, el anillo de claves de descifrado que utilice debe incluir al menos una de las AWS KMS keys definidas en el anillo de claves, o no. AWS KMS keys[(Un anillo de AWS KMS claves sin un número se conoce como anillo de claves de AWS KMS keys detección).AWS KMS](#kms-keyring-discovery)
Todas las claves de encapsulación de un conjunto de claves de cifrado o de varios conjunto de claves deben poder cifrar la clave de datos. Si alguna clave de encapsulación no se cifra, el método de cifrado falla. Como resultado, la persona que llama debe tener los [permisos necesarios](#kms-keyring-permissions) para todas las claves del conjunto de claves. Si utiliza un conjunto de claves de detección para cifrar los datos, solo o en un conjunto de claves múltiple, la operación de cifrado no se realizará correctamente.
Los ejemplos siguientes utilizan el `CreateAwsKmsMrkMultiKeyring` método para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El `CreateAwsKmsMrkMultiKeyring` método crea automáticamente el AWS KMS cliente y garantiza que el conjunto de claves gestione correctamente tanto las claves de una sola región como las de varias regiones. En estos ejemplos, se utiliza una [clave ARNs para identificar las claves](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) del KMS. Para obtener más información, consulte [Identificarse AWS KMS keys en un AWS KMS llavero](#kms-keyring-id)
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = kmsKeyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_mrk_multi_keyring()
.generator(kms_key_id)
.send()
.await?;
```
------
En los ejemplos siguientes, se utiliza el `CreateAwsKmsRsaKeyring` método para crear un AWS KMS anillo de claves con una clave RSA KMS asimétrica. Para crear un AWS KMS anillo de claves RSA asimétrico, proporcione los siguientes valores.
+ `kmsClient`: crea un cliente nuevo AWS KMS
+ `kmsKeyID`: el ARN clave que identifica su clave RSA KMS asimétrica
+ `publicKey`: a ByteBuffer de un archivo PEM codificado en UTF-8 que representa la clave pública de la clave a la que se le pasó `kmsKeyID`
+ `encryptionAlgorithm`: el algoritmo de cifrado debe ser o `RSAES_OAEP_SHA_256` `RSAES_OAEP_SHA_1`
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
CreateAwsKmsRsaKeyringInput.builder()
.kmsClient(KmsClient.create())
.kmsKeyId(rsaKMSKeyArn)
.publicKey(publicKey)
.encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
.build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsRsaKeyringInput = new CreateAwsKmsRsaKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = rsaKMSKeyArn,
PublicKey = publicKey,
EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_rsa_keyring = mpl
.create_aws_kms_rsa_keyring()
.kms_key_id(rsa_kms_key_arn)
.public_key(public_key)
.encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
.kms_client(aws_sdk_kms::Client::new(&sdk_config))
.send()
.await?;
```
------
## Uso de varias regiones AWS KMS keys
Puede utilizar varias regiones AWS KMS keys como claves de empaquetado en el SDK de cifrado de AWS bases de datos. 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
Las claves KMS 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](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) en la *Guía para desarrolladores de AWS Key Management Service *.
Para admitir claves multirregionales, el SDK de cifrado de AWS bases de datos incluye conjuntos de claves. AWS KMS multi-Region-aware El método `CreateAwsKmsMrkMultiKeyring` admite claves de una sola región y de múltiples regiones.
+ En el caso de las claves de una sola región, el multi-Region-aware símbolo se comporta igual que el anillo de claves de una sola región. AWS KMS Intenta descifrar el texto cifrado únicamente con la clave de región única que cifró los datos. Para simplificar su experiencia con el conjunto de AWS KMS claves, le recomendamos que utilice `CreateAwsKmsMrkMultiKeyring` este método siempre que utilice una clave KMS de cifrado simétrico.
+ En el caso de las claves multirregionales, el multi-Region-aware símbolo intenta descifrar el texto cifrado con la misma clave multirregional que cifró los datos o con la clave multirregional relacionada en la región que especifique.
En los multi-Region-aware anillos de claves que contienen más de una clave KMS, puede especificar varias claves de una o varias regiones. Sin embargo, solo puede especificar una clave de cada conjunto de claves de múltiples regiones 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.
En los siguientes ejemplos, se crea un AWS KMS anillo de claves con una clave KMS multirregional. Los ejemplos especifican una clave multirregional como clave generadora y una clave de región única como clave secundaria.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput =
CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(multiRegionKeyArn)
.kmsKeyIds(Collections.singletonList(kmsKeyArn))
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = multiRegionKeyArn,
KmsKeyIds = new List { kmsKeyArn }
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(multiRegion_key_arn)
.kms_key_ids(vec![key_arn.to_string()])
.send()
.await?;
```
------
Si utiliza conjuntos de AWS KMS claves multirregionales, puede descifrar el texto cifrado en modo estricto o en modo de descubrimiento. Para descifrar el texto cifrado en modo estricto, cree una instancia del símbolo multi-Region-aware con la clave ARN de la clave multirregión relacionada en la región en la que esté descifrando el texto cifrado. Si especifica la clave ARN de una clave multirregional relacionada en una región diferente (por ejemplo, la región en la que se cifró el registro), el multi-Region-aware símbolo realizará una llamada entre regiones para dicha clave. AWS KMS key
Al descifrar en modo estricto, el multi-Region-aware símbolo requiere una clave ARN. Solo acepta un ARN de clave de cada conjunto de claves de varias regiones relacionadas.
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, consulte.) [Uso de un anillo de claves de detección AWS KMS](#kms-keyring-discovery)
Si ha cifrado con una clave multirregional, el multi-Region-aware símbolo en el modo de descubrimiento intentará descifrarse 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, el SDK de cifrado AWS de bases de datos no intentará realizar una llamada entre regiones para obtener la clave multirregional utilizada para el cifrado.
## Uso de un anillo de claves de detección AWS KMS
Al descifrar, se recomienda especificar las claves de empaquetado que puede usar el SDK de cifrado AWS de bases de datos. Para seguir esta práctica recomendada, utilice un conjunto de claves de AWS KMS descifrado que limite las claves de AWS KMS empaquetado a las que especifique. Sin embargo, también puede crear un anillo de *claves de AWS KMS detección, es decir, un anillo* de AWS KMS claves que no especifique ninguna clave de empaquetado.
El SDK AWS de cifrado de bases de datos proporciona un conjunto de claves de AWS KMS detección estándar y un conjunto de claves de detección para claves de varias regiones. AWS KMS Para obtener información sobre cómo usar claves de varias regiones con el SDK de cifrado de bases de datos de AWS , consulte [Uso de varias regiones AWS KMS keys](#config-mrks).
Como no especifica ninguna clave de encapsulación, un conjunto de claves de detección no puede cifrar los datos. Si utiliza un conjunto de claves de detección para cifrar los datos, solo o en un conjunto de claves múltiple, la operación de cifrado no se realizará correctamente.
Al descifrar, un conjunto de claves de detección permite al SDK de cifrado de AWS bases de datos solicitar AWS KMS el descifrado de cualquier clave de datos cifrada utilizando la clave AWS KMS key que la cifró, independientemente de quién sea su propietario o tenga acceso a ella. AWS KMS key La llamada se realiza correctamente solo si el intermediario tiene permiso de `kms:Decrypt` sobre la AWS KMS key.
**importante**
Si incluye un conjunto de claves de AWS KMS detección en un conjunto de claves de descifrado [múltiple, el conjunto de claves](use-multi-keyring.md) de descubrimiento anula todas las restricciones de claves de KMS especificadas en otros conjuntos de claves del conjunto de claves múltiples. El conjunto de claves múltiples se comporta como el menos restrictivo. Si utiliza un conjunto de claves de detección para cifrar datos, solo o en un conjunto de claves múltiple, la operación de cifrado no se realizará correctamente
El SDK de cifrado de AWS bases de datos incluye un conjunto de claves de detección para mayor comodidad. AWS KMS No obstante, recomendamos que utilice un conjunto de claves más limitado siempre que sea posible por los siguientes motivos.
+ **Autenticidad**: un AWS KMS conjunto de claves de detección puede utilizar cualquier clave AWS KMS key que se haya utilizado para cifrar una clave de datos en la descripción del material, siempre que la persona que llama tenga permiso para usarla para descifrarla. AWS KMS key Es posible que esta no sea la AWS KMS key que la persona que llama pretende usar. Por ejemplo, es posible que una de las claves de datos cifradas se haya cifrado con un sistema menos seguro AWS KMS key que cualquiera pueda utilizar.
+ **Latencia y rendimiento**: un conjunto de claves de AWS KMS detección puede ser considerablemente más lento que otros, ya que el SDK de cifrado de AWS bases de datos intenta descifrar todas las claves de datos cifradas, incluidas las cifradas en otras regiones y AWS KMS keys en otras regiones, Cuentas de AWS y AWS KMS keys que la persona que llama no tiene permiso para utilizarlas para el descifrado.
[Si utiliza un conjunto de claves de detección, le recomendamos que utilice un [*filtro de detección*](configure.md#config-discovery) para limitar las claves de KMS que se pueden usar a las de las particiones Y especificadas. Cuentas de AWS](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) Para obtener ayuda para encontrar el ID y la partición de [su cuenta, consulte Sus Cuenta de AWS identificadores](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) y [el formato ARN en. *Referencia general de AWS*](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)
Los siguientes ejemplos de código crean una instancia de un conjunto de claves de AWS KMS detección con un filtro de detección que limita las claves de KMS que el SDK de cifrado de AWS bases de datos puede utilizar a las de la partición y la `aws` cuenta de ejemplo. `111122223333`
Antes de usar este código, sustituya los valores del ejemplo Cuenta de AWS y de la partición por valores válidos para la partición y. Cuenta de AWS Si sus claves de KMS se encuentran en regiones de China, use el valor de la partición de `aws-cn`. Si las claves KMS están en AWS GovCloud (US) Regions, use el valor de la partición de `aws-us-gov`. Para todas las demás Regiones de AWS, utilice el valor de la partición de `aws`.
------
#### [ Java ]
```
// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.send()
.await?;
```
------
## Uso de un anillo de claves de detección AWS KMS regional
Un conjunto de *claves de detección AWS KMS regional* es un conjunto de claves que no especifica las claves ARNs de KMS. En su lugar, permite que el SDK AWS de cifrado de bases de datos descifre utilizando únicamente las claves de KMS, en particular. Regiones de AWS
Al descifrar con un conjunto de claves de detección AWS KMS regional, el SDK de cifrado de AWS bases de datos descifra cualquier clave de datos cifrada que se haya cifrado con una AWS KMS key de las especificadas. Región de AWS Para tener éxito, la persona que llama debe tener `kms:Decrypt` permiso en al menos una de las claves de datos especificadas Región de AWS que cifraron una clave de datos. AWS KMS keys
Al igual que otros conjuntos de claves de detección, el conjunto de claves de detección regional no tiene ningún efecto sobre el cifrado. Solo funciona cuando se descifran campos cifrados. Si utiliza un conjunto de claves de detección regional en un conjunto de claves múltiples que se utiliza para cifrar y descifrar, solo es efectivo al descifrar. Si utiliza un conjunto de claves de detección multirregional para cifrar los datos, solo o en un conjunto de claves múltiples, la operación de cifrado no se realizará correctamente.
**importante**
Si incluye un conjunto de claves de detección AWS KMS regional en un conjunto de claves de descifrado [múltiple, el conjunto de claves](use-multi-keyring.md) de detección regional anula todas las restricciones de claves de KMS especificadas en otros anillos de claves del conjunto de claves múltiples. El conjunto de claves múltiples se comporta como el menos restrictivo. Cuando se utiliza un conjunto de claves de detección de AWS KMS en un conjunto de claves múltiple, no tiene ningún efecto sobre el cifrado.
El conjunto de claves de detección regional del SDK de cifrado de AWS bases de datos solo intenta descifrar las claves de KMS de la región especificada. Cuando se utiliza un conjunto de claves de detección, se configura la región en el cliente. AWS KMS Estas implementaciones del SDK de cifrado de AWS bases de datos no filtran las claves de KMS por región, pero AWS KMS no permiten descifrar las claves de KMS de fuera de la región especificada.
Si utiliza un conjunto de claves de detección, le recomendamos que utilice un *filtro de detección* para limitar las claves de KMS utilizadas en el descifrado a las de las particiones Y especificadas. Cuentas de AWS
Por ejemplo, el código siguiente crea un conjunto de claves de detección AWS KMS regional con un filtro de detección. Este conjunto de claves limita el SDK de cifrado de AWS bases de datos a las claves KMS de la cuenta 111122223333 de la región EE.UU. Oeste (Oregón) (us-west-2).
------
#### [ Java ]
```
// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.regions("us-west-2")
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter,
Regions = us-west-2
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.regions(us-west-2)
.send()
.await?;
```
------
# AWS KMS Llaveros jerárquicos
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de AWS datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
**nota**
A partir del 24 de julio de 2023, no se admiten las claves de rama creadas durante la versión preliminar para desarrolladores. Crea nuevas claves de rama para seguir usando el almacén de claves que creaste durante la versión preliminar para desarrolladores.
Con el conjunto de claves AWS KMS jerárquico, puede proteger sus materiales criptográficos con una clave KMS de cifrado simétrico sin tener que llamar AWS KMS cada vez que cifra o descifra un registro. Es una buena opción para las aplicaciones que necesitan minimizar las llamadas y las aplicaciones que pueden reutilizar algunos materiales criptográficos sin infringir sus requisitos de seguridad. AWS KMS
El anillo de claves jerárquico es una solución de almacenamiento en caché de materiales criptográficos que reduce el número de AWS KMS llamadas mediante el uso de *claves de rama AWS KMS * protegidas que se conservan en una tabla de Amazon DynamoDB y, a continuación, el almacenamiento en caché local de los materiales de clave de rama utilizados en las operaciones de cifrado y descifrado. La tabla de DynamoDB sirve como almacén de claves que administra y protege las claves de rama. Almacena la clave de rama activa y todas las versiones anteriores de la clave de rama. La clave de rama *activa* es la versión más reciente de la clave de rama. El conjunto de claves jerárquico utiliza una clave de cifrado de datos única para cada solicitud de cifrado y cifra cada clave de cifrado de datos con una clave de empaquetado única derivada de la clave de rama activa. El conjunto de claves jerárquico depende de la jerarquía establecida entre las claves de ramificación activas y las claves de encapsulamiento derivadas.
El conjunto de claves jerárquico suele utilizar cada versión de clave de rama para satisfacer múltiples solicitudes. Sin embargo, usted controla el grado en que se reutilizan las claves de rama activas y determina la frecuencia con la que se gira la clave de rama activa. La versión activa de la clave de rama permanece activa hasta que la [gire](rotate-branch-key.md). Las versiones anteriores de la clave de rama activa no se utilizarán para realizar operaciones de cifrado, pero sí se pueden consultar y utilizar en las operaciones de descifrado.
Al crear una instancia del conjunto de claves jerárquico, se crea una caché local. Se especifica un [límite de caché](#cache-limit) que define el tiempo máximo durante el que los materiales de las claves de ramificación se almacenan en la caché local antes de que caduquen y se expulsen de la caché. El conjunto de claves jerárquico realiza una AWS KMS llamada para descifrar la clave de bifurcación y reunir los materiales de la clave de bifurcación la primera vez que se especifica a en una operación. `branch-key-id` A continuación, los materiales de la clave de rama se almacenan en la memoria caché local y se reutilizan para todas las operaciones de cifrado y descifrado que la `branch-key-id` especifique hasta que caduque el límite de la memoria caché. Almacenar los materiales de las claves de rama en la memoria caché local reduce las llamadas. AWS KMS Por ejemplo, considere un límite de caché de 15 minutos. Si realizas 10 000 operaciones de cifrado dentro de ese límite de caché, el conjunto de [AWS KMS claves tradicional necesitaría](use-kms-keyring.md) realizar 10 000 AWS KMS llamadas para cumplir con 10 000 operaciones de cifrado. Si tiene uno activo`branch-key-id`, el conjunto de claves jerárquico solo necesita realizar una AWS KMS llamada para realizar 10 000 operaciones de cifrado.
La memoria caché local separa los materiales de cifrado de los materiales de descifrado. Los materiales de cifrado se ensamblan a partir de la clave de rama activa y se reutilizan en todas las operaciones de cifrado hasta que caduque el límite de la memoria caché. Los materiales de descifrado se recopilan a partir del identificador de la clave de ramificación y la versión que se identifica en los metadatos del campo cifrado, y se reutilizan para todas las operaciones de descifrado relacionadas con el identificador y la versión de la clave de bifurcación hasta que venza el límite de memoria caché. La memoria caché local puede almacenar varias versiones de la misma clave de rama a la vez. Cuando la caché local está configurada para usar una[branch key ID supplier](#branch-key-id-supplier), también puede almacenar materiales de claves de rama de varias claves de rama activas a la vez.
**nota**
Todas las menciones del conjunto de *claves jerárquico en el* SDK de cifrado de AWS bases de datos se refieren al conjunto de claves AWS KMS jerárquico.
**Topics**
+ [Funcionamiento](#how-hierarchical-keyring-works)
+ [Requisitos previos](#hierarchical-keyring-prereqs)
+ [Permisos necesarios](#hierarchical-keyring-permissions)
+ [Elige una memoria caché](#hierarchical-keyring-caches)
+ [Crear un conjunto de claves jerárquico](#initialize-hierarchical-keyring)
+ [Uso del conjunto de claves jerárquico para el cifrado para búsquedas](#searchable-encryption-hierarchical-keyrings)
## Funcionamiento
Los siguientes tutoriales describen cómo el conjunto de claves jerárquico reúne los materiales de cifrado y descifrado, y las diferentes llamadas que realiza el conjunto de claves para las operaciones de cifrado y descifrado. Para obtener detalles técnicos sobre los procesos de derivación de claves de ajuste y cifrado de claves de datos de texto no cifrado, consulte [Detalles técnicos del conjunto de claves jerárquico de AWS KMS](reference.md#hierarchical-keyring-details).
**Cifra y firma**
El siguiente tutorial describe cómo el conjunto de claves jerárquico reúne los materiales de cifrado y obtiene una clave de encapsulamiento única.
1. El método de cifrado solicita materiales de cifrado al conjunto de claves jerárquico. El conjunto de claves genera una clave de datos en texto plano y, a continuación, comprueba si hay materiales de clave de ramificación válidos en la caché local para generar la clave de empaquetado. **Si hay materiales de clave de bifurcación válidos, el llavero continúa con el paso 4.**
1. Si no hay ningún material de clave de bifurcación válido, el conjunto de claves jerárquico consulta el almacén de claves para encontrar la clave de bifurcación activa.
1. El almacén de claves llama AWS KMS para descifrar la clave de rama activa y devuelve la clave de rama activa en texto plano. Los datos que identifican la clave de rama activa se serializan para proporcionar datos autenticados adicionales (AAD) en la llamada de descifrado a AWS KMS.
1. El almacén de claves devuelve la clave de rama en texto simple y los datos que la identifican, como la versión de la clave de rama.
1. El conjunto de claves jerárquico reúne los materiales de las claves de rama (las versiones de las claves de rama y las claves de rama en texto no cifrado) y guarda una copia de los mismos en la memoria caché local.
1. El conjunto de claves jerárquico obtiene una clave de ajuste única de la clave de rama de texto simple y de una sal aleatoria de 16 bytes. Utiliza la clave de encapsulación derivada para cifrar una copia de la clave de datos de texto no cifrado.
El método de cifrado utiliza los materiales de cifrado para cifrar y firmar el registro. Para obtener más información sobre cómo se cifran y firman los registros en el SDK de cifrado de bases de datos de AWS , consulte [Encrypt and sign](how-it-works.md#encrypt-and-sign).
**Descifrado y verificación**
En el siguiente tutorial, se describe cómo el conjunto de claves jerárquico reúne los materiales de descifrado y descifra la clave de datos cifrados.
1. El método de descifrado identifica la clave de datos cifrada en el campo de descripción del material del registro cifrado y la pasa al conjunto de claves jerárquico.
1. El conjunto de claves jerárquico deserializa los datos que identifican la clave de datos cifrada, incluida la versión de la clave de rama, la sal de 16 bytes y otra información que describe cómo se cifró la clave de datos.
Para obtener más información, consulte [AWS KMS Detalles técnicos del llavero jerárquico](reference.md#hierarchical-keyring-details).
1. El conjunto de claves jerárquico comprueba si hay materiales de clave de rama válidos en la caché local que coincidan con la versión de clave de rama identificada en el **paso 2**. Si hay materiales de clave de rama válidos, el conjunto de claves continúa con el **paso 6**.
1. **Si no hay ningún material de clave de rama válido, el conjunto de claves jerárquico consulta en el almacén de claves la clave de rama que coincida con la versión de clave de rama identificada en el paso 2.**
1. El almacén de claves llama AWS KMS para descifrar la clave de bifurcación y devuelve la clave de bifurcación activa en texto plano. Los datos que identifican la clave de rama activa se serializan para proporcionar datos autenticados adicionales (AAD) en la llamada de descifrado a AWS KMS.
1. El almacén de claves devuelve la clave de rama en texto simple y los datos que la identifican, como la versión de la clave de rama.
1. El conjunto de claves jerárquico reúne los materiales de las claves de rama (las versiones de las claves de rama y las claves de rama en texto no cifrado) y guarda una copia de los mismos en la memoria caché local.
1. El conjunto de claves jerárquico utiliza los materiales de clave de rama ensamblados y la sal de 16 bytes identificada en el **paso 2** para reproducir la clave de encapsulamiento única que cifró la clave de datos.
1. El conjunto de claves jerárquico utiliza la clave de encapsulación para descifrar la clave de datos y devuelve la clave de datos en texto no cifrado.
El método de descifrado utiliza los materiales de descifrado y la clave de datos de texto no cifrado para descifrar y verificar el registro. Para obtener más información sobre cómo se descifran y verifican los registros en el SDK de cifrado AWS de bases de datos, consulte [Descifrar](how-it-works.md#decrypt-and-verify) y verificar.
## Requisitos previos
Antes de crear y utilizar un conjunto de claves jerárquico, asegúrese de que se cumplen los siguientes requisitos previos.
+ Usted, o el administrador del almacén de claves, ha [creado un almacén de claves](create-keystore.md) y [ha creado al menos una clave de rama activa](create-branch-keys.md).
+ Ha [configurado las acciones de su almacén de claves](keystore-actions.md#config-keystore-actions).
**nota**
La forma en que configure las acciones del almacén de claves determina qué operaciones puede realizar y qué claves de KMS puede utilizar el conjunto de claves jerárquico. Para obtener más información, consulte Acciones del [almacén de claves](keystore-actions.md).
+ Dispone de los AWS KMS permisos necesarios para acceder y utilizar las llaves del almacén de claves y de la sucursal. Para obtener más información, consulte [Permisos necesarios](#hierarchical-keyring-permissions).
+ Ha revisado los tipos de caché compatibles y ha configurado el tipo de caché que mejor se adapta a sus necesidades. Para obtener más información, consulte [Elige una memoria caché](#hierarchical-keyring-caches)
## Permisos necesarios
El SDK de cifrado de AWS bases de Cuenta de AWS datos no requiere ni depende de ninguno Servicio de AWS. Sin embargo, para usar un conjunto de claves jerárquico, necesita Cuenta de AWS los siguientes permisos mínimos en los AWS KMS key cifrados simétricos de su almacén de claves.
+ [Para cifrar y descifrar datos con el anillo de claves jerárquico, necesita KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)
Para obtener más información sobre cómo controlar el acceso a las llaves de su sucursal y al almacén de claves, consulte[Implementación de permisos de privilegio mínimo](keystore-least-privilege.md).
## Elige una memoria caché
El conjunto de claves jerárquico reduce la cantidad de llamadas AWS KMS realizadas al almacenar en caché local los materiales de las claves de sucursal que se utilizan en las operaciones de cifrado y descifrado. Antes de [crear su conjunto de claves jerárquico,](#initialize-hierarchical-keyring) debe decidir qué tipo de caché desea utilizar. Puedes usar la caché predeterminada o personalizarla para que se adapte mejor a tus necesidades.
El conjunto de claves jerárquico admite los siguientes tipos de caché:
+ [Caché predeterminada](#cache-default)
+ [MultiThreaded caché](#cache-multithreaded)
+ [StormTracking caché](#cache-stormtracking)
+ [Caché compartida](#cache-shared)
### Caché predeterminada
La mayoría de usuarios no necesitará modificar sus requisitos de subprocesamiento. La caché predeterminada está diseñada para admitir entornos con muchos subprocesos múltiples. Cuando caduca una entrada de materiales de clave de bifurcación, la caché predeterminada impide que varios subprocesos llamen, AWS KMS ya que notifica a un subproceso que la entrada de materiales de clave de bifurcación va a caducar con 10 segundos de antelación. Esto garantiza que solo un subproceso envíe una solicitud AWS KMS para actualizar la caché.
La memoria StormTracking caché predeterminada y la caché admiten el mismo modelo de subprocesos, pero solo es necesario especificar la capacidad de entrada para utilizar la memoria caché predeterminada. Para personalizaciones de caché más detalladas, utilice la. [StormTracking caché](#cache-stormtracking)
A menos que desee personalizar el número de entradas de materiales clave de rama que se pueden almacenar en la memoria caché local, no necesita especificar un tipo de memoria caché al crear el conjunto de claves jerárquico. Si no especifica un tipo de caché, el conjunto de claves jerárquico utiliza el tipo de caché predeterminado y establece la capacidad de entrada en 1000.
Para personalizar la caché predeterminada, especifique los siguientes valores:
+ **Capacidad de entrada**: limita el número de entradas de materiales clave de rama que se pueden almacenar en la caché local.
------
#### [ Java ]
```
.cache(CacheType.builder()
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType defaultCache = new CacheType
{
Default = new DefaultCache{EntryCapacity = 100}
};
```
------
#### [ Rust ]
```
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
```
------
### MultiThreaded caché
La MultiThreaded memoria caché se puede utilizar de forma segura en entornos de subprocesos múltiples, pero no proporciona ninguna funcionalidad para minimizar las llamadas de Amazon AWS KMS DynamoDB. Como resultado, cuando una entrada de materiales clave de rama caduque, se notificará a todos los subprocesos al mismo tiempo. Esto puede provocar varias AWS KMS llamadas para actualizar la memoria caché.
Para usar la MultiThreaded caché, especifique los siguientes valores:
+ **Capacidad de entrada**: limita el número de entradas de materiales clave de rama que se pueden almacenar en la caché local.
+ **Tamaño de la cola de poda de entrada**: define el número de entradas que se deben podar si se alcanza la capacidad de entrada.
------
#### [ Java ]
```
.cache(CacheType.builder()
.MultiThreaded(MultiThreadedCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType multithreadedCache = new CacheType
{
MultiThreaded = new MultiThreadedCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1
}
};
```
------
#### [ Rust ]
```
CacheType::MultiThreaded(
MultiThreadedCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.build()?)
```
------
### StormTracking caché
La StormTracking memoria caché está diseñada para soportar entornos con muchos subprocesos múltiples. Cuando una entrada de materiales de clave de rama caduca, la StormTracking caché evita que varios subprocesos AWS KMS llamen, ya que notifica a un subproceso que la entrada de materiales de clave de rama va a caducar con antelación. Esto garantiza que solo un subproceso envíe una solicitud AWS KMS para actualizar la caché.
Para usar la StormTracking caché, especifique los siguientes valores:
+ **Capacidad de entrada**: limita el número de entradas de materiales clave de rama que se pueden almacenar en la caché local.
Valor predeterminado: 1000 entradas
+ **Tamaño de la cola de poda de entrada**: define el número de entradas de materiales clave para la rama que se deben podar a la vez.
Valor predeterminado: 1 entrada
+ **Período de gracia**: define el número de segundos antes de la caducidad durante los que se intenta actualizar los materiales clave de la rama.
Valor predeterminado: 10 segundos
+ **Intervalo de gracia**: define el número de segundos entre los intentos de actualizar los materiales clave de la rama.
Valor predeterminado: 1 segundo
+ **Amplificador**: define el número de intentos simultáneos que se pueden realizar para actualizar los materiales clave de la rama.
Valor predeterminado: 20 intentos
+ **En tiempo de vuelo hasta la vida útil (TTL)**: define el número de segundos hasta que se agota el tiempo de espera para intentar actualizar los materiales clave de la rama. Cada vez que la caché devuelve `NoSuchEntry` en respuesta a un `GetCacheEntry`, se considera que esa clave de rama está *en tránsito* hasta que se escribe la misma clave con una entrada `PutCache`.
Valor predeterminado: 10 segundos
+ **Suspender**: define el número de segundos que un hilo debe permanecer inactivo si `fanOut` se supera.
Valor predeterminado: 20 milisegundos
------
#### [ Java ]
```
.cache(CacheType.builder()
.StormTracking(StormTrackingCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.gracePeriod(10)
.graceInterval(1)
.fanOut(20)
.inFlightTTL(10)
.sleepMilli(20)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType stormTrackingCache = new CacheType
{
StormTracking = new StormTrackingCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1,
FanOut = 20,
GraceInterval = 1,
GracePeriod = 10,
InFlightTTL = 10,
SleepMilli = 20
}
};
```
------
#### [ Rust ]
```
CacheType::StormTracking(
StormTrackingCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.grace_period(10)
.grace_interval(1)
.fan_out(20)
.in_flight_ttl(10)
.sleep_milli(20)
.build()?)
```
------
### Caché compartida
De forma predeterminada, el conjunto de claves jerárquico crea una nueva caché local cada vez que se crea una instancia del conjunto de claves. Sin embargo, la caché compartida puede ayudar a conservar la memoria, ya que permite compartir una caché entre varios conjuntos de claves jerárquicos. En lugar de crear una nueva caché de materiales criptográficos para cada conjunto de claves jerárquico que cree una instancia, la caché compartida solo almacena una caché en la memoria, que puede ser utilizada por todos los anillos de claves jerárquicos que hacen referencia a ella. La caché compartida ayuda a optimizar el uso de la memoria al evitar la duplicación de materiales criptográficos entre los conjuntos de claves. En cambio, los conjuntos de claves jerárquicos pueden acceder a la misma caché subyacente, lo que reduce el consumo total de memoria.
Al crear la caché compartida, se sigue definiendo el tipo de caché. Puede especificar un [Caché predeterminada](#cache-default)[MultiThreaded caché](#cache-multithreaded), o [StormTracking caché](#cache-stormtracking) como tipo de caché, o sustituirlo por cualquier caché personalizada compatible.
**Particiones**
Varios conjuntos de claves jerárquicos pueden utilizar una única caché compartida. **Al crear un conjunto de claves jerárquico con una caché compartida, puede definir un ID de partición opcional.** El ID de partición distingue qué anillo de claves jerárquico está escribiendo en la memoria caché. Si dos anillos de claves jerárquicos hacen referencia al mismo ID de partición y al mismo ID de clave de rama[logical key store name](create-keystore.md#logical-key-store-name), los dos anillos de claves compartirán las mismas entradas de caché en la caché. Si crea dos anillos de claves jerárquicos con la misma caché compartida, pero con una partición diferente IDs, cada conjunto de claves solo accederá a las entradas de la caché desde su propia partición designada dentro de la caché compartida. Las particiones actúan como divisiones lógicas dentro de la caché compartida, lo que permite que cada conjunto de claves jerárquico funcione de forma independiente en la partición designada, sin interferir con los datos almacenados en la otra partición.
Si tiene intención de reutilizar o compartir las entradas de la caché de una partición, debe definir su propio identificador de partición. Al pasar el ID de la partición a su conjunto de claves jerárquico, el conjunto de claves puede reutilizar las entradas de la caché que ya están presentes en la caché compartida, sin tener que recuperar y volver a autorizar los materiales de las claves de rama. Si no especifica un identificador de partición, se asignará automáticamente un identificador de partición único al conjunto de claves cada vez que cree una instancia del conjunto de claves jerárquico.
Los siguientes procedimientos muestran cómo crear una caché compartida con el [tipo de caché predeterminado](#cache-default) y pasarla a un anillo de claves jerárquico.
1. Cree una `CryptographicMaterialsCache` (CMC) mediante la [biblioteca de proveedores de materiales](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
------
#### [ Java ]
```
// Instantiate the MPL
final MaterialProviders matProv =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a CacheType object for the Default cache
final CacheType cache =
CacheType.builder()
.Default(DefaultCache.builder().entryCapacity(100).build())
.build();
// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
CreateCryptographicMaterialsCacheInput.builder()
.cache(cache)
.build();
final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ C\$1 / .NET ]
```
// Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };
// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};
var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ Rust ]
```
// Instantiate the MPL
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create a CacheType object for the default cache
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
// Create a CMC using the default cache
let shared_cryptographic_materials_cache: CryptographicMaterialsCacheRef = mpl.
create_cryptographic_materials_cache()
.cache(cache)
.send()
.await?;
```
------
1. Cree un `CacheType` objeto para la caché compartida.
Pase lo `sharedCryptographicMaterialsCache` que creó en el **paso 1** al nuevo `CacheType` objeto.
------
#### [ Java ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
CacheType.builder()
.Shared(sharedCryptographicMaterialsCache)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
```
------
#### [ Rust ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
let shared_cache: CacheType = CacheType::Shared(shared_cryptographic_materials_cache);
```
------
1. Pasa el `sharedCache` objeto del **paso 2** a tu llavero jerárquico.
Al crear un conjunto de claves jerárquico con una caché compartida, si lo desea, puede definir un conjunto de claves jerárquico `partitionID` para compartir las entradas de la caché entre varios anillos de claves jerárquicos. Si no especifica un identificador de partición, el conjunto de claves jerárquico asigna automáticamente al conjunto de claves un identificador de partición único.
**nota**
Sus conjuntos de claves jerárquicos compartirán las mismas entradas de caché en una caché compartida si crea dos o más conjuntos de claves que hagan referencia al mismo identificador de partición y al mismo identificador de clave de rama. [logical key store name](create-keystore.md#logical-key-store-name) Si no desea que varios conjuntos de claves compartan las mismas entradas de caché, debe utilizar un identificador de partición único para cada conjunto de claves jerárquico.
En el siguiente ejemplo, se crea un conjunto de claves jerárquico con un límite [branch key ID supplier](#branch-key-id-supplier) de [memoria caché](#cache-limit) de 600 segundos. Para obtener más información sobre los valores definidos en la siguiente configuración de anillo de claves jerárquico, consulte. [Crear un conjunto de claves jerárquico](#initialize-hierarchical-keyring)
------
#### [ Java ]
```
// Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(sharedCache)
.partitionID(partitionID)
.build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create the Hierarchical keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
Cache = sharedCache,
TtlSeconds = 600,
PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
```
------
#### [ Rust ]
```
// Create the Hierarchical keyring
let keyring1 = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store1)
.branch_key_id(branch_key_id.clone())
// CryptographicMaterialsCacheRef is an Rc (Reference Counted), so if you clone it to
// pass it to different Hierarchical Keyrings, it will still point to the same
// underlying cache, and increment the reference count accordingly.
.cache(shared_cache.clone())
.ttl_seconds(600)
.partition_id(partition_id.clone())
.send()
.await?;
```
------
## Crear un conjunto de claves jerárquico
Para crear un conjunto de claves jerárquico, debe proporcionar los siguientes valores:
+ **Un nombre de almacén de claves**
El nombre de la tabla de DynamoDB que usted o el administrador del almacén de claves crearon para que sirviera de almacén de claves.
+
**Un tiempo de vida límite de la memoria caché (TTL)**
La cantidad de tiempo en segundos que se puede utilizar una entrada de material de clave de la memoria caché local antes de que caduque. El límite de caché TTL determina la frecuencia con la que el cliente llama AWS KMS para autorizar el uso de las claves de sucursal. El valor debe ser mayor que cero. Una vez expirado el límite de caché TTL, la entrada no se sirve nunca y se desalojará de la caché local.
+ **Un identificador de clave de rama**
Puede configurar de forma estática la clave de sucursal `branch-key-id` que identifique una única clave de rama activa en su almacén de claves o proporcionar un proveedor de identificadores de clave de sucursal.
El *proveedor del identificador de la clave de sucursal* utiliza los campos almacenados en el contexto de cifrado para determinar qué clave de sucursal se necesita para descifrar un registro. De forma predeterminada, solo las claves de partición y clasificación se incluyen en el contexto de cifrado. Sin embargo, puede utilizar la [acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica](concepts.md#crypt-actions) para incluir campos adicionales en el contexto de cifrado.
Recomendamos encarecidamente utilizar un proveedor de ID de clave de sucursal para las bases de datos multiusuario, en las que cada inquilino tiene su propia clave de sucursal. Puedes usar el identificador de clave de sucursal del proveedor para crear un nombre descriptivo para tu clave IDs de sucursal y así poder reconocer fácilmente el identificador de clave de sucursal correcto para un inquilino específico. Por ejemplo, el nombre descriptivo le permite hacer referencia a una clave de rama como `tenant1` en lugar de`b3f61619-4d35-48ad-a275-050f87e15122`.
Para las operaciones de descifrado, puede configurar de forma estática un único conjunto de claves jerárquicas para restringir el descifrado a un único usuario, o puede utilizar el proveedor del identificador de clave de sucursal para identificar qué inquilino es responsable de descifrar un registro.
+ **(Opcional) Una caché**
Si desea personalizar el tipo de caché o el número de entradas de materiales clave de rama que se pueden almacenar en la caché local, especifique el tipo de caché y la capacidad de entrada al inicializar el conjunto de claves.
El conjunto de claves jerárquico admite los siguientes tipos de caché: predeterminada MultiThreaded StormTracking, y compartida. Para obtener más información y ejemplos que demuestren cómo definir cada tipo de caché, consulte. [Elige una memoria caché](#hierarchical-keyring-caches)
Si no especifica una caché, el conjunto de claves jerárquico utiliza automáticamente el tipo de caché predeterminado y establece la capacidad de entrada en 1000.
+ **(Opcional) Un ID de partición**
Si especifica el[Caché compartida](#cache-shared), puede definir opcionalmente un ID de partición. El ID de partición distingue qué conjunto de claves jerárquico está escribiendo en la memoria caché. Si pretende reutilizar o compartir las entradas de la caché de una partición, debe definir su propio ID de partición. Puede especificar cualquier cadena para el ID de la partición. Si no especifica un identificador de partición, se asigna automáticamente un identificador de partición único al conjunto de claves en el momento de la creación.
Para obtener más información, consulte [Partitions](#shared-cache-partitions).
**nota**
Sus conjuntos de claves jerárquicos compartirán las mismas entradas de caché en una caché compartida si crea dos o más conjuntos de claves que hagan referencia al mismo identificador de partición y al mismo identificador de clave de [logical key store name](create-keystore.md#logical-key-store-name) rama. Si no desea que varios conjuntos de claves compartan las mismas entradas de caché, debe utilizar un identificador de partición único para cada conjunto de claves jerárquico.
+ **(Opcional) Una lista de tokens de concesión**
Si controla el acceso a la clave KMS de su conjunto de claves jerárquico mediante [concesiones](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), debe proporcionar todos los tokens de concesión necesarios al inicializar el conjunto de claves.
### Cree un conjunto de claves jerárquico con un ID de clave de rama estático
Los siguientes ejemplos muestran cómo crear un anillo de claves jerárquico con un identificador de clave de rama estático[Caché predeterminada](#cache-default), el TTL con un límite de caché de 600 segundos.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyId(branch-key-id)
.ttlSeconds(600)
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(branch_key_store_name)
.ttl_seconds(600)
.send()
.await?;
```
------
### Cree un conjunto de claves jerárquico con un proveedor de ID de clave de sucursal
Los siguientes procedimientos muestran cómo crear un anillo de claves jerárquico con un proveedor de ID de sucursal.
1. Cree un proveedor de ID de clave de sucursal
En el siguiente ejemplo, se crean nombres descriptivos para las dos claves de rama creadas en el **paso 1** y se pide `CreateDynamoDbEncryptionBranchKeyIdSupplier` la creación de un proveedor de ID de clave de rama con el SDK de cifrado de AWS bases de datos para el cliente DynamoDB.
------
#### [ Java ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
private static String branchKeyIdForTenant1;
private static String branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this.branchKeyIdForTenant1 = tenant1Id;
this.branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
.DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
.build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
.ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
.build()).branchKeyIdSupplier();
```
------
#### [ C\$1 / .NET ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
private String _branchKeyIdForTenant1;
private String _branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this._branchKeyIdForTenant1 = tenant1Id;
this._branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
{
DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
}).BranchKeyIdSupplier;
```
------
#### [ Rust ]
```
// Create friendly names for each branch_key_id
pub struct ExampleBranchKeyIdSupplier {
branch_key_id_for_tenant1: String,
branch_key_id_for_tenant2: String,
}
impl ExampleBranchKeyIdSupplier {
pub fn new(tenant1_id: &str, tenant2_id: &str) -> Self {
Self {
branch_key_id_for_tenant1: tenant1_id.to_string(),
branch_key_id_for_tenant2: tenant2_id.to_string(),
}
}
}
// Create the branch key ID supplier
let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);
let branch_key_id_supplier = dbesdk
.create_dynamo_db_encryption_branch_key_id_supplier()
.ddb_key_branch_key_id_supplier(supplier)
.send()
.await?
.branch_key_id_supplier
.unwrap();
```
------
1. Crear un conjunto de claves jerárquico
En los ejemplos siguientes se inicializa un conjunto de claves jerárquico con el proveedor de claves de sucursal creado en el **paso 1**, un TLL con un límite de caché de 600 segundos y un tamaño máximo de caché de 1000.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
.build())
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 100 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id_supplier(branch_key_id_supplier)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
------
## Uso del conjunto de claves jerárquico para el cifrado para búsquedas
[El cifrado para búsquedas](searchable-encryption.md) le permite buscar registros cifrados sin necesidad de descifrar toda la base de datos. Esto se logra indexando el valor de texto no cifrado de un campo cifrado con una [baliza](beacons.md). Para implementar un cifrado para búsquedas, debe utilizar un conjunto de claves jerárquico.
La operación `CreateKey` de almacenamiento de claves genera tanto una clave de rama como una *clave de baliza*. La clave de rama se utiliza en las operaciones de cifrado y descifrado de registros. La clave de baliza se utiliza para generar balizas.
La clave de sucursal y la clave de baliza están protegidas por el mismo código AWS KMS key que especificó al crear el servicio de almacenamiento de claves. Una vez que la `CreateKey` operación llama AWS KMS para generar la clave de sucursal, llama a [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) una segunda vez para generar la clave de baliza mediante la siguiente solicitud.
```
{
"EncryptionContext": {
"branch-key-id" : "branch-key-id",
"type" : type,
"create-time" : "timestamp",
"tablename" : "the logical table name for your key store",
"kms-arn" : the KMS key ARN,
"hierarchy-version" : 1
},
"KeyId": "the KMS key ARN",
"NumberOfBytes": "32"
}
```
Tras generar ambas claves, la `CreateKey` operación llama a [ddb: TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) para escribir dos nuevos elementos que conservarán la clave de rama y la clave de baliza en tu almacén de claves de sucursal.
Al [configurar una baliza estándar](configure-beacons.md#config-standard-beacons), el SDK de cifrado de AWS bases de datos consulta la clave de la baliza en el almacén de claves. A continuación, utiliza una función de derivación de extract-and-expand claves ([HKDF](https://en.wikipedia.org/wiki/HKDF)) basada en HMAC para combinar la clave de baliza con el nombre de la [baliza estándar](beacons.md#standard-beacon-overview) y crear la clave HMAC para una baliza determinada.
A diferencia de las llaves de sucursal, solo hay una versión de clave de baliza por `branch-key-id` almacén de claves. La clave de la baliza nunca se rota.
### Definir la fuente de claves de baliza
Al definir la [versión de la baliza](using-beacons.md#beacon-version) para las balizas estándar y compuestas, debe identificar la clave de la baliza y definir un tiempo de vida útil (TTL) límite de caché para los materiales de la clave de la baliza. Los materiales de las claves de baliza se almacenan en una caché local independiente de las claves de rama. El siguiente fragmento muestra cómo definir la `keySource` para la base de datos de un solo inquilino. Identifique la clave de su baliza por el `branch-key-id` que está asociada.
------
#### [ Java ]
```
keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branch-key-id)
.cacheTTL(6000)
.build())
.build())
```
------
#### [ C\$1 / .NET ]
```
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000
}
}
```
------
#### [ Rust ]
```
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
```
------
**Definición de la fuente de la baliza en una base de multitenencia**
Si tiene una base de datos de multitenencia, debe especificar los siguientes valores al configurar la `keySource`.
+
**keyFieldName**
Define el nombre del campo que almacena la clave `branch-key-id` asociada a la baliza utilizada para generar las balizas para un inquilino determinado. El `keyFieldName` puede ser cualquier cadena, pero debe ser única para todos los demás campos de la base de datos. Cuando se escriben nuevos registros en la base de datos, en este campo se almacena la `branch-key-id` de baliza utilizada para generar las balizas de ese registro. Debe incluir este campo en sus consultas de baliza e identificar los materiales clave de baliza adecuados necesarios para volver a calcular la baliza. Para obtener más información, consulte [Consulta de balizas en una base de datos de multitenencia](searchable-encryption-multitenant.md#query-multitenant-beacons).
+ **CacheTTL**
El tiempo en segundos que se puede utilizar una entrada de materiales clave de baliza en la caché de balizas local antes de que caduque. Este valor debe ser mayor que cero. Cuando el TTL límite de caché vence, la entrada se expulsa de la caché local.
+ **(Opcional) Una caché**
Si desea personalizar el tipo de caché o el número de entradas de materiales clave de rama que se pueden almacenar en la caché local, especifique el tipo de caché y la capacidad de entrada al inicializar el conjunto de claves.
El conjunto de claves jerárquico admite los siguientes tipos de caché: predeterminada, MultiThreaded StormTracking, y compartida. Para obtener más información y ejemplos que demuestren cómo definir cada tipo de caché, consulte. [Elige una memoria caché](#hierarchical-keyring-caches)
Si no especifica una caché, el conjunto de claves jerárquico utiliza automáticamente el tipo de caché predeterminado y establece la capacidad de entrada en 1000.
En el siguiente ejemplo, se crea un conjunto de claves jerárquico con un proveedor de ID de rama, un límite de caché de 600 segundos y una capacidad de entrada de 1000.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(1000)
.build())
.build());
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 1000 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
# AWS KMS Llaveros ECDH
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de AWS datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
**importante**
El conjunto de claves AWS KMS ECDH solo está disponible en la versión 1.5.0 o posterior de la biblioteca de proveedores de materiales.
Un anillo de claves AWS KMS ECDH utiliza un acuerdo de claves asimétrico [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-types.html)para obtener una clave de empaquetado simétrico compartida entre dos partes. En primer lugar, el conjunto de claves utiliza el algoritmo de acuerdo de claves Elliptic Curve Diffie-Hellman (ECDH) para obtener un secreto compartido a partir de la clave privada del par de claves KMS del remitente y la clave pública del destinatario. A continuación, el conjunto de claves utiliza el secreto compartido para obtener la clave de empaquetado compartida que protege las claves de cifrado de datos. La función de derivación de claves que utiliza el SDK de cifrado de AWS bases de datos (`KDF_CTR_HMAC_SHA384`) para derivar la clave de empaquetado compartida cumple con las [recomendaciones del NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) para la derivación de claves.
La función de derivación de claves devuelve 64 bytes de material de creación de claves. Para garantizar que ambas partes utilicen el material de codificación correcto, el SDK de cifrado de AWS bases de datos utiliza los primeros 32 bytes como clave de compromiso y los últimos 32 bytes como clave de empaquetado compartida. Al descifrar, si el conjunto de claves no puede reproducir la misma clave de compromiso y la misma clave de empaquetado compartida que están almacenadas en el campo de descripción del material del registro cifrado, la operación no se realizará correctamente. Por ejemplo, si cifra un registro con un conjunto de claves configurado con la clave privada **de Alice** y la clave pública **de Bob**, un conjunto de claves configurado con la clave privada **de Bob** y la clave pública **de Alice** reproducirá la misma clave de compromiso y clave de empaquetado compartida y podrá descifrar el registro. Si la clave pública de Bob no proviene de un par de claves KMS, entonces Bob puede crear un conjunto de [claves ECDH sin procesar para](use-raw-ecdh-keyring.md) descifrar el registro.
El anillo de claves AWS KMS ECDH cifra los registros con una clave simétrica mediante AES-GCM. A continuación, la clave de datos se cifra sobre con la clave de empaquetado compartida derivada mediante AES-GCM. [Cada anillo de claves AWS KMS ECDH solo puede tener una clave de empaquetado compartida, pero puede incluir varios anillos de claves AWS KMS ECDH, solos o con otros, en un conjunto de claves múltiples.](use-multi-keyring.md)
**Topics**
+ [AWS KMS Permisos necesarios para los llaveros ECDH](#kms-ecdh-permissions)
+ [Crear un conjunto de claves ECDH AWS KMS](#kms-ecdh-create)
+ [Creación de un conjunto de claves AWS KMS de detección del ECDH](#kms-ecdh-discovery)
## AWS KMS Permisos necesarios para los llaveros ECDH
El SDK AWS de cifrado de bases de datos no requiere una AWS cuenta y no depende de ningún AWS servicio. Sin embargo, para usar un AWS KMS conjunto de claves ECDH, necesita una AWS cuenta y los siguientes permisos mínimos AWS KMS keys en su conjunto de claves. Los permisos varían en función del esquema de acuerdo de claves que utilice.
+ Para cifrar y descifrar registros mediante el esquema de acuerdo de `KmsPrivateKeyToStaticPublicKey` claves, necesita [kms: GetPublicKey y [kms: DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html)](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) en el par de claves KMS asimétricas *del remitente*. Si proporciona directamente la clave pública codificada en DER del remitente al crear una instancia de su conjunto de claves, solo necesitará el DeriveSharedSecret permiso [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) en el par de claves KMS asimétricas del remitente.
+ Para descifrar registros mediante el esquema de acuerdo de `KmsPublicKeyDiscovery` claves, necesita los GetPublicKey permisos [kms: DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) y [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) en el par de claves KMS asimétricas especificado.
## Crear un conjunto de claves ECDH AWS KMS
Para crear un conjunto de claves AWS KMS ECDH que cifre y descifre los datos, debe utilizar el esquema de acuerdo de claves. `KmsPrivateKeyToStaticPublicKey` Para inicializar un anillo de claves AWS KMS ECDH con el esquema de acuerdo de `KmsPrivateKeyToStaticPublicKey` claves, proporcione los siguientes valores:
+ **ID del remitente AWS KMS key **
Debe identificar un par de claves KMS de curva elíptica (ECC) asimétrica recomendado por el NIST con un valor de. `KeyUsage` `KEY_AGREEMENT` La clave privada del remitente se utiliza para obtener el secreto compartido.
+ **(Opcional) Clave pública del remitente**
[Debe ser una clave pública X.509 codificada en DER, también conocida como `SubjectPublicKeyInfo` (SPKI), según se define en el RFC 5280.](https://tools.ietf.org/html/rfc5280)
La AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operación devuelve la clave pública de un par de claves KMS asimétricas en el formato codificado DER requerido.
Para reducir el número de AWS KMS llamadas que realiza tu llavero, puedes proporcionar directamente la clave pública del remitente. Si no se proporciona ningún valor para la clave pública del remitente, el llavero llama AWS KMS para recuperar la clave pública del remitente.
+ **La clave pública del destinatario**
[Debe proporcionar la clave pública X.509 codificada en DER del destinatario, también conocida como `SubjectPublicKeyInfo` (SPKI), tal como se define en el RFC 5280.](https://tools.ietf.org/html/rfc5280)
La AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operación devuelve la clave pública de un par de claves KMS asimétricas en el formato codificado DER requerido.
+ **Especificación de curva**
Identifica la especificación de la curva elíptica en los pares de claves especificados. Los pares de claves del remitente y del destinatario deben tener la misma especificación de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Opcional) Una lista de tokens de concesión**
Si controla el acceso a la clave KMS de su conjunto de claves AWS KMS ECDH mediante [concesiones](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), debe proporcionar todos los símbolos de concesión necesarios al inicializar el conjunto de claves.
------
#### [ C\$1 / .NET ]
En el siguiente ejemplo, se crea un anillo de claves AWS KMS ECDH con la clave KMS del remitente, la clave pública del remitente y la clave pública del destinatario. En este ejemplo, se utiliza el `senderPublicKey` parámetro opcional para proporcionar la clave pública del remitente. Si no proporciona la clave pública del remitente, el conjunto de claves llama AWS KMS para recuperar la clave pública del remitente. Los pares de claves del remitente y del destinatario están en la `ECC_NIST_P256` curva.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Must be DER-encoded X.509 public keys
var BobPublicKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the AWS KMS ECDH static keyring
var staticConfiguration = new KmsEcdhStaticConfigurations
{
KmsPrivateKeyToStaticPublicKey = new KmsPrivateKeyToStaticPublicKeyInput
{
SenderKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
SenderPublicKey = BobPublicKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
En el siguiente ejemplo, se crea un conjunto de claves AWS KMS ECDH con la clave KMS del remitente, la clave pública del remitente y la clave pública del destinatario. En este ejemplo, se utiliza el `senderPublicKey` parámetro opcional para proporcionar la clave pública del remitente. Si no proporciona la clave pública del remitente, el conjunto de claves llama AWS KMS para recuperar la clave pública del remitente. Los pares de claves del remitente y del destinatario están en la `ECC_NIST_P256` curva.
```
// Retrieve public keys
// Must be DER-encoded X.509 public keys
ByteBuffer BobPublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab");
ByteBuffer AlicePublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the AWS KMS ECDH static keyring
final CreateAwsKmsEcdhKeyringInput senderKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPrivateKeyToStaticPublicKey(
KmsPrivateKeyToStaticPublicKeyInput.builder()
.senderKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
.senderPublicKey(BobPublicKey)
.recipientPublicKey(AlicePublicKey)
.build()).build()).build();
```
------
#### [ Rust ]
En el siguiente ejemplo, se crea un conjunto de claves AWS KMS ECDH con la clave KMS del remitente, la clave pública del remitente y la clave pública del destinatario. En este ejemplo, se utiliza el `sender_public_key` parámetro opcional para proporcionar la clave pública del remitente. Si no proporciona la clave pública del remitente, el conjunto de claves llama AWS KMS para recuperar la clave pública del remitente.
```
// Retrieve public keys
// Must be DER-encoded X.509 keys
let public_key_file_content_sender = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_SENDER))?;
let parsed_public_key_file_content_sender = parse(public_key_file_content_sender)?;
let public_key_sender_utf8_bytes = parsed_public_key_file_content_sender.contents();
let public_key_file_content_recipient = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_RECIPIENT))?;
let parsed_public_key_file_content_recipient = parse(public_key_file_content_recipient)?;
let public_key_recipient_utf8_bytes = parsed_public_key_file_content_recipient.contents();
// Create KmsPrivateKeyToStaticPublicKeyInput
let kms_ecdh_static_configuration_input =
KmsPrivateKeyToStaticPublicKeyInput::builder()
.sender_kms_identifier(arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab)
// Must be a UTF8 DER-encoded X.509 public key
.sender_public_key(public_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let kms_ecdh_static_configuration = KmsEcdhStaticConfigurations::KmsPrivateKeyToStaticPublicKey(kms_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH keyring
let kms_ecdh_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client)
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_static_configuration)
.send()
.await?;
```
------
## Creación de un conjunto de claves AWS KMS de detección del ECDH
Al descifrar, se recomienda especificar las claves que puede utilizar el SDK de cifrado de AWS bases de datos. Para seguir esta práctica recomendada, utilice un anillo de claves AWS KMS ECDH con el esquema de acuerdo de `KmsPrivateKeyToStaticPublicKey` claves. Sin embargo, también puede crear un conjunto de claves de detección de AWS KMS ECDH, es decir, un conjunto de claves de AWS KMS ECDH que pueda descifrar cualquier registro en el que la clave pública del par de claves KMS especificado coincida con la clave pública *del destinatario* almacenada en el campo de descripción del material del registro cifrado.
**importante**
Al descifrar los registros mediante el esquema de acuerdo de `KmsPublicKeyDiscovery` claves, acepta todas las claves públicas, independientemente de quién sea su propietario.
Para inicializar un conjunto de claves del AWS KMS ECDH con el esquema de acuerdo de `KmsPublicKeyDiscovery` claves, proporcione los siguientes valores:
+ **ID del destinatario AWS KMS key **
Debe identificar un par de claves KMS de curva elíptica (ECC) asimétrica recomendado por el NIST con un valor de. `KeyUsage` `KEY_AGREEMENT`
+ **Especificación de curva**
Identifica la especificación de la curva elíptica en el par de claves KMS del destinatario.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Opcional) Una lista de tokens de concesión**
Si controla el acceso a la clave KMS de su conjunto de claves AWS KMS ECDH mediante [concesiones](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), debe proporcionar todos los símbolos de concesión necesarios al inicializar el conjunto de claves.
------
#### [ C\$1 / .NET ]
En el siguiente ejemplo, se crea un anillo de claves de detección de AWS KMS ECDH con un par de claves KMS en la `ECC_NIST_P256` curva. Debe tener los DeriveSharedSecret permisos [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) y [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) en el key pair de claves KMS especificado. Este conjunto de claves puede descifrar cualquier registro en el que la clave pública del par de claves KMS especificado coincida con la clave pública del destinatario almacenada en el campo de descripción del material del registro cifrado.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create the AWS KMS ECDH discovery keyring
var discoveryConfiguration = new KmsEcdhStaticConfigurations
{
KmsPublicKeyDiscovery = new KmsPublicKeyDiscoveryInput
{
RecipientKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
En el siguiente ejemplo, se crea un anillo de claves de detección de AWS KMS ECDH con un par de claves KMS en la `ECC_NIST_P256` curva. Debe tener los DeriveSharedSecret permisos [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) y [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) en el key pair de claves KMS especificado. Este conjunto de claves puede descifrar cualquier registro en el que la clave pública del par de claves KMS especificado coincida con la clave pública del destinatario almacenada en el campo de descripción del material del registro cifrado.
```
// Create the AWS KMS ECDH discovery keyring
final CreateAwsKmsEcdhKeyringInput recipientKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPublicKeyDiscovery(
KmsPublicKeyDiscoveryInput.builder()
.recipientKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321").build()
).build())
.build();
```
------
#### [ Rust ]
```
// Create KmsPublicKeyDiscoveryInput
let kms_ecdh_discovery_static_configuration_input =
KmsPublicKeyDiscoveryInput::builder()
.recipient_kms_identifier(ecc_recipient_key_arn)
.build()?;
let kms_ecdh_discovery_static_configuration = KmsEcdhStaticConfigurations::KmsPublicKeyDiscovery(kms_ecdh_discovery_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH discovery keyring
let kms_ecdh_discovery_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client.clone())
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_discovery_static_configuration)
.send()
.await?;
```
------
# Conjunto de claves de AES sin formato
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
El SDK AWS de cifrado de bases de datos le permite utilizar una clave simétrica AES que se proporciona como clave de empaquetado para proteger la clave de datos. Debe generar, almacenar y proteger el material clave, preferiblemente en un módulo de seguridad de hardware (HSM) o en un sistema de administración de claves. Utilice un conjunto de claves de AES sin procesar cuando necesite proporcionar la clave de encapsulamiento y cifre las claves de datos de forma local o fuera de línea.
El conjunto de claves de AES sin formato usa el algoritmo AES-GCM y una clave de encapsulamiento que especifique como matriz de bytes para cifrar claves de datos. Puede especificar una sola clave de encapsulación en cada conjunto de claves de AES sin formato, pero puede incluir varios conjuntos de claves de AES sin formato en cada [conjunto de claves múltiples](use-multi-keyring.md).
**Nombres y espacios de nombres clave**
Para identificar la clave de AES, el conjunto de claves de AES sin formato utiliza un *espacio de nombres de claves* y *nombre de clave* que usted facilite. Estos valores no son secretos. Aparecen en texto plano en la [descripción del material](concepts.md#material-description) que el SDK de cifrado AWS de bases de datos añade al registro. Recomendamos utilizar un espacio de nombres clave en su HSM o sistema de administración de claves y un nombre de clave que identifique la clave AES en ese sistema.
**nota**
El espacio de nombres de clave y el nombre de clave son equivalentes a los campos *ID de proveedor* (o *proveedor*) e ID de *clave* del. `JceMasterKey`
Si crea diferentes conjuntos de claves para cifrar y descifrar un campo determinado, el espacio de nombres y los valores de los nombres son fundamentales. Si el espacio de nombres y el nombre de la clave del conjunto de claves de descifrado no coinciden exactamente y distinguen mayúsculas de minúsculas entre el espacio de nombres de la clave y el nombre de la clave del conjunto de claves de cifrado, no se utiliza el conjunto de claves de descifrado, incluso si los bytes del material de la clave son idénticos.
Por ejemplo, puede definir un conjunto de claves de AES sin procesar con el espacio de nombres `HSM_01` y el nombre de la clave `AES_256_012`. A continuación, utilice ese conjunto de claves para cifrar algunos datos. Para descifrar esos datos, cree un conjunto de claves de AES sin procesar con el mismo espacio de nombres, nombre de clave y material de clave.
Los siguientes ejemplos muestran cómo crear un conjunto de claves de AES sin formato. La `AESWrappingKey` variable representa el material clave que proporciona.
------
#### [ Java ]
```
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
// This example uses the key generator in Bouncy Castle to generate the key material.
// In production, use key material from a secure source.
var aesWrappingKey = new MemoryStream(GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey());
// Create the keyring
var keyringInput = new CreateRawAesKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var matProv = new MaterialProviders(new MaterialProvidersConfig());
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
```
------
# Conjunto de claves de RSA sin formato
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
El conjunto de claves de RSA sin formato realiza un cifrado y descifrado asimétrico de las claves de datos en la memoria local con las claves privadas y públicas de RSA que especifique. Debe generar, almacenar y proteger la clave privada, preferiblemente en un módulo de seguridad de hardware (HSM) o en un sistema de administración de claves. La función de cifrado cifra la clave de datos bajo la clave pública de RSA. La función de descifrado descifra la clave de datos utilizando la clave privada. Puede seleccionar de entre los diversos modos de rellenado de RSA.
Un conjunto de claves de RSA sin formato que cifra y descifra debe incluir una clave pública asimétrica y un par de claves privadas. Sin embargo, puede cifrar datos con un conjunto de claves de RSA sin formato que solo tenga una clave pública y puede descifrar datos con un conjunto de claves de RSA sin formato que solo tenga una clave privada. Y puede incluir cualquier conjunto de claves de RSA sin formato en un [conjunto de claves múltiple](use-multi-keyring.md). Si configura un conjunto de claves de RSA sin procesar con una clave pública y una privada, asegúrese de que formen parte del mismo par de claves.
El conjunto de claves RSA sin procesar es equivalente al del RSA e interactúa con él SDK de cifrado de AWS para Java cuando se utiliza con claves de cifrado asimétricas RSA. [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)
**nota**
El conjunto de claves RSA no admite claves de KMS asimétricas. Para usar claves RSA KMS asimétricas, cree un [conjunto de claves de AWS KMS](use-kms-keyring.md).
**Espacios de nombres y nombres**
Para identificar el par de claves, el conjunto de claves de RSA sin formato utiliza un *espacio de nombres* y *nombre* que usted facilite. Estos valores no son secretos. Aparecen en texto plano en la [descripción del material](concepts.md#material-description) que el SDK de cifrado de AWS bases de datos añade al registro. Recomendamos usar el espacio de nombres y el nombre de clave que identifican el par de claves RSA (o su clave privada) en su HSM o sistema de administración de claves.
**nota**
El espacio de nombres de clave y el nombre de clave son equivalentes a los campos *ID de proveedor* (o *proveedor*) e ID de *clave* del. `JceMasterKey`
Si crea diferentes conjuntos de claves para cifrar y descifrar un registro determinado, el espacio de nombres y los valores de los nombres son fundamentales. Si el espacio de nombres de clave y el nombre de clave del conjunto de claves de descifrado no coinciden exactamente y distinguen mayúsculas de minúsculas entre el espacio de nombres de clave y el nombre de clave del conjunto de claves de cifrado, no se utiliza el conjunto de claves de descifrado, incluso si las claves son del mismo par de claves.
El espacio de nombres de clave y el nombre de clave del material clave de los conjuntos de claves de cifrado y descifrado deben ser los mismos independientemente de que el conjunto de claves contenga la clave pública RSA, la clave privada RSA o ambas claves del par de claves. Por ejemplo, supongamos que cifra los datos con un conjunto de claves de RSA sin procesar para una clave pública RSA con el espacio de nombres `HSM_01` y el nombre de la clave `RSA_2048_06`. Para descifrar esos datos, cree un conjunto de claves de RSA sin procesar con la clave privada (o el mismo par de claves) y el mismo espacio de nombres y nombre de claves.
**Modo de relleno**
Debe especificar un modo de relleno para los conjunto de claves RSA sin formato utilizados para el cifrado y descifrado, o utilizar características de la implementación de su lenguaje que lo especifiquen por usted.
AWS Encryption SDK Admite los siguientes modos de relleno, sujetos a las limitaciones de cada idioma. Recomendamos un modo de relleno [OAEP](https://tools.ietf.org/html/rfc8017#section-7.1), especialmente el OAEP con relleno SHA-256 y SHA-256. MGF1 El modo de relleno solo se admite por motivos de compatibilidad con versiones anteriores. [PKCS1](https://tools.ietf.org/html/rfc8017#section-7.2)
+ OAEP con relleno SHA-1 y SHA-1 MGF1
+ OAEP con relleno SHA-256 y SHA-256 MGF1
+ OAEP con relleno SHA-384 y SHA-384 MGF1
+ OAEP con relleno SHA-512 y SHA-512 MGF1
+ PKCS1 Acolchado v1.5
El siguiente ejemplo de Java muestra cómo crear un conjunto de claves RSA sin procesar con la clave pública y privada de un par de claves RSA y el OAEP con SHA-256 y con el modo de relleno SHA-256. MGF1 `RSAPublicKey``RSAPrivateKey`Las variables y representan el material clave que proporciona.
------
#### [ Java ]
```
final CreateRawRsaKeyringInput keyringInput = CreateRawRsaKeyringInput.builder()
.keyName("RSA_2048_06")
.keyNamespace("HSM_01")
.paddingScheme(PaddingScheme.OAEP_SHA256_MGF1)
.publicKey(RSAPublicKey)
.privateKey(RSAPrivateKey)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "RSA_2048_06";
// Get public and private keys from PEM files
var publicKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePublicKey.pem"));
var privateKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePrivateKey.pem"));
// Create the keyring input
var keyringInput = new CreateRawRsaKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
PaddingScheme = PaddingScheme.OAEP_SHA512_MGF1,
PublicKey = publicKey,
PrivateKey = privateKey
};
// Create the keyring
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_rsa_keyring = mpl
.create_raw_rsa_keyring()
.key_name("RSA_2048_06")
.key_namespace("HSM_01")
.padding_scheme(PaddingScheme::OaepSha256Mgf1)
.public_key(RSA_public_key)
.private_key(RSA_private_key)
.send()
.await?;
```
------
# Llaveros ECDH sin procesar
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de AWS datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
**importante**
El conjunto de claves ECDH sin procesar solo está disponible en la versión 1.5.0 de la biblioteca de proveedores de materiales.
El anillo de claves ECDH sin procesar utiliza los pares de claves público-privadas de curva elíptica que usted proporciona para obtener una clave de empaquetado compartida entre dos partes. En primer lugar, el conjunto de claves obtiene un secreto compartido mediante la clave privada del remitente, la clave pública del destinatario y el algoritmo de acuerdo de claves Elliptic Curve Diffie-Hellman (ECDH). A continuación, el conjunto de claves utiliza el secreto compartido para obtener la clave de empaquetado compartida que protege las claves de cifrado de datos. La función de derivación de claves que utiliza el SDK de cifrado de AWS bases de datos (`KDF_CTR_HMAC_SHA384`) para derivar la clave de empaquetado compartida cumple con las [recomendaciones del NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) para la derivación de claves.
La función de derivación de claves devuelve 64 bytes de material de creación de claves. Para garantizar que ambas partes utilicen el material de codificación correcto, el SDK de cifrado de AWS bases de datos utiliza los primeros 32 bytes como clave de compromiso y los últimos 32 bytes como clave de empaquetado compartida. Al descifrar, si el conjunto de claves no puede reproducir la misma clave de compromiso y la misma clave de empaquetado compartida que están almacenadas en el campo de descripción del material del registro cifrado, la operación falla. Por ejemplo, si cifra un registro con un conjunto de claves configurado con la clave privada **de Alice** y la clave pública **de Bob**, un conjunto de claves configurado con la clave privada **de Bob** y la clave pública **de Alice** reproducirá la misma clave de compromiso y clave de empaquetado compartida y podrá descifrar el registro. Si la clave pública de Bob proviene de un AWS KMS key par, Bob puede crear un conjunto de [claves AWS KMS ECDH](use-kms-ecdh-keyring.md) para descifrar el registro.
El conjunto de claves ECDH sin procesar cifra los registros con una clave simétrica mediante AES-GCM. A continuación, la clave de datos se cifra sobre con la clave de empaquetado compartida derivada mediante AES-GCM. [Cada anillo de claves ECDH sin procesar solo puede tener una clave de empaquetado compartida, pero puede incluir varios anillos de claves ECDH sin procesar, solos o con otros, en un conjunto de claves múltiples.](use-multi-keyring.md)
Usted es responsable de generar, almacenar y proteger sus claves privadas, preferiblemente en un módulo de seguridad de hardware (HSM) o en un sistema de administración de claves. Los pares de claves del remitente y del destinatario deben estar en la misma curva elíptica. El SDK AWS de cifrado de bases de datos admite las siguientes especificaciones de curva elíptica:
+ `ECC_NIST_P256`
+ `ECC_NIST_P384`
+ `ECC_NIST_P512`
## Creación de un conjunto de claves ECDH sin procesar
El anillo de claves ECDH sin procesar admite tres esquemas de acuerdo clave:, y. `RawPrivateKeyToStaticPublicKey` `EphemeralPrivateKeyToStaticPublicKey` `PublicKeyDiscovery` El esquema de acuerdo de claves que seleccione determina qué operaciones criptográficas puede realizar y cómo se ensamblan los materiales de codificación.
**Topics**
+ [RawPrivateKeyToStaticPublicKey](#raw-ecdh-RawPrivateKeyToStaticPublicKey)
+ [EphemeralPrivateKeyToStaticPublicKey](#raw-ecdh-EphemeralPrivateKeyToStaticPublicKey)
+ [PublicKeyDiscovery](#raw-ecdh-PublicKeyDiscovery)
### RawPrivateKeyToStaticPublicKey
Utilice el esquema de acuerdo de `RawPrivateKeyToStaticPublicKey` claves para configurar de forma estática la clave privada del remitente y la clave pública del destinatario en el conjunto de claves. Este esquema de acuerdo de claves puede cifrar y descifrar registros.
Para inicializar un conjunto de claves ECDH sin procesar con el esquema de acuerdo de `RawPrivateKeyToStaticPublicKey` claves, proporcione los siguientes valores:
+ **Clave privada del remitente**
[Debe proporcionar la clave privada codificada en PEM del remitente ( PrivateKeyInfo estructuras PKCS \$18), tal como se define en el RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **La clave pública del destinatario**
[Debe proporcionar la clave pública X.509 codificada en DER del destinatario, también conocida como `SubjectPublicKeyInfo` (SPKI), tal como se define en el RFC 5280.](https://tools.ietf.org/html/rfc5280)
Puede especificar la clave pública de un par de claves KMS de un acuerdo de claves asimétrico o la clave pública de un par de claves generado fuera de AWS.
+ **Especificación de curva**
Identifica la especificación de la curva elíptica en los pares de claves especificados. Los pares de claves del remitente y del destinatario deben tener la misma especificación de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var BobPrivateKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH static keyring
var staticConfiguration = new RawEcdhStaticConfigurations()
{
RawPrivateKeyToStaticPublicKey = new RawPrivateKeyToStaticPublicKeyInput
{
SenderStaticPrivateKey = BobPrivateKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
El siguiente ejemplo de Java utiliza el esquema de acuerdo de `RawPrivateKeyToStaticPublicKey` claves para configurar estáticamente la clave privada del remitente y la clave pública del destinatario. Ambos pares de claves están en la `ECC_NIST_P256` curva.
```
private static void StaticRawKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair senderKeys = GetRawEccKey();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH static keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.RawPrivateKeyToStaticPublicKey(
RawPrivateKeyToStaticPublicKeyInput.builder()
// Must be a PEM-encoded private key
.senderStaticPrivateKey(ByteBuffer.wrap(senderKeys.getPrivate().getEncoded()))
// Must be a DER-encoded X.509 public key
.recipientPublicKey(ByteBuffer.wrap(recipient.getPublic().getEncoded()))
.build()
)
.build()
).build();
final IKeyring staticKeyring = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Rust ]
El siguiente ejemplo de Python usa el esquema de acuerdo de `raw_ecdh_static_configuration` claves para configurar estáticamente la clave privada del remitente y la clave pública del destinatario. Ambos pares de claves deben estar en la misma curva.
```
// Create keyring input
let raw_ecdh_static_configuration_input =
RawPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 PEM-encoded private key
.sender_static_private_key(private_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let raw_ecdh_static_configuration = RawEcdhStaticConfigurations::RawPrivateKeyToStaticPublicKey(raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH static keyring
let raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(raw_ecdh_static_configuration)
.send()
.await?;
```
------
### EphemeralPrivateKeyToStaticPublicKey
Los conjuntos de `EphemeralPrivateKeyToStaticPublicKey` claves configurados con el esquema de acuerdo de claves crean un nuevo par de claves localmente y derivan una clave de empaquetado compartida única para cada llamada de cifrado.
Este esquema de acuerdo de claves solo puede cifrar registros. Para descifrar los registros cifrados con el esquema de acuerdo de `EphemeralPrivateKeyToStaticPublicKey` claves, debe utilizar un esquema de acuerdo de claves de descubrimiento configurado con la clave pública del mismo destinatario. Para descifrar, puede usar un anillo de claves ECDH sin procesar con el algoritmo de acuerdo de claves o, si la [`PublicKeyDiscovery`](#raw-ecdh-PublicKeyDiscovery)clave pública del destinatario proviene de un par de claves KMS de acuerdo de claves asimétrico, puede usar un anillo de claves AWS KMS ECDH con el esquema de acuerdo de claves. [KmsPublicKeyDiscovery](use-kms-ecdh-keyring.md#kms-ecdh-discovery)
Para inicializar un conjunto de claves ECDH sin procesar con el esquema de acuerdo de claves, proporcione los siguientes valores`EphemeralPrivateKeyToStaticPublicKey`:
+ **Clave pública del destinatario**
[Debe proporcionar la clave pública X.509 codificada en DER del destinatario, también conocida como `SubjectPublicKeyInfo` (SPKI), tal como se define en el RFC 5280.](https://tools.ietf.org/html/rfc5280)
Puede especificar la clave pública de un par de claves KMS de un acuerdo de claves asimétrico o la clave pública de un par de claves generado fuera de AWS.
+ **Especificación de curva**
Identifica la especificación de la curva elíptica en la clave pública especificada.
Al cifrar, el anillo de claves crea un nuevo par de claves en la curva especificada y utiliza la nueva clave privada y la clave pública especificada para obtener una clave de empaquetado compartida.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el `EphemeralPrivateKeyToStaticPublicKey` esquema de acuerdo de claves. Al cifrar, el anillo de claves creará un nuevo par de claves localmente en la curva especificada`ECC_NIST_P256`.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH ephemeral keyring
var ephemeralConfiguration = new RawEcdhStaticConfigurations()
{
EphemeralPrivateKeyToStaticPublicKey = new EphemeralPrivateKeyToStaticPublicKeyInput
{
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = ephemeralConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el `EphemeralPrivateKeyToStaticPublicKey` esquema de acuerdo de claves. Al cifrar, el anillo de claves creará un nuevo par de claves localmente en la curva especificada`ECC_NIST_P256`.
```
private static void EphemeralRawEcdhKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
ByteBuffer recipientPublicKey = getPublicKeyBytes();
// Create the Raw ECDH ephemeral keyring
final CreateRawEcdhKeyringInput ephemeralInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.EphemeralPrivateKeyToStaticPublicKey(
EphemeralPrivateKeyToStaticPublicKeyInput.builder()
.recipientPublicKey(recipientPublicKey)
.build()
)
.build()
).build();
final IKeyring ephemeralKeyring = materialProviders.CreateRawEcdhKeyring(ephemeralInput);
}
```
------
#### [ Rust ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el `ephemeral_raw_ecdh_static_configuration` esquema de acuerdo de claves. Al cifrar, el anillo de claves creará un nuevo par de claves localmente en la curva especificada.
```
// Create EphemeralPrivateKeyToStaticPublicKeyInput
let ephemeral_raw_ecdh_static_configuration_input =
EphemeralPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let ephemeral_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::EphemeralPrivateKeyToStaticPublicKey(ephemeral_raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH ephemeral private key keyring
let ephemeral_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(ephemeral_raw_ecdh_static_configuration)
.send()
.await?;
```
------
### PublicKeyDiscovery
Al descifrar, se recomienda especificar las claves de empaquetado que puede usar el SDK de cifrado de AWS bases de datos. Para seguir esta práctica recomendada, utilice un conjunto de claves ECDH que especifique tanto la clave privada del remitente como la clave pública del destinatario. Sin embargo, también puede crear un conjunto de claves de detección de ECDH sin procesar, es decir, un conjunto de claves ECDH sin procesar que pueda descifrar cualquier registro en el que la clave pública de la clave especificada coincida con la clave pública del destinatario almacenada en el campo de descripción del material del registro cifrado. Este esquema de acuerdo de claves solo puede descifrar registros.
**importante**
Al descifrar registros mediante el esquema de acuerdo de `PublicKeyDiscovery` claves, acepta todas las claves públicas, independientemente de quién sea su propietario.
Para inicializar un conjunto de claves ECDH sin procesar con el esquema de acuerdo de `PublicKeyDiscovery` claves, proporcione los siguientes valores:
+ **Clave privada estática del destinatario**
[Debe proporcionar la clave privada codificada en PEM del destinatario ( PrivateKeyInfo estructuras PKCS \$18), tal como se define en el RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Especificación de curva**
Identifica la especificación de la curva elíptica en la clave privada especificada. Los pares de claves del remitente y del destinatario deben tener la misma especificación de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el esquema de acuerdo de `PublicKeyDiscovery` claves. Este conjunto de claves puede descifrar cualquier registro en el que la clave pública de la clave privada especificada coincida con la clave pública del destinatario almacenada en el campo de descripción del material del registro cifrado.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePrivateKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH discovery keyring
var discoveryConfiguration = new RawEcdhStaticConfigurations()
{
PublicKeyDiscovery = new PublicKeyDiscoveryInput
{
RecipientStaticPrivateKey = AlicePrivateKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el `PublicKeyDiscovery` esquema de acuerdo de claves. Este conjunto de claves puede descifrar cualquier registro en el que la clave pública de la clave privada especificada coincida con la clave pública del destinatario almacenada en el campo de descripción del material del registro cifrado.
```
private static void RawEcdhDiscovery() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH discovery keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.PublicKeyDiscovery(
PublicKeyDiscoveryInput.builder()
// Must be a PEM-encoded private key
.recipientStaticPrivateKey(ByteBuffer.wrap(sender.getPrivate().getEncoded()))
.build()
)
.build()
).build();
final IKeyring publicKeyDiscovery = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Rust ]
En el siguiente ejemplo, se crea un anillo de claves ECDH sin procesar con el `discovery_raw_ecdh_static_configuration` esquema de acuerdo de claves. Este conjunto de claves puede descifrar cualquier mensaje en el que la clave pública de la clave privada especificada coincida con la clave pública del destinatario almacenada en el texto cifrado del mensaje.
```
// Create PublicKeyDiscoveryInput
let discovery_raw_ecdh_static_configuration_input =
PublicKeyDiscoveryInput::builder()
// Must be a UTF8 PEM-encoded private key
.recipient_static_private_key(private_key_recipient_utf8_bytes)
.build()?;
let discovery_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::PublicKeyDiscovery(discovery_raw_ecdh_static_configuration_input);
// Create raw ECDH discovery private key keyring
let discovery_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(discovery_raw_ecdh_static_configuration)
.send()
.await?;
```
------
# Conjuntos de claves múltiples
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
Puede combinar conjuntos de claves en un conjuntos de claves múltiple. Un *conjunto de claves múltiple* es un conjunto de claves que consta de uno o varios conjuntos de claves individuales del mismo tipo o de un tipo distinto. El efecto equivale a utilizar varios conjuntos de claves en una serie. Cuando se utiliza un conjunto de claves múltiple para cifrar datos, cualquiera de las claves de encapsulamiento en cualquiera de los conjuntos de claves puede descifrar dichos datos.
Cuando crea un conjunto de claves múltiple para cifrar datos, designa uno de los conjuntos de claves como *conjunto de claves generador*. Los conjuntos de claves restantes se conocen como *conjuntos de claves secundarios*. El conjunto de claves generador genera y cifra la clave de datos de texto no cifrado. A continuación, todas las claves de encapsulamiento de todos los conjuntos de claves secundarios cifran la misma clave de datos en texto no cifrado. El conjunto de claves múltiple devuelve la clave de texto no cifrado y una clave de datos cifrada para cada clave de encapsulamiento del conjunto de claves múltiple. Si el anillo de claves del generador es un anillo de [claves de KMS, la clave del generador del anillo](use-kms-keyring.md) de claves genera y cifra la AWS KMS clave de texto simple. A continuación, todas las demás claves del AWS KMS keys conjunto de AWS KMS claves y todas las claves de empaquetado de todos los anillos secundarios del conjunto de claves múltiples cifran la misma clave de texto sin formato.
Al descifrar, el SDK de cifrado de AWS bases de datos utiliza los anillos de claves para intentar descifrar una de las claves de datos cifrados. Los conjuntos de claves se llaman en el orden en que están especificados en el conjunto de claves múltiple. El procesamiento se detiene tan pronto como cualquier clave de cualquier conjunto de claves pueda descifrar una clave de datos cifrada.
Para crear un conjunto de claves múltiple, en primer lugar, instancie los conjunto de claves secundarios. En este ejemplo, utilizamos un anillo de claves y un AWS KMS anillo de claves AES sin procesar, pero puede combinar cualquier conjunto de claves compatible en un conjunto de claves múltiples.
------
#### [ Java ]
```
// 1. Create the raw AES keyring.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput createRawAesKeyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// 1. Create the raw AES keyring.
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createRawAesKeyringInput = new CreateRawAesKeyringInput
{
KeyName = "keyName",
KeyNamespace = "myNamespaces",
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
// We create a MRK multi keyring, as this interface also supports
// single-region KMS keys,
// and creates the KMS client for us automatically.
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = keyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
// 1. Create the raw AES keyring
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
// 2. Create the AWS KMS keyring
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(key_arn)
.send()
.await?;
```
------
A continuación, cree el conjunto de claves múltiple y especifique su conjunto de claves generador, si lo hay. En este ejemplo, creamos un llavero múltiple en el que el llavero es el llavero generador y el AWS KMS llavero AES el llavero secundario.
------
#### [ Java ]
El `CreateMultiKeyringInput` constructor de Java permite definir un llavero generador y un llavero secundario. El objeto resultante `createMultiKeyringInput` es inmutable.
```
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(awsKmsMrkMultiKeyring)
.childKeyrings(Collections.singletonList(rawAesKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
El constructor `CreateMultiKeyringInput` de .NET permite definir un conjunto de claves generador y conjuntos de claves secundarios. El objeto resultante `CreateMultiKeyringInput` es inmutable.
```
var createMultiKeyringInput = new CreateMultiKeyringInput
{
Generator = awsKmsMrkMultiKeyring,
ChildKeyrings = new List { rawAesKeyring }
};
var multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ Rust ]
```
let multi_keyring = mpl
.create_multi_keyring()
.generator(aws_kms_mrk_multi_keyring)
.child_keyrings(vec![raw_aes_keyring.clone()])
.send()
.await?;
```
------
Ahora, puede utilizar el conjunto de claves múltiple para cifrar y descifrar datos.