Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Criptografia explícita CSFLE

A criptografia explícita fornece controle refinado sobre a segurança, ao custo de maior complexidade ao configurar collections e escrever código para os drivers do MongoDB. Com a criptografia explícita, você especifica como criptografar campos em seu documento para cada operação executada no banco de dados e inclui essa lógica em todo o aplicativo.

A criptografia explícita está disponível nos seguintes produtos MongoDB:

  • Servidor MongoDB Community

  • MongoDB Enterprise Advanced

  • MongoDB Atlas

Para usar criptografia explícita, você deve executar as seguintes ações em seu aplicativo habilitado para CSFLE:

Para usar a criptografia explícita, crie uma instância do ClientEncryption. ClientEncryption é uma abstração usada entre drivers e mongosh que encapsula a coleção de cofre de chaves e as operações do KMS envolvidas na criptografia explícita.

Para criar uma instância do ClientEncryption, você deve especificar as seguintes informações:

  • Uma instância do MongoClient com acesso à sua coleção do Key Vault

  • O namespace da sua coleção do Key Vault

  • Um objeto kmsProviders configurado com acesso ao provedor de KMS que hospeda sua chave mestra do cliente

Para mais opções do ClientEncryption , consulte Opções MongoClient para CSFLE.

Para visualizar trechos de código que mostram como criar uma instância do ClientEncryption, consulte a seção Exemplo deste guia.

Você deve atualizar as operações de leitura e gravação em todo o aplicativo para que ele criptografe os campos antes de executar operações de leitura e gravação.

Para criptografar campos, use o método encrypt de sua instância ClientEncryption.

Para ver trechos de código que mostram como usar o método encrypt, consulte a seção Exemplo deste guia.

Você pode descriptografar seus campos criptografados manualmente ou automaticamente ao usar criptografia explícita.

Para descriptografar seus campos manualmente, use o método decrypt da sua instância do ClientEncryption.

Para ver trechos de código que mostram como usar o método decrypt, consulte a seção Exemplo deste guia.

Para descriptografar seus campos automaticamente, configure sua instância do MongoClient como segue:

  • Especifique sua coleção do Key Vault

  • Especifique um objeto kmsProviders

  • Se você utilizar o servidor da comunidade MongoDB, configure a opção bypassAutoEncryption para True

Observação

A descriptografia automática está disponível no servidor da comunidade MongoDB

Embora a criptografia automática exija o MongoDB Enterprise ou o MongoDB Atlas, a descriptografia automática está disponível nos seguintes produtos do MongoDB:

  • Servidor MongoDB Community

  • MongoDB Enterprise Advanced

  • MongoDB Atlas

Para visualizar um trecho de código que demonstra como ativar a descriptografia automática, selecione a guia correspondente ao seu idioma preferido:

Linguagem

Suponha que você deseja inserir documentos com a seguinte estrutura em sua instância MongoDB:

{ "name": "<name of person>", "age": <age of person>, "favorite-foods": ["<array of foods>"]}
1

Neste exemplo, você usa a mesma instância do MongoClient para acessar sua coleção do Key Vault e ler e gravar dados criptografados.

Os trechos de código a seguir mostram como criar uma instância MongoClient:

const autoEncryptionOpts = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders,};const encryptedClient = Mongo(connectionString, autoEncryptionOpts);
2

Os trechos de código a seguir mostram como criar uma instância ClientEncryption:

const clientEncryption = encryptedClient.getClientEncryption();
3

Você deseja criptografar os campos do documento usando os seguintes algoritmos:

Nome do campo
Algoritmo de criptografia
Tipo de campo BSON

name

Determinístico(a)

String

age

Sem criptografia

Int

favorite-foods

Aleatório

Array

Os seguintes trechos de código mostram como criptografar manualmente os campos em seu documento e inserir seu documento no MongoDB:

Observação

A variável dataKeyId nos exemplos abaixo refere-se a uma chave de criptografia de dados (DEK). Para saber como gerar uma DEK com seu fornecedor de chave local, consulte o Início rápido. Para saber como criar uma DEK com um sistema de gerenciamento de chaves específico, consulte Tutoriais do CSFLE.

const encName = clientEncryption.encrypt( dataKeyId, "Greg", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic");const encFoods = clientEncryption.encrypt( dataKeyId, ["Cheese", "Grapes"], "AEAD_AES_256_CBC_HMAC_SHA_512-Random");db.getSiblingDB(database).getCollection(collection).insertOne({ name: encName, foods: encFoods,});
4

Os seguintes trechos de código mostram como recuperar seu documento inserido e descriptografar manualmente os campos criptografados:

const encNameQuery = clientEncryption.encrypt( dataKeyId, "Greg", "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic");let doc = db.getSiblingDB(database).getCollection(collection).findOne({ name: encNameQuery,});console.log(doc);doc.name = clientEncryption.decrypt(doc.name);doc.foods = clientEncryption.decrypt(doc.foods);console.log(doc);

O MongoDB suporta o uso da validação de esquema para impor a criptografia de campos específicos em uma coleção.

Um cliente que executa a criptografia de nível de campo do lado do cliente com o mecanismo de criptografia explícito em uma instância do MongoDB configurada para impor a criptografia de determinados campos deve criptografar esses campos conforme especificado na instância do MongoDB.

Para saber como configurar a imposição de CSFLE no lado do servidor, consulte Aplicação do esquema CSFLE no lado do servidor.

Para saber mais sobre coleções de Key Vault, chaves de criptografia de dados e chaves mestras de clientes, consulte Chaves de criptografia e Key Vaults.

Para aprender mais sobre KMS provedores e kmsProviders objetos, consulte KMS Provedores.

Para visualizar e baixar exemplos de código executáveis completos para os tópicos abordados acima, selecione uma linguagem de programação: