Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

Regras de criptografia automática

Nesta página

  • encrypt Palavras-chave do esquema
  • encryptMetadata Palavras-chave do esquema
  • Exemplos

Observação

Funcionalidade de empresas

O recurso automático da criptografia no nível do campo só está disponível no MongoDB Enterprise 4.2 ou posterior e no MongoDB Atlas 4.2 ou clusters posteriores.

A criptografia automática em nível de campo no lado do cliente requer regras especificadas pelo usuário que identifiquem quais campos devem ser criptografados e como criptografar esses campos. Os aplicativos devem especificar as regras de criptografia automática usando um subconjunto rigoroso da sintaxe padrão do Esquema JSON schema 4 e as seguintes palavras-chave específicas de criptografia:

Considere um MongoDB database onde a collection do employees no reconhecimento de data center do hr contém documento que se assemelham ao seguinte:

{
  "fname" : "Jo",
  "lname" : "Doe",
  "taxid" : "123-45-6789",
  "taxid-short" : "6789"
}

Os campos taxid e taxid-short contêm informações de identificação pessoal (PII) que devem ser protegidas contra visualização não autorizada no cliente e no servidor. As seguintes regras de criptografia automática para a coleção hr.employees marcam os campos taxid e taxid-short para criptografia automática de nível de campo do lado do cliente. MongoDB oficial 4.2+ drivers compatíveis , mongosh e o 4.2 ou shell mongo legado posterior configurado com essas regras criptografam automaticamente os campos taxid e taxid-short para operações de gravação ou leitura na coleção hr.employees .

{
  "hr.employees": {
    "bsonType": "object",
    "properties": {
      "taxid": {
        "encrypt": {
          "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
          "bsonType" : "string"
        }
      },
      "taxid-short": {
        "encrypt": {
          "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType": "string"
        }
      }
    }
  }
}

  • Para o MongoDB 4.2+ shell, use o construtor Mongo() para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia no nível do campo no lado do cliente. Consulte Conectar-se a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo.

  • Para o MongoDB 4 oficial.2+ drivers compatíveis, use o construtor de conexão de banco de dados específico do driver (por exemplo, MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia em nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Importante

A criptografia automática no nível do campo do lado do cliente oferece suporte a um subconjunto rigoroso da sintaxe do JSON schema apenas para definir o comportamento da criptografia. Não especifique palavras-chave de validação do documento nas regras de criptografia automática. Para definir regras de validação de documentos, configure a validação de esquema do lado do servidor.

encrypt Palavras-chave do esquema

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}
encrypt

Objeto

Indica que <fieldName> deve ser criptografado. O objeto encrypt tem os seguintes requisitos:

  • encrypt não pode ter nenhum campo filho no objeto <fieldName> . encrypt deve ser o único filho do objeto <fieldName> .

  • encrypt não pode ser especificado em nenhum subesquema das palavras-chave items ou additionalItems . Especificamente, a criptografia automática no nível do campo do lado do cliente não oferece suporte à criptografia de elementos individuais de uma array.

O objeto encrypt pode conter somente os seguintes campos:

Incluir qualquer outro campo no objeto encrypt resulta em erros ao emitir operações de leitura ou gravação criptografadas automaticamente

Se keyId ou algorithm forem omitidos, a Biblioteca Compartilhada de Criptografia Automática verificará a árvore completa de campos pai e tentará construir essas opções a partir do objeto encryptMetadata mais próximo que especifica a opção. bsonType não pode ser herdado e pode ser necessário dependendo do valor de algorithm.

Se a Biblioteca compartilhada de criptografia automática não puder construir o objeto encrypt completo usando os campos especificados para o objeto e quaisquer chaves herdadas encryptMetadatanecessárias, a criptografia automática falhará e retornará um erro.

encrypt.algorithm

String

Indica qual algoritmo de criptografia usar ao criptografar valores de <fieldName>. Suporta apenas os seguintes algoritmos :

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obter a documentação completa sobre os algoritmos de criptografia, consulte Algoritmos de criptografia.

Se omitido, a Biblioteca Compartilhada de Criptografia Automática verifica a árvore completa de campos pai para a chave encryptMetadata.algorithm mais próxima e herda esse valor. Se não houver nenhum algorithm pai, a criptografia automática em nível de campo falhará e retornará um erro.

  • Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, o objeto encrypt exigirá o campo encrypt.bsonType .

  • Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Random, o objeto encrypt poderá incluir o campo encrypt.bsonType .

encrypt.bsonType

Corda | Array de strings

O tipo de BSON do campo que está sendo criptografado. Obrigatório se encrypt.algorithm for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.

Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType deverá especificar um único tipo. bsonType não suporta nenhum dos seguintes tipos BSON com o algoritmo de criptografia determinístico:

  • double

  • decimal128

  • bool

  • object

  • array

