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 (Hash) (por defecto: {}) —

    Las opciones de ClientEncryption.

Opciones Hash (options):

  • :key_vault_namespace (Cadena) —

    El nombre de la Colección de Bóvedas de Llaves en el formato “base de datos.colección”.

  • :proveedores_de_kms (Hash) —

    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_opciones (Hash) —

    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 (Entero) —

    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.



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

def inicializar(key_vault_client, opciones = {})
  @encryptador = Cripta::EncriptadorExplicito.Nuevo(
    key_vault_client,
    opciones[:key_vault_namespace],
    Cripta::KMS::credenciales.Nuevo(opciones[:proveedores_de_kms]),
    Cripta::KMS::validación.validate_tls_options(opciones[:kms_tls_opciones])
  )
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 nulo si no existe dicha clave.



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

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 (Hash) (por defecto a: {})

Opciones Hash (options):

  • :llave maestra (Hash) —

    Información sobre la clave maestra de AWS. Es necesario si kms_provider es “aws”.

    • :region [ Cadena ] La región de AWS de la clave maestra (obligatoria).

    • :key [ String ] El Amazon recurso Name (ARN) de la clave maestra (obligatorio).

    • :endpoint [ String ] Un host alternativo al que enviar solicitudes de KMS (opcional). endpoint debe ser un nombre de host con un número de puerto opcional separado 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.

  • :tecla_alt_nombres (Matriz<String>) —

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

  • :material_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.



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

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

  clave_nombres_alternativos = opciones[:tecla_alt_nombres]
  material de clave = opciones[:material_clave]
  @encryptador.create_and_insert_data_key(Documento clave, clave_nombres_alternativos, material de clave)
end

#crear_colección_encriptada(base_de_datos, nombre_coll, opciones_coll, proveedor_kms, clave_maestra) ⇒ Matriz< Operación::Resultado,Hash>

Nota:

Este método no actualiza el :encrypted_fields_map en las :auto_encryption_options del cliente. Por lo tanto, para utilizar 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 keyId.

Parámetros:

  • database (Mongo::Database) —

    Base de datos para crear colección.

  • nombre_coll (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) 


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

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

  encrypted_fields = crear_claves_de_datos(coll_opts[:encrypted_fields], kms_provider, master_key)
  begin
    new_coll_opts = coll_opts.dup.fusionar(campos_encriptados: encrypted_fields)
    [database[nombre_coll].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.



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

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.



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

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.

Cifra un valor utilizando la clave de cifrado y el algoritmo especificados.

Si el algoritmo de cifrado está configurado como "Indexado", se debe configurar el tipo de consulta.

only if encryption algorithm is set to "Indexed". The only allowed
value is "equality".

Parámetros:

  • Valor (objeto) —

    El valor a cifrar.

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

Opciones Hash (options):

  • :identificación_de_clave (BSON::Binario) —

    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 (Cadena) —

    El nombre alternativo para la clave de cifrado.

  • algoritmo (Cadena) —

    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 como "Indexado". Si no se proporciona, se establece por defecto a un valor de 0. El factor de contención sólo debe establecerse si el algoritmo de cifrado está configurado en “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 está “Indexado”.



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

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 está soportado cuando queryType es “rango” y el algoritmo es “rango”. @note: El algoritmo Rango es solo experimental. No está destinado

for public use. It is subject to breaking changes.

# @param [ Hash ] opciones

Ejemplos:

Encripta expresión de coincidencia.

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

Cifrar 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 (Hash) (por defecto: {}) —

    un conjunto personalizable de opciones

Opciones Hash (options):

  • :identificación_de_clave (BSON::Binario) —

    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 (Cadena) —

    El nombre alternativo para la clave de cifrado.

  • algoritmo (Cadena) —

    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 query a aplicar. El único valor permitido es “rango”.

Devuelve:

  • (BSON::Binary) —

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

Aumenta:

  • (ArgumentError) —

    Si se establecen valores no permitidos en las opciones.



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

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.



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

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.



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

def obtener_clave_por_nombre_alt(key_alt_name)
  @encryptador.obtener_clave_por_nombre_alt(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:



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

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.



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

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

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

Descifra múltiples claves de datos y las (re)cifra con una nueva master_key,

or with their current master_key if a new one is not given.

Parámetros:

  • filtro (encriptada) —

    Filtro usado para encontrar claves que serán actualizadas.

  • opciones (Hash)

Devuelve:



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

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