MongoDB Academy · Aula

Criptografia em nível de campo no lado do cliente

Aula 4 de 413 etapas

Criptografia em nível de campo no lado do cliente é uma aula grátis de MongoDB Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de MongoDB Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de MongoDB Academy inclui 4 aulas no total.

Por que usar criptografia no nível de campo?

Mesmo com TLS e criptografia em repouso, o servidor MongoDB vê os dados em texto simples assim que eles são descriptografados do disco. Uma conta de DBA comprometida, um engenheiro de nuvem mal-intencionado com acesso ao disco ou o vazamento de um backup do banco de dados poderia expor campos confidenciais. A criptografia de campos no lado do cliente (CSFLE) resolve esse problema criptografando campos confidenciais individuais — como números de seguridade social, números de cartão de crédito ou dados de saúde — dentro do controlador do cliente, antes que os dados cheguem ao servidor. O servidor armazena apenas o texto cifrado.

Como o CSFLE funciona em alto nível

O CSFLE usa duas camadas de chaves. A Customer Master Key (CMK) é armazenada em um sistema externo de gerenciamento de chaves (AWS KMS, Azure Key Vault, GCP KMS ou uma chave local). A CMK criptografa uma Data Encryption Key (DEK), que é armazenada em uma collection do MongoDB chamada Key Vault. O controlador busca e descriptografa a DEK usando a CMK no momento da consulta e, em seguida, usa a DEK para criptografar ou descriptografar os valores de campos individuais. O servidor nunca vê a CMK ou a DEK em texto simples.

Dois modos: automático e explícito

O CSFLE oferece dois modos de criptografia. O CSFLE automático (que exige MongoDB Enterprise ou Atlas) criptografa e descriptografa campos de forma transparente com base em um esquema JSON — o código da sua aplicação não muda. O CSFLE explícito (manual) está disponível no controlador Community e exige que a aplicação chame explicitamente os métodos de criptografia e descriptografia. O modo automático é muito mais conveniente para projetos novos; o explícito oferece controle máximo sobre quais campos são criptografados em cada operação.

Configurando a collection do Key Vault

Antes de criptografar qualquer dado, crie uma collection do Key Vault — uma collection especial do MongoDB que armazena Data Encryption Keys. O cofre de chaves é apenas uma collection comum (por exemplo, encryption.__keyVault), mas deve ter um índice exclusivo no campo keyAltNames. As DEKs são armazenadas como documentos BSON, com o material da chave criptografado pela sua CMK — até mesmo o cofre de chaves armazena apenas texto cifrado.

const { MongoClient, ClientEncryption } = require('mongodb-client-encryption')

// Step 1: Create key vault collection with unique index
const client = new MongoClient('mongodb://localhost:27017')
await client.connect()

const keyVaultColl = client.db('encryption').collection('__keyVault')
await keyVaultColl.createIndex(
  { keyAltNames: 1 },
  { unique: true, partialFilterExpression: { keyAltNames: { $exists: true } } }
)

Criando uma Data Encryption Key

Use o auxiliar ClientEncryption para criar uma DEK. A chave é criptografada pela sua CMK (neste caso, uma chave mestra local para desenvolvimento) e armazenada no cofre de chaves. Em produção, substitua o provedor local por aws, azure ou gcp e forneça as credenciais do KMS. Você pode criar várias DEKs — por exemplo, uma por locatário em uma aplicação com vários locatários.

const crypto = require('crypto')

// 96-byte local master key (development only — use KMS in production)
const localMasterKey = crypto.randomBytes(96)

const encryption = new ClientEncryption(client, {
  keyVaultNamespace: 'encryption.__keyVault',
  kmsProviders: { local: { key: localMasterKey } }
})

// Create a DEK with an alias for easy reference
const dataKey = await encryption.createDataKey('local', {
  keyAltNames: ['userSensitiveDataKey']
})
console.log('DEK id:', dataKey)

Definindo o esquema de campos criptografados

Para o CSFLE automático, defina um mapa de campos criptografados que informe ao controlador quais campos criptografar e com qual algoritmo. AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic produz o mesmo texto cifrado para o mesmo texto simples, permitindo consultas de igualdade em campos criptografados. AEAD_AES_256_CBC_HMAC_SHA_512-Random produz um texto cifrado diferente a cada vez — é mais forte, mas não permite consultas.

const encryptedFieldsMap = {
  'myApp.users': {
    fields: [
      {
        path: 'ssn',
        bsonType: 'string',
        // Deterministic: can query encrypted SSN with equality
        algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic',
        keyId: dataKey
      },
      {
        path: 'creditCardNumber',
        bsonType: 'string',
        // Random: cannot query, but stronger encryption
        algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Random',
        keyId: dataKey
      }
    ]
  }
}

Criando um MongoClient com CSFLE automático

Para habilitar o CSFLE automático, configure o MongoClient com a opção autoEncryption, fornecendo o namespace do cofre de chaves, as credenciais do KMS e o mapa de campos criptografados. O controlador criptografará automaticamente os campos correspondentes na inserção ou atualização e os descriptografará na leitura. Não são necessárias alterações nas consultas da sua aplicação.

