Overview
Esta guía le muestra cómo crear una aplicación que implementa la función de cifrado consultable de MongoDB para cifrar y descifrar automáticamente campos de documentos y utilizar un proveedor de claves compatible con el Protocolo de interoperabilidad de administración de claves (KMIP) para la administración de claves.
Después de completar los pasos de esta guía, debería tener:
Una Llave Maestra de Cliente administrada por un Proveedor de claves compatible conKMIP
Una aplicación cliente funcional que inserta documentos con campos cifrados utilizando su clave maestra de cliente
Tip
Llaves maestras del cliente
Para obtener más información sobre la Llave Maestra del Cliente, lea el Documentación de claves y bóvedas de claves.
Antes de empezar
Para completar y ejecutar el código de esta guía, debe configurar su 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 ejemplo, seleccione la pestaña correspondiente a su lenguaje de programación y siga el enlace proporcionado. Cada repositorio de aplicaciones de ejemplo incluye un
README.md archivo que puede utilizar para aprender cómo configurar su entorno y ejecutar la aplicación.
Configurar el KMS
Configure su proveedor de claves compatible con KMIP
Para conectar un cliente de controlador MongoDB a su proveedor de claves compatible con KMIP,debe configurar su proveedor de claves compatible con KMIP de modo que acepte el certificado TLS de su cliente.
Consulta la documentación de tu proveedor de claves compatible con KMIPpara obtener información sobre cómo aceptar tu certificado de cliente.
Especifique sus certificados
Su cliente debe conectarse a su proveedor de claves compatible con KMIP a través de TLS y presentar un certificado de cliente que su proveedor de claves compatible con KMIPacepte:
const tlsOptions = { kmip: { tlsCAFile: process.env["KMIP_TLS_CA_FILE"], // Path to your TLS CA file tlsCertificateKeyFile: process.env["KMIP_TLS_CERT_FILE"], // Path to your TLS certificate key file }, };
var tlsOptions = new Dictionary<string, SslSettings>(); var sslSettings = new SslSettings(); var clientCertificate = new X509Certificate2(_appSettings["Kmip:TlsCertP12"]!); // Full path to your client certificate p12 file sslSettings.ClientCertificates = new[] { clientCertificate }; tlsOptions.Add("kmip", sslSettings);
Importante
Su certificado de cliente debe estar en12 formato pcs. Puede convertir su certificado mediante OpenSSL con el siguiente comando:
openssl pcks12 -export -out "<new pcks12 certificate>" -in "<certificate to convert>" \ -name "<new certificate name>" -password "<new certificate password>"
tlsOpts := map[string]interface{}{ "tlsCertificateKeyFile": os.Getenv("KMIP_TLS_CERT_ECDSA_FILE"), // Path to your client certificate file "tlsCAFile": os.Getenv("KMIP_TLS_CA_ECDSA_FILE"), // Path to your KMIP certificate authority file } kmipConfig, err := options.BuildTLSConfig(tlsOpts) if err != nil { panic(fmt.Sprintf("Unable to retrieve certificates from your environment: %s\n", err)) } tlsConfig := map[string]*tls.Config{ "kmip": kmipConfig, }
Configure las siguientes opciones de máquina virtual para especificar el almacén de claves y el almacén de confianza que contienen sus certificados TLS de KMIP y agréguelos al comando que utiliza para iniciar su aplicación Java:
-Djavax.net.ssl.enabled=true -Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=REPLACE-WITH-PATH-TO-PKC-KEYSTORE -Djavax.net.ssl.keyStorePassword=REPLACE-WITH-KEYSTORE-PASSWORD -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStore=REPLACE-WITH-PATH-TO-TRUSTSTORE -Djavax.net.ssl.trustStorePassword=REPLACE-WITH-TRUSTSTORE-PASSWORD
Nota
Configurar el cliente con SSLContext
Si prefieres configurar tu aplicación cliente utilizando un contexto SSL, usa el método kmsProviderSslContextMap.
const tlsOptions = { kmip: { tlsCAFile: process.env.KMIP_TLS_CA_FILE, // Path to your TLS CA file tlsCertificateKeyFile: process.env.KMIP_TLS_CERT_FILE, // Path to your TLS certificate key file }, };
tls_options = { "kmip": { "tlsCAFile": os.environ['KMIP_TLS_CA_FILE'], # Path to your TLS CA file "tlsCertificateKeyFile": os.environ['KMIP_TLS_CERT_FILE'] # Path to your TLS certificate key file } }
Crear la aplicación
Asignar variables a su aplicación
Los ejemplos de código de este tutorial utilizan las siguientes variables para realizar el flujo de trabajo de cifrado consultable:
kmsProviderName: el KMS que utiliza para almacenar su clave maestra de cliente. Establezca esta variable en
"kmip"para este tutorial.uri: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en la
MONGODB_URIvariable de entorno o reemplace el valor directamente.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 sus DEK. Establezca esta variable
"__keyVault"en.keyVaultNamespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las
keyVaultDatabaseNamekeyVaultCollectionNamevariables y, separados por un punto.encryptedDatabaseName: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"medicalRecords"en.encryptedCollectionName: La colección en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"patients"en.
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
"kmip"para este tutorial.keyVaultDatabaseName: La base de datos en MongoDB donde se almacenarán sus claves de cifrado de datos (DEK). Establezca el valor de
keyVaultDatabaseName"encryption"en.keyVaultCollectionName: La colección en MongoDB donde se almacenarán sus DEK. Establezca el valor de
keyVaultCollectionName"__keyVault"en.keyVaultNamespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca
keyVaultNamespacecomo un nuevoCollectionNamespaceobjeto cuyo nombre contenga los valores de laskeyVaultDatabaseNamekeyVaultCollectionNamevariables y, separados 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: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en el
appsettings.jsonarchivo o 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 utiliza para almacenar su clave maestra de cliente. Establezca esta variable en
"kmip"para este tutorial.uri: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en la
MONGODB_URIvariable de entorno o reemplace el valor directamente.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 sus DEK. Establezca esta variable
"__keyVault"en.keyVaultNamespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las
keyVaultDatabaseNamekeyVaultCollectionNamevariables y, separados por un punto.encryptedDatabaseName: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"medicalRecords"en.encryptedCollectionName: La colección en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"patients"en.
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 utiliza para almacenar su clave maestra de cliente. Establezca esta variable en
"kmip"para este tutorial.uri: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en la
MONGODB_URIvariable de entorno o reemplace el valor directamente.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 sus DEK. Establezca esta variable
"__keyVault"en.keyVaultNamespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las
keyVaultDatabaseNamekeyVaultCollectionNamevariables y, separados por un punto.encryptedDatabaseName: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"medicalRecords"en.encryptedCollectionName: La colección en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"patients"en.
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 utiliza para almacenar su clave maestra de cliente. Establezca esta variable en
"kmip"para este tutorial.uri: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en la
MONGODB_URIvariable de entorno o reemplace el valor directamente.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 sus DEK. Establezca esta variable
"__keyVault"en.keyVaultNamespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las
keyVaultDatabaseNamekeyVaultCollectionNamevariables y, separados por un punto.encryptedDatabaseName: La base de datos en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"medicalRecords"en.encryptedCollectionName: La colección en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"patients"en.
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 utiliza para almacenar su clave maestra de cliente. Establezca esta variable en
"kmip"para este tutorial.uri: la URI de conexión de su implementación de MongoDB. Establezca la URI de conexión en la
MONGODB_URIvariable de entorno o reemplace el valor directamente.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 sus DEK. Establezca esta variable
"__keyVault"en.key_vault_namespace: El espacio de nombres en MongoDB donde se almacenarán sus DEK. Establezca esta variable con los valores de las
key_vault_database_namekey_vault_collection_namevariables y, separados 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: La colección en MongoDB donde se almacenarán sus datos cifrados. Establezca esta variable
"patients"en.
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 Key Vault se encuentra en el encryption.__keyVault espacio de nombres. Asegúrese de que el usuario de la base de datos que su aplicación usa para conectarse a MongoDB tenga permisos de lectura y escritura en este espacio de nombres.
Tip
Variables de entorno
El código de ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 ejemplo de este tutorial hace referencia a las variables de entorno que debe configurar. También puede reemplazar los valores directamente en el código.
Para saber cómo 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 KMS de proveedor de claves compatibles con KMIP
Cree una variable que contenga el punto final de su proveedor de claves compatible con KMIP con la siguiente estructura:
kmsProviderCredentials = { kmip: { endpoint: process.env["KMIP_KMS_ENDPOINT"], // Your KMIP KMS endpoint }, };
var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>(); var kmsOptions = new Dictionary<string, object> { { "endpoint", _appSettings["Kmip:KmsEndpoint"] } // Your KMIP KMS endpoint }; kmsProviderCredentials.Add(kmsProvider, kmsOptions);
kmsProviderCredentials := map[string]map[string]interface{}{ "kmip": { "endpoint": os.Getenv("KMIP_KMS_ENDPOINT"), // KMIP KMS endpoint }, }
Map<String, Object> kmsProviderDetails = new HashMap<>(); kmsProviderDetails.put("endpoint", getEnv("KMIP_KMS_ENDPOINT")); // Your KMIP KMS endpoint Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>(); kmsProviderCredentials.put("kmip", kmsProviderDetails);
kmsProviders = { kmip: { endpoint: process.env.KMIP_KMS_ENDPOINT, // Your KMIP KMS endpoint }, };
kms_provider_credentials = { "kmip": { "endpoint": os.environ['KMIP_KMS_ENDPOINT'] # Your KMIP KMS endpoint } }
Agregue sus credenciales de clave maestra de cliente
Cree un objeto vacío como se muestra en el siguiente ejemplo de código. Esto solicitará a su proveedor de claves compatible con KMIPque genere una nueva clave maestra de cliente.
customerMasterKeyCredentials = {};
var customerMasterKeyCredentials = new BsonDocument();
cmkCredentials := map[string]string{}
BsonDocument customerMasterKeyCredentials = new BsonDocument();
customerMasterKeyCredentials = {};
customer_master_key_credentials = {}
Configure sus opciones de cifrado automático
Crea un objeto autoEncryptionOptions que contenga las siguientes opciones:
El espacio de nombres de su colección de Key Vault
El
kmsProviderCredentialsobjeto, que contiene su punto final KMIPEl
tlsOptionsobjeto que creó en el paso Especifique sus certificados
const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials, tlsOptions, };
Crea un objeto AutoEncryptionOptions que contenga las siguientes opciones:
El espacio de nombres de su colección de Key Vault
El
kmsProviderCredentialsobjeto, que contiene su punto final KMIPEl objeto
extraOptions, que contiene la ruta a su biblioteca compartida de cifrado automáticoEl
tlsOptionsobjeto que creó en el paso Especifique sus certificados
var extraOptions = new Dictionary<string, object> { { "cryptSharedLibPath", _appSettings["CryptSharedLibPath"] } // Path to your Automatic Encryption Shared Library }; var autoEncryptionOptions = new AutoEncryptionOptions( keyVaultNamespace, kmsProviderCredentials, extraOptions: extraOptions, tlsOptions: tlsOptions);
Crea un objeto AutoEncryption que contenga las siguientes opciones:
El espacio de nombres de su colección de Key Vault
El
kmsProviderCredentialsobjeto, que contiene su punto final KMIPEl objeto
cryptSharedLibraryPath, que contiene la ruta a su biblioteca compartida de cifrado automáticoEl
tlsConfigobjeto que creó en el paso Especifique sus certificados
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). SetTLSConfig(tlsConfig)
Crea un objeto AutoEncryptionSettings que contenga las siguientes opciones:
El espacio de nombres de su colección de Key Vault
El
kmsProviderCredentialsobjeto, que contiene su punto final KMIPEl objeto
extraOptions, que contiene la ruta a su biblioteca 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 contenga las siguientes opciones:
El espacio de nombres de su colección de Key Vault
El
kmsProvidersobjeto, que contiene su punto final KMIPEl objeto
sharedLibraryPathOptions, que contiene la ruta a su biblioteca compartida de cifrado automáticoEl
tlsOptionsobjeto que creó en el paso Especifique sus certificados
const extraOptions = { cryptSharedLibPath: process.env.SHARED_LIB_PATH, // Path to your Automatic Encryption Shared Library }; const autoEncryptionOptions = { keyVaultNamespace, kmsProviders, extraOptions, tlsOptions, };
Crea un objeto AutoEncryptionOpts que contenga las siguientes opciones:
El
kms_provider_credentialsobjeto, que contiene su punto final KMIPEl espacio de nombres de su colección de Key Vault
La ruta a su biblioteca compartida de cifrado automático
El
tls_optionsobjeto que creó en el paso Especifique sus certificados
auto_encryption_opts = AutoEncryptionOpts( kms_provider_credentials, key_vault_namespace, crypt_shared_lib_path=os.environ['SHARED_LIB_PATH'], # Path to your Automatic Encryption Shared Library kms_tls_options=tls_options )
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 utilizado para cifrar y descifrar datos en su colección, cree una instancia de MongoClient nueva mediante su URI de conexión y sus 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, añádalo al esquema de cifrado. Para habilitar las consultas en un campo, agregue la propiedad "consultas". Cree el esquema de cifrado de la siguiente manera:
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
Cree una instancia de ClientEncryption 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);
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 utiliza clases independientes como modelos de datos para representar la estructura del documento. Agregue las siguientes clases Patient, PatientRecord y PatientBilling a su 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 Golang de este tutorial utiliza modelos de datos para representar la estructura del documento. Agregue las siguientes estructuras a su proyecto para representar los datos de su 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 Node.js v6.0 y posterior, 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); encryptedCollection.InsertOne(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 su aplicación para usar POJOs, agregue 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 POJO de Java, consulte el artículo de Wikipedia Plain Old Java Object.
Este tutorial utiliza los siguientes POJO:
PatientPatientRecordPatientBilling
Puede 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)
Consulta en 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("record.ssn", patient.Record.Ssn); var findResult = await encryptedCollection.Find(ssnFilter).ToCursorAsync(); Console.WriteLine(findResult.FirstOrDefault().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 el cifrado consultable. No modifique su contenido.
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, consulte 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.
Vea cómo los proveedores de KMS administran sus claves de cifrado consultables en la página Proveedores de KMS.