Class: Mongo::ClientEncryption

Hereda:
Objeto
  • Objeto
Mostrar todo
Definido en:
lib/mongo/client_encryption.rb

Overview

ClientEncryption encapsula operaciones explícitas en una Colección de Bóvedas de Llaves que no pueden realizarse directamente en un MongoClient. Proporciona una API para encriptar y desencriptar valores explícitamente y para crear claves de datos.

Resumen del método de instancia colapsar

Detalles del Constructor

#initialize(key_vault_client, options = {}) ⇒ ClientEncryption

Crea un nuevo objeto ClientEncryption con las opciones proporcionadas.

Parámetros:

  • key_vault_client (Mongo::cliente) —

    Un Mongo::cliente que está conectado a la instancia de MongoDB donde se almacena la Colección de Bóvedas de Llaves.

  • opciones (encriptada) (por defecto: {}) —

    Las opciones de ClientEncryption.

Opciones Hash (options):

  • :key_vault_namespace (string) —

    El nombre de la colección del almacén de claves en el formato "database.collection".

  • :kms_providers (encriptada) —

    Un hash de información de configuración del Key Management Service. @see Mongo::Crypt::KMS::Credentials para obtener la lista de opciones para cada proveedor compatible. @note Puede que se especifique más de un proveedor de KMS.

  • kms_tls_options (encriptada) —

    Opciones de TLS para conectarse a los proveedores de KMS. Las claves del hash deben ser nombres de los proveedores de KSM; los valores deben ser hashes de opciones de conexión TLS. Las opciones son equivalentes a las opciones de conexión TLS de Mongo::Client. @see Mongo::Client#initialize para ver la lista de opciones TLS.

  • :timeout_ms (Integer) —

    El tiempo de espera de la operación en milisegundos. Debe ser un número entero no negativo. Un valor explícito de 0 significa infinito. El valor por defecto no está establecido, lo que significa que la funcionalidad está deshabilitada.

Aumenta:

  • (ArgumentError) —

    Si faltan las opciones requeridas o están formateadas incorrectamente.



48
49
50
51
52
53
54
55
 
# Archivo 'lib/mongo/client_encryption.rb', línea 48

def inicializar(key_vault_client, opciones = {})
  @encryptador = Cripta::EncriptadorExplicito.Nuevo(
    key_vault_client,
    opciones[:key_vault_namespace],
    Cripta::KMS::credenciales.Nuevo(opciones[:kms_providers]),
    Cripta::KMS::validación.validate_tls_options(opciones[kms_tls_options])
  )
end

Detalles del método de instancia

#add_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

Agrega un key_alt_name para la clave en la Colección de Bóvedas de Llaves con el ID proporcionado.

Parámetros:

  • ID (BSON::Binary) —

    Id. de la clave para agregar un nombre alternativo de clave nuevo.

  • key_alt_name (string) —

    Nuevo nombre alternativo de clave para agregar.

Devuelve:

  • (BSON::Document | nil) —

    Documento que describe la clave identificada antes de agregar el nombre alternativo de la clave, o nil si no existe tal clave.



182
183
184
 
# Archivo 'lib/mongo/client_encryption.rb', línea 182

def add_key_alt_name(ID, key_alt_name)
  @encryptador.add_key_alt_name(ID, key_alt_name)
end

#create_data_key(kms_provider, opciones = {}) ⇒ BSON::Binary

Genera una clave de datos utilizada para el cifrado/descifrado y almacena esa clave en la colección KMS. La clave generada está cifrado con la clave maestra KMS.

Parámetros:

  • kms_provider (string) —

    El proveedor de KMS a utilizar. Los valores válidos son "aws" y "local".

  • opciones (encriptada) (por defecto a: {})

Opciones Hash (options):

  • llave_maestra (encriptada) —

    Información sobre la clave maestra de AWS. Obligatorio si kms_provider es "aws".

    • :region [ String ] La región AWS de la clave maestra (obligatorio).
    • :key [ String ] El Amazon recurso Name (ARN) de la clave maestra (obligatorio).
    • :endpoint [ String ] Un host alternativo al que enviar solicitudes de KMS (opcional). el endpoint debe ser un nombre de host con un número de puerto opcional, separados por dos puntos (por ejemplo, "kms.us-east-1.amazonaws.com" o "kms.us-east-1.amazonaws.com:443"}. Un endpoint en cualquier otro formato no se analizará correctamente.
  • nombres alternativos (arreglo<String>) —

    Un arreglo opcional de cadenas que especifica nombres alternativos para la nueva clave de datos.

  • Elemento clave (String | nil) —

    Opcional 96 bytes para usar como material clave personalizado para la clave de datos que se está creando. Si se proporciona la opción :key_material, se utiliza el material clave personalizado para cifrar y descifrar datos.

Devuelve:

  • (BSON::Binary) —

    El UUID de 16bytes de la nueva clave de datos como un objeto BSON::Binary con tipo :uuid.



83
84
85
86
87
88
89
 
# Archivo 'lib/mongo/client_encryption.rb', línea 83

