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.

  • :key_expiration_ms (Inteiro) —

    A duração do cache da chave de criptografia de dados, em milissegundos. Deve ser um número inteiro não negativo. Um valor explícito de 0 significa que o cache nunca expira. O padrão é 60000.

Aumenta:

  • (ArgumentError) —

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



52
53
54
55
56
57
58
59
60
61
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 52

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]),
    opções[:timeout_ms],
    opções[:key_expiration_ms]
  )
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.



207
208
209
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 207

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.



89
90
91
92
93
94
95
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 89

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) 


294
295
296
297
298
299
300
301
302
303
304
305
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 294

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.



196
197
198
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 196

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.



217
218
219
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 217

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

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

Observação:

O resultado da criptografia explícita com o índice "Indexado", "Range" ou "String" o algoritmo deve ser processado pelo servidor para inserir ou consultar. Para inserir ou executar uma query com essa carga útil, use um Mongo::Client configurado com :auto_encryption_options. A opção :bypass_query_analysis pode ser verdadeira; a opção :bypass_auto_encryption deve ser falsa.

Observação:

A opção "substring" o tipo de query é instável e sujeito a alterações de quebra para trás.

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.

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

  • :contention_factor (Inteiro | nulo) —

    Fator de contenção a ser aplicado se o algoritmo de criptografia estiver definido como "Indexed", "Range" ou "String". Se não for fornecido, o padrão será um valor de 0. O fator de contenção deverá ser definido somente se o algoritmo de criptografia estiver definido como "Indexed", "Range" ou "String".

  • query_type (string | nil) —

    Tipo de query a ser aplicado se o algoritmo de criptografia estiver definido como "Indexed", "Range" ou "String". Os valores permitidos são "igualdade" (para "Indexado"), "variação" (para "Intervalo"), e "prefixo", "sufixo", "substring" (para "String").

  • :range_opts (Hash | nulo) —

    Especifica as opções de índice para um campo de Queryable Encryption que oferece suporte a "range" consultas. Obrigatório quando o algoritmo é "Intervalo". As opções permitidas são :min, :max, :trim_factor, :sparsity, :precision.

  • :string_opts (Hash | nulo) —

    Especifica as opções de índice para um campo de Queryable Encryption que oferece suporte a "prefixo", "sufixo" ou "substring" consultas. Obrigatório quando o algoritmo é "String". As opções permitidas são :case_sensitive, :diacritic_sensitive, :prefix, :suffix, :substring.

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



146
147
148
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 146

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.



186
187
188
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 186

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.



227
228
229
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 227

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.



237
238
239
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 237

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:



244
245
246
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 244

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.



256
257
258
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 256

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:



271
272
273
 
# Arquivo 'lib/mongo/client_encryption.rb', linha 271

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