Encriptación en uso

Overview

En esta guía, aprenderá a cifrar sus datos mediante el cifrado a nivel de campo del lado del cliente (CSFLE). CSFLE le permite cifrar los datos en su aplicación antes de enviarlos a MongoDB por la red. Esto significa que ningún producto de MongoDB tiene acceso a sus datos sin cifrar.

Puede configurar CSFLE utilizando uno de los siguientes mecanismos:

• Cifrado automático: te permite realizar operaciones de lectura y escritura cifradas sin especificar cómo cifrar los campos

• Cifrado explícito: Permite realizar operaciones de lectura y escritura cifradas con lógica de cifrado especificada en toda la aplicación.

Esta guía describe cómo configurar CSFLE con cifrado automático.

Instale las dependencias

Para usar CSFLE con Mongoid, debes primero instalar las siguientes dependencias:

• libmongocrypt

• Biblioteca compartida de cifrado automático si está utilizando el driver Ruby v2.19 o posterior. O mongocryptd si están utilizando el driver Ruby v2.18 o anterior.

• ffi

Las siguientes secciones proporcionan detalles sobre cómo instalar estas dependencias.

gem install libmongocrypt-helper --pre

development:
  clients:
    default:
      options:
        auto_encryption_options:
          extra_options:
            crypt_shared_lib_path: '<Path to Shared Library>'

gem 'ffi'

Crear una clave maestra de cliente

Para cifrar y descifrar datos, primero debes crear una llave maestra de cliente (CMK). Una llave maestra de cliente es una clave que se utiliza para cifrar tu llave de cifrado de datos (DEK). Sin acceso a una llave maestra de cliente, su aplicación cliente no puede descifrar las DEK asociadas con sus datos cifrados.

Puedes crear una clave almacenada localmente para usarla como una llave maestra de cliente local con fines de prueba ejecutando el siguiente código Ruby:

require 'securerandom'
SecureRandom.hex(48)

Configura tu Cliente

Debe configurar su cliente MongoDB para implementar CSFLE. Para configurar un cliente para CSFLE, agregue el siguiente código a su archivo mongoid.yml:

development:
  clients:
    default:
      uri: "<connection string>"
      options:
        auto_encryption_options: # This key enables automatic encryption
          key_vault_namespace: 'encryption.__keyVault' # Database and collection in which to store data keys
          kms_providers: # Tells the driver where to obtain master keys
            local: # Specifies that the key is local
              key: "<Path to your CMK>"
          extra_options:
            crypt_shared_lib_path: '<Path to Shared Library>' # Only required for Ruby versions 2.19 or later

Crear una llave de cifrado de datos

Una clave de cifrado de datos (DEK) es una clave que se utiliza para cifrar los campos de los documentos. MongoDB almacena las DEK, cifradas con la CMK, en la colección Key Vault como documentos BSON. MongoDB nunca puede descifrar las DEK, ya que la gestión de claves se realiza en el lado del cliente.

Para crear un DEK en Mongoid, puede utilizar la tarea rake db:mongoid:encryption:create_data_key, como se muestra en el siguiente ejemplo:

rake db:mongoid:encryption:create_data_key

Puedes crear múltiples DEK repitiendo el comando anterior tantas veces como llaves desees generar.

También puedes proporcionar un nombre alternativo para tu DEK. Esto te permite hacer referencia a la DEK por su nombre cuando configures el cifrado para tus campos y asignar dinámicamente una DEK a un campo en tiempo de ejecución.

El siguiente ejemplo crea un nombre alternativo al generar un nuevo DEK:

rake db:mongoid:encryption:create_data_key -- --key-alt-name=<custom DEK name>

Configura el esquema de cifrado

Puedes especificar qué campos encriptar añadiendo la opción encrypt a la definición del campo en tus modelos y especificando las opciones deterministic y key_id, como se muestra en el siguiente ejemplo:

class Patient
  include Mongoid::Document
  include Mongoid::Timestamps
  encrypt_with key_id: '<data encryption key>'
  # This field is not encrypted
  field :category, type: String
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm
  field :passport_id, type: String, encrypt: {
    deterministic: false
  }
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
  # algorithm
  field :blood_type, type: String, encrypt: {
    deterministic: true
  }
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm and a different data key
  field :ssn, type: Integer, encrypt: {
    deterministic: false, key_id: '<New key ID'
  }
  embeds_one :insurance
end
class Insurance
  include Mongoid::Document
  include Mongoid::Timestamps
  field :insurer, type: String
  # This field is encrypted using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm using a key with an alternate name stored in the policy_number_key field
  field :policy_number, type: Integer, encrypt: {
    deterministic: false,
    key_name_field: :policy_number_key
  }
  embedded_in :patient
end

Limitaciones

Se aplican las siguientes limitaciones al usar CSFLE con Mongoid:

• Mongoid no admite el cifrado de las asociaciones embeds_many.

• Si utiliza la opción :key_name_field, debe cifrar el campo utilizando un algoritmo no determinístico. Para cifrar su campo de forma determinista, debe especificar la opción :key_id en su lugar.

• Las limitaciones enumeradas en la página Limitaciones de CSFLE en el manual del servidor MongoDB también se aplican a Mongoid.

Trabajar con datos

Normalmente, CSFLE automático funciona de forma transparente en su aplicación. Una vez configurada su aplicación para CSFLE, puede crear documentos como de costumbre y Mongoid los cifra y descifra automáticamente según su configuración.

El siguiente ejemplo crea un nuevo documento Patient en una aplicación configurada para CSFLE. Luego utiliza un cliente llamado unencrypted_client que está conectado a la base de datos, pero no configurado para CSFLE, para leer el documento.

Patient.create!(
  category: 'ER',
  passport_id: '123456',
  blood_type: 'AB+',
  ssn: 98765,
  insurance: Insurance.new(insurer: 'TK', policy_number: 123456, policy_number_key: 'my_data_key')
)
# Fields are encrypted in the database
unencrypted_client['patients'].find.first

{"_id"=>BSON::ObjectId('6446a1d046ebfd701f9f4292'),
"category"=>"ER",
"passport_id"=><BSON::Binary:0x404080 type=ciphertext data=0x012889b2cb0b1341...>,
"blood_type"=><BSON::Binary:0x404560 type=ciphertext data=0x022889b2cb0b1341...>,
"ssn"=><BSON::Binary:0x405040 type=ciphertext data=0x012889b2cb0b1341...>,
"insurance"=>{"_id"=>BSON::ObjectId('6446a1d046ebfd701f9f4293'),
"insurer"=>"TK", "policy_number"=><BSON::Binary:0x405920 type=ciphertext
data=0x012889b2cb0b1341...>}, "policy_number_key"=>"my_data_key"}

En el ejemplo anterior, el cliente unencrypted_client no puede leer los campos cifrados. Sin embargo, si query el documento con un cliente que está configurado para CSFLE, Mongoid descifra automáticamente los campos.

Rotar las llaves de cifrado

Puedes rotar tus llaves de cifrado utilizando el método del driver Ruby rewrap_many_data_key. Este método descifra automáticamente varias claves de cifrado de datos y las vuelve a cifrar usando una llave maestra de cliente especificada. Luego, actualiza las claves rotadas en la Colección de Bóvedas de Llaves.

El método rewrap_many_data_key acepta los siguientes parámetros:

• Filtro: se utiliza para especificar los campos que se rotarán. Si ninguna clave de datos coincide con el filtro especificado, no se rotará ninguna clave. Omita el filtro para rotar todas las claves de su colección de almacén de claves.

• Objeto que representa una nueva CMK para volver a cifrar las DEK. Omítalo para rotar las claves de datos utilizando sus CMK actuales.

El siguiente ejemplo rota claves de cifrado mediante AWS KMS:

# Create a key vault client
key_vault_client = Mongo::Client.new('<connection string>')
# Create the encryption object
encryption = Mongo::ClientEncryption.new(
  key_vault_client,
  key_vault_namespace: 'encryption.__keyVault',
  kms_providers: {
    aws: {
      "accessKeyId": "<IAM User Access Key ID>",
      "secretAccessKey": "<IAM User Secret Access Key>"
    }
  }
)
encryption.rewrap_many_data_key(
  {}, # Empty filter to rewrap all keys
  {
    provider: 'aws',
    master_key: {
      region: 'us-east-2',
      key: 'arn:aws:kms:us-east-2:...'
    }
  }
)

Agregue cifrado automático al proyecto existente

CSFLE automático con Mongoid admite el cifrado. Puede habilitar el cifrado en una base de datos existente y seguir leyendo datos sin cifrar. Sin embargo, una vez habilitado el cifrado, todos los datos nuevos se cifran y cualquier consulta utiliza únicamente los documentos cifrados. Esto significa que las consultas podrían no devolver todos los documentos si algunos se guardaron antes de habilitar el cifrado.

El siguiente ejemplo query una colección que tiene un documento cifrado y un documento no cifrado:

# Print all documents in the collection. The first document is unencrypted, and
# the second is encrypted.
Patient.all.to_a
# =>
# [#<Patient _id: 644937ac46ebfd02468e58c8, category: "ER", passport_id: "DE-1257", blood_type: "AB+", ssn: 123456>,
# #<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]
# Querying for documents with a CSFLE-enabled client returns only the encrypted document
Patient.where(blood_type: 'AB+').to_a
# => [#<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]

Puede cifrar los datos existentes en una colección leyendo y reescribiéndolos con un cliente compatible con CSFLE. Al hacerlo, asegúrese de que todos los datos existentes sean del tipo esperado y de que los valores vacíos no estén configurados como nil.

Información Adicional

Para obtener más información sobre CSFLE, consulta la guía de Encriptación a nivel de campo del lado del cliente en el manual del MongoDB Server.

Para obtener más información sobre cómo configurar Mongoid en tu aplicación, consulta el Guía para conectar a MongoDB.