def create_data_key(kms_provider, opciones = {})
  Documento clave = Cripta::KMS::MasterKeyDocument.Nuevo(kms_provider, opciones)

  clave_nombres_alternativos = opciones[nombres alternativos]
  material de clave = opciones[Elemento clave]
  @encryptador.create_and_insert_data_key(Documento clave, clave_nombres_alternativos, material de clave)
end

#create_encrypted_collection(base de datos, coll_name, coll_opts, kms_provider, master_key) ⇒ arreglo<operación::Result, Hash>

Nota:

Este método no actualiza el :encrypted_fields_map en las :auto_encryption_options del cliente. Por lo tanto, para usar la colección creada por este método con cifrado automático, el usuario debe crear un nuevo cliente después de llamar a esta función con los :encrypted_fields devueltos.

Crea una colección con campos cifrados.

Si :encryption_fields contiene un keyId con un valor nulo, se generará automáticamente una clave de datos y se asignará al valor de keyId.

Parámetros:

  • database (Mongo::Database) —

    Base de datos para crear la colección en.

  • coll_name (string) —

    Nombre de la colección a crear.

  • coll_opts (encriptada) —

    Opciones para la colección a crear.

  • kms_provider (string) —

    Proveedor KMS para cifrar campos.

  • master_key (Hash | nil) —

    Documento que describe la clave maestra para cifrar campos.

Devuelve:

  • (arreglo<operación::Result, Hash>) —

    El resultado de la operación crear colección y el mapa de campos cifrados utilizado para crear la colección.

Aumenta:

  • (ArgumentError) 


269
270
271
272
273
274
275
276
277
278
279
280
 
# Archivo 'lib/mongo/client_encryption.rb', línea 269

def create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key)
  propagar ArgumentError, 'coll_opts debe contener :encrypted_fields' a menos que coll_opts[:encrypted_fields]

  encrypted_fields = create_data_keys(coll_opts[:encrypted_fields], kms_provider, master_key)
  begin
    new_coll_opts = coll_opts.dup.fusionar(campos_encriptados: encrypted_fields)
    [ database[coll_name].Cree(new_coll_opts), encrypted_fields ]
  rescate mongo::Error => e
    propagar Error::CryptError, "Error al crear la colección con campos cifrados \
          #{campos_cifrados}: #{e.class}: #{e.message}"
  end
end

#descifrar(valor) ⇒ Objeto

Descifra un valor que ya ha sido cifrado.

Parámetros:

  • Valor (BSON::Binary) —

    Un objeto BSON binario de subtipo 6 (texto cifrado) que será descifrado.

Devuelve:

  • (objeto) —

    El valor descifrado.



171
172
173
 
# Archivo 'lib/mongo/client_encryption.rb', línea 171

def descifrar(Valor)
  @encryptador.descifrar(Valor)
end

#delete_key(id) ⇒ Operación::Result

Remueve la clave con la ID indicada de la Colección de Bóvedas de Llaves.

Parámetros:

  • ID (BSON::Binary) —

    ID de la clave a borrar.

Devuelve:

  • (Operation::Result) —

    La respuesta de la base de datos para la operación delete_one que elimina la clave.



192
193
194
 
# Archivo 'lib/mongo/client_encryption.rb', línea 192

def delete_key(ID)
  @encryptador.delete_key(ID)
end

#encrypt(valor, opciones = {}) ⇒ BSON::Binary

Nota:

Las opciones :key_id y :key_alt_name son mutuamente excluyentes. Solo se requiere uno para realizar el cifrado explícito.

Encripta un valor usando la clave y algoritmo de cifrado especificados.

Si el algoritmo de cifrado está configurado en "Indexado". El tipo de query solo debe configurarse si el algoritmo de cifrado está configurado en "Indexado". El único valor permitido es "igualdad".

Parámetros:

  • Valor (objeto) —

    El valor a cifrar.

  • opciones (encriptada) (por defecto a: {})

Opciones Hash (options):

  • :key_id (BSON::Binary) —

    Un objeto BSON::Binary de tipo :uuid que representa el UUID de la llave de cifrado tal y como está almacenado en la Colección de Bóvedas de Llaves.

  • :key_alt_name (string) —

    El nombre alternativo para la clave de cifrado.

  • algoritmo (string) —

    El algoritmo utilizado para cifrar el valor. Los algoritmos válidos son "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed".

  • :contention_factor (Integer | nil) —

    Factor de contención que se aplicará si el algoritmo de cifrado está configurado en "Índice". Si no se proporciona, el valor por defecto será 0. El factor de contención debe establecerse solo si el algoritmo de cifrado está configurado como «Indexado».

  • query_type (String | nil) —

    Tipo de query que se aplicará

Devuelve:

  • (BSON::Binary) —

    Un objeto BSON Binary de subtipo 6 (texto cifrado) que representa el valor cifrado.

Aumenta:

  • (ArgumentError) —

    si se establece contention_factor o query_type, y el algoritmo no es "Indexed".



121
122
123
 
# Archivo 'lib/mongo/client_encryption.rb', línea 121

