/ /

Criptografia no nível de campo do cliente

Referência

Página inicial do Docs

Desenvolvimento

Criptografia em execução

Criptografia no nível de campo do cliente

Referência

Esquemas de criptografia CSFLE

Visão geral

Observação

Funcionalidade de empresas

O recurso automático da criptografia em nível de campo só é compatível com clusters do MongoDB Enterprise 6.0 ou posterior e do MongoDB Atlas 6.0 ou posterior.

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 sintaxe padrão do JSON schema rascunho 4 e as seguintes palavras-chave específicas da 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 shell do MongoDB, use o construtor Mongo() para criar a conexão de banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração Client-Side Field Level Encryption. Consulte Conectar-se a um cluster com criptografia automática do lado do cliente habilitada para ver um exemplo.

Para os drivers oficiais do MongoDB , use o construtor de conexão de banco de dados de dados específico do driver (MongoClient) para criar a conexão do banco de dados 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 de esquema em seu esquema de criptografia

Não especifique palavras-chave de validação de esquema nas regras de criptografia automática . Para definir regras de validação de esquema , configure 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 forem algorithm omitidos, a Biblioteca Compartilhada de Criptografia Automática verificará todos os campos pai e tentará construir essas opções a partir do objeto mais próximo encryptMetadata que especifica a opção. não podebsonType ser herdado e pode ser necessário dependendo do valor algorithm de.

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 Campos e tipos de criptografia.

Se omitido, a Biblioteca compartilhada de criptografia automática verifica todos os campos pai em busca do ancestral mais próximo que contém uma encryptMetadata.algorithm chave e herda esse valor. Se não houver algorithm pai, a criptografia automática em nível de campo falhará e retornará um erro.

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

encrypt.bsonType

Corda | Array de strings

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

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

double
decimal128
bool
object
array

Se ou seu valor encrypt.algorithm herdado AED_AES_256_CBC_HMAC_SHA_512-Random for, bsonType será opcional e poderá especificar uma array de tipos de bson suportados. Para campos com bsonType de array objectou, 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

string (ponteiro JSON) | Array de UUID único

Se você utilizar um UUID, especifique um UUID dentro de uma array. Esse é o UUID da chave de criptografia de dados a ser usada para criptografar os valores de campo . O UUID é um elemento de dados binários BSON do 4 subtipo.
Se você usar uma string, use um ponteiro JSON que faça referência a um nome alternativo de chave.

Se omitido, a Biblioteca compartilhada de criptografia automática verifica todos os campos pai em busca do ancestral mais próximo que contém uma encryptMetadata.keyId chave e herda esse valor. Se não houver keyId pai, a criptografia automática em nível de campo falhará e retornará um erro.

O ou keyId seu valor herdado deve existir na collection Key Vault especificada como parte das opções de configuração de criptografia automática . Se a chave de criptografia 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 encrypt objeto aninhado no ir properties pode herdar. Se um encrypt estiver sem uma opção necessária para oferecer suporte à criptografia, a Biblioteca Compartilhada de Criptografia Automática pesquisar todos os objetos pai para localizar um objeto que especifique a opção encryptMetadata 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 objetoencryptestiver faltando o campoalgorithm, a Biblioteca Compartilhada de Criptografia Automática pesquisar todos os objetos pai para localizar um objetoencryptMetadataque especifiqueencryptMetadata.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 elemento de dados binários BSON do 4 subtipo.

Especifique uma string dentro da array.

Se um objetoencryptestiver faltando o campokeyId, a Biblioteca Compartilhada de Criptografia Automática pesquisar todos os objetos pai para localizar um objetoencryptMetadataque especifiqueencryptMetadata.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 Queryable Encryption não ofereça suporte à criptografia de elementos individuais de array, a encryption random oferece suporte à criptografia de todo o campo de array em vez de elementos individuais no campo . As regras de criptografia automática do exemplo especificam a criptografia aleatória para o medicalRecords campo para criptografar toda a array. Se as regras de criptografia automática encrypt especificarem ou encryptMetadata dentro medicalRecords.items de medicalRecords.additionalItems ou, a criptografia automática em nível de campo falhará e retornará um erro.

Os drivers oficiais do MongoDB ,, emongosh o mongo shell legado 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 AutoEncryptionOpts . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers oficiais do MongoDB , use o construtor de conexão de banco de dados de dados específico do driver (MongoClient) para criar a conexão do banco de dados de dados com as regras de criptografia automática incluídas como parte do objeto de configuração Queryable Encryption . Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Para todos os clientes, o keyVault e o kmsProviders especificados para o parâmetro Queryable Encryption devem conceder acesso às Chaves de criptografia de dados especificadas nas regras de criptografia automática e à Chave mestre do cliente usada para criptografar as Chaves de criptografia 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 algorithm e keyId valores 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.

Os drivers oficiais do MongoDB ,, emongosh o mongo shell legado 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 AutoEncryptionOpts . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers oficiais do MongoDB , use o construtor de conexão de banco de dados de dados específico do driver (MongoClient) para criar a conexão do banco de dados de dados com as regras de criptografia automática incluídas como parte do objeto de configuração Queryable Encryption . Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

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.

Voltar

Limitações de CSFLE

Aplicação de esquema do lado do servidor CSFLE