Inicio rápido de Queryable Encryption

Asignar tus variables de aplicación

Los muestras de código de este tutorial utilizan las siguientes variables para llevar a cabo el flujo de trabajo Queryable Encryption:

const kmsProviderName = "<Your KMS Provider Name>";
const uri = process.env.MONGODB_URI; // Your connection URI
const keyVaultDatabaseName = "encryption";
const keyVaultCollectionName = "__keyVault";
const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;
const encryptedDatabaseName = "medicalRecords";
const encryptedCollectionName = "patients";

const string kmsProviderName = "<your KMS provider name>";
const string keyVaultDatabaseName = "encryption";
const string keyVaultCollectionName = "__keyVault";
var keyVaultNamespace =
    CollectionNamespace.FromFullName($"{keyVaultDatabaseName}.{keyVaultCollectionName}");
const string encryptedDatabaseName = "medicalRecords";
const string encryptedCollectionName = "patients";
var appSettings = new ConfigurationBuilder().AddJsonFile("appsettings.json").Build();
var uri = appSettings["MongoDbUri"];

kmsProviderName := "<KMS provider name>"
uri := os.Getenv("MONGODB_URI") // Your connection URI
keyVaultDatabaseName := "encryption"
keyVaultCollectionName := "__keyVault"
keyVaultNamespace := keyVaultDatabaseName + "." + keyVaultCollectionName
encryptedDatabaseName := "medicalRecords"
encryptedCollectionName := "patients"

String kmsProviderName = "<KMS provider name>";
String uri = QueryableEncryptionHelpers.getEnv("MONGODB_URI"); // Your connection URI
String keyVaultDatabaseName = "encryption";
String keyVaultCollectionName = "__keyVault";
String keyVaultNamespace = keyVaultDatabaseName + "." + keyVaultCollectionName;
String encryptedDatabaseName = "medicalRecords";
String encryptedCollectionName = "patients";

const kmsProviderName = "<Your KMS Provider Name>";
const uri = process.env.MONGODB_URI; // Your connection URI
const keyVaultDatabaseName = "encryption";
const keyVaultCollectionName = "__keyVault";
const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;
const encryptedDatabaseName = "medicalRecords";
const encryptedCollectionName = "patients";

$kmsProviderName = getenv('KMS_PROVIDER');
$uri = getenv('MONGODB_URI'); // Your connection URI
$keyVaultDatabaseName = 'encryption';
$keyVaultCollectionName = '__keyVault';
$keyVaultNamespace = $keyVaultDatabaseName . '.' . $keyVaultCollectionName;
$encryptedDatabaseName = 'medicalRecords';
$encryptedCollectionName = 'patients';

kms_provider_name = "<KMS provider name>"
uri = os.environ['MONGODB_URI']  # Your connection URI
key_vault_database_name = "encryption"
key_vault_collection_name = "__keyVault"
key_vault_namespace = f"{key_vault_database_name}.{key_vault_collection_name}"
encrypted_database_name = "medicalRecords"
encrypted_collection_name = "patients"

kms_provider_name = ENV["KMS_PROVIDER"]
uri = ENV["MONGODB_URI"] # Your connection URI
key_vault_database_name = "encryption"
key_vault_collection_name = "__keyVault"
key_vault_namespace = "#{key_vault_database_name}.#{key_vault_collection_name}"
encrypted_database_name = "medicalRecords"
encrypted_collection_name = "patients"

let kms_provider_name = "<KMS provider name>";
let uri = env::var("MONGODB_URI").expect("Set MONGODB_URI environment variable to your connection string");
let key_vault_database_name = "encryption";
let key_vault_collection_name = "__keyVault";
let key_vault_namespace = Namespace::new(key_vault_database_name, key_vault_collection_name);
let encrypted_database_name = "medicalRecords";
let encrypted_collection_name = "patients";

Crea tu colección encriptada

