Overview
Esta guía te muestra cómo crear una colección compatible con cifrado consultable e insertar un documento con campos cifrados.
Después de completar los pasos en esta guía, deberías ser capaz de crear una colección cifrada e insertar un documento con campos que estén cifrados con tu llave maestra de cliente.
Antes de comenzar
Crea tu aplicación habilitada para cifrado consultable antes de crear una colección cifrada.
Si utilizas cifrado explícito, también debes crear con antelación una llave de cifrado de datos única para cada campo cifrado. Para obtener más información, consulta Llaves de cifrado y almacenes de claves.
Procedimiento
Especificar campos para cifrar
Para cifrar un campo, agrégalos al esquema de cifrado. Para habilitar consultas en un campo, añade el queries propiedad. Puedes habilitar campos para que sean consultables mediante consultas de igualdad o consultas de rango. Los siguientes pasos demuestran cómo especificar los campos para cifrar con cada tipo de query.
Especificar campos para consultas de igualdad
Para habilitar query de igualdad en un campo, añade el campo al esquema de cifrado con un valor
queryTypede"equality". El siguiente ejemplo de código cifra tanto los camposssncomobilling, pero solo se puede consultar el campossn: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, }, ] }; Especificar campos para consultas de rango
Para habilitar consultas de rango en un campo, añade el campo al esquema de cifrado con un
queryTypede"range". El siguiente ejemplo añade el campobillAmountal esquema de cifrado creado en el paso anterior y habilita queries de rango en él:const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, { path: "patientRecord.billAmount", bsonType: "int", queries: { queryType: "range", sparsity: 1, trimFactor: 4, min: 100, max: 2000, }, }, ], }, }; 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" } }, new BsonDocument { { "keyId", BsonNull.Value }, { "path", "patientRecord.billAmount" }, { "bsonType", "int" }, { "queries", new BsonDocument { { "queryType", "range" }, { "sparsity", 1 }, { "min", 100 }, { "max", 2000 }, { "trimFactor", 4 } } }, } } } }; 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", }, bson.M{ "keyId": nil, "path": "patientRecord.billAmount", "bsonType": "int", "queries": []bson.M{ { "queryType": "range", "sparsity": 1, "min": 100, "max": 2000, "trimFactor": 4, }, }, }, }, } 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")), new BsonDocument() .append("keyId", new BsonNull()) .append("path", new BsonString("patientRecord.billAmount")) .append("bsonType", new BsonString("int")) .append("queries", new BsonDocument() .append("queryType", new BsonString("range")) .append("sparsity", new BsonInt32(1)) .append("trimFactor", new BsonInt32(4)) .append("min", new BsonInt32(100)) .append("max", new BsonInt32(2000)) )))); const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, { path: "patientRecord.billAmount", bsonType: "int", queries: { queryType: "range", sparsity: 1, trimFactor: 4, min: 100, max: 2000, }, }, ], }, }; $encryptedFieldsMap = [ 'encryptedFields' => [ 'fields' => [ [ 'path' => 'patientRecord.ssn', 'bsonType' => 'string', 'queries' => ['queryType' => 'equality'], 'keyId' => null, ], [ 'path' => 'patientRecord.billing', 'bsonType' => 'object', 'keyId' => null, ], [ 'path' => 'patientRecord.billAmount', 'bsonType' => 'int', 'queries' => [ 'queryType' => 'range', 'sparsity' => 1, 'trimFactor' => 4, 'min' => 100, 'max' => 2000, ], 'keyId' => null, ], ], ], ]; encrypted_fields_map = { "fields": [ { "path": "patientRecord.ssn", "bsonType": "string", "queries": [{"queryType": "equality"}] }, { "path": "patientRecord.billing", "bsonType": "object", }, { "path": "patientRecord.billAmount", "bsonType": "int", "queries": [{ "queryType": "range", "sparsity": 1, "min": 100, "max": 2000, "trimFactor": 4 }], }, ] } encrypted_fields_map = { encrypted_fields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, keyId: nil }, { path: "patientRecord.billing", bsonType: "object", keyId: nil }, { path: "patientRecord.billAmount", bsonType: "int", queries: { queryType: "range", sparsity: 1, trimFactor: 4, min: 100, max: 2000 }, 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, }, { "path": "patientRecord.billAmount", "bsonType": "int", "queries": { "queryType": "range", "sparsity": 1, "min": 100, "max": 2000, "trimFactor": 4 }, }, ] };
Para obtener versiones ampliadas de estos pasos, consulte Crear un esquema de cifrado.
Cree una instancia de un objeto de cifrado de cliente para acceder a la API para los métodos auxiliares de cifrado
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 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();
Crear la colección
Importante
Cree explícitamente su colección, en lugar de crearla implícitamente con una operación de inserción. Cuando creas una colección usando createCollection(), MongoDB crea un índice en los campos cifrados. Sin este índice, las queries en campos cifrados pueden ejecutarse lentamente.
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; [] 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);
Tip
Base de datos vs. Nombre de base de datos
El método que crea la colección requiere una referencia a un objeto de base de datos en lugar del nombre de la base de datos.
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, )
Tip
Base de datos vs. Nombre de base de datos
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); }
Tip
Base de datos vs. Nombre de base de datos
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.
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.
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( encryptedDatabase, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, } );
Tip
Base de datos vs. Nombre de base de datos
El método que crea la colección cifrada requiere una referencia a un objeto de base de datos en lugar de al nombre de la base de datos.
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, )
Tip
Base de datos vs. Nombre de base de datos
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 utilizando el método auxiliar de cifrado al que se accede 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 )
Este método genera automáticamente claves de cifrado de datos para sus campos cifrados y crea la colección cifrada.
Tip
Base de datos vs. Nombre de base de datos
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?;
Tip
Base de datos vs. Nombre de base de datos
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.
Para obtener información adicional, consulta Activar el cifrado con capacidad de consulta al crear una colección.
Inserte un documento con campos cifrados
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, billAmount: 1500, }, }; const encryptedCollection = encryptedClient .getDB(encryptedDatabaseName) .getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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);
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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)) }
Este tutorial utiliza POJOs como modelos de datos para representar la estructura del documento. Para configurar tu aplicación para que use POJOs, agrega el siguiente código:
CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build(); CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
Para aprender más sobre los POJO de Java, consulta el Artículo de Wikipedia sobre objetos Java simples y sencillos.
Este tutorial utiliza los siguientes POJO:
PatientPatientRecordPatientBilling
Puedes ver estas clases en el paquete de modelos de la aplicación Java completa.
Agregue estas clases POJO a su aplicación. Luego, cree una instancia de un Patient que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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);
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, billAmount: 1500, }, }; const encryptedCollection = encryptedClient .db(encryptedDatabaseName) .collection(encryptedCollectionName); const result = await encryptedCollection.insertOne(patientDocument);
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
$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);
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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)
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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)
Cree un documento de muestra que describa la información personal de un paciente. Utilice el cliente cifrado para insertarlo en la colección patients, como se muestra en el siguiente ejemplo:
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?;
Próximos pasos
Después de crear una colección habilitada para Cifrado consultable, puedes query los campos cifrados.