CSFLE 加密模式
Overview
注意
Enterprise 版功能
字段级加密的自动功能仅在 MongoDB Enterprise 4.2 或更高版本以及 MongoDB Atlas 4.2 或更高版本集群中可用。
加密模式包含用户指定的规则,用于确定必须加密哪些字段以及如何加密这些字段。 应用程序必须使用JSON schema 4草案 标准语法 的严格子集来指定自动加密规则 以及以下特定于加密的关键字:
对于MongoDB Shell,使用 Mongo()
构造函数创建数据库连接,其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。有关示例,请参阅连接到已启用客户端自动加密的集群。
对于官方 MongoDB 驱动程序,请使用特定于驱动程序的数据库连接构造函数 ( MongoClient
) 创建数据库连接,其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。要了解有关特定于 CSFLE 的MongoClient
选项的更多信息,请参阅mongo 客户端页面。
定义
encrypt
对象
"bsonType" : "object", "properties" : { "<fieldName>" : { "encrypt" : { "algorithm" : "<string>", "bsonType" : "<string>" | [ "<string>" ], "keyId" : [ <UUID> ] } } } 表示必须加密
<fieldName>
。encrypt
对象具有以下要求:encrypt
<fieldName>
对象中不能有任何同级字段。encrypt
必须是<fieldName>
对象的唯一子对象。encrypt
不能在items
或additionalItems
关键字的任何子模式中指定。 具体来说,自动客户端字段级加密不支持加密数组的单个元素。
encrypt
对象只能包含以下字段:在发出自动加密的读取或写入操作时,在
encrypt
对象中包含任何其他字段都会导致错误如果省略
keyId
或algorithm
,自动加密共享库会检查所有父字段,并尝试从指定该选项的最近的encryptMetadata
对象构造这些选项。bsonType
不能继承且可能为必需,具体取决于algorithm
的值。如果自动加密共享库无法使用为对象指定的字段和任何必需的
encryptMetadata
继承密钥来构造完整的encrypt
对象,则自动加密将失败并返回错误。
encrypt.algorithm
字符串
指示在加密
<fieldName>
的值时使用哪种加密算法。 仅支持以下算法:AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
有关加密算法的完整文档,请参阅字段和加密类型。
如果省略,自动加密共享库会检查所有父字段以查找包含
encryptMetadata.algorithm
密钥的最近祖先并继承该值。如果父项algorithm
不存在,则自动字段级加密将失败并返回错误。如果
encrypt.algorithm
或其继承值为AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
,则encrypt
对象需要encrypt.bsonType
字段。如果
encrypt.algorithm
或其继承值为AEAD_AES_256_CBC_HMAC_SHA_512-Random
,则encrypt
对象可能包含encrypt.bsonType
字段。
encrypt.bsonType
字符串 |字符串数组
正在加密的字段的BSON 类型。如果
encrypt.algorithm
为AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
,则为必填项。如果
encrypt.algorithm
或其继承值为AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
,则bsonType
必须指定为单一类型。bsonType
不支持以下任何使用确定性加密算法的 BSON 类型:double
decimal128
bool
object
array
如果
encrypt.algorithm
或其继承值为AED_AES_256_CBC_HMAC_SHA_512-Random
,则bsonType
为可选项,并可以指定支持的 bson 类型数组。对于array
或object
为bsonType
的字段,客户端会加密整个数组或对象,而不是加密它们的单个元素。encrypt.bsonType
无论 或其继承值如何, 都不encrypt.algorithm
支持以下类型:minKey
maxKey
null
undefined
encrypt.keyId
单个 UUID 的数组
用于加密字段值的数据加密密钥的 UUID。 UUID 是 BSON 二进制数据 子类型为
4
的元素。指定数组内的一个字符串。
如果省略,自动加密共享库会检查所有父字段以查找包含
encryptMetadata.keyId
密钥的最近祖先并继承该值。如果父项keyId
不存在,则自动字段级加密将失败并返回错误。keyId
或其继承值必须存在于指定为自动加密配置选项的一部分的密钥保管库集合中。如果指定的数据加密密钥不存在,则自动加密将会失败。官方 MongoDB 驱动程序对指定 UUID 有特定于语言的要求。有关实现客户端字段级加密的完整文档,请参阅驱动程序文档。
encryptMetadata
对象
{ "bsonType" : "object", "encryptMetadata" : { "algorithm" : "<string>", "keyId" : [ <UUID> ] }, "properties" : { "encrypt" : {} } } 定义嵌套在同级
properties
中的encrypt
对象可以继承的加密选项。如果encrypt
缺少支持加密所需的选项,则自动加密共享库会搜索所有父对象,以查找指定缺少选项的encryptMetadata
对象。encryptMetadata
必须在子模式中指定bsonType: "object"
。 不能将encryptMetadata
指定为items
或additionalItems
关键字的任何子模式。 Specifically, automatic Client-Side Field Level Encryption does not support encrypting individual elements of an array.encryptMetadata
对象只能包含以下字段。在发出自动加密的读取或写入操作时,在encrypt
对象中包含任何其他字段都会导致错误:
encryptMetadata.algorithm
字符串
用于加密特定字段的加密算法。如果
encrypt
对象缺少algorithm
字段,自动加密共享库将搜索所有父对象以查找指定encryptMetadata.algorithm
的encryptMetadata
对象。仅支持以下算法:
AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
有关加密算法的完整文档,请参阅字段和加密类型。
如果指定
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
,则任何继承该值的encrypt
对象都必须指定encrypt.bsonType
。
encryptMetadata.keyId
单个 UUID 的数组
数据加密密钥的 UUID。 UUID 是 BSON 二进制数据 子类型为
4
的元素。指定数组内的一个字符串。
如果
encrypt
对象缺少keyId
字段,自动加密共享库将搜索所有父对象以查找指定encryptMetadata.keyId
的encryptMetadata
对象。数据加密密钥必须存在于指定为自动加密配置选项一部分的密钥保管库集合中。 指定的配置选项还必须包括对用于创建数据密钥的密钥管理服务 (KMS)和客户主密钥 (CMK) 的适当访问权限。 如果数据加密密钥不存在,或者客户端无法使用指定的 KMS 和 CMK 解密密钥,则自动加密会失败。
官方 MongoDB 驱动程序对指定 UUID 有特定于语言的要求。有关实现客户端字段级加密的完整文档,请参阅驱动程序文档。
举例
加密模式 - 多个字段
考虑一个集合MedCo.patients
,其中每个文档都具有以下结构:
{ "fname" : "<String>", "lname" : "<String>", "passportId" : "<String>", "bloodType" : "<String>", "medicalRecords" : [ {<object>} ], "insurance" : { "policyNumber" : "<string>", "provider" : "<string>" } }
以下字段包含可能会被查询的个人身份信息 (PII):
passportId
bloodType
insurance.policyNumber
insurance.provider
确定性加密算法可保证值的加密输出保持静态。 这允许对特定值的查询返回有意义的结果,但代价是增加对频率分析恢复的敏感性。 因此,确定性加密算法同时满足数据的加密和可查询性要求。
以下字段包含可能永远无法查询的受法律保护的个人身份信息 (PII):
medicalRecords
随机加密算法可保证值的加密输出始终是唯一的。 这可以防止对特定字段值的查询返回有意义的结果,同时支持对字段内容进行尽可能高的保护。 因此,随机加密算法同时满足数据的加密和可查询性要求。
以下模式指定满足上述MedCo.patients
collection 要求的自动加密规则:
{ "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" } } } } } } }
上述自动加密规则将passportId
、 bloodType
、 insurance.policyNumber
、 insurance.provider
和medicalRecords
字段标记为要加密。
passportId
、bloodType
、insurance.policyNumber
和provider
字段需要使用指定密钥进行确定性加密。medicalRecords
字段需要使用指定密钥进行随机加密。
虽然 Queryable Encryption 不支持加密单个数组元素,但随机加密支持加密整个数组字段而不是字段中的单个元素。 示例自动加密规则为medicalRecords
字段指定随机加密,以加密整个数组。 如果自动加密规则在medicalRecords.items
或medicalRecords.additionalItems
中指定了encrypt
或encryptMetadata
,则自动字段级加密将失败并返回错误。
官方MongoDB驱动程序mongosh
和旧版 mongo
shell要求在创建数据库连接对象时指定自动加密规则:
对于
mongosh
,使用Mongo()
构造函数创建数据库连接。 将自动加密规则指定为AutoEncryptionOpts
参数的schemaMap
密钥。 有关完整示例,请参阅连接到已启用客户端自动加密的集群。对于官方 MongoDB 驱动程序,请使用特定于驱动程序的数据库连接构造函数 (
MongoClient
) 创建数据库连接,其中包含的自动加密规则作为可查询加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。
对于所有客户端,为 Queryable Encryption 参数指定的keyVault
和kmsProviders
必须授予对自动加密规则中指定的数据加密密钥以及用于加密数据加密密钥的客户主密钥的访问权限。
加密模式 — 具有继承性的多个字段
考虑一个集合MedCo.patients
,其中每个文档都具有以下结构:
{ "fname" : "<String>", "lname" : "<String>", "passportId" : "<String>", "bloodType" : "<String>", "medicalRecords" : [ {<object>} ], "insurance" : { "policyNumber" : "<string>", "provider" : "<string>" } }
以下字段包含可以查询的私有数据:
passportId
bloodType
insurance.policyNumber
insurance.provider
确定性加密算法可保证值的加密输出保持静态。 这允许对特定值的查询返回有意义的结果,但代价是增加对频率分析恢复的敏感性。 因此,确定性加密算法同时满足数据的加密和可查询性要求。
以下字段包含可能永远无法查询到的私有数据:
medicalRecords
随机加密算法可保证值的加密输出始终是唯一的。 这可以防止对特定字段值的查询返回有意义的结果,同时支持对字段内容进行尽可能高的保护。 因此,随机加密算法同时满足数据的加密和可查询性要求。
以下模式指定了满足MedCo.patients
collection 的自动加密规则:
{ "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" } } } } } } }
上述自动加密规则将passportId
、 bloodType
、 insurance.policyNumber
、 insurance.provider
和medicalRecords
字段标记为要加密。
passportId
、bloodType
、insurance.policyNumber
和provider
字段从父encryptMetadata
字段继承其加密设置。具体来说,这些字段继承algorithm
和keyId
值,这些值指定使用指定的数据加密密钥的确定性加密。medicalRecords
字段需要使用指定密钥进行随机加密。encrypt
选项会覆盖在父encryptMetadata
字段中指定的选项。
虽然 Queryable Encryption 不支持加密单个数组元素,但随机加密支持加密整个数组字段而不是字段中的单个元素。 示例自动加密规则为medicalRecords
字段指定随机加密,以加密整个数组。 如果自动加密规则在medicalRecords.items
或medicalRecords.additionalItems
中指定了encrypt
或encryptMetadata
,则自动字段级加密将失败并返回错误。
官方MongoDB驱动程序mongosh
和旧版 mongo
shell要求在创建数据库连接对象时指定自动加密规则:
对于
mongosh
,使用Mongo()
构造函数创建数据库连接。 将自动加密规则指定为AutoEncryptionOpts
参数的schemaMap
密钥。 有关完整示例,请参阅连接到已启用客户端自动加密的集群。对于官方 MongoDB 驱动程序,请使用特定于驱动程序的数据库连接构造函数 (
MongoClient
) 创建数据库连接,其中包含的自动加密规则作为可查询加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。
对于所有客户端,为 Queryable Encryption 参数指定的keyVault
和kmsProviders
必须授予对自动加密规则中指定的数据加密密钥以及用于加密数据加密密钥的客户主密钥的访问权限。
要了解有关 CMK 和密钥保管库集合的更多信息,请参阅密钥保管库页面。
要了解有关加密算法的更多信息,请参阅加密算法页面。
要了解有关特定于 CSFLE 的MongoClient
选项的更多信息,请参阅mongo 客户端页面。
加密模式 - 使用模式属性进行加密
您可以在加密模式中使用patternProperties
关键字,为名称与正则表达式匹配的所有字段定义加密规则。
考虑一个集合MedCo.patients
,其中每个文档都具有以下结构:
{ "fname" : "<string>", "lname" : "<string>", "passportId_PIIString" : "<string>", "bloodType_PIIString" : "<string>", "medicalRecords_PIIArray" : [ {<object>} ], "insurance" : { "policyNumber_PIINumber" : "<number>", "provider_PIIString" : "<string>" } }
包含私有数据的字段由字段名称末尾附加的“_PII <type>”标签标识。
passportId_PIIString
bloodType_PIIString
medicalRecords_PIIArray
insurance.policyNumber_PIINumber
insurance.provider_PIIString
您可以使用patternProperties
关键字来配置这些字段进行加密,而无需单独标识每个字段,也无需使用完整的字段名称。 为此,请使用正则表达式匹配所有以“_PII <type>”标签结尾的字段。
以下 JSON schema 使用patternProperties
和表达式来指定要加密的字段。
{ "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", }, }, }, }, }, }, }
上述自动加密规则将passportId_PIIString
、 bloodType_PIIString
、 medicalRecords_PIIArray
、 insurance.policyNumber_PIINumber
、 insurance.provider_PIIString
字段标记为加密。
要了解有关patternProperties
关键字的详情,请参阅patternProperties 关键字。