Esquemas de criptografia CSFLE

Nesta página

Visão geral

Definição
Exemplos
Esquema de criptografia - Vários campos
Esquema de criptografia - Vários campos com herança
Esquema de criptografia - Criptografar com propriedades de padrão

A Queryable Encryption está geralmente disponível (GA) no MongoDB 7.0. Para saber mais, consulte Criptografia consultável.

Visão geral

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.

Os esquemas de criptografia contêm regras especificadas pelo usuário que identificam 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 JSON schema 4 sintaxe padrão do{4 } e as seguintes palavras-chave específicas de criptografia:

Criptografar especifica as opções de criptografia a serem usadas ao criptografar o campo atual.
Criptografar metadados especifica opções de criptografia hereditárias.

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

Para os drivers oficiais do MongoDB, use o construtor de conexão de banco de dados específico do driver (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 Criptografia de nível de campo do lado do cliente. Para saber mais sobre as opções de MongoClient específicas do CSFLE, consulte a página do cliente mongo .

Importante

Não especifique palavras-chave de validação do documento em seu esquema de 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.

Definição

encrypt

Objeto

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

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 cannot be specified within any subschema of the items or additionalItems keywords. Especificamente, a criptografia automática em nível de 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:

algorithm
bsonType
keyId

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 verificará todos os 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 não puder construir o objeto encrypt completo usando os campos especificados para o objeto e quaisquer chaves encryptMetadata herdadas necessá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 Campos e tipos de criptografia.

Se omitido, a Biblioteca Compartilhada verificará todos os campos pai em busca do ancestral mais próximo que contenha uma chave encryptMetadata.algorithm 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 BSON types com o algoritmo de criptografia determinística:

double
decimal128
bool
object
array

Se encrypt.algorithm ou seu valor herdado for AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType é opcional e pode 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 verificará todos os campos pai em busca do ancestral mais próximo que contenha uma chave encryptMetadata.keyId 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 na Key Vault collection especificada 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 do MongoDB têm requisitos específicos da linguagem para especificar a UUID. Consulte a documentação do driver para ver a documentação completa sobre a implementação da criptografia no nível do campo no lado do cliente.

encryptMetadata

Objeto

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

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 pesquisará todos os 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 em nível de 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:

algorithm
keyId

encryptMetadata.algorithm

String

O algoritmo de criptografia a ser usado para criptografar um determinado campo. Se um objeto encrypt estiver faltando no campo algorithm , a Biblioteca Compartilhada pesquisará todos os objetos pai para localizar um objeto encryptMetadata que especifica 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 Campos e tipos 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 estiver faltando no campo keyId , a Biblioteca Compartilhada pesquisará todos os objetos pai para localizar um objeto encryptMetadata que especifica encryptMetadata.keyId.

O diretório de dados deve existir na collection de cofre de chaves especificada 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.

Exemplos

Esquema de criptografia - Vários campos

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.

Os drivers oficiais compatíveis com o MongoDB 4.2+, o mongosh e o shell legado do mongo 4.2 ou posterior exigem que se especifique as regras de criptografia ao criar o 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 AutoEncryptionOpts . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers oficiais compatíveis com o MongoDB 4.2+, use o construtor de conexão de banco de dados específico do driver ( 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 Criptografia de Nível de Campo do Lado do Cliente. Defer to the driver API reference for more complete documentation and tutorials.

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

Esquema de criptografia - 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

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

medicalRecords

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 encryptMetadata principal. Especificamente, esses campos herdam os valores algorithm e keyId que especificam 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.

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 AutoEncryptionOpts . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers oficiais compatíveis com o MongoDB 4.2+, use o construtor de conexão de banco de dados específico do driver ( 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 Criptografia de Nível de Campo do Lado do Cliente. Defer to the driver API reference for more complete documentation and tutorials.

Para saber mais sobre sua collection de chave mestra do cliente e cofre de chaves, consulte a página de collection de cofre de chaves .

Para saber mais sobre algoritmos de criptografia, consulte a página Algoritmos de criptografia .

Para saber mais sobre as opções MongoClient específicas do CSFLE, consulte a página do cliente mongo .

Esquema de criptografia - Criptografar com propriedades de padrão

Você pode usar a palavra-chave patternProperties em seu esquema de criptografia para definir regras de criptografia para todos os campos com nomes que correspondam a uma expressão regular.

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

{
  "fname" : "<string>",
  "lname" : "<string>",
  "passportId_PIIString" : "<string>",
  "bloodType_PIIString" : "<string>",
  "medicalRecords_PIIArray" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber_PIINumber" : "<number>",
    "provider_PIIString" : "<string>"
  }
}

Os campos que contêm dados privados são identificados por uma tag "_PII<type>" anexada ao final do nome do campo.

passportId_PIIString
bloodType_PIIString
medicalRecords_PIIArray
insurance.policyNumber_PIINumber
insurance.provider_PIIString

Você pode usar a palavra-chave patternProperties para configurar esses campos para criptografia, sem identificar cada campo individualmente e sem usar o nome completo do campo. Para isso, use expressões regulares que correspondam a todos os campos que terminam com a marcação "_PII<type>".

O JSON schema a seguir usa patternProperties e expressões regulares para especificar quais campos criptografar.

{
  "MedCo.patients": {
  "bsonType": "object",
  "patternProperties": {
    "_PIIString$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "string",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
      },
    },
    "_PIIArray$": {
      "encrypt": {
        "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
        "bsonType": "array",
        "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
      },
    },
    "insurance": {
      "bsonType": "object",
      "patternProperties": {
        "_PIINumber$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "int",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
        "_PIIString$": {
          "encrypt": {
            "keyId": [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
            "bsonType": "string",
            "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          },
        },
      },
    },
  },
  },
}

As regras de criptografia automática acima marcam os campos passportId_PIIString, bloodType_PIIString, medicalRecords_PIIArray, insurance.policyNumber_PIINumber, insurance.provider_PIIString para criptografia.

Para saber mais sobre a palavra-chave patternProperties , consulte a palavra- chave padrãoPropriedades.

← Limitações de CSFLE

Aplicação de esquema do lado do servidor CSFLE →