Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Utilizar Automatic Queryable Encryption con AWS

Esta guía te muestra cómo crear una aplicación que implemente la funcionalidad MongoDB Queryable Encryption para cifrar y descifrar automáticamente los campos de documento y usar Amazon Web Services (AWS) KMS para la gestión de claves.

Después de completar los pasos en esta guía, deberías tener:

  • Una llave maestra de cliente gestionada por AWS KMS

  • Un usuario de AWS IAM con permisos para acceder a la llave maestra de cliente en AWS KMS

  • Una aplicación cliente funcional que inserta documentos con campos cifrados usando su llave maestra de cliente

Tip

llave maestra de cliente

Para obtener más información sobre la llave maestra de cliente, lea la llave de cifrado y almacenes de Llaves documentación.

Para completar y ejecutar el código en esta guía, debes configurar tu entorno de desarrollo como se muestra en la página Instala un Controlador y Dependencias Compatibles con Queryable Encryption.

Tip

Consulta: aplicación completa

Para ver el código completo de esta aplicación de muestra, selecciona la pestaña correspondiente a tu lenguaje de programación y sigue el enlace proporcionado. Cada repositorio de aplicaciones de ejemplo incluye un archivo README.md que puedes utilizar para aprender a configurar tu entorno y ejecutar la aplicación.

1

Cree una nueva clave simétrica siguiendo la documentación oficial de AWS en Creación de claves simétricas de KMS. La clave que crees será tu clave maestra de cliente. Elija un nombre y una descripción que le ayuden a identificarlo; estos campos no afectan la funcionalidad ni la configuración de su llave maestra de cliente.

En el paso Usage Permissions del proceso de generación de claves, aplique la siguiente política de claves por defecto que habilita las políticas de gestión de identidad y acceso (IAM) para conceder acceso a su llave maestra de cliente:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "<ARN of your AWS account principal>" }, "Action": "kms:*", "Resource": "*" } ]}

Importante

Registra el Nombre de recurso de Amazon (ARN) y la región de tu clave maestra de cliente. Los utilizarás más adelante en los siguientes pasos de esta guía.

Tip

Políticas clave

Para obtener más información sobre las políticas clave, consulte Políticas clave en AWS KMS en la documentación oficial de AWS.

2

Crea un nuevo usuario IAM programático en la consola de gestión de AWS siguiendo la documentación oficial de AWS sobre Agregar un usuario. Utilizarás este usuario de IAM como cuenta de servicio para tu aplicación habilitada con cifrado consultable. Su aplicación se autentica con AWS KMS utilizando el usuario IAM para cifrar y descifrar sus llaves de cifrado de datos (DEK) con su llave maestra de cliente (CMK).

Importante

Registra tus credenciales

Asegúrese de registrar las siguientes credenciales de IAM en el paso final de la creación de su usuario IAM:

  • ID de clave de acceso

  • clave secreta de acceso

Tienes una oportunidad para guardar estas credenciales. Si no registra estas credenciales durante este paso, deberá crear otro usuario IAM.

Conceda a su usuario de IAM los permisos kms:Encrypt y kms:Decrypt para su clave maestra remota.

Importante

El nuevo usuario IAM no debe tener permisos administrativos para la clave maestra. Para mantener tus datos seguros, sigue el principio de privilegio mínimo.

La siguiente política inline permite que un usuario IAM cifre y descifre con la clave maestra del cliente con el mínimo privilegio posible:

Nota

ARN de clave maestra remota

La siguiente política requiere el ARN de la clave que usted genera en el paso Crear la Clave Principal de esta guía.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:Encrypt"], "Resource": "<the Amazon Resource Name (ARN) of your remote master key>" } ]}

Para aplicar la política anterior a tu usuario de IAM, sigue la Adición de permisos de identidad de IAM guía en la documentación de AWS.

Importante

Autenticación con IAM Roles en producción

Cuando implementes tu aplicación habilitada para cifrado consultable en un entorno de producción, autentica tu aplicación utilizando un rol de IAM en lugar de un usuario de IAM.

Para obtener más información sobre roles IAM, consulta las siguientes páginas de la documentación oficial de AWS:

1