const secureClient = new MongoClient('mongodb://localhost:27017', {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders: { local: { key: localMasterKey } },
    encryptedFieldsMap: encryptedFieldsMap
  }
})

await secureClient.connect()
const users = secureClient.db('myApp').collection('users')

// SSN and creditCardNumber are auto-encrypted on insert
await users.insertOne({
  name: 'Alice',
  ssn: '123-45-6789',           // encrypted transparently
  creditCardNumber: '4111-1111-1111-1111'  // encrypted transparently
})

Consultando campos criptografados

Com a criptografia determinística, você pode executar consultas de igualdade em campos criptografados — o controlador criptografa o valor da consulta com a mesma DEK antes de enviá-lo ao servidor, para que o servidor compare os textos cifrados. Com a criptografia aleatória, não é possível fazer consultas de igualdade, pois o mesmo texto simples produz textos cifrados diferentes a cada vez. Consultas por intervalo e expressões regulares não são compatíveis com campos criptografados no CSFLE.

// Query an encrypted SSN field (deterministic encryption)
// The driver auto-encrypts '123-45-6789' before sending the query
const user = await users.findOne({ ssn: '123-45-6789' })

// The result has SSN decrypted automatically by the driver:
console.log(user.ssn)  // '123-45-6789' (decrypted)

// A client WITHOUT the key sees ciphertext:
// user.ssn = Binary(Buffer.from('...'), 6)  // encrypted blob

Criptografia explícita com a API do controlador

O CSFLE explícito oferece controle por operação. Chame encryption.encrypt() antes de inserir e encryption.decrypt() depois de ler. Isso funciona nos controladores da edição Community sem exigir a biblioteca compartilhada do CSFLE automático. É mais verboso, mas oferece flexibilidade completa — você pode criptografar campos diferentes em documentos diferentes usando DEKs diferentes.

// Explicit encryption
const encryptedSsn = await encryption.encrypt('123-45-6789', {
  algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic',
  keyAltName: 'userSensitiveDataKey'
})

await users.insertOne({
  name: 'Bob',
  ssn: encryptedSsn  // manually encrypted Binary value
})

// Explicit decryption
const doc = await users.findOne({ name: 'Bob' })
const decryptedSsn = await encryption.decrypt(doc.ssn)
console.log(decryptedSsn)  // '123-45-6789'

Alternância de chaves para criptografia no nível de campo

Alterne as DEKs periodicamente para limitar a janela de exposição caso uma chave seja comprometida. A alternância de chaves no CSFLE envolve criar uma nova DEK, criptografar novamente todos os documentos que usam a DEK antiga (campo por campo) e depois excluir a DEK antiga do cofre de chaves. Esse processo pode ser realizado por um script de migração em segundo plano, sem indisponibilidade. Alternar CMKs no KMS (reencapsulando a DEK) não exige alterar os documentos criptografados.

Limitações e considerações do CSFLE

O CSFLE tem limitações importantes que devem ser consideradas: não há operações no servidor sobre campos criptografados (agregação, classificação e consultas por intervalo em campos criptografados não são compatíveis, exceto consultas de igualdade em campos determinísticos); alterações no esquema exigem reutilizar a DEK ou criptografar novamente os dados; o CSFLE automático exige MongoDB Enterprise ou Atlas; e a sobrecarga de desempenho causada pela criptografia e descriptografia no controlador aumenta a latência. Projete seu modelo de dados para minimizar a quantidade de campos que precisam de criptografia.

Verificação rápida

Teste sua compreensão dos conceitos de MongoDB e bancos de dados NoSQL desta lição.

Responda na aula interativa

Recapitulação da lição

Nesta lição, você aprendeu que o CSFLE criptografa campos confidenciais dentro do controlador antes que os dados cheguem ao servidor, portanto até mesmo o MongoDB vê apenas o texto cifrado; a criptografia determinística permite consultas de igualdade, enquanto a criptografia aleatória oferece mais segurança sem permitir consultas; e o modelo de chaves em dois níveis (a CMK no KMS encapsulando a DEK no cofre de chaves) mantém as chaves de criptografia fora do MongoDB. A seguir, exploraremos padrões de projeto de esquemas do MongoDB.

Grátis para começar

Aprenda JavaScript com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 30
Aulas: 120

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Criptografia em nível de campo no lado do cliente” é grátis?

Sim — o texto completo de “Criptografia em nível de campo no lado do cliente” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de MongoDB Academy, atualize para CoddyKit PRO. O curso de MongoDB Academy inclui 4 aulas no total.

O que vou aprender em “Criptografia em nível de campo no lado do cliente”?

Os alunos configurarão a criptografia em nível de campo no lado do cliente do MongoDB para criptografar campos confidenciais individuais antes que deixem a aplicação, mantendo o texto não criptografa… Você pratica MongoDB Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar MongoDB Academy?

Nenhuma experiência prévia é necessária. MongoDB Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Criptografia em nível de campo no lado do cliente”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de MongoDB Academy?

Sim. Cada aula de MongoDB Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Mecanismos de autenticação: SCRAM e x.509
Controle de acesso baseado em funções: funções integradas e personalizadas
Criptografia em repouso e TLS em trânsito
Criptografia em nível de campo no lado do cliente

← Voltar para MongoDB Academy