Usar Queryable Encryption com o GCP
Nesta página
- Visão geral
- Antes de começar
- Configurar o KMS
- Registrar uma conta de serviço do GCP
- Criar uma chave mestra do cliente GCP
- Criar o aplicativo
- Crie um índice único em sua coleção do Key Vault
- Crie seu diretório de dados e collection criptografada
- Configure seu MongoClient para leituras e gravações criptografadas
- Inserir um documento com campos criptografados
- Recupere seu documento criptografado
- Saiba mais
Visão geral
Este guia mostra como criar um aplicativo habilitado para Queryable Encryption usando o serviço de gerenciamento de chaves do Google Cloud.
Depois de concluir as etapas deste guia, você deverá ter:
Uma chavemestra do cliente hospedada no serviço de gerenciamento de chaves do Google Cloud.
Uma aplicação cliente que insere documento criptografados usando sua chave mestra do cliente.
Antes de começar
Para concluir e executar o código neste guia, você precisa configurar seu ambiente de desenvolvimento como mostrado na páginaRequisitos de instalação do .
Dica
Veja: Aplicação Completa
Para ver o código completo do aplicativo criado neste guia, selecione a guia correspondente à sua linguagem de programação e siga o link fornecido:
Configurar o KMS
Registrar uma conta de serviço do GCP
Registre-se ou faça login em sua conta existente no Google Cloud.
Crie uma conta de serviço para seu projeto
Para criar uma conta de serviço no GCP, siga a seção Criar uma conta de serviço guia na documentação oficial do Google.
Adicionar uma chave de conta de serviço
Para adicionar uma chave de conta de serviço no GCP, siga o Gerenciamento de chaves de conta de serviço guia na documentação oficial do Google.
Importante
Ao criar sua chave de conta de serviço, você recebe um download único das informações da chave privada. Certifique-se de baixar este arquivo no formato PKCS12 ou JSON para uso posterior neste tutorial.
Criar uma chave mestra do cliente GCP
Criar uma nova chave mestre do cliente
Crie um chaveiro e uma chave simétrica seguindo o Criar uma chave guia da documentação oficial do Google.
Essa chave é a chave mestre do cliente (CMK).
Registre os seguintes detalhes da sua chave mestra do cliente para uso em uma etapa futura deste tutorial.
Campo | Obrigatório | Descrição |
---|---|---|
key_name | Sim | Identificador para a chave mestra do cliente. |
key_ring | Sim | Identificador do grupo de chaves ao qual sua chave pertence. |
key_version | Não | A versão da chave nomeada. |
localização | Sim | Região especificada para sua chave. |
endpoint | Não | O host e a porta opcional do GCP KMS. O valor padrão é cloudkms.googleapis.com . |
Criar o aplicativo
Selecione a guia que corresponde ao driver MongoDB que você está usando em seu aplicativo para ver as amostras de código relevantes.
Crie seu diretório de dados e collection criptografada
Adicione suas credenciais do GCP KMS
Adicione as credenciais da conta de serviço ao código do cliente habilitado para Queryable Encryption.
Selecione a guia correspondente ao driver MongoDB de sua preferência:
Dica
Você salvou um arquivo contendo as credenciais da chave da conta de serviço na etapa Criar uma conta de serviço GCP deste guia.
Se você baixou suas credenciais no formato JSON, poderá usar o seguinte comando para extrair o valor de sua chave privada, substituindo <credentials-filename>
pelo nome do seu arquivo de credenciais:
cat <credentials-filename> | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64
Se você baixou suas credenciais no formato PKCS12, você precisará especificar sua senha de importação de conta de serviço do GCP e adicionar uma senha PEM para acessar a chave ao acessá-la usando o seguinte comando, substituindo <credentials-filename>
pelo nome do seu arquivo de credenciais:
openssl pkcs12 -info -in <credentials-filename>
Dica
Saiba mais
Para saber mais sobre o objeto do provedor de KMS para o GCP, consulte GCP KMS.
Adicione suas informações principais
Atualize o seguinte código para especificar sua Chave Mestre do Cliente:
Dica
Registrou os detalhes da Chave Mestre do Cliente na etapa Criar uma Chave Mestre do Cliente deste guia.
Gere suas Chaves de Criptografia de Dados
Crie um cliente com sua connection string do MongoDB e o namespace da collection do Key Vault e crie as chaves de criptografia de dados:
Observação
Permissões de namespace da coleção de cofre de chaves
A Key Vault collection deste guia é a collection __keyVault
no banco de dados encryption
. Certifique-se de que o usuário do banco de dados que seu aplicativo usa para se conectar ao MongoDB tenha permissões de Leitura e Gravação no namespace encryption.__keyVault
.
A saída do código nesta seção deve se assemelhar ao seguinte:
Created encrypted collection!
Dica
Saiba mais
Para ver um diagrama que mostra como o aplicativo cliente cria a chave de encriptação de dados ao usar um serviço de gerenciamento de chaves do Google Cloud, consulte Arquitetura.
Para saber mais sobre as opções de criação de uma Chave de criptografia de dados criptografada com uma Chave Mestre do Cliente hospedada no Azure Key Vault, consulte Objeto kmsProviders e Objeto dataKeyOpts.
Dica
Veja: Código Completo
Configure seu MongoClient para leituras e gravações criptografadas
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 Queryable Encryption.
Inserir um documento com campos criptografados
Use sua instância MongoClient
habilitada para Queryable Encryption 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 Queryable Encryption criptografa os campos do documento de forma que ele se pareça com o seguinte:
{ "_id": { "$oid": "<_id value>" }, "firstName": "Jon", "lastName": "Doe", "patientId": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "address": "157 Electric Ave.", "patientRecord": { "ssn": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "billing": { "$binary": { "base64": "<ciphertext>", "subType": "06" } } }, "medications": { "$binary": { "base64": "<ciphertext>", "subType": "06" } }, "__safeContent__": [ { "$binary": { "base64": "<ciphertext>", "subType": "00" } }, { "$binary": { "base64": "<ciphertext>", "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.
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 da Queryable Encryption, o seguinte trecho de código consulta seu documento com um cliente configurado para Queryable Encryption automática, bem como um cliente que não está configurado para Queryable Encryption automática.
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("628eabeb37590e84ea742665"), firstName: 'Jon', lastName: 'Doe', patientId: new Binary(Buffer.from("0798810acc0f4f46c9a76883cee80fca12102e9ddcbcdae46a821fa108a8155a850f2d0919475b6531ada68973d436a199b537a05a98a708c36d2bfec4979d59cbe66878865ce19e392d3e4789d309bdacc336e32efcc851806ae0a41b355288c10d01e39147e1c40d919c41913a0c9d2d3fad0d0d1d2873c4fc82c6c22f27b517df5f3131b331b96ed16a7c5cf89e09082a2d898c2dcd73da91d08760ba74a70077b2d0fdbbe1eea75655a19fcc397812325ad40b102cbd16b8d36b22e11e3f93404f24a8ff68cfdec3c22b0e787cb30078a5227b2a", "hex"), 6), address: '157 Electric Ave.', patientRecord: { ssn: new Binary(Buffer.from("07e8b69630c32f4a00a542af768f8abcf50223edd812ff20b0ecb046ee1a9f5a0eef8d85d99cd26076411129942752516ee605c55aadce73f3d44d81ea6ddbbb8134b108a9deb40d8cab9cb4f08ef210ab0c9d2ea4347f9d235b861baf29751e60abcf059eb5c120305bd5ac05a4e07ac8ccfa6d37283f4cdbfeb7a8accb65b71857d486b5cf55e354d6a95e287d9e2dd65f3f9d9c4c9d0bdb1f26c4bd549d7be77db81796be293e08b2223bac67b212423c4e06568578b5bd7a3c33cedc1b291bcda0b27e005144d344563711a489f24b8e9b65bbb721d3a0e9d9b227a0cec0cbad", "hex"), 6), billing: new Binary(Buffer.from("06808ae69d4caa49cf90bb688f386f097f03f870a7b8fcebb1980c9ee5488b1f0f68558fc2163adcd92d00ea5f349f56ed34e7b391f54c48ed2760b4bde73022fc818dc7486a4e046b92ce9c82e00333c7779d9d6bb476713a20632b593b7de54812662cfc4d174d05451d3f4195514e12edba", "hex"), 6) }, medications: new Binary(Buffer.from("06665ec15d38254dc4aa16da856789d33404f27bfea53e0d2fa4deaff166989ab33f469644d89c29112d33b41dbe54ec2d89c43f3de52cdc5d454e8694046216f533614fa7b42b7c5406d6518f7ed8f9e3ce52fda6c8b2146d0f8cc51e21a3467183697e1735a9f60c18e173c1916101", "hex"), 6), __safeContent__: [ new Binary(Buffer.from("3044b134ad0f7c8a90dab1e05bb8b296a8ede540796bd7403ab47693cdba1b26", "hex"), 0), new Binary(Buffer.from("a22ddf9a5657cdd56bef72febbba44371899e6486962a1c07d682082c4e65712", "hex"), 0) ] } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("628eaca1dcf9b63e2f43162d"), firstName: 'Jon', lastName: 'Doe', patientId: 12345678, address: '157 Electric Ave.', patientRecord: { ssn: '987-65-4320', billing: { type: 'Visa', number: '4111111111111111' } }, medications: [ 'Atorvastatin', 'Levothyroxine' ], __safeContent__: [ new Binary(Buffer.from("fbdc6cfe3b4659693650bfc60baced27dcb42b793efe09da0ded54d60a9d5a1f", "hex"), 0), new Binary(Buffer.from("0f92ff92bf904a858ef6fd5b1e508187f523e791f51d8b64596461b38ebb1791", "hex"), 0) ] }
Dica
Veja: Código Completo
Saiba mais
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.