Overview
Esta guía muestra cómo crear una aplicación que implemente la función de Queryable Encryption de MongoDB para encriptar y desencriptar automáticamente campos de documentos y utilizar el Google Cloud Key Management Service para la gestión de claves.
Después de completar los pasos en esta guía, deberías tener:
A CMK administrado por el servicio de administración de claves de Google Cloud
Una aplicación cliente funcional que inserta documentos con campos cifrados usando tu llave maestra de cliente
Tip
llave maestra de cliente
Para aprender más sobre la llave maestra de cliente, consulta el documentación sobre claves y almacenes de claves.
Antes de empezar
Para completar y ejecutar el código de esta guía, debes configurar tu entorno de desarrollo como se muestra en la página Requisitos de instalación.
Tip
Ver: Solicitud completa
Para ver el código completo de esta aplicación de muestra, selecciona la pestaña correspondiente a tu lenguaje de programación y sigue el enlace proporcionado. Cada repositorio de aplicaciones de muestra incluye
README.md file that you can use to learn how to set up your environment and run the application. (archivo que puedes usar para aprender cómo configurar tu entorno y ejecutar la aplicación.)
Configure el KMS
Registrar una cuenta de servicio de Google Cloud
Regístrese o inicie sesión en su cuenta existente en Google Cloud.
Cree una cuenta de servicio para su proyecto
Para crear una cuenta de servicio en Google Cloud, sigue la Guía de creación de una cuenta de servicio guía en la documentación oficial de Google.
Agregar una clave de cuenta de servicio
Para agregar una clave de cuenta de servicio en Google Cloud, siga la guía Administrar claves de cuenta de servicio en la documentación oficial de Google.
Importante
Al crear la clave de su cuenta de servicio, recibirá una descarga única de la información de la clave privada. Asegúrese de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.
Importante
Al crear la clave de su cuenta de servicio, recibirá una descarga única de la información de la clave privada. Asegúrese de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.
Importante
Al crear la clave de su cuenta de servicio, recibirá una descarga única de la información de la clave privada. Asegúrese de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.
Importante
Al crear la clave de la cuenta de servicio, recibes una descarga única de la información de la clave privada. A menos que estés usando una cuenta de servicio adjunta, asegúrate de descargar este archivo en formato PKCS12 o JSON para que puedas usarlo más adelante en este tutorial.
Importante
Al crear la clave de su cuenta de servicio, recibirá una descarga única de la información de la clave privada. Asegúrese de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.
Importante
Al crear la clave de su cuenta de servicio, recibirá una descarga única de la información de la clave privada. Asegúrese de descargar este archivo en formato PKCS12 o JSON para usarlo más adelante en este tutorial.
Crear una llave maestra de cliente (GCP)
Crear una nueva llave maestra de cliente
Crea un llavero y una llave simétrica siguiendo la guía Crear una llave de la documentación oficial de Google.
Esta clave es su clave maestra de cliente (CMK).
Registra los siguientes detalles de tu llave maestra de cliente para utilizarlos en una futura etapa de este tutorial.
Campo | Requerido | Descripción |
|---|---|---|
key_name | Sí | Identificador para el CMK. |
key_ring | Sí | Identificador del grupo de claves al que pertenece su clave. |
key_version | No | La versión de la clave nombrada. |
ubicación | Sí | Región especificada para tu clave. |
endpoint | No | The host y el Puerto opcional del Google Cloud KMS. El valor por defecto es |
Crear la aplicación
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:
kmsProviderName - El KMS que estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en
"gcp"para este tutorial.uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno
MONGODB_URIo reemplaza directamente el valor.keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Configure esta variable en
"encryption".keyVaultCollectionName: la colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a
"__keyVault".keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables
keyVaultDatabaseNameykeyVaultCollectionName, separadas por un punto.encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establece esta variable a
"medicalRecords".encryptedCollectionName - La colección en MongoDB donde se almacenarán tus datos cifrados. Establece esta variable a
"patients".
Puede declarar estas variables utilizando el siguiente código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" 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: el KMS que utiliza para almacenar su clave maestra de cliente. Configure este valor en
"gcp"para este tutorial.keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Establece el valor de
keyVaultDatabaseNameen"encryption".keyVaultCollectionName: La colección en MongoDB donde se almacenarán sus DEK. Establezca el valor de
keyVaultCollectionName"__keyVault"en.keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establece
keyVaultNamespaceen un nuevo objetoCollectionNamespacecuyo nombre es el de las variableskeyVaultDatabaseNameykeyVaultCollectionName, separadas por un punto.encryptedDatabaseName: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca el valor de
encryptedDatabaseName"medicalRecords"en.encryptedCollectionName: la colección en MongoDB donde se almacenarán tus datos cifrados. Establecer el valor de
encryptedCollectionNamea"patients".uri - Su URI de conexión de implementación de MongoDB. Establezca su URI de conexión en el archivo
appsettings.jsono reemplace el valor directamente.
Puede declarar estas variables utilizando el siguiente código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" 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 - El KMS que estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en
"gcp"para este tutorial.uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno
MONGODB_URIo reemplaza directamente el valor.keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Configure esta variable en
"encryption".keyVaultCollectionName: la colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a
"__keyVault".keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables
keyVaultDatabaseNameykeyVaultCollectionName, separadas por un punto.encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establece esta variable a
"medicalRecords".encryptedCollectionName - La colección en MongoDB donde se almacenarán tus datos cifrados. Establece esta variable a
"patients".
Puede declarar estas variables utilizando el siguiente código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" kmsProviderName := "<KMS provider name>" uri := os.Getenv("MONGODB_URI") // Your connection URI keyVaultDatabaseName := "encryption" keyVaultCollectionName := "__keyVault" keyVaultNamespace := keyVaultDatabaseName + "." + keyVaultCollectionName encryptedDatabaseName := "medicalRecords" encryptedCollectionName := "patients"
kmsProviderName - El KMS que estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en
"gcp"para este tutorial.uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno
MONGODB_URIo reemplaza directamente el valor.keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Configure esta variable en
"encryption".keyVaultCollectionName: la colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a
"__keyVault".keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables
keyVaultDatabaseNameykeyVaultCollectionName, separadas por un punto.encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establece esta variable a
"medicalRecords".encryptedCollectionName - La colección en MongoDB donde se almacenarán tus datos cifrados. Establece esta variable a
"patients".
Puede declarar estas variables utilizando el siguiente código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" 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";
kmsProviderName - El KMS que estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en
"gcp"para este tutorial.uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno
MONGODB_URIo reemplaza directamente el valor.keyVaultDatabaseName - La base de datos en MongoDB donde se almacenarán sus llaves de cifrado de datos (DEK). Configure esta variable en
"encryption".keyVaultCollectionName: la colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a
"__keyVault".keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables
keyVaultDatabaseNameykeyVaultCollectionName, separadas por un punto.encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establece esta variable a
"medicalRecords".encryptedCollectionName - La colección en MongoDB donde se almacenarán tus datos cifrados. Establece esta variable a
"patients".
Puede declarar estas variables utilizando el siguiente código:
// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" 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";
kms_provider_name - El KMS que utilizas para almacenar tu llave maestra de cliente. Establece esta variable en
"gcp"para este tutorial.uri - Su URI de conexión de implementación de MongoDB. Establece tu URI de conexión en la variable de entorno
MONGODB_URIo reemplaza directamente el valor.key_vault_database_name: La base de datos de MongoDB donde se almacenarán sus claves de cifrado de datos (DEK). Establezca esta variable
"encryption"en.key_vault_collection_name - La colección en MongoDB donde se almacenarán tus DEK. Establece esta variable a
"__keyVault".key_vault_namespace - El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las variables
key_vault_database_nameykey_vault_collection_name, separadas por un punto.encrypted_database_name: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"medicalRecords"en.encrypted_collection_name - Es la colección en MongoDB donde se almacenarán tus datos cifrados. Configure esta variable en
"patients".
Puede declarar estas variables utilizando el siguiente código:
# KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local" 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"
Importante
Permisos del espacio de nombres de la colección Key Vault
La Colección de Bóvedas de Llaves está en el namespace encryption.__keyVault. Asegúrate de que el usuario de la base de datos que tu aplicación usa para conectarse a MongoDB tenga permisos ReadWrite en este namespace.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Tip
Variables de entorno
El código de muestra en este tutorial hace referencia a variables de entorno que necesitas definir. Alternativamente, puedes reemplazar los valores directamente en el código.
Para aprender cómo puede configurar estas variables de entorno, consulte el archivo README.md incluido en la aplicación de muestra en GitHub.
Crea tu colección cifrada
Agregue sus credenciales de Google Cloud Key Management Service
Crea una variable que contenga tus credenciales de Google Cloud Key Management Service con la siguiente estructura:
kmsProviderCredentials = { gcp: { email: process.env["GCP_EMAIL"], // Your GCP email privateKey: process.env["GCP_PRIVATE_KEY"], // Your GCP private key }, };
var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>(); var kmsOptions = new Dictionary<string, object> { { "email", _appSettings["Gcp:Email"] }, // Your GCP email { "privateKey", _appSettings["Gcp:PrivateKey"] } // Your GCP private key }; kmsProviderCredentials.Add(kmsProvider, kmsOptions);
kmsProviderCredentials := map[string]map[string]interface{}{ "gcp": { "email": os.Getenv("GCP_EMAIL"), // GCP email "privateKey": os.Getenv("GCP_PRIVATE_KEY"), // GCP private key }, }
Map<String, Object> kmsProviderDetails = new HashMap<>(); kmsProviderDetails.put("email", getEnv("GCP_EMAIL")); // Your GCP email kmsProviderDetails.put("privateKey", getEnv("GCP_PRIVATE_KEY")); // Your GCP private key Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>(); kmsProviderCredentials.put("gcp", kmsProviderDetails);
kmsProviders = { gcp: { email: process.env.GCP_EMAIL, // Your GCP email privateKey: process.env.GCP_PRIVATE_KEY, // Your GCP private key }, };
kms_provider_credentials = { "gcp": { "email": os.environ['GCP_EMAIL'], # Your GCP email "privateKey": os.environ['GCP_PRIVATE_KEY'] # Your GCP private key } }
Agregar sus credenciales de clave maestra de cliente
Cree una variable que contenga sus credenciales de clave maestra de cliente con la siguiente estructura. Utilice las credenciales que registró en el paso "Crear una nueva clave maestra de cliente" de este tutorial.
customerMasterKeyCredentials = { projectId: process.env["GCP_PROJECT_ID"], // Your GCP Project ID location: process.env["GCP_LOCATION"], // Your GCP Key Location keyRing: process.env["GCP_KEY_RING"], // Your GCP Key Ring keyName: process.env["GCP_KEY_NAME"], // Your GCP Key Name };
var customerMasterKeyCredentials = new BsonDocument { { "projectId", _appSettings["Gcp:ProjectId"] }, // Your GCP Project ID { "location", _appSettings["Gcp:Location"] }, // Your GCP Key Location { "keyRing", _appSettings["Gcp:KeyRing"] }, // Your GCP Key Ring { "keyName", _appSettings["Gcp:KeyName"] } // Your GCP Key Name };
customerMasterKeyCredentials := map[string]string{ "projectId": os.Getenv("GCP_PROJECT_ID"), // Your GCP Project ID "location": os.Getenv("GCP_LOCATION"), // Your GCP Key Location "keyRing": os.Getenv("GCP_KEY_RING"), // Your GCP Key Ring "keyName": os.Getenv("GCP_KEY_NAME"), // Your GCP Key Name }
BsonDocument customerMasterKeyCredentials = new BsonDocument(); customerMasterKeyCredentials.put("provider", new BsonString(kmsProviderName)); customerMasterKeyCredentials.put("projectId", new BsonString(getEnv("GCP_PROJECT_ID"))); // Your GCP Project ID customerMasterKeyCredentials.put("location", new BsonString(getEnv("GCP_LOCATION"))); // Your GCP Key Location customerMasterKeyCredentials.put("keyRing", new BsonString(getEnv("GCP_KEY_RING"))); // Your GCP Key Ring customerMasterKeyCredentials.put("keyName", new BsonString(getEnv("GCP_KEY_NAME"))); // Your GCP Key Name
customerMasterKeyCredentials = { projectId: process.env.GCP_PROJECT_ID, // Your GCP Project ID location: process.env.GCP_LOCATION, // Your GCP Key Location keyRing: process.env.GCP_KEY_RING, // Your GCP Key Ring keyName: process.env.GCP_KEY_NAME, // Your GCP Key Name };
customer_master_key_credentials = { "projectId": os.environ['GCP_PROJECT_ID'], # Your GCP email "location": os.environ['GCP_LOCATION'], # Your GCP private key "keyRing": os.environ['GCP_KEY_RING'], # Your GCP private key "keyName": os.environ['GCP_KEY_NAME'] # Your GCP private key }
Configura tus opciones de cifrado automático
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, que contiene tus credenciales de Google Cloud Key Management Service
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, que contiene tus credenciales de Google Cloud Key Management ServiceEl objeto
extraOptions, que contiene la ruta a tu librería Compartida de Cifrado Automático
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, que contiene tus credenciales de Google Cloud Key Management ServiceEl objeto
cryptSharedLibraryPath, que contiene la ruta a tu 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, que contiene tus credenciales de Google Cloud Key Management ServiceEl objeto
extraOptions, que contiene la ruta a tu 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();
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, que contiene tus credenciales de Google Cloud Key Management ServiceEl objeto
sharedLibraryPathOptions, que contiene la ruta a tu 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 AutoEncryptionOpts que contiene las siguientes opciones:
El objeto
kms_provider_credentials, que contiene tus credenciales de Google Cloud Key Management ServiceEl 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> )
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 obtener más información sobre la biblioteca compartida de cifrado automático, consulte la página Biblioteca compartida de cifrado automático para cifrado consultable.
Crear un cliente para configurar una colección cifrada
Para crear un cliente que se utilice para cifrar y descifrar datos en tu colección, instancia un nuevo MongoClient utilizando tu URI de conexión y tus opciones de cifrado automático.
const encryptedClient = Mongo(uri, autoEncryptionOptions);
var clientSettings = MongoClientSettings.FromConnectionString(uri); clientSettings.AutoEncryptionOptions = qeHelpers.GetAutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials); var encryptedClient = new MongoClient(clientSettings);
encryptedClient, err := mongo.Connect( context.TODO(), options.Client().ApplyURI(uri).SetAutoEncryptionOptions(autoEncryptionOptions), ) 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, });
encrypted_client = MongoClient( uri, auto_encryption_opts=auto_encryption_options)
Especificar campos para cifrar
Para cifrar un campo, agrégalos al esquema de cifrado. Para habilitar las consultas en un campo, agregue la propiedad "queries". Cree el esquema de cifrado como sigue:
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", "record.ssn" }, { "bsonType", "string" }, { "queries", new BsonDocument("queryType", "equality") } }, new BsonDocument { { "keyId", BsonNull.Value }, { "path", "record.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", }, ], }, };
encrypted_fields_map = { "fields": [ { "path": "patientRecord.ssn", "bsonType": "string", "queries": [{"queryType": "equality"}] }, { "path": "patientRecord.billing", "bsonType": "object", } ] }
Nota
En el ejemplo de código anterior, los campos "ssn" y "facturación" están cifrados, pero solo se puede consultar el campo "ssn".
Crear la colección
Instancie ClientEncryption para acceder a la API de los métodos de asistente 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);
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) )
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 Name { get; set; } public PatientRecord Record { get; set; } }
public class PatientRecord { public string Ssn { get; set; } public PatientBilling Billing { 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 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"` }
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 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[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.
Insertar 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", }, }, }; 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 { Name = "Jon Doe", Id = new ObjectId(), Record = new PatientRecord { Ssn = "987-65-4320", Billing = new PatientBilling { CardType = "Visa", CardNumber = 4111111111111111 } } }; 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: "John Doe", PatientID: 12345678, PatientRecord: PatientRecord{ SSN: "987-65-4320", Billing: PaymentInfo{ Type: "Visa", Number: "4111111111111111", }, }, } 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 obtener más información sobre los POJOs de Java, consulta el artículo de Wikipedia sobre Plain Old Java Object..
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); 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", }, }, }; 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:
patient_document = { "patientName": "Jon Doe", "patientId": 12345678, "patientRecord": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111", }, }, } encrypted_collection = encrypted_client[encrypted_database_name][encrypted_collection_name] result = encrypted_collection.insert_one(patient_document)
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);
find_result = encrypted_collection.find_one({ "patientRecord.ssn": "987-65-4320" }) print(find_result)
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" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ] }
Advertencia
No modifique el campo __safeContent__
El campo __safeContent__ es esencial para Queryable Encryption. No modifiques el contenido de este campo.
Obtén más información
Para saber cómo funciona el cifrado consultable, consulte Fundamentos del cifrado consultable.
Para obtener más información sobre los temas mencionados en esta guía, consulta los siguientes enlaces:
Obtenga más información sobre los componentes de cifrado consultable en la página de Referencia.
Obtenga información sobre cómo funcionan las claves maestras del cliente y las claves de cifrado de datos en la página Claves y bóvedas de claves.
Mira cómo los Proveedores de KMS gestionan tus claves de Encriptación Consultable en la página Proveedores de KMS.