Encriptación a nivel de campo

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: permite realizar operaciones de lectura y escritura cifradas sin especificar cómo cifrar los campos

• Cifrado explícito: le permite realizar operaciones de lectura y escritura cifradas con una lógica de cifrado específica en toda su aplicación.

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

Instalar dependencias

Para utilizar CSFLE con Mongoid, primero debe instalar las siguientes dependencias:

• libmongocrypt

• Biblioteca compartida de cifrado automático si utiliza el controlador Ruby v2.19 o posterior. O mongocryptd si utiliza el controlador 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 debe crear una Clave Maestra de Cliente (CMK). Una CMK es una clave que se utiliza para cifrar su Clave de Cifrado de Datos (DEK). Sin acceso a una CMK, su aplicación cliente no puede descifrar las DEK asociadas a sus datos cifrados.

Puede crear una clave almacenada localmente para usarla como CMK 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

Puede crear varias DEK repitiendo el comando anterior para la cantidad de claves que desee generar.

También puede proporcionar un nombre alternativo para su DEK. Esto le permite referenciarla por su nombre al configurar el cifrado de sus campos y asignarla dinámicamente a un campo en tiempo de ejecución.

El siguiente ejemplo crea un nombre alternativo al generar una nueva DEK:

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

Configurar el esquema de cifrado

Puede especificar qué campos cifrar agregando la opción encrypt a la definición del campo en sus 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 utilizar CSFLE con Mongoid:

• Mongoid no admite el cifrado de asociaciones embeds_many.

• Si usa la opción :key_name_field, debe cifrar el campo con un algoritmo no determinista. Para cifrar el campo de forma determinista, debe especificar la opción :key_id.

• Las limitaciones enumeradas en la página Limitaciones de CSFLE del 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 unencrypted_client cliente no puede leer los campos cifrados. Sin embargo, si consulta el documento con un cliente configurado para CSFLE, Mongoid descifra automáticamente los campos.

Rotar claves de cifrado

Puede rotar sus claves de cifrado mediante el método del controlador Ruby rewrap_many_data_key. Este método descifra automáticamente varias claves de cifrado de datos y las vuelve a cifrar utilizando una CMK específica. A continuación, actualiza las claves rotadas en la colección del almacén de claves.

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:...'
    }
  }
)

Agregar cifrado automático a un 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 consulta una colección que tiene un documento cifrado y uno 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, consulte la guía de cifrado a nivel de campo del lado del cliente en el manual del servidor MongoDB.

Para obtener más información sobre cómo configurar Mongoid en su aplicación, consulte la Guíade configuración de la aplicación.