Chaves e cofres de chaves
Nesta página
Visão geral
Este guia contém mais informações sobre os seguintes componentes da criptografia no nível do campo do lado do cliente (CSFLE):
Chaves de criptografia de dados (DEK)s
Chaves mestras do cliente (CMK)s
Key Vault collections
Sistema de Gerenciamento de Chaves (KMS)
Para exibir guias passo a passo demonstrando como usar os componentes anteriores para configurar um cliente habilitado para CSFLE, consulte os seguintes recursos:
Data Encryption Keys e a Chave mestre do cliente
A criptografia em uso usa uma hierarquia de chaves de vários níveis para proteger seus dados, geralmente chamada de "criptografia de envelope" ou "chaves de encapsulamento".
Uma chave mestra do cliente (CMK), às vezes chamada de chave KMS (Sistema de Gerenciamento de Chaves), é a chave de nível superior que você cria no fornecedor de chaves provisionado pelo cliente, como um KMS na nuvem. O CMK criptografa as chaves de criptografia de dados (DEK), que, por sua vez, criptografam os campos em seus documentos. Sem acesso a um CMK, seu aplicativo cliente não pode descriptografar os DEKs associados.
O MongoDB armazena DEKs, criptografadas com sua CMK, na collection Key Vault como documentos BSON. O MongoDB nunca pode descriptografar os DEKs, pois o gerenciamento de chaves é controlado pelo cliente e pelo cliente.
Se você excluir uma DEK, todos os campos criptografados com essa DEK ficarão permanentemente ilegíveis. Se você excluir uma CMK, todos os campos criptografados com uma DEK usando essa CMK se tornarão permanentemente ilegíveis.
Aviso
A Chave Mestra do Cliente é a chave mais sensível na Queryable Encryption. Se a sua CMK estiver comprometida, todos os seus dados criptografados poderão ser descriptografados. Use um sistema de Gerenciamento de Chaves Remoto para armazenar sua CMK.
Importante
Use um fornecedor de serviços de gerenciamento de chaves remoto
Armazene sua chave mestra do cliente em um sistema de gerenciamento de chaves (KMS) remoto.
Para saber mais sobre por que você deve usar um KMS remoto, consulte Motivos para usar um Sistema de Gerenciamento de Chaves Remotas.
Para ver uma lista de todos os fornecedores de KMS compatíveis, consulte a página Fornecedores de KMS.
Rotação de chaves
Você gira sua chave mestra do cliente manual ou automaticamente no provedor de chaves provisionado. O MongoDB não tem visibilidade desse processo. Depois de girar a chave mestra do cliente, o MongoDB a usará para envolver todos os novos DEKs. Ele não envolve DEKs criptografados existentes. Eles ainda estão agrupados com a chave mestra do cliente anterior.
Para fazer a rotação de algumas ou todas as DEKs criptografadas em seu cofre de chaves, use o método KeyVault.rewrapManyDataKey(). Ele envolve perfeitamente as chaves com a nova CMK especificada, sem interromper seu aplicativo. As próprias DEKs são deixadas inalteradas depois de envolvê-las com a nova CMK.
Key Vault Collections
A Key Vault collection é a collection do MongoDB que você usa para armazenar documentos criptografados de Data Encryption Key (DEK). Documentos DEK são documentos BSON que contêm DEKs e possuem a seguinte estrutura:
{ "_id" : UUID(<string>), "status" : <int>, "masterKey" : {<object>}, "updateDate" : ISODate(<string>), "keyMaterial" : BinData(0,<string>), "creationDate" : ISODate(<string>), "keyAltNames" : <array> }
Crie uma Key Vault collection igual criaria uma collection padrão do MongoDB. Sua Key Vault collection deve ter um índice único no campo keyAltNames. Para conferir se o índice único existe, execute o comando listIndexes na Key Vault collection:
1 db.runCommand({ 2 listIndexes: "__keyVault", 3 });
1 { 2 cursor: { 3 id: Long("0"), 4 ns: 'encryption.__keyVault', 5 firstBatch: [ 6 { v: 2, key: { _id: 1 }, name: '_id_' } 7 ] 8 }, 9 ok: 1, 10 }
Se o índice único não existir, seu aplicativo deverá criá-lo antes de executar o gerenciamento DEK.
Para saber como criar uma collection do MongoDB, consulte Bancos de dados e coleções.
Dica
Funcionalidade mongosh
O método mongosh KeyVault.createKey() cria automaticamente um índice único no campo keyAltNames se não existir.
Para exibir diagramas detalhando como sua collection DEK, CMK e Key Vault interagem em todas as arquiteturas de provedor KMS compatíveis, consulte Provedores KMS CSFLE.
Nome da Key Vault Collection
Você pode usar qualquer namespace que não seja de administrador para armazenar sua collection do Key Vault. Por convenção, os exemplos ao longo desta documentação utilizam o namespace do encryption.__keyVault.
Aviso
Não use o banco de dados admin para armazenar collections relacionadas à criptografia. Se você usar o banco de dados admin para essa collection, o cliente MongoDB não conseguirá acessar ou descriptografar seus dados devido à falta de permissões.
Permissões
Aplicativos com acesso de read à Key Vault collection podem recuperar uma Data Encryption Key (DEK) criptografada fazendo queries na collection. No entanto, somente aplicativos com acesso à Chave mestra do cliente (CMK) usada para criptografar uma DEK podem usar essa DEK para fins de criptografia ou descriptografia. Você deve conceder ao seu aplicativo acesso à Key Vault collection e à sua CMK para criptografar e descriptografar documentos com uma DEK.
Para saber como conceder acesso a uma coleção MongoDB, consulte Gerenciar usuários e funções no manual MongoDB.
Para saber como conceder acesso ao aplicativo à CMK, consulte o tutorial Tutoriais.
Key Vault Cluster
Por padrão, o MongoDB armazena a Key Vault Collection no cluster conectado. O MongoDB também oferece suporte à hospedagem da Key Vault Collection em uma implantação do MongoDB diferente do cluster conectado. Os aplicativos devem ter acesso tanto ao cluster que hospeda sua Key Vault Collection quanto ao cluster de conexão para executar operações de Queryable Encryption.
Para especificar o cluster que hospeda sua Key Vault Collection, use o campo keyVaultClient do objeto MongoClient do cliente. Para saber mais sobre as opções de configuração específicas do CSFLE no objeto MongoClient do seu cliente, consulte Opções do MongoClient específicas do CSFLE.
Atualizar uma Key Vault Collection
Para adicionar uma DEK à sua Key Vault collection, use o método createKey de um objeto ClientEncryption.
Para excluir ou atualizar uma DEK, use um dos seguintes mecanismos:
O método
rewrapManyDataKeyOperações de CRUD padrão
Para saber mais sobre o método rewrapManyDataKey, consulte a documentação do método para seu cliente ou driver:
Dica
Funcionalidades específicas do mongosh
mongosh fornece os seguintes métodos adicionais para trabalhar com sua collection do Key Vault:
Para exibir um tutorial que mostra como criar uma DEK, consulte o Início rápido.