Los muestras de código de este tutorial utilizan las siguientes variables para llevar a cabo el flujo de trabajo Queryable Encryption:

  • kmsProviderName - El KMS que estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en "aws" para este tutorial.

  • uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno MONGODB_URI o reemplaza directamente el valor.

  • keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Configure esta variable en "encryption".

  • keyVaultCollectionName: la colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a "__keyVault".

  • keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables keyVaultDatabaseName y keyVaultCollectionName, separadas por un punto.

  • encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establece esta variable a "medicalRecords".

  • encryptedCollectionName - La colección en MongoDB donde se almacenarán tus datos cifrados. Establece esta variable a "patients".

Puede declarar estas variables utilizando el siguiente código:

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

Importante

Permisos del namespace de la Colección de Bóvedas de Llaves

La Colección de Bóvedas de Llaves está en el namespace encryption.__keyVault. Asegúrate de que el usuario de la base de datos que tu aplicación usa para conectarse a MongoDB tenga permisos ReadWrite en este namespace.

Tip

Variables de entorno

El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.

Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.

2

Cree una variable que contenga sus credenciales de AWS KMS con la siguiente estructura. Utilice la Clave de acceso ID y la Clave secreta de acceso que creó en el paso Crear un usuario de IAM de este tutorial.

kmsProviderCredentials = { aws: { accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key },};

Importante

Recordatorio: Autenticarse con Roles IAM en Producción

Para usar un rol IAM en lugar de un usuario IAM para autenticar tu aplicación, especifica un objeto vacío para tus credenciales en el objeto de proveedor KMS. Esto le indica al driver que recupere automáticamente las credenciales del entorno:

kmsProviders = { aws: { }};

Cree una variable que contenga sus credenciales de llave maestra de cliente con la siguiente estructura. Usa el ARN y la región que registraste en el paso Crear una clave maestra de cliente de este tutorial.

customerMasterKeyCredentials = { key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN region: process.env["AWS_KEY_REGION"], // Your AWS Key Region};

Crea un objeto autoEncryptionOptions que contiene las siguientes opciones:

  • El espacio de nombres de tu Colección de Bóvedas de Llaves

  • El objeto kmsProviderCredentials, que contiene tus credenciales de AWS KMS

const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials,};

Nota

Opciones de cifrado automático

Las opciones de cifrado automático proporcionan información de configuración a la Librería Compartida de Cifrado Automático, que modifica el comportamiento de la aplicación al acceder a campos cifrados.

Para obtener más información sobre la Biblioteca compartida de cifrado automático, consulta la página Biblioteca compartida de cifrado automático para Queryable Encryption.

Para crear un cliente que se utilice para cifrar y descifrar datos en tu colección, instancia un nuevo MongoClient utilizando tu URI de conexión y tus opciones de cifrado automático.

const encryptedClient = Mongo(uri, autoEncryptionOptions);

Para cifrar un campo, agrégalos al esquema de cifrado. Para habilitar las consultas en un campo, agregue la propiedad "queries". Cree el esquema de cifrado como sigue:

const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};

Nota

En la muestra de código anterior, ambos campos "ssn" y "billing" están cifrados, pero solo se puede query el campo "ssn".

Instancie ClientEncryption para acceder a la API de los métodos de asistente de cifrado.

const clientEncryption = encryptedClient.getClientEncryption()

Crea tu colección cifrada utilizando el método de asistente para cifrar al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, });
3

Crea un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, },}; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
4

El siguiente código de muestra ejecuta una consulta de query en un campo cifrado e imprime los datos descifrados:

const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320",});console.log(findResult);

La salida de la muestra de código anterior debe ser similar a la siguiente:

{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ]}

Advertencia

No modifique el campo __safeContent__

El campo __safeContent__ es esencial para Queryable Encryption. No modifiques el contenido de este campo.

Para aprender cómo funciona Queryable Encryption, consulta Fundamentos de Queryable Encryption.

Para obtener más información sobre los temas mencionados en esta guía, consulta los siguientes enlaces:

  • Aprende más sobre los componentes de Queryable Encryption en la página de Referencia.

  • Aprenda cómo funcionan las llaves maestras de cliente y las claves de cifrado de datos en la página Claves de cifrado y claves secretas.

  • Mira cómo los Proveedores de KMS gestionan tus claves de Encriptación Consultable en la página Proveedores de KMS.