def cifrado(Valor, opciones = {})
  @encryptador.cifrado(Valor, opciones)
end

#encrypt_expression(expresión, opciones = {}) ⇒ BSON::Binary

Nota:

Las opciones :key_id y :key_alt_name son mutuamente excluyentes. Solo se requiere uno para realizar el cifrado explícito.

Encripta una expresión de coincidencia o una expresión de agregación para consultar un índice de rango.

Solo se admite cuando queryType es "range" y el algoritmo es "Range". @note: El algoritmo de Rango es solo experimental. No está destinado al uso público. Está sujeto a cambios disruptivos.

@param [ Hash ] opciones

Ejemplos:

Encripta expresión de coincidencia.

encryption.encrypt_expression(
  {'$and' =>  [{'field' => {'$gt' => 10}}, {'field' =>  {'$lt' => 20 }}]}
)

Encriptar expresión agregada.

encryption.encrypt_expression(
  {'$and' =>  [{'$gt' => ['$field', 10]}, {'$lt' => ['$field', 20]}}
)
{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]

Parámetros:

  • expresión (encriptada) —

    Expresión para cifrar.

  • opciones (encriptada) (por defecto: {}) —

    un conjunto personalizable de opciones

Opciones Hash (options):

  • :key_id (BSON::Binary) —

    Un objeto BSON::Binary de tipo :uuid que representa el UUID de la llave de cifrado tal y como está almacenado en la Colección de Bóvedas de Llaves.

  • :key_alt_name (string) —

    El nombre alternativo para la clave de cifrado.

  • algoritmo (string) —

    El algoritmo utilizado para cifrar la expresión. El único valor permitido es "Rango"

  • :contention_factor (Integer | nil) —

    Factor de contención a aplicar Si no se proporciona, el valor por defecto es 0.

  • query_type (String | nil) —

    Tipo de consulta que se aplicará. El único valor permitido es "rango".

Devuelve:

  • (BSON::Binary) —

    Un objeto BSON Binary de subtipo 6 (texto cifrado) que representa la expresión cifrada.

Aumenta:

  • (ArgumentError) —

    si se establecen valores no permitidos en las opciones.



161
162
163
 
# Archivo 'lib/mongo/client_encryption.rb', línea 161

def encrypt_expression(expresión, opciones = {})
  @encryptador.encrypt_expression(expresión, opciones)
end

#get_key(id) ⇒ BSON::Document | nil

Encuentra una sola clave con el ID proporcionado.

Parámetros:

  • ID (BSON::Binary) —

    Id de la clave a obtener.

Devuelve:

  • (BSON::Document | nil) —

    El documento clave encontrado o nulo si no se encuentra.



202
203
204
 
# Archivo 'lib/mongo/client_encryption.rb', línea 202

def obtener_clave(ID)
  @encryptador.obtener_clave(ID)
end

#get_key_by_alt_name(key_alt_name) ⇒ BSON::Document | nil

Devuelve una clave en la Colección de Bóvedas de Llaves con el key_alt_name (nombre alternativo de clave) proporcionado.

Parámetros:

  • key_alt_name (string) —

    Nombre alternativo clave para encontrar una clave.

Devuelve:

  • (BSON::Document | nil) —

    El documento clave encontrado o nulo si no se encuentra.



212
213
214
 
# Archivo 'lib/mongo/client_encryption.rb', línea 212

def get_key_by_alt_name(key_alt_name)
  @encryptador.get_key_by_alt_name(key_alt_name)
end

#get_keys ⇒ colección::View También conocido como: keys

Devuelve todas las Colección de Bóvedas de Llaves.

Devuelve:



219
220
221
 
# Archivo 'lib/mongo/client_encryption.rb', línea 219

def get_keys
  @encryptador.get_keys
end

#remove_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

Remueve un key_alt_name de una clave en la Colección de Bóvedas de Llaves con el ID especificado.

Parámetros:

  • ID (BSON::Binary) —

    ID de la clave para remover el nombre alternativo de la clave.

  • key_alt_name (string) —

    Nombre alternativo clave a remover.

Devuelve:

  • (BSON::Document | nil) —

    Documento que describe la clave identificada antes de remover el nombre alternativo de la clave, o nulo si no existe tal clave.



231
232
233
 
# Archivo 'lib/mongo/client_encryption.rb', línea 231

def eliminar_nombre_alternativo_de_clave(ID, key_alt_name)
  @encryptador.eliminar_nombre_alternativo_de_clave(ID, key_alt_name)
end

#rewrap_many_data_key(filtro, opts = {}) ⇒ Crypt::RewrapManyDataKeyResult

Descifra varias claves de datos y las (re)encripta con una nueva master_key, o con su master_key actual si no se proporciona una nueva.

Parámetros:

  • filtro (encriptada) —

    Filtro usado para encontrar claves que serán actualizadas.

  • opciones (encriptada)

Devuelve:



246
247
248
 
# Archivo 'lib/mongo/client_encryption.rb', línea 246

def rewrap_many_data_key(filtro, opciones = {})
  @encryptador.rewrap_many_data_key(filtro, opciones)
end