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.

Utilice Automatic Queryable Encryption con KMIP

Esta guía te muestra cómo crear una aplicación que implemente la funcionalidad de Queryable Encryption de MongoDB para cifrar y descifrar automáticamente los campos de documentos y utilizar un proveedor de claves compatible con el estándar KMIP (Key Management Interoperability Protocol) para la gestión de claves.

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

  • Una clave maestra de cliente gestionada por un proveedor de claves conforme a KMIP

  • 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 conectar un cliente de driver de MongoDB a tu proveedor de claves compatible con KMIP, debes configurar tu proveedor de claves compatible con KMIPde modo que acepte el certificado TLS de tu cliente.

Consulta la documentación de tu proveedor de claves compatible con KMIPpara obtener información sobre cómo aceptar tu certificado de cliente.

2

Su cliente debe conectarse con su proveedor de claves compatible con KMIPa través de TLS y presentar un certificado de cliente que sea aceptado por su proveedor de claves compatible con KMIP:

const tlsOptions = { kmip: { tlsCAFile: process.env["KMIP_TLS_CA_FILE"], // Path to your TLS CA file tlsCertificateKeyFile: process.env["KMIP_TLS_CERT_FILE"], // Path to your TLS certificate key file },};
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 "kmip" 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 el endpoint de su proveedor de claves compatible con KMIP con la siguiente estructura:

kmsProviderCredentials = { kmip: { endpoint: process.env["KMIP_KMS_ENDPOINT"], // Your KMIP KMS endpoint },};

Cree un objeto vacío como se muestra en el siguiente ejemplo de código. Esto ordena a su proveedor de claves compatible con KMIPque genere una nueva llave maestra de cliente.

customerMasterKeyCredentials = {};

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 tu KMIP endpoint

  • El objeto tlsOptions que creaste en el paso Especifica tus Certificados

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

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.