Se encrypt.algorithm ou seu valor herdado for AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType será opcional e poderá especificar uma array de tipos de bson suportados. Para campos com bsonType de array ou object, o cliente criptografa toda a array ou objeto e não seus elementos individuais.

encrypt.bsonType não suporta os seguintes tipos, independentemente de encrypt.algorithm ou de seu valor herdado:

  • minKey

  • maxKey

  • null

  • undefined

encrypt.keyId

Array de UUID único

O UUID da chave de criptografia de dados a ser usada para criptografar valores de campo. O UUID é um conjunto de dados binários BSON elemento do subtipo 4.

Especifique uma string dentro da array.

Se omitido, a Biblioteca Compartilhada de Criptografia Automática verifica a árvore completa de campos pai para a chave encryptMetadata.keyId mais próxima e herda esse valor. Se não houver nenhum keyId pai, a criptografia automática em nível de campo falhará e retornará um erro.

O keyId ou seu valor herdado deve existir no cofre de chave especificado como parte das opções de configuração de criptografia automática. Se a chave de encriptação de dados especificada não existir, a criptografia automática falhará.

Os drivers oficiais compatíveis com o MongoDB 4.2+ têm requisitos específicos de idioma para especificar o UUID. Consulte a documentação do driver para obter a documentação completa sobre a implementação da criptografia no nível do campo do lado do cliente.

encryptMetadata Palavras-chave do esquema

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}
encryptMetadata

Objeto

Define as opções de criptografia que um objeto encrypt aninhado no filho properties pode herdar. Se um encrypt estiver faltando uma opção necessária para oferecer suporte à criptografia, a Biblioteca Compartilhada de Criptografia Automática pesquisará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique a opção ausente.

encryptMetadata deve ser especificado em subesquemas com bsonType: "object". encryptMetadata não pode ser especificado para nenhum subesquema das palavras-chave items ou additionalItems . Especificamente, a criptografia automática no nível do campo do lado do cliente não oferece suporte à criptografia de elementos individuais de uma array.

O objeto encryptMetadata pode conter somente os seguintes campos. Incluir qualquer outro campo no objeto encrypt resulta em erros ao emitir operações de leitura ou gravação criptografadas automaticamente:

encryptMetadata.algorithm

String

O algoritmo de criptografia a ser usado para criptografar um determinado campo. Se um objeto encrypt não estiver no campo algorithm , a Biblioteca Compartilhada de Criptografia Automática procurará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique encryptMetadata.algorithm.

Suporta apenas os seguintes algoritmos :

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random

  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obter a documentação completa sobre os algoritmos de criptografia, consulte Algoritmos de criptografia.

Se especificar AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, qualquer objeto encrypt que herde esse valor deverá especificar encrypt.bsonType.

encryptMetadata.keyId

Array de UUID único

O UUID de uma chave de criptografia de dados. O UUID é um conjunto de dados binários BSON elemento do subtipo 4.

Especifique uma string dentro da array.

Se um objeto encrypt não estiver no campo keyId , a Biblioteca Compartilhada de Criptografia Automática procurará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique encryptMetadata.keyId.

O diretório de dados deve existir no cofre de chave especificado como parte das opções de configuração da criptografia automática. As opções de configuração especificadas também devem incluir o acesso apropriado ao KMS e à chave mestra do cliente usadas para criar a chave de dados. A criptografia automática falhará se o diretório de dados não existir ou se o cliente não puder descriptografar a chave com o KMS e a chave mestra do cliente especificados.

Os drivers oficiais compatíveis com o MongoDB 4.2+ têm requisitos específicos de idioma para especificar o UUID. Consulte a documentação do driver para obter a documentação completa sobre a implementação da criptografia no nível do campo do lado do cliente.

Exemplos

Criptografar vários campos automaticamente

Considere uma collection MedCo.patients onde cada documento tem a seguinte estrutura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

O campo a seguir contém informações de identificação pessoal (PII) que podem ser query:

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

O algoritmo de criptografia determinístico garante que a saída criptografada de um valor permaneça estática. Isso permite que query de um valor específico retornem resultados significativos ao custo de maior suscetibilidade à recuperação da análise de frequência. O algoritmo de criptografia determinístico atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

O campo a seguir contém informações de identificação pessoal (PII) protegidas por lei que podem nunca ser query:

  • medicalRecords

O algoritmo de criptografia aleatório garante que a saída criptografada de um valor seja sempre exclusiva. Isso impede que query de um valor de campo específico retornem resultados significativos, ao mesmo tempo em que oferece a maior proteção possível do conteúdo do campo. O algoritmo de criptografia aleatório atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

O esquema a seguir especifica regras de criptografia automática que atendem aos requisitos acima para a collection MedCo.patients :

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

As regras de criptografia automática acima marcam os campos passportId, bloodType, insurance.policyNumber, insurance.provider e medicalRecords para criptografia.

  • Os campos passportId, bloodType, insurance.policyNumber e provider exigem criptografia determinística usando a chave especificada.

  • O campo medicalRecords requer criptografia aleatória usando a chave especificada.

Embora a criptografia no nível do campo do lado do cliente não suporte a criptografia de elementos individuais da array, a criptografia aleatória suporta a criptografia de todo o campo da array em vez de elementos individuais no campo. As regras de criptografia automática do exemplo especificam a criptografia aleatória para o campo medicalRecords para criptografar toda a array. Se as regras de criptografia automática especificarem encrypt ou encryptMetadata dentro medicalRecords.items ou medicalRecords.additionalItems, a criptografia automática em nível de campo falhará e retornará um erro.

O MongoDB 4 oficial.2+ drivers compatíveis, mongosh e o 4.2 ou o shell mongo legado posterior exigem a especificação das regras de criptografia automática como parte da criação do objeto de conexão do banco de dados:

  • Para mongosh, utilize o construtor Mongo() para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para a schemaMap chave do parâmetro ClientSideFieldLevelEncryptionOptions . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.

  • Para o MongoDB 4 oficial.2+ drivers compatíveis, use o construtor de conexão de banco de dados específico do driver (por exemplo, MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia em nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Para todos os clientes, os keyVault e kmsProviders especificados para o parâmetro de criptografia do nível do campo do lado do cliente devem conceder acesso às diretório de dados especificadas nas regras de criptografia automática e à chave mestra do cliente usada para criptografar as diretório de dados.

Criptografar automaticamente vários campos com herança

Considere uma collection MedCo.patients onde cada documento tem a seguinte estrutura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

Os seguintes campo contêm dados privados que podem ser query:

  • passportId

  • bloodType

  • insurance.policyNumber

  • insurance.provider

O algoritmo de criptografia determinístico garante que a saída criptografada de um valor permaneça estática. Isso permite que query de um valor específico retornem resultados significativos ao custo de maior suscetibilidade à recuperação da análise de frequência. O algoritmo de criptografia determinístico atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

Os seguintes campo contêm dados privados que podem nunca ser query:

  • medicalRecords

O algoritmo de criptografia aleatório garante que a saída criptografada de um valor seja sempre exclusiva. Isso impede que query de um valor de campo específico retornem resultados significativos, ao mesmo tempo em que oferece a maior proteção possível do conteúdo do campo. O algoritmo de criptografia aleatório atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

O esquema a seguir especifica regras de criptografia automática que atendem aos requisitos de criptografia para a collection MedCo.patients :

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "encryptMetadata" : {
      "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
      "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    },
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

As regras de criptografia automática acima marcam os campos passportId, bloodType, insurance.policyNumber, insurance.provider e medicalRecords para criptografia.

  • Os campos passportId, bloodType, insurance.policyNumber e provider herdam suas configurações de criptografia do campo pai encryptMetadata . Especificamente, estes campos herdam os valores algorithm e keyId especificando a criptografia determinística com a chave de criptografia de dados especificada.

  • O campo medicalRecords requer criptografia aleatória usando a chave especificada. As opções encrypt substituem aquelas especificadas no campo encryptMetadata pai.

Embora a criptografia no nível do campo do lado do cliente não suporte a criptografia de elementos individuais da array, a criptografia aleatória suporta a criptografia de todo o campo da array em vez de elementos individuais no campo. As regras de criptografia automática do exemplo especificam a criptografia aleatória para o campo medicalRecords para criptografar toda a array. Se as regras de criptografia automática especificarem encrypt ou encryptMetadata dentro medicalRecords.items ou medicalRecords.additionalItems, a criptografia automática em nível de campo falhará e retornará um erro.

O MongoDB 4 oficial.2+ drivers compatíveis, mongosh e o 4.2 ou o shell mongo legado posterior exigem a especificação das regras de criptografia automática como parte da criação do objeto de conexão do banco de dados:

  • Para mongosh, utilize o construtor Mongo() para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para a schemaMap chave do parâmetro ClientSideFieldLevelEncryptionOptions . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.

  • Para o MongoDB 4 oficial.2+ drivers compatíveis, use o construtor de conexão de banco de dados específico do driver (por exemplo, MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia em nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Para todos os clientes, os keyVault e kmsProviders especificados para o parâmetro de criptografia do nível do campo do lado do cliente devem conceder acesso às diretório de dados especificadas nas regras de criptografia automática e à chave mestra do cliente usada para criptografar as diretório de dados.

← Criptografia automática no nível do campo do lado do cliente
Suporte de leitura/gravação com criptografia automática de nível de campo →

Nesta página