Esquemas de criptografia CSFLE
Nesta página
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 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 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 objetoencrypt
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 theitems
oradditionalItems
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:Incluir qualquer outro campo no objeto
encrypt
resulta em erros ao emitir operações de leitura ou gravação criptografadas automaticamenteSe
keyId
oualgorithm
forem omitidos, a Biblioteca Compartilhada de Criptografia Automática verificará todos os campos principais e tentará construir essas opções a partir do objetoencryptMetadata
mais próximo que especifique a opção.bsonType
não pode ser herdado e pode ser necessário dependendo do valor doalgorithm
.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 herdadasencryptMetadata
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 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 nenhumalgorithm
pai, a criptografia automática em nível de campo falhará e retornará um erro.Se
encrypt.algorithm
ou seu valor herdado forAEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
, o objetoencrypt
exigirá o campoencrypt.bsonType
.Se
encrypt.algorithm
ou seu valor herdado forAEAD_AES_256_CBC_HMAC_SHA_512-Random
, o objetoencrypt
poderá incluir o campoencrypt.bsonType
.
encrypt.bsonType
Corda | Array de strings
O tipo de BSON do campo que está sendo criptografado. Obrigatório se
encrypt.algorithm
forAEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
.Se
encrypt.algorithm
ou seu valor herdado forAEAD_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 forAED_AES_256_CBC_HMAC_SHA_512-Random
,bsonType
é opcional e pode especificar uma array de tipos de bson suportados. Para campos combsonType
dearray
ouobject
, o cliente criptografa toda a array ou objeto e não seus elementos individuais.encrypt.bsonType
não suporta os seguintes tipos, independentemente deencrypt.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 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 nenhumkeyId
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ãoproperties
pode herdar. Se umencrypt
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 objetoencryptMetadata
que especifique a opção ausente.encryptMetadata
deve ser especificado em subesquemas combsonType: "object"
.encryptMetadata
não pode ser especificado para nenhum subesquema das palavras-chaveitems
ouadditionalItems
. 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 objetoencrypt
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 tiver o campoalgorithm
, a Biblioteca Compartilhada de Criptografia Automática pesquisará todos os objetos pai para localizar um objetoencryptMetadata
que 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 objetoencrypt
que herde esse valor deverá especificarencrypt.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 campokeyId
, a Biblioteca compartilhada de criptografia automática pesquisará todos os objetos pai para localizar um objetoencryptMetadata
que 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.
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.
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
eprovider
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 ofereça suporte à criptografia de elementos individuais da 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 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 construtorMongo()
para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para aschemaMap
chave do parâmetroAutoEncryptionOpts
. 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
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
eprovider
herdam suas configurações de criptografia do campoencryptMetadata
principal. Especificamente, esses campos herdam os valoresalgorithm
ekeyId
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çõesencrypt
substituem aquelas especificadas no campoencryptMetadata
pai.
Embora a criptografia no nível do campo do lado do cliente não ofereça suporte à criptografia de elementos individuais da 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 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 construtorMongo()
para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para aschemaMap
chave do parâmetroAutoEncryptionOpts
. 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.
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.