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.

  • :key_expiration_ms (Integer) —

    Duración de la caché de claves de cifrado de datos, en milisegundos. Debe ser un número entero no negativo. Un valor explícito de 0 significa que la caché nunca caduca. El valor predeterminado es 60000.

Aumenta:

  • (ArgumentError) —

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



52
53
54
55
56
57
58
59
60
61
 
# Archivo 'lib/mongo/client_encryption.rb', línea 52

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]),
    opciones[:timeout_ms],
    opciones[:key_expiration_ms]
  )
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.



207
208
209
 
# Archivo 'lib/mongo/client_encryption.rb', línea 207

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.



89
90
91
92
93
94
95
 
# Archivo 'lib/mongo/client_encryption.rb', línea 89

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) 


294
295
296
297
298
299
300
301
302
303
304
305
 
# Archivo 'lib/mongo/client_encryption.rb', línea 294

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.



196
197
198
 
# Archivo 'lib/mongo/client_encryption.rb', línea 196

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.



217
218
219
 
# Archivo 'lib/mongo/client_encryption.rb', línea 217

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

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

Nota:

El resultado del cifrado explícito con los algoritmos «Indexed», «Range» o «String» debe ser procesado por el servidor para insertar o consultar datos. Para insertar o consultar con este tipo de datos, utilice un Mongo::Client configurado con la opción :auto_encryption_options. La opción :bypass_query_analysis puede ser verdadera; la opción :bypass_auto_encryption debe ser falsa.

Nota:

El tipo de consulta "subcadena" es inestable y está sujeto a cambios incompatibles con versiones anteriores.

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.

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", "Range" y "String".

  • :contention_factor (Integer | nil) —

    Factor de contención que se aplicará si el algoritmo de cifrado se establece en "Indexado", "Rango" o "Cadena". Si no se especifica, se utiliza el valor predeterminado 0. El factor de contención solo debe establecerse si el algoritmo de cifrado se establece en "Indexado", "Rango" o "Cadena".

  • query_type (String | nil) —

    Tipo de consulta que se aplicará si el algoritmo de cifrado está configurado como "Indexado", "Rango" o "Cadena". Los valores permitidos son "igualdad" (para "Indexado"), "rango" (para "Rango") y "prefijo", "sufijo" o "subcadena" (para "Cadena").

  • Opciones de rango (Hash | nil) —

    Especifica las opciones de índice para un campo de cifrado consultable que admite consultas de tipo "range". Es obligatorio cuando el algoritmo es "Range". Las opciones permitidas son: min, max, trim_factor, sparsity y precision.

  • :string_opts (Hash | nil) —

    Especifica las opciones de índice para un campo de cifrado consultable que admite consultas de "prefijo", "sufijo" o "subcadena". Es obligatorio cuando el algoritmo es "String". Las opciones permitidas son: :case_sensitive, :diacritic_sensitive, :prefix, :suffix y :substring.

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 algorithm no es "Indexed", "Range" o "String".



146
147
148
 
# Archivo 'lib/mongo/client_encryption.rb', línea 146

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.

  • :tipo_de_consulta (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.



186
187
188
 
# Archivo 'lib/mongo/client_encryption.rb', línea 186

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.



227
228
229
 
# Archivo 'lib/mongo/client_encryption.rb', línea 227

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.



237
238
239
 
# Archivo 'lib/mongo/client_encryption.rb', línea 237

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:



244
245
246
 
# Archivo 'lib/mongo/client_encryption.rb', línea 244

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.



256
257
258
 
# Archivo 'lib/mongo/client_encryption.rb', línea 256

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:



271
272
273
 
# Archivo 'lib/mongo/client_encryption.rb', línea 271

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