Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
Início rápido
Nesta página
Visão geral
Este guia mostra como criptografar um documento com a criptografia automática em nível de campo do lado do cliente (CSFLE) e um driver MongoDB.
Depois de concluir este guia, você deve ter o seguinte conhecimento e software:
Conhecimento das etapas para configurar um driver para criptografar campos em um documento.
Um aplicativo cliente funcional, mas não pronto para produção, que utiliza criptografia automática de nível de campo do lado do cliente.
Importante
Não use este aplicativo em produção
Como esse aplicativo de exemplo armazena uma chave de criptografia no sistema de arquivos do aplicativo, você corre o risco de acesso não autorizado à chave ou de perda da chave para descriptografar seus dados.
Para ver um tutorial que demonstra como criar um aplicativo habilitado para CSFLE pronto para produção, consulte Tutoriais.
Antes de começar
Para concluir e executar o código neste guia, você precisa configurar seu ambiente de desenvolvimento, como mostrado na página Requisitos de instalação.
Selecione a linguagem de programação para a qual você deseja ver exemplos de código no menu suspenso Select your language no lado direito da página.
Dica
Veja: Aplicação Completa
Para ver o código completo do aplicativo executável deste tutorial, acesse o link a seguir:
Procedimento
Criar uma Chave Mestre do Cliente
Você deve criar uma chave mestre do cliente (CMK) para executar o CSFLE.
Crie uma chave mestra do cliente de 96 bytes e salve-a no seu provedor de chaves locais, que é o seu sistema de arquivos, como o arquivo master-key.txt:
openssl rand 96 > master-key.txt
Observação
Use uma linguagem de programação para criar uma chave mestre do cliente
Se preferir usar sua linguagem de programação de preferência para gerar sua CMK , você pode visualizar trechos de código que demonstram como gerar uma Chave Mestre do Cliente em cada uma das linguagens suportadas deste guia no GitHub.
Aviso
Não use o provedor de chave local na produção
O provedor de chaves locais é um método inseguro de armazenamento e não é recomendado para produção. Em vez disso, você deve armazenar as chaves mestras do cliente em um sistema de gerenciamento de chaves remoto (KMS).
Para saber como usar um KMS remoto na implementação do CSFLE, consulte o guia Tutoriais.
Crie um índice único em sua coleção do Key Vault
Crie um índice único no campo keyAltNames na sua collection encryption.__keyVault .
Selecione a guia correspondente ao driver MongoDB de sua preferência:
Criar uma chave de criptografia de dados
Leia a chave mestre do cliente e especifique as configurações do provedor KMS
Recupere o conteúdo do arquivo de chave mestra do cliente que você gerou na etapa Criar uma chave mestra do cliente deste guia.
Passe o valor chave mestra do cliente para as configurações do seu provedor de KMS. O cliente usa essas configurações para descobrir a chave mestra do cliente. Como você está usando o provedor de chave local, defina o nome do provedor para local.
Criar uma chave de criptografia de dados
Crie um cliente com sua string de conexão do MongoDB e o namespace da collection de cofre de chaves e crie um diretório de dados:
Observação
Permissões do namespace da coleção do Key Vault
A Key Vault collection deste guia é a collection __keyVault no banco de dados encryption . Verifique se o usuário do banco de dados que seu aplicativo usa para se conectar ao MongoDB tem permissões de Leitura e Gravação no namespace encryption.__keyVault .
A saída do código acima deve ser semelhante ao seguinte:
DataKeyId [base64]: 3k13WkSZSLy7kwAAP4HDyQ==
Dica
Veja: Código Completo
Configure o MongoClient
Especifique o namespace da coleção do Key Vault
Especifique encryption.__keyVault como o namespace da coleção Key Vault.
Especifique a chave mestre do cliente local
Especifique o provedor de KMS e especifique sua chave em linha:
Crie um esquema de criptografia para sua coleção
Dica
Adicione sua chave de encriptação de dados ID Base64
Certifique-se de atualizar o seguinte código para incluir seu ID Base64 DEK . Você recebeu esse valor na etapa Gerar sua chave de criptografia de dados deste guia.
Especifique o local da biblioteca compartilhada de criptografia automática
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 CSFLE.
Criar o MongoClient
Instale instantaneamente um objeto de cliente MongoDB com as seguintes configurações de criptografia automática:
Inserir um documento com campos criptografados
Use sua instância de MongoClient habilitada para CSFLE para inserir um documento criptografado no namespace medicalRecords.patients usando o seguinte trecho de código:
Quando você insere um documento, o cliente habilitado para CSFLE criptografa os campos do documento de forma que ele se pareça com o seguinte:
{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } } }
Dica
Veja: Código Completo
Recupere seu documento criptografado
Recupere o documento criptografado inserido na etapa Inserir um documento com campos criptografados deste guia.
Para mostrar a funcionalidade do CSFLE, as seguintes consultas de trecho de código para seu documento com um cliente configurado para CSFLE automático, bem como um cliente que não está configurado para CSFLE automático.
A saída do trecho de código anterior deve ser semelhante a esta:
Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' } } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' } }
Dica
Veja: Código Completo
Saiba mais
Para ver um tutorial sobre o CSFLE pronto para produção com um KMS remoto, consulte Tutoriais.
Para saber como funciona o CSFLE, consulte Fundamentos.
Para saber mais sobre os tópicos mencionados neste guia, consulte os seguintes links: