Docs Menu
Docs Home
/ /

Utilizar Automatic Queryable Encryption con AWS

Esta guía muestra cómo compilar una aplicación que implemente la funcionalidad de Queryable Encryption de MongoDB para cifrar y descifrar automáticamente los campos de documentos y utilizar Amazon Web Services (AWS) KMS para la gestión de claves.

Después de completar los pasos en esta guía, deberías tener:

  • Una llave maestra de cliente gestionada por AWS KMS

  • Un usuario de AWS IAM con permisos para acceder a la llave maestra de cliente en AWS KMS

  • Una aplicación cliente funcional que inserta documentos con campos cifrados usando su 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.

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

Consulta: aplicación 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.)

Completa la Aplicación mongosh

1
1
2
3

Crea una nueva clave simétrica siguiendo la documentación oficial de AWS en Creación de claves KMS simétricas. La clave que cree es la llave maestra de cliente. Elige un nombre y una descripción que te ayuden a identificarla; estos campos no afectan la funcionalidad o configuración de tu llave maestra de cliente.

En el Usage Permissions paso del proceso de generación de claves, aplica la siguiente política de claves por defecto que permite a las políticas de Gestión de identidad y acceso (IAM) otorgar acceso a tu llave maestra de cliente:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "<ARN of your AWS account principal>"
},
"Action": "kms:*",
"Resource": "*"
}
]
}

Importante

Registra el Nombre de recurso de Amazon (ARN) y la región de tu clave maestra de cliente. Los utilizarás más adelante en los siguientes pasos de esta guía.

Tip

Políticas clave

Para obtener más información sobre las políticas clave, consulte Políticas clave en AWS KMS en la documentación oficial de AWS.

2
1
2

Crea un nuevo usuario IAM programático en la consola de gestión de AWS siguiendo la documentación oficial de AWS sobre Agregar un usuario. Utilizarás este usuario de IAM como cuenta de servicio para tu aplicación habilitada con cifrado consultable. Su aplicación se autentica con AWS KMS utilizando el usuario IAM para cifrar y descifrar sus llaves de cifrado de datos (DEK) con su llave maestra de cliente (CMK).

Importante

Registra tus credenciales

Asegúrese de registrar las siguientes credenciales de IAM en el paso final de la creación de su usuario IAM:

  • ID de clave de acceso

  • clave secreta de acceso

Tienes una oportunidad para guardar estas credenciales. Si no registra estas credenciales durante este paso, deberá crear otro usuario IAM.

3

Concede a tu usuario de IAM kms:Encrypt y kms:Decrypt permisos para tu clave maestra remota.

Importante

El nuevo usuario de IAM del cliente no debe tener permisos administrativos para la clave principal. Para mantener sus datos seguros, siga el principio de mínimo privilegio.

La siguiente política en línea permite que un usuario IAM encripte y desencripte con la llave maestra de cliente con los mínimos privilegios posibles:

Nota

ARN de clave maestra remota

La siguiente política requiere el ARN de la clave que usted genera en el paso Crear la Clave Principal de esta guía.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["kms:Decrypt", "kms:Encrypt"],
"Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
}
]
}

Para aplicar la política anterior a tu usuario IAM, sigue la Adición de permisos de identidad IAM guía en la documentación de AWS.

Importante

Autenticación con IAM Roles en producción

Cuando implementes tu aplicación habilitada para cifrado consultable en un entorno de producción, autentica tu aplicación usando un rol IAM en lugar de un usuario IAM .

Para obtener más información sobre roles IAM, consulta las siguientes páginas de la documentación oficial de AWS:

1

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 "aws" 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_URI o 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 keyVaultDatabaseName y keyVaultCollectionName, 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 estás utilizando para almacenar tu clave maestra de cliente. Configura este valor en "aws" 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 keyVaultDatabaseName en "encryption".

  • keyVaultCollectionName - La colección en MongoDB donde se almacenarán tus DEKs. Establezca el valor de keyVaultCollectionName en "__keyVault".

  • keyVaultNamespace - El namespace en MongoDB donde se almacenarán sus DEK. Establece keyVaultNamespace en un nuevo objeto CollectionNamespace cuyo nombre es el de las variables keyVaultDatabaseName y keyVaultCollectionName, separadas por un punto.

  • encryptedDatabaseName - La base de datos en MongoDB donde se almacenarán tus datos cifrados. Establezca el valor de encryptedDatabaseName en "medicalRecords".

  • encryptedCollectionName: la colección en MongoDB donde se almacenarán tus datos cifrados. Establecer el valor de encryptedCollectionName a "patients".

  • uri - Su URI de conexión de implementación de MongoDB. Establezca su URI de conexión en el archivo appsettings.json 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 estás utilizando para almacenar tu clave maestra de cliente. Establece esta variable en "aws" 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_URI o 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 keyVaultDatabaseName y keyVaultCollectionName, 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 "aws" 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_URI o 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 keyVaultDatabaseName y keyVaultCollectionName, 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 "aws" 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_URI o 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 keyVaultDatabaseName y keyVaultCollectionName, 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 "aws" 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_URI o reemplaza directamente el valor.

  • key_vault_database_name: La base de datos en MongoDB donde se almacenarán tus claves de cifrado de datos (DEK). Establezca esta variable en "encryption".

  • 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_name y key_vault_collection_name, separadas por un punto.

  • encrypted_database_name - La base de datos en MongoDB donde se almacenarán tus datos cifrados. Establezca esta variable en "medicalRecords".

  • 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 namespace de la Colección de Bóvedas de Llaves

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.

2
1

Cree una variable que contenga sus credenciales de AWS KMS con la siguiente estructura. Utiliza el ID de clave de acceso y la clave de acceso secreta que creaste en el paso Crear un usuario de IAM de este tutorial.

kmsProviderCredentials = {
aws: {
accessKeyId: process.env["AWS_ACCESS_KEY_ID"], // Your AWS access key ID
secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"], // Your AWS secret access key
},
};
var kmsProviderCredentials = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var kmsOptions = new Dictionary<string, object>
{
{ "accessKeyId", _appSettings["Aws:AccessKeyId"] }, // Your AWS access key ID
{ "secretAccessKey", _appSettings["Aws:SecretAccessKey"] } // Your AWS secret access key
};
kmsProviderCredentials.Add(kmsProvider, kmsOptions);
kmsProviderCredentials := map[string]map[string]interface{}{
"aws": {
"accessKeyId": os.Getenv("AWS_ACCESS_KEY_ID"), // AWS access key ID
"secretAccessKey": os.Getenv("AWS_SECRET_ACCESS_KEY"), // AWS secret access key
},
}
Map<String, Object> kmsProviderDetails = new HashMap<>();
kmsProviderDetails.put("accessKeyId", getEnv("AWS_ACCESS_KEY_ID")); // Your AWS access key ID
kmsProviderDetails.put("secretAccessKey", getEnv("AWS_SECRET_ACCESS_KEY")); // Your AWS secret access key
Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<String, Map<String, Object>>();
kmsProviderCredentials.put("aws", kmsProviderDetails);
kmsProviders = {
aws: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID, // Your AWS access key ID
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, // Your AWS secret access key
},
};
kms_provider_credentials = {
"aws": {
"accessKeyId": os.environ['AWS_ACCESS_KEY_ID'], # Your AWS access key ID
"secretAccessKey": os.environ['AWS_SECRET_ACCESS_KEY'] # Your AWS secret access key
}
}

Importante

Recordatorio: Autenticarse con Roles IAM en Producción

Para utilizar un rol IAM en lugar de un usuario IAM para autenticar tu aplicación, especifica un objeto vacío para tus credenciales en tu objeto proveedor KMS. Esto indica al driver que recupere automáticamente las credenciales del entorno:

kmsProviders = {
aws: { }
};
kmsProviderCredentials.Add("aws", new Dictionary<string, object>);
kmsProviderCredentials := map[string]map[string]interface{}{
"aws": { },
}
kmsProviderCredentials.put("aws", new HashMap<>());
kmsProviders = {
aws: { }
};
kms_provider_credentials = {
"aws": { }
}
2

Cree una variable que contenga las credenciales de la llave maestra de cliente con la siguiente estructura. Utiliza el ARN y la Región que anotaste en el paso Crear una llave maestra de cliente de este tutorial.

customerMasterKeyCredentials = {
key: process.env["AWS_KEY_ARN"], // Your AWS Key ARN
region: process.env["AWS_KEY_REGION"], // Your AWS Key Region
};
var customerMasterKeyCredentials = new BsonDocument
{
{ "key", _appSettings["Aws:KeyArn"] }, // Your AWS Key ARN
{ "region", _appSettings["Aws:KeyRegion"] } // Your AWS Key Region
};
customerMasterKeyCredentials := map[string]string{
"key": os.Getenv("AWS_KEY_ARN"), // Your AWS Key ARN
"region": os.Getenv("AWS_KEY_REGION"), // Your AWS Key Region
}
BsonDocument customerMasterKeyCredentials = new BsonDocument();
customerMasterKeyCredentials.put("provider", new BsonString(kmsProviderName));
customerMasterKeyCredentials.put("key", new BsonString(getEnv("AWS_KEY_ARN"))); // Your AWS Key ARN
customerMasterKeyCredentials.put("region", new BsonString(getEnv("AWS_KEY_REGION"))); // Your AWS Key Region
customerMasterKeyCredentials = {
key: process.env.AWS_KEY_ARN, // Your AWS Key ARN
region: process.env.AWS_KEY_REGION, // Your AWS Key Region
};
customer_master_key_credentials = {
"key": os.environ['AWS_KEY_ARN'], # Your AWS Key ARN
"region": os.environ['AWS_KEY_REGION'] # Your AWS Key Region
}
3

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

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

  • El 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 AWS KMS

  • El 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 AWS KMS

  • El 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 AWS KMS

  • El 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 AWS KMS

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

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

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

Nota

Opciones de cifrado automático

Las opciones de cifrado automático proporcionan información de configuración a la Librería Compartida de Cifrado Automático, que modifica el comportamiento de la aplicación al acceder a campos cifrados.

Para obtener más información sobre la Biblioteca compartida de cifrado automático, consulta la página Biblioteca compartida de cifrado automático para Queryable Encryption.

4

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

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 la muestra de código anterior, ambos campos "ssn" y "billing" están cifrados, pero solo se puede query el campo "ssn".

6

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

Crea tu colección cifrada utilizando el método de asistente para cifrar al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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

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

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
[BsonIgnoreExtraElements]
public class Patient
{
public ObjectId Id { get; set; }
public string 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, crea tu colección cifrada utilizando el método asistente de cifrado al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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

Tip

Base de datos vs. Nombre de la base de datos

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

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

type PatientDocument struct {
PatientName string `bson:"patientName"`
PatientID int32 `bson:"patientId"`
PatientRecord PatientRecord `bson:"patientRecord"`
}
type PatientRecord struct {
SSN string `bson:"ssn"`
Billing PaymentInfo `bson:"billing"`
}
type PaymentInfo struct {
Type string `bson:"type"`
Number string `bson:"number"`
}

Después de agregar estas clases, crea tu colección cifrada utilizando el método asistente de cifrado al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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

Tip

Base de datos vs. Nombre de la base de datos

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

Crea tu colección cifrada utilizando el método de asistente para cifrar al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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

Tip

Base de datos vs. Nombre de la base de datos

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

Nota

Import ClientEncryption

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

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

Crea tu colección cifrada utilizando el método de asistente para cifrar al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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

Tip

Base de datos vs. Nombre de la base de datos

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

Crea tu colección cifrada utilizando el método de asistente para cifrar al que se accede a través de la clase ClientEncryption. Este método genera automáticamente claves de cifrado de datos para tus campos cifrados y crea la colección cifrada:

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 la base de datos

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

3

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

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

Crea 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 POJOs:

  • Patient

  • PatientRecord

  • PatientBilling

Puedes ver estas clases en el paquete de modelos de la aplicación Java completa.

Agrega estas clases POJO a tu aplicación. A continuación, crea una instancia de un Patient que describe la información personal de un paciente. Utiliza 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);

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

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

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 de la muestra de código anterior debe ser similar a la siguiente:

{
"_id": {
"$oid": "648b384a722cb9b8392df76a"
},
"name": "Jon Doe",
"record": {
"ssn": "987-65-4320",
"billing": {
"type": "Visa",
"number": "4111111111111111"
}
},
"__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.

Para aprender cómo funciona Queryable Encryption, consulta Fundamentos de Queryable Encryption.

Para obtener más información sobre los temas mencionados en esta guía, consulta los siguientes enlaces:

  • Aprende más sobre los componentes de Queryable Encryption en la página de Referencia.

  • Aprende cómo funcionan las llaves maestras de cliente y las llaves de cifrado de datos en la página de 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.

Volver

Tutorials

En esta página