/ /

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

If keyId or algorithm are omitted, the Automatic Encryption Shared Library checks all parent fields and attempts to construct those options from the nearest encryptMetadata object that specifies the option. bsonType cannot be inherited and may be required depending on the value of 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 Campos e tipos de criptografia.

If omitted, the Automatic Encryption Shared Library checks all parent fields for the closest ancestor containing an encryptMetadata.algorithm key and inherits that value. If no parent algorithm exists, automatic field level encryption fails and returns an error.

If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, the encrypt object requires the encrypt.bsonType field.
If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Random, the encrypt object may include the encrypt.bsonType field.

encrypt.bsonType

Corda | Array de strings

The BSON type of the field being encrypted. Required if encrypt.algorithm is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.

If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType must specify a single type. bsonType does not support any of the following BSON types with the deterministic encryption algorithm:

double
decimal128
bool
object
array

If encrypt.algorithm or its inherited value is AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType is optional and may specify an array of supported bson types. For fields with bsonType of array or object, the client encrypts the entire array or object and not their individual elements.

encrypt.bsonType does not support the following types regardless of encrypt.algorithm or its inherited value:

minKey
maxKey
null
undefined

encrypt.keyId

string (ponteiro JSON) | Array de UUID único

If you use a UUID, specify one UUID inside an array. This is the UUID of the Data Encryption Key to use for encrypting field values. The UUID is a BSON binary data element of subtype 4.
Se você usar uma string, use um ponteiro JSON que faça referência a um nome alternativo de chave.

If omitted, the Automatic Encryption Shared Library checks all parent fields for the closest ancestor containing an encryptMetadata.keyId key and inherits that value. If no parent keyId exists, automatic field level encryption fails and returns an error.

The keyId or its inherited value must exist in the Key Vault collection specified as part of the automatic encryption configuration options. If the specified Data Encryption Key does not exist, automatic encryption fails.

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" : {}
  }
}

Defines encryption options which an encrypt object nested in the sibling properties may inherit. If an encrypt is missing an option required to support encryption, the Automatic Encryption Shared Library searches all parent objects to locate an encryptMetadata object that specifies the missing option.

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

The encryption algorithm to use to encrypt a given field. If an encrypt object is missing the algorithm field, the Automatic Encryption Shared Library searches all parent objects to locate an encryptMetadata object that specifies 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.

If specifying AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, any encrypt object inheriting that value must specify encrypt.bsonType.

encryptMetadata.keyId

Array de UUID único

The UUID of a Data Encryption Key. The UUID is a BSON binary data element of subtype 4.

Especifique uma string dentro da array.

If an encrypt object is missing the keyId field, the Automatic Encryption Shared Library searches all parent objects to locate an encryptMetadata object that specifies 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.

While Queryable Encryption does not support encrypting individual array elements, randomized encryption supports encrypting the entire array field rather than individual elements in the field. The example automatic encryption rules specify randomized encryption for the medicalRecords field to encrypt the entire array. If the automatic encryption rules specified encrypt or encryptMetadata within medicalRecords.items or medicalRecords.additionalItems, automatic field level encryption fails and returns an errors.

The official MongoDB drivers, mongosh, and the legacy mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

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.

The passportId, bloodType, insurance.policyNumber, and provider fields inherit their encryption settings from the parent encryptMetadata field. Specifically, these fields inherit the algorithm and keyId values specifying deterministic encryption with the specified Data Encryption Key.
O campo medicalRecords requer criptografia aleatória usando a chave especificada. As opções encrypt substituem aquelas especificadas no campo encryptMetadata pai.

The official MongoDB drivers, mongosh, and the legacy mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

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

Referência

Aplicação de esquema do lado do servidor CSFLE