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.
# 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?;
```