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 SDK de cifrado de bases de datos para DynamoDB
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de datos. AWS 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 para DynamoDB es una biblioteca de software que le permite incluir el cifrado del lado del cliente en el diseño de Amazon DynamoDB.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) El SDK de cifrado de AWS bases de datos para DynamoDB proporciona cifrado a nivel de atributos y le permite especificar qué elementos cifrar y qué elementos incluir en las firmas para garantizar la autenticidad de los datos. El cifrado de sus datos en tránsito y en reposo confidenciales ayuda a garantizar que los datos de texto no cifrado no estén disponibles para ningún tercero, incluido AWS.
**nota**
El SDK AWS de cifrado de bases de datos no admite PartiQL.
En DynamoDB una [tabla](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.TablesItemsAttributes) es una colección de elementos. Cada *elemento* es una colección de *atributos*. Cada atributo tiene un nombre y un valor. El SDK AWS de cifrado de bases de datos para DynamoDB cifra los valores de los atributos. A continuación, calcula una firma sobre los atributos. Puede especificar qué valores de atributo cifrar y cuáles incluir en la firma en las acciones criptográficas[Funciones criptográficas](concepts.md#crypt-actions).
Los temas de este capítulo proporcionan información general sobre el SDK de cifrado de AWS bases de datos para DynamoDB, incluidos los campos que se cifran, instrucciones sobre la instalación y configuración del cliente y ejemplos de Java para ayudarle a empezar.
**Topics**
+ [cifrado del cliente o del lado del servidor](client-server-side.md)
+ [¿Qué campos se cifran y se firman?](DDB-encrypted-and-signed.md)
+ [Cifrado con capacidad de búsqueda en DynamoDB](ddb-searchable-encryption.md)
+ [Actualización de su modelo de datos](ddb-update-data-model.md)
+ [AWS SDK de cifrado de bases de datos para los lenguajes de programación disponibles en DynamoDB](ddb-programming-languages.md)
+ [Cliente de cifrado de DynamoDB antiguo](legacy-dynamodb-encryption-client.md)
# cifrado del cliente o del lado del servidor
****
| |
| --- |
| 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 para DynamoDB *admite el cifrado del lado del cliente*, en el que se cifran los datos de la tabla antes de enviarlos a la base de datos. Sin embargo, admite una característica de *cifrado en reposo* que cifra de modo transparente la tabla cuando se almacena en disco y la descifra cuando accede a la tabla.
Las herramientas que elija dependen de la confidencialidad de sus datos y de los requisitos de seguridad de su aplicación. Puede usar tanto el SDK de cifrado AWS de bases de datos para DynamoDB como el cifrado en reposo. Cuando envía elementos cifrados y firmados a , no reconoce los elementos como protegidos. Detecta elementos de tabla típicos con valores de atributo binario.
**Cifrado del lado del servidor en reposo**
DynamoDB admite el [cifrado en reposo](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/EncryptionAtRest.html), una característica de *cifrado del servidor* en la que DynamoDB cifra de modo transparente las tablas cuando la tabla se almacena en disco y las descifra cuando se accede a los datos de la tabla.
Cuando utiliza un AWS SDK para interactuar con DynamoDB, de forma predeterminada, los datos se cifran en tránsito a través de una conexión HTTPS, se descifran en el punto de conexión de DynamoDB y, a continuación, se vuelven a cifrar antes de almacenarlos en DynamoDB.
+ **Cifrado de forma predeterminada.** DynamoDB cifra y descifra de forma transparente todas las tablas cuando se escriben. No existe la opción de habilitar o deshabilitar el cifrado en reposo.
+ **DynamoDB crea y administra las claves criptográficas. **La clave única de cada tabla está protegida por un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) que nunca se deja [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) sin cifrar. De forma predeterminada, DynamoDB utiliza una [Clave propiedad de AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) en la cuenta de servicio de DynamoDB, pero puede elegir una [Clave administrada de AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) o [ una clave gestionada](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) por el cliente en su cuenta para proteger algunas o todas sus tablas.
+ **Todos los datos de la tabla se cifran en disco. **Cuando una tabla cifrada se guarda en disco, cifra todos los datos de la tabla, incluida la [clave principal](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey) y los [índices secundarios locales](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.SecondaryIndexes) y globales. Si la tabla tiene una clave de clasificación, algunas de las claves de ordenación que marcan los límites del rango se almacenan en texto no cifrado en los metadatos de la tabla.
+ **Los objetos relacionados con las tablas también están cifrados.** El cifrado en reposo protege los [flujos de ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html), las [tablas globales](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html) y las [copias de seguridad](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) cada vez que se escriben en medios duraderos.
+ **Sus elementos se descifran cuando accede a ellos. **Cuando accede a la tabla, DynamoDB descifra la parte de la tabla que incluye el elemento de destino y le devuelve el elemento de texto no cifrado.
**AWS SDK de cifrado de bases de datos para DynamoDB**
El cifrado del lado del cliente proporciona end-to-end protección para los datos, en tránsito y en reposo, desde su origen hasta su almacenamiento en DynamoDB. Sus datos de texto sin formato nunca están expuestos a terceros, ni siquiera a ellos. AWS Puede utilizar el SDK de cifrado de AWS bases de datos para DynamoDB con las nuevas tablas de DynamoDB o migrar las tablas existentes de Amazon DynamoDB a la versión más reciente del SDK de cifrado de bases de datos para DynamoDB. AWS
+ **Sus datos se protegen en tránsito y en reposo.** Nunca está expuesto a ningún tercero, ni siquiera. AWS
+ **Puede firmar sus elementos de tabla.** Puede dirigir el SDK de cifrado de bases de datos de AWS para DynamoDB para calcular una firma sobre todo o parte de un elemento de tabla, incluidos los atributos de clave principal y el nombre de la tabla. Esta firma permite detectar cambios no autorizados en el elemento en general, incluida la adición o eliminación de atributos o el cambio de valores de atributo.
+ **Para determinar cómo se protegen los datos**, [seleccione un conjunto de claves](keyrings.md). Su conjunto de claves determina las claves de encapsulación que protegen sus claves de datos y, en última instancia, sus datos. Utilice las claves de encapsulamiento más seguras que resulten prácticas para su tarea.
+ **El SDK AWS de cifrado de bases de datos para DynamoDB no cifra toda la tabla.** Usted elige qué atributos se cifrarán en sus elementos. El SDK AWS de cifrado de bases de datos para DynamoDB no cifra un elemento completo. No cifra nombres de atributo o los nombres o valores de los atributos de clave principal (clave de partición y clave de clasificación).
**AWS Encryption SDK**
Si va a cifrar los datos que almacena en DynamoDB, le recomendamos AWS el SDK de cifrado de bases de datos para DynamoDB.
La [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/) es una biblioteca de cifrado del cliente que le ayuda a cifrar y descifrar datos genéricos. Aunque puede proteger cualquier tipo de datos, no se ha diseñado para funcionar con datos estructurados, como registros de base de datos. A diferencia del SDK AWS de cifrado de bases de datos para DynamoDB, AWS Encryption SDK no puede proporcionar comprobaciones de integridad a nivel de elemento y no tiene ninguna lógica para reconocer los atributos o impedir el cifrado de las claves principales.
Si lo usa AWS Encryption SDK para cifrar algún elemento de la tabla, recuerde que no es compatible con el SDK de cifrado de AWS bases de datos para DynamoDB. No puede cifrar con una biblioteca y descifrar con la otra.
# ¿Qué campos se cifran y se firman?
****
| |
| --- |
| 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 para DynamoDB es una biblioteca de cifrado del lado del cliente diseñada especialmente para las aplicaciones de Amazon DynamoDB. Amazon DynamoDB almacena los datos en [tablas](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.TablesItemsAttributes), que son un conjunto de elementos. Cada *elemento* es una colección de *atributos*. Cada atributo tiene un nombre y un valor. El SDK AWS de cifrado de bases de datos para DynamoDB cifra los valores de los atributos. A continuación, calcula una firma sobre los atributos. Puede especificar qué valores de atributo cifrar y cuáles incluir en la firma.
El cifrado protege la confidencialidad del valor de atributo. La firma proporciona integridad de todos los atributos firmados y de sus relaciones entre sí y proporciona autenticación. Le permite detectar cambios no autorizados en el elemento en general, incluida la adición o eliminación de atributos o la sustitución de un valor cifrado por otro.
En un elemento cifrado, algunos datos permanecen en texto no cifrado, incluido el nombre de la tabla, todos los nombres de atributo, los valores de atributo que no cifra y los nombres y valores de los atributos de la clave principal (clave de partición y clave de clasificación). No almacene información confidencial en estos campos.
Para obtener más información sobre el funcionamiento del SDK AWS de cifrado de bases de datos para DynamoDB, consulte. [Cómo funciona el SDK AWS de cifrado de bases de datos](how-it-works.md)
**nota**
[Todas las menciones a *las acciones de atributos* en los temas del SDK AWS de cifrado de bases de datos para DynamoDB se refieren a acciones criptográficas.](concepts.md#crypt-actions)
**Topics**
+ [Cifrado de valores de atributos](#encrypt-attribute-values)
+ [Firma del elemento](#sign-the-item)
## Cifrado de valores de atributos
El SDK AWS de cifrado de bases de datos para DynamoDB cifra los valores (pero no el nombre o el tipo de atributo) de los atributos que especifique. Para determinar los valores de atributo que se cifran, utilice [acciones de atributo](concepts.md#crypt-actions).
Por ejemplo, este elemento incluye los atributos `example` y `test`.
```
'example': 'data',
'test': 'test-value',
...
```
Si cifra el atributo `example`, pero no cifra el atributo `test`, el resultado tendrá el siguiente aspecto. El valor de atributo `example` cifrado son datos binarios, en lugar de una cadena.
```
'example': Binary(b"'b\x933\x9a+s\xf1\xd6a\xc5\xd5\x1aZ\xed\xd6\xce\xe9X\xf0T\xcb\x9fY\x9f\xf3\xc9C\x83\r\xbb\\"),
'test': 'test-value'
...
```
Los atributos de clave principal (clave de partición y clave de clasificación) de cada elemento deben permanecer en texto no cifrado porque DynamoDB los utiliza para buscar el elemento en la tabla. Deben estar firmados, pero no cifrados.
El SDK AWS de cifrado de bases de datos para DynamoDB identifica los atributos clave principales y garantiza que sus valores estén firmados, pero no cifrados. Y, si identifica la clave principal y, a continuación, intenta cifrarla, el cliente generará una excepción.
El cliente guarda la [descripción del material](concepts.md#material-description) en un nuevo atributo (`aws_dbe_head`) que agrega al elemento. La descripción del material describe cómo se cifró y firmó el elemento. El cliente utiliza esta información para verificar y descifrar el elemento. El campo que almacena la descripción del material no está cifrado.
## Firma del elemento
[Tras cifrar los valores de los atributos especificados, el SDK de cifrado de AWS bases de datos para DynamoDB calcula los códigos de autenticación de mensajes basados en hash HMACs () y [una firma digital](concepts.md#digital-sigs) mediante la canonicalización de la descripción del material[, el contexto de cifrado](concepts.md#encryption-context) y cada campo `ENCRYPT_AND_SIGN` marcado o en las acciones de los atributos. `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](concepts.md#crypt-actions) Las firmas ECDSA están habilitadas de forma predeterminada, pero no son obligatorias. El cliente almacena las firmas HMACs y en un nuevo atributo (`aws_dbe_foot`) que añade al elemento.
# Cifrado con capacidad de búsqueda en DynamoDB
Para configurar las tablas de Amazon DynamoDB para el cifrado con capacidad de búsqueda, debe utilizar el [conjunto de claves de AWS KMS jerárquico](use-hierarchical-keyring.md) para generar, cifrar y descifrar las claves de datos utilizadas para proteger los elementos. También debe incluir [`SearchConfig`](ddb-net-using.md#ddb-net-search-config)en la configuración de cifrado de la tabla.
**nota**
Si utiliza la biblioteca de cifrado del lado del cliente de Java para DynamoDB, debe utilizar el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB para cifrar, firmar, verificar y descifrar los elementos de la tabla. El cliente mejorado de DynamoDB y los `DynamoDBItemEncryptor` niveles inferiores no admiten el cifrado con capacidad de búsqueda.
**Topics**
+ [Configurar índices secundarios con balizas](#ddb-beacon-indexes)
+ [Probando las salidas de balizas](#ddb-beacon-testing)
## Configurar índices secundarios con balizas
Después de [configurar las balizas](configure-beacons.md), debe configurar un índice secundario que refleje cada baliza antes de poder buscar en los atributos cifrados.
Al configurar una baliza estándar o compuesta, el SDK de cifrado de AWS bases de datos añade el `aws_dbe_b_` prefijo al nombre de la baliza para que el servidor pueda identificarlas fácilmente. Por ejemplo, si nombra una baliza compuesta`compoundBeacon`, el nombre completo de la baliza es realmente. `aws_dbe_b_compoundBeacon` Si desea configurar [índices secundarios](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SecondaryIndexes.html) que incluyan una baliza estándar o compuesta, debe incluir el `aws_dbe_b_` prefijo al identificar el nombre de la baliza.
**Claves de partición y claves de clasificación**
No puede cifrar los valores de la clave principal. Las claves de partición y clasificación deben estar firmadas. Sus valores de la clave principal no pueden ser una baliza estándar o compuesta.
Los valores de las claves principales deben ser`SIGN_ONLY`, a menos que especifique algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
Sus valores de la clave principal pueden ser balizas firmadas. Si ha configurado balizas firmadas distintas para cada uno de los valores de la clave principal, debe especificar el nombre del atributo que identifica el valor de la clave principal como el nombre de la baliza firmada. Sin embargo, el SDK AWS de cifrado de bases de datos no añade el `aws_dbe_b_` prefijo a las balizas firmadas. Aunque haya configurado balizas firmadas distintas para los valores de la clave principal, solo tendrá que especificar los nombres de los atributos de los valores de la clave principal al configurar un índice secundario.
**Índices secundarios locales**
La clave de clasificación de un [índice secundario local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html) puede ser una baliza.
Si especifica una baliza para la clave de clasificación, el tipo debe ser Cadena. Si especifica una baliza estándar o compuesta para la clave de clasificación, debe incluir el `aws_dbe_b_` prefijo al especificar el nombre de la baliza. Si especifica una baliza firmada, especifique el nombre de la baliza sin ningún prefijo.
**Índices secundarios globales**
Tanto la partición como las claves de clasificación de un [índice secundario global](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html) pueden ser balizas.
Si especifica un indicador para la partición o la clave de clasificación, el tipo debe ser Cadena. Si especifica una baliza estándar o compuesta para la clave de clasificación, debe incluir el prefijo `aws_dbe_b_` al especificar el nombre de la baliza. Si especifica una baliza firmada, especifique el nombre de la baliza sin ningún prefijo.
**Proyecciones de atributos**
Una [proyección](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.Projections) es el conjunto de atributos que se copia de una tabla en un índice secundario. La clave de partición y la clave de clasificación de la tabla siempre se proyectan en el índice; puede proyectar otros atributos para admitir los requisitos de consulta de la aplicación. DynamoDB ofrece tres opciones diferentes para las proyecciones de atributos`KEYS_ONLY`:`INCLUDE`, y. `ALL`
Si utiliza la proyección de atributos INCLUDE para buscar en una baliza, debe especificar los nombres de todos los atributos a partir de los que se construye la baliza y el nombre de la baliza con el `aws_dbe_b_` prefijo. Por ejemplo, si ha configurado una baliza compuesta`compoundBeacon`, desde `field1``field2`, y`field3`, debe especificar`aws_dbe_b_compoundBeacon`, `field1``field2`, y `field3` en la proyección.
Un índice secundario global solo puede usar los atributos especificados explícitamente en la proyección, pero un índice secundario local puede usar cualquier atributo.
## Probando las salidas de balizas
Si [configuró balizas compuestas](configure-beacons.md#config-compound-beacons) o construyó las balizas mediante [campos virtuales](configure-beacons.md#create-virtual-field), le recomendamos comprobar que estas balizas producen el resultado esperado antes de rellenar la tabla de DynamoDB.
El SDK de cifrado AWS de bases de datos proporciona el `DynamoDbEncryptionTransforms` servicio que le ayuda a solucionar los problemas de las salidas de balizas compuestas y de campo virtual.
### Probando campos virtuales
En el siguiente fragmento se crean elementos de prueba, se define el `DynamoDbEncryptionTransforms` servicio con la [configuración de cifrado de tablas de DynamoDB](ddb-java-using.md#ddb-config-encrypt) y se muestra cómo utilizarlos `ResolveAttributes` para comprobar que el campo virtual produce el resultado esperado.
------
#### [ Java ]
**Consulte el ejemplo de código completo**[: .java VirtualBeaconSearchableEncryptionExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption/VirtualBeaconSearchableEncryptionExample.java)
```
// Create test items
final PutItemRequest itemWithHasTestResultPutRequest = PutItemRequest.builder()
.tableName(ddbTableName)
.item(itemWithHasTestResult)
.build();
final PutItemResponse itemWithHasTestResultPutResponse = ddb.putItem(itemWithHasTestResultPutRequest);
final PutItemRequest itemWithNoHasTestResultPutRequest = PutItemRequest.builder()
.tableName(ddbTableName)
.item(itemWithNoHasTestResult)
.build();
final PutItemResponse itemWithNoHasTestResultPutResponse = ddb.putItem(itemWithNoHasTestResultPutRequest);
// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
.DynamoDbTablesEncryptionConfig(encryptionConfig).build();
// Verify configuration
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
.TableName(ddbTableName)
.Item(itemWithHasTestResult)
.Version(1)
.build();
final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);
// Verify that VirtualFields has the expected value
Map vf = new HashMap<>();
vf.put("stateAndHasTestResult", "CAt");
assert resolveOutput.VirtualFields().equals(vf);
```
------
#### [ C\$1 / .NET ]
**Consulte el ejemplo de código completo**: [VirtualBeaconSearchableEncryptionExample.cs.](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/VirtualBeaconSearchableEncryptionExample.cs)
```
// Create item with hasTestResult=true
var itemWithHasTestResult = new Dictionary
{
["customer_id"] = new AttributeValue("ABC-123"),
["create_time"] = new AttributeValue { N = "1681495205" },
["state"] = new AttributeValue("CA"),
["hasTestResult"] = new AttributeValue { BOOL = true }
};
// Create item with hasTestResult=false
var itemWithNoHasTestResult = new Dictionary
{
["customer_id"] = new AttributeValue("DEF-456"),
["create_time"] = new AttributeValue { N = "1681495205" },
["state"] = new AttributeValue("CA"),
["hasTestResult"] = new AttributeValue { BOOL = false }
};
// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);
// Verify configuration
var resolveInput = new ResolveAttributesInput
{
TableName = ddbTableName,
Item = itemWithHasTestResult,
Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);
// Verify that VirtualFields has the expected value
Debug.Assert(resolveOutput.VirtualFields.Count == 1);
Debug.Assert(resolveOutput.VirtualFields["stateAndHasTestResult"] == "CAt");
```
------
#### [ Rust ]
**Consulte el ejemplo de código completo**: [virtual\$1beacon\$1searchable\$1encryption.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/virtual_beacon_searchable_encryption.rs).
```
// Create item with hasTestResult=true
let item_with_has_test_result = HashMap::from([
(
"customer_id".to_string(),
AttributeValue::S("ABC-123".to_string()),
),
(
"create_time".to_string(),
AttributeValue::N("1681495205".to_string()),
),
("state".to_string(), AttributeValue::S("CA".to_string())),
("hasTestResult".to_string(), AttributeValue::Bool(true)),
]);
// Create item with hasTestResult=false
let item_with_no_has_test_result = HashMap::from([
(
"customer_id".to_string(),
AttributeValue::S("DEF-456".to_string()),
),
(
"create_time".to_string(),
AttributeValue::N("1681495205".to_string()),
),
("state".to_string(), AttributeValue::S("CA".to_string())),
("hasTestResult".to_string(), AttributeValue::Bool(false)),
]);
// Define the transform service
let trans = transform_client::Client::from_conf(encryption_config.clone())?;
// Verify the configuration
let resolve_output = trans
.resolve_attributes()
.table_name(ddb_table_name)
.item(item_with_has_test_result.clone())
.version(1)
.send()
.await?;
// Verify that VirtualFields has the expected value
let virtual_fields = resolve_output.virtual_fields.unwrap();
assert_eq!(virtual_fields.len(), 1);
assert_eq!(virtual_fields["stateAndHasTestResult"], "CAt");
```
------
### Probando balizas compuestas
En el siguiente fragmento se crea un elemento de prueba, se define el `DynamoDbEncryptionTransforms` servicio con la [configuración de cifrado de la tabla de DynamoDB](ddb-java-using.md#ddb-config-encrypt) y se muestra cómo se utiliza `ResolveAttributes` para comprobar que la baliza compuesta produce el resultado esperado.
------
#### [ Java ]
**Consulte el ejemplo de código completo**[: .java CompoundBeaconSearchableEncryptionExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption/CompoundBeaconSearchableEncryptionExample.java)
```
// Create an item with both attributes used in the compound beacon.
final HashMap item = new HashMap<>();
item.put("work_id", AttributeValue.builder().s("9ce39272-8068-4efd-a211-cd162ad65d4c").build());
item.put("inspection_date", AttributeValue.builder().s("2023-06-13").build());
item.put("inspector_id_last4", AttributeValue.builder().s("5678").build());
item.put("unit", AttributeValue.builder().s("011899988199").build());
// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
.DynamoDbTablesEncryptionConfig(encryptionConfig).build();
// Verify configuration
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
.TableName(ddbTableName)
.Item(item)
.Version(1)
.build();
final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);
// Verify that CompoundBeacons has the expected value
Map cbs = new HashMap<>();
cbs.put("last4UnitCompound", "L-5678.U-011899988199");
assert resolveOutput.CompoundBeacons().equals(cbs);
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon
```
------
#### [ C\$1 / .NET ]
**[Consulte el ejemplo de código completo: .cs CompoundBeaconSearchableEncryptionExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/CompoundBeaconSearchableEncryptionExample.cs)**
```
// Create an item with both attributes used in the compound beacon
var item = new Dictionary
{
["work_id"] = new AttributeValue("9ce39272-8068-4efd-a211-cd162ad65d4c"),
["inspection_date"] = new AttributeValue("2023-06-13"),
["inspector_id_last4"] = new AttributeValue("5678"),
["unit"] = new AttributeValue("011899988199")
};
// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);
// Verify configuration
var resolveInput = new ResolveAttributesInput
{
TableName = ddbTableName,
Item = item,
Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);
// Verify that CompoundBeacons has the expected value
Debug.Assert(resolveOutput.CompoundBeacons.Count == 1);
Debug.Assert(resolveOutput.CompoundBeacons["last4UnitCompound"] == "L-5678.U-011899988199");
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon
```
------
#### [ Rust ]
**Consulte el ejemplo de código completo**[: compound\$1beacon\$1searchable\$1encryption.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/compound_beacon_searchable_encryption.rs)
```
// Create an item with both attributes used in the compound beacon
let item = HashMap::from([
(
"work_id".to_string(),
AttributeValue::S("9ce39272-8068-4efd-a211-cd162ad65d4c".to_string()),
),
(
"inspection_date".to_string(),
AttributeValue::S("2023-06-13".to_string()),
),
(
"inspector_id_last4".to_string(),
AttributeValue::S("5678".to_string()),
),
(
"unit".to_string(),
AttributeValue::S("011899988199".to_string()),
),
]);
// Define the transforms service
let trans = transform_client::Client::from_conf(encryption_config.clone())?;
// Verify configuration
let resolve_output = trans
.resolve_attributes()
.table_name(ddb_table_name)
.item(item.clone())
.version(1)
.send()
.await?;
// Verify that CompoundBeacons has the expected value
let compound_beacons = resolve_output.compound_beacons.unwrap();
assert_eq!(compound_beacons.len(), 1);
assert_eq!(
compound_beacons["last4UnitCompound"],
"L-5678.U-011899988199"
);
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon
```
------
# Actualización de su modelo de datos
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de datos. AWS En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
[Al configurar el SDK de cifrado AWS de bases de datos para DynamoDB, proporciona acciones de atributos.](concepts.md#crypt-actions) Al cifrar, el SDK de cifrado de AWS bases de datos utiliza las acciones de atributos para identificar qué atributos cifrar y firmar, qué atributos firmar (pero no cifrar) y cuáles ignorar. También [se definen los atributos no firmados permitidos](ddb-java-using.md#allowed-unauth) para indicar explícitamente al cliente qué atributos están excluidos de las firmas. Al descifrar, el SDK de cifrado AWS de bases de datos utiliza los atributos no firmados permitidos que usted definió para identificar qué atributos no están incluidos en las firmas. Las acciones de los atributos no se guardan en el elemento cifrado y el SDK de cifrado AWS de bases de datos no actualiza las acciones de los atributos automáticamente.
Elija cuidadosamente sus acciones de atributo. En caso de duda, use **Encrypt and sign**. Una vez que haya utilizado el SDK de cifrado de AWS bases de datos para proteger sus elementos, no podrá cambiar un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo existente `ENCRYPT_AND_SIGN` o uno a`DO_NOTHING`. `SIGN_ONLY` Puede hacer los siguientes cambios.
+ [Agregue `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributos nuevos `ENCRYPT_AND_SIGN` y `SIGN_ONLY`](#ddb-add-auth-attribute)
+ [Elimine los atributos existentes](#ddb-remove-attribute)
+ [Cambie un `ENCRYPT_AND_SIGN` atributo existente a `SIGN_ONLY` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](#ddb-encrypt-to-sign)
+ [Cambie un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo `SIGN_ONLY` o existente a `ENCRYPT_AND_SIGN`](#ddb-sign-to-encrypt)
+ [Añada un atributo `DO_NOTHING` nuevo](#ddb-add-unauth-attribute)
+ [Cambio de un atributo `SIGN_ONLY` existente a `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](#ddb-signOnly-to-signInclude)
+ [Cambio de un atributo `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` existente a `SIGN_ONLY`](#ddb-signInclude-to-signOnly)
**Consideraciones sobre el cifrado con capacidad de búsqueda**
Antes de actualizar el modelo de datos, considere detenidamente cómo podrían afectar las actualizaciones a las [balizas](beacons.md) que haya creado a partir de los atributos. Una vez que haya escrito nuevos registros con una baliza, no puede actualizar la configuración de la baliza. No puede actualizar las acciones de los atributos asociadas a los atributos que utilizó para construir balizas. Si elimina un atributo existente y su baliza asociada, no podrá consultar los registros existentes con esa baliza. Puede crear balizas nuevas para los campos nuevos que añada a su registro, pero no puede actualizar las balizas existentes para incluir el nuevo campo.
**Consideraciones sobre los `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributos**
De forma predeterminada, la partición y las claves de clasificación son el único atributo incluido en el contexto de cifrado. Podría considerar la posibilidad de definir campos adicionales para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` que el proveedor del identificador de clave de rama de su conjunto de [claves AWS KMS jerárquicas pueda identificar](use-hierarchical-keyring.md) qué clave de rama es necesaria para el descifrado a partir del contexto de cifrado. Para obtener más información, consulte el proveedor de ID de [clave de sucursal](use-hierarchical-keyring.md#branch-key-id-supplier). Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**nota**
Para utilizar la acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, debe utilizar la versión 3.3 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de [actualizar su modelo de datos](#ddb-update-data-model) para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` incluirla.
## Agregue `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributos nuevos `ENCRYPT_AND_SIGN` y `SIGN_ONLY`
Para añadir un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo o un nuevo `ENCRYPT_AND_SIGN` atributo, defina el nuevo atributo en las acciones de sus atributos. `SIGN_ONLY`
No puede eliminar un `DO_NOTHING` atributo existente y volver a añadirlo como `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo `ENCRYPT_AND_SIGN``SIGN_ONLY`, o.
**Uso de una clase de datos anotada**
Si ha definido las acciones de los atributos con una`TableSchema`, añada el nuevo atributo a la clase de datos anotada. Si no especificas una anotación de acción de atributo para el nuevo atributo, el cliente cifrará y firmará el nuevo atributo de forma predeterminada (a menos que el atributo forme parte de la clave principal). Si solo quiere firmar el nuevo atributo, debe añadirlo con la `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotación `@DynamoDBEncryptionSignOnly` o.
**Uso de un objeto de modelo**
Si ha definido manualmente las acciones de los atributos, añada el nuevo atributo a las acciones de los atributos del modelo de objetos y especifique `ENCRYPT_AND_SIGN``SIGN_ONLY`, o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` como acción de atributo.
## Elimine los atributos existentes
Si decide que ya no necesita un atributo, puede dejar de escribir datos en ese atributo o puede eliminarlo formalmente de las acciones de sus atributos. Cuando dejas de escribir nuevos datos en un atributo, el atributo sigue apareciendo en las acciones de tus atributos. Esto puede resultar útil si necesita volver a utilizar el atributo en el futuro. Si eliminas formalmente el atributo de tus acciones de atributos, no lo eliminas de tu conjunto de datos. Su conjunto de datos seguirá conteniendo elementos que incluyan ese atributo.
Para eliminar formalmente un atributo `ENCRYPT_AND_SIGN``SIGN_ONLY`, o un `DO_NOTHING` atributo existente`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, actualice las acciones de sus atributos.
Si elimina un atributo `DO_NOTHING`, no debe eliminarlo de los [atributos no firmados permitidos](ddb-java-using.md#allowed-unauth). Aunque ya no escriba valores nuevos en ese atributo, el cliente necesitará saber que el atributo no está firmado para poder leer los elementos existentes que lo contienen.
**Uso de una clase de datos anotada**
Si ha definido las acciones de los atributos con una `TableSchema`, elimine el atributo de la clase de datos anotada.
**Uso de un objeto de modelo**
Si definió manualmente las acciones de los atributos, elimine el atributo de las acciones de los atributos del modelo de objetos.
## Cambie un `ENCRYPT_AND_SIGN` atributo existente a `SIGN_ONLY` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
Para cambiar un `ENCRYPT_AND_SIGN` atributo existente a `SIGN_ONLY` o`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, debe actualizar las acciones de su atributo. Tras implementar la actualización, el cliente podrá verificar y descifrar los valores existentes escritos en el atributo, pero solo firmará los nuevos valores escritos en el atributo.
**nota**
Tenga en cuenta detenidamente sus requisitos de seguridad antes de cambiar un `ENCRYPT_AND_SIGN` atributo existente a `SIGN_ONLY` o`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Cualquier atributo que pueda almacenar datos confidenciales debe estar cifrado.
**Uso de una clase de datos anotada**
Si ha definido las acciones de los atributos con una`TableSchema`, actualice el atributo existente para incluir la `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotación `@DynamoDBEncryptionSignOnly` o en la clase de datos anotada.
**Uso de un objeto de modelo**
Si ha definido manualmente las acciones de atributo, actualice la acción de atributo asociada al atributo existente desde `ENCRYPT_AND_SIGN` `SIGN_ONLY` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` en su modelo de objetos.
## Cambie un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo `SIGN_ONLY` o existente a `ENCRYPT_AND_SIGN`
Para cambiar un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo `SIGN_ONLY` o un atributo existente a`ENCRYPT_AND_SIGN`, debe actualizar las acciones de sus atributos. Tras implementar la actualización, el cliente podrá comprobar los valores existentes escritos en el atributo y cifrará y firmará los nuevos valores escritos en el atributo.
**Uso de una clase de datos anotada**
Si ha definido las acciones de sus atributos con una`TableSchema`, elimine la `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotación `@DynamoDBEncryptionSignOnly` o del atributo existente.
**Uso de un objeto de modelo**
Si ha definido manualmente las acciones de atributo, actualice la acción de atributo asociada al atributo desde `SIGN_ONLY` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` hacia `ENCRYPT_AND_SIGN` en su modelo de objetos.
## Añada un atributo `DO_NOTHING` nuevo
Para reducir el riesgo de errores al añadir un atributo `DO_NOTHING` nuevo, le recomendamos que especifique un prefijo distinto al asignar un nombre a los atributos `DO_NOTHING` y, a continuación, utilizar ese prefijo para definir los atributos no [firmados permitidos](ddb-java-using.md#allowed-unauth).
No puede eliminar un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo o atributo existente `ENCRYPT_AND_SIGN` de la clase de datos anotada y`SIGN_ONLY`, a continuación, volver a añadir el atributo como `DO_NOTHING` atributo. Solo puede agregar atributos `DO_NOTHING` completamente nuevos.
Los pasos que siga para añadir un atributo `DO_NOTHING` nuevo dependerán de si ha definido los atributos no firmados permitidos de forma explícita en una lista o con un prefijo.
**Utilizar un prefijo de atributos no firmados permitido**
Si ha definido las acciones de los atributos con un `TableSchema`, añada el atributo `DO_NOTHING` nuevo a la clase de datos anotada con la anotación `@DynamoDBEncryptionDoNothing`. Si ha definido manualmente las acciones de los atributos, actualice las acciones de los atributos para incluir el nuevo atributo. Asegúrese de configurar explícitamente el nuevo atributo con la acción de atributo `DO_NOTHING`. Debe incluir el mismo prefijo distinto en el nombre del nuevo atributo.
**Utilizar una lista de atributos no firmados permitidos**
1. Añada el atributo `DO_NOTHING` nuevo a la lista de atributos no firmados permitidos e implemente la lista actualizada.
1. Implemente el cambio desde el **paso 1**.
No puede continuar con el **paso 3** hasta que el cambio se haya propagado a todos los hosts que necesiten leer estos datos.
1. Añada el atributo `DO_NOTHING` nuevo a las acciones de sus atributos.
1. Si ha definido las acciones de los atributos con un `TableSchema`, añada el atributo `DO_NOTHING` nuevo a la clase de datos anotada con la anotación `@DynamoDBEncryptionDoNothing`.
1. Si ha definido manualmente las acciones de los atributos, actualice las acciones de los atributos para incluir el nuevo atributo. Asegúrese de configurar explícitamente el nuevo atributo con la acción de atributo `DO_NOTHING`.
1. Implemente el cambio desde el **paso 3**.
## Cambio de un atributo `SIGN_ONLY` existente a `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
Para cambiar un atributo existente `SIGN_ONLY` a `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, debe actualizar las acciones del atributo. Tras implementar la actualización, el cliente podrá comprobar los valores existentes escritos en el atributo y seguirá firmando los nuevos valores escritos en el atributo. Los nuevos valores escritos en el atributo se incluirán en el [contexto de cifrado](concepts.md#encryption-context).
Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**Uso de una clase de datos anotada**
Si ha definido sus acciones de atributo con una`TableSchema`, actualice la acción de atributo asociada al atributo de `@DynamoDBEncryptionSignOnly` a`@DynamoDBEncryptionSignAndIncludeInEncryptionContext`.
**Uso de un objeto de modelo**
Si ha definido manualmente las acciones de atributo, actualice la acción de atributo asociada al atributo de `SIGN_ONLY` a `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` en su modelo de objetos.
## Cambio de un atributo `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` existente a `SIGN_ONLY`
Para cambiar un atributo existente `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` a `SIGN_ONLY`, debe actualizar las acciones del atributo. Tras implementar la actualización, el cliente podrá comprobar los valores existentes escritos en el atributo y seguirá firmando los nuevos valores escritos en el atributo. Los nuevos valores escritos en el atributo no se incluirán en el [contexto de cifrado](concepts.md#encryption-context).
Antes de cambiar un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo existente a`SIGN_ONLY`, considere detenidamente cómo sus actualizaciones podrían afectar a la funcionalidad de su [proveedor de ID de clave de sucursal](use-hierarchical-keyring.md#branch-key-id-supplier).
**Uso de una clase de datos anotada**
Si ha definido sus acciones de atributo con una`TableSchema`, actualice la acción de atributo asociada al atributo de `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` a`@DynamoDBEncryptionSignOnly`.
**Uso de un objeto de modelo**
Si ha definido manualmente las acciones de atributo, actualice la acción de atributo asociada al atributo de `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` a `SIGN_ONLY` en su modelo de objetos.
# AWS SDK de cifrado de bases de datos para los lenguajes de programación disponibles en DynamoDB
El SDK AWS de cifrado de bases de datos para DynamoDB está disponible para los siguientes lenguajes de programación. Las bibliotecas específicas de lenguaje varían, pero las implementaciones resultantes son interoperables. Puede cifrar con una implementación de lenguaje y descifrar con otra. La interoperabilidad puede estar sujeta a restricciones de lenguaje. Si es así, estas restricciones se describen en el tema que trata de la implementación del lenguaje.
**Topics**
+ [Java](ddb-java.md)
+ [.NET](ddb-net.md)
+ [Rust](ddb-rust.md)
# Java
****
| |
| --- |
| 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). |
En este tema se explica cómo instalar y usar la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB. Para obtener más información sobre la programación con el SDK AWS de cifrado de bases de datos para DynamoDB, consulte los ejemplos de [Java en el repositorio -dynamodb](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) en aws-database-encryption-sdk. GitHub
**nota**
Los siguientes temas se centran en la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB.
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). El SDK AWS de cifrado de bases de datos sigue siendo compatible con las versiones [antiguas de DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md).
**Topics**
+ [Requisitos previos](#ddb-java-prerequisites)
+ [Instalación](#ddb-java-installation)
+ [Uso de la biblioteca de cliente de Java](ddb-java-using.md)
+ [Ejemplos de Java](ddb-java-examples.md)
+ [Agregar la versión 3.x a una tabla existente](ddb-java-config-existing-table.md)
+ [Migrar a la versión 3.x](ddb-java-migrate.md)
## Requisitos previos
Antes de instalar la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB, asegúrese de cumplir los siguientes requisitos previos.
**Un entorno de desarrollo de Java**
Necesitará Java 8 o una versión posterior. En el sitio web de Oracle, vaya a la página de [descargas de Java SE](https://www.oracle.com/java/technologies/downloads/) y, a continuación, descargue e instale el Java SE Development Kit (JDK).
Si utiliza el JDK de Oracle, también debe descargar e instalar los [archivos de políticas de jurisdicción de seguridad ilimitada de la extensión de criptografía de Java (JCE)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).
**AWS SDK for Java 2.x**
El SDK AWS de cifrado de bases de datos para DynamoDB requiere el módulo [DynamoDB Enhanced Client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) del. AWS SDK for Java 2.x Puede instalar todo el SDK o solo este módulo.
Para obtener información sobre cómo actualizar su versión de AWS SDK para Java, consulte [Migración de la versión 1.x a la 2.x del](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html). AWS SDK para Java
AWS SDK para Java Está disponible a través de Apache Maven. Puede declarar una dependencia para todo AWS SDK para Java el `dynamodb-enhanced` módulo o solo para él.
**Instálelo AWS SDK para Java con Apache Maven**
+ Para [importar todo AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) como una dependencia declárelo en el archivo `pom.xml`.
+ Para crear una dependencia solo para el módulo Amazon DynamoDB en el AWS SDK para Java, siga las instrucciones para [especificar módulos concretos](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies). Establece el `groupId` para y el para.`software.amazon.awssdk` `artifactID` `dynamodb-enhanced`
**nota**
Si usa el anillo de AWS KMS claves o el anillo de claves AWS KMS jerárquico, también necesita crear una dependencia para el módulo. AWS KMS Establece el `groupId` en `software.amazon.awssdk` y el `artifactID` en `kms`.
## Instalación
Puede instalar la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB de las siguientes maneras.
**Con Apache Maven**
El Cliente de encriptación de Amazon DynamoDB para Java está disponible en [Apache Maven](https://maven.apache.org/) con la siguiente definición de dependencias.
```
software.amazon.cryptography
aws-database-encryption-sdk-dynamodb
version-number
```
**Uso de Gradle Kotlin**
Puede usar [Gradle](https://gradle.org/) para declarar una dependencia en el Cliente de encriptación de Amazon DynamoDB para Java añadiendo lo siguiente *a* la sección de dependencias de su proyecto de Gradle.
```
implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:version-number")
```
**Manualmente**
[Para instalar la biblioteca de cifrado del lado del cliente de Java para DynamoDB, clone o descargue el repositorio -dynamodb. aws-database-encryption-sdk](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) GitHub
Tras instalar el SDK, comience por consultar el código de ejemplo de esta guía y los ejemplos de [Java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) del repositorio -dynamodb de. aws-database-encryption-sdk GitHub
# Usar la biblioteca de cifrado del cliente de Java para DynamoDB
****
| |
| --- |
| 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). |
En este tema se explican algunas de las funciones y clases de ayuda de la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB.
[Para obtener más información sobre la programación con la biblioteca de cifrado del lado del cliente de Java para DynamoDB, consulte los ejemplos de Java y los [ejemplos de Java](java-examples.md) en el repositorio -dynamodb de.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) aws-database-encryption-sdk GitHub
**Topics**
+ [Encriptadores de elementos](#ddb-item-encryptors)
+ [Acciones de atributo](#ddb-attribute-actions)
+ [La configuración de cifrado](#ddb-config-encrypt)
+ [Actualización de un elemento](#ddb-update-items)
+ [Descifrado de conjuntos firmados](#ddb-java-signed-sets)
## Encriptadores de elementos
En esencia, el SDK de cifrado AWS de bases de datos para DynamoDB es un cifrador de elementos. Puede utilizar la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB para cifrar, firmar, verificar y descifrar los elementos de la tabla de DynamoDB de las siguientes maneras.
**El cliente mejorado de DynamoDB**
Puede configurar el [cliente mejorado de DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) con el `DynamoDbEncryptionInterceptor` para cifrar y firmar automáticamente los elementos del lado del cliente con sus solicitudes `PutItem` de DynamoDB. Con el cliente mejorado de DynamoDB, puede definir las acciones de sus atributos mediante [una](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) clase de datos anotada. Recomendamos utilizar el cliente mejorado de DynamoDB siempre que sea posible.
El cliente mejorado de DynamoDB no admite [el cifrado con capacidad de búsqueda.](searchable-encryption.md)
[El SDK AWS de cifrado de bases de datos no admite anotaciones en atributos anidados.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html)
**API de bajo nivel de DynamoDB**
Puede configurar la API de [DynamoDB de bajo nivel](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html) para cifrar y firmar automáticamente los elementos `DynamoDbEncryptionInterceptor` del lado del cliente con sus solicitudes de DynamoDB. `PutItem`
Debe usar la API de DynamoDB de bajo nivel para utilizar el cifrado [con capacidad de búsqueda](searchable-encryption.md).
**El nivel inferior `DynamoDbItemEncryptor`**
El nivel inferior cifra y firma o descifra y verifica `DynamoDbItemEncryptor` directamente los elementos de la tabla sin llamar a DynamoDB. No realiza DynamoDB ni `PutItem` solicitudes`GetItem`. Por ejemplo, puede usar el nivel inferior `DynamoDbItemEncryptor` para descifrar y verificar directamente un elemento de DynamoDB que ya haya recuperado.
El nivel inferior `DynamoDbItemEncryptor` no admite el cifrado [con capacidad de búsqueda.](searchable-encryption.md)
## Acciones de atributos en el SDK de cifrado AWS de bases de datos para DynamoDB
[Las acciones de atributos](concepts.md#crypt-actions) determinan qué valores de atributo están cifrados y firmados, cuáles solo están firmados, cuáles están firmados e incluidos en el contexto de cifrado y cuáles se ignoran.
**nota**
Para utilizar la acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, debe utilizar la versión 3.3 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de [actualizar su modelo de datos](ddb-update-data-model.md) para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` incluirla.
Si utiliza la API de DynamoDB de bajo nivel o el `DynamoDbItemEncryptor` nivel inferior, debe definir manualmente las acciones de los atributos. Si usa el cliente mejorado de DynamoDB, puede definir manualmente las acciones de sus atributos o puede usar una clase de datos anotada para [generar un. `TableSchema`](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html) Para simplificar el proceso de configuración, se recomienda utilizar una clase de datos anotada. Cuando utiliza una clase de datos anotada, solo tiene que modelar el objeto una vez.
**nota**
Tras definir las acciones de los atributos, debe definir qué atributos se excluyen de las firmas. Para facilitar la adición de nuevos atributos sin firmar en el futuro, recomendamos elegir un prefijo distinto (como “`:`“) para identificar los atributos sin firmar. Incluya este prefijo en el nombre del atributo para todos los atributos marcados `DO_NOTHING` al definir el esquema y las acciones de atributos de DynamoDB.
### Utilice una clase de datos anotada
Utilice una [clase de datos anotada](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) para especificar las acciones de sus atributos con el cliente mejorado de DynamoDB y. `DynamoDbEncryptionInterceptor` El SDK de cifrado de bases de datos de AWS para DynamoDB utiliza las anotaciones de atributo estándar de DynamoDB [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html)que definen el tipo de atributo para determinar cómo proteger un atributo. De forma predeterminada, todos los atributos están cifrados y firmados, excepto las claves principales, que están firmadas, pero no cifradas.
**nota**
Para usar la acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, debe usar la versión 3.3 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de [actualizar su modelo de datos](ddb-update-data-model.md) para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` incluirla.
Consulte [SimpleClass.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) en el repositorio aws-database-encryption-sdk -dynamodb GitHub para obtener más información sobre las anotaciones del cliente mejorado de DynamoDB.
De forma predeterminada, los atributos de la clave principal están firmados pero no cifrados (`SIGN_ONLY`) y todos los demás atributos están cifrados y firmados `ENCRYPT_AND_SIGN`(). Si define algún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, los atributos de partición y ordenación también deben serlo. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Para especificar las excepciones, utilice las anotaciones de cifrado que se definen en la biblioteca de cifrado del cliente de Java para DynamoDB. Por ejemplo, si desea que un atributo concreto solo esté firmado, utilice la `@DynamoDbEncryptionSignOnly` anotación. Si desea que un atributo concreto se firme e incluya en el contexto de cifrado, utilice el`@DynamoDbEncryptionSignAndIncludeInEncryptionContext`. Si desea que un atributo concreto no esté firmado ni cifrado (`DO_NOTHING`), utilice la anotación `@DynamoDbEncryptionDoNothing`.
**nota**
El SDK AWS de cifrado de bases de datos no admite anotaciones en atributos [anidados](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html).
En el siguiente ejemplo, se muestran las anotaciones utilizadas para definir y `ENCRYPT_AND_SIGN` `SIGN_ONLY` `DO_NOTHING` atribuir acciones. [Para ver un ejemplo que muestre las anotaciones utilizadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte SimpleClass 4.java.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java)
```
@DynamoDbBean
public class SimpleClass {
private String partitionKey;
private int sortKey;
private String attribute1;
private String attribute2;
private String attribute3;
@DynamoDbPartitionKey
@DynamoDbAttribute(value = "partition_key")
public String getPartitionKey() {
return this.partitionKey;
}
public void setPartitionKey(String partitionKey) {
this.partitionKey = partitionKey;
}
@DynamoDbSortKey
@DynamoDbAttribute(value = "sort_key")
public int getSortKey() {
return this.sortKey;
}
public void setSortKey(int sortKey) {
this.sortKey = sortKey;
}
public String getAttribute1() {
return this.attribute1;
}
public void setAttribute1(String attribute1) {
this.attribute1 = attribute1;
}
@DynamoDbEncryptionSignOnly
public String getAttribute2() {
return this.attribute2;
}
public void setAttribute2(String attribute2) {
this.attribute2 = attribute2;
}
@DynamoDbEncryptionDoNothing
public String getAttribute3() {
return this.attribute3;
}
@DynamoDbAttribute(value = ":attribute3")
public void setAttribute3(String attribute3) {
this.attribute3 = attribute3;
}
}
```
Utilice la clase de datos anotada para crearla tal y `TableSchema` como se muestra en el siguiente fragmento.
```
final TableSchema tableSchema = TableSchema.fromBean(SimpleClass.class);
```
### Defina manualmente las acciones de sus atributos
Para especificar las acciones de atributo cuando se utiliza el DynamoDBEncryptor directamente, cree un objeto `Map` en el que las parejas de nombre-valor representen nombres de atributo y las acciones especificadas.
Especifique `ENCRYPT_AND_SIGN` si desea cifrar y firmar un atributo. Especifique `SIGN_ONLY` firmar, pero no cifrar, un atributo. Especifique si `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` desea firmar un atributo e incluirlo en el contexto de cifrado. No se puede cifrar un atributo sin firmarlo también. Especifique `DO_NOTHING` que se omita un atributo.
Los atributos de partición y ordenación deben ser uno de `SIGN_ONLY` los dos`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Si define algún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**nota**
Para utilizar la acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, debe utilizar la versión 3.3 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de [actualizar su modelo de datos](ddb-update-data-model.md) para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` incluirla.
```
final Map attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be signed
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT);
// The sort attribute must be signed
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT);
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put("attribute3", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT);
attributeActionsOnEncrypt.put(":attribute4", CryptoAction.DO_NOTHING);
```
## Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB
Al utilizar el SDK de cifrado AWS de bases de datos, debe definir explícitamente una configuración de cifrado para la tabla de DynamoDB. Los valores necesarios en la configuración de cifrado dependen de si ha definido las acciones de los atributos manualmente o con una clase de datos anotada.
El siguiente fragmento define una configuración de cifrado de tablas de DynamoDB mediante el cliente mejorado de DynamoDB y los atributos no firmados permitidos definidos por un prefijo [https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html)distinto.
```
final Map tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
DynamoDbEnhancedTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.schemaOnEncrypt(tableSchema)
// Optional: only required if you use beacons
.search(SearchConfig.builder()
.writeVersion(1) // MUST be 1
.versions(beaconVersions)
.build())
.build());
```
**Nombre de la tabla lógica**
Un nombre de tabla lógico para la tabla de DynamoDB.
El nombre de la tabla lógica está enlazado criptográficamente a todos los datos almacenados en la tabla para simplificar las operaciones de restauración de DynamoDB. Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Debe especificar siempre el mismo nombre de tabla lógica. Para que el descifrado se realice correctamente, el nombre de la tabla lógica debe coincidir con el nombre especificado en el cifrado. En caso de que el nombre de la tabla de DynamoDB cambie después de [restaurar la tabla de DynamoDB a partir de una copia de seguridad, el nombre de la tabla](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html) lógica garantiza que la operación de descifrado siga reconociendo la tabla.
**Atributos no firmados permitidos**
Los atributos marcados `DO_NOTHING` en tus acciones de atributos.
Los atributos no firmados permitidos indican al cliente qué atributos están excluidos de las firmas. El cliente asume que todos los demás atributos están incluidos en la firma. A continuación, al descifrar un registro, el cliente determina qué atributos debe verificar y cuáles debe ignorar de los atributos no firmados permitidos que especificó. No puede eliminar un atributo de los atributos no firmados permitidos.
Puede definir los atributos no firmados permitidos de forma explícita mediante la creación de una matriz que enumere todos sus `DO_NOTHING` atributos. También puedes especificar un prefijo distinto al asignar un nombre a tus `DO_NOTHING` atributos y usar el prefijo para indicar al cliente qué atributos no están firmados. Recomendamos encarecidamente especificar un prefijo distinto porque simplifica el proceso de añadir un nuevo `DO_NOTHING` atributo en el futuro. Para obtener más información, consulte [Actualización de su modelo de datos](ddb-update-data-model.md).
Si no especifica un prefijo para todos los `DO_NOTHING` atributos, puede configurar una `allowedUnsignedAttributes` matriz que enumere de forma explícita todos los atributos que el cliente debería esperar que no estén firmados cuando los encuentre al descifrarlos. Solo debe definir de forma explícita los atributos no firmados permitidos si es absolutamente necesario.
**Configuración de búsqueda (opcional)**
`SearchConfig`Define la [versión de baliza](using-beacons.md#beacon-version).
`SearchConfig`Debe especificarse para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifradas con capacidad de búsqueda](searchable-encryption.md).
**Conjunto de algoritmos (opcional)**
El `algorithmSuiteId` define qué conjunto de algoritmos utiliza el SDK de cifrado de bases de datos de AWS .
A menos que especifique explícitamente un conjunto de algoritmos alternativo, el SDK AWS de cifrado de bases de datos utiliza el [conjunto de algoritmos predeterminado](supported-algorithms.md#recommended-algorithms). [El conjunto de algoritmos predeterminado utiliza el algoritmo AES-GCM con la derivación de claves, [las firmas digitales](concepts.md#digital-sigs) y el compromiso de claves.](concepts.md#key-commitment) Aunque es probable que el conjunto de algoritmos predeterminado sea adecuado para la mayoría de las aplicaciones, puede elegir un conjunto de algoritmos alternativo. Por ejemplo, algunos modelos de confianza quedarían satisfechos con un conjunto de algoritmos sin firmas digitales. Para obtener información sobre los conjuntos de algoritmos compatibles con el SDK AWS de cifrado de bases de datos, consulte[Conjuntos de algoritmos compatibles en el SDK de cifrado AWS de bases de datos](supported-algorithms.md).
Para seleccionar el [conjunto de algoritmos AES-GCM sin firmas digitales ECDSA](supported-algorithms.md#other-algorithms), incluya el siguiente fragmento en la configuración de cifrado de la tabla.
```
.algorithmSuiteId(
DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)
```
## Actualización de elementos con el SDK de cifrado de bases de datos AWS
El SDK AWS de cifrado de bases de datos no admite [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para elementos cifrados o firmados. Para actualizar un elemento cifrado o firmado, debe usar [ddb](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html):. PutItem Cuando se especifica la misma clave principal que un elemento existente en la solicitud `PutItem`, el nuevo elemento sustituye completamente al existente. También puedes usar [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) para borrar y reemplazar todos los atributos al guardar después de actualizar tus artículos.
## Descifrado de conjuntos firmados
En las versiones 3.0.0 y 3.1.0 del SDK de cifrado de AWS bases de datos, si define un atributo de [tipo de conjunto](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes) como`SIGN_ONLY`, los valores del conjunto se canonicalizan en el orden en que se proporcionan. DynamoDB no mantiene el orden de los conjuntos. Como resultado, existe la posibilidad de que se produzca un error al intentar la firma del elemento que contiene el conjunto. La validación de firmas falla cuando los valores del conjunto se devuelven en un orden diferente al que se proporcionaron al SDK de cifrado de AWS bases de datos, incluso si los atributos del conjunto contienen los mismos valores.
**nota**
Las versiones 3.1.1 y posteriores del SDK de cifrado de AWS bases de datos canonicalizan los valores de todos los atributos de tipo establecido, de modo que los valores se leen en el mismo orden en que se escribieron en DynamoDB.
Si se produce un error durante la validación de la firma, la operación de descifrado también sufre un error y devuelve el siguiente mensaje de error.
| |
| --- |
| software.amazon.cryptography.dbencryptionsdk.structuredencryption.model. StructuredEncryptionException: No hay ninguna etiqueta de destinatario coincidente. |
Si recibe el mensaje de error anterior y cree que el elemento que está intentando descifrar incluye un conjunto que se firmó con las versiones 3.0.0 o 3.1.0, consulte el [DecryptWithPermute](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/tree/v3.1.1/DecryptWithPermute)directorio del repositorio aws-database-encryption-sdk -dynamodb-java GitHub para obtener más información sobre cómo validar correctamente el conjunto.
# Ejemplos de Java
****
| |
| --- |
| 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). |
Los siguientes ejemplos muestran cómo utilizar la biblioteca de cifrado del cliente de Java para DynamoDB para proteger los elementos de tabla en su aplicación. Puedes encontrar más ejemplos (y añadir los tuyos propios) en los [ejemplos de Java del repositorio](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) aws-database-encryption-sdk -dynamodb de. GitHub
Los siguientes ejemplos muestran cómo configurar la biblioteca de cifrado del cliente de Java para DynamoDB en una tabla de Amazon DynamoDB nueva y sin rellenar. Si desea configurar las tablas de Amazon DynamoDB existentes para el cifrado del cliente, consulte. [Agregar la versión 3.x a una tabla existente](ddb-java-config-existing-table.md)
**Topics**
+ [Uso del cliente mejorado de DynamoDB](#ddb-java-enhanced-client-example)
+ [API de bajo nivel de DynamoDB](#ddb-java-lowlevel-API-example)
+ [Usando el nivel inferior DynamoDbItemEncryptor](#ddb-java-itemencryptor)
## Uso del cliente mejorado de DynamoDB
En el siguiente ejemplo, se muestra cómo utilizar el cliente mejorado de DynamoDB y el `DynamoDbEncryptionInterceptor` con un [conjunto de claves de AWS KMS](use-kms-keyring.md) para cifrar los elementos de la tabla de DynamoDB como parte de las llamadas a la API de DynamoDB.
Puede utilizar cualquier conjunto de [claves compatible con el cliente mejorado de DynamoDB, pero le recomendamos que utilice uno de los anillos](keyrings.md) de AWS KMS claves siempre que sea posible.
**nota**
El cliente mejorado de DynamoDB no admite [el cifrado con capacidad de búsqueda.](searchable-encryption.md) Úselo `DynamoDbEncryptionInterceptor` con el API de bajo nivel de DynamoDB para usar el cifrado con capacidad de búsqueda.
**Consulte el ejemplo de código completo**[: .java EnhancedPutGetExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPutGetExample.java)
**Paso 1: Crea el llavero AWS KMS **
El siguiente ejemplo se utiliza `CreateAwsKmsMrkMultiKeyring` para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**Paso 2: crear un esquema de tabla a partir de la clase de datos anotados**
En el siguiente ejemplo, se utiliza la clase de datos anotada para crear la `TableSchema`.
[En este ejemplo, se supone que las acciones de clase y atributo de datos anotados se definieron mediante .java. SimpleClass](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) Para obtener más información sobre cómo anotar las acciones de los atributos, consulte [Utilice una clase de datos anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).
[El SDK AWS de cifrado de bases de datos no admite anotaciones en atributos anidados.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html)
```
final TableSchema schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);
```
**Paso 3: defina qué atributos se excluyen de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asume que cualquier nombre de atributo con el prefijo “`:`” está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).
```
final String unsignedAttrPrefix = ":";
```
**Paso 4: crear el contexto de cifrado**
En el siguiente ejemplo, se define un mapa `tableConfigs` que representa la configuración de cifrado de la tabla de DynamoDB.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-java-using.md#logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-java-using.md#ddb-config-encrypt).
Para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifrado con capacidad de búsqueda](searchable-encryption.md), también debe incluirlos [`SearchConfig`](ddb-java-using.md#ddb-search-config)en la configuración de cifrado.
```
final Map tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
DynamoDbEnhancedTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.schemaOnEncrypt(tableSchema)
.build());
```
**Paso 5: Cree la `DynamoDbEncryptionInterceptor`**
En el siguiente ejemplo, se crea un nuevo `DynamoDbEncryptionInterceptor` con la `tableConfigs` del **Paso 4**.
```
final DynamoDbEncryptionInterceptor interceptor =
DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
CreateDynamoDbEncryptionInterceptorInput.builder()
.tableEncryptionConfigs(tableConfigs)
.build()
);
```
**Paso 6: Crear un nuevo cliente AWS SDK de DynamoDB**
**En el siguiente ejemplo, se crea un nuevo cliente AWS SDK de DynamoDB mediante `interceptor` el paso 5.**
```
final DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(interceptor)
.build())
.build();
```
**Paso 7: Crear el cliente mejorado de DynamoDB y crear una tabla**
En el siguiente ejemplo, se crea el cliente mejorado DynamoDB mediante el cliente del SDK DynamoDB de AWS creado en el **Paso 6** y se crea una tabla con la clase de datos anotados.
```
final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema);
```
**Paso 8: Cifrar y guardar un elemento de la tabla**
En el siguiente ejemplo, se coloca un elemento en la tabla de DynamoDB mediante el cliente mejorado de DynamoDB. El elemento se cifra y se firma en el lado del cliente antes de enviarlo a DynamoDB.
```
final SimpleClass item = new SimpleClass();
item.setPartitionKey("EnhancedPutGetExample");
item.setSortKey(0);
item.setAttribute1("encrypt and sign me!");
item.setAttribute2("sign me!");
item.setAttribute3("ignore me!");
table.putItem(item);
```
## API de bajo nivel de DynamoDB
En el siguiente ejemplo, se muestra cómo utilizar la API de DynamoDB de bajo nivel con un [conjunto de claves de AWS KMS](use-kms-keyring.md) para cifrar y firmar automáticamente los elementos del lado del cliente con las solicitudes de DynamoDB de `PutItem`.
Puede utilizar cualquier [llavero](keyrings.md) compatible, pero le recomendamos que utilice uno de los AWS KMS llaveros siempre que sea posible.
**[Consulta el ejemplo de código completo: .java BasicPutGetExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/BasicPutGetExample.java)**
**Paso 1: Crea el llavero AWS KMS **
El siguiente ejemplo se utiliza `CreateAwsKmsMrkMultiKeyring` para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**Paso 2: configurar las acciones de sus atributos**
En el siguiente ejemplo, se define un mapa `attributeActionsOnEncrypt` que representa ejemplos de [acciones de atributos](concepts.md#crypt-actions) para un elemento de la tabla.
En el siguiente ejemplo no se define ningún atributo como. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
final Map attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY);
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);
```
**Paso 3: defina qué atributos se excluyen de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asume que cualquier nombre de atributo con el prefijo “`:`” está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).
```
final String unsignedAttrPrefix = ":";
```
**Paso 4: definir la configuración de cifrado de la tabla de DynamoDB**
El siguiente ejemplo define un mapa `tableConfigs` que representa la configuración de cifrado de esta tabla de DynamoDB.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-java-using.md#logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-java-using.md#ddb-config-encrypt).
Para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifrado con capacidad de búsqueda](searchable-encryption.md), también debe incluir [`SearchConfig`](ddb-java-using.md#ddb-search-config) en la configuración de cifrado.
```
final Map tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.partitionKeyName("partition_key")
.sortKeyName("sort_key")
.attributeActionsOnEncrypt(attributeActionsOnEncrypt)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.build();
tableConfigs.put(ddbTableName, config);
```
**Paso 5: Crear el `DynamoDbEncryptionInterceptor`**
En el siguiente ejemplo, se crea el `DynamoDbEncryptionInterceptor` con la `tableConfigs` del **Paso 4**.
```
DynamoDbEncryptionInterceptor interceptor = DynamoDbEncryptionInterceptor.builder()
.config(DynamoDbTablesEncryptionConfig.builder()
.tableEncryptionConfigs(tableConfigs)
.build())
.build();
```
**Paso 6: Crear un nuevo cliente AWS SDK de DynamoDB**
**En el siguiente ejemplo, se crea un nuevo cliente AWS SDK de DynamoDB mediante `interceptor` el paso 5.**
```
final DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(interceptor)
.build())
.build();
```
**Paso 7: Cifrar y firmar un elemento de la tabla de DynamoDB**
En el siguiente ejemplo, se define un mapa `item` que representa un elemento de tabla de ejemplo y se coloca el elemento en la tabla de DynamoDB. El elemento se cifra y se firma en el lado del cliente antes de enviarlo a DynamoDB.
```
final HashMap item = new HashMap<>();
item.put("partition_key", AttributeValue.builder().s("BasicPutGetExample").build());
item.put("sort_key", AttributeValue.builder().n("0").build());
item.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
item.put("attribute2", AttributeValue.builder().s("sign me!").build());
item.put(":attribute3", AttributeValue.builder().s("ignore me!").build());
final PutItemRequest putRequest = PutItemRequest.builder()
.tableName(ddbTableName)
.item(item)
.build();
final PutItemResponse putResponse = ddb.putItem(putRequest);
```
## Usando el nivel inferior DynamoDbItemEncryptor
En el siguiente ejemplo, se muestra cómo utilizar el nivel inferior `DynamoDbItemEncryptor` con un [conjunto de claves de AWS KMS](use-kms-keyring.md) para cifrar y firmar directamente los elementos de la tabla. `DynamoDbItemEncryptor` No coloca el elemento en la tabla de DynamoDB.
Puede utilizar cualquier conjunto de [claves compatible con el cliente mejorado de DynamoDB, pero le recomendamos que utilice uno de los anillos](keyrings.md) de AWS KMS claves siempre que sea posible.
**nota**
El nivel inferior `DynamoDbItemEncryptor` no admite el cifrado [con capacidad de búsqueda.](searchable-encryption.md) Úselo `DynamoDbEncryptionInterceptor` con el API de bajo nivel de DynamoDB para usar el cifrado con capacidad de búsqueda.
**Consulte el ejemplo de código completo**[: .java ItemEncryptDecryptExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/itemencryptor/ItemEncryptDecryptExample.java)
**Paso 1: Crea el llavero AWS KMS **
El siguiente ejemplo se utiliza `CreateAwsKmsMrkMultiKeyring` para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**Paso 2: configurar las acciones de sus atributos**
En el siguiente ejemplo, se define un mapa `attributeActionsOnEncrypt` que representa ejemplos de [acciones de atributos](concepts.md#crypt-actions) para un elemento de la tabla.
En el siguiente ejemplo no se define ningún atributo como. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
final Map attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY);
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);
```
**Paso 3: defina qué atributos se excluyen de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asume que cualquier nombre de atributo con el prefijo “`:`” está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).
```
final String unsignedAttrPrefix = ":";
```
**Paso 4: defina la configuración de `DynamoDbItemEncryptor`**
En el siguiente ejemplo, se consulta la configuración de `DynamoDbItemEncryptor`.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-java-using.md#logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-java-using.md#ddb-config-encrypt).
```
final DynamoDbItemEncryptorConfig config = DynamoDbItemEncryptorConfig.builder()
.logicalTableName(ddbTableName)
.partitionKeyName("partition_key")
.sortKeyName("sort_key")
.attributeActionsOnEncrypt(attributeActionsOnEncrypt)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.build();
```
**Paso 5: Crear el `DynamoDbItemEncryptor`**
En el siguiente ejemplo, se crea un nuevo `DynamoDbItemEncryptor`, con la `config` del **Paso 4**.
```
final DynamoDbItemEncryptor itemEncryptor = DynamoDbItemEncryptor.builder()
.DynamoDbItemEncryptorConfig(config)
.build();
```
**Paso 6: cifrar y firmar directamente un elemento de la tabla**
En el siguiente ejemplo, se cifra y firma directamente un elemento mediante el `DynamoDbItemEncryptor`. `DynamoDbItemEncryptor` no coloca el elemento en la tabla de DynamoDB.
```
final Map originalItem = new HashMap<>();
originalItem.put("partition_key", AttributeValue.builder().s("ItemEncryptDecryptExample").build());
originalItem.put("sort_key", AttributeValue.builder().n("0").build());
originalItem.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
originalItem.put("attribute2", AttributeValue.builder().s("sign me!").build());
originalItem.put(":attribute3", AttributeValue.builder().s("ignore me!").build());
final Map encryptedItem = itemEncryptor.EncryptItem(
EncryptItemInput.builder()
.plaintextItem(originalItem)
.build()
).encryptedItem();
```
# Configurar una tabla de DynamoDB existente para usar AWS el SDK de cifrado de bases de datos para DynamoDB
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de bases de datos. AWS En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
Con la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB, puede configurar las tablas de Amazon DynamoDB existentes para el cifrado del cliente. En este tema se proporcionan instrucciones sobre los tres pasos que debe seguir para añadir la versión 3.*x* a una tabla de DynamoDB existente y rellenada.
**Requisitos previos**
Versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB requiere el cliente mejorado de [DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) incluido en AWS SDK for Java 2.x . Si aún usa [Dynamo DBMapper](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html), debe migrar AWS SDK for Java 2.x para usar DynamoDB Enhanced Client.
Siga las instrucciones para [migrar de la versión 1.x a la 2.x de AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html).
A continuación, siga las instrucciones para [empezar a utilizar la API de cliente mejorada de DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started.html).
[Antes de configurar la tabla para que utilice la biblioteca de cifrado del cliente de Java para DynamoDB, debe generar una `TableSchema`[mediante una clase de datos anotada y crear un](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) cliente mejorado.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient)
## Paso 1: prepararse para leer y escribir elementos cifrados
Complete los siguientes pasos para preparar su cliente del SDK de cifrado AWS de bases de datos para leer y escribir elementos cifrados. Tras implementar los siguientes cambios, el cliente seguirá leyendo y escribiendo elementos de texto no cifrado. No cifrará ni firmará ningún elemento nuevo escrito en la tabla, pero podrá descifrar los elementos cifrados en cuanto aparezcan. Estos cambios preparan al cliente para empezar a [cifrar nuevos elementos.](#ddb-java-add-step2) Los siguientes cambios deben implementarse en cada lector antes de continuar con el siguiente paso.
**1. Defina las [acciones de sus atributos](concepts.md#crypt-actions)**
Actualice la clase de datos anotada para incluir acciones de atributos que definan qué valores de atributo se cifrarán y firmarán, cuáles solo se firmarán y cuáles se ignorarán.
Consulte el [SimpleClassarchivo.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) en el repositorio aws-database-encryption-sdk -dynamodb GitHub para obtener más información sobre las anotaciones del cliente mejorado de DynamoDB.
De forma predeterminada, los atributos de la clave principal están firmados pero no cifrados (`SIGN_ONLY`) y todos los demás atributos están cifrados y firmados `ENCRYPT_AND_SIGN`(). Para especificar las excepciones, utiliza las anotaciones de cifrado que se definen en la biblioteca de cifrado del cliente de Java para DynamoDB. Por ejemplo, si desea que un atributo concreto sea de solo firmar, utilice únicamente la anotación `@DynamoDbEncryptionSignOnly`. Si desea que un atributo concreto se firme e incluya en el contexto de cifrado, utilice la anotación. `@DynamoDbEncryptionSignAndIncludeInEncryptionContext` Si desea que un atributo concreto no esté firmado ni cifrado (`DO_NOTHING`), utilice la anotación `@DynamoDbEncryptionDoNothing`.
Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Para ver un ejemplo que muestre las anotaciones utilizadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte [SimpleClass4.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java).
Para ver anotaciones de ejemplo, consulte [Utilice una clase de datos anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).
**2. Defina qué atributos se excluirán de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asumirá que cualquier nombre de atributo con el prefijo "`:`" está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).
```
final String unsignedAttrPrefix = ":";
```
**3. Cree un [conjunto de claves](keyrings.md)**
El siguiente ejemplo crea un [conjunto de claves de AWS KMS](use-kms-keyring.md). El AWS KMS anillo de claves utiliza un cifrado simétrico o un RSA asimétrico AWS KMS keys para generar, cifrar y descifrar las claves de datos.
En este ejemplo, se utiliza `CreateMrkMultiKeyring` para crear un conjunto de claves de AWS KMS con una clave de KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**4. Definir la configuración de cifrado de la tabla de DynamoDB **
El siguiente ejemplo define un mapa `tableConfigs` que representa la configuración de cifrado de esta tabla de DynamoDB.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-java-using.md#logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-java-using.md#ddb-config-encrypt).
Debe especificarlo `FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT` como modificación de texto no cifrado. Esta política sigue leyendo y escribiendo elementos de texto no cifrado, lee los elementos cifrados y prepara al cliente para escribir elementos cifrados.
```
final Map tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.partitionKeyName("partition_key")
.sortKeyName("sort_key")
.schemaOnEncrypt(tableSchema)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.plaintextOverride(PlaintextOverride.FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT)
.build();
tableConfigs.put(ddbTableName, config);
```
**5. Crear el `DynamoDbEncryptionInterceptor`**
En el siguiente ejemplo, se crea el `DynamoDbEncryptionInterceptor` con la misma `tableConfigs` del **Paso 3**.
```
DynamoDbEncryptionInterceptor interceptor = DynamoDbEncryptionInterceptor.builder()
.config(DynamoDbTablesEncryptionConfig.builder()
.tableEncryptionConfigs(tableConfigs)
.build())
.build();
```
## Paso 2: escribir elementos cifrados y firmados
Actualice la política de texto no cifrado de su `DynamoDbEncryptionInterceptor` configuración para permitir que el cliente escriba elementos cifrados y firmados. Tras implementar el siguiente cambio, el cliente cifrará y firmará los nuevos elementos en función de las acciones de atributos que configuró en el **paso** 1. El cliente podrá leer los elementos en texto no cifrado y los elementos cifrados y firmados.
Antes de continuar con el [Paso 3](#ddb-java-add-step3), debe cifrar y firmar todos los elementos de texto no cifrado existentes en la tabla. No existe una métrica o consulta única que pueda ejecutar para cifrar rápidamente los elementos de texto no cifrado existentes. Utilice el proceso que mejor se adapte a su sistema. Por ejemplo, puede utilizar un proceso asíncrono que escanee lentamente la tabla y reescriba los elementos mediante las acciones de los atributos y la configuración de cifrado que haya definido. Para identificar los elementos de texto sin formato de la tabla, se recomienda buscar todos los elementos que no contengan los `aws_dbe_foot` atributos que el SDK de cifrado de AWS bases de datos agrega a los elementos cuando están cifrados `aws_dbe_head` y firmados.
En el siguiente ejemplo, se actualiza la configuración de cifrado de la tabla desde el **paso 1**. Debe actualizar la anulación de texto no cifrado con `FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`. Esta política sigue leyendo los elementos de texto no cifrado, pero también lee y escribe los elementos cifrados. Cree una nueva `DynamoDbEncryptionInterceptor` con la actualización`tableConfigs`.
```
final Map tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.partitionKeyName("partition_key")
.sortKeyName("sort_key")
.schemaOnEncrypt(tableSchema)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
.plaintextOverride(PlaintextOverride.FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT)
.build();
tableConfigs.put(ddbTableName, config);
```
## Paso 3: Lee solo los elementos cifrados y firmados
Una vez cifrados y firmados todos los elementos, actualice la modificación del texto no cifrado de la `DynamoDbEncryptionInterceptor` configuración para que el cliente solo pueda leer y escribir los elementos cifrados y firmados. Tras implementar el siguiente cambio, el cliente cifrará y firmará los nuevos elementos en función de las acciones de atributos que configuró en el **paso 1**. El cliente solo podrá leer los elementos cifrados y firmados.
El siguiente ejemplo actualiza la configuración de cifrado de la tabla desde el **paso 2**. Puede actualizar la anulación de texto no cifrado con `FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT` o eliminar la política de texto no cifrado de su configuración. De forma predeterminada, el cliente solo lee y escribe los elementos cifrados y firmados. Cree una nueva `DynamoDbEncryptionInterceptor` con la actualización`tableConfigs`.
```
final Map tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.partitionKeyName("partition_key")
.sortKeyName("sort_key")
.schemaOnEncrypt(tableSchema)
.keyring(kmsKeyring)
.allowedUnsignedAttributePrefix(unsignedAttrPrefix)
// Optional: you can also remove the plaintext policy from your configuration
.plaintextOverride(PlaintextOverride.FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT)
.build();
tableConfigs.put(ddbTableName, config);
```
# Migre a la versión 3.x de la biblioteca de cifrado del cliente de Java para DynamoDB
****
| |
| --- |
| 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). |
Versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB es una importante reescritura de la base de código 2.*x*. Incluye numerosas actualizaciones, como un nuevo formato de datos estructurados, una compatibilidad mejorada de multitenencia, cambios de esquema fluidos y compatibilidad con el cifrado para búsquedas. En este tema se proporciona orientación sobre cómo migrar el código a la versión 3.*x*.
## Migración de la versión 1.x a la versión 2.x
Migre a la versión 2.*x* antes de migrar a la versión 3.*x*. Versión 2. *x* cambió el símbolo del proveedor más reciente de `MostRecentProvider` a`CachingMostRecentProvider`. Si actualmente usa la versión 1. *x* de la biblioteca de cifrado del cliente de Java para DynamoDB con el `MostRecentProvider` símbolo, debe actualizar el nombre del símbolo en el código a. `CachingMostRecentProvider` Para obtener más información, consulte [Actualizaciones del proveedor más reciente](most-recent-provider.md#mrp-versions).
## Migración de la versión 2.x a la versión 3.x
En los siguientes procedimientos se describe cómo migrar el código desde la versión 2.*x* a la versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB.
### Paso 1. Prepárese para leer los elementos en el nuevo formato
Complete los siguientes pasos para preparar su cliente del SDK AWS de cifrado de bases de datos para leer los elementos en el nuevo formato. Tras implementar los siguientes cambios, el cliente seguirá comportándose del mismo modo que en la versión 2. *x*. Su cliente seguirá leyendo y escribiendo los elementos de la versión 2. formato *x*, pero estos cambios preparan al cliente para [leer los elementos en el nuevo formato](#ddb-java-migrate-step2).
**Actualice su versión AWS SDK para Java a la 2.x**
Versión 3.*x* de la biblioteca de cifrado del cliente de Java para DynamoDB requiere el [cliente mejorado de DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html). El cliente mejorado de DynamoDB reemplaza al DBMapper Dynamo utilizado [en](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html) versiones anteriores. Para usar el cliente mejorado, debe usar el. AWS SDK for Java 2.x
Siga las instrucciones para [migrar de la versión 1.x a la 2.x de AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html).
Para obtener más información sobre los AWS SDK for Java 2.x módulos necesarios, consulte. [Requisitos previos](ddb-java.md#ddb-java-prerequisites)
**Configure su cliente para que lea los elementos cifrados por las versiones antiguas**
Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.
1. Cree un [conjunto de claves](keyrings.md).
Los [administradores de conjunto de claves y materiales criptográficos](concepts.md#crypt-materials-manager) sustituyen a los proveedores de materiales criptográficos utilizados en las versiones anteriores de la biblioteca de cifrado del cliente de Java para DynamoDB.
**importante**
Las claves de encapsulación que especifique al crear un conjunto de claves deben ser las mismas claves de encapsulación que utilizó con su proveedor de materiales criptográficos en la versión 2. *x*.
1. Crea un esquema de tabla sobre tu clase anotada.
En este paso se definen las acciones de atributos que se utilizarán cuando comience a escribir elementos en el nuevo formato.
Para obtener instrucciones sobre el uso del nuevo cliente mejorado de DynamoDB, consulte [Generar un `TableSchema`](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html) en la * Guía para desarrolladores de AWS SDK para Java *.
En el siguiente ejemplo, se supone que actualizó la clase anotada a partir de la versión 2.*x* utilizando las nuevas anotaciones de acciones de atributos. Para obtener más información sobre cómo anotar las acciones de los atributos, consulte [Utilice una clase de datos anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).
**nota**
Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Para ver un ejemplo que muestre las anotaciones utilizadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte [SimpleClass4.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java).
1. Defina qué [atributos se excluyen de la firma](ddb-java-using.md#allowed-unauth).
1. Configure un mapa explícito de las acciones de los atributos configuradas en su clase modelada de la versión 2.x.
En este paso, se definen las acciones de atributo utilizadas para escribir los elementos en el formato anterior.
1. Configure el `DynamoDBEncryptor` que utilizó en la versión 2. *x* de la biblioteca de cifrado del cliente de Java para DynamoDB.
1. Configure el comportamiento heredado.
1. Crear una `DynamoDbEncryptionInterceptor`.
1. Cree un nuevo cliente AWS SDK de DynamoDB.
1. Cree el `DynamoDBEnhancedClient` y cree una tabla con su clase modelada.
Para obtener más información sobre el cliente mejorado de DynamoDB, [consulte crear un](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient) cliente mejorado.
```
public class MigrationExampleStep1 {
public static void MigrationStep1(String kmsKeyId, String ddbTableName, int sortReadValue) {
// 1. Create a Keyring.
// This example creates an AWS KMS Keyring that specifies the
// same kmsKeyId previously used in the version 2.x configuration.
// It uses the 'CreateMrkMultiKeyring' method to create the
// keyring, so that the keyring can correctly handle both single
// region and Multi-Region KMS Keys.
// Note that this example uses the AWS SDK for Java v2 KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
// 2. Create a Table Schema over your annotated class.
// For guidance on using the new attribute actions
// annotations, see SimpleClass.java in the
// aws-database-encryption-sdk-dynamodb GitHub repository.
// All primary key attributes must be signed but not encrypted
// and by default all non-primary key attributes
// are encrypted and signed (ENCRYPT_AND_SIGN).
// If you want a particular non-primary key attribute to be signed but
// not encrypted, use the 'DynamoDbEncryptionSignOnly' annotation.
// If you want a particular attribute to be neither signed nor encrypted
// (DO_NOTHING), use the 'DynamoDbEncryptionDoNothing' annotation.
final TableSchema schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);
// 3. Define which attributes the client should expect to be excluded
// from the signature when reading items.
// This value represents all unsigned attributes across the entire
// dataset.
final List allowedUnsignedAttributes = Arrays.asList("attribute3");
// 4. Configure an explicit map of the attribute actions configured
// in your version 2.x modeled class.
final Map legacyActions = new HashMap<>();
legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
legacyActions.put("attribute3", CryptoAction.DO_NOTHING);
// 5. Configure the DynamoDBEncryptor that you used in version 2.x.
final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);
// 6. Configure the legacy behavior.
// Input the DynamoDBEncryptor and attribute actions created in
// the previous steps. For Legacy Policy, use
// 'FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy continues to read
// and write items using the old format, but will be able to read
// items written in the new format as soon as they appear.
final LegacyOverride legacyOverride = LegacyOverride
.builder()
.encryptor(oldEncryptor)
.policy(LegacyPolicy.FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
.attributeActionsOnEncrypt(legacyActions)
.build();
// 7. Create a DynamoDbEncryptionInterceptor with the above configuration.
final Map tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
DynamoDbEnhancedTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.keyring(kmsKeyring)
.allowedUnsignedAttributes(allowedUnsignedAttributes)
.schemaOnEncrypt(tableSchema)
.legacyOverride(legacyOverride)
.build());
final DynamoDbEncryptionInterceptor interceptor =
DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
CreateDynamoDbEncryptionInterceptorInput.builder()
.tableEncryptionConfigs(tableConfigs)
.build()
);
// 8. Create a new AWS SDK DynamoDb client using the
// interceptor from Step 7.
final DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(interceptor)
.build())
.build();
// 9. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb client
// created in Step 8, and create a table with your modeled class.
final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema);
}
}
```
### Paso 2. Escriba los elementos en el nuevo formato
Una vez implementados los cambios del paso 1 en todos los lectores, complete los siguientes pasos para configurar su cliente del SDK de cifrado de AWS bases de datos para escribir elementos en el nuevo formato. Tras implementar los siguientes cambios, el cliente seguirá leyendo los elementos en el formato anterior y empezará a escribir y leer los elementos en el nuevo formato.
Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.
1. Siga configurando el conjunto de claves, el esquema de la tabla, las acciones de los atributos heredados, `allowedUnsignedAttributes` y `DynamoDBEncryptor` tal y como hizo en el [**Paso 1**](#ddb-java-migrate-step1).
1. Actualice su comportamiento anterior para escribir solo elementos nuevos con el nuevo formato.
1. Crear una `DynamoDbEncryptionInterceptor `
1. Cree un nuevo cliente AWS SDK de DynamoDB.
1. Cree el `DynamoDBEnhancedClient` y cree una tabla con su clase modelada.
Para obtener más información sobre el cliente mejorado de DynamoDB, consulte [Create an enhanced client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).
```
public class MigrationExampleStep2 {
public static void MigrationStep2(String kmsKeyId, String ddbTableName, int sortReadValue) {
// 1. Continue to configure your keyring, table schema, legacy
// attribute actions, allowedUnsignedAttributes, and
// DynamoDBEncryptor as you did in Step 1.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
final TableSchema schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);
final List allowedUnsignedAttributes = Arrays.asList("attribute3");
final Map legacyActions = new HashMap<>();
legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
legacyActions.put("attribute3", CryptoAction.DO_NOTHING);
final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);
// 2. Update your legacy behavior to only write new items using the new
// format.
// For Legacy Policy, use 'FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy
// continues to read items in both formats, but will only write items
// using the new format.
final LegacyOverride legacyOverride = LegacyOverride
.builder()
.encryptor(oldEncryptor)
.policy(LegacyPolicy.FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
.attributeActionsOnEncrypt(legacyActions)
.build();
// 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
final Map tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
DynamoDbEnhancedTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.keyring(kmsKeyring)
.allowedUnsignedAttributes(allowedUnsignedAttributes)
.schemaOnEncrypt(tableSchema)
.legacyOverride(legacyOverride)
.build());
final DynamoDbEncryptionInterceptor interceptor =
DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
CreateDynamoDbEncryptionInterceptorInput.builder()
.tableEncryptionConfigs(tableConfigs)
.build()
);
// 4. Create a new AWS SDK DynamoDb client using the
// interceptor from Step 3.
final DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(interceptor)
.build())
.build();
// 5. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb Client created
// in Step 4, and create a table with your modeled class.
final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema);
}
}
```
Tras implementar los cambios del paso 2, debe volver a cifrar todos los elementos antiguos de la tabla con el nuevo formato para poder continuar con el [Paso 3](#ddb-java-migrate-step3). No hay una única métrica o consulta que puedas ejecutar para cifrar rápidamente los elementos existentes. Utilice el proceso que mejor se adapte a su sistema. Por ejemplo, podría utilizar un proceso asíncrono que escanee lentamente la tabla y reescriba los elementos utilizando las nuevas acciones de atributo y la nueva configuración de cifrado que haya definido.
### Paso 3. Lea y escriba únicamente los elementos en el nuevo formato
Tras volver a cifrar todos los elementos de la tabla con el nuevo formato, puede eliminar el comportamiento anterior de la configuración. Siga los pasos que se indican a continuación para configurar el cliente para que solo lea y escriba los elementos en el nuevo formato.
Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.
1. Continúe configurando el conjunto de claves, el esquema de la tabla y `allowedUnsignedAttributes` tal como lo hizo en el [**Paso 1**](#ddb-java-migrate-step1). Elimine las acciones y acciones de los atributos heredados `DynamoDBEncryptor` de su configuración.
1. Creación de una `DynamoDbEncryptionInterceptor`.
1. Cree un nuevo cliente AWS SDK de DynamoDB.
1. Cree el `DynamoDBEnhancedClient` y cree una tabla con su clase modelada.
Para obtener más información sobre el cliente mejorado de DynamoDB, consulte [Create an enhanced client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).
```
public class MigrationExampleStep3 {
public static void MigrationStep3(String kmsKeyId, String ddbTableName, int sortReadValue) {
// 1. Continue to configure your keyring, table schema,
// and allowedUnsignedAttributes as you did in Step 1.
// Do not include the configurations for the DynamoDBEncryptor or
// the legacy attribute actions.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyId)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
final TableSchema schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);
final List allowedUnsignedAttributes = Arrays.asList("attribute3");
// 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
// Do not configure any legacy behavior.
final Map tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
DynamoDbEnhancedTableEncryptionConfig.builder()
.logicalTableName(ddbTableName)
.keyring(kmsKeyring)
.allowedUnsignedAttributes(allowedUnsignedAttributes)
.schemaOnEncrypt(tableSchema)
.build());
final DynamoDbEncryptionInterceptor interceptor =
DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
CreateDynamoDbEncryptionInterceptorInput.builder()
.tableEncryptionConfigs(tableConfigs)
.build()
);
// 4. Create a new AWS SDK DynamoDb client using the
// interceptor from Step 3.
final DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(
ClientOverrideConfiguration.builder()
.addExecutionInterceptor(interceptor)
.build())
.build();
// 5. Create the DynamoDbEnhancedClient using the AWS SDK Client
// created in Step 4, and create a table with your modeled class.
final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema);
}
}
```
# .NET
En este tema se explica cómo instalar y usar la versión 3. *x* de la biblioteca de cifrado del lado del cliente.NET para DynamoDB. Para obtener más información sobre la programación con el SDK AWS de cifrado de bases de datos para DynamoDB, consulte los ejemplos [de.NET en el repositorio -dynamodb](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/) en aws-database-encryption-sdk. GitHub
La biblioteca de cifrado del lado del cliente.NET para DynamoDB es para desarrolladores que escriben aplicaciones en C\$1 y otros lenguajes de programación.NET. Es compatible con Windows, macOS y Linux.
Todas las implementaciones de [lenguajes de programación](ddb-programming-languages.md) del SDK de cifrado de AWS bases de datos para DynamoDB son interoperables. Sin embargo, no SDK para .NET admite valores vacíos para los tipos de datos de listas o mapas. Esto significa que si utiliza la biblioteca de cifrado del lado del cliente de Java para DynamoDB para escribir un elemento que contenga valores vacíos para un tipo de datos de lista o mapa, no podrá descifrar ni leer ese elemento mediante la biblioteca de cifrado del lado del cliente .NET para DynamoDB.
**Topics**
+ [Instalación](#ddb-net-install)
+ [Debugging](#ddb-net-debugging)
+ [Uso del cliente.NET](ddb-net-using.md)
+ [Ejemplos de.NET](ddb-net-examples.md)
+ [Agregar la versión 3.x a una tabla existente](ddb-net-config-existing-table.md)
## Instalación de la biblioteca de cifrado del lado del cliente.NET para DynamoDB
[La biblioteca de cifrado del lado del cliente .NET para DynamoDB está disponible como AWS.Cryptography. DbEncryptionSDK. DynamoDb](https://www.nuget.org/packages/AWS.Cryptography.DbEncryptionSDK.DynamoDb/)paquete en NuGet. Para obtener más información sobre la instalación y creación de la biblioteca, consulte el [archivo.NET README.md](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/runtimes/net/README.md) en el aws-database-encryption-sdk repositorio -dynamodb. La biblioteca de cifrado del lado del cliente.NET para DynamoDB requiere las claves « SDK para .NET incluso si no se utilizan» (). AWS Key Management Service AWS KMS SDK para .NET Se instala con el paquete. NuGet
Versión 3. *x* de la biblioteca de cifrado del lado del cliente .NET para DynamoDB es compatible con .NET 6.0 y .NET Framework net48 y versiones posteriores.
## Depuración con .NET
La biblioteca de cifrado del lado del cliente.NET para DynamoDB no genera ningún registro. Las excepciones de la biblioteca de cifrado del lado del cliente de.NET para DynamoDB generan un mensaje de excepción, pero no se rastrean las pilas.
Para ayudarle a depurar, asegúrese de activar el inicio de sesión en la SDK para .NET. Los registros y los mensajes de error de SDK para .NET pueden ayudarle a distinguir los errores que se producen en la biblioteca SDK para .NET de cifrado del lado del cliente de.NET para DynamoDB. *Para obtener ayuda con el SDK para .NET registro, consulte la Guía para desarrolladores [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-other.html#config-setting-awslogging).AWS SDK para .NET * (Para ver el tema, amplíe la sección **Abrir para ver la sección de contenido de .NET Framework**).
# Uso de la biblioteca de cifrado del lado del cliente.NET para DynamoDB
En este tema se explican algunas de las funciones y clases auxiliares de la versión 3. *x* de la biblioteca de cifrado del lado del cliente.NET para DynamoDB.
Para obtener más información sobre la programación con la biblioteca de cifrado del lado del cliente .NET para DynamoDB, consulte los [ejemplos de.NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/) en el repositorio -dynamodb de. aws-database-encryption-sdk GitHub
**Topics**
+ [Encriptadores de elementos](#ddb-net-item-encryptors)
+ [Acciones de atributo](#ddb-net-attribute-actions)
+ [La configuración de cifrado](#ddb-net-config-encrypt)
+ [Actualización de un elemento](#ddb-net-update-items)
## Encriptadores de elementos
En esencia, el SDK de cifrado AWS de bases de datos para DynamoDB es un cifrador de elementos. Puede utilizar la versión 3. *x* de la biblioteca de cifrado del lado del cliente .NET para que DynamoDB cifre, firme, verifique y descifre los elementos de la tabla de DynamoDB de las siguientes maneras.
**El SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB**
Puede usar la [configuración de cifrado de tablas](#ddb-net-config-encrypt) para crear un cliente de DynamoDB que cifre y firme automáticamente los elementos del lado del cliente con sus solicitudes de DynamoDB. `PutItem` [https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-document](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-document)
[Debe usar el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB para utilizar el cifrado con capacidad de búsqueda.](searchable-encryption.md)
**El nivel inferior `DynamoDbItemEncryptor`**
El nivel inferior cifra y firma o descifra y verifica `DynamoDbItemEncryptor` directamente los elementos de la tabla sin llamar a DynamoDB. No realiza DynamoDB ni `PutItem` solicitudes`GetItem`. Por ejemplo, puede usar el nivel inferior `DynamoDbItemEncryptor` para descifrar y verificar directamente un elemento de DynamoDB que ya haya recuperado. Si utiliza el nivel inferior`DynamoDbItemEncryptor`, le recomendamos que utilice el [modelo de programación de bajo nivel](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-low-level) que SDK para .NET proporciona para la comunicación con DynamoDB.
El nivel inferior `DynamoDbItemEncryptor` no admite el cifrado [con capacidad de búsqueda.](searchable-encryption.md)
## Acciones de atributos en el SDK de cifrado AWS de bases de datos para DynamoDB
[Las acciones de atributos](concepts.md#crypt-actions) determinan qué valores de atributo están cifrados y firmados, cuáles solo están firmados, cuáles están firmados e incluidos en el contexto de cifrado y cuáles se ignoran.
Para especificar las acciones de los atributos con el cliente .NET, defina manualmente las acciones de los atributos mediante un modelo de objetos. Especifique las acciones de los atributos creando un `Dictionary` objeto en el que los pares nombre-valor representen los nombres de los atributos y las acciones especificadas.
Especifique `ENCRYPT_AND_SIGN` si desea cifrar y firmar un atributo. Especifique `SIGN_ONLY` firmar, pero no cifrar, un atributo. Especifique si `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` desea firmar un atributo e incluirlo en el contexto de cifrado. No se puede cifrar un atributo sin firmarlo también. Especifique `DO_NOTHING` que se omita un atributo.
Los atributos de partición y ordenación deben ser uno de `SIGN_ONLY` los dos`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Si define algún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**nota**
Tras definir las acciones de los atributos, debe definir qué atributos se excluyen de las firmas. Para facilitar la adición de nuevos atributos sin firmar en el futuro, recomendamos elegir un prefijo distinto (como “`:`“) para identificar los atributos sin firmar. Incluya este prefijo en el nombre del atributo para todos los atributos marcados `DO_NOTHING` al definir el esquema y las acciones de atributos de DynamoDB.
El siguiente modelo de objetos muestra cómo especificar `ENCRYPT_AND_SIGN` `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, y `DO_NOTHING` atribuir acciones con el cliente.NET. En este ejemplo se utiliza el prefijo `:` "» para identificar `DO_NOTHING` los atributos.
**nota**
Para utilizar la acción `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, debe utilizar la versión 3.3 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de [actualizar su modelo de datos](ddb-update-data-model.md) para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` incluirla.
```
var attributeActionsOnEncrypt = new Dictionary
{
["partition_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The partition attribute must be signed
["sort_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The sort attribute must be signed
["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
["attribute2"] = CryptoAction.SIGN_ONLY,
["attribute3"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT,
[":attribute4"] = CryptoAction.DO_NOTHING
};
```
## Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB
Al utilizar el SDK de cifrado AWS de bases de datos, debe definir explícitamente una configuración de cifrado para la tabla de DynamoDB. Los valores necesarios en la configuración de cifrado dependen de si ha definido las acciones de los atributos manualmente o con una clase de datos anotada.
El siguiente fragmento define una configuración de cifrado de tablas de DynamoDB mediante el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB y los atributos no firmados permitidos definidos por un prefijo distinto.
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
// Optional: SearchConfig only required if you use beacons
Search = new SearchConfig
{
WriteVersion = 1, // MUST be 1
Versions = beaconVersions
}
};
tableConfigs.Add(ddbTableName, config);
```
**Nombre de la tabla lógica**
Un nombre de tabla lógico para la tabla de DynamoDB.
El nombre de la tabla lógica está enlazado criptográficamente a todos los datos almacenados en la tabla para simplificar las operaciones de restauración de DynamoDB. Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Debe especificar siempre el mismo nombre de tabla lógica. Para que el descifrado se realice correctamente, el nombre de la tabla lógica debe coincidir con el nombre especificado en el cifrado. En caso de que el nombre de la tabla de DynamoDB cambie después de [restaurar la tabla de DynamoDB a partir de una copia de seguridad, el nombre de la tabla](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html) lógica garantiza que la operación de descifrado siga reconociendo la tabla.
**Atributos no firmados permitidos**
Los atributos marcados `DO_NOTHING` en tus acciones de atributos.
Los atributos no firmados permitidos indican al cliente qué atributos están excluidos de las firmas. El cliente asume que todos los demás atributos están incluidos en la firma. A continuación, al descifrar un registro, el cliente determina qué atributos debe verificar y cuáles debe ignorar de los atributos no firmados permitidos que especificó. No puede eliminar un atributo de los atributos no firmados permitidos.
Puede definir los atributos no firmados permitidos de forma explícita mediante la creación de una matriz que enumere todos sus `DO_NOTHING` atributos. También puedes especificar un prefijo distinto al asignar un nombre a tus `DO_NOTHING` atributos y usar el prefijo para indicar al cliente qué atributos no están firmados. Recomendamos encarecidamente especificar un prefijo distinto porque simplifica el proceso de añadir un nuevo `DO_NOTHING` atributo en el futuro. Para obtener más información, consulte [Actualización de su modelo de datos](ddb-update-data-model.md).
Si no especifica un prefijo para todos los `DO_NOTHING` atributos, puede configurar una `allowedUnsignedAttributes` matriz que enumere de forma explícita todos los atributos que el cliente debería esperar que no estén firmados cuando los encuentre al descifrarlos. Solo debe definir de forma explícita los atributos no firmados permitidos si es absolutamente necesario.
**Configuración de búsqueda (opcional)**
`SearchConfig`Define la [versión de baliza](using-beacons.md#beacon-version).
`SearchConfig`Debe especificarse para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifradas con capacidad de búsqueda](searchable-encryption.md).
**Conjunto de algoritmos (opcional)**
El `algorithmSuiteId` define qué conjunto de algoritmos utiliza el SDK de cifrado de bases de datos de AWS .
A menos que especifique explícitamente un conjunto de algoritmos alternativo, el SDK AWS de cifrado de bases de datos utiliza el [conjunto de algoritmos predeterminado](supported-algorithms.md#recommended-algorithms). [El conjunto de algoritmos predeterminado utiliza el algoritmo AES-GCM con la derivación de claves, [las firmas digitales](concepts.md#digital-sigs) y el compromiso de claves.](concepts.md#key-commitment) Aunque es probable que el conjunto de algoritmos predeterminado sea adecuado para la mayoría de las aplicaciones, puede elegir un conjunto de algoritmos alternativo. Por ejemplo, algunos modelos de confianza quedarían satisfechos con un conjunto de algoritmos sin firmas digitales. Para obtener información sobre los conjuntos de algoritmos compatibles con el SDK AWS de cifrado de bases de datos, consulte[Conjuntos de algoritmos compatibles en el SDK de cifrado AWS de bases de datos](supported-algorithms.md).
Para seleccionar el [conjunto de algoritmos AES-GCM sin firmas digitales ECDSA](supported-algorithms.md#other-algorithms), incluya el siguiente fragmento en la configuración de cifrado de la tabla.
```
AlgorithmSuiteId = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384
```
## Actualización de elementos con el SDK de cifrado de bases de datos AWS
El SDK AWS de cifrado de bases de datos no admite [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para elementos que incluyen atributos cifrados o firmados. Para actualizar un atributo cifrado o firmado, debe usar [ddb](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html):. PutItem Cuando se especifica la misma clave principal que un elemento existente en la solicitud `PutItem`, el nuevo elemento sustituye completamente al existente. También puedes usar [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) para borrar y reemplazar todos los atributos al guardar después de actualizar tus artículos.
# Ejemplos de.NET
En los ejemplos siguientes se muestra cómo utilizar la biblioteca de cifrado del lado del cliente de.NET para DynamoDB a fin de proteger los elementos de la tabla de la aplicación. Para encontrar más ejemplos (y aportar los suyos propios), consulte los [ejemplos de.NET en el repositorio -dynamodb](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/net/src) en. aws-database-encryption-sdk GitHub
Los siguientes ejemplos muestran cómo configurar la biblioteca de cifrado del lado del cliente.NET para DynamoDB en una tabla de Amazon DynamoDB nueva y sin rellenar. Si desea configurar las tablas de Amazon DynamoDB existentes para el cifrado del cliente, consulte. [Agregar la versión 3.x a una tabla existente](ddb-net-config-existing-table.md)
**Topics**
+ [Uso del SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB](#ddb-net-lowlevel-API-example)
+ [Uso del nivel inferior `DynamoDbItemEncryptor`](#ddb-net-itemencryptor)
## Uso del SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB
El siguiente ejemplo muestra cómo utilizar el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB con [AWS KMS un](use-kms-keyring.md) anillo de claves para cifrar y firmar automáticamente los elementos del lado del cliente con las solicitudes de DynamoDB. `PutItem`
Puede utilizar cualquier conjunto de [claves compatible, pero le recomendamos que utilice uno de ellos siempre](keyrings.md) que sea posible. AWS KMS
**[Consulta el ejemplo de código completo: .cs BasicPutGetExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/BasicPutGetExample.cs)**
**Paso 1: Crea el llavero AWS KMS **
El siguiente ejemplo se utiliza `CreateAwsKmsMrkMultiKeyring` para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**Paso 2: configurar las acciones de sus atributos**
En el siguiente ejemplo, se define un `attributeActionsOnEncrypt` diccionario que representa ejemplos de [acciones de atributo](concepts.md#crypt-actions) para un elemento de la tabla.
El siguiente ejemplo no define ningún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
var attributeActionsOnEncrypt = new Dictionary
{
["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
["attribute2"] = CryptoAction.SIGN_ONLY,
[":attribute3"] = CryptoAction.DO_NOTHING
};
```
**Paso 3: defina qué atributos se excluyen de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asume que cualquier nombre de atributo con el prefijo “`:`” está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).
```
const String unsignAttrPrefix = ":";
```
**Paso 4: definir la configuración de cifrado de la tabla de DynamoDB**
El siguiente ejemplo define un mapa `tableConfigs` que representa la configuración de cifrado de esta tabla de DynamoDB.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-net-using.md#net-logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-net-using.md#ddb-net-config-encrypt).
Para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifrado con capacidad de búsqueda](searchable-encryption.md), también debe incluir [`SearchConfig`](ddb-java-using.md#ddb-search-config) en la configuración de cifrado.
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix
};
tableConfigs.Add(ddbTableName, config);
```
**Paso 5: Crear un nuevo cliente AWS SDK de DynamoDB**
**En el siguiente ejemplo, se crea un nuevo cliente AWS SDK de DynamoDB mediante `TableEncryptionConfigs` el paso 4.**
```
var ddb = new Client.DynamoDbClient(
new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });
```
**Paso 6: Cifrar y firmar un elemento de la tabla de DynamoDB**
En el siguiente ejemplo, se define un `item` diccionario que representa un elemento de tabla de ejemplo y se coloca el elemento en la tabla de DynamoDB. El elemento se cifra y se firma en el lado del cliente antes de enviarlo a DynamoDB.
```
var item = new Dictionary
{
["partition_key"] = new AttributeValue("BasicPutGetExample"),
["sort_key"] = new AttributeValue { N = "0" },
["attribute1"] = new AttributeValue("encrypt and sign me!"),
["attribute2"] = new AttributeValue("sign me!"),
[":attribute3"] = new AttributeValue("ignore me!")
};
PutItemRequest putRequest = new PutItemRequest
{
TableName = ddbTableName,
Item = item
};
PutItemResponse putResponse = await ddb.PutItemAsync(putRequest);
```
## Uso del nivel inferior `DynamoDbItemEncryptor`
En el siguiente ejemplo, se muestra cómo utilizar el nivel inferior `DynamoDbItemEncryptor` con un [conjunto de claves de AWS KMS](use-kms-keyring.md) para cifrar y firmar directamente los elementos de la tabla. `DynamoDbItemEncryptor` No coloca el elemento en la tabla de DynamoDB.
Puede utilizar cualquier conjunto de [claves compatible con el cliente mejorado de DynamoDB, pero le recomendamos que utilice uno de los anillos](keyrings.md) de AWS KMS claves siempre que sea posible.
**nota**
El nivel inferior `DynamoDbItemEncryptor` no admite el cifrado [con capacidad de búsqueda.](searchable-encryption.md) Utilice el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB para utilizar el cifrado con capacidad de búsqueda.
**Consulte el ejemplo de código completo**[: .cs ItemEncryptDecryptExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/itemencryptor/ItemEncryptDecryptExample.cs)
**Paso 1: Crea el llavero AWS KMS **
El siguiente ejemplo se utiliza `CreateAwsKmsMrkMultiKeyring` para crear un AWS KMS anillo de claves con una clave KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**Paso 2: configurar las acciones de sus atributos**
En el siguiente ejemplo, se define un `attributeActionsOnEncrypt` diccionario que representa ejemplos de [acciones de atributo](concepts.md#crypt-actions) para un elemento de la tabla.
El siguiente ejemplo no define ningún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
var attributeActionsOnEncrypt = new Dictionary
{
["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
["attribute2"] = CryptoAction.SIGN_ONLY,
[":attribute3"] = CryptoAction.DO_NOTHING
};
```
**Paso 3: defina qué atributos se excluyen de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asume que cualquier nombre de atributo con el prefijo “`:`” está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).
```
String unsignAttrPrefix = ":";
```
**Paso 4: defina la configuración de `DynamoDbItemEncryptor`**
En el siguiente ejemplo, se consulta la configuración de `DynamoDbItemEncryptor`.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-net-using.md#net-logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Para obtener más información, consulte [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-net-using.md#ddb-net-config-encrypt).
```
var config = new DynamoDbItemEncryptorConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix
};
```
**Paso 5: Crear el `DynamoDbItemEncryptor`**
En el siguiente ejemplo, se crea un nuevo `DynamoDbItemEncryptor`, con la `config` del **Paso 4**.
```
var itemEncryptor = new DynamoDbItemEncryptor(config);
```
**Paso 6: cifrar y firmar directamente un elemento de la tabla**
En el siguiente ejemplo, se cifra y firma directamente un elemento mediante el `DynamoDbItemEncryptor`. `DynamoDbItemEncryptor` no coloca el elemento en la tabla de DynamoDB.
```
var originalItem = new Dictionary
{
["partition_key"] = new AttributeValue("ItemEncryptDecryptExample"),
["sort_key"] = new AttributeValue { N = "0" },
["attribute1"] = new AttributeValue("encrypt and sign me!"),
["attribute2"] = new AttributeValue("sign me!"),
[":attribute3"] = new AttributeValue("ignore me!")
};
var encryptedItem = itemEncryptor.EncryptItem(
new EncryptItemInput { PlaintextItem = originalItem }
).EncryptedItem;
```
# Configurar una tabla de DynamoDB existente para usar AWS el SDK de cifrado de bases de datos para DynamoDB
Con la versión 3. *x* de la biblioteca de cifrado del lado del cliente .NET para DynamoDB, puede configurar las tablas de Amazon DynamoDB existentes para el cifrado del lado del cliente. En este tema se proporcionan instrucciones sobre los tres pasos que debe seguir para añadir la versión 3.*x* a una tabla de DynamoDB existente y rellenada.
## Paso 1: prepararse para leer y escribir elementos cifrados
Complete los siguientes pasos para preparar su cliente del SDK de cifrado de AWS bases de datos para leer y escribir elementos cifrados. Tras implementar los siguientes cambios, el cliente seguirá leyendo y escribiendo elementos de texto no cifrado. No cifrará ni firmará ningún elemento nuevo escrito en la tabla, pero podrá descifrar los elementos cifrados en cuanto aparezcan. Estos cambios preparan al cliente para empezar a [cifrar nuevos elementos.](#ddb-net-add-step2) Los siguientes cambios deben implementarse en cada lector antes de continuar con el siguiente paso.
**1. Defina las [acciones de sus atributos](concepts.md#crypt-actions)**
Cree un modelo de objetos para definir qué valores de atributo se cifrarán y firmarán, cuáles solo se firmarán y cuáles se ignorarán.
De forma predeterminada, los atributos de la clave principal están firmados pero no cifrados (`SIGN_ONLY`) y todos los demás atributos están cifrados y firmados `ENCRYPT_AND_SIGN`().
Especifique `ENCRYPT_AND_SIGN` si desea cifrar y firmar un atributo. Especifique `SIGN_ONLY` firmar, pero no cifrar, un atributo. Especifique `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` el signo y el atributo e inclúyalos en el contexto de cifrado. No se puede cifrar un atributo sin firmarlo también. Especifique `DO_NOTHING` que se omita un atributo. Para obtener más información, consulte [Acciones de atributos en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-net-using.md#ddb-net-attribute-actions).
Si especifica algún `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
var attributeActionsOnEncrypt = new Dictionary
{
["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
["attribute2"] = CryptoAction.SIGN_ONLY,
[":attribute3"] = CryptoAction.DO_NOTHING
};
```
**2. Defina qué atributos se excluirán de las firmas**
En el ejemplo siguiente, se supone que todos los atributos `DO_NOTHING` comparten el prefijo distinto "`:`" y se utiliza el prefijo para definir los atributos no firmados permitidos. El cliente asumirá que cualquier nombre de atributo con el prefijo "`:`" está excluido de las firmas. Para obtener más información, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).
```
const String unsignAttrPrefix = ":";
```
**3. Cree un [conjunto de claves](keyrings.md)**
El siguiente ejemplo crea un [conjunto de claves de AWS KMS](use-kms-keyring.md). El AWS KMS anillo de claves utiliza un cifrado simétrico o un RSA asimétrico AWS KMS keys para generar, cifrar y descifrar las claves de datos.
En este ejemplo, se utiliza `CreateMrkMultiKeyring` para crear un conjunto de claves de AWS KMS con una clave de KMS de cifrado simétrico. El método `CreateAwsKmsMrkMultiKeyring` garantiza que el conjunto de claves maneje correctamente las claves de una sola región y de múltiples regiones.
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
**4. Definir la configuración de cifrado de la tabla de DynamoDB **
El siguiente ejemplo define un mapa `tableConfigs` que representa la configuración de cifrado de esta tabla de DynamoDB.
En este ejemplo, se especifica el nombre de la tabla de DynamoDB como [nombre de la tabla lógica](ddb-net-using.md#net-logical-table-name). Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado.
Debe especificarlo `FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT` como modificación de texto no cifrado. Esta política sigue leyendo y escribiendo elementos de texto no cifrado, lee los elementos cifrados y prepara al cliente para escribir elementos cifrados.
Para obtener más información sobre los valores incluidos en la tabla de configuración de cifrado, consulte. [Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB](ddb-java-using.md#ddb-config-encrypt)
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
PlaintextOverride = FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```
**5. Crear un nuevo cliente AWS SDK de DynamoDB**
**En el siguiente ejemplo, se crea un nuevo cliente AWS SDK de DynamoDB mediante `TableEncryptionConfigs` el paso 4.**
```
var ddb = new Client.DynamoDbClient(
new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });
```
## Paso 2: escribir elementos cifrados y firmados
Actualice la política de texto sin formato en la configuración de cifrado de la tabla para permitir que el cliente escriba elementos cifrados y firmados. Tras implementar el siguiente cambio, el cliente cifrará y firmará los nuevos elementos en función de las acciones de atributos que configuró en el **paso** 1. El cliente podrá leer los elementos en texto no cifrado y los elementos cifrados y firmados.
Antes de continuar con el [Paso 3](#ddb-net-add-step3), debe cifrar y firmar todos los elementos de texto no cifrado existentes en la tabla. No existe una métrica o consulta única que pueda ejecutar para cifrar rápidamente los elementos de texto no cifrado existentes. Utilice el proceso que mejor se adapte a su sistema. Por ejemplo, puede utilizar un proceso asíncrono que escanee lentamente la tabla y reescriba los elementos mediante las acciones de los atributos y la configuración de cifrado que haya definido. Para identificar los elementos de texto sin formato de la tabla, se recomienda buscar todos los elementos que no contengan los `aws_dbe_foot` atributos que el `aws_dbe_head` SDK de cifrado de AWS bases de datos añade a los elementos cuando están cifrados y firmados.
En el siguiente ejemplo, se actualiza la configuración de cifrado de la tabla desde el **paso 1**. Debe actualizar la anulación de texto no cifrado con `FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`. Esta política sigue leyendo los elementos de texto no cifrado, pero también lee y escribe los elementos cifrados. Cree un nuevo cliente AWS SDK de DynamoDB con la actualización. `TableEncryptionConfigs`
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
PlaintextOverride = FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```
## Paso 3: Lee solo los elementos cifrados y firmados
Una vez cifrados y firmados todos los elementos, actualice la modificación del texto sin formato en la configuración de cifrado de la tabla para que el cliente solo pueda leer y escribir los elementos cifrados y firmados. Tras implementar el siguiente cambio, el cliente cifrará y firmará los nuevos elementos en función de las acciones de atributos que configuró en el **paso 1**. El cliente solo podrá leer los elementos cifrados y firmados.
En el siguiente ejemplo, se actualiza la configuración de cifrado de la tabla desde el **paso** 2. Puede actualizar la anulación de texto no cifrado con `FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT` o eliminar la política de texto no cifrado de su configuración. De forma predeterminada, el cliente solo lee y escribe los elementos cifrados y firmados. Cree un nuevo cliente AWS SDK de DynamoDB con la actualización. `TableEncryptionConfigs`
```
Dictionary tableConfigs =
new Dictionary();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
LogicalTableName = ddbTableName,
PartitionKeyName = "partition_key",
SortKeyName = "sort_key",
AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
Keyring = kmsKeyring,
AllowedUnsignedAttributePrefix = unsignAttrPrefix,
// Optional: you can also remove the plaintext policy from your configuration
PlaintextOverride = FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```
# Rust
En este tema se explica cómo instalar y usar la versión 1. *x* de la biblioteca de cifrado del lado del cliente de Rust para DynamoDB. Para obtener más información sobre la programación con el SDK AWS de cifrado de bases de datos para DynamoDB, consulte los ejemplos de [Rust en el repositorio -dynamodb](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/) en aws-database-encryption-sdk. GitHub
Todas las implementaciones de lenguajes de programación del SDK de cifrado de AWS bases de datos para DynamoDB son interoperables.
**Topics**
+ [Requisitos previos](#ddb-rust-prerequisites)
+ [Instalación](#ddb-rust-install)
+ [Uso del cliente Rust](ddb-rust-using.md)
## Requisitos previos
Antes de instalar la biblioteca de cifrado del lado del cliente de Rust para DynamoDB, asegúrese de cumplir los siguientes requisitos previos.
**Instale Rust y Cargo**
Instala la versión estable actual de [Rust](https://www.rust-lang.org/) usando [rustup.](https://rustup.rs/)
Para obtener más información sobre la descarga e instalación de rustup, consulta los [procedimientos de instalación](https://doc.rust-lang.org/cargo/getting-started/installation.html) en The Cargo Book.
## Instalación
La biblioteca de cifrado del lado del cliente de Rust para DynamoDB está disponible en forma de caja en Crates.io. [aws-db-esdk](https://crates.io/crates/aws-db-esdk) [Para obtener más información sobre la instalación y creación de la biblioteca, consulte el archivo README.md en el repositorio -dynamodb.](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) aws-database-encryption-sdk GitHub
**Manualmente**
[Para instalar la biblioteca de cifrado del lado del cliente de Rust para DynamoDB, clone o descargue el repositorio -dynamodb. aws-database-encryption-sdk](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) GitHub
**Para instalar la versión más reciente**
Ejecute el siguiente comando Cargo en el directorio de su proyecto:
```
cargo add aws-db-esdk
```
O añade la siguiente línea a tu Cargo.toml:
```
aws-db-esdk = ""
```
# Uso de la biblioteca de cifrado del lado del cliente de Rust para DynamoDB
En este tema se explican algunas de las funciones y clases auxiliares de la versión 1. *x* de la biblioteca de cifrado del lado del cliente de Rust para DynamoDB.
Para obtener más información sobre la programación con la biblioteca de cifrado del lado del cliente de Rust para DynamoDB, consulte los [ejemplos de Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/) en el repositorio -dynamodb de. aws-database-encryption-sdk GitHub
**Topics**
+ [Encriptadores de elementos](#ddb-rust-item-encryptors)
+ [Acciones de atributo](#ddb-rust-attribute-actions)
+ [La configuración de cifrado](#ddb-rust-config-encrypt)
+ [Actualización de un elemento](#ddb-rust-update-items)
## Encriptadores de elementos
En esencia, el SDK de cifrado AWS de bases de datos para DynamoDB es un cifrador de elementos. Puede utilizar la versión 1. *x* de la biblioteca de cifrado del lado del cliente de Rust para DynamoDB para cifrar, firmar, verificar y descifrar los elementos de la tabla de DynamoDB de las siguientes maneras.
**El SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB**
Puede usar la [configuración de cifrado de tablas](#ddb-rust-config-encrypt) para crear un cliente de DynamoDB que cifre y firme automáticamente los elementos del lado del cliente con sus solicitudes de DynamoDB. `PutItem`
[Debe usar el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB para utilizar el cifrado con capacidad de búsqueda.](searchable-encryption.md)
Para ver un ejemplo que muestre cómo utilizar el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB, [consulte](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/basic_get_put_example.rs) basic\$1get\$1put\$1example.rs en el repositorio -dynamodb en. aws-database-encryption-sdk GitHub
**El nivel inferior `DynamoDbItemEncryptor`**
El nivel inferior cifra y firma o descifra y verifica `DynamoDbItemEncryptor` directamente los elementos de la tabla sin llamar a DynamoDB. No realiza DynamoDB ni `PutItem` solicitudes`GetItem`. Por ejemplo, puede usar el nivel inferior `DynamoDbItemEncryptor` para descifrar y verificar directamente un elemento de DynamoDB que ya haya recuperado.
El nivel inferior `DynamoDbItemEncryptor` no admite el cifrado [con capacidad de búsqueda.](searchable-encryption.md)
[Para ver un ejemplo que muestre cómo utilizar el nivel inferior, consulte item\$1encrypt\$1decrypt.rs en el repositorio -dynamodb de. `DynamoDbItemEncryptor`](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/itemencryptor/item_encrypt_decrypt.rs) aws-database-encryption-sdk GitHub
## Acciones de atributos en el SDK de cifrado AWS de bases de datos para DynamoDB
[Las acciones de atributos](concepts.md#crypt-actions) determinan qué valores de atributo están cifrados y firmados, cuáles solo están firmados, cuáles están firmados e incluidos en el contexto de cifrado y cuáles se ignoran.
Para especificar las acciones de los atributos con el cliente Rust, defina manualmente las acciones de los atributos mediante un modelo de objetos. Especifique las acciones de sus atributos creando un `HashMap` objeto en el que los pares nombre-valor representen los nombres de los atributos y las acciones especificadas.
Especifique `ENCRYPT_AND_SIGN` si desea cifrar y firmar un atributo. Especifique `SIGN_ONLY` firmar, pero no cifrar, un atributo. Especifique si `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` desea firmar un atributo e incluirlo en el contexto de cifrado. No se puede cifrar un atributo sin firmarlo también. Especifique `DO_NOTHING` que se omita un atributo.
Los atributos de partición y ordenación deben ser uno de `SIGN_ONLY` los dos`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Si define algún atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, los atributos de partición y ordenación también deben serlo`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**nota**
Tras definir las acciones de los atributos, debe definir qué atributos se excluyen de las firmas. Para facilitar la adición de nuevos atributos sin firmar en el futuro, recomendamos elegir un prefijo distinto (como “`:`“) para identificar los atributos sin firmar. Incluya este prefijo en el nombre del atributo para todos los atributos marcados `DO_NOTHING` al definir el esquema y las acciones de atributos de DynamoDB.
El siguiente modelo de objetos muestra cómo especificar `ENCRYPT_AND_SIGN` `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, y `DO_NOTHING` atribuir acciones con el cliente Rust. En este ejemplo se usa el prefijo `:` "» para identificar `DO_NOTHING` los atributos.
```
let attribute_actions_on_encrypt = HashMap::from([
("partition_key".to_string(), CryptoAction::SignOnly),
("sort_key".to_string(), CryptoAction::SignOnly),
("attribute1".to_string(), CryptoAction::EncryptAndSign),
("attribute2".to_string(), CryptoAction::SignOnly),
(":attribute3".to_string(), CryptoAction::DoNothing),
]);
```
## Configuración de cifrado en el SDK de cifrado AWS de bases de datos para DynamoDB
Al utilizar el SDK de cifrado AWS de bases de datos, debe definir explícitamente una configuración de cifrado para la tabla de DynamoDB. Los valores necesarios en la configuración de cifrado dependen de si ha definido las acciones de los atributos manualmente o con una clase de datos anotada.
El siguiente fragmento define una configuración de cifrado de tablas de DynamoDB mediante el SDK de cifrado de AWS bases de datos de bajo nivel para la API de DynamoDB y los atributos no firmados permitidos definidos por un prefijo distinto.
```
let table_config = DynamoDbTableEncryptionConfig::builder()
.logical_table_name(ddb_table_name)
.partition_key_name("partition_key")
.sort_key_name("sort_key")
.attribute_actions_on_encrypt(attribute_actions_on_encrypt)
.keyring(kms_keyring)
.allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
// Specifying an algorithm suite is optional
.algorithm_suite_id(
DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
)
.build()?;
let table_configs = DynamoDbTablesEncryptionConfig::builder()
.table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
.build()?;
```
**Nombre de la tabla lógica**
Un nombre de tabla lógico para la tabla de DynamoDB.
El nombre de la tabla lógica está enlazado criptográficamente a todos los datos almacenados en la tabla para simplificar las operaciones de restauración de DynamoDB. Se recomienda encarecidamente especificar el nombre de la tabla de DynamoDB como nombre de la tabla lógica cuando defina por primera vez la configuración de cifrado. Debe especificar siempre el mismo nombre de tabla lógica. Para que el descifrado se realice correctamente, el nombre de la tabla lógica debe coincidir con el nombre especificado en el cifrado. En caso de que el nombre de la tabla de DynamoDB cambie después de [restaurar la tabla de DynamoDB a partir de una copia de seguridad, el nombre de la tabla](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html) lógica garantiza que la operación de descifrado siga reconociendo la tabla.
**Atributos no firmados permitidos**
Los atributos marcados `DO_NOTHING` en tus acciones de atributos.
Los atributos no firmados permitidos indican al cliente qué atributos están excluidos de las firmas. El cliente asume que todos los demás atributos están incluidos en la firma. A continuación, al descifrar un registro, el cliente determina qué atributos debe verificar y cuáles debe ignorar de los atributos no firmados permitidos que especificó. No puede eliminar un atributo de los atributos no firmados permitidos.
Puede definir los atributos no firmados permitidos de forma explícita mediante la creación de una matriz que enumere todos sus `DO_NOTHING` atributos. También puedes especificar un prefijo distinto al asignar un nombre a tus `DO_NOTHING` atributos y usar el prefijo para indicar al cliente qué atributos no están firmados. Recomendamos encarecidamente especificar un prefijo distinto porque simplifica el proceso de añadir un nuevo `DO_NOTHING` atributo en el futuro. Para obtener más información, consulte [Actualización de su modelo de datos](ddb-update-data-model.md).
Si no especifica un prefijo para todos los `DO_NOTHING` atributos, puede configurar una `allowedUnsignedAttributes` matriz que enumere de forma explícita todos los atributos que el cliente debería esperar que no estén firmados cuando los encuentre al descifrarlos. Solo debe definir de forma explícita los atributos no firmados permitidos si es absolutamente necesario.
**Configuración de búsqueda (opcional)**
`SearchConfig`Define la [versión de baliza](using-beacons.md#beacon-version).
`SearchConfig`Debe especificarse para utilizar [balizas firmadas](configure.md#signed-beacons) o [cifradas con capacidad de búsqueda](searchable-encryption.md).
**Conjunto de algoritmos (opcional)**
El `algorithmSuiteId` define qué conjunto de algoritmos utiliza el SDK de cifrado de bases de datos de AWS .
A menos que especifique explícitamente un conjunto de algoritmos alternativo, el SDK AWS de cifrado de bases de datos utiliza el [conjunto de algoritmos predeterminado](supported-algorithms.md#recommended-algorithms). [El conjunto de algoritmos predeterminado utiliza el algoritmo AES-GCM con la derivación de claves, [las firmas digitales](concepts.md#digital-sigs) y el compromiso de claves.](concepts.md#key-commitment) Aunque es probable que el conjunto de algoritmos predeterminado sea adecuado para la mayoría de las aplicaciones, puede elegir un conjunto de algoritmos alternativo. Por ejemplo, algunos modelos de confianza quedarían satisfechos con un conjunto de algoritmos sin firmas digitales. Para obtener información sobre los conjuntos de algoritmos compatibles con el SDK AWS de cifrado de bases de datos, consulte[Conjuntos de algoritmos compatibles en el SDK de cifrado AWS de bases de datos](supported-algorithms.md).
Para seleccionar el [conjunto de algoritmos AES-GCM sin firmas digitales ECDSA](supported-algorithms.md#other-algorithms), incluya el siguiente fragmento en la configuración de cifrado de la tabla.
```
.algorithm_suite_id(
DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
)
```
## Actualización de elementos con el SDK de cifrado de bases de datos AWS
El SDK AWS de cifrado de bases de datos no admite [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para elementos que incluyen atributos cifrados o firmados. Para actualizar un atributo cifrado o firmado, debe usar [ddb](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html):. PutItem Cuando se especifica la misma clave principal que un elemento existente en la solicitud `PutItem`, el nuevo elemento sustituye completamente al existente.
# Cliente de cifrado de DynamoDB antiguo
El 9 de junio de 2023, nuestra biblioteca de cifrado del lado del cliente pasó a AWS llamarse Database Encryption SDK. El SDK AWS de cifrado de bases de datos sigue siendo compatible con las versiones antiguas de DynamoDB Encryption Client. Para obtener más información sobre las distintas partes de la biblioteca de cifrado del cliente que cambiaron con el cambio de nombre, consulte [Cambio de nombre del Cliente de encriptación de Amazon DynamoDB](DDBEC-rename.md).
Para migrar a la versión más reciente de la biblioteca de cifrado del cliente de Java para DynamoDB, consulte [Migrar a la versión 3.x](ddb-java-migrate.md).
**Topics**
+ [AWS Compatibilidad con la versión SDK de cifrado de bases de datos para DynamoDB](#legacy-support)
+ [Cómo funciona el cliente de cifrado de DynamoDB](DDBEC-legacy-how-it-works.md)
+ [Conceptos del Cliente de encriptación de Amazon DynamoDB](DDBEC-legacy-concepts.md)
+ [Proveedor de materiales criptográficos](crypto-materials-providers.md)
+ [Lenguajes de programación disponibles para el Cliente de encriptación de Amazon DynamoDB](programming-languages.md)
+ [Cambiar el modelo de datos](data-model.md)
+ [Solución de problemas en la aplicación DynamoDB Encryption Client](troubleshooting.md)
## AWS Compatibilidad con la versión SDK de cifrado de bases de datos para DynamoDB
En los temas del capítulo Legacy, se proporciona información sobre las versiones 1. *x* —2. *x* del cliente de cifrado de DynamoDB para Java y versiones 1. *x —3*. *x* del cliente de cifrado de DynamoDB para Python.
En la siguiente tabla se enumeran los idiomas y las versiones que admiten el cifrado del cliente en Amazon DynamoDB.
| Lenguaje de programación | Versión | Fase del ciclo de vida de la versión principal del SDK |
| --- | --- | --- |
| Java | Versiones 1. *x* | [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), efectiva en julio de 2022 |
| Java | Versiones 2. *x* | [Disponibilidad general](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA) |
| Java | Versión 3.*x* | [Disponibilidad general](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA) |
| Python | Versiones 1.*x* | [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), efectiva en julio de 2022 |
| Python | Versiones 2.*x* | [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), efectiva en julio de 2022 |
| Python | Versiones 3. *x* | [Disponibilidad general](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA) |
# Cómo funciona el cliente de cifrado de DynamoDB
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El cliente de cifrado de DynamoDB está diseñado específicamente para proteger los datos que almacena en DynamoDB. Las bibliotecas incluyen implementaciones seguras que puede ampliar o utilizar sin hacer ningún cambio. La mayoría de los elementos se representan mediante elementos abstractos para que pueda crear y utilizar componentes personalizados compatibles.
**Cifrado y firma de elementos de tabla**
La esencia del cliente de cifrado de DynamoDB es un *encriptador de elementos* que cifra, firma, verifica y descifra los elementos de la tabla. Recibe información acerca de los elementos de tabla e instrucciones acerca de qué elementos hay que cifrar y firmar. Obtiene los materiales de cifrado, y las instrucciones sobre su uso, de un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) que usted selecciona y configura.
En el siguiente diagrama, se muestra una vista general de este proceso.
![\[Cifrado y firma de elementos en el cliente de cifrado de DynamoDB\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/arch-encrypt.png)
Para cifrar y firmar un elemento de la tabla, el cliente de cifrado de DynamoDB necesita:
+ **Información acerca de la tabla. ** Obtiene información acerca de la tabla de un [contexto de cifrado de DynamoDB](concepts.md#encryption-context) que usted suministra. Algunos elementos auxiliares obtienen la información necesaria de DynamoDB y crean automáticamente el contexto de cifrado de DynamoDB para usted.
**nota**
El contexto de cifrado de *DynamoDB en el cliente de cifrado* de DynamoDB no está relacionado con el contexto de cifrado de () y *el*. AWS Key Management Service AWS KMS AWS Encryption SDK
+ **Los atributos que hay que cifrar y firmar.** Obtiene esta información de las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) que usted suministra.
+ **Materiales de cifrado, incluidas las claves de cifrado y firma.** Los obtiene de un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que usted selecciona y configura.
+ **Instrucciones para cifrar y firmar el elemento**. El CMP añade instrucciones de uso de los materiales de cifrado, incluidos los algoritmos de cifrado y firma, a la [descripción de material real](DDBEC-legacy-concepts.md#legacy-material-description).
El [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor) utiliza todos estos elementos para cifrar y firmar el elemento. El encriptador de elementos también añade dos atributos al elemento: un [atributo de descripción de material](DDBEC-legacy-concepts.md#legacy-material-description) que contiene las instrucciones de cifrado y firma (la descripción de material real) y un atributo que contiene la firma. Puede interactuar directamente con el encriptador de elementos, o puede utilizar características auxiliares que interactúan con el encriptador de elementos para implementar un comportamiento predeterminado seguro.
El resultado es un elemento de DynamoDB que contiene datos cifrados y firmados.
**Verificación y descifrado de elementos de tabla**
Estos componentes también funcionan juntos para verificar y descifrar el elemento, como se muestra en el siguiente diagrama.
![\[Verificación y descifrado de elementos en el cliente de cifrado de DynamoDB\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/arch-decrypt.png)
Para verificar y descifrar un elemento, el cliente de cifrado de DynamoDB necesita los mismos componentes, componentes con la misma configuración o componentes diseñados especialmente para descifrar los elementos, de la siguiente manera:
+ **Información acerca de la tabla** del [contexto de cifrado de DynamoDB](concepts.md#encryption-context).
+ **Qué atributos verificar y descifrar.** Los obtiene de las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions).
+ **Materiales de descifrado, incluidas las claves de verificación y descifrado**, del [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que usted selecciona y configura.
El elemento cifrado no incluye ningún registro del CMP que se utilizó para cifrarlo. Debe proporcionar el mismo CMP, un CMP con la misma configuración o un CMP que esté diseñado para descifrar elementos.
+ **Información acerca de cómo el elemento se cifró y firmó**, incluidos los algoritmos de cifrado y firma. El cliente los obtiene del [atributo de descripción de material](DDBEC-legacy-concepts.md#legacy-material-description) del elemento.
El [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor) utiliza todos estos elementos para verificar y descifrar el elemento. También elimina los atributos de descripción de material y firma. El resultado es un elemento de DynamoDB como texto no cifrado.
# Conceptos del Cliente de encriptación de Amazon DynamoDB
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En este tema se explican la terminología y los conceptos empleados en el Cliente de encriptación de Amazon DynamoDB.
Para obtener información acerca de cómo interactúan los componentes del cliente de cifrado de DynamoDB, consulte [Cómo funciona el cliente de cifrado de DynamoDB](DDBEC-legacy-how-it-works.md).
**Topics**
+ [Proveedor de materiales criptográficos (CMP)](#concept-material-provider)
+ [Encriptadores de elementos](#item-encryptor)
+ [Acciones de atributo](#legacy-attribute-actions)
+ [Descripción de material](#legacy-material-description)
+ [Contexto de cifrado de DynamoDB](#legacy-encryption-context)
+ [Almacén de proveedores](#provider-store)
## Proveedor de materiales criptográficos (CMP)
Al implementar el cliente de cifrado de DynamoDB, una de sus primeras tareas consiste en [seleccionar un proveedor de materiales criptográficos ](crypto-materials-providers.md)(CMP) (también conocido como *proveedor de materiales de cifrado*). Esta elección determina gran parte del resto de la implementación.
Un *proveedor de materiales criptográficos* (CMP) recopila, reúne y devuelve los materiales criptográficos que el [encriptador de elementos](#item-encryptor) utiliza para cifrar y firmar los elementos de tabla. El CMP determina los algoritmos de cifrado que se utilizarán y cómo generar y proteger las claves de cifrado y firma.
El CMP interactúa con el encriptador de elementos. El encriptador de elementos solicita materiales de cifrado o descifrado al CMP, y el CMP los devuelve al encriptador de elementos. A continuación, el encriptador de elementos utiliza los materiales criptográficos para cifrar y firmar, o para verificar y descifrar, el elemento.
Debe especificar el CMP al configurar el cliente. Puede crear un CMP personalizado compatible o utilizar uno de los muchos de CMPs la biblioteca. La mayoría CMPs están disponibles para varios lenguajes de programación.
## Encriptadores de elementos
El *encriptador de elementos* es un componente de nivel inferior que realiza operaciones criptográficas para el cliente de cifrado de DynamoDB. Solicita materiales criptográficos a un [proveedor de materiales criptográficos](#concept-material-provider) (CMP) y después utiliza los materiales que el CMP devuelve para cifrar y firmar, o para verificar y descifrar, el elemento de tabla.
Puede interactuar directamente con el encriptador de elementos o puede utilizar los elementos auxiliares proporcionados en la biblioteca. Por ejemplo, el cliente de cifrado de DynamoDB para Java incluye una clase auxiliar `AttributeEncryptor``DynamoDBMapper` que puede utilizar con , en lugar de interactuar directamente con el encriptador de elementos `DynamoDBEncryptor`. La biblioteca Python incluye las clases auxiliares `EncryptedTable`, `EncryptedClient` y `EncryptedResource` que interactúan con el encriptador de elementos por usted.
## Acciones de atributo
Las *acciones de atributo* indican al encriptador de elementos qué acciones hay que realizar en cada atributo del elemento.
Los valores de las acciones de atributo pueden ser uno de los siguientes:
+ **Encrypt and sign**: cifra el valor del atributo. Incluir el atributo (nombre y valor) en la firma del elemento.
+ **Sign only**: incluye el atributo en la firma del artículo.
+ **Do nothing**: no cifre ni firme el atributo.
Para cualquier atributo que pueda almacenar datos confidenciales, use **Encrypt and sign**. Para los atributos de clave principal (clave de partición y clave de clasificación), utilice **Sign only**. El [atributo de descripción de material](#legacy-material-description) y el atributo de firma no se firman ni se cifran. No es necesario especificar acciones para estos atributos.
Elija cuidadosamente sus acciones de atributo. En caso de duda, use **Encrypt and sign**. Una vez que haya utilizado la para proteger los elementos de la tabla, no puede cambiar la acción de un atributo sin arriesgarse a que se produzca un error de validación de firma. Para obtener más información, consulte [Cambiar el modelo de datos](data-model.md).
**aviso**
No cifre los atributos de clave principal. Deben permanecer en texto no cifrado para que DynamoDB pueda encontrar el elemento sin realizar un examen completo de la tabla.
Si el [contexto de cifrado de DynamoDB](concepts.md#encryption-context) identifica sus atributos de clave principal, el cliente generará un error si intenta cifrarlos.
La técnica empleada para especificar las acciones de atributo es diferente para cada lenguaje de programación. También puede ser específica de las clases auxiliares que utilice.
Para obtener más información, consulte la documentación de su lenguaje de programación.
+ [Python](python-using.md#python-attribute-actions)
+ [Java](java-using.md#attribute-actions-java)
## Descripción de material
La *descripción de material* de un elemento de tabla cifrado consta de información, como los algoritmos de cifrado, acerca del cifrado y la firma del elemento de tabla. El [proveedor de materiales criptográficos](#concept-material-provider) (CMP) registra la descripción de material mientras reúne los materiales criptográficos para el cifrado y la firma. Posteriormente, cuando necesita reunir los materiales criptográficos para verificar y descifrar el elemento, utiliza la descripción de material como guía.
En el DynamoDB Encryption Client, la descripción de material se refiere a tres elementos relacionados:
**Descripción de material solicitado**
Algunos [proveedores de materiales criptográficos](#concept-material-provider) (CMPs) permiten especificar opciones avanzadas, como un algoritmo de cifrado. Para indicar sus opciones, añada pares de nombre y valor a la propiedad de descripción de material del [contexto de cifrado de DynamoDB](concepts.md#encryption-context) en la solicitud para cifrar un elemento de tabla. Este elemento se conoce como la *descripción de material solicitado*. Los valores válidos de la descripción de material solicitado los define el CMP elegido.
Puesto que la descripción de material puede anular valores predeterminados seguros, le recomendamos que omita la descripción de material solicitado a menos que tenga una razón de peso para utilizarla.
**Descripción de material real**
La descripción del material que devuelven los [proveedores de materiales criptográficos](#concept-material-provider) (CMPs) se conoce como descripción del *material real*. Describe los valores reales que el CMP utilizó cuando reunió los materiales criptográficos. Por lo general, consiste en la descripción de material solicitado, si se utiliza, con algunos cambios y adiciones.
**Atributo de descripción de material**
El cliente guarda la descripción de material real en el *atributo de descripción de material* del elemento cifrado. El nombre del atributo de descripción de material es `amzn-ddb-map-desc` y su valor es la descripción de material real. El cliente utiliza los valores del atributo de descripción de material para verificar y descifrar el elemento.
## Contexto de cifrado de DynamoDB
El *contexto de cifrado de DynamoDB* proporciona información acerca de la tabla y el elemento al [proveedor de materiales criptográficos](#concept-material-provider) (CMP). En las implementaciones avanzadas, el contexto de cifrado de DynamoDB puede incluir una [descripción del material solicitado](#legacy-material-description).
Al cifrar elementos de tabla, el contexto de cifrado de DynamoDB está enlazado criptográficamente a los valores de atributo cifrados. Al descifrar, si el contexto de cifrado de no es una coincidencia exacta que distingue mayúsculas de minúsculas para el contexto de cifrado de DynamoDB utilizado para cifrar, se produce un error en la operación de descifrado. Si interactúa directamente con el [cifrado de elementos](#item-encryptor) debe proporcionar un contexto de cifrado de DynamoDB cuando llame a un método de cifrado o descifrado. La mayoría de los elementos auxiliares crean automáticamente el contexto de cifrado de DynamoDB.
**nota**
El contexto de cifrado de *DynamoDB en el cliente de cifrado* de DynamoDB no está relacionado con el contexto de cifrado de () y *el*. AWS Key Management Service AWS KMS AWS Encryption SDK
El contexto de cifrado de DynamoDB puede incluir los siguientes campos. Todos los campos y valores son opcionales.
+ Nombre de la tabla
+ Nombre de la clave de partición
+ Nombre de la clave de clasificación
+ Pares de nombre y valor de los atributos
+ [Descripción de material solicitado](#legacy-material-description)
## Almacén de proveedores
Un *almacén de proveedores* es un componente que devuelve los proveedores de materiales [criptográficos](#concept-material-provider) (). CMPs El almacén del proveedor puede crearlos CMPs u obtenerlos de otra fuente, como otro almacén del proveedor. El almacén del proveedor guarda las versiones CMPs que crea en un almacenamiento persistente en el que cada CMP almacenado se identifica mediante el nombre del material del solicitante y el número de versión.
El [proveedor más reciente](most-recent-provider.md) del cliente de cifrado de DynamoDB lo obtiene CMPs de un almacén de proveedores, pero puede utilizarlo para CMPs suministrar a cualquier componente. Cada proveedor más reciente está asociado a un almacén de proveedores, pero un almacén de proveedores puede abastecer CMPs a muchos solicitantes en varios hosts.
La tienda del proveedor crea nuevas versiones de CMPs On Demand y devuelve las versiones nuevas y las existentes. También devuelve el número de versión más reciente de un nombre de material determinado. De esta forma, el solicitante puede saber cuándo el almacén de proveedores tiene una nueva versión de su CMP que puede solicitar.
El cliente de cifrado de DynamoDB incluye [ MetaStore](most-recent-provider.md#about-metastore)un, que es un almacén de proveedores que crea CMPs Wrapped con claves que se almacenan en DynamoDB y se cifran mediante un cliente de cifrado de DynamoDB interno.
**Más información:**
+ Almacén de proveedores: [Java](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/store/ProviderStore.html), [Python](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/src/dynamodb_encryption_sdk/material_providers/store/__init__.py)
+ MetaStore: [Java](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/store/MetaStore.html), [Python](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/materials_providers/metastore.html#module-dynamodb_encryption_sdk.material_providers.store.meta)
# Proveedor de materiales criptográficos
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
Una de las decisiones más importantes que debe tomar al utilizar el cliente de cifrado de DynamoDB es seleccionar un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP). El CMP combina y devuelve materiales criptográficos al encriptador de elementos. También determina cómo se generan las claves de cifrado y de firma, si se generan nuevos materiales de clave para cada elemento o si se reutilizan, así como los algoritmos de cifrado y de firma que se utilizan.
Puede elegir un CMP para las implementaciones proporcionadas en las bibliotecas del cliente de cifrado de DynamoDB o crear un CMP personalizado compatible. Su opción de CMP también podría depender del [lenguaje de programación](programming-languages.md) que utilice.
En este tema se describen las más comunes CMPs y se ofrecen algunos consejos para ayudarle a elegir la mejor opción para su aplicación.
**Proveedor de materiales de KMS directo**
El proveedor de materiales de KMS directo protege los elementos de la tabla con un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)que nunca se deja[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) sin cifrar. Su aplicación no tiene que generar ni gestionar ningún material criptográfico. Como las utiliza AWS KMS key para generar claves de cifrado y firma únicas para cada elemento, este proveedor llama AWS KMS cada vez que cifra o descifra un elemento.
Si para su aplicación le resulta práctico utilizar AWS KMS una AWS KMS llamada por transacción, este proveedor es una buena opción.
Para obtener más información, consulte [Proveedor de materiales de KMS directo](direct-kms-provider.md).
**Proveedor de materiales encapsulado (CMP encapsulado)**
El proveedor de materiales encapsulado (CMP encapsulado) permite generar y administrar las claves de encapsulación y de firma desde fuera del cliente de cifrado de DynamoDB.
El CMP encapsulado genera una clave de cifrado única para cada elemento. A continuación utiliza las claves de encapsulación (o desencapsulación) y de firma que suministre. Por tanto, determina cómo se generan las claves de firma y encapsulación y si son únicas para cada elemento o si se reutilizan. El Wrapped CMP es una alternativa segura al [proveedor de Direct KMS](direct-kms-provider.md) para aplicaciones que no utilizan materiales criptográficos AWS KMS y pueden gestionarlos de forma segura.
Para obtener más información, consulte [Proveedor de materiales encapsulado](wrapped-provider.md).
**Proveedor más reciente**
El *proveedor más reciente* es un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que está diseñado para funcionar con un [almacén de proveedores](DDBEC-legacy-concepts.md#provider-store). Lo obtiene CMPs de la tienda del proveedor y obtiene los materiales criptográficos que devuelve del. CMPs El proveedor más reciente normalmente utiliza cada CMP para satisfacer varias solicitudes para materiales criptográficos, pero puede usar las características del almacén de proveedores para controlar hasta qué punto se reutilizan los materiales, determinar la frecuencia con la que se rota su CMP e incluso cambiar el tipo de CMP que se utiliza sin cambiar el proveedor más reciente.
Puede usar el proveedor más reciente con cualquier almacén de proveedores compatible. El cliente de cifrado de DynamoDB incluye MetaStore una, que es una tienda de proveedores que devuelve Wrapped. CMPs
El proveedor más reciente es una buena opción para aplicaciones que necesitan minimizar las llamadas a su origen criptográfico y para aplicaciones que pueden reutilizar algunos materiales criptográficos sin infringir sus requisitos de seguridad. Por ejemplo, le permite proteger sus materiales criptográficos con un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) sin tener que llamar AWS KMS cada vez que cifra o descifra un elemento.
Para obtener más información, consulte [Proveedor más reciente](most-recent-provider.md).
**Proveedor de materiales estático**
El proveedor de materiales estáticos está diseñado para realizar pruebas, proof-of-concept demostraciones y ofrecer compatibilidad con versiones anteriores. No genera materiales criptográficos únicos para cada elemento. Devuelve las mismas claves de cifrado y firma que suministra y dichas claves se utilizan directamente para cifrar, descifrar y firmar los elementos de tabla.
El [Proveedor estático asimétrico](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/AsymmetricStaticProvider.html) de la biblioteca de Java no es un proveedor estático. Solo suministra constructores alternativos para el [CMP encapsulado](wrapped-provider.md). Es seguro para uso de producción, pero se debe utilizar directamente el CMP encapsulado siempre que sea posible.
**Topics**
+ [Proveedor de materiales de KMS directo](direct-kms-provider.md)
+ [Proveedor de materiales encapsulado](wrapped-provider.md)
+ [Proveedor más reciente](most-recent-provider.md)
+ [Proveedor de materiales estático](static-provider.md)
# Proveedor de materiales de KMS directo
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El *proveedor de materiales de Direct KMS* (proveedor de Direct KMS) protege los elementos de la tabla con un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)que nunca deja [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) sin cifrar. Este [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) devuelve una clave de cifrado y una clave de firma únicas para cada elemento de la tabla. Para ello, llama AWS KMS cada vez que se cifra o descifra un elemento.
Si procesa elementos de DynamoDB con una frecuencia alta y a gran escala, es posible que supere los límites y provoque demoras en AWS KMS [requests-per-secondel](https://docs.aws.amazon.com/kms/latest/developerguide/limits.html#requests-per-second) procesamiento. Si necesita superar estos límites, cree un caso en el [AWS Support Centro](https://console.aws.amazon.com/support/home). También podría considerar la posibilidad de utilizar un proveedor de materiales criptográficos con una reutilización de claves limitada, como el [proveedor más reciente](most-recent-provider.md).
[Para utilizar el proveedor de KMS directo, la persona que llama debe tener, al menos Cuenta de AWS, uno AWS KMS key, y permiso para llamar a las operaciones de [descifrado [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)y desencriptar](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) del.](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) AWS KMS key La AWS KMS key debe ser una clave de cifrado simétrica; el cliente de cifrado de DynamoDB no admite el cifrado asimétrico. Si utiliza una [tabla global de DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html), posiblemente desee especificar una [AWS KMS clave de múltiples regiones](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html). Para obtener más información, consulte [Modo de uso](#provider-kms-how-to-use).
**nota**
Al utilizar el proveedor de KMS directo, los nombres y valores de los atributos de la clave principal aparecen en texto plano en el [contexto de AWS KMS cifrado](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) y en los AWS CloudTrail registros de las operaciones relacionadas. AWS KMS Sin embargo, el cliente de cifrado de DynamoDB nunca expone el texto no cifrado de ningún valor de atributo cifrado.
El proveedor de Direct KMS es uno de los varios [proveedores de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) compatibles con el cliente de cifrado de DynamoDB. Para obtener información sobre el otro CMPs, consulte. [Proveedor de materiales criptográficos](crypto-materials-providers.md)
**Para ver código de ejemplo, consulte:**
+ Java: [AwsKmsEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedItem.java)
+ Python: [aws-kms-encrypted-table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py), [aws-kms-encrypted-item](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)
**Topics**
+ [Modo de uso](#provider-kms-how-to-use)
+ [Cómo funciona](#provider-kms-how-it-works)
## Modo de uso
Para crear un proveedor de KMS directo, utilice el parámetro de ID de clave para especificar una [clave KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) de cifrado simétrico en su cuenta. El valor del parámetro ID de clave puede ser el ID de clave, el ARN de clave, el nombre de alias o el ARN de alias de AWS KMS key. Para obtener más información sobre los [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 *.
El proveedor de KMS directo necesita una clave KMS de cifrado simétrica. No puede utilizar una clave KMS asimétrica. Sin embargo, puede utilizar una clave KMS de múltiples regiones, una clave KMS con material de claves importado o una clave KMS en un almacén de claves personalizado. Debe tener los permisos [kms: GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) y [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) en la clave KMS. Por lo tanto, debe usar una clave administrada por el cliente, no una clave de KMS AWS administrada o AWS propia.
El cliente de cifrado de DynamoDB para Python determina la región a la que se debe AWS KMS llamar desde la región en el valor del parámetro de ID de clave, si incluye alguna. De lo contrario, utiliza la región del AWS KMS cliente, si se especifica una, o la región que se configura en el. AWS SDK para Python (Boto3) Para obtener información sobre la selección de regiones en Python, consulta [Configuración](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html) en la referencia de la API del AWS SDK for Python (Boto3).
El cliente de cifrado de DynamoDB para Java determina la región a la que se debe AWS KMS llamar desde la región del cliente, si AWS KMS el cliente que especifique incluye una región. De lo contrario, utiliza la región que usted configure en la AWS SDK para Java. Para obtener información sobre la selección de regiones en AWS SDK para Java, consulte la [Región de AWS selección](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-region-selection.html) en la Guía AWS SDK para Java para desarrolladores.
------
#### [ Java ]
```
// Replace the example key ARN and Region with valid values for your application
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
final String region = 'us-west-2'
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```
------
#### [ Python ]
En el siguiente ejemplo, se utiliza la clave ARN para especificar el AWS KMS key. Si su identificador de clave no incluye una Región de AWS, el cliente de cifrado de DynamoDB obtiene la región de la sesión de Botocore configurada, si la hay, o de los valores predeterminados de Boto.
```
# Replace the example key ID with a valid value
kms_key = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key)
```
------
Si utiliza tablas [globales de Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html), le recomendamos que cifre los datos con una clave multirregional. AWS KMS Las claves multirregionales son AWS KMS keys diferentes Regiones de AWS y se pueden usar indistintamente porque tienen el mismo identificador de clave y el mismo material de clave. Para obtener más detalles, consulte [Uso de claves de múltiples regiones](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) en la *Guía para desarrolladores de AWS Key Management Service *.
**nota**
Si utiliza las tablas globales de la [versión 2017.11.29](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V1.html), debe configurar las acciones de los atributos para que los campos de replicación reservados no estén cifrados ni firmados. Para obtener más información, consulte [Problemas con las tablas globales de versiones anteriores](troubleshooting.md#fix-global-tables).
Para usar una clave de múltiples regiones con el cliente de cifrado de DynamoDB, cree una clave de múltiples regiones y replíquela en las regiones en las que se ejecuta la aplicación. A continuación, configure el proveedor de KMS directo para que utilice la clave de múltiples regiones en la región a la que llama el cliente de cifrado de DynamoDB AWS KMS.
En el siguiente ejemplo, se configura el cliente de cifrado de DynamoDB para que cifre datos en la región Este de EE. UU. (Norte de Virginia) (us-east-1) y los descifra en la región Oeste de EE. UU. (Oregón) (us-west-2) mediante una clave de múltiples regiones.
------
#### [ Java ]
En este ejemplo, el cliente de cifrado de DynamoDB obtiene la región para realizar AWS KMS llamadas desde la región del cliente. AWS KMS El valor `keyArn` identifica una clave de múltiples regiones en la misma región.
```
// Encrypt in us-east-1
// Replace the example key ARN and Region with valid values for your application
final String usEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-east-1'
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usEastKey);
```
```
// Decrypt in us-west-2
// Replace the example key ARN and Region with valid values for your application
final String usWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-west-2'
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usWestKey);
```
------
#### [ Python ]
En este ejemplo, el cliente de cifrado de DynamoDB obtiene la región para realizar AWS KMS llamadas desde la región en la clave ARN.
```
# Encrypt in us-east-1
# Replace the example key ID with a valid value
us_east_key = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_east_key)
```
```
# Decrypt in us-west-2
# Replace the example key ID with a valid value
us_west_key = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_west_key)
```
------
## Cómo funciona
El proveedor de KMS directo devuelve las claves de cifrado y firma protegidas por una AWS KMS key que especifique, tal como se muestra en el diagrama siguiente.
![\[La entrada, el procesamiento y la salida del proveedor de KMS directo en el cliente de cifrado de DynamoDB.\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/directKMS.png)
+ Para generar materiales de cifrado, el proveedor de Direct KMS solicita AWS KMS [generar una clave de datos única para cada elemento utilizando una clave](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) AWS KMS key que usted especifique. Deriva las claves de cifrado y de firma para el elemento desde la copia de texto no cifrado de la [clave de datos](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) y, a continuación, devuelve las claves de cifrado y de firma, junto con la clave de datos cifrada, que está almacenada en el [atributo de descripción de material](DDBEC-legacy-concepts.md#legacy-material-description) del elemento.
El encriptador de elementos utiliza las claves de cifrado y de firma y las elimina de la memoria lo antes posible. En el sistema cifrado solo se guarda la copia cifrada de la clave de datos desde la que se derivaron.
+ Para generar materiales de descifrado, el proveedor de Direct KMS solicita descifrar AWS KMS la clave de datos cifrada. A continuación, deriva las claves de verificación y firma desde la clave de datos de texto no cifrado y los devuelve al encriptador de elementos.
El encriptador de elementos verifica el elemento y, si la verificación se realiza correctamente, descifra los valores cifrados. A continuación, elimina las claves de la memoria lo antes posible.
### Obtener los materiales de cifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de KMS directo cuando recibe una solicitud para materiales de cifrado desde el [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor).
**Entrada** (desde la aplicación)
+ El ID de clave de un. AWS KMS key
**Entrada** (desde el encriptador de elementos)
+ [Contexto de cifrado de DynamoDB](concepts.md#encryption-context)
**Salida** (al encriptador de elementos)
+ Clave de cifrado (texto no cifrado)
+ Clave de firma
+ En la [descripción de material real](DDBEC-legacy-concepts.md#legacy-material-description): estos valores se guardan en el atributo de descripción de material que el cliente agrega al elemento.
+ amzn-ddb-env-key: clave de datos codificada en Base64 cifrada por AWS KMS key
+ amzn-ddb-env-alg[: Algoritmo de cifrado, por defecto AES/256](https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines/archived-crypto-projects/aes-development)
+ amzn-ddb-sig-alg[: algoritmo de firma, por defecto, Hmac /256 SHA256](https://en.wikipedia.org/wiki/HMAC)
+ amzn-ddb-wrap-alg: kms
**Procesando**
1. El proveedor de KMS directo envía AWS KMS una solicitud para utilizar lo especificado AWS KMS key a fin de [generar una clave de datos única](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) para el elemento. La operación devuelve una clave de texto no cifrado y una copia que está cifrada con la AWS KMS key. Esto se conoce como el *material de claves inicial*.
La solicitud incluye los siguientes valores en texto no cifrado en [contexto de cifrado de AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context). Estos valores no secretos están vinculados criptográficamente al objeto cifrado, de modo que se requiere el mismo contexto de cifrado para el descifrado. Puede usar estos valores para identificar la llamada AWS KMS en los [AWS CloudTrail registros](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-overview.html).
+ amzn-ddb-env-alg — Algoritmo de cifrado, por defecto AES/256
+ amzn-ddb-sig-alg — Algoritmo de firma, por defecto Hmac /256 SHA256
+ (Opcional) — aws-kms-table *table name*
+ (Opcional) *partition key name* — *partition key value* (los valores binarios están codificados en Base64)
+ (Opcional) *sort key name* — *sort key value* (los valores binarios están codificados en Base64)
El proveedor de Direct KMS obtiene los valores del contexto de AWS KMS cifrado del contexto de cifrado de [DynamoDB del elemento](concepts.md#encryption-context). Si el contexto de cifrado de DynamoDB no incluye un valor, como el nombre de la tabla, ese par nombre-valor se omite del contexto de cifrado. AWS KMS
1. El proveedor de KMS directo deriva una clave de cifrado simétrica y una clave de firma de la clave de datos. De forma predeterminada, utiliza el [algoritmo hash seguro (SHA) 256](https://en.wikipedia.org/wiki/SHA-2) y la [función de derivación de claves RFC5869 basada en HMAC para obtener una clave de cifrado simétrica AES de 256 bits y una clave de firma HMAC-SHA-256](https://tools.ietf.org/html/rfc5869) de 256 bits.
1. El proveedor de KMS directo devuelve la salida al encriptador de elementos.
1. El encriptador de elementos utiliza la clave de cifrado para cifrar los atributos especificados y la clave de firma para firmarlos, utilizando los algoritmos especificados en la descripción de material real. Elimina las claves de texto no cifrado de la memoria lo antes posible.
### Obtener los materiales de descifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de KMS directo cuando recibe una solicitud para materiales de descifrado desde el [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor).
**Entrada** (desde la aplicación)
+ AWS KMS key El ID de clave de un.
El valor del ID de clave puede ser el ID de clave, el ARN de clave, el nombre de alias o el ARN de alias del AWS KMS key. Los valores que no se especifiquen en el ID de clave, como la región, deben estar disponibles en el perfil nombrado [AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles). El ARN de clave proporciona todos los valores que necesita AWS KMS .
**Entrada** (desde el encriptador de elementos)
+ Una copia del [contexto de cifrado de DynamoDB](concepts.md#encryption-context) que contiene el contenido del atributo de descripción de material.
**Salida** (al encriptador de elementos)
+ Clave de cifrado (texto no cifrado)
+ Clave de firma
**Procesando**
1. El proveedor de KMS directo obtiene la clave de datos cifrados desde el atributo de descripción del material en el elemento cifrado.
1. Solicita AWS KMS utilizar la especificada AWS KMS key para [descifrar](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) la clave de datos cifrados. La operación devuelve una clave de texto no cifrado.
Esta solicitud debe usar el mismo [contexto de cifrado de AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) que se utilizó para generar y cifrar la clave de datos.
+ aws-kms-table – *table name*
+ *partition key name*— *partition key value* (los valores binarios están codificados en Base64)
+ (Opcional) *sort key name* — *sort key value* (los valores binarios están codificados en Base64)
+ amzn-ddb-env-alg — Algoritmo de cifrado, por defecto AES/256
+ amzn-ddb-sig-alg — Algoritmo de firma, por defecto Hmac /256 SHA256
1. El proveedor de Direct KMS utiliza el [algoritmo de hash seguro (SHA) 256](https://en.wikipedia.org/wiki/SHA-2) y la [función de derivación de claves RFC5869 basada en el HMAC para obtener una clave](https://tools.ietf.org/html/rfc5869) de cifrado simétrica AES de 256 bits y una clave de firma HMAC-SHA-256 de 256 bits a partir de la clave de datos.
1. El proveedor de KMS directo devuelve la salida al encriptador de elementos.
1. El encriptador de elementos utiliza la clave de firma para verificar el elemento. Si se realiza correctamente, utiliza la clave de cifrado simétrica para descifrar los valores de atributo cifrados. Estas operaciones utilizan los algoritmos de cifrado y firma especificados en la descripción de material real. El encriptador de elementos elimina las claves de texto no cifrado de la memoria lo antes posible.
# Proveedor de materiales encapsulado
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El *proveedor de materiales encapsulado* (CMP encapsulado) le permite utilizar las claves de encapsulación y de firma desde cualquier fuente con el cliente de cifrado de DynamoDB. El Wrapped CMP no depende de ningún AWS servicio. Sin embargo, debe generar y administrar las claves de encapsulación y de firma fuera del cliente, incluida la entrega de las claves correctas para verificar y descifrar el elemento.
El CMP encapsulado genera una clave de cifrado de elemento única para cada elemento. Encapsula la clave de cifrado del elemento con la clave de encapsulación que proporcione y guarda la clave de cifrado de elemento encapsulado en el [atributo de descripción de materiales](DDBEC-legacy-concepts.md#legacy-material-description) del elemento. Dado que suministra las claves de encapsulación y de firma, determina cómo se generan las claves de firma y encapsulación y si son únicas para cada elemento o si se reutilizan.
El CMP encapsulado es una implementación segura y supone una buena opción para aplicaciones que puedan administrar materiales criptográficos.
Wrapped CMP es uno de los varios [proveedores de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) compatibles con el cliente de cifrado de DynamoDB. Para obtener información sobre el otro, consulte. CMPs [Proveedor de materiales criptográficos](crypto-materials-providers.md)
**Para ver código de ejemplo, consulte:**
+ Java: [AsymmetricEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AsymmetricEncryptedItem.java)
+ Python: [wrapped-rsa-encrypted-table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/wrapped_rsa_encrypted_table.py), [wrapped-symmetric-encrypted-table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/wrapped_symmetric_encrypted_table.py)
**Topics**
+ [Modo de uso](#wrapped-cmp-how-to-use)
+ [Funcionamiento](#wrapped-cmp-how-it-works)
## Modo de uso
Para crear un CMP encapsulado, especifique una clave de encapsulación (requerida durante el cifrado), una clave de desencapsulación (requerida durante el descifrado) y una clave de firma. Debe proporcionar las claves al cifrar y descifrar elementos.
Las claves de encapsulación, desencapsulación y firma pueden ser claves simétricas o pares de claves asimétricas.
------
#### [ Java ]
```
// This example uses asymmetric wrapping and signing key pairs
final KeyPair wrappingKeys = ...
final KeyPair signingKeys = ...
final WrappedMaterialsProvider cmp =
new WrappedMaterialsProvider(wrappingKeys.getPublic(),
wrappingKeys.getPrivate(),
signingKeys);
```
------
#### [ Python ]
```
# This example uses symmetric wrapping and signing keys
wrapping_key = ...
signing_key = ...
wrapped_cmp = WrappedCryptographicMaterialsProvider(
wrapping_key=wrapping_key,
unwrapping_key=wrapping_key,
signing_key=signing_key
)
```
------
## Funcionamiento
El CMP encapsulado genera una clave de cifrado de elemento nueva para cada elemento. Utiliza las claves de encapsulación, desencapsulación y firma que proporcione, tal y como se muestra en el siguiente diagrama.
![\[La entrada, el procesamiento y la salida del proveedor de materiales encapsulado en el cliente de cifrado de DynamoDB\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/wrappedCMP.png)
### Obtener los materiales de cifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de materiales encapsulado (CMP encapsulado) cuando recibe una solicitud para materiales de cifrado.
**Entrada** (desde la aplicación)
+ Clave de encapsulación: una clave simétrica [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) o una clave pública [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)). Obligatorio si los valores de atributos están cifrados. De lo contrario, es opcional y se pasa por alto.
+ Clave de desencapsulación: opcional y se pasa por alto.
+ Clave de firma
**Entrada** (desde el encriptador de elementos)
+ [Contexto de cifrado de DynamoDB](concepts.md#encryption-context)
**Salida** (al encriptador de elementos):
+ Clave de cifrado de elemento de texto no cifrado
+ Clave de firma (sin cambios)
+ [Descripción de material real](DDBEC-legacy-concepts.md#legacy-material-description): estos valores se guardan en el [atributo de descripción de material](DDBEC-legacy-concepts.md#legacy-material-description) que el cliente añade al elemento.
+ `amzn-ddb-env-key`: clave de cifrado de elemento encapsulado cifrado en Base64
+ `amzn-ddb-env-alg`: algoritmo de cifrado utilizado para cifrar el elemento. El valor predeterminado es AES-256-CBC.
+ `amzn-ddb-wrap-alg`: el algoritmo de encapsulación que utilizó el CMP encapsulado para encapsular la clave de cifrado del elemento. Si la clave de encapsulación es una clave AES, la clave se encapsula utilizando `AES-Keywrap` no rellenado, tal como se define en [RFC 3394](https://tools.ietf.org/html/rfc3394.html). Si la clave de empaquetado es una clave RSA, la clave se cifra mediante RSA OAEP con relleno. MGF1
**Procesando**
Cuando se cifra un elemento, transfiere una clave de encapsulación y una clave de firma. Una clave de desencapsulación es opcional y se pasa por alto.
1. El CMP encapsulado genera una clave de cifrado de elemento simétrica única para el elemento de tabla.
1. Utiliza la clave de cifrado que especifica para encapsular la clave de cifrado del elemento. A continuación, lo elimina de la memoria lo antes posible.
1. Devuelve la clave de cifrado del elemento con texto no cifrado, la clave de firma que suministró y una [descripción de material real](DDBEC-legacy-concepts.md#legacy-material-description) que incluye la clave de cifrado del elemento encapsulado y los algoritmos de cifrado y encapsulación.
1. El encriptador de elementos utiliza la clave de cifrado de texto no cifrado para cifrar el elemento. Utiliza la clave de firma que suministró para firmar el elemento. A continuación, elimina las claves de texto no cifrado de la memoria lo antes posible. Copia los campos en la descripción de material real, incluida la clave de cifrado encapsulada (`amzn-ddb-env-key`), en el atributo de descripción de material del elemento.
### Obtener los materiales de descifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de materiales encapsulado (CMP encapsulado) cuando recibe una solicitud para materiales de descifrado.
**Entrada** (desde la aplicación)
+ Clave de encapsulación: opcional y se pasa por alto.
+ Clave de encapsulación: la misma clave simétrica [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) o clave privada [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) que corresponde a la clave pública RSA utilizada para cifrar. Obligatorio si los valores de atributos están cifrados. De lo contrario, es opcional y se pasa por alto.
+ Clave de firma
**Entrada** (desde el encriptador de elementos)
+ Una copia del [contexto de cifrado de DynamoDB](concepts.md#encryption-context) que contiene el contenido del atributo de descripción de material.
**Salida** (al encriptador de elementos)
+ Clave de cifrado de elemento de texto no cifrado
+ Clave de firma (sin cambios)
**Procesando**
Cuando se descifra un elemento, transfiere una clave de desencapsulación y una clave de firma. Una clave de encapsulación es opcional y se pasa por alto.
1. El CMP encapsulado obtiene la clave de cifrado del elemento encapsulado desde el atributo de descripción de material del elemento.
1. Utiliza la clave de desencapsulación y el algoritmo para desencapsular la clave de cifrado del elemento.
1. Devuelve la clave de cifrado del elemento con texto no cifrado, la clave de firma y los algoritmos de cifrado y de firma al encriptador de elementos.
1. El encriptador de elementos utiliza la clave de firma para verificar el elemento. Si se realiza correctamente, utiliza la clave de cifrado de elementos para descifrar el elemento. A continuación, elimina las claves de texto no cifrado de la memoria lo antes posible.
# Proveedor más reciente
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El *proveedor más reciente* es un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que está diseñado para funcionar con un [almacén de proveedores](DDBEC-legacy-concepts.md#provider-store). Lo obtiene CMPs de la tienda del proveedor y obtiene los materiales criptográficos que devuelve de CMPs. Normalmente utiliza cada CMP para satisfacer varias solicitudes para materiales criptográficos. Pero puede utilizar las características de su almacén de proveedores para controlar hasta qué punto se reutilizan los materiales, determinar la frecuencia con la que se rota su CMP e, incluso, cambiar el tipo de CMP que utiliza sin cambiar el proveedor más reciente.
**nota**
El código asociado al símbolo `MostRecentProvider` del proveedor más reciente puede almacenar materiales criptográficos en la memoria durante todo el proceso. Podría permitir a la persona que llama usar claves que ya no está autorizada a usar.
El símbolo `MostRecentProvider` está obsoleto en las versiones anteriores compatibles del cliente de cifrado de DynamoDB y se eliminó de la versión 2.0.0. Se sustituye por el símbolo `CachingMostRecentProvider`. Para obtener más información, consulte [Actualizaciones del proveedor más reciente](#mrp-versions).
El proveedor más reciente es una buena opción para aplicaciones que necesitan minimizar las llamadas al almacén de proveedores y su origen criptográfico y para aplicaciones que pueden reutilizar algunos materiales criptográficos sin infringir sus requisitos de seguridad. Por ejemplo, le permite proteger sus materiales criptográficos con un signo [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) sin tener que llamar AWS KMS cada vez que cifra o descifra un elemento.
El almacén de proveedores que elija determinará el tipo CMPs que utilizará el proveedor más reciente y la frecuencia con la que recibirá un nuevo CMP. Puede utilizar cualquier almacén de proveedores compatible con el proveedor más reciente, incluidos los almacenes de proveedor personalizados que diseñe.
El cliente de cifrado de DynamoDB incluye *MetaStore*un que crea y [devuelve proveedores de materiales empaquetados (Wrapped](wrapped-provider.md)). CMPs MetaStore Guarda varias versiones del Wrapped CMPs que genera en una tabla interna de DynamoDB y las protege con un cifrado del lado del cliente mediante una instancia interna del DynamoDB Encryption Client.
Puede configurarlo MetaStore para que utilice cualquier tipo de CMP interno para proteger los materiales de la tabla, incluido un [proveedor de KMS directo](direct-kms-provider.md) que genere materiales criptográficos protegidos por usted AWS KMS key, un CMP empaquetado que utilice las claves de empaquetado y firma que usted suministre o un CMP personalizado compatible que diseñe.
**Para ver código de ejemplo, consulte:**
+ Java: [MostRecentEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/MostRecentEncryptedItem.java)
+ Python: [most\$1recent\$1provider\$1encrypted\$1table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/most_recent_provider_encrypted_table.py)
**Topics**
+ [Modo de uso](#mrp-how-to-use-it)
+ [Funcionamiento](#mrp-how-it-works)
+ [Actualizaciones del proveedor más reciente](#mrp-versions)
## Modo de uso
Para crear un proveedor más reciente, tiene que crear y configurar un almacén de proveedores y, a continuación, crear un proveedor más reciente que utiliza el almacén de proveedores.
[Los siguientes ejemplos muestran cómo crear un proveedor más reciente que utilice MetaStore y proteja las versiones de su tabla interna de DynamoDB con materiales criptográficos de un proveedor de Direct KMS.](direct-kms-provider.md) Estos ejemplos utilizan el símbolo [`CachingMostRecentProvider`](#mrp-versions).
Cada proveedor más reciente tiene un nombre que lo identifica CMPs en la MetaStore tabla, un ajuste [time-to-live](#most-recent-provider-ttl)(TTL) y un ajuste de tamaño de caché que determina el número de entradas que puede contener la caché. En estos ejemplos, se establece el tamaño de la caché en 1000 entradas y un TTL de 60 segundos.
------
#### [ Java ]
```
// Set the name for MetaStore's internal table
final String keyTableName = 'metaStoreTable'
// Set the Region and AWS KMS key
final String region = 'us-west-2'
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
// Set the TTL and cache size
final long ttlInMillis = 60000;
final long cacheSize = 1000;
// Name that identifies the MetaStore's CMPs in the provider store
final String materialName = 'testMRP'
// Create an internal DynamoDB client for the MetaStore
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
// Create an internal Direct KMS Provider for the MetaStore
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider kmsProv = new DirectKmsMaterialProvider(kms, keyArn);
// Create an item encryptor for the MetaStore,
// including the Direct KMS Provider
final DynamoDBEncryptor keyEncryptor = DynamoDBEncryptor.getInstance(kmsProv);
// Create the MetaStore
final MetaStore metaStore = new MetaStore(ddb, keyTableName, keyEncryptor);
//Create the Most Recent Provider
final CachingMostRecentProvider cmp = new CachingMostRecentProvider(metaStore, materialName, ttlInMillis, cacheSize);
```
------
#### [ Python ]
```
# Designate an AWS KMS key
kms_key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
# Set the name for MetaStore's internal table
meta_table_name = 'metaStoreTable'
# Name that identifies the MetaStore's CMPs in the provider store
material_name = 'testMRP'
# Create an internal DynamoDB table resource for the MetaStore
meta_table = boto3.resource('dynamodb').Table(meta_table_name)
# Create an internal Direct KMS Provider for the MetaStore
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
# Create the MetaStore with the Direct KMS Provider
meta_store = MetaStore(
table=meta_table,
materials_provider=kms_cmp
)
# Create a Most Recent Provider using the MetaStore
# Sets the TTL (in seconds) and cache size (# entries)
most_recent_cmp = MostRecentProvider(
provider_store=meta_store,
material_name=material_name,
version_ttl=60.0,
cache_size=1000
)
```
------
## Funcionamiento
El proveedor más reciente se obtiene CMPs de una tienda de proveedores. A continuación, utiliza el CMP para generar los materiales criptográficos que devuelve al encriptador de elementos.
### Acerca del proveedor más reciente
El proveedor más reciente obtiene un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) desde un [almacén de proveedores](DDBEC-legacy-concepts.md#provider-store). A continuación, utiliza el CMP para generar los materiales criptográficos que devuelve. Cada proveedor más reciente está asociado a una tienda de proveedores, pero una tienda de proveedores puede suministrar CMPs a varios proveedores en varios hosts.
El proveedor más reciente puede funcionar con cualquier CMP compatible desde cualquier almacén de proveedores. El encriptador de elementos solicita materiales de cifrado o descifrado al CMP y los devuelve al encriptador de elementos. No realiza ninguna operación criptográfica.
Para solicitar un CMP desde su almacén de proveedores, el proveedor más reciente proporciona su nombre de material y la versión de un CMP existente que desea utilizar. Para los materiales de cifrado, el proveedor más reciente solicita siempre la versión máxima ("más reciente"). Para los materiales de descifrado, solicita la versión del CMP que se utilizó para crear los materiales de cifrado, tal como se muestra en el diagrama siguiente.
![\[Un proveedor más reciente\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/most-recent-provider-1.png)
El proveedor más reciente guarda las versiones de las CMPs que devuelve la tienda del proveedor en una caché local de uso menos reciente (LRU) en la memoria. La memoria caché permite al proveedor más reciente obtener lo que necesita sin tener CMPs que llamar a la tienda del proveedor para comprar cada artículo. Puede borrar la caché bajo demanda.
El proveedor más reciente utiliza un [time-to-livevalor](#most-recent-provider-ttl) configurable que se puede ajustar en función de las características de la aplicación.
### Acerca del MetaStore
Puede utilizar un proveedor más reciente con cualquier almacén de proveedores, incluido un almacén de proveedores personalizado compatible. El cliente de cifrado de DynamoDB incluye MetaStore una implementación segura que se puede configurar y personalizar.
A *MetaStore*es un [almacén proveedor](DDBEC-legacy-concepts.md#provider-store) que crea y devuelve [Wrapped](wrapped-provider.md), CMPs que se configura con la clave de empaquetado, la clave de desempaquetado y la clave de firma que Wrapped requiere. CMPs A MetaStore es una opción segura para los proveedores más recientes, ya que Wrapped CMPs siempre genera claves de cifrado únicas para cada artículo. Solo se reutilizan la clave de encapsulación que protege la clave de cifrado del elemento y las claves de firma.
El siguiente diagrama muestra los componentes del proveedor más reciente MetaStore y cómo interactúa con él.
![\[A MetaStore\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/most-recent-provider-2.png)
MetaStore Genera el Wrapped y CMPs, a continuación, lo almacena (en forma cifrada) en una tabla interna de DynamoDB. La clave de partición es el nombre del material del proveedor más reciente; la clave de clasificación es el número de versión. Los materiales de la tabla están protegidos mediante un cliente de cifrado interno de DynamoDB, incluido un encriptador de elementos y un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) interno.
Puede utilizar cualquier tipo de CMP interno MetaStore, incluido un [proveedor de KMS directo](wrapped-provider.md), un CMP empaquetado con materiales criptográficos que usted proporcione o un CMP personalizado compatible. Si el CMP interno de su empresa MetaStore es un proveedor de Direct KMS, sus claves reutilizables de empaquetado y firma están protegidas con un símbolo in (). [AWS KMS key[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)AWS KMS Las MetaStore llamadas AWS KMS cada vez que agrega una nueva versión de CMP a su tabla interna o obtiene una versión de CMP de su tabla interna.
### Establecer un valor time-to-live
Puede establecer un valor time-to-live (TTL) para cada proveedor más reciente que cree. En general, utilice el valor TTL más bajo que resulte práctico para su aplicación.
El uso del valor de TTL se cambia en el símbolo `CachingMostRecentProvider` del proveedor más reciente.
**nota**
El `MostRecentProvider` símbolo del proveedor más reciente quedó obsoleto en las versiones anteriores compatibles del cliente de cifrado de DynamoDB y se eliminó de la versión 2.0.0. Se sustituye por el símbolo `CachingMostRecentProvider`. Se recomienda que actualice el código lo antes posible. Para obtener más información, consulte [Actualizaciones del proveedor más reciente](#mrp-versions).
**`CachingMostRecentProvider`**
El `CachingMostRecentProvider` utiliza el valor de TTL de dos maneras diferentes.
+ El TTL determina la frecuencia con la que el proveedor más reciente busca en la tienda del proveedor una nueva versión del CMP. Si hay una nueva versión disponible, el proveedor más reciente reemplaza su CMP y actualiza sus materiales criptográficos. De lo contrario, seguirá utilizando su CMP y sus materiales criptográficos actuales.
+ El TTL determina cuánto tiempo se puede usar CMPs en la memoria caché. Antes de utilizar un CMP almacenado en caché para el cifrado, el proveedor más reciente evalúa el tiempo que permanece en la memoria caché. Si el tiempo de caché de un CMP supera el TTL, el CMP se expulsa de la memoria caché y el proveedor más reciente obtiene una nueva versión del CMP de la última versión de la tienda de su proveedor.
**`MostRecentProvider`**
En el `MostRecentProvider`, el TTL determina la frecuencia con la que el proveedor más reciente busca en la tienda del proveedor una nueva versión del CMP. Si hay una nueva versión disponible, el proveedor más reciente reemplaza su CMP y actualiza sus materiales criptográficos. De lo contrario, seguirá utilizando su CMP y sus materiales criptográficos actuales.
El TTL no determina la frecuencia con la que se crea una nueva versión del CMP. Las nuevas versiones de CMP se crean [rotando los materiales criptográficos](#most-recent-provider-rotate).
Un valor de TTL ideal varía según la aplicación y sus objetivos de latencia y disponibilidad. Un TTL menor mejora el perfil de seguridad al reducir el tiempo que los materiales criptográficos se almacenan en la memoria. Además, un TTL menor actualiza la información crítica con más frecuencia. Por ejemplo, si su CMP interno es un [proveedor de KMS directo](direct-kms-provider.md), verificará con más frecuencia que la persona que llama siga estando autorizada a utilizar un AWS KMS key.
Sin embargo, si el TTL es demasiado breve, las llamadas frecuentes a la tienda del proveedor pueden aumentar los costos y hacer que la tienda del proveedor limite las solicitudes de su aplicación y de otras aplicaciones que comparten su cuenta de servicio. También podría resultarle útil coordinar el TTL con la velocidad de rotación de los materiales criptográficos.
Durante las pruebas, varíe el TTL y el tamaño de la caché según las distintas cargas de trabajo hasta que encuentre una configuración que se adapte a su aplicación y a sus estándares de seguridad y rendimiento.
### Rotación de materiales criptográficos
Cuando un proveedor más reciente necesita materiales de cifrado, siempre utiliza la versión más reciente que conozca de su CMP. La frecuencia con la que comprueba si hay una versión más reciente viene determinada por el valor [time-to-live](#most-recent-provider-ttl)(TTL) que se establece al configurar el proveedor más reciente.
Cuando el TTL caduca, el proveedor más reciente busca en la tienda del proveedor una versión más reciente del CMP. Si hay alguna disponible, el proveedor más reciente la obtiene y reemplaza el CMP en su caché. Utiliza este CMP y sus materiales criptográficos hasta que descubre que la tienda del proveedor tiene una versión más reciente.
Para indicarle al almacén de proveedores que cree una nueva versión de un CMP para un proveedor más reciente, llame a la operación Crear nuevo proveedor del almacén de proveedores con el nombre del material del proveedor más reciente. El almacén de proveedores crea un nuevo CMP y guarda una copia cifrada en su almacén interno con un número de versión mayor. (También devuelve un CMP, pero puede descartarlo). Como resultado, la próxima vez que el proveedor más reciente consulte el número máximo de versión de su almacén de proveedores CMPs, obtendrá el nuevo número de versión superior y lo utilizará en las siguientes solicitudes al almacén para comprobar si se ha creado una nueva versión del CMP.
Puede programar sus llamadas a Crear nuevo proveedor en función de la hora, del número de elementos o de los atributos procesados o de cualquier otra métrica que tenga sentido para su aplicación.
### Obtener los materiales de cifrado
El proveedor más reciente utiliza el siguiente proceso, mostrado en este diagrama, para obtener los materiales de cifrado que devuelve al encriptador de elementos. La salida depende del tipo de CMP que el almacén de proveedores devuelve. El proveedor más reciente puede usar cualquier almacén de proveedores compatible, incluido el MetaStore que se incluye en el cliente de cifrado de DynamoDB.
![\[Entrada, procesamiento y salida del proveedor más reciente en el cliente de cifrado de DynamoDB\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/most-recent-provider-provider-store.png)
Al crear un proveedor más reciente con el [`CachingMostRecentProvider`símbolo](#mrp-versions), se especifica un almacén de proveedores, un nombre para el proveedor más reciente y un valor [time-to-live](#most-recent-provider-ttl)(TTL). Si lo desea, también puede especificar un tamaño de caché, que determina la cantidad máxima de materiales criptográficos que pueden existir en la caché.
Cuando el encriptador de elementos solicita al proveedor más reciente materiales de cifrado, el proveedor más reciente empieza buscando en su caché la versión más reciente de su CMP.
+ Si encuentra el CMP con la versión más reciente en su caché y el CMP no ha excedido el valor de TTL, el proveedor más reciente utiliza el CMP para generar materiales de cifrado. A continuación, devuelve los materiales de cifrado al encriptador de elementos. Esta operación no requiere una llamada al almacén de proveedores.
+ Si la última versión del CMP no está en su caché, o si está en la caché, pero excedió su valor de TTL, el proveedor más reciente solicita un CMP desde su almacén de proveedores. La solicitud incluye el nombre del material del proveedor más reciente y el número de versión máximo que conoce.
1. El almacén de proveedores devuelve un CMP desde su almacenamiento persistente. Si el almacén del proveedor es un MetaStore, obtiene un CMP empaquetado cifrado de su tabla interna de DynamoDB utilizando el nombre del material del proveedor más reciente como clave de partición y el número de versión como clave de clasificación. MetaStore Utiliza su cifrador de elementos interno y su CMP interno para descifrar el CMP empaquetado. A continuación, devuelve el CMP de texto no cifrado al proveedor más reciente. Si el CMP interno es un [proveedor de KMS directo](direct-kms-provider.md), este paso incluye una llamada al [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS).
1. El CMP agrega el campo `amzn-ddb-meta-id` a la [descripción de material real](DDBEC-legacy-concepts.md#legacy-material-description). Su valor es el nombre de material y la versión del CMP en su tabla interna. El almacén del proveedor devuelve el CMP al proveedor más reciente.
1. El proveedor más reciente almacena en la memoria caché el CMP.
1. El proveedor más reciente utiliza el CMP para generar materiales de cifrado. A continuación, devuelve los materiales de cifrado al encriptador de elementos.
### Obtener los materiales de descifrado
Cuando el encriptador de elementos solicita al proveedor más reciente los materiales de descifrado, el proveedor más reciente utiliza el proceso siguiente para obtenerlos y devolverlos.
1. El proveedor más reciente solicita al almacén de proveedores el número de la versión de los materiales criptográficos que se utilizaron para cifrar el elemento. Transfiere la descripción de material real desde el [atributo de descripción de material](DDBEC-legacy-concepts.md#legacy-material-description) del elemento.
1. El almacén de proveedores obtiene el número de versión de CMP de cifrado desde el campo `amzn-ddb-meta-id` en la descripción de material real y lo devuelve al proveedor más reciente.
1. El proveedor más reciente busca en la caché la versión del CMP que se utilizó para cifrar y firmar el elemento.
+ Si encuentra que la versión coincidente del CMP está en su caché y que el CMP no ha superado el [valor time-to-live (TTL)](#most-recent-provider-ttl), el proveedor más reciente utiliza el CMP para generar materiales de descifrado. A continuación, devuelve los materiales de descifrado al encriptador de elementos. Esta operación no requiere una llamada al almacén de proveedores o cualquier otro CMP.
+ Si la versión coincidente del CMP no está en su caché, o si la caché AWS KMS key excedió su valor de TTL, el proveedor más reciente solicita un CMP desde su almacén de proveedores. Envía el nombre del material y el número de versión de CMP de cifrado en la solicitud.
1. El almacén de proveedores busca su almacenamiento persistente para el CMP utilizando el nombre del proveedor más reciente como clave de partición y el número de la versión como la clave de clasificación.
+ Si el nombre y el número de versión no están en su almacenamiento persistente, el almacén de proveedores genera una excepción. Si el almacén de proveedores se utilizó para generar el CMP, el CMP se debería almacenar en su almacenamiento persistente, a menos que se haya eliminado de forma intencionada.
+ Si el CMP con el nombre y número de versión coincidentes están en el almacenamiento persistente del almacén de proveedores, este devuelve el CMP especificado al proveedor más reciente.
Si el almacén del proveedor es un MetaStore, obtiene el CMP cifrado de su tabla de DynamoDB. A continuación, utiliza materiales criptográficos desde su CMP interno para descifrar el CMP cifrado antes de devolver el CMP al proveedor más reciente. Si el CMP interno es un [proveedor de KMS directo](direct-kms-provider.md), este paso incluye una llamada al [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS).
1. El proveedor más reciente almacena en la memoria caché el CMP.
1. El proveedor más reciente utiliza el CMP para generar materiales de descifrado. A continuación, devuelve los materiales de descifrado al encriptador de elementos.
## Actualizaciones del proveedor más reciente
El símbolo del proveedor más reciente cambia de `MostRecentProvider` a `CachingMostRecentProvider`.
**nota**
El símbolo `MostRecentProvider`, que representa al proveedor más reciente, está obsoleto en la versión 1.15 del cliente de cifrado de DynamoDB para Java y en la versión 1.3 del cliente de cifrado de DynamoDB para Python, y se eliminó de las versiones 2.0.0 del cliente de cifrado de DynamoDB en las implementaciones de ambos lenguajes. En su lugar, utilice el `CachingMostRecentProvider`.
El `CachingMostRecentProvider` implementa los siguientes cambios:
+ Elimina `CachingMostRecentProvider` periódicamente los materiales criptográficos de la memoria cuando su tiempo en la memoria supera el valor configurado [time-to-live (](#most-recent-provider-ttl)TTL).
Es posible que `MostRecentProvider` almacene materiales criptográficos en la memoria durante el tiempo de vida del proceso. Como resultado, es posible que el proveedor más reciente no esté al tanto de los cambios de autorización. Es posible que utilice claves de cifrado una vez revocados los permisos de uso de la persona que llama.
Si no puede actualizar a esta nueva versión, puede obtener un efecto similar si llama periódicamente al `clear()` método de la memoria caché. Este método vacía manualmente el contenido de la caché y requiere que el proveedor más reciente solicite un nuevo CMP y nuevos materiales criptográficos.
+ El `CachingMostRecentProvider` también incluye una configuración de tamaño de la caché que le da más control sobre la caché.
Para actualizar el `CachingMostRecentProvider`, debe cambiar el nombre del símbolo en el código. En todos los demás aspectos, el `CachingMostRecentProvider` es totalmente compatible con versiones anteriores del `MostRecentProvider`. No es necesario volver a cifrar ningún elemento de la mesa.
Sin embargo, el `CachingMostRecentProvider` genera más llamadas a la infraestructura clave subyacente. Llama a la tienda del proveedor al menos una vez en cada intervalo time-to-live (TTL). Las aplicaciones con numerosas flotas activas CMPs (debido a la rotación frecuente) o las aplicaciones con grandes flotas son las más propensas a ser sensibles a este cambio.
Antes de publicar el código actualizado, pruébelo minuciosamente para asegurarse de que las llamadas más frecuentes no perjudiquen a la aplicación ni provoquen una limitación por parte de los servicios de los que depende su proveedor, como AWS Key Management Service (AWS KMS) o Amazon DynamoDB. Para mitigar cualquier problema de rendimiento, ajuste el tamaño de la caché y el tamaño time-to-live de la memoria caché en `CachingMostRecentProvider` función de las características de rendimiento que observe. Para obtener instrucciones, consulte [Establecer un valor time-to-live](#most-recent-provider-ttl).
# Proveedor de materiales estático
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El *proveedor de materiales estáticos* (Static CMP) es un [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) muy simple que está diseñado para pruebas, proof-of-concept demostraciones y compatibilidad con sistemas anteriores.
Para utilizar el CMP estático para cifrar un elemento de tabla, proporcione una clave de cifrado simétrica con [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) y una clave o un par de claves de firma. Debe proporcionar las mismas claves para descifrar el elemento cifrado. El CMP estático no realiza ninguna operación criptográfica. En lugar de ello, transfiere las claves de cifrado que suministra al encriptador de elementos sin cambios. El encriptador de elementos cifra los elementos directamente bajo la clave de cifrado. A continuación, utiliza la clave de cifrado directamente para firmarlos.
Dado que el CMP estático no genera ningún material criptográfico único, todos los elementos de tabla que procesa están cifrados con la misma clave de cifrado y están firmados por la misma clave de firma. Cuando se utiliza la misma clave para cifrar los valores de atributos en muchos elementos o se utiliza la misma clave o par de claves para firmar todos los elementos, se arriesga a exceder los límites criptográficos de las claves.
**nota**
El [Proveedor estático asimétrico](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/AsymmetricStaticProvider.html) de la biblioteca de Java no es un proveedor estático. Solo suministra constructores alternativos para el [CMP encapsulado](wrapped-provider.md). Es seguro para uso de producción, pero se debe utilizar directamente el CMP encapsulado siempre que sea posible.
El CMP estático es uno de los varios [proveedores de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) compatibles con el cliente de cifrado de DynamoDB. Para obtener información sobre el otro, consulte. CMPs [Proveedor de materiales criptográficos](crypto-materials-providers.md)
**Para ver código de ejemplo, consulte:**
+ Java: [SymmetricEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/SymmetricEncryptedItem.java)
**Topics**
+ [Modo de uso](#static-cmp-how-to-use)
+ [Funcionamiento](#static-cmp-how-it-works)
## Modo de uso
Para crear un proveedor estático, suministre una clave un par de claves de cifrado o y una clave o par de claves de firma. Tiene que proporcionar material de claves para cifrar y descifrar elementos de tabla.
------
#### [ Java ]
```
// To encrypt
SecretKey cek = ...; // Encryption key
SecretKey macKey = ...; // Signing key
EncryptionMaterialsProvider provider = new SymmetricStaticProvider(cek, macKey);
// To decrypt
SecretKey cek = ...; // Encryption key
SecretKey macKey = ...; // Verification key
EncryptionMaterialsProvider provider = new SymmetricStaticProvider(cek, macKey);
```
------
#### [ Python ]
```
# You can provide encryption materials, decryption materials, or both
encrypt_keys = EncryptionMaterials(
encryption_key = ...,
signing_key = ...
)
decrypt_keys = DecryptionMaterials(
decryption_key = ...,
verification_key = ...
)
static_cmp = StaticCryptographicMaterialsProvider(
encryption_materials=encrypt_keys
decryption_materials=decrypt_keys
)
```
------
## Funcionamiento
El proveedor estático transfiere las claves de cifrado y de firma que suministre al encriptador de elementos, donde se utilizan directamente para cifrar y firmar los elementos de tabla. A menos que suministre distintas claves para cada elemento, se utilizan las mismas claves para todos ellos.
![\[La entrada, el procesamiento y la salida del proveedor de materiales estático en el cliente de cifrado de DynamoDB\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/staticCMP.png)
### Obtener los materiales de cifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de materiales estático (CMP estático) cuando recibe una solicitud para materiales de cifrado.
**Entrada** (desde la aplicación)
+ Una clave de cifrado: esta debe ser una clave simétrica, como una clave del [estándar de cifrado avanzado](https://tools.ietf.org/html/rfc3394.html) (AES).
+ Una clave de firma: esta puede ser una clave simétrica o un par de claves asimétricas.
**Entrada** (desde el encriptador de elementos)
+ [Contexto de cifrado de DynamoDB](concepts.md#encryption-context)
**Salida** (al encriptador de elementos)
+ La clave de cifrado transferida como entrada.
+ La clave de firma transferida como entrada.
+ Descripción de material real: la [descripción de material solicitada](DDBEC-legacy-concepts.md#legacy-material-description), si la hay, sin cambios.
### Obtener los materiales de descifrado
En esta sección se describen en detalle las entradas, las salidas y el procesamiento del proveedor de materiales estático (CMP estático) cuando recibe una solicitud para materiales de descifrado.
Aunque incluye métodos independientes para obtener materiales de cifrado y obtener materiales de descifrado, el comportamiento es el mismo.
**Entrada** (desde la aplicación)
+ Una clave de cifrado: esta debe ser una clave simétrica, como una clave del [estándar de cifrado avanzado](https://tools.ietf.org/html/rfc3394.html) (AES).
+ Una clave de firma: esta puede ser una clave simétrica o un par de claves asimétricas.
**Entrada** (desde el encriptador de elementos)
+ [Contexto de cifrado de DynamoDB](concepts.md#encryption-context) (no utilizado)
**Salida** (al encriptador de elementos)
+ La clave de cifrado transferida como entrada.
+ La clave de firma transferida como entrada.
# Lenguajes de programación disponibles para el Cliente de encriptación de Amazon DynamoDB
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
El Cliente de encriptación de Amazon DynamoDB está disponible para los siguientes lenguajes de programación. Las bibliotecas específicas de lenguaje varían, pero las implementaciones resultantes son interoperables. Por ejemplo, puede cifrar (y firmar) un elemento con el cliente Java y descifrar el elemento con el cliente Python.
Para obtener más información, consulte el tema correspondiente.
**Topics**
+ [Java](java.md)
+ [Python](python.md)
# Cliente de encriptación de Amazon DynamoDB para Java
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En este tema, se explica cómo instalar y utilizar el Cliente de encriptación de Amazon DynamoDB para Java. Para obtener más información sobre la programación con el cliente de cifrado de DynamoDB, consulte [los ejemplos de Java](java-examples.md), [los ejemplos del](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) repositorio GitHub y aws-dynamodb-encryption-java el Javadoc [del](https://aws.github.io/aws-dynamodb-encryption-java/) cliente de cifrado de DynamoDB.
**nota**
Versiones 1. *x*. *x* del cliente de cifrado de DynamoDB para Java entrarán [end-of-support en](what-is-database-encryption-sdk.md#support) fase a partir de julio de 2022. Actualice a una versión más reciente tan pronto como sea posible.
**Topics**
+ [Requisitos previos](#java-prerequisites)
+ [Instalación](#java-installation)
+ [Uso del cliente de cifrado de DynamoDB para Java](java-using.md)
+ [Ejemplos de Java](java-examples.md)
## Requisitos previos
Antes de instalar el Cliente de encriptación de Amazon DynamoDB para Java, asegúrese de que cumple los siguientes requisitos previos.
**Un entorno de desarrollo de Java**
Necesitará Java 8 o una versión posterior. En el sitio web de Oracle, vaya a la página de [descargas de Java SE](https://www.oracle.com/java/technologies/downloads/) y, a continuación, descargue e instale el Java SE Development Kit (JDK).
Si utiliza el JDK de Oracle, también debe descargar e instalar los [archivos de políticas de jurisdicción de seguridad ilimitada de la extensión de criptografía de Java (JCE)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).
**AWS SDK para Java**
El cliente de cifrado de DynamoDB requiere el módulo DynamoDB incluso si la aplicación no interactúa con DynamoDB. AWS SDK para Java Puede instalar todo el SDK o solo este módulo. Si utiliza Maven, añada `aws-java-sdk-dynamodb` al archivo `pom.xml`.
Para obtener más información sobre la instalación y configuración del, consulte. AWS SDK para Java[AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/getting-started.html)
## Instalación
Puede instalar el Cliente de encriptación de Amazon DynamoDB para Java de las siguientes maneras.
**Manualmente**
Para instalar el cliente de cifrado Amazon DynamoDB para Java, clone o descargue el repositorio. [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/) GitHub
**Con Apache Maven**
El Cliente de encriptación de Amazon DynamoDB para Java está disponible en [Apache Maven](https://maven.apache.org/) con la siguiente definición de dependencias.
```
com.amazonaws
aws-dynamodb-encryption-java
version-number
```
Tras instalar el SDK, comience consultando el código de ejemplo de esta guía y el Javadoc del cliente de [cifrado de DynamoDB](https://aws.github.io/aws-dynamodb-encryption-java/). GitHub
# Uso del cliente de cifrado de DynamoDB para Java
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En este tema, se explican algunas de las características del cliente de cifrado de DynamoDB en Java que podrían no encontrarse en otras implementaciones de lenguaje de programación.
[Para obtener más información sobre la programación con el cliente de cifrado de DynamoDB, consulte [los ejemplos de Java, los](java-examples.md) ejemplos de GitHub on y [el](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) Javadoc `aws-dynamodb-encryption-java repository` del cliente de cifrado de DynamoDB.](https://aws.github.io/aws-dynamodb-encryption-java/)
**Topics**
+ [Encriptadores de elementos](#attribute-encryptor)
+ [Configuración del comportamiento de almacenamiento](#save-behavior)
+ [Acciones de atributo en Java](#attribute-actions-java)
+ [Reemplazar nombres de tabla](#override-table-name)
## Encriptadores de elementos: y Dynamo AttributeEncryptor DBEncryptor
[El cliente de cifrado de DynamoDB en Java tiene [dos cifradores de elementos](DDBEC-legacy-concepts.md#item-encryptor): el Dynamo de nivel inferior y el. DBEncryptor [AttributeEncryptor](#attribute-encryptor)](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html)
`AttributeEncryptor`Es una clase auxiliar que le ayuda a usar [Dynamo](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html) AWS SDK para Java con DBMapper el cliente de cifrado `DynamoDB Encryptor` de DynamoDB. Cuando utiliza el `AttributeEncryptor` con el `DynamoDBMapper`, cifra y firma de forma transparente los elementos cuando los guarda. También verifica y descifra de forma transparente los elementos al cargarlos.
## Configuración del comportamiento de almacenamiento
Puede usar el `AttributeEncryptor` y `DynamoDBMapper` para agregar o editar elementos de la tabla con atributos que solo están firmados o que están cifrados y firmados. Para estas tareas, recomendamos que lo configure para que use el comportamiento de guardado `PUT`, tal como se muestra en el siguiente ejemplo. De lo contrario, es posible que no pueda descifrar los datos.
```
DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```
Si utiliza el comportamiento de almacenamiento predeterminado, que actualiza los atributos en el elemento de la tabla, solo se incluyen en la firma atributos que se hayan cambiado. Como resultado, en las lecturas posteriores de todos los atributos, la firma no se validará, porque no incluye los atributos no modelados.
También puede utilizar el comportamiento de guardado `CLOBBER`. Este comportamiento es idéntico al comportamiento de guardado `PUT`, pero deshabilita el bloqueo positivo y sobrescribe el elemento en la tabla.
Para evitar errores de firma, el cliente de cifrado de DynamoDB lanza una excepción de tiempo de ejecución si se utiliza un `AttributeEncryptor` con un `DynamoDBMapper` que no está configurado con un comportamiento seguro de `CLOBBER` o `PUT`.
Para ver este código utilizado en un ejemplo, consulte [Uso del Dynamo DBMapper](java-examples.md#java-example-dynamodb-mapper) y el ejemplo de [AwsKmsEncryptedObject.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java) en el repositorio de. `aws-dynamodb-encryption-java` GitHub
## Acciones de atributo en Java
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) determinan qué valores de atributo se cifran y se firman, cuáles solo se firman y cuáles se omiten. [El método que utilice para especificar las acciones de los atributos depende de si utiliza el Dynamo de nivel inferior o el `DynamoDBMapper` Dynamo de nivel inferior. `AttributeEncryptor` DBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html)
**importante**
Después de utilizar las acciones de atributo para cifrar los elementos de la tabla, agregar o quitar atributos del modelo de datos puede provocar un error de validación de firma que le impide descifrar los datos. Para ver una explicación detallada, consulte [Cambiar el modelo de datos](data-model.md).
### Acciones de atributos para el Dynamo DBMapper
Cuando utilice `DynamoDBMapper` y `AttributeEncryptor`, utilice anotaciones para especificar las acciones de atributos. El cliente de cifrado de DynamoDB utiliza las [anotaciones de atributo estándar](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Annotations.html) que definen el tipo de atributo para determinar cómo proteger un atributo. De forma predeterminada, todos los atributos están cifrados y firmados, excepto las claves principales, que están firmadas, pero no cifradas.
**nota**
No cifre el valor de los atributos con la [anotación @Dynamo DBVersion Attribute](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptimisticLocking.html), aunque puede (y debe) firmarlos. De lo contrario, las condiciones que utilizan su valor tendrán efectos no previstos.
```
// Attributes are encrypted and signed
@DynamoDBAttribute(attributeName="Description")
// Partition keys are signed but not encrypted
@DynamoDBHashKey(attributeName="Title")
// Sort keys are signed but not encrypted
@DynamoDBRangeKey(attributeName="Author")
```
Para especificar las excepciones, utilice las anotaciones de cifrado que se definen en el cliente de cifrado de DynamoDB para Java. Si las especifica en el nivel de clase, se convierten en el valor predeterminado para la clase.
```
// Sign only
@DoNotEncrypt
// Do nothing; not encrypted or signed
@DoNotTouch
```
Por ejemplo, estas anotaciones firman pero no cifran el atributo `PublicationYear` y no cifran o firman el valor del atributo `ISBN`.
```
// Sign only (override the default)
@DoNotEncrypt
@DynamoDBAttribute(attributeName="PublicationYear")
// Do nothing (override the default)
@DoNotTouch
@DynamoDBAttribute(attributeName="ISBN")
```
### Acciones de atributos para el Dynamo DBEncryptor
Para especificar las acciones de los atributos cuando utilice la [Dinamo DBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) directamente, cree un `HashMap` objeto en el que los pares nombre-valor representen los nombres de los atributos y las acciones especificadas.
Los valores válidos para las acciones de atributo que se definen en el tipo enumerado `EncryptionFlags`. Puede utilizar `ENCRYPT` y `SIGN` juntos, usar `SIGN` solo u omitir ambos. Sin embargo, si usa `ENCRYPT` solo, el cliente de cifrado de DynamoDB generará un error. No puede cifrar un atributo que no firme.
```
ENCRYPT
SIGN
```
**aviso**
No cifre los atributos de clave principal. Deben permanecer en texto no cifrado para que DynamoDB pueda encontrar el elemento sin realizar un examen completo de la tabla.
Si especifica una clave principal en el contexto de cifrado y, a continuación, especifica `ENCRYPT` en la acción de atributo para alguno de los atributos de clave principal, el cliente de cifrado de DynamoDB genera una excepción.
Por ejemplo, el siguiente código Java crea un código `actions` HashMap que cifra y firma todos los atributos del elemento. `record` Las excepciones son la clave de partición y los atributos de clave de clasificación, que se firman pero no se cifran, y el atributo `test`, que ni se signa ni se cifra.
```
final EnumSet signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> actions = new HashMap<>();
for (final String attributeName : record.keySet()) {
switch (attributeName) {
case partitionKeyName: // no break; falls through to next case
case sortKeyName:
// Partition and sort keys must not be encrypted, but should be signed
actions.put(attributeName, signOnly);
break;
case "test":
// Don't encrypt or sign
break;
default:
// Encrypt and sign everything else
actions.put(attributeName, encryptAndSign);
break;
}
}
```
A continuación, cuando llama al método [encryptRecord](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html#encryptRecord-java.util.Map-java.util.Map-com.amazonaws.services.dynamodbv2.datamodeling.encryption.EncryptionContext-) del `DynamoDBEncryptor`, especifique el mapa como el valor del parámetro `attributeFlags`. Por ejemplo, esta llamada a `encryptRecord` utiliza el mapa `actions`.
```
// Encrypt the plaintext record
final Map encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```
## Reemplazar nombres de tabla
En el cliente de cifrado de DynamoDB, el nombre de la tabla de DynamoDB es un elemento del [contexto de cifrado de DynamoDB](concepts.md#encryption-context) que se pasa a los métodos de cifrado y descifrado. Al cifrar o firmar elementos de la tabla, el contexto de cifrado de DynamoDB, incluido el nombre de la tabla, está enlazado criptográficamente al texto cifrado. Si el contexto de cifrado de DynamoDB que se pasa al método de descifrado no coincide con el contexto de cifrado de DynamoDB que se pasó al método de cifrado, se produce un error en la operación de descifrado.
En ocasiones, el nombre de una tabla cambia, por ejemplo, cuando se hace una copia de seguridad de una tabla o se realiza una [point-in-time recuperación](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html). Al descifrar o verificar la firma de estos elementos, debe pasar el mismo contexto de cifrado de DynamoDB que se utilizó para cifrar y firmar los elementos, incluido el nombre de la tabla original. El nombre de la tabla actual no es necesario.
Cuando se utiliza `DynamoDBEncryptor`, se ensambla el contexto de cifrado de DynamoDB manualmente. Sin embargo, si está utilizando `DynamoDBMapper`, el `AttributeEncryptor` crea el contexto de cifrado de DynamoDB para usted, incluido el nombre de la tabla actual. Para indicar a `AttributeEncryptor` que cree un contexto de cifrado con un nombre de tabla diferente, utilice el `EncryptionContextOverrideOperator`.
Por ejemplo, el código siguiente crea instancias del proveedor de materiales criptográficos (CMP) y el `DynamoDBEncryptor`. Luego llama al método `setEncryptionContextOverrideOperator` de `DynamoDBEncryptor`. Utiliza el operador `overrideEncryptionContextTableName`, que anula un nombre de tabla. Cuando se configura de esta manera, el `AttributeEncryptor` crea un contexto de cifrado de DynamoDB que incluye `newTableName` en lugar de `oldTableName`. Para ver un ejemplo completo, consulte [EncryptionContextOverridesWithDynamoDBMapper.java.](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/EncryptionContextOverridesWithDynamoDBMapper.java)
```
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
encryptor.setEncryptionContextOverrideOperator(EncryptionContextOperators.overrideEncryptionContextTableName(
oldTableName, newTableName));
```
Cuando se llama al método de carga de `DynamoDBMapper`, que descifra y verifica el elemento, se especifica el nombre de la tabla original.
```
mapper.load(itemClass, DynamoDBMapperConfig.builder()
.withTableNameOverride(DynamoDBMapperConfig.TableNameOverride.withTableNameReplacement(oldTableName))
.build());
```
También puede utilizar el operador `overrideEncryptionContextTableNameUsingMap`, que anula varios nombres de tabla.
Normalmente los operadores de reemplazo de nombres de tabla se utilizan al descifrar datos y verificar firmas. Sin embargo, puede usarlos para establecer el nombre de la tabla en el contexto de cifrado de DynamoDB en un valor diferente al cifrar y firmar.
No utilice los operadores de anulación de nombre de tabla si está utilizando `DynamoDBEncryptor`. En su lugar, cree un contexto de cifrado con el nombre de la tabla original y envíelo al método de descifrado.
# Ejemplo de código para el cliente de cifrado de DynamoDB para Java
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
Los siguientes ejemplos muestran cómo utilizar el cliente de cifrado de DynamoDB para Java para proteger los elementos de tabla de DynamoDB en su aplicación. Puedes encontrar más ejemplos (y aportar los tuyos) en el directorio de [ejemplos](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) del [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/)repositorio en GitHub.
**Topics**
+ [¿Usando el Dynamo DBEncryptor](#java-example-ddb-encryptor)
+ [Uso del Dynamo DBMapper](#java-example-dynamodb-mapper)
## ¿Usando el Dynamo DBEncryptor
En este ejemplo, se muestra cómo utilizar el [Dynamo](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) de nivel inferior DBEncryptor con el proveedor de [Direct](direct-kms-provider.md) KMS. El proveedor de KMS directo genera y protege sus materiales criptográficos con un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in AWS Key Management Service (AWS KMS) que usted especifique.
Puede usar cualquier [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) compatible con`DynamoDBEncryptor`, y puede usar el proveedor de Direct KMS con y. `DynamoDBMapper` [AttributeEncryptor](java-using.md#attribute-encryptor)
**[Consulte el ejemplo de código completo: .java AwsKmsEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedItem.java)**
Paso 1: crear el proveedor de KMS directo
Cree una instancia del AWS KMS cliente con la región especificada. A continuación, utilice la instancia de cliente para crear una instancia del proveedor de KMS directo con su AWS KMS key preferido.
En este ejemplo, se utiliza el nombre de recurso de Amazon (ARN) para identificar el AWS KMS key, pero se puede utilizar [cualquier identificador clave válido](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn).
```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```
Paso 2: crear un elemento
En este ejemplo se define un elemento `record` HashMap que representa un ejemplo de una tabla.
```
final String partitionKeyName = "partition_attribute";
final String sortKeyName = "sort_attribute";
final Map record = new HashMap<>();
record.put(partitionKeyName, new AttributeValue().withS("value1"));
record.put(sortKeyName, new AttributeValue().withN("55"));
record.put("example", new AttributeValue().withS("data"));
record.put("numbers", new AttributeValue().withN("99"));
record.put("binary", new AttributeValue().withB(ByteBuffer.wrap(new byte[]{0x00, 0x01, 0x02})));
record.put("test", new AttributeValue().withS("test-value"));
```
Paso 3: Crear una dinamo DBEncryptor
Cree una instancia del `DynamoDBEncryptor` con el proveedor de KMS directo.
```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
```
Paso 4: crear un contexto de cifrado de DynamoDB
El [contexto de cifrado de DynamoDB](concepts.md#encryption-context) contiene información acerca de la estructura de la tabla y cómo se cifra y se firma. Si utiliza el `DynamoDBMapper`, el `AttributeEncryptor` crea el contexto de cifrado automáticamente.
```
final String tableName = "testTable";
final EncryptionContext encryptionContext = new EncryptionContext.Builder()
.withTableName(tableName)
.withHashKeyName(partitionKeyName)
.withRangeKeyName(sortKeyName)
.build();
```
Paso 5: crear el objeto de acciones de atributo
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) determinan qué atributos del elemento se cifran y se firman, cuáles solo se firman y cuáles no se cifran o firman.
En Java, para especificar las acciones de los atributos, se crea un par HashMap de pares de nombre y `EncryptionFlags` valor del atributo.
Por ejemplo, el siguiente código de Java crea un código `actions` HashMap que cifra y firma todos los atributos `record` del elemento, excepto los atributos de la clave de partición y la clave de clasificación, que están firmados, pero no cifrados, y el `test` atributo, que no está firmado ni cifrado.
```
final EnumSet signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> actions = new HashMap<>();
for (final String attributeName : record.keySet()) {
switch (attributeName) {
case partitionKeyName: // fall through to the next case
case sortKeyName:
// Partition and sort keys must not be encrypted, but should be signed
actions.put(attributeName, signOnly);
break;
case "test":
// Neither encrypted nor signed
break;
default:
// Encrypt and sign all other attributes
actions.put(attributeName, encryptAndSign);
break;
}
}
```
Paso 6: cifrar y firmar el elemento
Para cifrar y firmar el elemento de tabla, llame al método `encryptRecord` en la instancia del `DynamoDBEncryptor`. Especifique el elemento de tabla (`record`), las acciones de atributo (`actions`) y el contexto de cifrado (`encryptionContext`).
```
final Map encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```
Paso 7: colocar el elemento en la tabla de DynamoDB
Finalmente, coloque el elemento cifrado y firmado en la tabla de DynamoDB.
```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ddb.putItem(tableName, encrypted_record);
```
## Uso del Dynamo DBMapper
El ejemplo siguiente le muestra cómo utilizar la clase auxiliar del DynamoDB Mapper con el [Proveedor de KMS directo](direct-kms-provider.md). El proveedor de KMS directo genera y protege sus materiales criptográficos con un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) en AWS Key Management Service (AWS KMS) que usted especifique.
Puede utilizar cualquier [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) compatible con el `DynamoDBMapper` y puede utilizar el proveedor de KMS directo con el `DynamoDBEncryptor` de nivel inferior.
**[Consulte el ejemplo de código completo: .java AwsKmsEncryptedObject](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java)**
Paso 1: crear el proveedor de KMS directo
Cree una instancia del AWS KMS cliente con la región especificada. A continuación, utilice la instancia de cliente para crear una instancia del proveedor de KMS directo con su AWS KMS key preferido.
En este ejemplo, se utiliza el nombre de recurso de Amazon (ARN) para identificar el AWS KMS key, pero se puede utilizar [cualquier identificador clave válido](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id).
```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```
Paso 2: Crear DynamoDB Encryptor y Dynamo DBMapper
Utilice el Proveedor de KMS directo que creó en el paso anterior para crear una instancia del [Encriptador de DynamoDB](java-using.md#attribute-encryptor). Debe crear instancias en el Encriptador de DynamoDB de nivel inferior para utilizar DynamoDB Mapper.
A continuación, cree una instancia de base de datos de DynamoDB y una configuración de mapeador, y úselas para crear una instancia de DynamoDB Mapper.
Al utilizar el `DynamoDBMapper` para añadir o editar elementos firmados (o cifrados y firmados), configúrelo para [usar un comportamiento de almacenamiento](java-using.md#save-behavior), como `PUT`, que incluye todos los atributos, como se muestra en el ejemplo siguiente. De lo contrario, es posible que no pueda descifrar los datos.
```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp)
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build();
DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```
Paso 3: Definir la tabla de DynamoDB
A continuación, defina la tabla de DynamoDB. Utilice anotaciones para especificar las [acciones del atributo](java-using.md#attribute-actions-java). En este ejemplo, se crea una tabla de DynamoDB, `ExampleTable`, y una clase `DataPoJo` que representa elementos de la tabla.
En este ejemplo de tabla, los atributos de clave principal se firmarán, pero no se cifrarán. Esto se aplica al `partition_attribute`, que se ha anotado con `@DynamoDBHashKey`, y el `sort_attribute`, que se ha anotado con `@DynamoDBRangeKey`.
Los atributos que son anotados con `@DynamoDBAttribute`, como `some numbers`, se cifrarán y firmarán. Las excepciones son atributos que utilizan las anotaciones de cifrado `@DoNotEncrypt` (solo firmar) o `@DoNotTouch` (no cifrar ni firmar) definidas por el cliente de cifrado de DynamoDB. Por ejemplo, ya que el atributo `leave me` tiene una anotación `@DoNotTouch`, no se cifrará ni se firmará.
```
@DynamoDBTable(tableName = "ExampleTable")
public static final class DataPoJo {
private String partitionAttribute;
private int sortAttribute;
private String example;
private long someNumbers;
private byte[] someBinary;
private String leaveMe;
@DynamoDBHashKey(attributeName = "partition_attribute")
public String getPartitionAttribute() {
return partitionAttribute;
}
public void setPartitionAttribute(String partitionAttribute) {
this.partitionAttribute = partitionAttribute;
}
@DynamoDBRangeKey(attributeName = "sort_attribute")
public int getSortAttribute() {
return sortAttribute;
}
public void setSortAttribute(int sortAttribute) {
this.sortAttribute = sortAttribute;
}
@DynamoDBAttribute(attributeName = "example")
public String getExample() {
return example;
}
public void setExample(String example) {
this.example = example;
}
@DynamoDBAttribute(attributeName = "some numbers")
public long getSomeNumbers() {
return someNumbers;
}
public void setSomeNumbers(long someNumbers) {
this.someNumbers = someNumbers;
}
@DynamoDBAttribute(attributeName = "and some binary")
public byte[] getSomeBinary() {
return someBinary;
}
public void setSomeBinary(byte[] someBinary) {
this.someBinary = someBinary;
}
@DynamoDBAttribute(attributeName = "leave me")
@DoNotTouch
public String getLeaveMe() {
return leaveMe;
}
public void setLeaveMe(String leaveMe) {
this.leaveMe = leaveMe;
}
@Override
public String toString() {
return "DataPoJo [partitionAttribute=" + partitionAttribute + ", sortAttribute="
+ sortAttribute + ", example=" + example + ", someNumbers=" + someNumbers
+ ", someBinary=" + Arrays.toString(someBinary) + ", leaveMe=" + leaveMe + "]";
}
}
```
Paso 4: Cifrar y guardar un elemento de la tabla
Ahora, al crear un elemento de tabla y utilizar DynamoDB Mapper para guardarlo, el elemento se cifra automáticamente y firma antes de que se agregue a la tabla.
Este ejemplo define un elemento de tabla llamado `record`. Antes de que se guarde en la tabla, sus atributos se cifran y firman en función de las anotaciones de la clase `DataPoJo`. En este caso, todos los atributos salvo `PartitionAttribute`, `SortAttribute` y `LeaveMe` se cifran y se firman. `PartitionAttribute` y `SortAttributes` solo se firman. El atributo `LeaveMe` no está cifrado o firmado.
Para cifrar y firmar el elemento `record`y, a continuación, añadirlo a `ExampleTable`, llame al método `save` de la clase `DynamoDBMapper`. Dado que el DynamoDB mapper está configurado para utilizar el `PUT` comportamiento de almacenamiento, el elemento sustituye a cualquier elemento con las mismas claves principales, en lugar de actualizarla. De este modo, se garantiza que las firmas coincidan y puede descifrar el elemento cuando se obtiene de la tabla.
```
DataPoJo record = new DataPoJo();
record.setPartitionAttribute("is this");
record.setSortAttribute(55);
record.setExample("data");
record.setSomeNumbers(99);
record.setSomeBinary(new byte[]{0x00, 0x01, 0x02});
record.setLeaveMe("alone");
mapper.save(record);
```
# Cliente de cifrado de DynamoDB para Python
**nota**
Nuestra biblioteca de cifrado del cliente [pasó a llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En este tema, se explica cómo instalar y utilizar el cliente de cifrado de DynamoDB para en Python. Puede encontrar el código en el [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/)repositorio de GitHub, incluido un [código de muestra](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) completo y probado que le ayudará a empezar.
**nota**
Versiones 1. *x*. *x* y 2. *x*. *x* del cliente de cifrado de DynamoDB para Python entrarán en vigor [end-of-support en](what-is-database-encryption-sdk.md#support) julio de 2022. Actualice a una versión más reciente tan pronto como sea posible.
**Topics**
+ [Requisitos previos](#python-prerequisites)
+ [Instalación](#python-installation)
+ [Uso del cliente de cifrado de DynamoDB para Python](python-using.md)
+ [Ejemplos de Python](python-examples.md)
## Requisitos previos
Antes de instalar el Cliente de encriptación de Amazon DynamoDB para Python, asegúrese de que cumple los siguientes requisitos previos.
**Una versión compatible de Python**
El cliente de cifrado de Amazon DynamoDB para las versiones 3.3.0 y posteriores de Python requiere Python 3.8 o posterior. Para descargar Python, visite el sitio de [descargas de Python](https://www.python.org/downloads/).
Las versiones anteriores del Cliente de encriptación de Amazon DynamoDB para Python admiten Python 2.7 y Python 3.4 y versiones posteriores, pero le recomendamos que utilice la versión más reciente del cliente de cifrado de DynamoDB.
**La herramienta de instalación pip para Python**
Python 3.6 y versiones posteriores incluyen **pip**, aunque es posible que desee actualizarlo. Para obtener más información acerca de la actualización o la instalación de pip, consulte la sección sobre la [instalación](https://pip.pypa.io/en/latest/installation/) en la documentación de **pip**.
## Instalación
Utilice **pip** para instalar el Cliente de encriptación de Amazon DynamoDB para Python, como se muestra en los siguientes ejemplos.
**Para instalar la versión más reciente**
```
pip install dynamodb-encryption-sdk
```
Para obtener más información acerca de cómo utilizar **pip** para instalar y actualizar paquetes, consulte la página sobre la [instalación de paquetes](https://packaging.python.org/tutorials/installing-packages/).
El cliente de cifrado de DynamoDB requiere la [biblioteca de criptografía](https://cryptography.io/en/latest/) en todas las plataformas. Todas las versiones de **pip** instalan y compilan la biblioteca **cryptography** en Windows. **pip** 8.1 y las versiones posteriores instalan y compilan la biblioteca **cryptography** en Linux. Si utiliza una versión anterior de **pip** y su entorno Linux no dispone de las herramientas necesarias para compilar la biblioteca **cryptography**, tiene que instalarlas. Para obtener más información, consulte [Building cryptography on Linux](https://cryptography.io/en/latest/installation/#building-cryptography-on-linux).
Puede obtener la última versión de desarrollo del cliente de cifrado de DynamoDB desde [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/)el repositorio en adelante. GitHub
Después de instalar el cliente de cifrado de DynamoDB, comience examinando el código de Python de ejemplo de esta guía.
# Uso del cliente de cifrado de DynamoDB para Python
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En este tema, se explican algunas de las características del cliente de cifrado de DynamoDB para Python que podrían no encontrarse en otras implementaciones de lenguaje de programación. Estas características se han diseñado para facilitar el uso del cliente de cifrado de DynamoDB de la forma más segura. A menos que tenga un caso de uso inusual, le recomendamos que las utilice.
Para obtener más información sobre la programación con el cliente de cifrado de DynamoDB, consulte los ejemplos de [Python](python-examples.md) de esta guía, [los ejemplos del](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) repositorio GitHub y aws-dynamodb-encryption-python la documentación de [Python](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/) del cliente de cifrado de DynamoDB.
**Topics**
+ [Clases auxiliares de cliente](#python-helpers)
+ [TableInfo clase](#table-info)
+ [Acciones de atributo en Python](#python-attribute-actions)
## Clases auxiliares de cliente
El cliente de cifrado de DynamoDB para Python incluye varias clases auxiliares de cliente, que interactúan con las clases de Boto 3 para DynamoDB. Estas clases auxiliares se han diseñado para facilitar agregar cifrado y firma a su aplicación de DynamoDB existente y evitar los problemas más habituales del siguiente modo:
+ Evite cifrar la clave principal del elemento, ya sea añadiendo una acción de anulación de la clave principal del objeto o lanzando una excepción si el [AttributeActions](#python-attribute-actions)objeto indica explícitamente al cliente que cifre la clave principal. `AttributeActions` Si la acción predeterminada en su objeto `AttributeActions` es `DO_NOTHING`, las clases auxiliares de cliente utilizan dicha acción para la clave principal. De lo contrario, utilizan `SIGN_ONLY`.
+ Cree un [TableInfo objeto y complete](#python-helpers) el contexto de [cifrado de DynamoDB en función de una llamada a DynamoDB](concepts.md#encryption-context). Esto ayuda a garantizar que el contexto de cifrado de DynamoDB sea exacto y el cliente pueda identificar la clave principal.
+ Admite métodos, tales como `put_item` y `get_item`, que cifran y descifran de modo transparente los elementos de tabla al escribir o leer desde una tabla de DynamoDB. Solo el método `update_item` no se admite.
Puede utilizar las clases auxiliares de cliente en lugar de interactuar directamente con el [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor) de nivel inferior. Utilice estas clases a menos que tenga que establecer opciones avanzadas en el encriptador de elementos.
Las clases auxiliares de cliente incluyen:
+ [EncryptedTable](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html#module-dynamodb_encryption_sdk.encrypted.table)para las aplicaciones que utilizan el recurso [Tabla](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table) de DynamoDB para procesar una tabla a la vez.
+ [EncryptedResource](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html)para aplicaciones que utilizan la clase [Service Resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#service-resource) de DynamoDB para el procesamiento por lotes.
+ [EncryptedClient](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html)para aplicaciones que utilizan el [cliente de nivel inferior de DynamoDB](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#client).
Para usar las clases auxiliares del cliente, la persona que llama debe tener permiso para llamar a la operación de DynamoDB en la tabla de destino [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html).
## TableInfo clase
La [TableInfo](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/structures.html#dynamodb_encryption_sdk.structures.TableInfo)clase es una clase auxiliar que representa una tabla de DynamoDB, completa con campos para su clave principal e índices secundarios. Le ayuda a obtener información precisa y en tiempo real sobre la tabla.
Si utiliza una [clase auxiliar de cliente](#python-helpers), crea y utiliza un objeto `TableInfo` automáticamente. De lo contrario, puede crear una explícitamente. Para ver un ejemplo, consulta [Utilice el encriptador de elementos](python-examples.md#python-example-item-encryptor).
Cuando se llama al `refresh_indexed_attributes` método en un `TableInfo` objeto, se rellenan los valores de las propiedades del objeto mediante una llamada a la operación DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html). Consultar la tabla ofrece mucha más confianza que codificar de forma rígida los nombres de índice. La clase `TableInfo` incluye además una `encryption_context_values` propiedad que proporciona los valores requeridos para el [contexto de cifrado de DynamoDB](concepts.md#encryption-context).
Para usar el `refresh_indexed_attributes` método, la persona que llama debe tener permiso para llamar a la operación de [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)DynamoDB en la tabla de destino.
## Acciones de atributo en Python
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) indican al encriptador de elementos qué acciones hay que realizar en cada atributo del elemento. Para especificar acciones de atributo en Python, cree un objeto `AttributeActions` con una acción predeterminada y cualquier excepción para atributos particulares. Los valores válidos se definen en el tipo enumerado `CryptoAction`.
**importante**
Después de utilizar las acciones de atributo para cifrar los elementos de la tabla, agregar o quitar atributos del modelo de datos puede provocar un error de validación de firma que le impide descifrar los datos. Para ver una explicación detallada, consulte [Cambiar el modelo de datos](data-model.md).
```
DO_NOTHING = 0
SIGN_ONLY = 1
ENCRYPT_AND_SIGN = 2
```
Por ejemplo, este objeto `AttributeActions` establece `ENCRYPT_AND_SIGN` como predeterminado para todos los atributos y especifica excepciones para los atributos `ISBN` y `PublicationYear`.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={
'ISBN': CryptoAction.DO_NOTHING,
'PublicationYear': CryptoAction.SIGN_ONLY
}
)
```
Si utiliza una [clase auxiliar de cliente](#python-helpers), no tiene que especificar una acción de atributo para los atributos de clave principal. Las clases auxiliares de cliente impiden que cifre su clave principal.
Si no utiliza una clase auxiliar de cliente y la acción predeterminada es `ENCRYPT_AND_SIGN`, debe especificar una acción para la clave principal. La acción recomendada para las claves principales es `SIGN_ONLY`. Para facilitarlo, utilice el método `set_index_keys`, que utiliza SIGN\$1ONLY para claves principales o DO\$1NOTHING, cuando esa es la acción predeterminada.
**aviso**
No cifre los atributos de clave principal. Deben permanecer en texto no cifrado para que DynamoDB pueda encontrar el elemento sin realizar un examen completo de la tabla.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
)
actions.set_index_keys(*table_info.protected_index_keys())
```
# Código de ejemplo para el cliente de cifrado de DynamoDB para Python
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En los siguientes ejemplos, se muestra cómo utilizar el cliente de cifrado de DynamoDB para Python para proteger los datos de DynamoDB en su aplicación. Puedes encontrar más ejemplos (y aportar los tuyos propios) en el directorio de [ejemplos](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) del [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/)repositorio de. GitHub
**Topics**
+ [Usa la clase de ayuda al EncryptedTable cliente](#python-example-table)
+ [Utilice el encriptador de elementos](#python-example-item-encryptor)
## Usa la clase de ayuda al EncryptedTable cliente
El ejemplo siguiente le muestra cómo utilizar el [proveedor de KMS directo](direct-kms-provider.md) con la `EncryptedTable` [clase auxiliar cliente](python-using.md#python-helpers). Este ejemplo utiliza el mismo [proveedor de materiales criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) que el ejemplo [Utilice el encriptador de elementos](#python-example-item-encryptor) siguiente. Sin embargo, utiliza la clase `EncryptedTable` en lugar de interactuar directamente con el [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor) de nivel inferior.
Comparando estos ejemplos, puede ver el trabajo que realiza la clase auxiliar cliente automáticamente. Esto incluye la creación del [contexto de cifrado de DynamoDB](concepts.md#encryption-context) y asegurarse de que los atributos de clave principal estén siempre firmados, pero nunca cifrados. Para crear el contexto de cifrado y descubrir la clave principal, las clases auxiliares del cliente llaman a la operación DynamoDB [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html). Para ejecutar este código, debe tener permiso para llamar a esta operación.
**Vea la muestra de código completa**: [aws\$1kms\$1encrypted\$1table.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)
Paso 1: crear la tabla
Empiece creando una instancia de una tabla de DynamoDB estándar con el nombre de la tabla.
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
Paso 2: crear un proveedor de materiales criptográficos
Cree una instancia del [proveedor de materiales criptográficos](crypto-materials-providers.md) (CMP) que ha seleccionado.
Este ejemplo utiliza el [proveedor de KMS directo](direct-kms-provider.md), pero puede utilizar cualquier CMP compatible. Para crear un proveedor de KMS directo, especifique un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys). En este ejemplo se utiliza el nombre de recurso de Amazon (ARN) del AWS KMS key, pero se puede utilizar cualquier identificador clave válido.
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
Paso 3: crear el objeto de acciones de atributo
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) indican al encriptador de elementos qué acciones hay que realizar en cada atributo del elemento. El objeto `AttributeActions` de este ejemplo cifra y firma todos los elementos, excepto el atributo `test`, que se pasa por alto.
No especifique acciones de atributo para los atributos de clave principal cuando utilice una clase auxiliar cliente. La clase `EncryptedTable` firma, pero no cifra nunca, los atributos de clave principal.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
```
Paso 4: crear la tabla cifrada
Cree la tabla cifrada utilizando la tabla estándar, el proveedor de KMS directo y las acciones de atributo. Este paso completa la configuración.
```
encrypted_table = EncryptedTable(
table=table,
materials_provider=kms_cmp,
attribute_actions=actions
)
```
Paso 5: colocar el elemento de texto no cifrado en la tabla
Cuando se llama al método `put_item` en la `encrypted_table`, los elementos de la tabla se cifran de modo transparente, se firman y se agrega a su tabla de DynamoDB.
Primero, defina el elemento de tabla.
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_attribute': 55
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
A continuación, colóquelo en la tabla.
```
encrypted_table.put_item(Item=plaintext_item)
```
Para obtener el elemento desde la tabla de DynamoDB en su forma cifrada, llame al método `get_item` en el objeto `table`. Para obtener el objeto descifrado, llame al método `get_item` en el objeto `encrypted_table`.
## Utilice el encriptador de elementos
En este ejemplo, se muestra cómo interactuar directamente con el [encriptador de elementos](DDBEC-legacy-concepts.md#item-encryptor) en la al cifrar elementos de tabla, en lugar de utilizar las [clases auxiliares de cliente](python-using.md#python-helpers) que interactúan con el encriptador de elementos.
Cuando se utiliza esta técnica, crea el contexto de cifrado de DynamoDB y el objeto de configuración (`CryptoConfig`) manualmente. Además, cifra los elementos en una llamada y los coloca en su tabla de DynamoDB en una llamada independiente. Esto le permite personalizar sus `put_item` llamadas y utilizar el cliente de cifrado de DynamoDB para cifrar y firmar datos estructurados que nunca se envían a DynamoDB.
Este ejemplo utiliza el [proveedor de KMS directo](direct-kms-provider.md), pero puede utilizar cualquier CMP compatible.
**Vea la muestra de código completa**: [aws\$1kms\$1encrypted\$1item.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)
Paso 1: crear la tabla
Empiece creando una instancia de un recurso de tabla de DynamoDB estándar con el nombre de la tabla.
```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```
Paso 2: crear un proveedor de materiales criptográficos
Cree una instancia del [proveedor de materiales criptográficos](crypto-materials-providers.md) (CMP) que ha seleccionado.
Este ejemplo utiliza el [proveedor de KMS directo](direct-kms-provider.md), pero puede utilizar cualquier CMP compatible. Para crear un proveedor de KMS directo, especifique un [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys). En este ejemplo se utiliza el nombre de recurso de Amazon (ARN) del AWS KMS key, pero se puede utilizar cualquier identificador clave válido.
```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```
Paso 3: Usa la clase TableInfo auxiliar
Para obtener información sobre la tabla de DynamoDB, cree una instancia de [TableInfo](python-using.md#python-helpers)la clase auxiliar. Cuando trabaja directamente con el encriptador de elementos, tiene que crear una instancia `TableInfo` y llamar a sus métodos. Las [clases auxiliares de cliente](python-using.md#python-helpers) lo hacen automáticamente.
El `refresh_indexed_attributes` método `TableInfo` utiliza la operación [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)DynamoDB para obtener información precisa y en tiempo real sobre la tabla. Incluye su clave principal y sus índices secundarios locales y globales. El intermediario tiene que tener permiso para llamar a `DescribeTable`.
```
table_info = TableInfo(name=table_name)
table_info.refresh_indexed_attributes(table.meta.client)
```
Paso 4: crear el contexto de cifrado de DynamoDB
El [contexto de cifrado de DynamoDB](concepts.md#encryption-context) contiene información acerca de la estructura de la tabla y cómo se cifra y se firma. En este ejemplo, se crea un contexto de cifrado de DynamoDB explícitamente, porque interactúa con el encriptador de elementos. Las [clases auxiliares de cliente](python-using.md#python-helpers) crean el contexto de cifrado de DynamoDB para usted.
Para obtener la clave de partición y la clave de clasificación, puede usar las propiedades de la clase [TableInfo](python-using.md#python-helpers)auxiliar.
```
index_key = {
'partition_attribute': 'value1',
'sort_attribute': 55
}
encryption_context = EncryptionContext(
table_name=table_name,
partition_key_name=table_info.primary_index.partition,
sort_key_name=table_info.primary_index.sort,
attributes=dict_to_ddb(index_key)
)
```
Paso 5: crear el objeto de acciones de atributo
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) indican al encriptador de elementos qué acciones hay que realizar en cada atributo del elemento. El objeto `AttributeActions` en este ejemplo cifra y firma todos los elementos, excepto los atributos de clave principal, que se firman, pero no se cifran y el atributo `test`, que se pasa por alto.
Cuando se interactúa directamente con el encriptador de elementos y la acción predeterminada es `ENCRYPT_AND_SIGN`, debe especificar una acción alternativa para la clave principal. Puede utilizar el método `set_index_keys`, que usa `SIGN_ONLY` para la clave principal o utiliza `DO_NOTHING` si es la acción predeterminada.
Para especificar la clave principal, en este ejemplo se utilizan las claves de índice del [TableInfo](python-using.md#python-helpers)objeto, que se rellenan con una llamada a DynamoDB. Esta técnica es más segura que los nombres de clave principal de codificación rígida.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={'test': CryptoAction.DO_NOTHING}
)
actions.set_index_keys(*table_info.protected_index_keys())
```
Paso 6: crear la configuración para el elemento
Para configurar el cliente de cifrado de DynamoDB, utilice los objetos que acaba de crear en [CryptoConfig](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html)una configuración para el elemento de la tabla. Las clases auxiliares del cliente las crean por usted. CryptoConfig
```
crypto_config = CryptoConfig(
materials_provider=kms_cmp,
encryption_context=encryption_context,
attribute_actions=actions
)
```
Paso 7: cifrar el elemento
En este paso, se cifra y firma el elemento, pero no lo coloca en la tabla de DynamoDB.
Cuando utiliza una clase auxiliar de cliente, sus elementos se cifran y se firman de modo transparente y, a continuación, se agregan a su tabla de DynamoDB cuando llama al `put_item` método de la clase auxiliar. Cuando utiliza el encriptador de elementos directamente, las acciones de cifrado y colocación son independientes.
En primer lugar, cree un elemento de texto no cifrado.
```
plaintext_item = {
'partition_attribute': 'value1',
'sort_key': 55,
'example': 'data',
'numbers': 99,
'binary': Binary(b'\x00\x01\x02'),
'test': 'test-value'
}
```
A continuación, cífrelo y fírmelo. El método `encrypt_python_item` requiere el objeto de configuración `CryptoConfig`.
```
encrypted_item = encrypt_python_item(plaintext_item, crypto_config)
```
Paso 8: colocar el elemento en la tabla
En este paso, se coloca el elemento cifrado y firmado en la tabla de DynamoDB.
```
table.put_item(Item=encrypted_item)
```
Para ver el elemento cifrado, llame al método `get_item` en el objeto `table` original, en lugar del objeto `encrypted_table`. Obtiene el elemento de la tabla DynamoDB sin verificarlo y descifrarlo.
```
encrypted_item = table.get_item(Key=partition_key)['Item']
```
En la imagen siguiente se muestra una parte de un elemento de tabla cifrado y firmado de ejemplo.
Los valores de atributo cifrados son datos binarios. Los nombres y los valores de los atributos de clave principal (`partition_attribute` y `sort_attribute`) y el atributo `test` permanecen en texto no cifrado. La salida muestra además el atributo que contiene la firma (`*amzn-ddb-map-sig*`) y el [atributo de descripción de materiales](DDBEC-legacy-concepts.md#legacy-material-description) (`*amzn-ddb-map-desc*`).
![\[Un fragmento de un elemento cifrado y firmado\]](http://docs.aws.amazon.com/es_es/database-encryption-sdk/latest/devguide/images/encrypted-item-closeup.png)
# Cambiar el modelo de datos
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
Cada vez que cifra o descifra un elemento, tiene que proporcionar acciones de atributo [Acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) que indiquen al DynamoDB qué atributos cifrar y firmar, qué atributos firmar (pero no cifrar) y cuáles omitir. Las acciones de atributo no se guardan en el elemento cifrado y no actualiza automáticamente las acciones de atributo.
**importante**
El cliente de cifrado de DynamoDB no admite el cifrado de datos de tablas de DynamoDB existentes y no cifrados.
Cada vez que cambie el modelo de datos, es decir, cuando agregue o quite atributos de los elementos de la tabla, corre el riesgo de que se produzca un error. Si las acciones de atributo que especifique no cuentan para todos los atributos del elemento, el elemento podría no cifrarse y firmarse del modo previsto. Lo que es más importante, si las acciones de atributo que proporciona al descifrar un elemento difieren de las acciones de atributo que proporcione al cifrar el elemento, la verificación de la firma podría fallar.
Por ejemplo, si las acciones de atributo utilizadas para cifrar el elemento indican que se firme el atributo `test`, la firma en el elemento incluirá el atributo `test`. Pero, si las acciones de atributo utilizadas para descifrar el elemento no se tienen en cuenta para el atributo `test`, la verificación devolverá un error, ya que el cliente intentará verificar una firma que no incluye el atributo `test`.
Este es un problema particular cuando varias aplicaciones leen y escriben los mismos elementos de porque debe calcular la misma firma para los elementos en todas las aplicaciones. También es un problema para cualquier aplicación distribuida porque los cambios en las acciones de atributos deben propagarse a todos los hosts. Incluso si un host accede a sus tablas de en un proceso, establecer un proceso de prácticas recomendadas ayudará a evitar errores si el proyecto se vuelve más complejo.
Para evitar errores de validación de firmas que le impidan leer los elementos de la tabla, siga las instrucciones siguientes.
+ [Añadir un atributo](#add-attribute): si el nuevo atributo cambia sus acciones de atributo, implemente completamente el cambio de acción de atributo antes de incluir el nuevo atributo en un elemento.
+ [Eliminar un atributo](#remove-attribute): si dejas de usar un atributo en tus artículos, no cambies las acciones de los atributos.
+ Cambiar la acción: después de haber utilizado una configuración de acciones de atributos para cifrar los elementos de la tabla, no podrá cambiar de forma segura la acción predeterminada o la acción de un atributo existente sin volver a cifrar todos los elementos de la tabla.
Los errores de validación de firmas pueden ser extremadamente difíciles de resolver, por lo que el mejor enfoque es prevenirlos.
**Topics**
+ [Adición de un atributo](#add-attribute)
+ [Eliminación de un atributo](#remove-attribute)
## Adición de un atributo
Al agregar un nuevo atributo a los elementos de tabla, es posible que tenga que cambiar las acciones de atributo. Para evitar errores de validación de firmas, se recomienda implementar este cambio en un proceso de dos etapas. Verifique que la primera etapa esté completa antes de comenzar la segunda etapa.
1. Cambie las acciones de atributo en todas las aplicaciones que leen o escriben en la tabla. Implemente estos cambios y confirme que la actualización se ha propagado a todos los hosts de destino.
1. Escriba valores en el nuevo atributo de los elementos de la tabla.
Este enfoque de dos etapas garantiza que todas las aplicaciones y hosts tengan las mismas acciones de atributo y calculará la misma firma antes de que cualquier otro encuentre el nuevo atributo. Esto es importante incluso cuando la acción del atributo es *Do nothing* (no cifrar ni firmar), porque el valor predeterminado de algunos encriptadores es cifrar y firmar.
Los siguientes ejemplos muestran el código de la primera etapa de este proceso. Agregan un nuevo atributo de elemento, `link`, que almacena un vínculo a otro elemento de tabla. Dado que este vínculo debe permanecer como texto sin formato, el ejemplo le asigna la acción de solo firma. Después de implementar completamente este cambio y comprobar que todas las aplicaciones y hosts tienen las nuevas acciones de atributo, puede comenzar a usar el atributo `link` en los elementos de tabla.
------
#### [ Java DynamoDB Mapper ]
Cuando usa `DynamoDB Mapper` y `AttributeEncryptor`, todos los atributos están cifrados y firmados por defecto, excepto las claves principales, que están firmadas pero no cifradas. Para especificar una acción de solo firma, utilice la anotación `@DoNotEncrypt`.
En este ejemplo se utiliza la anotación `@DoNotEncrypt` para el nuevo atributo `link`.
```
@DynamoDBTable(tableName = "ExampleTable")
public static final class DataPoJo {
private String partitionAttribute;
private int sortAttribute;
private String link;
@DynamoDBHashKey(attributeName = "partition_attribute")
public String getPartitionAttribute() {
return partitionAttribute;
}
public void setPartitionAttribute(String partitionAttribute) {
this.partitionAttribute = partitionAttribute;
}
@DynamoDBRangeKey(attributeName = "sort_attribute")
public int getSortAttribute() {
return sortAttribute;
}
public void setSortAttribute(int sortAttribute) {
this.sortAttribute = sortAttribute;
}
@DynamoDBAttribute(attributeName = "link")
@DoNotEncrypt
public String getLink() {
return link;
}
public void setLink(String link) {
this.link = link;
}
@Override
public String toString() {
return "DataPoJo [partitionAttribute=" + partitionAttribute + ",
sortAttribute=" + sortAttribute + ",
link=" + link + "]";
}
}
```
------
#### [ Java DynamoDB encryptor ]
En el encriptador de nivel inferior, debe establecer acciones para cada atributo. En este ejemplo se utiliza una instrucción switch donde el valor predeterminado es `encryptAndSign` y se especifican excepciones para la clave de partición, la clave de clasificación y el nuevo atributo `link`. En este ejemplo, si el código de atributo de vínculo no se implementó completamente antes de utilizarlo, algunas aplicaciones cifrarían y firmarían el atributo de vínculo, pero solo lo firmarían otras.
```
for (final String attributeName : record.keySet()) {
switch (attributeName) {
case partitionKeyName:
// fall through to the next case
case sortKeyName:
// partition and sort keys must be signed, but not encrypted
actions.put(attributeName, signOnly);
break;
case "link":
// only signed
actions.put(attributeName, signOnly);
break;
default:
// Encrypt and sign all other attributes
actions.put(attributeName, encryptAndSign);
break;
}
}
```
------
#### [ Python ]
En DynamoDB para Python, puede especificar una acción predeterminada para todos los atributos y, a continuación, especificar excepciones.
Si utiliza una [clase auxiliar de cliente](python-using.md#python-helpers) de Python, no tiene que especificar una acción de atributo para los atributos de clave principal. Las clases auxiliares de cliente impiden que cifre su clave principal. Sin embargo, si no está utilizando una clase auxiliar de cliente, debe establecer la acción SIGN\$1ONLY en la clave de partición y la clave de clasificación. Si accidentalmente cifra la partición o la clave de clasificación, no podrá recuperar los datos sin un análisis completo de la tabla.
En este ejemplo se especifica una excepción para el nuevo atributo `link`, que obtiene la acción `SIGN_ONLY`.
```
actions = AttributeActions(
default_action=CryptoAction.ENCRYPT_AND_SIGN,
attribute_actions={
'example': CryptoAction.DO_NOTHING,
'link': CryptoAction.SIGN_ONLY
}
)
```
------
## Eliminación de un atributo
Si ya no necesita un atributo en los elementos que se han cifrado con , puede dejar de usar el atributo. Sin embargo, no elimine ni cambie la acción de ese atributo. Si lo hace y, a continuación, encuentra un elemento con ese atributo, la firma calculada para el artículo no coincidirá con la firma original y la validación de la firma fallará.
Aunque podría tener la tentación de eliminar todos los rastros del atributo del código, agregue un comentario de que el elemento ya no se usa en lugar de eliminarlo. Incluso si realiza un análisis de tabla completo para eliminar todas las instancias del atributo, un elemento cifrado con ese atributo podría almacenarse en caché o estar en proceso en algún lugar de la configuración.
# Solución de problemas en la aplicación DynamoDB Encryption Client
**nota**
Nuestra biblioteca de cifrado del cliente pasó a [llamarse SDK de cifrado de bases de datos de AWS](DDBEC-rename.md). En el siguiente tema, se presenta información sobre las versiones 1.*x*—2.*x* del cliente de cifrado de DynamoDB para Java y versiones 1.*x*—3.*x* del cliente de cifrado de DynamoDB para Python. Para obtener más información, consulte el [SDK de cifrado de bases de datos de AWS para la compatibilidad de la versión de DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).
En esta sección se describen los problemas que podría encontrar al utilizar el y se ofrecen sugerencias para resolverlos.
Para enviar comentarios sobre el cliente de cifrado de DynamoDB, registre un problema en [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/)el repositorio o. [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) GitHub
Para enviar comentarios sobre esta documentación, utilice el enlace de comentarios de cualquier página.
**Topics**
+ [Acceso denegado](#kms-permissions)
+ [Errores de verificación de firma](#change-data-model)
+ [Problemas con las tablas globales de versiones anteriores](#fix-global-tables)
+ [Rendimiento deficiente del proveedor más reciente](#mrp-ttl-delay)
## Acceso denegado
**Problema**: su aplicación ha denegado el acceso a un recurso que la necesita.
**Sugerencia**: obtenga información acerca de los permisos requeridos y agréguelos al contexto de seguridad en el que se ejecuta su aplicación.
**Detalles**
Para ejecutar una aplicación que usa una biblioteca de , el intermediario debe tener permiso para utilizar sus componentes. De lo contrario, se les denegará el acceso a los elementos requeridos.
+ El cliente de cifrado de DynamoDB no requiere una cuenta de Amazon Web Services (AWS) ni depende de ningún servicio. AWS Sin embargo, si su aplicación lo usa AWS, necesitará [una cuenta Cuenta de AWS](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) y [usuarios que tengan permiso](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) para usar la cuenta.
+ El cliente de cifrado de DynamoDB no requiere Amazon DynamoDB. Sin embargo, si la aplicación que utiliza el cliente crea tablas de DynamoDB, coloca elementos en una tabla u obtiene elementos de una tabla, el intermediario debe tener permiso para utilizar las operaciones de DynamoDB requeridas en su Cuenta de AWS. Para obtener más información, consulte los [temas de control de acceso](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/access-control-overview.html) en la *Guía para desarrolladores de Amazon DynamoDB*.
+ Si la aplicación utiliza una [clase auxiliar de cliente](python-using.md#python-helpers) en el cliente de cifrado de DynamoDB para Python, la persona que llama debe tener permiso para llamar a la operación de DynamoDB. [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)
+ El cliente de cifrado de DynamoDB no AWS Key Management Service requiere ().AWS KMS[Sin embargo, si la aplicación utiliza un [proveedor de materiales de Direct KMS](direct-kms-provider.md) o utiliza un [proveedor más reciente](most-recent-provider.md) con un almacén de proveedores que lo utilice AWS KMS, la persona que llama debe tener permiso para utilizar las operaciones AWS KMS[GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)y descifrar.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
## Errores de verificación de firma
**Problema**: un elemento no se puede descifrar porque la verificación de firma devuelve un error. El elemento podría no estar cifrado y firmado del modo previsto.
**Sugerencia**: asegúrese de que las acciones de atributos que proporcione cuenten para todos los atributos del elemento. Al descifrar un elemento, asegúrese de proporcionar acciones de atributo que coincidan con las acciones utilizadas para cifrar el elemento.
**Detalles**
Las [acciones de atributo](DDBEC-legacy-concepts.md#legacy-attribute-actions) que proporciona indican qué atributos cifrar y firmar, qué atributos firmar (pero no cifrar) y cuáles ignorar.
Si las acciones de atributo que especifique no cuentan para todos los atributos del elemento, el elemento podría no cifrarse y firmarse del modo previsto. Si las acciones de atributo que proporciona al descifrar un elemento difieren de las acciones de atributo que proporcione al cifrar el elemento, la verificación de la firma podría fallar. Se trata de un problema particular para aplicaciones distribuidas en las que las nuevas acciones de atributos podrían no haberse propagado a todos los hosts.
Los errores de validación de firmas son difíciles de resolver. Para ayudar a prevenirlos, tome precauciones adicionales al cambiar el modelo de datos. Para obtener más información, consulte [Cambiar el modelo de datos](data-model.md).
## Problemas con las tablas globales de versiones anteriores
**Problema**: los elementos de una tabla global de Amazon DynamoDB de una versión anterior no se pueden descifrar porque no se puede comprobar la firma.
**Sugerencia**: defina las acciones de los atributos de forma que los campos de replicación reservados no estén cifrados ni firmados.
**Detalles**
Puede utilizar el cliente de cifrado de DynamoDB con las tablas globales de [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html). Se recomienda utilizar tablas globales con una clave KMS [multirregional y replicar la clave KMS](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) en todos los Regiones de AWS lugares donde esté replicada la tabla global.
A partir de la [versión 2019.11.21](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V2.html) de tablas globales, puede utilizarlas con el cliente de cifrado de DynamoDB sin ninguna configuración especial. Sin embargo, si utiliza tablas globales de la [versión 2017.11.29](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V1.html), debe asegurarse de que los campos de replicación reservados no estén cifrados ni firmados.
[Si utiliza las tablas globales de la versión 2017.11.29, debe configurar las acciones de atributo para los siguientes atributos `DO_NOTHING` en [`@DoNotTouch`Java](java-using.md#attribute-actions-java) o Python.](python-using.md#python-attribute-actions)
+ `aws:rep:deleting`
+ `aws:rep:updatetime`
+ `aws:rep:updateregion`
Si utiliza cualquier otra versión de las tablas globales, no es necesario realizar ninguna acción.
## Rendimiento deficiente del proveedor más reciente
**Problema**: la aplicación responde menos, especialmente después de actualizarse a una versión más reciente del cliente de cifrado de DynamoDB.
**Sugerencia**: ajuste el time-to-live valor y el tamaño de la memoria caché.
**Detalles**
El proveedor más reciente está diseñado para mejorar el rendimiento de las aplicaciones que utilizan el cliente de cifrado de DynamoDB al permitir una reutilización limitada del material criptográfico. Al configurar el proveedor más reciente para su aplicación, debe equilibrar la mejora del rendimiento con los problemas de seguridad que se derivan del almacenamiento en caché y la reutilización.
En las versiones más recientes del cliente de cifrado de DynamoDB, time-to-live el valor (TTL) determina durante cuánto tiempo se pueden utilizar los proveedores de material criptográfico en caché (). CMPs El TTL también determina la frecuencia con la que el proveedor más reciente comprueba si hay una nueva versión del CMP.
Si su TTL es demasiado largo, su aplicación podría infringir sus normas empresariales o normas de seguridad. Si tu TTL es demasiado breve, las llamadas frecuentes a la tienda del proveedor pueden provocar que la tienda del proveedor limite las solicitudes de tu aplicación y de otras aplicaciones que comparten tu cuenta de servicio. Para resolver este problema, ajusta el TTL y el tamaño de la caché a un valor que cumpla tus objetivos de latencia y disponibilidad y que se ajuste a tus estándares de seguridad. Para obtener más información, consulte [Establecer un valor time-to-live](most-recent-provider.md#most-recent-provider-ttl).