Class: Mongo::ClientEncryption

Herda:
Objeto
  • Objeto
mostrar tudo
Definido em:
lib/mongo/client_encryption.rb

Visão geral

O ClientEncryption encapsula operações explícitas em uma coleção de cofre de chaves que não podem ser feitas diretamente em um MongoClient. Ele fornece uma API para criptografar e descriptografar explicitamente valores e criar chaves de dados.

Recolhimento do Resumo do método de instância

Detalhes do construtor

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

Crie um novo objeto ClientEncryption com as opções fornecidas.

Parâmetros:

  • key_vault_client (Mongo::Client) —

    Um Mongo::Client que está conectado à instância MongoDB onde a coleção de cofre de chave está armazenada.

  • opções (Hash) (padrão para: {}) —

    As opções do ClientEncryption.

Hash de opções (opções):

  • :key_vault_namespace (string) —

    O nome da coleção de cofre de chave no formato "banco de dados.coleção".

  • :kms_providers (Hash) —

    Um hash de informações de configuração do KMS. @consulte Mongo::Crypt::KMS::Credentials para obter a lista de opções de cada provedor suportado. @note Pode haver mais de um provedor de KMS especificado.

  • :kms_tls_options (Hash) —

    Opções de TLS para se conectar a provedores de KMS. As chaves do hash devem ser nomes de provedor KSM; Os valores devem ser hashes de opções de conexão TLS . As opções são equivalentes às opções de conexão TLS do Mongo::Client. @veja Mongo::Client#initialize para obter uma lista de opções de TLS.

  • :timeout_ms (Inteiro) —

    O tempo limite da operação em milissegundos. Deve ser um número inteiro não negativo. Um valor explícito de 0 significa infinito. O valor padrão não está definido, o que significa que a funcionalidade está desabilitada.

Aumenta:

  • (ArgumentError) —

    Se as opções necessárias estiverem ausentes ou formatadas incorretamente.



48
49
50
51
52
53
54
55
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 48

def inicializar(key_vault_client, opções = {})
  @encrypter = Criptografar::ExplicitEncrypter.Novo(
    key_vault_client,
    opções[:key_vault_namespace],
    Criptografar::KMS::Credenciais.Novo(opções[:kms_providers]),
    Criptografar::KMS::Validações.validate_tls_options(opções[:kms_tls_options])
  )
end

Detalhes do método de instância

#add_key_alt_name(ID, key_alt_name) ➤ BSON::Document | nada

Adiciona um key_alt_name para a chave na key vault collection com o ID fornecido.

Parâmetros:

  • id (BSON::Binary) —

    ID da chave para adicionar o novo nome alternativo da chave.

  • key_alt_name (string) —

    Novo nome alternativo da chave para adicionar.

Retorna:

  • (BSON::Document | nil) —

    Documento que descreve a chave identificada antes de adicionar o nome alternativo da chave ou nulo se não houver essa chave.



182
183
184
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 182

def add_key_alt_name(id, key_alt_name)
  @encrypter.add_key_alt_name(id, key_alt_name)
end

#create_data_key(kms_provider, options = {}) ➤ BSON::Binary

Gera uma chave de dados usada para criptografia/descriptografia e armazena essa chave na coleção KMS. A chave gerada é criptografada com a chave mestre KMS.

Parâmetros:

  • kms_provider (string) —

    O provedor KMS a ser usado. Os valores válidos são "aws" e "local".

  • opções (Hash) (padrão para: {})

Hash de opções (opções):

  • :master_key (Hash) —

    Informações sobre a chave mestra AWS . Obrigatório se kms_provider for "aws".

    • :region [ string ] A região do Amazon Web Services da chave mestre (obrigatório).
    • :key [ string ] O Nome do Recurso Amazon (ARN) da chave mestre (obrigatório).
    • :ponto de extremidade [ String ] Um hospedeiro alternativo para enviar solicitações KMS (opcional). O ponto de extremidade deve ser um nome de hospedar com um número de porta opcional separado por dois pontos (por exemplo "kms.us-east-1.amazonaws.com" ou "kms.us-east-1.amazonaws.com:443"). Um ponto de extremidade em qualquer outro formato não será analisado corretamente.
  • :key_alt_names (Array<String>) —

    Uma array opcional de strings especificando nomes alternativos para a nova chave de dados.

  • :key_material (string | nil) —

    96 bytes opcionais para utilizar como material de chave personalizado para a chave de dados que está sendo criada. Se a opção :key_material for fornecida, o material da chave personalizada será usado para criptografar e descriptografar dados.

