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.

Use o Queryable Encryption com o KMIP

Este guia mostra como criar uma aplicação que implementa o MongoDB Queryable Encryption para criptografar e descriptografar automaticamente os campos do documento e usar um provedor de chaves compatível com o Key Management Interoperability Protocol (KMIP) para gerenciamento de chaves.

Depois de concluir as etapas deste guia, você deverá ter:

  • Uma chave mestra do cliente gerenciada por um provedor de chaves compatível com KMIP

  • Uma aplicação cliente funcional que insere documentos com campos criptografados usando sua Chave Mestre do Cliente

Dica

chave mestra do cliente

Para aprender mais sobre a chave mestra do cliente, leia a documentação Chaves de Criptografia and Key Vaults.

Para concluir e executar o código neste guia, você precisa configurar seu ambiente de desenvolvimento, conforme mostrado na página Instalar um driver e dependências compatíveis com Queryable Encryption.

Dica

Veja: Aplicação Completa

Para ver o código completo para este aplicativo de amostra, selecione a guia correspondente à sua linguagem de programação e siga o link fornecido. Cada repositório de aplicativo de amostra inclui um arquivo de README.md que você pode usar para aprender a configurar seu ambiente e executar o aplicativo.

1

Para conectar um cliente de driver MongoDB ao seu fornecedor de chaves compatível com KMIP , você deve configurar seu provedor de chaves compatível com KMIPpara que ele aceite o certificado TLS do seu cliente.

Consulte a documentação do seu provedor de chaves compatível com KMIPpara obter informações sobre como aceitar seu certificado de cliente.

2

Seu cliente deve se conectar ao seu provedor de chaves compatível com KMIPpor meio de TLS e apresentar um certificado de cliente que seu provedor de chaves compatível com KMIPaceite:

const tlsOptions = { kmip: { tlsCAFile: process.env["KMIP_TLS_CA_FILE"], // Path to your TLS CA file tlsCertificateKeyFile: process.env["KMIP_TLS_CERT_FILE"], // Path to your TLS certificate key file },};
1

Os exemplos de código neste tutorial usam as seguintes variáveis para executar o fluxo de trabalho com Queryable Encryption:

  • kmsProviderName - O KMS que você está usando para armazenar sua Chave Mestre do Cliente. Defina esta variável como "kmip" para este tutorial.

  • uri - URI de conexão do sistema do MongoDB . Defina seu URI de conexão na variável de ambiente MONGODB_URI ou substitua o valor diretamente.

  • keyVaultDatabaseName - O banco de dados de dados no MongoDB onde suas chaves de criptografia de dados (DEKs) serão armazenadas. Defina esta variável como "encryption".

  • keyVaultCollectionName - A collection no MongoDB onde seus DEKs serão armazenados. Configure esta variável para "__keyVault".

  • keyVaultNamespace - O namespace no MongoDB onde seus DEKs serão armazenados. Defina esta variável para os valores das variáveis keyVaultDatabaseName e keyVaultCollectionName , separados por um período.

  • encryptedDatabaseName - O banco de dados no MongoDB em que seus dados criptografados serão armazenados. Defina esta variável como "medicalRecords".

  • encryptionCollectionName - A coleção no MongoDB onde seus dados criptografados serão armazenados. Defina esta variável como "patients".

Você pode declarar essas variáveis usando o seguinte código:

// KMS provider name should be one of the following: "aws", "gcp", "azure", "kmip" or "local"const kmsProviderName = "<Your KMS Provider Name>";const uri = process.env.MONGODB_URI; // Your connection URIconst keyVaultDatabaseName = "encryption";const keyVaultCollectionName = "__keyVault";const keyVaultNamespace = `${keyVaultDatabaseName}.${keyVaultCollectionName}`;const encryptedDatabaseName = "medicalRecords";const encryptedCollectionName = "patients";

Importante

Permissões de namespace da coleção de cofre de chaves

A collection de cofre de chaves está no namespace encryption.__keyVault . Certifique-se de que o trigger de banco de dados que sua aplicação usa para se conectar ao MongoDB tenha permissões de ReadWrite nesse namespace.

Dica

Variáveis de ambiente

O código de exemplo neste tutorial faz referência a variáveis de ambiente que você precisa definir. Como alternativa, você pode substituir os valores diretamente no código.

Para saber como configurar essas variáveis de ambiente, consulte o readme.md incluído na aplicação de amostra no Github.

2

Crie uma variável contendo o endpoint do seu provedor de chaves compatível com KMIP com a seguinte estrutura:

kmsProviderCredentials = { kmip: { endpoint: process.env["KMIP_KMS_ENDPOINT"], // Your KMIP KMS endpoint },};

Crie um objeto vazio, conforme mostrado no exemplo de código a seguir. Isso solicita que seu fornecedor de chaves compatível com KMIPgere uma nova chave mestre do cliente.

customerMasterKeyCredentials = {};

Crie um objeto autoEncryptionOptions que contenha as seguintes opções:

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

  • O objeto kmsProviderCredentials , que contém seu endpoint KMIP

  • O objeto tlsOptions que você criou na etapa Especificar seus certificados

const autoEncryptionOptions = { keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviderCredentials, tlsOptions,};

Observação

Opções de criptografia automática

As opções de criptografia automática fornecem informações de configuração para a Biblioteca compartilhada de criptografia automática, que modifica o comportamento do aplicativo ao acessar campos criptografados.

Para saber mais sobre a Biblioteca Compartilhada de Criptografia Automática, consulte a página Biblioteca Compartilhada de Criptografia Automática para Queryable Encryption.

Para criar um cliente utilizado para criptografar e descriptografar dados em sua coleção, instancie um novo MongoClient usando seu URI de conexão e suas opções de criptografia automática.

const encryptedClient = Mongo(uri, autoEncryptionOptions);

Para criptografar um campo, adicione-o ao esquema de criptografia. Para habilitar queries em um campo, adicione a propriedade "queries". Crie o esquema de criptografia da seguinte forma:

const encryptedFieldsMap = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};

Observação

No exemplo de código anterior, os campos "ssn" e "billing" são criptografados, mas somente o campo "ssn" pode ser consultado.

Instancie ClientEncryption para acessar a API e obter métodos assistentes de criptografia.

const clientEncryption = encryptedClient.getClientEncryption()

Crie sua coleção criptografada usando o método assistente de criptografia acessado por meio da classe ClientEncryption . Este método gera automaticamente chaves de criptografia de dados para seus campos criptografados e cria a coleção criptografada:

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: encryptedFieldsMap, masterKey: customerMasterKeyCredentials, });
3

Crie um documento de amostra que descreva as informações pessoais de um paciente. Use o cliente criptografado para inseri-lo na coleção patients, conforme mostrado no exemplo a seguir:

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, },}; const encryptedCollection = encryptedClient.getDB(encryptedDatabaseName).getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);
4

A amostra de código a seguir executa uma query de localização em um campo criptografado e imprime os dados descriptografados:

const findResult = await encryptedCollection.findOne({ "patientRecord.ssn": "987-65-4320",});console.log(findResult);

A saída do exemplo de código anterior deve ser semelhante a esta:

{ "_id": { "$oid": "648b384a722cb9b8392df76a" }, "name": "Jon Doe", "record": { "ssn": "987-65-4320", "billing": { "type": "Visa", "number": "4111111111111111" } }, "__safeContent__": [ { "$binary": { "base64": "L1NsYItk0Sg+oL66DBj6IYHbX7tveANQyrU2cvMzD9Y=", "subType": "00" } } ]}

Aviso

Não modifique o campo __safeContent__.

O campo __safeContent__ é essencial para o Queryable Encryption. Não modifique o conteúdo deste campo.

Para saber como a Queryable Encryption funciona, consulte Fundamentos da Queryable Encryption.

Para saber mais sobre os tópicos mencionados neste guia, consulte os seguintes links: