Encriptación en uso

Overview

En esta guía, puedes aprender a cifrar tus datos utilizando cifrado a nivel de campo del lado del cliente (CSFLE). CSFLE te permite cifrar los datos de tu aplicación antes de enviarlos a través de la red a MongoDB. Esto significa que ningún producto de MongoDB tiene acceso a tus datos en forma no cifrada.

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

Debes configurar tu cliente de MongoDB para implementar CSFLE. Para configurar un cliente para CSFLE, añade el siguiente código a tu 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 tus documentos. MongoDB almacena los DEK, cifrados con tu llave maestra de cliente, en la Colección de Bóvedas de Llaves como documentos BSON. MongoDB nunca podrá descifrar los DEK, ya que la gestión de claves se realiza del lado del cliente y está controlada por el 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

Por lo general, el CSFLE automático funciona de manera transparente en su aplicación. Después de configurar tu aplicación para CSFLE, puedes crear documentos como de costumbre y Mongoid los encriptará y desencriptará automáticamente según tu 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, utilizado para especificar qué campos rotar. Si ninguna clave de datos coincide con el filtro dado, no se rotarán las claves. Omite el filtro para rotar todas las claves de tu Colección de Bóvedas de Llaves.

• Objeto que representa una nueva llave maestra de cliente con la que volver a encriptar las DEKs. Omite este objeto para rotar las claves de datos utilizando sus CMK actuales.

El siguiente ejemplo rota las claves de cifrado utilizando 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

La CSFLE automática con Mongoid admite el cifrado en el lugar. Puedes habilitar el cifrado en una base de datos existente y aún así leer datos no cifrados. Sin embargo, una vez que habilite el cifrado, todos los datos nuevos se cifran y cualquier operación de query usa únicamente los documentos cifrados. Esto significa que es posible que las consultas no devuelvan todos los documentos si algunos se guardaron antes de activar 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>]

Puedes encriptar los datos existentes en una colección leyendo y luego escribiendo todos los datos con un cliente habilitado para CSFLE. Al hacerlo, asegúrese de que todos los datos existentes sean del tipo esperado y 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.