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.

Usa Automatic Queryable Encryption con Azure

Esta guía muestra cómo compilar una aplicación que implemente la funcionalidad de cifrado consultable de MongoDB para cifrar y descifrar automáticamente los campos de documentos y utilizar Azure Key Vault KMS para la gestión de claves.

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

  • Una clave maestra de cliente administrada por Azure Key Vault

  • 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

Para registrar una aplicación en Azure Active Directory, sigue la Guía de inicio rápido oficial de Microsoft Registrar una aplicación con la plataforma de identidad de Microsoft.

Importante

Registra tus credenciales

Asegúrese de registrar las siguientes credenciales:

  • ID de arrendatario

  • ID de cliente

  • Secreto del cliente

Necesita estas credenciales para crear su objeto kmsProviders más adelante en este tutorial. También puedes autenticarse usando un token de acceso o mediante la obtención automática de credenciales. Para conocer todas las formas de credenciales disponibles para Azure, consulte Objeto kmsProviders.

2

Para crear una instancia nueva de Azure Key Vault y una llave maestra de cliente, sigue el establecimiento y recuperación de una clave de Azure Key Vault mediante el portal de Azure inicio rápido oficial de Microsoft.

Importante

Registra tus credenciales

Asegúrese de registrar las siguientes credenciales:

  • Nombre de la clave

  • Identificador clave (denominado keyVaultEndpoint más adelante en esta guía)

  • Versión clave

Los necesitarás para crear tu objeto dataKeyOpts más adelante en este tutorial.

Conceda a su aplicación cliente wrap y unwrap permisos para la clave.

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 "azure" 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

Crea una variable que contenga tus credenciales de KMS de Azure con la siguiente estructura. Utilice las credenciales de Azure Key Vault que registró en el paso Registrar tu aplicación con Azure de este tutorial.

kmsProviderCredentials = { azure: { tenantId: process.env["AZURE_TENANT_ID"], // Your Azure tenant ID clientId: process.env["AZURE_CLIENT_ID"], // Your Azure client ID clientSecret: process.env["AZURE_CLIENT_SECRET"], // Your Azure client secret },};

Cree una variable que contenga sus credenciales de llave maestra de cliente con la siguiente estructura. Utiliza los detalles de la llave maestra de cliente que registraste en el paso Crear una llave maestra de cliente de este tutorial.

customerMasterKeyCredentials = { keyVaultEndpoint: process.env["AZURE_KEY_VAULT_ENDPOINT"], // Your Azure Key Vault Endpoint keyName: process.env["AZURE_KEY_NAME"], // Your Azure Key Name};

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 Azure 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.