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 almacén de claves que no se pueden realizar directamente en un MongoClient. Proporciona una API para cifrar y descifrar valores explícitamente, así como para crear claves de datos.

Colapso del resumen del método de instancia

Detalles del constructor

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

Cree un nuevo objeto ClientEncryption con las opciones proporcionadas.

Parámetros:

  • cliente de bóveda de claves (Mongo::Cliente) —

    Un Mongo::Client que está conectado a la instancia de MongoDB donde se almacena la colección de bóveda de claves.

  • opciones (Hash) (predeterminado: {}) —

    Las opciones de ClientEncryption.

Opciones Hash(opciones):

  • :key_vault_namespace (Cadena) —

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

  • :proveedores_de_kms (Hash) —

    Un hash de información de configuración del servicio de administración de claves. @see Mongo::Crypt::KMS::Credentials para obtener una lista de opciones para cada proveedor compatible. @note Puede haber más de un proveedor de KMS especificado.

  • :kms_tls_opciones (Hash) —

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

  • :tiempo de espera_ms (Entero) —

    El tiempo de espera de la operación en milisegundos. Debe ser un entero positivo. Un valor explícito de 0 significa infinito. El valor predeterminado es "unset", lo que significa que la función está deshabilitada.

Aumentos:

  • (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(cliente de bóveda de claves, opciones = {})
  @encrypter = Cripta::Cifrador explícito.Nuevo(
    cliente de bóveda de claves,
    opciones[:key_vault_namespace],
    Cripta::KMS::Credenciales.Nuevo(opciones[:proveedores_de_kms]),
    Cripta::KMS::Validaciones.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 almacén de claves con la identificación dada.

Parámetros:

  • ID. (BSON::Binario) —

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

  • key_alt_name (Cadena) -

    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)
  @encrypter.add_key_alt_name(ID., key_alt_name)
end

#crear_clave_de_datos(proveedor_kms, opciones = {}) ⇒ BSON::Binario

Genera una clave de datos para el cifrado/descifrado y la almacena en la colección KMS. La clave generada se cifra con la clave maestra de KMS.

Parámetros:

  • proveedor de kms (Cadena) -

    El proveedor KMS que se utilizará. Los valores válidos son "aws" y "local".

  • opciones (Hash) (predeterminado: {})

Opciones Hash(opciones):

  • :llave maestra (Hash) —

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

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

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

    • :endpoint [ Cadena ] Un host alternativo al que se envían las solicitudes KMS (opcional). El endpoint debe ser un nombre de host con un número de puerto opcional separado por dos puntos (p. ej., “kms.us-east-1.amazonaws.com” o “kms.us-east-1.amazonaws.com:443”). Un endpoint con cualquier otro formato no se analizará correctamente.

  • :tecla_alt_nombres (Matriz<String>) —

    Una matriz opcional de cadenas que especifican nombres alternativos para la nueva clave de datos.

  • :material_clave (String | nil) —

    Bytes 96 opcionales para usar como material de clave personalizado para la clave de datos que se está creando. Si se especifica la opción :key_material, el material de clave personalizado se usa para cifrar y descifrar datos.

Devuelve:

  • (BSON::Binario) —

    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 crear_clave_de_datos(proveedor de kms, opciones={})
  documento_clave = Cripta::KMS::Documento de clave maestra.Nuevo(proveedor de kms, opciones)

  nombres de teclas alternativas = opciones[:tecla_alt_nombres]
  material de clave = opciones[:material_clave]
  @encrypter.crear_e_insertar_clave_de_datos(documento_clave, nombres de teclas alternativas, 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 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 el :encrypted_fields devuelto.

Crear 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::Basede datos) —

    Base de datos para crear colección.

  • nombre_coll (Cadena) -

    Nombre de la colección a crear.

  • opciones de colección (Hash) —

    Opciones para crear colección.

  • proveedor de kms (Cadena) -

    Proveedor KMS para cifrar campos.

  • llave maestra (Hash | nulo ) —

    Documento que describe la clave maestra para cifrar campos.

Devuelve:

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

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

Aumentos:

  • (ArgumentError) 


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

def crear_colección_encriptada(database, nombre_coll, opciones de colección, proveedor de kms, llave maestra)
  propagar ArgumentError, 'coll_opts debe contener: campos cifrados ' a no ser que opciones de colección[:campos_encriptados]

  campos cifrados = crear_claves_de_datos(opciones de colección[:campos_encriptados], proveedor de kms, llave maestra)
  begin
    nuevas opciones de recopilación = opciones de colección.dup.unir(campos cifrados: campos cifrados)
    [database[nombre_coll].Cree(nuevas opciones de recopilación), campos cifrados]
  rescate Mongo::Error => e
    propagar Error::CryptError, "Erroral crear una colección con campos cifrados \
          #{encrypted_fields }: #{e.class}: #{e.message}"
  end
end

#descifrar(valor) ⇒ Objeto

Descifra un valor que ya ha sido cifrado.

Parámetros:

  • valor (BSON::Binario) —

    Un objeto binario BSON del 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 desencriptar(valor)
  @encrypter.desencriptar(valor)
end

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

Elimina la clave con la identificación dada de la colección de bóveda de claves.

Parámetros:

  • ID. (BSON::Binario) —

    Id de la clave a eliminar.

Devuelve:

  • (Operación::Resultado) —

    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 tecla_de_eliminar(ID.)
  @encrypter.tecla_de_eliminar(ID.)
end

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

Nota:

Las opciones :key_id y :key_alt_name son mutuamente excluyentes. Solo se requiere una 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) (predeterminado: {})

