Criptografia no nível de campo do cliente

Visão geral

Neste guia, você pode aprender a criptografar seus dados usando a criptografia em nível de campo do lado do cliente (CSFLE). O CSFLE permite criptografar dados em seu aplicação antes de enviá-los pela rede para o MongoDB. Isso significa que nenhum produto MongoDB tem acesso aos seus dados de forma não criptografada.

Você pode configurar o CSFLE usando um dos seguintes mecanismos:

• Criptografia automática: permite que você execute operações de leitura e gravação criptografadas sem especificar como criptografar campos

• Criptografia explícita: permite que você execute operações de leitura e gravação criptografadas com lógica de criptografia especificada em todo o aplicação.

Este guia descreve como configurar o CSFLE com criptografia automática.

Instalar dependências

Para usar o CSFLE com o Mongoid, você deve primeiro instalar as seguintes dependências:

• libmongocrypt

• Biblioteca compartilhada de criptografia automática se você estiver usando o driver Ruby v2.19 ou posterior. Ou mongocryptd se você estiver usando o driver Ruby v2.18 ou anterior.

• ffi

As seções a seguir fornecem detalhes sobre como instalar essas dependências.

gem install libmongocrypt-helper --pre

development:
  clients:
    default:
      options:
        auto_encryption_options:
          extra_options:
            crypt_shared_lib_path: '<Path to Shared Library>'

gem 'ffi'

Criar uma chave mestra do cliente

Para criptografar e descriptografar dados, você deve primeiro criar uma chave mestra do cliente (CMK). Um CMK é uma chave que você usa para criptografar sua chave de criptografia de dados (DEK). Sem acesso a um CMK, seu aplicação cliente não pode descriptografar DEKs associados aos seus dados criptografados.

Você pode criar uma chave armazenada localmente para usar como CMK local para fins de teste, executando o seguinte código Ruby:

require 'securerandom'
SecureRandom.hex(48)

Configure seu cliente

Você deve configurar seu cliente MongoDB para implementar o CSFLE. Para configurar um cliente para CSFLE, adicione o seguinte código ao seu arquivo mongoid.yml:

development:
  clients:
    default:
      uri: "<connection string>"
      options:
        auto_encryption_options: # This key enables automatic encryption
          key_vault_namespace: 'encryption.__keyVault' # Database and collection in which to store data keys
          kms_providers: # Tells the driver where to obtain master keys
            local: # Specifies that the key is local
              key: "<Path to your CMK>"
          extra_options:
            crypt_shared_lib_path: '<Path to Shared Library>' # Only required for Ruby versions 2.19 or later

Criar uma chave de criptografia de dados

Uma chave de criptografia de dados (DEK) é uma chave que você usa para criptografar os campos em seus documentos. O MongoDB armazena DEKs, criptografadas com sua CMK, na collection Key Vault como documentos BSON. O MongoDB nunca pode descriptografar os DEKs, pois o gerenciamento de chaves é controlado lado do cliente e cliente .

Para criar uma DEK no Mongoid, você pode usar a tarefa de varredura db:mongoid:encryption:create_data_key, como mostrado no exemplo a seguir:

rake db:mongoid:encryption:create_data_key

Você pode criar vários DEKs repetindo o comando anterior para o número de chaves que deseja gerar.

Você também pode fornecer um nome alternativo para sua DEK. Isso permite que você faça referência à DEK pelo nome ao configurar a criptografia para seus campos e atribua dinamicamente uma DEK a um campo em tempo de execução.

O exemplo a seguir cria um nome alternativo ao gerar uma nova DEK:

rake db:mongoid:encryption:create_data_key -- --key-alt-name=<custom DEK name>

Configurar esquema de criptografia

Você pode especificar quais campos criptografar adicionando a opção encrypt à definição de campo em seus modelos e especificando as opções deterministic e key_id, conforme mostrado no exemplo a seguir :

class Patient
  include Mongoid::Document
  include Mongoid::Timestamps
  encrypt_with key_id: '<data encryption key>'
  # This field is not encrypted
  field :category, type: String
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm
  field :passport_id, type: String, encrypt: {
    deterministic: false
  }
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
  # algorithm
  field :blood_type, type: String, encrypt: {
    deterministic: true
  }
  # This field is encrypted by using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm and a different data key
  field :ssn, type: Integer, encrypt: {
    deterministic: false, key_id: '<New key ID'
  }
  embeds_one :insurance
end
class Insurance
  include Mongoid::Document
  include Mongoid::Timestamps
  field :insurer, type: String
  # This field is encrypted using AEAD_AES_256_CBC_HMAC_SHA_512-Random
  # algorithm using a key with an alternate name stored in the policy_number_key field
  field :policy_number, type: Integer, encrypt: {
    deterministic: false,
    key_name_field: :policy_number_key
  }
  embedded_in :patient
end

Limitações

As seguintes limitações se aplicam ao usar o CSFLE com Mongoid:

• O Mongoid não suporta criptografia de associações embeds_many.

• Se você utilizar a opção :key_name_field , você deverá criptografar o campo utilizando um algoritmo não determinístico. Para criptografar seu campo deterministicamente, você deve especificar a opção :key_id.

• As limitações listadas na página Limitações de CSFLE no manual do MongoDB Server também se aplicam ao Mongoid.

Trabalhando com dados

Normalmente, o CSFLE automático funciona de forma transparente em seu aplicação. Depois que seu aplicação for configurado para CSFLE, você poderá criar documentos como de costume e o Mongoid criptografa e descriptografa automaticamente de acordo com sua configuração.

O exemplo a seguir cria um novo documento Patient em um aplicação configurado para CSFLE. Em seguida, ele usa um cliente chamado unencrypted_client que está conectado ao banco de dados , mas não configurado para que o CSFLE leia o documento.

Patient.create!(
  category: 'ER',
  passport_id: '123456',
  blood_type: 'AB+',
  ssn: 98765,
  insurance: Insurance.new(insurer: 'TK', policy_number: 123456, policy_number_key: 'my_data_key')
)
# Fields are encrypted in the database
unencrypted_client['patients'].find.first

{"_id"=>BSON::ObjectId('6446a1d046ebfd701f9f4292'),
"category"=>"ER",
"passport_id"=><BSON::Binary:0x404080 type=ciphertext data=0x012889b2cb0b1341...>,
"blood_type"=><BSON::Binary:0x404560 type=ciphertext data=0x022889b2cb0b1341...>,
"ssn"=><BSON::Binary:0x405040 type=ciphertext data=0x012889b2cb0b1341...>,
"insurance"=>{"_id"=>BSON::ObjectId('6446a1d046ebfd701f9f4293'),
"insurer"=>"TK", "policy_number"=><BSON::Binary:0x405920 type=ciphertext
data=0x012889b2cb0b1341...>}, "policy_number_key"=>"my_data_key"}

No exemplo anterior, o cliente unencrypted_client não consegue ler os campos criptografados. No entanto, se você consultar o documento com um cliente configurado para CSFLE, o Mongoid descriptografará automaticamente os campos.

Girar chaves de criptografia

Você pode girar suas chaves de encriptação usando o método de driver Ruby rewrap_many_data_key. Esse método descriptografa automaticamente várias chaves de encriptação de dados e as criptografa novamente usando uma CMK especificada. Em seguida, ele atualiza as chaves giradas na key vault collection.

O método rewrap_many_data_key utiliza os seguintes parâmetros:

• Filtro, usado para especificar quais campos devem ser rotacionados. Se nenhuma chave de dados corresponder ao filtro fornecido, nenhuma chave será girada. Omita o filtro para rotacionar todas as chaves na sua Key Vault Collection.

• Objeto que representa um novo CMK com o qual criptografar novamente os DEKs. Omitir este objeto para girar as chaves de dados usando seus CMKs atuais.

O exemplo a seguir alterna as chaves de encriptação usando o Amazon Web Services KMS:

# Create a key vault client
key_vault_client = Mongo::Client.new('<connection string>')
# Create the encryption object
encryption = Mongo::ClientEncryption.new(
  key_vault_client,
  key_vault_namespace: 'encryption.__keyVault',
  kms_providers: {
    aws: {
      "accessKeyId": "<IAM User Access Key ID>",
      "secretAccessKey": "<IAM User Secret Access Key>"
    }
  }
)
encryption.rewrap_many_data_key(
  {}, # Empty filter to rewrap all keys
  {
    provider: 'aws',
    master_key: {
      region: 'us-east-2',
      key: 'arn:aws:kms:us-east-2:...'
    }
  }
)

Adicionar criptografia automática a um projeto existente

O CSFLE automático com Mongoid suporta criptografia em vigor. Você pode habilitar a criptografia em um banco de dados existente e ainda ler dados não criptografados. No entanto, depois de ativar a criptografia, todos os novos dados são criptografados, e qualquer operação de query usa somente os documentos criptografados. Isso significa que as queries podem não retornar todos os documentos se alguns foram salvos antes de ativar a criptografia.

O exemplo a seguir consulta uma collection que tem um documento criptografado e um documento não criptografado:

# Print all documents in the collection. The first document is unencrypted, and
# the second is encrypted.
Patient.all.to_a
# =>
# [#<Patient _id: 644937ac46ebfd02468e58c8, category: "ER", passport_id: "DE-1257", blood_type: "AB+", ssn: 123456>,
# #<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]
# Querying for documents with a CSFLE-enabled client returns only the encrypted document
Patient.where(blood_type: 'AB+').to_a
# => [#<Patient _id: 644937c946ebfd029309b912, category: "ER", passport_id: "AT-1545", blood_type: "AB+", ssn: 987654>]

Você pode criptografar dados existentes em uma collection lendo e write back de todos os dados com um cliente habilitado para CSFLE. Ao fazer isso, certifique-se de que todos os dados existentes sejam do tipo esperado e que os valores vazios não estejam definidos como nil.

Informações adicionais

Para saber mais sobre o CSFLE, consulte o guia Criptografia de nível de campo do lado do cliente no manual do MongoDB Server .

Para saber mais sobre como configurar o Mongoid em seu aplicação, consulte o guiade configuração do aplicativo.