Início rápido
Nesta página
Visão geral
Este guia mostra como criar um aplicativo que implemente o recurso Queryable Encryption do MongoDB para criptografar e descriptografar automaticamente campos de documentos.
Selecione o idioma do driver no menu suspenso à direita para saber como criar um aplicativo que criptografa e descriptografa automaticamente os campos do documento.
Importante
Não use este aplicativo de amostra em produção
Como as instruções deste tutorial incluem o armazenamento de uma chave de encriptação em um ambiente inseguro, você não deve usar uma versão não modificada desse aplicativo em produção. O uso desse aplicativo em produção gera o risco de acesso não autorizado à chave de encriptação ou a perda da chave necessária para descriptografar seus dados. O objetivo deste tutorial é demonstrar como usar a Queryable Encryption sem precisar configurar um sistema de gerenciamento de chaves.
Você pode usar um sistema de gerenciamento de chaves para armazenar com segurança sua chave de criptografia em um ambiente de produção. Um KMS é um serviço remoto que armazena e gerencia suas chaves de encriptação com segurança. Para saber como configurar um aplicativo habilitado para Queryable Encryption que usa um KMS, consulte os Tutoriais de Queryable Encryption.
Antes de começar
Para concluir e executar o código neste guia, você precisa configurar seu ambiente de desenvolvimento, conforme mostrado na página Instalar um driver compatível com criptografia consultável .
Dica
Veja: Aplicação Completa
Para ver o código completo desse aplicativo de amostra, selecione a aba correspondente à sua linguagem de programação e siga o link fornecido. Cada repositório de aplicativo de amostra inclui um arquivo README.md que você pode utilizar para saber como configurar seu ambiente e executar o aplicativo.
Procedimento
Atribua variáveis ao seu aplicativo
As amostras de código neste tutorial usam as seguintes variáveis para executar o fluxo de trabalho da Queryable Encryption:
Importante
Permissões do namespace da coleção do Key Vault
Para concluir este tutorial, o usuário do banco de dados que seu aplicativo usa para se conectar ao MongoDB deve ter permissões dbAdmin nos seguintes namespaces:
encryption.__keyVaultmedicalRecordsBanco de dados
Crie sua coleção criptografada
Criar uma Chave Mestre do Cliente
Você deve criar uma chave mestra do cliente (CMK) para executar a Queryable Encryption.
Crie uma Chave Mestra do Cliente 96bytes e salve-a em seu sistema de arquivos como o arquivo customer-master-key.txt:
Aviso
Não use um arquivo de chave local na produção
Um arquivo de chave local em seu sistema de arquivos é inseguro e não é recomendado para produção. Em vez disso, você deve armazenar as chaves mestras do cliente em um Sistema degerenciamento de chaves remoto ( KMS).
Para saber como usar um KMS remoto em sua implementação do Queryable Encryption, consulte o Guia de tutoriais .
Dica
Gerar uma CMK a partir da Linha de Comando
Use o seguinte comando para gerar uma chave mestra do cliente a partir de um shell Unix ou PowerShell:
Shell Unix:
echo $(head -c 96 /dev/urandom | base64 | tr -d '\n') PowerShell:
$r=[byte[]]::new(64);$g=[System.Security.Cryptography.RandomNumberGenerator]::Create();$g.GetBytes($r);[Convert]::ToBase64String($r)
Salve a saída do comando anterior em um arquivo chamado customer-master-key.txt.
Recuperar a chave-mestre do cliente e especificar 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. Defina o nome do provedor como local para informar ao driver que você está usando um provedor de chaves local.
Defina suas opções 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 .
Crie um cliente para configurar uma coleção criptografada
Para criar um cliente usado 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.
Especifique campos para criptografia
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 maneira:
Observação
No exemplo de código anterior, os campos "ssn" e "billing" são criptografados, mas somente o campo "ssn" pode ser consultado.
Criar a coleção
Instancie ClientEncryption para acessar a API dos métodos auxiliares de criptografia.
Como você está usando uma chave mestra do cliente local, não é necessário fornecer as credenciais da chave mestra do cliente. Crie uma variável contendo um objeto vazio para usar no lugar de credenciais ao criar sua coleção criptografada.
Inserir um documento com campos criptografados
Query em um campo criptografado
A seguinte amostra de código executa uma consulta de localização em um campo criptografado e imprime os dados descriptografados:
A saída da amostra 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.
Saiba mais
Para exibir um tutorial sobre Queryable Encryption pronta para produção com um KMS remoto, consulte Tutoriais.
Para saber como a Queryable Encryption funciona, consulte Fundamentos.
Para saber mais sobre os tópicos mencionados neste guia, consulte os seguintes links:
Saiba mais sobre os componentes da Queryable Encryption na página Referência .
Saiba como funcionam as chaves mestras do cliente e as chaves de criptografia de dados na página Chaves de criptografia e cofres de chaves .
Veja como os provedores de KMS gerenciam suas chaves de Queryable Encryption na página Provedores de KMS .