1. Crear una clave maestra de cliente

   Debe crear una llave maestra de cliente (CMK) para realizar Queryable Encryption.

   Cree una clave maestra de cliente de 96bytes y guárdela en su sistema de archivos como el archivo customer-master-key.txt:

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   customerMasterKeyPath = "customer-master-key.txt";
   if (!fs.existsSync(customerMasterKeyPath)) {
     fs.writeFileSync(customerMasterKeyPath, crypto.randomBytes(96));
   }

   using var randomNumberGenerator = RandomNumberGenerator.Create();
   try
   {
       var bytes = new byte[96];
       randomNumberGenerator.GetBytes(bytes);
       File.WriteAllBytes("customer-master-key.txt", bytes);
   }
   catch (Exception e)
   {
       throw new Exception("Unable to write Customer Master Key file due to the following error: " + e.Message);
   }

   key := make([]byte, 96)
   if _, err := rand.Read(key); err != nil {
   	panic(fmt.Sprintf("Unable to create a random 96 byte data key: %v\n", err))
   }
   if err := os.WriteFile("customer-master-key.txt", key, 0644); err != nil {
   	panic(fmt.Sprintf("Unable to write key to file: %v\n", err))
   }

   byte[] localCustomerMasterKey = new byte[96];
   new SecureRandom().nextBytes(localCustomerMasterKey);
   try (FileOutputStream stream = new FileOutputStream("customer-master-key.txt")) {
       stream.write(localCustomerMasterKey);
       // ...

   if (!existsSync("./customer-master-key.txt")) {
     try {
       writeFileSync("customer-master-key.txt", randomBytes(96));
     } catch (err) {
       throw new Error(
         `Unable to write Customer Master Key to file due to the following error: ${err}`
       );
     }
   }

   if (!file_exists('./customer-master-key.txt')) {
       file_put_contents('./customer-master-key.txt', random_bytes(96));
   }

   path = "customer-master-key.txt"
   file_bytes = os.urandom(96)
   with open(path, "wb") as f:
       f.write(file_bytes)

   unless File.exist?("./customer-master-key.txt")
     File.binwrite("./customer-master-key.txt", SecureRandom.random_bytes(96))
   end

   let key_file_path = "customer-master-key.txt";
   let mut local_key = Vec::new();
   if !Path::new(key_file_path).exists() {
       let mut key = [0u8; 96];
       rand::rng().fill_bytes(&mut key);
       // Write the key to the file
       match OpenOptions::new().write(true).create(true).open(key_file_path) {
           Ok(mut file) => {
               if let Err(err) = file.write_all(&key) {
                   panic!("Unable to write Customer Master Key to file: {}", err);
               }
           }
           Err(err) => panic!("Unable to create Customer Master Key file: {}", err),
       }
       local_key = key.to_vec();
   } 

   Además de las cadenas de bytes, también puedes utilizar una cadena codificada en Base64como clave local.

   Advertencia

   Asegurar tu archivo de clave local en producción

   Recomendamos almacenar sus claves maestras de cliente en un sistema de gestión de claves remoto (KMS). Para aprender a utilizar un KMS remoto en tu implementación de cifrado consultable, consulta la guía Tutoriales sobre Queryable Encryption.

   Si optas por usar un proveedor local de llaves en producción, proceder con extrema precaución y no almacenarlo en el sistema de archivos. Considera inyectar la clave en la aplicación cliente mediante un proceso sidecar o usa otro método que mantenga la clave segura.

   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 Unix o PowerShell:

   • Unix/macOS shell:

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

   • PowerShell:

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

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

2. Recuperar la clave maestra del cliente y especificar la configuración del proveedor de KMS

   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.

   Usa el valor de llave maestra de cliente en la configuración del proveedor de KMS. El cliente utiliza estas configuraciones para descubrir la llave maestra de cliente. Establece el nombre del proveedor en local para indicar que estás usando un Proveedor de Clave Local.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   // WARNING: Do not use a local key file in a production application
   const localMasterKey = fs.readFileSync("./customer-master-key.txt");
   if (localMasterKey.length !== 96) {
     throw new Error(
       "Expected the customer master key file to be 96 bytes."
     );
   }
   kmsProviderCredentials = {
     local: {
       key: localMasterKey,
     },
   };

   También puedes proporcionar un nombre personalizado para tu proveedor de KMS pasando una string que incluya el nombre del proveedor de KMS, seguido de dos puntos y el nombre personalizado. Proporcionar un nombre único para un proveedor de KMS te permite especificar múltiples proveedores de KMS del mismo tipo.

   El siguiente ejemplo muestra un objeto que establece el nombre del proveedor KMS en "my_kms_provider":

   {
       "local:my_kms_provider": {
          { "key" : "<local CMK>" }
       },
   }

   // WARNING: Do not use a local key file in a production application
   var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>();
   try
   {
       var localCustomerMasterKeyBytes = File.ReadAllBytes("customer-master-key.txt");
       if (localCustomerMasterKeyBytes.Length != 96)
       {
           throw new Exception("Expected the customer master key file to be 96 bytes.");
       }
       var localOptions = new Dictionary<string, object>
       {
           { "key", localCustomerMasterKeyBytes }
       };
       kmsProviderCredentials.Add("local", localOptions);
   }

   key, err := os.ReadFile("customer-master-key.txt")
   if err != nil {
   	panic(fmt.Sprintf("Could not read the Customer Master Key: %v", err))
   }
   if len(key) != 96 {
   	panic(fmt.Sprintf("Expected the customer master key file to be 96 bytes."))
   }
   kmsProviderCredentials := map[string]map[string]interface{}{"local": {"key": key}}

   byte[] localCustomerMasterKey = new byte[96];
   try (FileInputStream fis = new FileInputStream("customer-master-key.txt")) {
       if (fis.read(localCustomerMasterKey) != 96)
           throw new Exception("Expected the customer master key file to be 96 bytes.");
   } catch (Exception e) {
       throw new Exception("Unable to read the Customer Master Key due to the following error: " + e.getMessage());
   }
   Map<String, Object> keyMap = new HashMap<String, Object>();
   keyMap.put("key", localCustomerMasterKey);
   Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>();
   kmsProviderCredentials.put("local", keyMap);

   También puedes proporcionar un nombre personalizado para tu proveedor de KMS pasando una string que incluya el nombre del proveedor de KMS, seguido de dos puntos y el nombre personalizado. Proporcionar un nombre único para un proveedor de KMS te permite especificar múltiples proveedores de KMS del mismo tipo.

   El siguiente ejemplo muestra un objeto que establece el nombre del proveedor KMS en "my_kms_provider":

   {
       "local:my_kms_provider": {
          { "key" : "<local CMK>" }
       },
   }

   // WARNING: Do not use a local key file in a production application
   const localMasterKey = readFileSync("./customer-master-key.txt");
   if (localMasterKey.length !== 96) {
     throw new Error(
       "Expected the customer master key file to be 96 bytes."
     );
   }
   kmsProviders = {
     local: {
       key: localMasterKey,
     },
   };

   También puedes proporcionar un nombre personalizado para tu proveedor de KMS pasando una string que incluya el nombre del proveedor de KMS, seguido de dos puntos y el nombre personalizado. Proporcionar un nombre único para un proveedor de KMS te permite especificar múltiples proveedores de KMS del mismo tipo.

   El siguiente ejemplo muestra un objeto que establece el nombre del proveedor KMS en "my_kms_provider":

   {
       "local:my_kms_provider": {
          { "key" : "<local CMK>" }
       },
   }

   // WARNING: Do not use a local key file in a production application
   $localMasterKey = file_get_contents('./customer-master-key.txt');
   $kmsProviders = [
       'local' => [
           'key' => new \MongoDB\BSON\Binary($localMasterKey),
       ],
   ];

   path = "./customer-master-key.txt"
   with open(path, "rb") as f:
       local_master_key = f.read()
       if len(local_master_key) != 96:
           raise Exception("Expected the customer master key file to be 96 bytes.")
       kms_provider_credentials = {
           "local": {
               "key": local_master_key
           },
       }

   También puedes proporcionar un nombre personalizado para tu proveedor de KMS pasando una string que incluya el nombre del proveedor de KMS, seguido de dos puntos y el nombre personalizado. Proporcionar un nombre único para un proveedor de KMS te permite especificar múltiples proveedores de KMS del mismo tipo.

   El siguiente ejemplo muestra un objeto que establece el nombre del proveedor KMS en "my_kms_provider":

   {
       "local:my_kms_provider": {
          { "key" : "<local CMK>" }
       },
   }

   # WARNING: Do not use a local key file in a production application
   local_master_key = File.binread("./customer-master-key.txt")
   raise "Expected the customer master key file to be 96 bytes." unless local_master_key.bytesize == 96
   kms_providers = {
     local: {
       key: local_master_key
     }
   }

   {
       // WARNING: Do not use a local key file in a production application
       match fs::File::open(key_file_path) {
           Ok(mut file) => {
               if let Err(err) = file.read_to_end(&mut local_key) {
                   panic!("Unable to read Customer Master Key file: {}", err);
               }
           }
           Err(err) => panic!("Unable to open Customer Master Key file: {}", err),
       }
       if local_key.len() != 96 {
           panic!("Expected the customer master key file to be 96 bytes.");
       }
   }
   let binary_key = Binary {
       subtype: BinarySubtype::Generic,
       bytes: local_key,
   };
   kms_providers = vec![(
       KmsProvider::local(),
       doc! {
           "key": binary_key,
       },
       None,
   )];

3. Configura tus opciones de cifrado automático

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   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, definido en el paso anterior

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

   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, definido en el paso anterior

   • El objeto extraOptions, que contiene la ruta a

     su Librería compartida de cifrado automático

   Tip

   Ruta de la librería compartida de cifrado automático

   El valor cryptSharedLibPath debe ser la ruta absoluta a tu archivo de la librería Compartida de Cifrado Automático. Por ejemplo:

   • Linux: /usr/local/lib/mongo_crypt_v1.so

   • macOS: /usr/local/lib/mongo_crypt_v1.dylib

   • Windows: C:\path\to\bin\mongo_crypt_v1.dll

   Establezca esta ruta en el campo CryptSharedLibPath de su archivo appsettings.json.

   var extraOptions = new Dictionary<string, object>
   {
       { "cryptSharedLibPath", _appSettings["CryptSharedLibPath"] } // Path to your Automatic Encryption Shared Library
   };
   var autoEncryptionOptions = new AutoEncryptionOptions(
       keyVaultNamespace,
       kmsProviderCredentials,
       extraOptions: extraOptions);

   Crea un objeto AutoEncryption que contiene las siguientes opciones:

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El objeto kmsProviderCredentials, definido en el paso anterior

   • El objeto cryptSharedLibraryPath, que contiene la ruta a

     su Librería compartida de cifrado automático

   cryptSharedLibraryPath := map[string]interface{}{
   	"cryptSharedLibPath": os.Getenv("SHARED_LIB_PATH"), // Path to your Automatic Encryption Shared Library
   }
   autoEncryptionOptions := options.AutoEncryption().
   	SetKeyVaultNamespace(keyVaultNamespace).
   	SetKmsProviders(kmsProviderCredentials).
   	SetExtraOptions(cryptSharedLibraryPath)

   Crea un objeto AutoEncryptionSettings que contiene las siguientes opciones:

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El objeto kmsProviderCredentials, definido en el paso anterior

   • El objeto extraOptions, que contiene la ruta a

     su Librería compartida de cifrado automático

   Map<String, Object> extraOptions = new HashMap<String, Object>();
   extraOptions.put("cryptSharedLibPath", getEnv("SHARED_LIB_PATH")); // Path to your Automatic Encryption Shared Library
   AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
           .keyVaultNamespace(keyVaultNamespace)
           .kmsProviders(kmsProviderCredentials)
           .extraOptions(extraOptions)
           .build();

   Si omite keyVaultClient o establece bypassAutomaticEncryption en falso en su objeto AutoEncryptionSettings, el controlador crea un MongoClient interno y separado. La configuración interna de MongoClient difiere de la de MongoClient principal mediante el ajuste de minPoolSize a 0 y omitiendo AutoEncryptionSettings.

   Crea un objeto autoEncryptionOptions que contiene las siguientes opciones:

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El objeto kmsProviders, definido en el paso anterior

   • El objeto sharedLibraryPathOptions, que contiene la ruta a

     su Librería compartida de cifrado automático

   const extraOptions = {
     cryptSharedLibPath: process.env.SHARED_LIB_PATH, // Path to your Automatic Encryption Shared Library
   };
   const autoEncryptionOptions = {
     keyVaultNamespace,
     kmsProviders,
     extraOptions,
   };

   Crea un objeto $autoEncryptionOptions que contiene las siguientes opciones:

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El objeto $kmsProviders, definido en el paso anterior

   $autoEncryptionOptions = [
       'keyVaultNamespace' => $keyVaultNamespace,
       'kmsProviders' => $kmsProviders,
   ];

   Crea un objeto AutoEncryptionOpts que contiene las siguientes opciones:

   • El objeto kms_provider_credentials, definido en el paso anterior

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • La ruta a tu librería compartida de cifrado automático

   auto_encryption_options = AutoEncryptionOpts(
       kms_provider_credentials,
       key_vault_namespace,
       crypt_shared_lib_path=os.environ['SHARED_LIB_PATH'] # Path to your Automatic Encryption Shared Library>
   )

   Crea un hash auto_encryption_options encriptado que contenga las siguientes opciones:

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El hash kms_providers, definido en el paso anterior

   • La ruta a tu librería compartida de cifrado automático

   auto_encryption_options = {
     key_vault_namespace: key_vault_namespace,
     kms_providers: kms_providers,
     extra_options: {
       crypt_shared_lib_path: ENV["SHARED_LIB_PATH"] # Path to your Automatic Encryption Shared Library
     }
   }

   Crea un objeto EncryptedClientBuilder que contiene las siguientes opciones:

   • Un objeto ClientOptions

   • El espacio de nombres de tu Colección de Bóvedas de Llaves

   • El objeto kms_providers, definido en el paso anterior

   let client_options = ClientOptions::builder().build();
   let builder = Client::encrypted_builder(
       client_options,
       key_vault_namespace.clone(),
       kms_providers.clone()
   ).expect("");

   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 Biblioteca Compartida de Cifrado Automático, consulta la página Biblioteca Compartida de Cifrado Automático.

4. Crea un cliente para configurar una colección cifrada

   Para crear un cliente que se utilice para cifrar y descifrar datos de su colección, cree una instancia de un nuevo cliente usando su URI de conexión y sus opciones de cifrado automático.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   const encryptedClient = Mongo(uri, autoEncryptionOptions);

   IMPORTANTE: Si usas la versión 3.0 o posterior del Driver .NET/C#, debes agregar el siguiente código a tu aplicación antes de instanciar un nuevo MongoClient:

   MongoClientSettings.Extensions.AddAutoEncryption(); // .NET/C# Driver v3.0 or later only

   Crear un nuevo MongoClient utilizando tu URI de conexión y opciones de cifrado automático:

   var clientSettings = MongoClientSettings.FromConnectionString(uri);
   clientSettings.AutoEncryptionOptions = qeHelpers.GetAutoEncryptionOptions(
       keyVaultNamespace,
       kmsProviderCredentials);
   var encryptedClient = new MongoClient(clientSettings);

   opts := options.Client().
   	ApplyURI(uri).
   	SetAutoEncryptionOptions(autoEncryptionOptions)
   encryptedClient, err := mongo.Connect(opts)
   if err != nil {
   	panic(fmt.Sprintf("Unable to connect to MongoDB: %v\n", err))
   }
   defer func() {
   	_ = encryptedClient.Disconnect(context.TODO())
   }()

   MongoClientSettings clientSettings = MongoClientSettings.builder()
           .applyConnectionString(new ConnectionString(uri))
           .autoEncryptionSettings(autoEncryptionSettings)
           .build();
   try (MongoClient encryptedClient = MongoClients.create(clientSettings)) {

   const encryptedClient = new MongoClient(uri, {
     autoEncryption: autoEncryptionOptions,
   });

   $encryptedClient = new \MongoDB\Client($uri, [], [
       'autoEncryption' => $autoEncryptionOptions,
   ]);

   encrypted_client = MongoClient(
       uri, auto_encryption_opts=auto_encryption_options)

   encrypted_client = Mongo::Client.new(uri, auto_encryption_options: auto_encryption_options)

   let encrypted_client = encrypted_client_builder
       .extra_options(Some(doc!{
           "cryptSharedLibPath": env::var("SHARED_LIB_PATH").expect("Set SHARED_LIB_PATH environment variable to path to crypt_shared library")
       }))
       .key_vault_client(Client::with_uri_str(uri).await.unwrap())
       .build()
       .await
       .unwrap();

5. Especificar campos a cifrar

   Para cifrar un campo, agrégalos al esquema de cifrado. Para habilitar consultas en un campo, agrega la propiedad queries. Cree el esquema de cifrado como sigue:

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   const encryptedFieldsMap = {
     encryptedFields: {
       fields: [
         {
           path: "patientRecord.ssn",
           bsonType: "string",
           queries: { queryType: "equality" },
         },
         {
           path: "patientRecord.billing",
           bsonType: "object",
         },
       ],
     },
   };

   var encryptedFields = new BsonDocument
   {
       {
           "fields", new BsonArray
           {
               new BsonDocument
               {
                   { "keyId", BsonNull.Value },
                   { "path", "patientRecord.ssn" },
                   { "bsonType", "string" },
                   { "queries", new BsonDocument("queryType", "equality") }
               },
               new BsonDocument
               {
                   { "keyId", BsonNull.Value },
                   { "path", "patientRecord.billing" },
                   { "bsonType", "object" }
               }
           }
       }
   };

   encryptedFieldsMap := bson.M{
   	"fields": []bson.M{
   		bson.M{
   			"keyId":    nil,
   			"path":     "patientRecord.ssn",
   			"bsonType": "string",
   			"queries": []bson.M{
   				{
   					"queryType": "equality",
   				},
   			},
   		},
   		bson.M{
   			"keyId":    nil,
   			"path":     "patientRecord.billing",
   			"bsonType": "object",
   		},
   	},
   }

   BsonDocument encryptedFieldsMap = new BsonDocument().append("fields",
           new BsonArray(Arrays.asList(
                   new BsonDocument()
                           .append("keyId", new BsonNull())
                           .append("path", new BsonString("patientRecord.ssn"))
                           .append("bsonType", new BsonString("string"))
                           .append("queries", new BsonDocument()
                                   .append("queryType", new BsonString("equality"))),
                   new BsonDocument()
                           .append("keyId", new BsonNull())
                           .append("path", new BsonString("patientRecord.billing"))
                           .append("bsonType", new BsonString("object")))));

   const encryptedFieldsMap = {
     encryptedFields: {
       fields: [
         {
           path: "patientRecord.ssn",
           bsonType: "string",
           queries: { queryType: "equality" },
         },
         {
           path: "patientRecord.billing",
           bsonType: "object",
         },
       ],
     },
   };

   $encryptedFieldsMap = [
       'encryptedFields' => [
           'fields' => [
               [
                   'path' => 'patientRecord.ssn',
                   'bsonType' => 'string',
                   'queries' => ['queryType' => 'equality'],
                   'keyId' => null,
               ],
               [
                   'path' => 'patientRecord.billing',
                   'bsonType' => 'object',
                   'keyId' => null,
               ],
           ],
       ],
   ];

   encrypted_fields_map = {
       "fields": [
           {
               "path": "patientRecord.ssn",
               "bsonType": "string",
               "queries": [{"queryType": "equality"}]
           },
           {
               "path": "patientRecord.billing",
               "bsonType": "object",
           }
       ]
   }

   encrypted_fields_map = {
     encrypted_fields: {
       fields: [
         {
           path: "patientRecord.ssn",
           bsonType: "string",
           queries: { queryType: "equality" },
           keyId: nil
         },
         {
           path: "patientRecord.billing",
           bsonType: "object",
           keyId: nil
         }
       ]
     }
   }

   let encrypted_fields_map = doc! {
       "fields": [
           {
               "path":     "patientRecord.ssn",
               "bsonType": "string",
               "keyId":    Bson::Null,
               "queries": { "queryType": "equality" },
           },
           {
               "path":     "patientRecord.billing",
               "bsonType": "object",
               "keyId":    Bson::Null,
           },
       ]
   };

   Nota

   En el ejemplo de código anterior, tanto el campo ssn como el campo billing están cifrados, pero solo se puede consultar el campo ssn.

6. Crear la colección

   Cree una instancia de un objeto ClientEncryption para acceder a la API de los métodos auxiliares de cifrado.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   const clientEncryption = encryptedClient.getClientEncryption();

   var clientEncryptionOptions = new ClientEncryptionOptions(
       keyVaultClient: keyVaultClient,
       keyVaultNamespace: keyVaultNamespace,
       kmsProviders: kmsProviderCredentials
   );
   var clientEncryption = new ClientEncryption(clientEncryptionOptions);

   opts := options.ClientEncryption().
   	SetKeyVaultNamespace(keyVaultNamespace).
   	SetKmsProviders(kmsProviderCredentials)
   clientEncryption, err := mongo.NewClientEncryption(encryptedClient, opts)
   if err != nil {
   	panic(fmt.Sprintf("Unable to create a ClientEncryption instance due to the following error: %s\n", err))
   }

   ClientEncryptionSettings clientEncryptionSettings = ClientEncryptionSettings.builder()
           .keyVaultMongoClientSettings(MongoClientSettings.builder()
                   .applyConnectionString(new ConnectionString(uri))
                   .build())
           .keyVaultNamespace(keyVaultNamespace)
           .kmsProviders(kmsProviderCredentials)
           .build();
   ClientEncryption clientEncryption = ClientEncryptions.create(clientEncryptionSettings);

   const clientEncryption = new ClientEncryption(
     encryptedClient,
     autoEncryptionOptions
   );

   $clientEncryption = $encryptedClient->createClientEncryption($autoEncryptionOptions);

   client_encryption = ClientEncryption(
       kms_providers=kms_provider_credentials,
       key_vault_namespace=key_vault_namespace,
       key_vault_client=encrypted_client,
       codec_options=CodecOptions(uuid_representation=STANDARD)
   )

   client_encryption = Mongo::ClientEncryption.new(
     encrypted_client,
     key_vault_namespace: auto_encryption_options[:key_vault_namespace],
     kms_providers: auto_encryption_options[:kms_providers]
   )

   let client_encryption = ClientEncryption::new(
       encrypted_client.clone(),
       key_vault_namespace.clone(),
       kms_providers.clone(),
   )
   .unwrap();

   Debido a que estás utilizando una llave maestra de cliente local, no necesitas proporcionar las credenciales de llave maestra de cliente. Crea una variable que contenga un objeto vacío para usar en lugar de credenciales cuando crees tu colección cifrada.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

   customerMasterKeyCredentials = {};

   var customerMasterKeyCredentials = new BsonDocument();

   cmkCredentials := map[string]string{}

   BsonDocument customerMasterKeyCredentials = new BsonDocument();

   customerMasterKeyCredentials = {};

   $customerMasterKeyCredentials = [];

   customer_master_key_credentials = {}

   customer_master_key_credentials = {}

   let local_master_key = LocalMasterKey::builder().build();
   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Ruby

   Rust

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

   La versión en C# de este tutorial usa clases separadas como modelos de datos para representar la estructura del documento. Agrega las siguientes clases Patient, PatientRecord y PatientBilling a tu proyecto:

   using MongoDB.Bson;
   using MongoDB.Bson.Serialization.Attributes;
   [BsonIgnoreExtraElements]
   public class Patient
   {
       public ObjectId Id { get; set; }
       public string PatientName { get; set; }
       public PatientRecord PatientRecord { get; set; }
   }

   public class PatientRecord
   {
       public string Ssn { get; set; }
       public PatientBilling Billing { get; set; }
       public int BillAmount { get; set; }
   }

   public class PatientBilling
   {
       public string CardType { get; set; }
       public long CardNumber { get; set; }
   }

   Después de agregar estas clases, crea tu colección cifrada utilizando el método asistente de cifrado 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:

   var createCollectionOptions = new CreateCollectionOptions<Patient>
   {
       EncryptedFields = encryptedFields
   };
   clientEncryption.CreateEncryptedCollection(patientDatabase,
       encryptedCollectionName,
       createCollectionOptions,
       kmsProviderName,
       customerMasterKeyCredentials);

   El método que crea la colección cifrada requiere una referencia a un objeto de la base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   La versión en Golang de este tutorial utiliza modelos de datos para representar la estructura del documento. Añade las siguientes estructuras a tu proyecto para representar los datos en tu colección:

   type PatientDocument struct {
   	PatientName   string        `bson:"patientName"`
   	PatientID     int32         `bson:"patientId"`
   	PatientRecord PatientRecord `bson:"patientRecord"`
   }

   type PatientRecord struct {
   	SSN        string      `bson:"ssn"`
   	Billing    PaymentInfo `bson:"billing"`
   	BillAmount int         `bson:"billAmount"`
   }

   type PaymentInfo struct {
   	Type   string `bson:"type"`
   	Number string `bson:"number"`
   }

   Después de agregar estas clases, crea tu colección cifrada utilizando el método asistente de cifrado 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:

   createCollectionOptions := options.CreateCollection().SetEncryptedFields(encryptedFieldsMap)
   _, _, err =
   	clientEncryption.CreateEncryptedCollection(
   		context.TODO(),
   		encryptedClient.Database(encryptedDatabaseName),
   		encryptedCollectionName,
   		createCollectionOptions,
   		kmsProviderName,
   		customerMasterKey,
   	)

   El método que crea la colección cifrada requiere una referencia a un objeto de la base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   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:

   CreateCollectionOptions createCollectionOptions = new CreateCollectionOptions().encryptedFields(encryptedFieldsMap);
   CreateEncryptedCollectionParams encryptedCollectionParams = new CreateEncryptedCollectionParams(kmsProviderName);
   encryptedCollectionParams.masterKey(customerMasterKeyCredentials);
   try {
       clientEncryption.createEncryptedCollection(
               encryptedClient.getDatabase(encryptedDatabaseName),
               encryptedCollectionName,
               createCollectionOptions,
               encryptedCollectionParams);
   } 

   El método que crea la colección cifrada requiere una referencia a un objeto de la base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   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:

   Nota

   Import ClientEncryption

   Al utilizar el controlador de Node.js versión 6.0 y posteriores, se debe importar ClientEncryption desde mongodb.

   Para versiones anteriores del controlador, importa ClientEncryption de mongodb-client-encryption.

   await clientEncryption.createEncryptedCollection(
     encryptedDatabase,
     encryptedCollectionName,
     {
       provider: kmsProviderName,
       createCollectionOptions: encryptedFieldsMap,
       masterKey: customerMasterKeyCredentials,
     }
   );

   El método que crea la colección cifrada requiere una referencia a un objeto de la base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   Crea tu colección encriptada llamando al método createEncryptedCollection() en tu base de datos. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

   $client->getDatabase($encryptedDatabase)->createEncryptedCollection(
       $encryptedCollectionName,
       $clientEncryption,
       $kmsProviderName,
       $customerMasterKeyCredentials,
       $encryptedFieldsMap,
   );

   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:

   client_encryption.create_encrypted_collection(
       encrypted_client[encrypted_database_name],
       encrypted_collection_name,
       encrypted_fields_map,
       kms_provider_name,
       customer_master_key_credentials,
   )

   El método que crea la colección cifrada requiere una referencia a un objeto de la base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   Cree su colección cifrada utilizando el método asistente de cifrado accesible a través de la clase ClientEncryption, como se muestra en el siguiente ejemplo:

   client_encryption.create_encrypted_collection(
     encrypted_client.use(encrypted_database_name).database,
     encrypted_collection_name,
     encrypted_fields_map,
     kms_provider_name,
     customer_master_key_credentials
   )

   El método create_encrypted_collection() genera automáticamente las claves de cifrado de datos para tus campos cifrados y crea la colección cifrada.

   create_encrypted_collection() requiere una referencia a un objeto de base de datos en lugar del nombre de la base de datos. Puedes obtener esta referencia utilizando un método en tu objeto cliente.

   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:

   client_encryption.create_encrypted_collection(
       &encrypted_client.database(encrypted_database_name), 
       encrypted_collection_name,
       customer_master_key_credentials
   )
   .encrypted_fields(encrypted_fields_map)
   .await
   .1?;

   El método que crea la colección cifrada requiere una referencia a un objeto de base de datos en vez del nombre de la base de datos. Puedes obtener esta referencia utilizando el método database() en tu objeto cliente.

Insertar un documento con campos cifrados

const patientDocument = {
  patientName: "Jon Doe",
  patientId: 12345678,
  patientRecord: {
    ssn: "987-65-4320",
    billing: {
      type: "Visa",
      number: "4111111111111111",
    },
    billAmount: 1500,
  },
};
const encryptedCollection = encryptedClient
  .getDB(encryptedDatabaseName)
  .getCollection(encryptedCollectionName);
const insertResult = await encryptedCollection.insertOne(patientDocument);

var patient = new Patient
{
    PatientName = "Jon Doe",
    Id = new ObjectId(),
    PatientRecord = new PatientRecord
    {
        Ssn = "987-65-4320",
        Billing = new PatientBilling
        {
            CardType = "Visa",
            CardNumber = 4111111111111111,
        },
        BillAmount = 1500
    }
};
var encryptedCollection = encryptedClient.GetDatabase(encryptedDatabaseName).
    GetCollection<Patient>(encryptedCollectionName);
await encryptedCollection.InsertOneAsync(patient);

patientDocument := &PatientDocument{
	PatientName: "Jon Doe",
	PatientID:   12345678,
	PatientRecord: PatientRecord{
		SSN: "987-65-4320",
		Billing: PaymentInfo{
			Type:   "Visa",
			Number: "4111111111111111",
		},
		BillAmount: 1500,
	},
}
coll := encryptedClient.Database(encryptedDatabaseName).Collection(encryptedCollectionName)
_, err = coll.InsertOne(context.TODO(), patientDocument)
if err != nil {
	panic(fmt.Sprintf("Unable to insert the patientDocument: %s", err))
}

CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

MongoDatabase encryptedDb = encryptedClient.getDatabase(encryptedDatabaseName).withCodecRegistry(pojoCodecRegistry);
MongoCollection<Patient> collection = encryptedDb.getCollection(encryptedCollectionName, Patient.class);
PatientBilling patientBilling = new PatientBilling("Visa", "4111111111111111");
PatientRecord patientRecord = new PatientRecord("987-65-4320", patientBilling, 1500);
Patient patientDocument = new Patient("Jon Doe", patientRecord);
InsertOneResult result = collection.insertOne(patientDocument);

const patientDocument = {
  patientName: "Jon Doe",
  patientId: 12345678,
  patientRecord: {
    ssn: "987-65-4320",
    billing: {
      type: "Visa",
      number: "4111111111111111",
    },
    billAmount: 1500,
  },
};
const encryptedCollection = encryptedClient
  .db(encryptedDatabaseName)
  .collection(encryptedCollectionName);
const result = await encryptedCollection.insertOne(patientDocument);

$patientDocument = [
    'patientName' => 'Jon Doe',
    'patientId' => 12345678,
    'patientRecord' => [
        'ssn' => '987-65-4320',
        'billing' => [
            'type' => 'Visa',
            'number' => '4111111111111111',
        ],
        'billAmount' => 1500,
    ],
];
$encryptedCollection = $encryptedClient
    ->getDatabase($encryptedDatabaseName)
    ->getCollection($encryptedCollectionName);
$result = $encryptedCollection->insertOne($patientDocument);

patient_document = {
    "patientName": "Jon Doe",
    "patientId": 12345678,
    "patientRecord": {
        "ssn": "987-65-4320",
        "billing": {
            "type": "Visa",
            "number": "4111111111111111",
        },
        "billAmount": 1500,
    },
}
encrypted_collection = encrypted_client[encrypted_database_name][encrypted_collection_name]
result = encrypted_collection.insert_one(patient_document)

patient_document = {
  patientName: "Jon Doe",
  patientId: 12345678,
  patientRecord: {
    ssn: "987-65-4320",
    billing: {
      type: "Visa",
      number: "4111111111111111"
    },
    billAmount: 1500
  }
}
encrypted_collection = encrypted_client
  .use(encrypted_database_name)[encrypted_collection_name]
result = encrypted_collection.insert_one(patient_document)

let patient_document = doc! {
    "patientName": "Jon Doe",
    "patientId": 12345678,
    "patientRecord": {
        "ssn": "987-65-4320",
        "billing": {
            "type": "Visa",
            "number": "4111111111111111",
        },
        "billAmount": 1500,
    }
};
let encrypted_coll: Collection<Document>  = encrypted_client
    .database(encrypted_database_name)
    .collection(encrypted_collection_name);
let insert_result = encrypted_coll.insert_one(patient_document).await?;

Query sobre un campo cifrado

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

var ssnFilter = Builders<Patient>.Filter.Eq("patientRecord.ssn", patient.PatientRecord.Ssn);
var findResult = await encryptedCollection.Find(ssnFilter).FirstOrDefaultAsync();
Console.WriteLine(findResult.ToJson());

var findResult PatientDocument
err = coll.FindOne(
	context.TODO(),
	bson.M{"patientRecord.ssn": "987-65-4320"},
).Decode(&findResult)

Patient findResult = collection.find(
    new BsonDocument()
            .append("patientRecord.ssn", new BsonString("987-65-4320")))
            .first();
 
System.out.println(findResult);

const findResult = await encryptedCollection.findOne({
  "patientRecord.ssn": "987-65-4320",
});
console.log(findResult);

$findResult = $encryptedCollection->findOne([
    'patientRecord.ssn' => '987-65-4320',
]);
print_r($findResult);

find_result = encrypted_collection.find_one({
    "patientRecord.ssn": "987-65-4320"
})
print(find_result)

find_result = encrypted_collection.find("patientRecord.ssn" => "987-65-4320").first
puts find_result.inspect

let find_result = encrypted_coll.find_one(doc! {"patientRecord.ssn": "987-65-4320"}).await?;
match find_result {
    Some(document) => println!("{:?}", document),
    None => println!("Document not found"),
}

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"
    },
    "billAmount": 1500
  },
  "__safeContent__": [
    {
      "$binary": {
        "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=",
        "subType": "00"
      }
    }
  ]
}