Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Segurança
/
Criptografia
/
Criptografia em execução
/
Queryable Encryption
/
Tutoriais

Usar Queryable Encryption automática com Amazon Web Services

Nesta página

  • Visão geral
  • Antes de começar
  • Configurar o KMS
  • Criar a Chave Mestre do Cliente
  • Criar um usuário AWS IAM
  • 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 Amazon Web Services (AWS) KMS.

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

  • Uma Chave mestre do cliente hospedada em uma instância do AWS KMS.

  • Uma aplicação funcional 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

1

Criar a Chave Mestre do Cliente

1

Faça login no seu Console de gerenciamento da AWS .

2

Navegue até o Console AWS KMS.

3

Crie sua chave mestra do cliente

Criar uma nova chave simétrica seguindo a documentação oficial da AWS em Criar chaves KMS simétricas. A chave que você cria é a chave mestre do cliente. Escolha um nome e uma descrição que o ajude a identificá-lo; esses campos não afetam a funcionalidade ou a configuração da CMK.

Na etapa Usage Permissions do processo de geração de chaves, aplique a seguinte política de chave padrão que habilita políticas de gerenciamento de identidade e acesso (IAM) para conceder acesso à sua chave mestre do cliente:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ARN of your AWS account principal>"
      },
      "Action": "kms:*",
      "Resource": "*"
    }
  ]
}

Importante

Registre o nome do recurso da Amazon (ARN) e a região da sua chave mestra do cliente. Você os usará nas etapas posteriores deste guia.

Dica

Saiba mais

Para saber mais sobre suas chaves mestres de clientes, consulte Chaves e cofres de chaves.

Para saber mais sobre as principais políticas, consulte Principais políticas no AWS KMS na documentação oficial da AWS.

2

Criar um usuário AWS IAM

1

Navegue até o Console AWS IAM.

2

Criar um usuário IAM

Criar um novo usuário programático do IAM no console de gerenciamento da AWS seguindo a documentação oficial da AWS sobre como adicionar um usuário . Você usará esse usuário do IAM como uma conta de serviço para seu aplicativo habilitado para Queryable Encryption. Seu aplicativo se autentica com o AWS KMS usando o usuário do IAM para criptografar e descriptografar suas DEKs (chaves de criptografia de dados) com sua chave mestra do cliente (CMK).

Importante

Registre suas Credenciais

Certifique-se de registrar as seguintes credenciais do IAM na etapa final da criação do seu usuário do IAM:

  • ID da chave de acesso

  • chave de acesso secreta

Você tem uma oportunidade de registrar essas credenciais. Se você não registrar essas credenciais durante essa etapa, deverá criar outro usuário do IAM .

3

Conceder permissões

Conceda ao usuário do IAM permissões de kms:Encrypt e kms:Decrypt para sua chave mestra remota.

Importante

O novo usuário do cliente IAM não deve ter permissões administrativas para a chave mestre. Para manter seus dados seguros, siga o principal de privilégio mínimo.

A política em linha a seguir permite que um usuário do IAM criptografe e descriptografe com a chave mestra do cliente com o mínimo de privilégios possível:

Observação

Chave mestra remota ARN

A política a seguir requer o ARN da chave gerada na etapa Criar a chave mestra deste guia.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt", "kms:Encrypt"],
      "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
    }
  ]
}

Para aplicar a política anterior ao seu usuário do IAM, siga o guia Adicionando permissões de identidade do IAM na documentação da AWS.

Importante

Autenticar com funções IAM em produção

Ao implantar seu aplicativo habilitado para Queryable Encryption em um ambiente de produção, autentique seu aplicativo por meio de uma função do IAM em vez de um usuário do IAM .

Para autenticar com uma role do IAM , especifique suas credenciais de role do IAM temporárias no objeto do provedor de KMS da seguinte forma:

{
    "accessKeyId":"<temporary access key ID>",
    "secretAccessKey":"<temporary secret access key>",
    "sessionToken":"<temporary session token>"
}

Você pode obter suas credenciais de role do IAM temporárias por meio dos seguintes mecanismos:

Seu aplicativo deve incluir lógica para obter novas credenciais temporárias e recriar sua instância MongoClient habilitada para Queryable Encryption quando cada conjunto de credenciais temporárias expirar.

Para saber mais sobre roles do IAM, consulte as seguintes páginas na documentação oficial da AWS:

Para saber como obter credenciais temporárias e assumir uma função em cada um dos idiomas suportados neste guia, consulte os seguintes exemplos executáveis do AssumeRole na documentação da Amazon Web Services:

Criar o aplicativo

1

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:

2

Crie seu diretório de dados e collection criptografada

1

Adicione suas credenciais da AWS 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ê criou e registrou seu ID de chave de acesso e chave de acesso secreta na etapa Criar um usuário IAM deste guia.

Dica

Saiba mais

Para saber mais sobre o objeto do provedor KMS para AWS, consulte Amazon Web Services KMS.

2

Adicione suas informações principais

Atualize o seguinte código para especificar sua Chave Mestre do Cliente:

Dica

Você registrou o ARN e a região da chave mestra do cliente na etapa Criar uma chave mestra do cliente deste guia.

3

Crie seu diretório 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 .

4

Crie sua coleção criptografada

Use uma instância MongoClient habilitada para Queryable Encryption para especificar quais campo você deve criptografar e criar sua collection criptografada:

A saída do código nesta seção deve se assemelhar ao seguinte:

Created encrypted collection!

Dica

Saiba mais

Para visualizar um diagrama que mostra como o cliente cria a chave de encriptação de dados ao usar um AWS KMS, consulte Arquitetura.

Para saber mais sobre as opções de criação de uma chave de encriptação de dados criptografada com uma chave mestra do cliente hospedada no AWS KMS, consulte o objeto dataKeyOpts.

Dica

Veja: Código Completo

3

Configure seu MongoClient para leituras e gravações criptografadas

1

Especifique o namespace da coleção do Key Vault

Especifique encryption.__keyVault como o namespace da coleção Key Vault.

2

Especifique suas Credenciais AWS

Informe o fornecedor KMS do aws e as credenciais IAM do usuário:

Dica

Você criou e registrou seu ID de chave de acesso e chave de acesso secreta na etapa Criar um usuário IAM deste guia.

3

Crie um mapa de campos criptografados para sua collection

4

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.

5

Criar o MongoClient

Instale instantaneamente um objeto de cliente MongoDB com as seguintes configurações de criptografia automática:

4

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

5

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 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.

← Tutoriais
Use o Queryable Encryption com o Azure →

Nesta página