/ /

Referência

Página inicial do Docs

/ /

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 das 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 MongoDB shell, use o construtor Mongo() 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 Client-Side Field Level Encryption . 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 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 algorithm forem omitidos, a Biblioteca Compartilhada de Criptografia Automática verificará todos os campos principais e tentará construir essas opções a partir do objeto encryptMetadata mais próximo que especifique a opção. bsonType não pode ser herdado e pode ser necessário dependendo do valor do 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.

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 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 elemento de dados binários BSON do subtipo 4.

Especifique uma string dentro da array.

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 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 coleção 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 opções de criptografia que um objeto encrypt aninhado no irmão properties pode herdar. Se um encrypt não tiver uma opção necessária para suportar a criptografia, a Biblioteca Compartilhada de Criptografia Automática 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 não tiver o campo algorithm, a Biblioteca Compartilhada de Criptografia Automática pesquisará todos os 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 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 subtipo 4.

Especifique uma string dentro da array.

Se um objeto encrypt estiver faltando no campo keyId, a Biblioteca compartilhada de criptografia automática pesquisará todos os objetos pai para localizar um objeto encryptMetadata que especifique 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 Queryable Encryption não ofereça suporte à criptografia de elementos individuais de array, a criptografia aleatória oferece suporte à 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 do MongoDB, mongosh e o shell mongo 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 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.

Os drivers oficiais do MongoDB, mongosh e o shell mongo 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