Utiliza el cifrado automático de nivel de campo del lado del cliente con Azure

Registre su aplicación con Azure

1. Inicie sesión en Azure.

2. Registre su aplicación en Azure Active Directory

   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.

Crear la llave maestra de cliente

1. Cree su Azure Key Vault y su llave maestra de cliente

   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.

   Nota

   La clave maestra de cliente debe tener un tamaño de clave RSA de 2048 o 4096 bits.

   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.

2. Otorgar permisos

Cree un Índice Único en su Colección de Bóvedas de Llaves

Crea un índice único en el campo keyAltNames de tu namespace encryption.__keyVault.

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);

uri := "<Your MongoDB URI>"keyVaultClient, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))if err != nil {	return fmt.Errorf("Connect error for regular client: %v", err)}defer func() {	_ = keyVaultClient.Disconnect(context.TODO())}()
keyVaultColl := "__keyVault"keyVaultDb := "encryption"keyVaultNamespace := keyVaultDb + "." + keyVaultCollkeyVaultIndex := mongo.IndexModel{	Keys: bson.D{{"keyAltNames", 1}},	Options: options.Index().		SetUnique(true).		SetPartialFilterExpression(bson.D{			{"keyAltNames", bson.D{				{"$exists", true},			}},		}),}// Drop the Key Vault Collection in case you created this collection// in a previous run of this application.if err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Drop(context.TODO()); err != nil {	log.Fatalf("Collection.Drop error: %v", err)}// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.if err = keyVaultClient.Database("medicalRecords").Collection("patients").Drop(context.TODO()); err != nil {	log.Fatalf("Collection.Drop error: %v", err)}_, err = keyVaultClient.Database(keyVaultDb).Collection(keyVaultColl).Indexes().CreateOne(context.TODO(), keyVaultIndex)if err != nil {	panic(err)}

String connectionString = "<Your MongoDB URI>";String keyVaultDb = "encryption";String keyVaultColl = "__keyVault";String keyVaultNamespace = keyVaultDb + "." + keyVaultColl;MongoClient keyVaultClient = MongoClients.create(connectionString);
// Drop the Key Vault Collection in case you created this collection// in a previous run of this application.keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl).drop();// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.keyVaultClient.getDatabase("medicalRecords").getCollection("patients").drop();

MongoCollection keyVaultCollection = keyVaultClient.getDatabase(keyVaultDb).getCollection(keyVaultColl);IndexOptions indexOpts = new IndexOptions().partialFilterExpression(new BsonDocument("keyAltNames", new BsonDocument("$exists", new BsonBoolean(true) ))).unique(true);keyVaultCollection.createIndex(new BsonDocument("keyAltNames", new BsonInt32(1)), indexOpts);keyVaultClient.close();

const uri = "<Your Connection String>";const keyVaultDatabase = "encryption";const keyVaultCollection = "__keyVault";const keyVaultNamespace = `${keyVaultDatabase}.${keyVaultCollection}`;const keyVaultClient = new MongoClient(uri);await keyVaultClient.connect();const keyVaultDB = keyVaultClient.db(keyVaultDatabase);// Drop the Key Vault Collection in case you created this collection// in a previous run of this application.await keyVaultDB.dropDatabase();// Drop the database storing your encrypted fields as all// the DEKs encrypting those fields were deleted in the preceding line.await keyVaultClient.db("medicalRecords").dropDatabase();const keyVaultColl = keyVaultDB.collection(keyVaultCollection);await keyVaultColl.createIndex(  { keyAltNames: 1 },  {    unique: true,    partialFilterExpression: { keyAltNames: { $exists: true } },  });

connection_string = "<your connection string here>"
key_vault_coll = "__keyVault"key_vault_db = "encryption"key_vault_namespace = f"{key_vault_db}.{key_vault_coll}"key_vault_client = MongoClient(connection_string)# Drop the Key Vault Collection in case you created this collection# in a previous run of this application.key_vault_client.drop_database(key_vault_db)# Drop the database storing your encrypted fields as all# the DEKs encrypting those fields were deleted in the preceding line.key_vault_client["medicalRecords"].drop_collection("patients")key_vault_client[key_vault_db][key_vault_coll].create_index(    [("keyAltNames", ASCENDING)],    unique=True,    partialFilterExpression={"keyAltNames": {"$exists": True}},)

Crear una nueva clave de cifrado de datos

1. Agrega tus credenciales de Azure Key Vault

   Agrega las credenciales de la cuenta de servicio a tu código de cliente habilitado para CSFLE.

    C#GoJava (Sync)Node.jsPython

   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "azure";var azureKmsOptions = new Dictionary<string, object>{   { "tenantId", "<Your Azure Tenant ID>" },   { "clientId", "<Your Azure Client ID>" },   { "clientSecret", "<Your Azure Client Secret>" },};