Retorna:

  • (BSON::Binary) —

    O 16bytes UUID da nova chave de dados como um objeto BSON::Binary com tipo :uuid.



83
84
85
86
87
88
89
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 83

def create_data_key(kms_provider, opções = {})
  key_document = Criptografar::KMS::Documento MasterKey.Novo(kms_provider, opções)

  key_alt_names = opções[:key_alt_names]
  key_material = opções[:key_material]
  @encrypter.create_and_insert_data_key(key_document, key_alt_names, key_material)
end

#create_encrypted_collection(banco de dados, coll_name, coll_opts, kms_provider, master_key) ➤ Array

Observação:

Este método não atualiza o :encrypted_fields_map no :auto_encryption_options do cliente. Portanto, para usar a coleção criada por esse método com criptografia automática, o usuário deve criar um novo cliente depois de chamar essa função com os :encrypted_fields retornados.

Crie uma coleção com campos criptografados.

Se :encryption_fields contiver um keyId com um valor nulo, uma chave de dados será gerada automaticamente e atribuída ao valor keyId.

Parâmetros:

  • database (Mongo::Database) —

    Banco de dados para criar coleção.

  • coll_name (string) —

    Nome da collection a ser criada.

  • coll_opts (Hash) —

    Opções de collection a ser criada.

  • kms_provider (string) —

    Provedor de KMS para criptografar campos.

  • master_key (Hash | nulo) —

    Documento que descreve a chave mestre para criptografar campos.

Retorna:

  • (Array<Operação::Result, Hash>) —

    O resultado da criação da operação de collection e o mapa de campos criptografados usado para criar a collection.

Aumenta:

  • (ArgumentError) 


269
270
271
272
273
274
275
276
277
278
279
280
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 269

def create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key)
  aumentar ArgumentError, 'coll_opts deve conter :encrypted_fields' a menos que coll_opts[:encrypted_fields]

  campos_criptografados = create_data_keys(coll_opts[:encrypted_fields], kms_provider, master_key)
  começar
    new_coll_opts = coll_opts.dup.mesclar(encryption_fields: campos_criptografados)
    [ database[coll_name].criar(new_coll_opts), campos_criptografados ]
  salvar mongo::Erro => e
    aumentar Erro::Criptografia de erro, "Erro ao criar a collection com campos criptografados \
          #{encryption_fields}: #{e.class}: #{e.message}"
  end
end

#descriptografar(valor) ➤ Objeto

Descriptografa um valor que já foi criptografado.

Parâmetros:

  • valor (BSON::Binary) —

    Um objeto binário BSON do subtipo 6 (texto cifrado) que será descriptografado.

Retorna:

  • (Objeto) —

    O valor descriptografado.



171
172
173
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 171

def Descriptografar(valor)
  @encrypter.Descriptografar(valor)
end

#delete_key(ID) ➤ Operação::Result

Remove a chave com o ID fornecido da coleção de cofre de chave.

Parâmetros:

  • id (BSON::Binary) —

    ID da chave a ser excluída.

Retorna:

  • (Operação::Resultado) —

    A resposta do banco de dados para a operação delete_one que exclui a chave.



192
193
194
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 192

def delete_key(id)
  @encrypter.delete_key(id)
end

#encrypt(value, options = {}) ➤ BSON::Binary

Observação:

As opções :key_id e :key_alt_name são mutuamente exclusivas. Apenas um é necessário para executar a criptografia explícita.

Criptografa um valor usando a chave de encriptação e o algoritmo especificados.

se o algoritmo de criptografia estiver definido como "Indexado". O tipo de query deve ser definido somente se o algoritmo de criptografia estiver definido como "Indexado". O único valor permitido é "igualdade".

Parâmetros:

  • valor (Objeto) —

    O valor a ser criptografado.

  • opções (Hash) (padrão para: {})

Hash de opções (opções):

  • :key_id (BSON::Binary) —

    Um objeto BSON::Binary do tipo :uuid representando o UUID da chave de criptografia conforme armazenado na coleção de cofre de chaves.

  • :key_alt_name (string) —

    O nome alternativo da chave de criptografia.

  • :algorithm (string) —

    O algoritmo usado para criptografar o valor. Algoritmos válidos são "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexado", "não indexado".

  • :contention_factor (Inteiro | nulo) —

    Fator de contenção a ser aplicado se o algoritmo de criptografia estiver definido como "Índice". Se não for fornecido, o padrão será um valor de 0. O fator de contenção deve ser definido somente se o algoritmo de criptografia estiver definido como "Indexado".

  • query_type (string | nil) —

    Tipo de query a ser aplicada

