Inicio rápido del cifrado consultable

Asignar variables a su 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"

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 cifrada

1. Crear una clave maestra de cliente

   Debe crear una clave maestra de cliente(CMK) para realizar el cifrado consultable.

   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

   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)

   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::thread_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

   Utilice el siguiente comando para generar una CMK desde un shell de Unix o PowerShell:

   • Shell de Unix/macOS:

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

   • Potencia Shell:

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

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

2. Recupere la clave maestra del cliente y especifique la configuración del proveedor KMS

   Recupere el contenido del archivo de clave maestra del cliente que generó en el paso Crear una clave maestra del cliente de esta guía.

   Utilice el valor de CMK en la configuración de su proveedor de KMS. El cliente utiliza esta configuración para descubrir la CMK. Configure el nombre del proveedor como local para indicar que utiliza un proveedor de claves local.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

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

   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 biblioteca compartida de cifrado automático

   El valor cryptSharedLibPath debe ser la ruta absoluta a su archivo de biblioteca 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 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 biblioteca 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. Crear un cliente para configurar una colección cifrada

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

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Rust

   const encryptedClient = Mongo(uri, autoEncryptionOptions);

   IMPORTANTE: Si está utilizando la versión del controlador .NET/C# 3.0 o posterior, debe agregar el siguiente código a su aplicación antes de crear una instancia de un MongoClient nuevo:

   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)

   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 para 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

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

   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, los campos ssn y 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

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

   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

   Rust

   customerMasterKeyCredentials = {};

   var customerMasterKeyCredentials = new BsonDocument();

   cmkCredentials := map[string]string{}

   BsonDocument customerMasterKeyCredentials = new BsonDocument();

   customerMasterKeyCredentials = {};

   $customerMasterKeyCredentials = [];

   customer_master_key_credentials = {}

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

   C#

   Go

   Java (Sync)

   Node.js

   PHP

   Python

   Rust

   Cree su colección cifrada mediante el método auxiliar 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 sus 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, cree su colección cifrada mediante el método auxiliar 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 sus 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 base de datos, en lugar del nombre de la base de datos. Puede obtener esta referencia mediante un método en su 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, cree su colección cifrada mediante el método auxiliar 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 sus 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 base de datos, en lugar del nombre de la base de datos. Puede obtener esta referencia mediante un método en su objeto cliente.

   Cree su colección cifrada mediante el método auxiliar 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 sus 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 base de datos, en lugar del nombre de la base de datos. Puede obtener esta referencia mediante un método en su objeto cliente.

   Cree su colección cifrada mediante el método auxiliar 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 sus 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, importe ClientEncryption desde 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 base de datos, en lugar del nombre de la base de datos. Puede obtener esta referencia mediante un método en su objeto cliente.

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

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

   Cree su colección cifrada mediante el método auxiliar 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 sus 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 base de datos, en lugar del nombre de la base de datos. Puede obtener esta referencia mediante un método en su objeto cliente.

   Cree su colección cifrada mediante el método auxiliar 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 sus 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)

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)

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 del ejemplo de código anterior debería verse 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"
      }
    }
  ]
}