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

Esta guía muestra cómo crear una aplicación que implemente la función de Queryable Encryption de MongoDB para encriptar y desencriptar automáticamente campos de documentos y utilizar el Google Cloud Key Management Service 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 Google Cloud Key Management Service

  • Una aplicación cliente funcional que inserta documentos con campos cifrados usando tu 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 crear una cuenta de servicio en Google Cloud, sigue la Guía de creación de una cuenta de servicio guía en la documentación oficial de Google.

Para añadir una clave de cuenta de servicio en Google Cloud, sigue la Guía para gestionar claves de cuentas de servicio en la documentación oficial de Google.

Importante

Apixio will receive a llave privada from an external service. The key must be stored securely and safely, as it cannot be descargada again or retrieved if lost. Asegúrate de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.

2

Crea un anillo de claves y una clave simétrica siguiendo la Crea una clave guía de la documentación oficial de Google.

Esta clave es tu llave maestra de cliente (CMK).

Registre los siguientes detalles de su llave maestra de cliente para usarlos en un paso futuro de este tutorial.

Campo
Requerido
Descripción

key_name

Sí

Identificador para la llave maestra de cliente.

key_ring

Sí

Identificador del grupo de claves al que pertenece su clave.

key_version

No

La versión de la clave nombrada.

Ubicación

Sí

Región especificada para tu clave.

endpoint

No

The host y el Puerto opcional del Google Cloud KMS. El valor por defecto es cloudkms.googleapis.com.

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 "gcp" 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 Google Cloud Key Management Service con la siguiente estructura:

kmsProviderCredentials = { gcp: { email: process.env["GCP_EMAIL"], // Your GCP email privateKey: process.env["GCP_PRIVATE_KEY"], // Your GCP private key },};

Cree una variable que contenga las credenciales de la llave maestra de cliente con la siguiente estructura. Utiliza las credenciales que has registrado en el paso Crear una nueva Clave maestra de cliente de este tutorial.

customerMasterKeyCredentials = { projectId: process.env["GCP_PROJECT_ID"], // Your GCP Project ID location: process.env["GCP_LOCATION"], // Your GCP Key Location keyRing: process.env["GCP_KEY_RING"], // Your GCP Key Ring keyName: process.env["GCP_KEY_NAME"], // Your GCP 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 Google Cloud Key Management Service

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.