Opciones Hash(opciones):

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

    Un objeto BSON::Binary de tipo :uuid que representa el UUID de la clave de cifrado tal como está almacenada en la colección de almacén de claves.

  • :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-Determinista», «AEAD_AES_256_CBC_HMAC_SHA_512-Aleatorio», «Indexado» y «Sin indexar».

  • :factor_de_contención (Integer | nil) —

    El factor de contención se aplicará si el algoritmo de cifrado está configurado como "Indexado". Si no se proporciona, el valor predeterminado es 0. El factor de contención solo debe configurarse si el algoritmo de cifrado está configurado como "Indexado".

  • tipo de consulta (String | nil) —

    Tipo de consulta a aplicar

Devuelve:

  • (BSON::Binario) —

    Un objeto binario BSON del subtipo 6 (texto cifrado) que representa el valor cifrado.

Aumentos:

  • (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 cifrar(valor, opciones={})
  @encrypter.cifrar(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 una 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 el tipo de consulta es "rango" y el algoritmo es "Rango". @nota: El algoritmo de rango es solo experimental. No está diseñado para...

for public use. It is subject to breaking changes.

# @param [ Hash ] opciones

Ejemplos:

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

    Expresión para cifrar.

  • opciones (Hash) (predeterminado: {}) —

    un conjunto personalizable de opciones

Opciones Hash(opciones):

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

    Un objeto BSON::Binary de tipo :uuid que representa el UUID de la clave de cifrado tal como está almacenada en la colección de almacén de claves.

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

  • :factor_de_contención (Integer | nil) —

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

  • tipo de consulta (String | nil) —

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

Devuelve:

  • (BSON::Binario) —

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

Aumentos:

  • (ArgumentError) —

    Si se establecen valores no permitidos en las opciones.



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

def expresión_cifrada(expresión, opciones = {})
  @encrypter.expresión_cifrada(expresión, opciones)
end

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

Encuentra una sola clave con la identificación dada.

Parámetros:

  • ID. (BSON::Binario) —

    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.)
  @encrypter.obtener_clave(ID.)
end

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

Devuelve una clave en la colección de almacén de claves con el key_alt_name indicado.

Parámetros:

  • key_alt_name (Cadena) -

    Nombre de la tecla alt para buscar una tecla.

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)
  @encrypter.obtener_clave_por_nombre_alt(key_alt_name)
end

#get_keys ⇒ Collection::View También conocido como: keys

Devuelve todas las claves de la colección de almacén de claves.

Devuelve:



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

def get_keys
  @encrypter.get_keys
end

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

Elimina un key_alt_name de una clave en la colección de almacén de claves con la identificación dada.

Parámetros:

  • ID. (BSON::Binario) —

    Id de la clave para eliminar el nombre alternativo de la clave.

  • key_alt_name (Cadena) -

    Tecla alt nombre para eliminar.

Devuelve:

  • (BSON::Document | nil) —

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



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

def eliminar_tecla_alt_nombre(ID., key_alt_name)
  @encrypter.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 vuelve a cifrar con una nueva clave maestra.

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

Parámetros:

  • filtro (Hash) —

    Filtro utilizado para encontrar claves a actualizar.

  • opciones (Hash)

Devuelve:



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

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