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.
# Cifrado para búsquedas
****
| |
| --- |
| 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 cifrado para búsquedas le permite buscar registros cifrados sin tener que descifrar toda la base de datos. Esto se logra mediante *balizas*, que crean un mapa entre el valor de texto no cifrado escrito en un campo y el valor cifrado que realmente está almacenado en la base de datos. El SDK AWS de cifrado de bases de datos almacena la baliza en un campo nuevo que se añade al registro. Según el tipo de baliza que utilice, puede realizar búsquedas de coincidencias exactas o consultas complejas más personalizadas en sus datos cifrados.
**nota**
El cifrado con capacidad de búsqueda del SDK AWS de cifrado de bases de datos difiere del cifrado simétrico con capacidad de búsqueda definido en la investigación académica, como el cifrado simétrico con capacidad de [búsqueda](https://dl.acm.org/doi/10.1145/1180405.1180417).
Una baliza es una etiqueta de código de autenticación de mensajes basado en hash (HMAC) truncada que crea un mapa entre el texto no cifrado y los valores cifrados de un campo. Al escribir un valor nuevo en un campo cifrado que está configurado para el cifrado con capacidad de búsqueda, el SDK de cifrado de AWS bases de datos calcula un HMAC sobre el valor del texto sin formato. Esta salida del HMAC coincide uno a uno (1:1) con el valor de texto no cifrado de ese campo. La salida del HMAC se trunca para que varios valores de texto no cifrado distintos se asignen a la misma etiqueta HMAC truncada. Estos falsos positivos limitan la capacidad de un usuario no autorizado para identificar información distintiva sobre el valor del texto no cifrado. Al consultar una baliza, el SDK de cifrado de bases de datos de AWS filtra automáticamente estos falsos positivos y devuelve el resultado de la consulta en texto no cifrado.
El número medio de falsos positivos generados por cada baliza viene determinado por la longitud de la baliza restante tras el truncamiento. Si necesita ayuda para determinar la longitud de la baliza adecuada para su implementación, consulte [Determinar la longitud de la baliza](choosing-beacon-length.md).
**nota**
El cifrado para búsquedas está diseñado para implementarse en bases de datos nuevas y despobladas. Cualquier baliza configurada en una base de datos existente solo mapeará los nuevos registros cargados en la base de datos; no hay forma de que una baliza mapee los datos ya existentes.
**Temas**
+ [¿Las balizas son adecuadas para mi conjunto de datos?](#are-beacons-right-for-me)
+ [Situación de cifrado para búsquedas](#beacon-overview-example)
## ¿Las balizas son adecuadas para mi conjunto de datos?
El uso de balizas para realizar consultas sobre datos cifrados reduce los costos de rendimiento asociados a las bases de datos cifradas del cliente. Cuando se utilizan balizas, existe un equilibrio inherente entre la eficacia de las consultas y la cantidad de información que se revela sobre la distribución de los datos. La baliza no altera el estado cifrado del campo. Al cifrar y firmar un campo con el SDK de cifrado de AWS bases de datos, el valor de texto sin formato del campo nunca se expone a la base de datos. La base de datos almacena el valor cifrado y la asignación al azar del campo.
Las balizas se almacenan junto a los campos cifrados a partir de los cuales se calculan. Esto significa que, incluso si un usuario no autorizado no puede ver los valores de texto no cifrado de un campo cifrado, podría realizar un análisis estadístico de las balizas para obtener más información sobre la distribución del conjunto de datos y, en casos extremos, identificar los valores de texto no cifrado a los que se asigna una baliza. La forma en que configura su baliza puede mitigar estos riesgos. En particular, [elegir la longitud de baliza correcta](choosing-beacon-length.md) puede ayudarle a preservar la confidencialidad de su conjunto de datos.
**Seguridad en comparación con rendimiento**
+ Cuanto menor sea la longitud de la baliza, más seguridad se preservará.
+ Cuanto mayor sea la longitud de la baliza, más rendimiento se preservará.
Es posible que el cifrado para búsquedas no proporcione los niveles deseados de rendimiento y seguridad para todos los conjunto de datos. Revise su modelo de amenazas, sus requisitos de seguridad y sus necesidades de rendimiento antes de configurar cualquier baliza.
Tenga en cuenta los siguientes requisitos de exclusividad del conjunto de datos al determinar si el cifrado para búsquedas es adecuado para su conjunto de datos.
**Distribución**
El grado de seguridad que conserva una baliza depende de la distribución del conjunto de datos. Al configurar un campo cifrado para un cifrado que permita realizar búsquedas, el SDK de cifrado de AWS bases de datos calcula un HMAC a partir de los valores de texto sin formato escritos en ese campo. Todas las balizas calculadas para un campo determinado se calculan con la misma clave, con la excepción de las bases de datos de multitenencia, que utilizan una clave distinta para cada inquilino. Esto significa que si se escribe el mismo valor de texto no cifrado en el campo varias veces, se crea la misma etiqueta HMAC para cada instancia de ese valor de texto no cifrado.
Debe evitar crear balizas a partir de campos que contengan valores muy comunes. Por ejemplo, considere una base de datos que almacene la dirección de todos los residentes del estado de Illinois. Si crea una baliza a partir del campo `City` cifrado, la baliza calculada sobre “Chicago” estará sobrerrepresentada debido al porcentaje alto de la población de Illinois que vive en Chicago. Incluso si un usuario no autorizado solo puede leer los valores cifrados y los valores de la baliza, podría identificar qué registros contienen datos de los residentes de Chicago si la baliza conserva esta distribución. Para minimizar la cantidad de información distintiva revelada sobre su distribución, debe truncar suficientemente la baliza. La longitud de baliza necesaria para ocultar esta distribución desigual supone unos costos de rendimiento significativos que podrían no satisfacer las necesidades de la aplicación.
Debe analizar detenidamente la distribución del conjunto de datos para determinar en qué medida es necesario truncar las balizas. La longitud de la baliza que queda después del truncamiento se correlaciona directamente con la cantidad de información estadística que se puede identificar sobre su distribución. Es posible que tengas que elegir longitudes de baliza más cortas para minimizar suficientemente la cantidad de información distintiva que se revela sobre tu conjunto de datos.
En casos extremos, no se puede calcular la longitud de una baliza para un conjunto de datos distribuido de forma desigual que equilibre eficazmente el rendimiento y la seguridad. Por ejemplo, no debe construir una baliza a partir de un campo que almacene el resultado de un examen médico para detectar una enfermedad rara. Como `NEGATIVE` se espera que los resultados sean significativamente más frecuentes en el conjunto de datos, `POSITIVE` los resultados se pueden identificar fácilmente por su poca frecuencia. Es muy difícil ocultar la distribución cuando el campo solo tiene dos valores posibles. Si utiliza una longitud de baliza lo suficientemente corta como para ocultar la distribución, todos los valores de texto no cifrado se asignan a la misma etiqueta HMAC. Si utiliza una longitud de baliza más larga, es obvio qué balizas se asignan a valores `POSITIVE` de texto no cifrado.
**Correlación**
Le recomendamos encarecidamente que evite construir balizas distintas a partir de campos con valores relacionados entre sí. Las balizas construidas a partir de campos relacionados entre sí requieren longitudes de baliza más cortas para minimizar suficientemente la cantidad de información revelada sobre la distribución de cada conjunto de datos a un usuario no autorizado. Debe analizar detenidamente el conjunto de datos, incluida su entropía y la distribución conjunta de los valores relacionados entre sí, para determinar en qué medida deben truncarse las balizas. Si la longitud de baliza resultante no satisface sus necesidades de rendimiento, es posible que las balizas no sean adecuadas para su conjunto de datos.
Por ejemplo, no debe construir dos balizas independientes a partir de los campos `City` y `ZIPCode`, ya que es probable que el código postal esté asociado a una sola ciudad. Por lo general, los falsos positivos que genera una baliza limitan la capacidad de un usuario no autorizado de identificar información distintiva sobre su conjunto de datos. Sin embargo, la correlación entre los campos `City` y `ZIPCode` significa que un usuario no autorizado puede identificar fácilmente qué resultados son falsos positivos y distinguir los distintos códigos postales.
También debe evitar crear balizas a partir de campos que contengan los mismos valores de texto no cifrado. Por ejemplo, no debe crear una baliza a partir de los campos `mobilePhone` y `preferredPhone` porque es probable que contengan los mismos valores. Si crea balizas distintas a partir de ambos campos, el SDK de cifrado AWS de bases de datos crea las balizas para cada campo con claves diferentes. Esto da como resultado dos etiquetas HMAC diferentes para el mismo valor de texto no cifrado. Es poco probable que las dos balizas distintas tengan los mismos falsos positivos y un usuario no autorizado podría distinguir números de teléfono diferentes.
Incluso si su conjunto de datos contiene campos relacionados entre sí o tiene una distribución desigual, es posible que pueda construir balizas que preserven la confidencialidad del conjunto de datos mediante longitudes de baliza más cortas. Sin embargo, la longitud de la baliza no garantiza que cada valor único del conjunto de datos produzca una serie de falsos positivos que minimicen de forma efectiva la cantidad de información distintiva que se revela sobre el conjunto de datos. La longitud de la baliza solo estima el número medio de falsos positivos producidos. Cuanto más desigualmente esté distribuido el conjunto de datos, menos eficaz será la longitud de la baliza para determinar el número medio de falsos positivos producidos.
Considere detenidamente la distribución de los campos a partir de los cuales construye las balizas y considere cuánto necesitará truncar la longitud de la baliza para cumplir con sus requisitos de seguridad. En los siguientes temas de este capítulo, se parte del supuesto de que las balizas están distribuidas uniformemente y no contienen datos relacionados entre sí.
## Situación de cifrado para búsquedas
En el ejemplo siguiente, se muestra una solución de cifrado sencilla para búsquedas. En la aplicación, es posible que los campos de ejemplo utilizados en este ejemplo no cumplan con las recomendaciones de unicidad de distribución y correlación para las balizas. Puede utilizar este ejemplo como referencia mientras lee en este capítulo acerca de los conceptos de cifrado para búsquedas.
Considere una base de datos denominada `Employees` que rastrea los datos de los empleados de una empresa. *Cada registro de la base de datos contiene campos denominados *EmployeeID *LastName**, *FirstName*, y Address.* Cada campo de la `Employees` base de datos se identifica mediante la clave principal `EmployeeID`.
A continuación, se muestra un ejemplo de un registro de texto no cifrado de la base de datos.
```
{
"EmployeeID": 101,
"LastName": "Jones",
"FirstName": "Mary",
"Address": {
"Street": "123 Main",
"City": "Anytown",
"State": "OH",
"ZIPCode": 12345
}
}
```
Si marcó los campos `LastName` y `FirstName` como `ENCRYPT_AND_SIGN` en sus [acciones criptográficas](concepts.md#crypt-actions), los valores de estos campos se cifrarán localmente antes de cargarlos en la base de datos. Los datos cifrados que se cargan son completamente asignados al azar y la base de datos no los reconoce como protegidos. Simplemente detecta las entradas de datos típicas. Esto significa que el registro que está realmente almacenado en la base de datos podría tener el siguiente aspecto.
```
{
"PersonID": 101,
"LastName": "1d76e94a2063578637d51371b363c9682bad926cbd",
"FirstName": "21d6d54b0aaabc411e9f9b34b6d53aa4ef3b0a35",
"Address": {
"Street": "123 Main",
"City": "Anytown",
"State": "OH",
"ZIPCode": 12345
}
}
```
Si necesita consultar en la base de datos las coincidencias exactas en el `LastName` campo, [configure una baliza estándar con un](configure-beacons.md#config-standard-beacons) nombre *LastName*que asigne los valores de texto sin formato escritos en el `LastName` campo a los valores cifrados almacenados en la base de datos.
Esta baliza se calcula HMACs a partir de los valores de texto sin formato del `LastName` campo. Cada salida del HMAC se trunca para que ya no coincida exactamente con el valor del texto no cifrado. Por ejemplo, el hash completo y el hash truncado `Jones` pueden tener el siguiente aspecto.
**Hash completo**
`2aa4e9b404c68182562b6ec761fcca5306de527826a69468885e59dc36d0c3f824bdd44cab45526f70a2a18322000264f5451acf75f9f817e2b35099d408c833`
**Hash truncado**
`b35099d408c833`
Una vez configurada la baliza estándar, puede realizar búsquedas de igualdad en el campo `LastName`. Por ejemplo, si desea buscar`Jones`, utilice la *LastName*baliza para realizar la siguiente consulta.
```
LastName = Jones
```
El SDK AWS de cifrado de bases de datos filtra automáticamente los falsos positivos y devuelve el resultado de la consulta en texto plano.
# Balizas
****
| |
| --- |
| 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). |
Una baliza es una etiqueta de código de autenticación de mensajes basado en hash (HMAC) truncada que crea un mapa entre el valor de texto no cifrado escrito en un campo y el valor cifrado que está realmente almacenado en la base de datos. La baliza no altera el estado cifrado del campo. La baliza calcula un HMAC sobre el valor de texto no cifrado del campo y lo almacena junto con el valor cifrado. Esta salida del HMAC coincide uno a uno (1:1) con el valor de texto no cifrado de ese campo. La salida del HMAC se trunca para que varios valores de texto no cifrado distintos se asignen a la misma etiqueta HMAC truncada. Estos falsos positivos limitan la capacidad de un usuario no autorizado para identificar información distintiva sobre el valor del texto no cifrado.
[Las balizas solo se pueden crear a partir de campos marcados `ENCRYPT_AND_SIGN` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` en tus `SIGN_ONLY` acciones criptográficas.](concepts.md#crypt-actions) La baliza en sí no está firmada ni cifrada. No se puede construir una baliza con campos marcados `DO_NOTHING`.
El tipo de baliza que configure determinará el tipo de consultas que podrá realizar. Existen dos tipos de balizas que admiten el cifrado para búsquedas. Las *balizas estándar* realizan búsquedas de igualdad. Las *balizas compuestas* combinan cadenas literales de texto no cifrado y balizas estándar para realizar operaciones complejas de bases de datos. Después de [configurar las balizas](configure-beacons.md), debe configurar un índice secundario para cada baliza antes de poder buscar en los campos cifrados. Para obtener más información, consulte [Configurar índices secundarios con balizas](ddb-searchable-encryption.md#ddb-beacon-indexes).
**Topics**
+ [Balizas estándar](#standard-beacon-overview)
+ [Balizas compuestas](#compound-beacon-overview)
## Balizas estándar
Las balizas estándar son la forma más sencilla de implementar el cifrado para búsquedas en su base de datos. Solo pueden realizar búsquedas de igualdad para un único campo virtual o cifrado. Para obtener información sobre cómo configurar balizas estándar, consulte [Configuración de balizas estándar](configure-beacons.md#config-standard-beacons).
El campo a partir del cual se construye una baliza estándar se denomina la *fuente de baliza*. Identifica la ubicación de los datos que la baliza necesita mapear. La fuente de la baliza puede ser un campo cifrado o un *campo virtual*. La fuente de baliza de cada baliza estándar debe ser única. No puede configurar dos balizas con la misma fuente de baliza.
Las balizas estándar se pueden utilizar para realizar búsquedas de igualdad en un campo cifrado o virtual. O bien, se pueden usar para construir balizas compuestas para realizar operaciones de bases de datos más complejas. Para ayudarlo a organizar y administrar las balizas estándar, el SDK de cifrado de AWS bases de datos proporciona los siguientes *estilos de balizas* opcionales que definen el uso previsto de una baliza estándar. Para obtener más información, consulte [Definición de estilos de baliza.](configure-beacons.md#define-beacon-styles)
Puede crear una baliza estándar que realice búsquedas de igualdad para un único campo cifrado, o puede crear una baliza estándar que realice búsquedas de igualdad en la concatenación de varios `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campos y `ENCRYPT_AND_SIGN``SIGN_ONLY`, creando un campo virtual.
**Campos virtuales**
Un campo virtual es un campo conceptual creado a partir de uno o más campos de origen. Al crear un campo virtual no se graba un campo nuevo en el registro. El campo virtual no se almacena de forma explícita en la base de datos. Se utiliza en la configuración de baliza estándar para dar instrucciones a la baliza sobre cómo identificar un segmento específico de un campo o concatenar varios campos de un registro para realizar una consulta específica. Un campo virtual requiere al menos un campo cifrado.
El siguiente ejemplo muestra los tipos de transformaciones y consultas que se pueden realizar con un campo virtual. En la aplicación, es posible que los campos de ejemplo utilizados en este ejemplo no cumplan con las recomendaciones de unicidad de [distribución](searchable-encryption.md#searchable-encryption-distribution) y [correlación](searchable-encryption.md#searchable-encryption-correlated-values) para las balizas.
Por ejemplo, si desea realizar búsquedas de igualdad en la concatenación de los campos `FirstName` y `LastName`, puede crear uno de los siguientes campos virtuales.
+ Un campo virtual `NameTag`, construido a partir de la primera letra del campo `FirstName`, seguida del campo `LastName`, todo en minúsculas. Este campo virtual le permite realizar consultas `NameTag=mjones`.
+ Un campo virtual `LastFirst`, que se construye a partir del campo `LastName`, seguido del campo `FirstName`. Este campo virtual le permite realizar consultas `LastFirst=JonesMary`.
O bien, si desea realizar búsquedas de igualdad en un segmento específico de un campo cifrado, cree un campo virtual que identifique el segmento que desea consultar.
Por ejemplo, si desea consultar un campo `IPAddress` cifrado con los tres primeros segmentos de la dirección IP, cree el siguiente campo virtual.
+ Un campo virtual `IPSegment`, construido a partir de `Segments(‘.’, 0, 3)`. Este campo virtual le permite realizar consultas `IPSegment=192.0.2`. La consulta devuelve todos los registros con un valor `IPAddress` que comienza por “192.0.2”.
Los campos virtuales deben ser únicos. No se pueden construir dos campos virtuales a partir exactamente de los mismos campos de origen.
Para obtener ayuda para configurar los campos virtuales y las balizas que los utilizan, consulte [Creación de un campo virtual](configure-beacons.md#create-virtual-field).
## Balizas compuestas
Las balizas compuestas crean índices que mejoran el rendimiento de las consultas y permiten realizar operaciones de base de datos más complejas. Puede utilizar balizas compuestas para combinar cadenas literales de texto no cifrado y balizas estándar para realizar consultas complejas en registros cifrados, como consultar dos tipos de registros diferentes desde un único índice o consultar una combinación de campos con una clave de clasificación. Para ver más ejemplos de soluciones de baliza compuesta, consulte [Elegir un tipo de baliza](choosing-beacon-type.md).
Las balizas compuestas se pueden construir a partir de balizas estándar o de una combinación de balizas estándar y campos señalizados. Se construyen a partir de una lista de piezas. Todas las balizas compuestas deben incluir una lista de [partes cifradas](configure-beacons.md#encrypted-parts) que identifique los `ENCRYPT_AND_SIGN` campos incluidos en la baliza. Cada `ENCRYPT_AND_SIGN` campo debe identificarse mediante una baliza estándar. Las balizas compuestas más complejas también pueden incluir una lista de [partes firmadas](configure-beacons.md#signed-parts) que identifique el texto sin formato `SIGN_ONLY` o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` los campos incluidos en la baliza, y una lista de [partes constructivas](configure-beacons.md#constructor-parts) que identifique todas las formas posibles en que la baliza compuesta puede ensamblar los campos.
**nota**
El SDK AWS de cifrado de bases de datos también admite *balizas firmadas* que se pueden configurar completamente a partir de texto sin formato `SIGN_ONLY` y campos. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Las balizas firmadas son un tipo de baliza compuesta que indexan y realizan consultas complejas en campos firmados, pero no cifrados. Para obtener más información, consulte [Crear balizas firmadas](configure.md#signed-beacons).
Para obtener ayuda para configurar balizas compuestas, consulte [Configuración de balizas compuestas](configure-beacons.md#config-compound-beacons).
La forma en que configure su baliza compuesta determina los tipos de consultas que puede realizar. Por ejemplo, puede hacer que algunas partes cifradas y firmadas sean opcionales para permitir una mayor flexibilidad en sus consultas. Para obtener más información sobre los tipos de consultas que pueden realizar las balizas compuestas, consulte [Balizas de consulta](using-beacons.md#querying-beacons).
# Planificación de balizas
****
| |
| --- |
| 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). |
Las balizas están diseñadas para su implementación en bases de datos nuevas y despobladas. Cualquier baliza configurada en una base de datos existente solo mapeará los nuevos registros escritos en la base de datos. Las balizas se calculan a partir del valor de texto no cifrado de un campo. Una vez cifrado el campo, la baliza no tiene forma de mapear los datos existentes. Una vez que haya escrito nuevos registros con una baliza, no puede actualizar la configuración de la baliza. Sin embargo, puede agregar balizas nuevas para los campos nuevos que agregue a su registro.
Para implementar un cifrado que permita realizar búsquedas, debe usar el [conjunto de claves de AWS KMS jerárquico](use-hierarchical-keyring.md) para generar, cifrar y descifrar las claves de datos que se utilizan para proteger sus registros. Para obtener más información, consulte [Uso del conjunto de claves jerárquico para el cifrado para búsquedas](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings).
Antes de poder configurar [balizas](searchable-encryption.md#beacon-definition) para el cifrado para búsquedas, debe revisar sus requisitos de cifrado, los patrones de acceso a las bases de datos y el modelo de amenazas para determinar cuál es la mejor solución para su base de datos.
El [tipo de baliza](beacons.md) que configure determina el tipo de consultas que puede realizar. La [longitud de la baliza](choosing-beacon-length.md) que especifique en la configuración de baliza estándar determina el número esperado de falsos positivos producidos para una baliza determinada. Recomendamos encarecidamente identificar y planificar los tipos de consultas que debe realizar antes de configurar las balizas. Una vez que haya utilizado una baliza, la configuración no se puede actualizar.
Le recomendamos encarecidamente que revise y complete las siguientes tareas antes de configurar cualquier baliza.
+ [Determine si las balizas son adecuadas para su conjunto de datos](searchable-encryption.md#are-beacons-right-for-me)
+ [Elija un tipo de baliza](choosing-beacon-type.md)
+ [Elija una longitud de baliza](choosing-beacon-length.md)
+ [Elija un nombre de baliza](choosing-beacon-name.md)
Recuerde los siguientes requisitos de exclusividad de las balizas al planificar la solución de cifrado para búsquedas para su base de datos.
+ **Cada baliza estándar debe tener una [fuente de baliza única](beacons.md#beacon-source)**
No se pueden construir varias balizas estándar a partir del mismo campo virtual o cifrado.
Sin embargo, se puede usar una única baliza estándar para construir múltiples balizas compuestas.
+ **Evite crear un campo virtual con campos de origen que se superpongan con las balizas estándar existentes**
La construcción de una baliza estándar a partir de un campo virtual que contiene un campo de origen que se utilizó para crear otra baliza estándar puede reducir la seguridad de ambas balizas.
Para obtener más información, consulte [Aspectos de seguridad para campos virtuales](configure-beacons.md#virtual-field-considerations).
## Consideraciones para bases de datos de multitenencia
Para consultar las balizas configuradas en una base de datos de multitenencia, debe incluir el campo que almacena la `branch-key-id` asociada al inquilino que cifró el registro en la consulta. Este campo se define al [definir la fuente de la clave de la baliza](use-hierarchical-keyring.md#beacon-key-source). Para que la consulta se realice correctamente, el valor de este campo debe identificar los materiales clave de baliza adecuados necesarios para volver a calcular la baliza.
Antes de configurar las balizas, debe decidir cómo las va a incluir `branch-key-id` en las consultas. Para obtener más información sobre las diferentes formas en que puede incluirlos `branch-key-id` en sus consultas, visite [Consulta de balizas en una base de datos de multitenencia](searchable-encryption-multitenant.md#query-multitenant-beacons).
# Elección de un tipo de baliza
****
| |
| --- |
| 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). |
Con el cifrado que permite realizar búsquedas, puede buscar registros cifrados asignando con una *baliza* los valores de texto no cifrado de un campo cifrado. El tipo de baliza que configure determina el tipo de consultas que puede realizar.
Recomendamos encarecidamente identificar y planificar los tipos de consultas que debe realizar antes de configurar las balizas. Después de [configurar las balizas](configure-beacons.md), debe configurar un índice secundario para cada baliza antes de poder buscar en los campos cifrados. Para obtener más información, consulte [Configurar índices secundarios con balizas](ddb-searchable-encryption.md#ddb-beacon-indexes).
Las balizas crean un mapa entre el valor de texto no cifrado escrito en un campo y el valor cifrado que está realmente almacenado en la base de datos. No se pueden comparar los valores de dos balizas estándar, aunque contengan el mismo texto no cifrado subyacente. Las dos balizas estándar generarán dos etiquetas HMAC diferentes para los mismos valores de texto no cifrado. Como resultado, las balizas estándar no pueden realizar las siguientes consultas.
+ `beacon1 = beacon2`
+ `beacon1 IN (beacon2)`
+ `value IN (beacon1, beacon2, ...)`
+ `CONTAINS(beacon1, beacon2)`
Solo puede realizar las consultas anteriores si compara las [partes firmadas](configure-beacons.md#signed-parts) de las balizas compuestas, con la excepción del `CONTAINS` operador, que puede utilizar con las balizas compuestas para identificar el valor total de un campo cifrado o firmado que contenga la baliza ensamblada. Al comparar partes firmadas, si lo desea, puede incluir el prefijo de una [parte cifrada](configure-beacons.md#encrypted-parts), pero no puede incluir el valor cifrado de un campo. Para obtener más información sobre los tipos de consultas que pueden realizar las balizas estándar y compuestas, consulte [Consulta de balizas](using-beacons.md#querying-beacons).
Tenga en cuenta las siguientes soluciones de cifrado con capacidad de búsqueda al revisar los patrones de acceso a la base de datos. Los siguientes ejemplos definen qué baliza se debe configurar para satisfacer los diferentes requisitos de cifrado y consulta.
## Balizas estándar
[Las balizas estándar](beacons.md#standard-beacon-overview) solo pueden realizar búsquedas de igualdad. Puede utilizar balizas estándar para llevar a cabo las siguientes consultas.
### Consulte un único campo cifrado
Si desea identificar los registros que contienen un valor específico para un campo cifrado, cree un indicador estándar.
#### Ejemplos
Para el siguiente ejemplo, considere una base de datos denominada `UnitInspection` que rastrea los datos de inspección de una planta de producción. Cada registro de la base de datos contiene campos denominados `work_id`, `inspection_date`, `inspector_id_last4` y `unit`. El ID completo del inspector es un número comprendido entre 0 y 99 999 999. Sin embargo, para garantizar que el conjunto de datos se distribuya de manera uniforme, `inspector_id_last4` solo almacena los últimos cuatro dígitos del ID del inspector. Cada campo de la base de datos se identifica mediante la clave principal `work_id`. Los campos `inspector_id_last4` y `unit` están marcados `ENCRYPT_AND_SIGN` en las [acciones criptográficas](concepts.md#crypt-actions).
A continuación, se muestra un ejemplo de una entrada de texto no cifrado en la `UnitInspection` base de datos.
```
{
"work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b",
"inspection_date": 2023-06-07,
"inspector_id_last4": 8744,
"unit": 229304973450
}
```
**Consulte un único campo cifrado de un registro**
Si es necesario cifrar el campo `inspector_id_last4`, pero aun así necesita consultarlo para obtener coincidencias exactas, cree una baliza estándar a partir del campo `inspector_id_last4`. A continuación, utilice la baliza estándar para crear un índice secundario. Puede utilizar este índice secundario para realizar consultas en el `inspector_id_last4` campo cifrado.
Para obtener ayuda para configurar balizas estándar, consulte [Configuración de balizas estándar](configure-beacons.md#config-standard-beacons).
### Consulte un campo virtual
Un [campo virtual](beacons.md#virtual-field) es un campo conceptual creado a partir de uno o más campos de origen. Si desea realizar búsquedas de igualdad para un segmento específico de un campo cifrado o realizar búsquedas de igualdad en la concatenación de varios campos, cree una baliza estándar a partir de un campo virtual. Todos los campos virtuales deben incluir al menos un campo de origen cifrado.
#### Ejemplos
Los siguientes ejemplos crean campos virtuales para la base de datos de `Employees`. A continuación, se muestra un ejemplo de un registro de texto no cifrado de la base de datos de `Employees`.
```
{
"EmployeeID": 101,
"SSN": 000-00-0000,
"LastName": "Jones",
"FirstName": "Mary",
"Address": {
"Street": "123 Main",
"City": "Anytown",
"State": "OH",
"ZIPCode": 12345
}
}
```
**Consulte un segmento de un campo cifrado**
En este ejemplo, el campo `SSN` está cifrado.
Si desea consultar el campo `SSN` con los últimos cuatro dígitos de un número de seguro social, cree un campo virtual que identifique el segmento que desea consultar.
Un `Last4SSN` campo virtual, creado a partir de `Suffix(4)`, le permite realizar consultas`Last4SSN=0000`. Utilice este campo virtual para construir una baliza estándar. A continuación, utilice la baliza estándar para crear un índice secundario. Puede utilizar este índice secundario para realizar consultas en el campo virtual. Esta consulta devuelve todos los registros con un valor `SSN` que termina en los últimos cuatro dígitos que especificó.
**Consulte la concatenación de varios campos**
El siguiente ejemplo muestra los tipos de transformaciones y consultas que se pueden realizar con un campo virtual. En la aplicación, es posible que los campos de ejemplo utilizados en este ejemplo no cumplan con las recomendaciones de unicidad de [distribución](searchable-encryption.md#searchable-encryption-distribution) y [correlación](searchable-encryption.md#searchable-encryption-correlated-values) para las balizas.
Si desea realizar búsquedas de igualdad en una concatenación de los campos `FirstName` y `LastName`, puede crear un campo `NameTag` virtual, construido a partir de la primera letra del campo `FirstName`, seguida del campo `LastName`, todo en minúsculas. Utilice este campo virtual para construir una baliza estándar. A continuación, utilice la baliza estándar para crear un índice secundario. Puede utilizar este índice secundario para realizar consultas `NameTag=mjones` en el campo virtual.
Al menos uno de los campos de origen debe estar cifrado. Bien sea `FirstName` o `LastName` puede estar cifrado, o ambos pueden estar cifrados. [Todos los campos fuente de texto sin formato deben marcarse como acciones criptográficas `SIGN_ONLY` o figurar `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` en ellas.](concepts.md#crypt-actions)
Para obtener ayuda para configurar los campos virtuales y las balizas que los utilizan, consulte [Creación de un campo virtual](configure-beacons.md#create-virtual-field).
## Balizas compuestas
[Las balizas compuestas](beacons.md#compound-beacon-overview) crean un índice a partir de cadenas literales de texto no cifrado y balizas estándar para realizar operaciones complejas de bases de datos. Puede utilizar balizas compuestas para realizar las siguientes consultas.
### Consulte una combinación de campos cifrados en un único índice
Si necesita consultar una combinación de campos cifrados en un único índice, cree una baliza compuesta que combine las balizas estándar individuales creadas para cada campo cifrado para formar un índice único.
Tras configurar la baliza compuesta, puede crear un índice secundario que especifique la baliza compuesta como clave de partición para realizar consultas de coincidencia exacta o con una clave de clasificación para realizar consultas más complejas. Los índices secundarios que especifican la baliza compuesta como clave de clasificación pueden realizar consultas de coincidencia exacta y consultas complejas más personalizadas.
#### Ejemplos
Para los siguientes ejemplos, considere una base de datos denominada `UnitInspection` que rastrea los datos de inspección de una instalación de producción. Cada registro de la base de datos contiene campos denominados `work_id`, `inspection_date`, `inspector_id_last4` y `unit`. El ID completo del inspector es un número comprendido entre 0 y 99 999 999. Sin embargo, para garantizar que el conjunto de datos se distribuya de manera uniforme, `inspector_id_last4` solo almacena los últimos cuatro dígitos del ID del inspector. Cada campo de la base de datos se identifica mediante la clave principal `work_id`. Los campos `inspector_id_last4` y `unit` están marcados `ENCRYPT_AND_SIGN` en las [acciones criptográficas](concepts.md#crypt-actions).
A continuación, se muestra un ejemplo de una entrada de texto no cifrado en la base de datos `UnitInspection`.
```
{
"work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b",
"inspection_date": 2023-06-07,
"inspector_id_last4": 8744,
"unit": 229304973450
}
```
**Realice búsquedas de igualdad en una combinación de campos cifrados**
Si desea consultar en la `UnitInspection` base de datos las coincidencias exactas en `inspector_id_last4.unit`, cree primero balizas estándar distintas para los campos `inspector_id_last4` y `unit`. A continuación, cree una baliza compuesta a partir de las dos balizas estándar.
Después de configurar la baliza compuesta, cree un índice secundario que especifique la baliza compuesta como clave de partición. Utilice este índice secundario para buscar coincidencias exactas en `inspector_id_last4.unit`. Por ejemplo, puede consultar esta baliza para encontrar una lista de las inspecciones que un inspector realizó en una unidad determinada.
**Realice consultas complejas en una combinación de campos cifrados**
Si desea consultar la `UnitInspection` base de datos en `inspector_id_last4` y `inspector_id_last4.unit`, primero, cree balizas estándar distintas para los campos `inspector_id_last4` y `unit`. A continuación, cree una baliza compuesta a partir de las dos balizas estándar.
Después de configurar la baliza compuesta, cree un índice secundario que especifique la baliza compuesta como clave de clasificación. Utilice este índice secundario para consultar en la `UnitInspection` base de datos las entradas que comiencen por un inspector determinado o consulte la base de datos para obtener una lista de todas las unidades dentro de un rango de ID de unidades específico que fueron inspeccionadas por un inspector determinado. También puede realizar búsquedas de coincidencias exactas en `inspector_id_last4.unit`.
Para obtener ayuda para configurar balizas compuestas, consulte [Configuración de balizas compuestas](configure-beacons.md#config-compound-beacons).
### Consulte una combinación de campos cifrados y de texto no cifrado en un único índice
Si necesita consultar una combinación de campos cifrados y de texto no cifrado en un solo índice, cree un indicador compuesto que combine balizas estándar individuales y campos de texto no cifrado para formar un índice único. [Los campos de texto sin formato utilizados para construir la baliza compuesta deben estar marcados `SIGN_ONLY` o figurar `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` en sus acciones criptográficas.](concepts.md#crypt-actions)
Después de configurar la baliza compuesta, puede crear un índice secundario que especifique la baliza compuesta como clave de partición para realizar consultas de coincidencia exacta o con una clave de clasificación para realizar consultas más complejas. Los índices secundarios que especifican la baliza compuesta como clave de clasificación pueden realizar consultas de coincidencia exacta y consultas complejas más personalizadas.
#### Ejemplos
Para los siguientes ejemplos, considere una base de datos denominada `UnitInspection` que rastrea los datos de inspección de una instalación de producción. Cada registro de la base de datos contiene campos denominados `work_id`, `inspection_date`, `inspector_id_last4` y `unit`. El ID completo del inspector es un número comprendido entre 0 y 99 999 999. Sin embargo, para garantizar que el conjunto de datos se distribuya de manera uniforme, `inspector_id_last4` solo almacena los últimos cuatro dígitos del ID del inspector. Cada campo de la base de datos se identifica mediante la clave principal `work_id`. Los campos `inspector_id_last4` y `unit` están marcados `ENCRYPT_AND_SIGN` en las [acciones criptográficas](concepts.md#crypt-actions).
A continuación, se muestra un ejemplo de una entrada de texto no cifrado en la base de datos `UnitInspection`.
```
{
"work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b",
"inspection_date": 2023-06-07,
"inspector_id_last4": 8744,
"unit": 229304973450
}
```
**Realice búsquedas de igualdad en una combinación de campos**
Si desea consultar en la base de datos de `UnitInspection` las inspecciones realizadas por un inspector específico en una fecha específica, cree primero una baliza estándar para el campo `inspector_id_last4`. El campo `inspector_id_last4` está marcado `ENCRYPT_AND_SIGN` en las [acciones criptográficas](concepts.md#crypt-actions). Todas las partes cifradas requieren su propia baliza estándar. El campo `inspection_date` está marcado `SIGN_ONLY` y no requiere una baliza estándar. A continuación, cree una baliza compuesta desde el campo`inspection_date` y la baliza `inspector_id_last4` estándar.
Después de configurar la baliza compuesta, cree un índice secundario que especifique la baliza compuesta como clave de partición. Utilice este índice secundario para consultar en las bases de datos los registros que coincidan exactamente con un inspector y una fecha de inspección determinados. Por ejemplo, puede consultar la base de datos para obtener una lista de todas las inspecciones que el inspector cuya ID termina en `8744` realizó en una fecha específica.
**Realice consultas complejas en una combinación de campos**
Si desea consultar en la base de datos las inspecciones realizadas dentro de un intervalo de `inspection_date`, o consultar en la base de datos las inspecciones realizadas en un determinado ámbito `inspection_date` limitado por `inspector_id_last4` o `inspector_id_last4.unit`, primero, cree balizas estándar distintas para los campos `inspector_id_last4` y `unit`. A continuación, cree una baliza compuesta a partir del campo `inspection_date` de texto no cifrado y de las dos balizas estándar.
Después de configurar la baliza compuesta, cree un índice secundario que especifique la baliza compuesta como clave de clasificación. Utilice este índice secundario para realizar consultas sobre las inspecciones realizadas en fechas específicas por un inspector específico. Por ejemplo, puede consultar la base de datos para obtener una lista de todas las unidades inspeccionadas en la misma fecha. O bien, puede consultar la base de datos para obtener una lista de todas las inspecciones realizadas en una unidad específica en un intervalo determinado de fechas de inspección.
Para obtener ayuda para configurar balizas compuestas, consulte [Configuración de balizas compuestas](configure-beacons.md#config-compound-beacons).
# Elegir la longitud de una baliza
****
| |
| --- |
| Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el [cliente de cifrado de DynamoDB](legacy-dynamodb-encryption-client.md). |
Al escribir un valor nuevo en un campo cifrado que está configurado para el cifrado con capacidad de búsqueda, el SDK de cifrado de AWS bases de datos calcula un HMAC sobre el valor del texto simple. Esta salida del HMAC coincide uno a uno (1:1) con el valor de texto no cifrado de ese campo. La salida del HMAC se trunca para que varios valores de texto no cifrado distintos se asignen a la misma etiqueta HMAC truncada. Estas colisiones, o *falsos positivos*, limitan la capacidad de un usuario no autorizado de identificar información distintiva sobre el valor del texto no cifrado.
El número medio de falsos positivos generados por cada baliza viene determinado por la longitud de la baliza restante tras el truncamiento. Solo es necesario definir la longitud de la baliza al configurar las balizas estándar. Las balizas compuestas utilizan las longitudes de baliza de las balizas estándar con las que están construidas.
La baliza no altera el estado cifrado del campo. Sin embargo, cuando se utilizan balizas, existe un equilibrio inherente entre la eficacia de las consultas y la cantidad de información que se revela sobre la distribución de los datos.
El objetivo del cifrado con capacidad de búsqueda es reducir los costos de rendimiento asociados a las bases de datos cifradas del cliente mediante el uso de balizas para realizar consultas sobre datos cifrados. Las balizas se almacenan junto a los campos cifrados a partir de los cuales se calculan. Esto significa que pueden revelar información distintiva sobre la distribución de su conjunto de datos. En casos extremos, un usuario no autorizado podría analizar la información revelada sobre su distribución y utilizarla para identificar el valor de texto no cifrado de un campo. Elegir la longitud de baliza correcta puede ayudar a mitigar estos riesgos y preservar la confidencialidad de la distribución.
Revise su modelo de amenazas para determinar el nivel de seguridad que necesita. Por ejemplo, cuantas más personas tengan acceso a su base de datos, pero que no deberían tener acceso a los datos en texto no cifrado, más querrá proteger la confidencialidad de la distribución de su conjunto de datos. Para aumentar la confidencialidad, una baliza debe generar más falsos positivos. El aumento de la confidencialidad reduce el rendimiento de las consultas.
**Seguridad en comparación con rendimiento**
+ Una longitud de baliza **demasiado larga** produce muy pocos falsos positivos y podría revelar información distintiva sobre la distribución del conjunto de datos.
+ Una longitud de baliza **demasiado corta** produce demasiados falsos positivos y aumenta el costo de rendimiento de las consultas, porque requiere un análisis más amplio de la base de datos.
Al determinar la longitud de baliza adecuada para su solución, debe encontrar una longitud que preserve adecuadamente la seguridad de sus datos sin afectar el rendimiento de las consultas más de lo estrictamente necesario. El grado de seguridad que conserva una baliza depende de la [distribución](searchable-encryption.md#searchable-encryption-distribution) del conjunto de datos y de la [correlación](searchable-encryption.md#searchable-encryption-correlated-values) de los campos a partir de los cuales se construyen las balizas. En los temas siguientes, se parte del supuesto de que las balizas están distribuidas de manera uniforme y no contienen datos relacionados entre sí.
**Topics**
+ [Calcular la longitud de la baliza](#calculate-beacon-length)
+ [Ejemplo](#beacon-length-example)
## Calcular la longitud de la baliza
La longitud de la baliza se define en *bits* y se refiere al número de bits de la etiqueta HMAC que se conservan tras el truncamiento. La longitud de baliza recomendada varía en función de la distribución del conjunto de datos, la presencia de valores relacionados entre sí y los requisitos específicos de seguridad y rendimiento. Si su conjunto de datos está distribuido de manera uniforme, puede usar las siguientes ecuaciones y procedimientos para ayudarse a identificar la mejor longitud de baliza para su implementación. Estas ecuaciones solo estiman el número promedio de falsos positivos que producirá la baliza, pero no garantizan que cada valor único del conjunto de datos produzca un número específico de falsos positivos.
**nota**
La eficacia de estas ecuaciones depende de la distribución del conjunto de datos. Si su conjunto de datos no está distribuido uniformemente, consulte [¿Las balizas son adecuadas para mi conjunto de datos?](searchable-encryption.md#are-beacons-right-for-me).
En general, cuanto más lejos esté el conjunto de datos de una distribución uniforme, más necesitará acortar la longitud de la baliza.
1.
**Calcula la población**
La población es el número esperado de valores únicos en el campo a partir del cual se construye la baliza estándar, no el número total esperado de valores almacenados en el campo. Por ejemplo, considere un `Room` campo cifrado que identifique la ubicación de las reuniones de los empleados. Se espera que el `Room` campo almacene 100 000 valores en total, pero solo hay 50 salas diferentes que los empleados pueden reservar para reuniones. Esto significa que la población es de 50 porque solo hay 50 valores únicos posibles que se pueden almacenar en el `Room` campo.
**nota**
Si la baliza estándar se construye a partir de un [campo virtual](beacons.md#virtual-field), la población utilizada para calcular la longitud de la baliza es el número de combinaciones únicas creadas por el campo virtual.
Al estimar la población, asegúrese de tener en cuenta el crecimiento proyectado del conjunto de datos. Una vez que haya escrito nuevos registros con la baliza, no podrá actualizar la longitud de la baliza. Revise su modelo de amenazas y cualquier solución de base de datos existente para crear una estimación del número de valores únicos que espera que este campo almacene en los próximos cinco años.
Su población no tiene por qué ser precisa. En primer lugar, identifique el número de valores únicos en su base de datos actual o calcule el número de valores únicos que espera almacenar durante el primer año. A continuación, utilice las siguientes preguntas para determinar el crecimiento proyectado de los valores únicos en los próximos cinco años.
+ ¿Espera que los valores únicos se multipliquen por 10?
+ ¿Espera que los valores únicos se multipliquen por 100?
+ ¿Espera que los valores únicos se multipliquen por 1000?
La diferencia entre los valores únicos 50 000 y 60 000 no es significativa y ambos darán como resultado la misma longitud de baliza recomendada. Sin embargo, la diferencia entre los valores únicos 50 000 y 500 000 afectará considerablemente la longitud de baliza recomendada.
Considere la posibilidad de revisar los datos públicos sobre la frecuencia de los tipos de datos más comunes, como los códigos postales o los apellidos. Por ejemplo, hay 41 707 códigos postales en los Estados Unidos. La población que utilice debe ser proporcional a su propia base de datos. Si el `ZIPCode` campo de la base de datos incluye datos de todos los Estados Unidos, puede definir su población como 41 707, incluso si el `ZIPCode` campo no tiene *actualmente* 41 707 valores únicos. Si el `ZIPCode` campo de la base de datos solo incluye datos de un estado y siempre incluirá datos de un solo estado, entonces puede definir su población como el número total de códigos postales de ese estado en lugar de 41 704.
1. **Calcule el rango recomendado para el número esperado de colisiones**
Para determinar la longitud de baliza adecuada para un campo determinado, primero debe identificar un rango adecuado para el número esperado de colisiones. El número esperado de colisiones representa el número promedio esperado de valores únicos de texto no cifrado que se asignan a una etiqueta HMAC concreta. El número esperado de falsos positivos para un valor único de texto no cifrado es uno menos que el número esperado de colisiones.
Recomendamos que el número esperado de colisiones sea mayor o igual a dos e inferior a la raíz cuadrada de la población. Las siguientes ecuaciones solo funcionan si la población tiene 16 o más valores únicos.
```
2 ≤ number of collisions < √(Population)
```
Si el número de colisiones es inferior a dos, la baliza producirá muy pocos falsos positivos. Recomendamos dos como número mínimo de colisiones esperadas porque significa que, en promedio, cada valor único del campo generará al menos un falso positivo al asignarlo a otro valor único.
1. **Calcule el rango recomendado para las longitudes de baliza**
Tras identificar el número mínimo y máximo de colisiones esperadas, utilice la siguiente ecuación para identificar un rango de longitudes de baliza adecuadas.
```
number of collisions = Population * 2-(beacon length)
```
En primer lugar, calcule la **longitud de la baliza**, donde el número de colisiones esperadas es igual a dos (el número mínimo recomendado de colisiones esperadas).
```
2 = Population * 2-(beacon length)
```
A continuación, calcule la **longitud de la baliza**, donde el número esperado de colisiones es igual a la raíz cuadrada de tu población (el número máximo recomendado de colisiones esperadas).
```
√(Population) = Population * 2-(beacon length)
```
Recomendamos redondear el resultado que produce esta ecuación a la longitud de baliza más corta. Por ejemplo, si la ecuación produce una longitud de baliza de 15,6, recomendamos redondear ese valor a 15 bits en lugar de redondearlo al alza a 16 bits.
1. **Elija una longitud de baliza**
Estas ecuaciones solo identifican un rango recomendado de longitudes de baliza para su campo. Recomendamos utilizar una longitud de baliza más corta para preservar la seguridad del conjunto de datos siempre que sea posible. Sin embargo, la longitud de la baliza que utilice realmente viene determinada por el modelo de amenaza. Tenga en cuenta sus requisitos de rendimiento al revisar su modelo de amenazas para determinar la mejor longitud de baliza para su campo.
El uso de una longitud de baliza más corta reduce el rendimiento de las consultas, mientras que el uso de una longitud de baliza más larga reduce la seguridad. En general, si el conjunto de datos está [distribuido](searchable-encryption.md#searchable-encryption-distribution) de forma desigual, o si se construyen balizas distintas a partir de campos [relacionados entre sí](searchable-encryption.md#searchable-encryption-correlated-values), es necesario utilizar longitudes de baliza más cortas para minimizar la cantidad de información revelada sobre la distribución de los conjunto de datos.
Si revisa su modelo de amenazas y decide que cualquier información distintiva revelada sobre la distribución de un campo no representa una amenaza para su seguridad general, puede optar por utilizar una longitud de baliza superior al rango recomendado que calculó. Por ejemplo, si ha calculado el rango recomendado de longitudes de baliza para un campo de 9 a 16 bits, puede optar por utilizar una longitud de baliza de 24 bits para evitar cualquier pérdida de rendimiento.
Elija la longitud de la baliza con cuidado. Una vez que haya escrito nuevos registros con la baliza, no podrá actualizar la longitud de la baliza.
## Ejemplo
Considere una base de datos que marcara el `unit` campo como `ENCRYPT_AND_SIGN` parte de las [acciones criptográficas](concepts.md#crypt-actions). Para configurar una baliza estándar para el `unit` campo, necesitamos determinar el número esperado de falsos positivos y la longitud de la baliza para el `unit` campo.
1. Haga un estimado de la población
Tras revisar nuestro modelo de amenazas y nuestra solución de base de datos actual, esperamos que el `unit` campo acabe teniendo 100 000 valores únicos.
Esto significa que la **Población = 100 000**.
1. Calcule el rango recomendado para el número esperado de colisiones.
Para este ejemplo, el número esperado de colisiones debe estar entre 2 y 316.
```
2 ≤ number of collisions < √(Population)
```
1.
```
2 ≤ number of collisions < √(100,000)
```
1.
```
2 ≤ number of collisions < 316
```
1. Calcule el rango recomendado para la longitud de la baliza.
Para este ejemplo, la longitud de la baliza debe estar entre 9 y 16 bits.
```
number of collisions = Population * 2-(beacon length)
```
1. Calcule la longitud de la baliza cuando el número esperado de colisiones sea igual al mínimo identificado en el **Paso 2**.
```
2 = 100,000 * 2-(beacon length)
```
Longitud de la baliza = 15,6 o 15 bits
1. Calcule la longitud de la baliza cuando el número esperado de colisiones sea igual al máximo identificado en el **Paso 2**.
```
316 = 100,000 * 2-(beacon length)
```
Longitud de la baliza = 8,3 u 8 bits
1. Determine la longitud de baliza adecuada para sus requisitos de seguridad y rendimiento.
Por cada bit inferior a 15, el costo de rendimiento y la seguridad se duplican.
+ 16 bits
+ En promedio, cada valor único se asignará a otras 1,5 unidades.
+ Seguridad: dos registros con la misma etiqueta HMAC truncada tienen un 66% de probabilidades de tener el mismo valor de texto no cifrado.
+ Rendimiento: una consulta recuperará 15 registros por cada 10 registros que realmente haya solicitado.
+ 14 bits
+ En promedio, cada valor único se asignará a otras 6,1 unidades.
+ Seguridad: dos registros con la misma etiqueta HMAC truncada tienen un 33% de probabilidades de tener el mismo valor de texto no cifrado.
+ Rendimiento: una consulta recuperará 30 registros por cada 10 registros que realmente haya solicitado.
# Elección de un nombre de baliza
****
| |
| --- |
| 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). |
Cada baliza se identifica con un *nombre de baliza* único. Una vez configurada una baliza, el nombre de la baliza es el nombre que se utiliza para consultar un campo cifrado. El nombre de una baliza puede ser el mismo nombre que un campo cifrado o un [campo virtual](beacons.md#virtual-field), pero no puede ser el mismo nombre que un campo no cifrado. Dos balizas diferentes no pueden tener el mismo nombre de baliza.
Para ver ejemplos que muestran cómo nombrar y configurar balizas, consulte [Configuración de balizas](configure-beacons.md).
**Denominación de baliza estándar**
Al nombrar las balizas estándar, recomendamos encarecidamente que el nombre de la baliza se refiera a la [*fuente de la baliza*](beacons.md#beacon-source) siempre que sea posible. Esto significa que el nombre de la baliza y el nombre del campo cifrado o [virtual](beacons.md#virtual-field) a partir del cual se construye la baliza estándar son los mismos. Por ejemplo, si va a crear una baliza estándar para un campo cifrado denominado `LastName`, el nombre de la baliza también debería ser `LastName`.
Si el nombre de la baliza es el mismo que el de la fuente de la baliza, puede omitirla de la configuración y el SDK de cifrado de AWS bases de datos utilizará automáticamente el nombre de la baliza como fuente de la baliza.
# Configuración de las balizas
****
| |
| --- |
| 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). |
Existen dos tipos de balizas que admiten el cifrado para búsquedas. Las balizas estándar realizan búsquedas de igualdad. Son la forma más sencilla de implementar el cifrado para búsquedas en su base de datos. Las balizas compuestas combinan cadenas literales de texto no cifrado y balizas estándar para realizar consultas más complejas.
Las balizas están diseñadas para su implementación en bases de datos nuevas y despobladas. Cualquier baliza configurada en una base de datos existente solo mapeará los nuevos registros escritos en la base de datos. Las balizas se calculan a partir del valor de texto no cifrado de un campo. Una vez cifrado el campo, la baliza no tiene forma de mapear los datos existentes. Una vez que haya escrito nuevos registros con una baliza, no puede actualizar la configuración de la baliza. Sin embargo, puede agregar balizas nuevas para los campos nuevos que agregue a su registro.
Una vez determinados los patrones de acceso, la configuración de las balizas debería ser el segundo paso de la implementación de la base de datos. A continuación, después de configurar todas las balizas, debe crear un conjunto de [claves AWS KMS jerárquico](use-hierarchical-keyring.md), definir la versión de las balizas, [configurar un índice secundario para cada](ddb-searchable-encryption.md#ddb-beacon-indexes) baliza, definir las [acciones criptográficas](concepts.md#crypt-actions) y configurar la base de datos y el cliente del SDK de cifrado de bases de datos. AWS Para obtener más información, consulte [Utilizar balizas](using-beacons.md).
Para facilitar la definición de la versión de baliza, recomendamos crear listas de balizas estándar y compuestas. Agregue cada baliza que cree a la lista de balizas estándar o compuestas correspondiente a medida que las vaya configurando.
**Topics**
+ [Configuración de balizas estándar](#config-standard-beacons)
+ [Configuración de balizas compuestas](#config-compound-beacons)
+ [Configuraciones de ejemplo](beacon-config-examples.md)
## Configuración de balizas estándar
[Las balizas estándar](beacons.md#standard-beacon-overview) son la forma más sencilla de implementar el cifrado para búsquedas en su base de datos. Solo pueden realizar búsquedas de igualdad para un único campo virtual o cifrado.
### Ejemplo de sintaxis de configuración
------
#### [ Java ]
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
------
#### [ C\$1 / .NET ]
```
var standardBeaconList = new List();
StandardBeacon exampleStandardBeacon = new StandardBeacon
{
Name = "beaconName",
Length = 10
};
standardBeaconList.Add(exampleStandardBeacon);
```
------
#### [ Rust ]
```
let standard_beacon_list = vec con el que se construye la baliza estándar. Dos balizas diferentes no pueden tener el mismo nombre de baliza. Para obtener ayuda para determinar el mejor nombre de baliza para su implementación, consulte [Elegir un nombre de baliza](choosing-beacon-name.md).
**Longitud de la baliza**
El número de bits del valor hash de la baliza que se conservan tras el truncamiento.
La longitud de la baliza determina el número medio de falsos positivos producidos por una baliza determinada. Para obtener más información y ayuda para determinar la longitud de baliza adecuada para su implementación, consulte [Determinar la longitud de la baliza](choosing-beacon-length.md).
**Fuente de la baliza (opcional)**
El campo a partir del cual se construye una baliza estándar.
La fuente de la baliza debe ser un nombre de campo o un índice que haga referencia al valor de un campo anidado. Si el nombre de la baliza es el mismo que el de la fuente de la baliza, puede omitir la fuente de la baliza de la configuración y el SDK de cifrado de AWS bases de datos utilizará automáticamente el nombre de la baliza como fuente de la baliza.
### Creación de un campo virtual
Para crear un [campo virtual](beacons.md#virtual-field), debe proporcionar un nombre para el campo virtual y una lista de los campos de origen. El orden en que se agregan los campos de origen a la lista de piezas virtuales determina el orden en que se concatenan para crear el campo virtual. El siguiente ejemplo concatena dos campos de origen en su totalidad para crear un campo virtual.
**nota**
Recomendamos comprobar que los campos virtuales producen el resultado esperado antes de rellenar la base de datos. Para obtener más información, consulte [Probar los resultados de las balizas](ddb-searchable-encryption.md#ddb-beacon-testing).
------
#### [ Java ]
**Consulta el ejemplo de código completo**: [VirtualBeaconSearchableEncryptionExample.java](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)
```
List virtualPartList = new ArrayList<>();
virtualPartList.add(sourceField1);
virtualPartList.add(sourceField2);
VirtualField virtualFieldName = VirtualField.builder()
.name("virtualFieldName")
.parts(virtualPartList)
.build();
List virtualFieldList = new ArrayList<>();
virtualFieldList.add(virtualFieldName);
```
------
#### [ C\$1 / .NET ]
**[Vea el ejemplo de código completo: .cs VirtualBeaconSearchableEncryptionExample](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/VirtualBeaconSearchableEncryptionExample.cs)**
```
var virtualPartList = new List { sourceField1, sourceField2 };
var virtualFieldName = new VirtualField
{
Name = "virtualFieldName",
Parts = virtualPartList
};
var virtualFieldList = new List { virtualFieldName };
```
------
#### [ Rust ]
**Consulta 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)
```
let virtual_part_list = vec![source_field_one, source_field_two];
let state_and_has_test_result_field = VirtualField::builder()
.name("virtual_field_name")
.parts(virtual_part_list)
.build()?;
let virtual_field_list = vec![virtual_field_name];
```
------
Para crear un campo virtual con un segmento específico de un campo de origen, debe definir esa transformación antes de agregar el campo de origen a la lista de piezas virtuales.
#### Aspectos de seguridad para campos virtuales
Las balizas no alteran el estado cifrado del campo. Sin embargo, cuando se utilizan balizas, existe un equilibrio inherente entre la eficacia de las consultas y la cantidad de información que se revela sobre la distribución de los datos. La forma en que configura su baliza determina el nivel de seguridad que preserva esa baliza.
Evite crear un campo virtual con campos de origen que se superpongan con las balizas estándar existentes. La creación de campos virtuales que incluyan un campo de origen que ya se haya utilizado para crear una baliza estándar puede reducir el nivel de seguridad de ambas balizas. La medida en que se reduzca la seguridad depende del nivel de entropía agregado por los campos de origen adicionales. El nivel de entropía está determinado por la distribución de valores únicos en el campo de origen adicional y el número de bits que el campo de origen adicional aporta al tamaño total del campo virtual.
Puede usar la población y la [longitud de la baliza](choosing-beacon-length.md) para determinar si los campos de origen de un campo virtual preservan la seguridad del conjunto de datos. La población es el número esperado de valores únicos en un campo. Su población no tiene por qué ser precisa. Para obtener ayuda para estimar la población de un campo, consulte [Estimar la población](choosing-beacon-length.md#estimate-population).
Considere el siguiente ejemplo al revisar la seguridad de sus campos virtuales.
+ Beacon1 se construye a partir de `FieldA`. `FieldA`tiene una población superior a **2 (longitud de Beacon1)**.
+ Beacon2 se construye a partir de `VirtualField`, que se construye a partir de `FieldA`, `FieldB`, `FieldC` y `FieldD`. Juntos, `FieldB`, `FieldC` y `FieldD` tienen una población superior a **2N**
Beacon2 preserva la seguridad tanto de Beacon1 como de Beacon2 si se cumplen las siguientes afirmaciones:
```
N ≥ (Beacon1 length)/2
```
and
```
N ≥ (Beacon2 length)/2
```
### Definir estilos de balizas
Las balizas estándar se pueden utilizar para realizar búsquedas de igualdad en un campo cifrado o virtual. O bien, se pueden usar para construir balizas compuestas para realizar operaciones de bases de datos más complejas. Para ayudarlo a organizar y administrar las balizas estándar, el SDK de cifrado de AWS bases de datos proporciona los siguientes *estilos de balizas* opcionales que definen el uso previsto de una baliza estándar.
**nota**
Para definir los estilos de balizas, debe usar la versión 3.2 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de añadir estilos de baliza a las configuraciones de baliza.
------
#### [ PartOnly ]
Una baliza estándar definida como solo se `PartOnly` puede utilizar para definir una [parte cifrada](#encrypted-parts) de una baliza compuesta. No se puede consultar directamente una baliza `PartOnly` estándar.
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.partOnly(PartOnly.builder().build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1/.NET**
```
new StandardBeacon
{
Name = "beaconName",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
PartOnly = new PartOnly()
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon_name")
.length(beacon_length_in_bits)
.style(BeaconStyle::PartOnly(PartOnly::builder().build()?))
.build()?
```
------
#### [ Shared ]
De forma predeterminada, cada baliza estándar genera una clave HMAC única para el cálculo de la baliza. Como resultado, no se puede realizar una búsqueda de igualdad en los campos cifrados de dos balizas estándar independientes. Una baliza estándar definida como `Shared` utiliza la clave HMAC de otra baliza estándar para sus cálculos.
Por ejemplo, si necesita comparar `beacon1` campos con otros `beacon2` campos, defínalo `beacon2` como un `Shared` indicador que utilice la clave HMAC de `beacon1` para sus cálculos.
**nota**
Tenga en cuenta sus necesidades de seguridad y rendimiento antes de configurar cualquier `Shared` baliza. `Shared`las balizas pueden aumentar la cantidad de información estadística que se puede identificar sobre la distribución del conjunto de datos. Por ejemplo, pueden revelar qué campos compartidos contienen el mismo valor de texto sin formato.
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beacon2")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.shared(Shared.builder().other("beacon1").build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1/.NET**
```
new StandardBeacon
{
Name = "beacon2",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
Shared = new Shared { Other = "beacon1" }
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon2")
.length(beacon_length_in_bits)
.style(BeaconStyle::Shared(
Shared::builder().other("beacon1").build()?,
))
.build()?
```
------
#### [ AsSet ]
De forma predeterminada, si el valor de un campo es un conjunto, el SDK de cifrado de AWS bases de datos calcula una única baliza estándar para el conjunto. Como resultado, no se puede realizar la consulta `CONTAINS(a, :value)` si `a` hay un campo cifrado. Una baliza estándar definida como `AsSet` calcula los valores de baliza estándar individuales para cada elemento individual del conjunto y almacena el valor de la baliza en el elemento como un conjunto. Esto permite que el SDK AWS de cifrado de bases de datos realice la consulta`CONTAINS(a, :value)`.
Para definir una baliza `AsSet` estándar, los elementos del conjunto deben ser de la misma población para que todos puedan utilizar la misma [longitud de baliza](choosing-beacon-length.md). El conjunto de balizas podría tener menos elementos que el conjunto de texto sin formato si se produjeran colisiones al calcular los valores de las balizas.
**nota**
Tenga en cuenta sus necesidades de seguridad y rendimiento antes de configurar cualquier `AsSet` baliza. `AsSet`las balizas pueden aumentar la cantidad de información estadística que se puede identificar sobre la distribución del conjunto de datos. Por ejemplo, pueden revelar el tamaño del conjunto de texto sin formato.
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.asSet(AsSet.builder().build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1/.NET**
```
new StandardBeacon
{
Name = "beaconName",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
AsSet = new AsSet()
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon_name")
.length(beacon_length_in_bits)
.style(BeaconStyle::AsSet(AsSet::builder().build()?))
.build()?
```
------
#### [ SharedSet ]
Una baliza estándar definida como `SharedSet` combina las `AsSet` funciones `Shared` y para que puedas realizar búsquedas de igualdad en los valores cifrados de un conjunto y un campo. Esto permite que el SDK de cifrado de AWS bases de datos realice la consulta `CONTAINS(a, b)` cuando `a` hay un conjunto cifrado y `b` un campo cifrado.
**nota**
Tenga en cuenta sus necesidades de seguridad y rendimiento antes de configurar cualquier `Shared` baliza. `SharedSet`las balizas pueden aumentar la cantidad de información estadística que se puede identificar sobre la distribución del conjunto de datos. Por ejemplo, pueden revelar el tamaño del conjunto de texto sin formato o qué campos compartidos contienen el mismo valor de texto sin formato.
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beacon2")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.sharedSet(SharedSet.builder().other("beacon1").build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1/.NET**
```
new StandardBeacon
{
Name = "beacon2",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
SharedSet = new SharedSet { Other = "beacon1" }
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon2")
.length(beacon_length_in_bits)
.style(BeaconStyle::SharedSet(
SharedSet::builder().other("beacon1").build()?,
))
.build()?
```
------
## Configuración de balizas compuestas
Las balizas compuestas combinan cadenas literales de texto no cifrado y balizas estándar para realizar operaciones complejas de bases de datos, como consultar dos tipos de registros diferentes desde un único índice o consultar una combinación de campos con una clave de clasificación. Las balizas compuestas se pueden construir a partir de `ENCRYPT_AND_SIGN``SIGN_ONLY`, y `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campos. Debe crear una baliza estándar para cada campo cifrado incluido en la baliza compuesta.
**nota**
Se recomienda comprobar que las balizas compuestas producen el resultado esperado antes de rellenar la base de datos. Para obtener más información, consulte [Probar](ddb-searchable-encryption.md#ddb-beacon-testing) las salidas de las balizas.
### Ejemplo de sintaxis de configuración
------
#### [ Java ]
**Configuración de baliza compuesta**
El siguiente ejemplo define las listas de piezas cifradas y firmadas localmente dentro de la configuración de baliza compuesta.
```
List compoundBeaconList = new ArrayList<>();
CompoundBeacon exampleCompoundBeacon = CompoundBeacon.builder()
.name("compoundBeaconName")
.split(".")
.encrypted(encryptedPartList)
.signed(signedPartList)
.constructors(constructorList)
.build();
compoundBeaconList.add(exampleCompoundBeacon);
```
**Definición de la versión de baliza**
El siguiente ejemplo define las listas de piezas cifradas y firmadas de forma global en la versión de baliza. Para obtener más información sobre cómo definir la versión de baliza, consulte [Uso de balizas](using-beacons.md).
```
List beaconVersions = new ArrayList<>();
beaconVersions.add(
BeaconVersion.builder()
.standardBeacons(standardBeaconList)
.compoundBeacons(compoundBeaconList)
.encryptedParts(encryptedPartList)
.signedParts(signedPartList)
.version(1) // MUST be 1
.keyStore(keyStore)
.keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branchKeyId)
.cacheTTL(6000)
.build())
.build())
.build()
);
```
------
#### [ C\$1 / .NET ]
**[Consulte el ejemplo de código completo: .cs BeaconConfig](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/complexexample/BeaconConfig.cs)**
**Configuración de baliza compuesta**
El siguiente ejemplo define las listas de piezas cifradas y firmadas localmente dentro de la configuración de baliza compuesta.
```
var compoundBeaconList = new List();
var exampleCompoundBeacon = new CompoundBeacon
{
Name = "compoundBeaconName",
Split = ".",
Encrypted = encryptedPartList,
Signed = signedPartList,
Constructors = constructorList
};
compoundBeaconList.Add(exampleCompoundBeacon);
```
**Definición de la versión de baliza**
El siguiente ejemplo define las listas de piezas cifradas y firmadas de forma global en la versión de baliza. Para obtener más información sobre cómo definir la versión de baliza, consulte [Uso de balizas](using-beacons.md).
```
var beaconVersions = new List
{
new BeaconVersion
{
StandardBeacons = standardBeaconList,
CompoundBeacons = compoundBeaconList,
EncryptedParts = encryptedPartsList,
SignedParts = signedPartsList,
Version = 1, // MUST be 1
KeyStore = keyStore,
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branchKeyId,
CacheTTL = 6000
}
}
}
};
```
------
#### [ Rust ]
**Consulte el ejemplo de código completo**[: beacon\$1config.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/complexexample/beacon_config.rs)
**Configuración de baliza compuesta**
El siguiente ejemplo define las listas de piezas cifradas y firmadas localmente dentro de la configuración de baliza compuesta.
```
let compound_beacon_list = vec.
```
let beacon_versions = BeaconVersion::builder()
.standard_beacons(standard_beacon_list)
.compound_beacons(compound_beacon_list)
.encrypted_parts(encrypted_parts_list)
.signed_parts(signed_parts_list)
.version(1) // MUST be 1
.key_store(key_store.clone())
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
.build()?;
let beacon_versions = vec![beacon_versions];
```
------
Puede definir [las partes cifradas y las partes](#encrypted-parts) [firmadas](#signed-parts) en listas definidas local o globalmente. Siempre que sea posible, le recomendamos que defina las partes cifradas y firmadas en una lista global en la [versión de baliza](using-beacons.md#beacon-version). Al definir las partes cifradas y firmadas de forma global, puede definir cada parte una vez y, a continuación, reutilizarlas en varias configuraciones de balizas compuestas. Si solo piensa utilizar una parte cifrada o firmada una vez, puede definirla en una lista local en la configuración de baliza compuesta. Puede hacer referencia a partes locales y globales en su [lista de constructores](#constructor-parts).
Si define sus listas de piezas cifradas y firmadas de forma global, debe proporcionar una lista de las partes constructoras que identifique todas las formas posibles en que la baliza compuesta puede ensamblar los campos en su configuración de baliza compuesta.
**nota**
Para definir listas de piezas cifradas y firmadas de forma global, debe utilizar la versión 3.2 o posterior del SDK de cifrado de AWS bases de datos. Implemente la nueva versión en todos los lectores antes de definir cualquier pieza nueva a nivel mundial.
No puede actualizar las configuraciones de balizas existentes para definir listas de piezas cifradas y firmadas a nivel mundial.
Para configurar una baliza compuesta, proporcione los siguientes valores.
**Nombre de la baliza**
El nombre que se utiliza al consultar un campo cifrado.
El nombre de un indicador puede ser el mismo nombre que un campo cifrado o un campo virtual, pero no puede ser el mismo nombre que un campo no cifrado. No puede haber dos balizas con el mismo nombre de baliza. Para obtener ayuda para determinar el mejor nombre de baliza para su implementación, consulte [Elección de un nombre de baliza](choosing-beacon-name.md).
**Carácter dividido**
El personaje que se usa para separar las partes que conforman su baliza compuesta.
El carácter dividido no puede aparecer en los valores de texto no cifrado de ninguno de los campos a partir de los que se construye la baliza compuesta.
**Lista de piezas cifradas**
Identifica los campos `ENCRYPT_AND_SIGN` incluidos en la baliza compuesta.
Cada pieza debe incluir un nombre y un prefijo. El nombre de la pieza debe ser el nombre de la baliza estándar construida a partir del campo cifrado. El prefijo puede ser cualquier cadena, pero debe ser único. Una parte cifrada no puede tener el mismo prefijo que una parte firmada. Recomendamos utilizar un valor corto que distinga la pieza de otras partes servidas por la baliza compuesta.
Recomendamos definir las piezas cifradas de forma global siempre que sea posible. Podría considerar la posibilidad de definir una parte cifrada de forma local si solo pretende utilizarla en una baliza compuesta. Una parte cifrada definida localmente no puede tener el mismo prefijo o nombre que una parte cifrada definida globalmente.
```
List encryptedPartList = new ArrayList<>();
EncryptedPart encryptedPartExample = EncryptedPart.builder()
.name("standardBeaconName")
.prefix("E-")
.build();
encryptedPartList.add(encryptedPartExample);
```
```
var encryptedPartList = new List();
var encryptedPartExample = new EncryptedPart
{
Name = "compoundBeaconName",
Prefix = "E-"
};
encryptedPartList.Add(encryptedPartExample);
```
```
let encrypted_parts_list = vec![
EncryptedPart::builder()
.name("standard_beacon_name")
.prefix("E-")
.build()?
];
```
**Lista de piezas firmadas**
Identifica los campos firmados incluidos en la baliza compuesta.
Las partes firmadas son opcionales. Puede configurar una baliza compuesta que no haga referencia a ninguna parte firmada.
Cada parte debe incluir un nombre, una fuente y un prefijo. La fuente es el `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campo `SIGN_ONLY` o que identifica la pieza. La fuente debe ser un nombre de campo o un índice que haga referencia al valor de un campo anidado. Si el nombre de la pieza identifica la fuente, puede omitirla y el SDK de cifrado de AWS bases de datos utilizará automáticamente el nombre como fuente. Recomendamos especificar la fuente como nombre de la pieza siempre que sea posible. El prefijo puede ser cualquier cadena, pero debe ser único. Una pieza firmada no puede tener el mismo prefijo que una parte cifrada. Recomendamos utilizar un valor corto que distinga la pieza de otras partes servidas por la baliza compuesta.
Recomendamos definir las piezas firmadas de forma global siempre que sea posible. Podría considerar la posibilidad de definir una pieza firmada de forma local si solo tiene intención de utilizarla en una baliza compuesta. Una parte firmada definida localmente no puede tener el mismo prefijo o nombre que una parte firmada definida globalmente.
```
List signedPartList = new ArrayList<>();
SignedPart signedPartExample = SignedPart.builder()
.name("signedFieldName")
.prefix("S-")
.build();
signedPartList.add(signedPartExample);
```
```
var signedPartsList = new List
{
new SignedPart { Name = "signedFieldName1", Prefix = "S-" },
new SignedPart { Name = "signedFieldName2", Prefix = "SF-" }
};
```
```
let signed_parts_list = vec![
SignedPart::builder()
.name("signed_field_name_1")
.prefix("S-")
.build()?,
SignedPart::builder()
.name("signed_field_name_2")
.prefix("SF-")
.build()?,
];
```
**Lista de constructores**
Identifica los *constructores* que definen las diferentes formas en que la baliza compuesta puede ensamblar las piezas cifradas y firmadas. Puede hacer referencia a partes locales y globales en su lista de constructores.
Si crea su baliza compuesta a partir de partes firmadas y cifradas definidas globalmente, debe proporcionar una lista de constructores.
Si no utiliza ninguna parte cifrada o firmada definida globalmente para construir la baliza compuesta, la lista de constructores es opcional. Si no especificas una lista de constructores, el SDK de cifrado AWS de bases de datos ensambla la baliza compuesta con el siguiente constructor predeterminado.
+ Todas las piezas firmadas en el orden en que se agregaron a la lista de piezas firmadas
+ Todas las piezas cifradas en el orden en que se agregaron a la lista de piezas cifradas
+ Todas las piezas son obligatorias
**Constructores**
Cada constructor es una lista ordenada de *piezas del constructor* que define una forma en la que se puede ensamblar la baliza compuesta. Las piezas del constructor se unen en el orden en que se agregan a la lista, con cada parte separada por el carácter dividido especificado.
Cada parte del constructor nombra una parte cifrada o una parte firmada y define si esa parte es obligatoria u opcional en el constructor. Por ejemplo, si desea consultar una baliza compuesta sobre `Field1`, `Field1.Field2` y `Field1.Field2.Field3`, marque `Field2` y `Field3` como opcional y cree un constructor.
Cada constructor debe tener como mínimo una pieza requerida. Recomendamos hacer que la primera parte de cada constructor sea obligatoria para poder usar el operador `BEGINS_WITH` en las consultas.
Un constructor tiene éxito si todas las piezas requeridas están presentes en el registro. Al escribir un registro nuevo, la baliza compuesta utiliza la lista de constructores para determinar si la baliza se puede ensamblar a partir de los valores proporcionados. Intente ensamblar la baliza en el orden en que se agregaron los constructores a la lista de constructores y utilice el primer constructor que lo haga correctamente. Si ningún constructor tiene éxito, la baliza no se graba en el registro.
Todos los lectores y redactores deben especificar el mismo orden de constructores para garantizar que los resultados de sus consultas sean correctos.
Utilice los siguientes procedimientos para especificar su propia lista de constructores.
1. Cree una parte constructora para cada pieza cifrada y firmada para definir si esa pieza es necesaria o no.
El nombre de la pieza constructora debe ser el nombre de la baliza estándar o el campo firmado que representa.
------
#### [ Java ]
```
ConstructorPart field1ConstructorPart = ConstructorPart.builder()
.name("Field1")
.required(true)
.build();
```
------
#### [ C\$1 / .NET ]
```
var field1ConstructorPart = new ConstructorPart { Name = "Field1", Required = true };
```
------
#### [ Rust ]
```
let field_1_constructor_part = ConstructorPart::builder()
.name("field_1")
.required(true)
.build()?;
```
------
1. Cree un constructor para cada forma posible de ensamblaje de la baliza compuesta utilizando las piezas constructoras que creó en el **Paso 1**.
Por ejemplo, si desea consultar sobre `Field1.Field2.Field3` y `Field4.Field2.Field3`, debe crear dos constructores. Tanto `Field1` como `Field4` pueden ser necesarios porque están definidos en dos constructores distintos.
------
#### [ Java ]
```
// Create a list for Field1.Field2.Field3 queries
List field123ConstructorPartList = new ArrayList<>();
field123ConstructorPartList.add(field1ConstructorPart);
field123ConstructorPartList.add(field2ConstructorPart);
field123ConstructorPartList.add(field3ConstructorPart);
Constructor field123Constructor = Constructor.builder()
.parts(field123ConstructorPartList)
.build();
// Create a list for Field4.Field2.Field1 queries
List field421ConstructorPartList = new ArrayList<>();
field421ConstructorPartList.add(field4ConstructorPart);
field421ConstructorPartList.add(field2ConstructorPart);
field421ConstructorPartList.add(field1ConstructorPart);
Constructor field421Constructor = Constructor.builder()
.parts(field421ConstructorPartList)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a list for Field1.Field2.Field3 queries
var field123ConstructorPartList = new Constructor
{
Parts = new List { field1ConstructorPart, field2ConstructorPart, field3ConstructorPart }
};
// Create a list for Field4.Field2.Field1 queries
var field421ConstructorPartList = new Constructor
{
Parts = new List { field4ConstructorPart, field2ConstructorPart, field1ConstructorPart }
};
```
------
#### [ Rust ]
```
// Create a list for field1.field2.field3 queries
let field1_field2_field3_constructor = Constructor::builder()
.parts(vec![
field1_constructor_part,
field2_constroctor_part.clone(),
field3_constructor_part,
])
.build()?;
// Create a list for field4.field2.field1 queries
let field4_field2_field1_constructor = Constructor::builder()
.parts(vec![
field4_constructor_part,
field2_constroctor_part.clone(),
field1_constructor_part,
])
.build()?;
```
------
1. Cree una lista de constructores que incluya todos los constructores que creó en el **Paso 2**.
------
#### [ Java ]
```
List constructorList = new ArrayList<>();
constructorList.add(field123Constructor);
constructorList.add(field421Constructor);
```
------
#### [ C\$1 / .NET ]
```
var constructorList = new List
{
field123Constructor,
field421Constructor
};
```
------
#### [ Rust ]
```
let constructor_list = vec![
field1_field2_field3_constructor,
field4_field2_field1_constructor,
];
```
------
1. Especifica el `constructorList` momento de crear la baliza compuesta.
# Configuraciones de ejemplo
****
| |
| --- |
| 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 los ejemplos siguientes, se muestra cómo configurar balizas estándar y compuestas. Las siguientes configuraciones no proporcionan longitudes de baliza. Para obtener ayuda para determinar la longitud adecuada de la baliza para su configuración, consulte [Elegir longitud de una baliza](choosing-beacon-length.md).
Para ver ejemplos de código completos que muestran cómo configurar y usar balizas, consulte los ejemplos de cifrado con capacidad de búsqueda en [Java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption), [.NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/) y [Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/) en el aws-database-encryption-sdk repositorio -dynamodb de. GitHub
**Topics**
+ [Balizas estándar](#standard-config-examples)
+ [Balizas compuestas](#compound-config-examples)
## Balizas estándar
Si desea consultar las coincidencias exactas en el campo `inspector_id_last4`, cree una baliza estándar con la siguiente configuración.
------
#### [ Java ]
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("inspector_id_last4")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
------
#### [ C\$1 / .NET ]
```
var standardBeaconList = new List>);
StandardBeacon exampleStandardBeacon = new StandardBeacon
{
Name = "inspector_id_last4",
Length = 10
};
standardBeaconList.Add(exampleStandardBeacon);
```
------
#### [ Rust ]
```
let last4_beacon = StandardBeacon::builder()
.name("inspector_id_last4")
.length(10)
.build()?;
let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;
let standard_beacon_list = vec![last4_beacon, unit_beacon];
```
------
## Balizas compuestas
Si desea consultar la `UnitInspection` base de datos sobre `inspector_id_last4` y `inspector_id_last4.unit`, cree una baliza compuesta con la siguiente configuración. Esta baliza compuesta solo requiere [partes cifradas](configure-beacons.md#encrypted-parts).
------
#### [ Java ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
List standardBeaconList = new ArrayList<>();
StandardBeacon inspectorBeacon = StandardBeacon.builder()
.name("inspector_id_last4")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(inspectorBeacon);
StandardBeacon unitBeacon = StandardBeacon.builder()
.name("unit")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(unitBeacon);
// 2. Define the encrypted parts.
List encryptedPartList = new ArrayList<>();
// Each encrypted part needs a name and prefix
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
EncryptedPart encryptedPartInspector = EncryptedPart.builder()
.name("inspector_id_last4")
.prefix("I-")
.build();
encryptedPartList.add(encryptedPartInspector);
EncryptedPart encryptedPartUnit = EncryptedPart.builder()
.name("unit")
.prefix("U-")
.build();
encryptedPartList.add(encryptedPartUnit);
// 3. Create the compound beacon.
// This compound beacon only requires a name, split character,
// and list of encrypted parts
CompoundBeacon inspectorUnitBeacon = CompoundBeacon.builder()
.name("inspectorUnitBeacon")
.split(".")
.sensitive(encryptedPartList)
.build();
```
------
#### [ C\$1 / .NET ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
StandardBeacon inspectorBeacon = new StandardBeacon
{
Name = "inspector_id_last4",
Length = 10
};
standardBeaconList.Add(inspectorBeacon);
StandardBeacon unitBeacon = new StandardBeacon
{
Name = "unit",
Length = 30
};
standardBeaconList.Add(unitBeacon);
// 2. Define the encrypted parts.
var last4EncryptedPart = new EncryptedPart
// Each encrypted part needs a name and prefix
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
var last4EncryptedPart = new EncryptedPart
{
Name = "inspector_id_last4",
Prefix = "I-"
};
encryptedPartList.Add(last4EncryptedPart);
var unitEncryptedPart = new EncryptedPart
{
Name = "unit",
Prefix = "U-"
};
encryptedPartList.Add(unitEncryptedPart);
// 3. Create the compound beacon.
// This compound beacon only requires a name, split character,
// and list of encrypted parts
var compoundBeaconList = new List>);
var inspectorCompoundBeacon = new CompoundBeacon
{
Name = "inspector_id_last4",
Split = ".",
Encrypted = encryptedPartList
};
compoundBeaconList.Add(inspectorCompoundBeacon);
```
------
#### [ Rust ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
let last4_beacon = StandardBeacon::builder()
.name("inspector_id_last4")
.length(10)
.build()?;
let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;
let standard_beacon_list = vec![last4_beacon, unit_beacon];
// 2. Define the encrypted parts.
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
let encrypted_parts_list = vec![
EncryptedPart::builder()
.name("inspector_id_last4")
.prefix("I-")
.build()?,
EncryptedPart::builder().name("unit").prefix("U-").build()?,
];
// 3. Create the compound beacon
// This compound beacon only requires a name, split character,
// and list of encrypted parts
let compound_beacon_list = vec![CompoundBeacon::builder()
.name("last4UnitCompound")
.split(".")
.encrypted(encrypted_parts_list)
.build()?];
```
------
# Uso de balizas
****
| |
| --- |
| 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). |
Las balizas permiten buscar registros cifrados sin necesidad de descifrar toda la base de datos consultada. Las balizas están diseñadas para su implementación en bases de datos nuevas y despobladas. Cualquier baliza configurada en una base de datos existente solo mapeará los nuevos registros escritos en la base de datos. Las balizas se calculan a partir del valor de texto no cifrado de un campo. Una vez cifrado el campo, la baliza no tiene forma de mapear los datos existentes. Una vez que haya escrito nuevos registros con una baliza, no puede actualizar la configuración de la baliza. Sin embargo, puede agregar balizas nuevas para los campos nuevos que agrega a su registro.
Tras configurar las balizas, debe completar los siguientes pasos antes de empezar a rellenar la base de datos y a realizar consultas en las balizas.
1. **Cree un conjunto de claves jerárquico AWS KMS **
Para utilizar 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](concepts.md#data-key) que se utilizan para proteger sus registros.
Después de configurar sus balizas, reúna los requisitos previos del [conjunto de claves jerárquico ](use-hierarchical-keyring.md#hierarchical-keyring-prereqs) y [cree su conjunto de claves jerárquico](use-hierarchical-keyring.md#initialize-hierarchical-keyring).
Para obtener más información sobre por qué se requiere el conjunto de claves jerárquico, consulte [Uso del conjunto de claves jerárquico para el cifrado con capacidad de búsqueda](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings).
1.
**Defina la versión de baliza**
Especifique una lista de todas las balizas estándar que haya configurado, una lista de todas las balizas compuestas que haya configurado, una lista de las partes cifradas, una lista de las partes firmadas y una versión de la baliza. `keyStore` `keySource` Debe especificar la versión `1` de la baliza. Para obtener orientación sobre cómo definir su `keySource`, consulte [Definir la fuente de claves de baliza](use-hierarchical-keyring.md#beacon-key-source).
El siguiente ejemplo de Java define la versión de baliza para una base de datos de un solo inquilino. Para obtener ayuda para definir la versión de baliza para una base de datos de multitenencia, consulte [Cifrado con capacidad de búsqueda para bases de datos de multitenencia](searchable-encryption-multitenant.md).
------
#### [ Java ]
```
List beaconVersions = new ArrayList<>();
beaconVersions.add(
BeaconVersion.builder()
.standardBeacons(standardBeaconList)
.compoundBeacons(compoundBeaconList)
.encryptedParts(encryptedPartsList)
.signedParts(signedPartsList)
.version(1) // MUST be 1
.keyStore(keyStore)
.keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branchKeyId)
.cacheTTL(6000)
.build())
.build())
.build()
);
```
------
#### [ C\$1 / .NET ]
```
var beaconVersions = new List
{
new BeaconVersion
{
StandardBeacons = standardBeaconList,
CompoundBeacons = compoundBeaconList,
EncryptedParts = encryptedPartsList,
SignedParts = signedPartsList,
Version = 1, // MUST be 1
KeyStore = branchKeyStoreName,
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000
}
}
}
};
```
------
#### [ Rust ]
```
let beacon_version = BeaconVersion::builder()
.standard_beacons(standard_beacon_list)
.compound_beacons(compound_beacon_list)
.version(1) // MUST be 1
.key_store(key_store.clone())
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
.build()?;
let beacon_versions = vec![beacon_version];
```
------
1. **Configure los índices secundarios**
Después de [configurar las balizas](configure-beacons.md), debe configurar un índice secundario que refleje cada baliza antes de poder buscar en los campos cifrados. Para obtener más información, consulte [Configurar índices secundarios con balizas](ddb-searchable-encryption.md#ddb-beacon-indexes).
1. **Defina sus acciones [criptográficas](concepts.md#crypt-actions)**
Todos los campos utilizados para construir una baliza estándar deben estar marcados `ENCRYPT_AND_SIGN`. Todos los demás campos utilizados para construir balizas deben estar marcados con o. `SIGN_ONLY` `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
1. **Configure un cliente SDK AWS de cifrado de bases de datos**
Para configurar un cliente SDK AWS de cifrado de bases de datos que proteja los elementos de la tabla de DynamoDB, [consulte la biblioteca de cifrado del lado del cliente de Java para](ddb-java.md) DynamoDB.
## Balizas de consulta
El tipo de baliza que configure determinará el tipo de consultas que podrá realizar. Las balizas estándar utilizan expresiones de filtro para realizar búsquedas de igualdad. Las balizas compuestas combinan cadenas literales de texto no cifrado y balizas estándar para realizar consultas complejas. Al consultar datos cifrados, se busca por el nombre de la baliza.
No se pueden comparar los valores de dos balizas estándar, aunque contengan el mismo texto no cifrado subyacente. Las dos balizas estándar generarán dos etiquetas HMAC diferentes para los mismos valores de texto no cifrado. Como resultado, las balizas estándar no pueden realizar las siguientes consultas.
+ `beacon1 = beacon2`
+ `beacon1 IN (beacon2)`
+ `value IN (beacon1, beacon2, ...)`
+ `CONTAINS(beacon1, beacon2)`
Las balizas compuestas pueden realizar las siguientes consultas.
+ `BEGINS_WITH(a)`, dónde `a` refleja el valor total del campo por el que comienza la baliza compuesta ensamblada. No puede utilizar el `BEGINS_WITH` operador para identificar un valor que comience con una subcadena determinada. Sin embargo, puede usar`BEGINS_WITH(S_)`, donde `S_` refleja el prefijo de una parte por la que comienza la baliza compuesta ensamblada.
+ `CONTAINS(a)`, donde `a` refleja el valor total de un campo que contiene la baliza compuesta ensamblada. No puede usar el `CONTAINS` operador para identificar un registro que contenga una subcadena concreta o un valor dentro de un conjunto.
Por ejemplo, no puede realizar una consulta `CONTAINS(path, "a"` en la que `a` se refleje el valor de un conjunto.
+ Puede comparar [partes firmadas](configure-beacons.md#signed-parts) de balizas compuestas. Al comparar partes firmadas, si lo desea, puede agregar el prefijo de una [parte cifrada](configure-beacons.md#encrypted-parts) a una o más partes firmadas, pero no puede incluir el valor de un campo cifrado en ninguna consulta.
Por ejemplo, puede comparar las partes firmadas y realizar consultas en `signedField1 = signedField2` o `value IN (signedField1, signedField2, ...)`.
También puede comparar las partes firmadas y el prefijo de una parte cifrada consultando `signedField1.A_ = signedField2.B_`.
+ `field BETWEEN a AND b`, donde `a` y `b` son partes firmadas. Si lo desea, puede añadir el prefijo de una parte cifrada a una o más partes firmadas, pero no puede incluir el valor de un campo cifrado en ninguna consulta.
Debe incluir el prefijo de cada parte que incluya en una consulta en una baliza compuesta. Por ejemplo, si ha creado una baliza compuesta, `compoundBeacon`, a partir de dos campos, `encryptedField` y `signedField`, debe incluir los prefijos configurados para esas dos partes cuando consulte la baliza.
```
compoundBeacon = E_encryptedFieldValue.S_signedFieldValue
```
# Cifrado con capacidad de búsqueda para bases de datos multitenencia
****
| |
| --- |
| 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). |
Para implementar un cifrado con capacidad de búsqueda en su base de datos, debe utilizar un [conjunto de claves de AWS KMS jerárquico](use-hierarchical-keyring.md). El conjunto de claves AWS KMS jerárquico genera, cifra y descifra las claves de datos utilizadas para proteger sus registros. También crea la clave de baliza que se utiliza para generar balizas. Cuando se utiliza el conjunto de claves AWS KMS jerárquico con bases de datos multiusuario, hay una clave de rama y una clave de baliza distintas para cada inquilino. Para consultar datos cifrados en una base de datos de multitenencia, debe identificar los materiales clave de baliza utilizados para generar la baliza que está consultando. Para obtener más información, consulte [Uso del conjunto de claves jerárquico para el cifrado para búsquedas](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings).
Al definir la [versión de baliza](using-beacons.md#beacon-version) para una base de datos de multitenencia, especifique una lista de todas las balizas estándar que configuró, una lista de todas las balizas compuestas que configuró, una versión de baliza y una `keySource`. Debe [definir la fuente de claves de baliza](use-hierarchical-keyring.md#beacon-key-source) como una `MultiKeyStore`, e incluir una`keyFieldName`, el tiempo de vida de la caché de claves de baliza local y el tamaño máximo de la caché de claves de baliza local.
Si configuró alguna [baliza firmada](configure.md#signed-beacons), debe incluirla en su `compoundBeaconList`. Las balizas firmadas son un tipo de baliza compuesta que indexan y realizan consultas complejas en los campos y campos. `SIGN_ONLY` `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
------
#### [ Java ]
```
List beaconVersions = new ArrayList<>();
beaconVersions.add(
BeaconVersion.builder()
.standardBeacons(standardBeaconList)
.compoundBeacons(compoundBeaconList)
.version(1) // MUST be 1
.keyStore(branchKeyStoreName)
.keySource(BeaconKeySource.builder()
.multi(MultiKeyStore.builder()
.keyFieldName(keyField)
.cacheTTL(6000)
.maxCacheSize(10)
.build())
.build())
.build()
);
```
------
#### [ C\$1 / .NET ]
```
var beaconVersions = new List
{
new BeaconVersion
{
StandardBeacons = standardBeaconList,
CompoundBeacons = compoundBeaconList,
EncryptedParts = encryptedPartsList,
SignedParts = signedPartsList,
Version = 1, // MUST be 1
KeyStore = branchKeyStoreName,
KeySource = new BeaconKeySource
{
Multi = new MultiKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000,
MaxCacheSize = 10
}
}
}
};
```
------
#### [ Rust ]
```
let beacon_version = BeaconVersion::builder()
.standard_beacons(standard_beacon_list)
.compound_beacons(compound_beacon_list)
.version(1) // MUST be 1
.key_store(key_store.clone())
.key_source(BeaconKeySource::Multi(
MultiKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.max_cache_size(10)
.build()?,
))
.build()?;
let beacon_versions = vec![beacon_version];
```
------
**keyFieldName**
El [`keyFieldName`](use-hierarchical-keyring.md#keyFieldName) define el nombre del campo que almacena la `branch-key-id` asociada a la baliza utilizada para generar las balizas para un inquilino determinado.
Cuando se escriben nuevos registros en la base de datos, en este campo se almacena la `branch-key-id` de baliza utilizada para generar las balizas de ese registro.
De forma predeterminada, el `keyField` es un campo conceptual que no se almacena de forma explícita en la base de datos. El SDK AWS de cifrado de bases de datos identifica la [clave `branch-key-id` de los datos](concepts.md#data-key) cifrados en la [descripción del material](concepts.md#material-description) y almacena el valor en el concepto `keyField` para que pueda consultarlo en las balizas compuestas y balizas [firmadas](configure.md#signed-beacons). Como la descripción del material está firmada, lo conceptual `keyField` se considera una parte firmada.
También puede incluirlo `keyField` en sus acciones criptográficas como un `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campo `SIGN_ONLY` o para almacenar de forma explícita el campo en la base de datos. Si lo hace, debe incluir manualmente el `branch-key-id` en la `keyField` cada vez que escriba un registro en la base de datos.
## Consulta de balizas en una base de datos de multitenencia
Para consultar una baliza, debe incluir la `keyField` en la consulta los materiales clave necesarios para volver a calcular la baliza. Debe especificar la `branch-key-id` asociada a la baliza utilizada para generar las balizas para un registro. No puede especificar el [nombre amigable](use-hierarchical-keyring.md#branch-key-id-supplier) que identifica al `branch-key-id` del inquilino en el proveedor de ID de clave de rama. Puede incluir el `keyField` en sus consultas de las siguientes maneras.
**Balizas compuestas**
Ya sea que las almacene de forma explícita `keyField` en sus registros o no, puede incluir las `keyField` directamente en sus balizas compuestas como una parte firmada. La parte `keyField` firmada debe ser obligatoria.
Por ejemplo, si desea construir una baliza compuesta, `compoundBeacon`, a partir de dos campos, `encryptedField` y `signedField`, también debe incluir la baliza `keyField` como parte firmada. Esto permite realizar la siguiente consulta en `compoundBeacon`.
```
compoundBeacon = E_encryptedFieldValue.S_signedFieldValue.K_branch-key-id
```
**Balizas firmadas**
El SDK AWS de cifrado de bases de datos utiliza balizas estándar y compuestas para proporcionar soluciones de cifrado con capacidad de búsqueda. Estas balizas deben incluir al menos un campo cifrado. Sin embargo, el SDK AWS de cifrado de bases de datos también admite [balizas firmadas](configure.md#signed-beacons) que se pueden configurar completamente a partir de texto sin formato `SIGN_ONLY` y campos. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
Las balizas firmadas se pueden construir a partir de una sola pieza. Ya sea que las almacene de forma explícita `keyField` en sus registros o no, puede crear una baliza firmada a partir de ella `keyField` y utilizarla para crear consultas compuestas que combinen una consulta en la baliza `keyField` firmada con una consulta en una de las otras balizas. Por ejemplo, puede realizar la siguiente consulta.
```
keyField = K_branch-key-id AND compoundBeacon = E_encryptedFieldValue.S_signedFieldValue
```
Si necesita ayuda para configurar las balizas firmadas, consulte [Crear balizas firmadas](configure.md#signed-beacons)
**Realice consultas directamente en el `keyField`**
Si lo especificó `keyField` en sus acciones criptográficas y almacenó el campo de forma explícita en su registro, puede crear una consulta compuesta que combine una consulta de su baliza con una consulta de`keyField`. Puede optar por realizar una consulta directamente en el `keyField` si desea consultar una baliza estándar. Por ejemplo, puede realizar la siguiente consulta.
```
keyField = branch-key-id AND standardBeacon = S_standardBeaconValue
```