Retorna:

  • (BSON::Binary) —

    Um objeto Binary BSON do subtipo 6 (texto cifrado) representando o valor criptografado.

Aumenta:

  • (ArgumentError) —

    se container_factor ou query_type estiver definido e o algoritmo não for "indexado".



121
122
123
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 121

def criptografar(valor, opções = {})
  @encrypter.criptografar(valor, opções)
end

#encrypt_expression(expression, options = {}) ➤ BSON::Binary

Observação:

As opções :key_id e :key_alt_name são mutuamente exclusivas. Apenas um é necessário para executar a criptografia explícita.

Criptografa uma expressão de correspondência ou expressão de agregação para consultar um índice de faixa.

Somente suportado quando queryType for "faixa" e algoritmo for "faixa". @note: o algoritmo faixa é apenas experimental. Não se destina ao uso público. Ele está sujeito a alterações interruptivas.

@param [ Hash ] opções

Exemplos:

Criptografar expressão de correspondência.

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

Criptografar expressão agregada.

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

Parâmetros:

  • expressão (Hash) —

    Expressão a ser criptografada.

  • opções (Hash) (padrão para: {}) —

    um conjunto personalizável de opções

Hash de opções (opções):

  • :key_id (BSON::Binary) —

    Um objeto BSON::Binary do tipo :uuid representando o UUID da chave de criptografia conforme armazenado na coleção de cofre de chaves.

  • :key_alt_name (string) —

    O nome alternativo da chave de criptografia.

  • :algorithm (string) —

    O algoritmo utilizado para criptografar a expressão. O único valor permitido é "faixa"

  • :contention_factor (Inteiro | nulo) —

    Fator de contenção a ser aplicado Se não for fornecido, o padrão será um valor de 0.

  • query_type (string | nil) —

    Tipo de query a ser aplicada. O único valor permitido é "faixa".

Retorna:

  • (BSON::Binary) —

    Um objeto Binary BSON do subtipo 6 (texto cifrado) representando a expressão criptografada.

Aumenta:

  • (ArgumentError) —

    se valores não permitidos nas opções estiverem definidos.



161
162
163
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 161

def encryption_expression(expressão, opções = {})
  @encrypter.encryption_expression(expressão, opções)
end

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

Encontra uma única chave com o ID fornecido.

Parâmetros:

  • id (BSON::Binary) —

    ID da chave a ser obtida.

Retorna:

  • (BSON::Document | nil) —

    O documento chave encontrado ou nulo se não for encontrado.



202
203
204
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 202

def get_key(id)
  @encrypter.get_key(id)
end

#get_key_by_alt_name(key_alt_name) ➤ BSON::Document | nada

Retorna uma chave na key vault collection com o key_alt_name fornecido.

Parâmetros:

  • key_alt_name (string) —

    Nome alternativo da chave para encontrar uma chave.

Retorna:

  • (BSON::Document | nil) —

    O documento chave encontrado ou nulo se não for encontrado.



212
213
214
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 212

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

#get_keys ➤ Collection::View Também conhecido como: chaves

Retorna todas as chaves na key vault collection.

Retorna:



219
220
221
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 219

def get_keys
  @encrypter.get_keys
end

#remove_key_alt_name(ID, key_alt_name) ➤ BSON::Document | nada

Remove um key_alt_name de uma chave na key vault collection com o ID fornecido.

Parâmetros:

  • id (BSON::Binary) —

    ID da chave para remover o nome alternativo da chave.

  • key_alt_name (string) —

    Nome alternativo da chave a ser removido.

Retorna:

  • (BSON::Document | nil) —

    Documento que descreve a chave identificada antes de remover o nome alternativo da chave ou nulo se não houver essa chave.



231
232
233
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 231

def remove_key_alt_name(id, key_alt_name)
  @encrypter.remove_key_alt_name(id, key_alt_name)
end

#rewrap_many_data_key(filter, opts = {}) ➤ Crypt::RewrapManyDataKeyResult

Descriptografa várias chaves de dados e (re)criptografa-as com uma nova master_key ou com sua master_key atual se uma nova não for fornecida.

Parâmetros:

  • filtro, filtro (Hash) —

    Filtro usado para encontrar chaves a serem atualizadas.

  • opções (Hash)

Retorna:



246
247
248
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 246

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