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.

Inicio rápido CSFLE

Esta guía te muestra cómo cifrar un documento con el cifrado automático del lado del cliente cifrado a nivel de campo (CSFLE) y un driver de MongoDB.

Después de completar esta guía, deberías tener los siguientes conocimientos y software:

  • Conocimiento de los pasos para configurar un controlador que cifre los campos en un documento.

  • Una aplicación cliente funcional, pero no apta para producción, que utiliza el automático de cifrado a nivel de campo del lado del cliente.

Importante

No utilizar esta aplicación en producción

Dado que esta aplicación de ejemplo almacena una llave de cifrado en el sistema de archivos de tu aplicación, te arriesgas a un acceso no autorizado a la llave o a la pérdida de la llave para descifrar tus datos.

Para ver un tutorial que demuestre cómo crear una aplicación lista para producción habilitada para CSFLE, consulta Tutoriales de CSFLE.

Para completar y ejecutar el código de esta guía, debes configurar tu entorno de desarrollo como se muestra en la página Requisitos de instalación.

Seleccione el lenguaje de programación para el cual desea ver ejemplos de código en el menú desplegable Select your language en el lado derecho de la página.

Tip

Consulta: aplicación completa

Para ver el código completo y ejecutable de la aplicación de este tutorial, visita el siguiente enlace:

// You are viewing the .NET/C# driver code examples.// Use the dropdown menu to select a different driver.
1

Debes crear una clave maestra de cliente (CMK) para realizar CSFLE.

Cree una clave maestra de cliente de 96 bytes y guárdela en su Proveedor de claves local, que es su sistema de archivos, como archivo master-key.txt:

const fs = require("fs");const crypto = require("crypto");try { fs.writeFileSync("master-key.txt", crypto.randomBytes(96));} catch (err) { console.error(err);}

Advertencia

No utilizar el proveedor de clave local en producción

El proveedor de llaves locales es un método de almacenamiento inseguro y no se recomienda para producción. En su lugar, debe almacenar sus llaves maestras de cliente en un Sistema de Gestión de Claves remoto (KMS).

Para aprender a usar un KMS remoto en tu implementación de CSFLE, consulta la guía Tutoriales de CSFLE.

Tip

Genera una llave maestra de cliente desde la línea de comandos

Utiliza el siguiente comando para generar una llave maestra de cliente desde un shell de Unix o PowerShell:

  • Unix/macOS shell:

    echo $(head -c 96 /dev/urandom | base64 | tr -d '\n')
  • PowerShell:

    $r=[byte[]]::new(64);$g=[System.Security.Cryptography.RandomNumberGenerator]::Create();$g.GetBytes($r);[Convert]::ToBase64String($r)

Guarda la salida del comando anterior en un archivo llamado customer-master-key.txt.

Tip

Consultar: Código completo

Para ver el código completo para crear una llave maestra de cliente, consulte nuestro repositorio Github.

2

Crea un índice parcial único en el campo keyAltNames de tu namespace encryption.__keyVault. Este índice debe tener un partialFilterExpression para los documentos donde exista keyAltNames.

El cifrado a nivel de campo del lado del cliente depende de la exclusividad de los nombres alternativos de claves impuesta por el servidor.

Seleccione la pestaña correspondiente al controlador MongoDB preferido:

var connectionString = "<Your MongoDB URI>";var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");var keyVaultClient = new MongoClient(connectionString);var indexOptions = new CreateIndexOptions<BsonDocument>();indexOptions.Unique = true;indexOptions.PartialFilterExpression = new BsonDocument { { "keyAltNames", new BsonDocument { { "$exists", new BsonBoolean(true) } } } };var builder = Builders<BsonDocument>.IndexKeys;var indexKeysDocument = builder.Ascending("keyAltNames");var indexModel = new CreateIndexModel<BsonDocument>(indexKeysDocument, indexOptions);var keyVaultDatabase = keyVaultClient.GetDatabase(keyVaultNamespace.DatabaseNamespace.ToString());// Drop the Key Vault Collection in case you created this collection// in a previous run of this application. keyVaultDatabase.DropCollection(keyVaultNamespace.CollectionName);// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.keyVaultClient.GetDatabase("medicalRecords").DropCollection("patients");var keyVaultCollection = keyVaultDatabase.GetCollection<BsonDocument>(keyVaultNamespace.CollectionName.ToString());keyVaultCollection.Indexes.CreateOne(indexModel);
3

Recupera el contenido del archivo de llave maestra de cliente que generaste en el paso Crear una llave maestra de cliente de esta guía.

Pase el valor de llave maestra de cliente a la configuración de su proveedor de KMS. El cliente utiliza esta configuración para descubrir la llave maestra de cliente. Como está utilizando el proveedor de claves local, establezca el nombre del proveedor en local.

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";string localMasterKeyBase64Read = File.ReadAllText("master-key.txt");var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add("local", localOptions);

Construya un cliente con su cadena de conexión de MongoDB y el namespace de la Colección de Bóvedas de Llaves, y cree una llave de cifrado de datos:

Nota

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

Para completar este tutorial, el usuario de base de datos que tu aplicación utiliza para conectar a MongoDB debe tener permisos dbAdmin en los siguientes espacios de nombres:

  • encryption.__keyVault

  • medicalRecords database

var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders ); var clientEncryption = new ClientEncryption(clientEncryptionOptions);var dataKeyOptions = new DataKeyOptions();var dataKeyId = clientEncryption.CreateDataKey(provider, dataKeyOptions, CancellationToken.None);var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));Console.WriteLine($"DataKeyId [base64]: {dataKeyIdBase64}");

La salida del código anterior debe parecerse a lo siguiente:

DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==

Tip

Consultar: Código completo

Para ver el código completo para la creación de una llave de cifrado de datos, consulte nuestro repositorio de Github.

4

Especifica encryption.__keyVault como el namespace de la Colección de Bóvedas de Llaves.

var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.__keyVault");

Especifique el proveedor de KMS y especifique su clave en línea:

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "local";var localMasterKeyPath = "master-key.txt";string localMasterKeyBase64Read = File.ReadAllText(localMasterKeyPath);var localMasterKeyBytes = Convert.FromBase64String(localMasterKeyBase64Read);var localOptions = new Dictionary<string, object>{ { "key", localMasterKeyBytes }};kmsProviders.Add(provider, localOptions);

Tip

Añada la llave de cifrado de datos ID Base64

Asegúrese de actualizar el siguiente código para incluir su ID de DEK Base64. Recibió este valor en el paso Generar tu llave de cifrado de datos de esta guía.

var keyId = "<Your base64 DEK ID here>";var schema = new BsonDocument{ { "bsonType", "object" }, { "encryptMetadata", new BsonDocument("keyId", new BsonArray(new[] { new BsonBinaryData(Convert.FromBase64String(keyId), BsonBinarySubType.UuidStandard) })) }, { "properties", new BsonDocument { { "ssn", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } }, { "bloodType", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "string" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "medicalRecords", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "array" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }, { "insurance", new BsonDocument { { "bsonType", "object" }, { "properties", new BsonDocument { { "policyNumber", new BsonDocument { { "encrypt", new BsonDocument { { "bsonType", "int" }, { "algorithm", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } } } } } } } } } }};var schemaMap = new Dictionary<string, BsonDocument>();schemaMap.Add(dbNamespace, schema);
var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";var extraOptions = new Dictionary<string, object>(){ { "cryptSharedLibPath", mongoBinariesPath },};

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 librería Compartida de Cifrado Automático, consulta la página librería Compartida de Cifrado Automático para CSFLE.

Instancia un objeto cliente de MongoDB con la siguiente configuración de cifrado automático:

var clientSettings = MongoClientSettings.FromConnectionString(connectionString);var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders, schemaMap: schemaMap, extraOptions: extraOptions );clientSettings.AutoEncryptionOptions = autoEncryptionOptions;var secureClient = new MongoClient(clientSettings);
5

Utiliza tu instancia de MongoClient habilitada para CSFLE para insertar un documento con campos cifrados en el namespace medicalRecords.patients usando el siguiente fragmento de código:

var sampleDocFields = new BsonDocument{ { "name", "Jon Doe" }, { "ssn", 145014000 }, { "bloodType", "AB-" }, { "medicalRecords", new BsonArray { new BsonDocument("weight", 180), new BsonDocument("bloodPressure", "120/80") } }, { "insurance", new BsonDocument { { "policyNumber", 123142 }, { "provider", "MaestCare" } } }}; // Construct an auto-encrypting clientvar secureCollection = secureClient.GetDatabase(db).GetCollection<BsonDocument>(coll); // Insert a document into the collectionsecureCollection.InsertOne(sampleDocFields);

Cuando insertas un documento, tu cliente habilitado con CSFLE cifra los campos de tu documento de modo que se asemejan a lo siguiente:

{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } }}

Tip

Consultar: Código completo

Para ver el código completo para insertar un documento con campos cifrados, consulta nuestro repositorio de Github

6

Recupera el documento con campos cifrados que insertaste en el paso Insertar un documento con campos cifrados de esta guía.

Para mostrar la funcionalidad de CSFLE, el siguiente snippet de código query tu documento con un cliente configurado para CSFLE automático, así como un cliente que no está configurado para CSFLE automático.

Console.WriteLine("Finding a document with regular (non-encrypted) client.");var filter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var regularResult = regularCollection.Find(filter).Limit(1).ToList()[0];Console.WriteLine($"\n{regularResult}\n"); Console.WriteLine("Finding a document with encrypted client, searching on an encrypted field");var ssnFilter = Builders<BsonDocument>.Filter.Eq("ssn", 145014000);var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();Console.WriteLine($"\n{secureResult}\n");

La salida del código snippet precedente debería verse así:

Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' }} Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' }}

Tip

Consultar: Código completo

Para ver el código completo para encontrar un documento con campos cifrados, consulta nuestro repositorio de Github

Para ver un tutorial sobre CSFLE lista para producción con un KMS remoto, consulta Tutoriales de CSFLE.

Para aprender cómo funciona CSFLE, consulta Fundamentos de CSFLE.

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