2. Agrega tu información clave

   Actualiza el siguiente código para especificar tu llave maestra de cliente:

   Tip

   Registraste el ARN de tu llave maestra de cliente y la región en el paso Crear una llave maestra de cliente de esta guía.

    C#GoJava (Sync)Node.jsPython

   kmsProviders.Add(provider, azureKmsOptions);var dataKeyOptions = new DataKeyOptions(masterKey: new BsonDocument{   { "keyName", "<Your Azure Key Name>" },   { "keyVaultEndpoint", "<Your Azure Key Vault Endpoint>" },});

3. Genere su clave de cifrado de datos

   Genera tu llave de cifrado de datos usando las variables declaradas en el paso uno de este tutorial.

    C#GoJava (Sync)Node.jsPython

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

Configurar el MongoClient

1. Especifica el namespace de la Colección de Bóvedas de Llaves

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

    C#GoJava (Sync)Node.jsPython

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

2. Especifica tus credenciales de Azure

   Especifique el proveedor de KMS de azure y sus credenciales de Azure:

    C#GoJava (Sync)Node.jsPython

   var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();var provider = "azure";var azureKmsOptions = new Dictionary<string, object>{   { "tenantId", "<Your Azure Tenant ID>" },   { "clientId", "<Your Azure Client ID>" },   { "clientSecret", "<Your Azure Client Secret>" },};kmsProviders.Add(provider, azureKmsOptions);

3. Cree un esquema de cifrado para su colección

   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.

    C#GoJava (Sync)Node.jsPython

   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);

4. Especifica la ubicación de la librería compartida de cifrado automático

    C#GoJava (Sync)Node.jsPython

   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 aprender más sobre la Librería Compartida de Cifrado Automático, consulte la página Instalar y Configurar un Componente de Análisis de Query CSFLE.

5. Crea el cliente de Mongo

   Instancia un objeto cliente de MongoDB con la siguiente configuración de cifrado automático que utiliza las variables declaradas en los pasos previos:

   .NET/C# Driver v3.0+Driver .NET/C# < v3.0

    C#GoJava (Sync)Node.jsPython

   MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later onlyvar clientSettings = MongoClientSettings.FromConnectionString(connectionString);var autoEncryptionOptions = new AutoEncryptionOptions(    keyVaultNamespace: keyVaultNamespace,    kmsProviders: kmsProviders,    schemaMap: schemaMap,    extraOptions: extraOptions    );clientSettings.AutoEncryptionOptions = autoEncryptionOptions;var secureClient = new MongoClient(clientSettings);

Insertar un documento con campos cifrados

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);

test_patient := map[string]interface{}{	"name":      "Jon Doe",	"ssn":       241014209,	"bloodType": "AB+",	"medicalRecords": []map[string]interface{}{{		"weight":        180,		"bloodPressure": "120/80",	}},	"insurance": map[string]interface{}{		"provider":     "MaestCare",		"policyNumber": 123142,	},}if _, err := secureClient.Database(dbName).Collection(collName).InsertOne(context.TODO(), test_patient); err != nil {	return fmt.Errorf("InsertOne error: %v", err)}

ArrayList<Document> medicalRecords = new ArrayList<>();medicalRecords.add(new Document().append("weight", "180"));medicalRecords.add(new Document().append("bloodPressure", "120/80"));
Document insurance = new Document().append("policyNumber", 123142).append("provider",  "MaestCare");
Document patient = new Document()    .append("name", "Jon Doe")    .append("ssn", 241014209)    .append("bloodType", "AB+")    .append("medicalRecords", medicalRecords)    .append("insurance", insurance);mongoClientSecure.getDatabase(recordsDb).getCollection(recordsColl).insertOne(patient);

try {  const writeResult = await secureClient    .db(db)    .collection(coll)    .insertOne({      name: "Jon Doe",      ssn: 241014209,      bloodType: "AB+",      medicalRecords: [{ weight: 180, bloodPressure: "120/80" }],      insurance: {        policyNumber: 123142,        provider: "MaestCare",      },    });} catch (writeError) {  console.error("writeError occurred:", writeError);}

def insert_patient(    collection, name, ssn, blood_type, medical_records, policy_number, provider):    insurance = {"policyNumber": policy_number, "provider": provider}    doc = {        "name": name,        "ssn": ssn,        "bloodType": blood_type,        "medicalRecords": medical_records,        "insurance": insurance,    }    collection.insert_one(doc)

medical_record = [{"weight": 180, "bloodPressure": "120/80"}]insert_patient(    secureClient.medicalRecords.patients,    "Jon Doe",    241014209,    "AB+",    medical_record,    123142,    "MaestCare",)

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

Recupera tu documento con campos cifrados

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");var ssnFilter = Builders<BsonDocument>.Filter.Eq("name", "Jon Doe");var secureResult = secureCollection.Find(ssnFilter).Limit(1).First();Console.WriteLine($"\n{secureResult}\n");