Início rápido
Nesta página
Visão geral
Este guia mostra como criar um aplicativo que implementa 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 criptografe e descriptografe 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 criptografia 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 está sujeito ao acesso não autorizado à chave de criptografia ou à 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, como mostrado na página Requisitos de instalação.
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
Os exemplos de código neste tutorial usam as seguintes variáveis para executar o fluxo de trabalho com Queryable Encryption:
Importante
Permissões de namespace da coleção de cofre de chaves
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.__keyVault
medicalRecords
banco de dados
Crie sua coleção criptografada
Criar uma chave mestra do cliente
Você deve criar uma chave mestra do cliente (CMK) para executar a Queryable Encryption.
Crie uma chave mestra do cliente de 96 bytes e salve-a em seu sistema de arquivos como o arquivo customer-master-key.txt
:
Aviso
Não use um arquivo de chave local em 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 de gerenciamentode chaves remoto (KMS ).
Para saber como usar um KMS remoto em sua implementação do Queryable Encryption, consulte o Guia de tutoriais .
Dica
Gere uma chave mestra do cliente 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 denominado 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.
Definir 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 para Queryable Encryption.
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 forma:
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 e obter métodos assistentes 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 das credenciais ao criar sua coleção criptografada.
Consulte um campo criptografado
A amostra de código a seguir executa uma query de localização em um campo criptografado e imprime os dados descriptografados:
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.
Saiba mais
Para exibir um tutorial sobre Queryable Encryption pronta para produção com um KMS remoto, consulte Tutoriais.
Para saber como funciona a Queryable Encryption, consulte a página 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 e cofres de chaves.
Veja como os provedores de KMS gerenciam suas chaves Queryable Encryption na página Provedores de KMS.