参考 > 安全 > 客户端字段级加密 > 自动客户端字段级加密 > 自动加密规则
企业功能
字段级加密的自动功能仅在MongoDB 4.2 Enterprise和MongoDB Atlas 4.2集群中可用。
自动客户端字段级加密需要用户指定的规则,这些规则标识必须加密哪些字段以及如何加密这些字段。应用程序必须使用JSON Schema Draft 4标准语法的严格子集和以下特定于加密的关键字来指定自动加密规则:
考虑一个MongoDB数据库,其中数据库中的employees
集合
hr
包含类似于以下内容的文档:
在taxid
和taxid-short
领域包含必须受到保护,免受未授权查看客户端上的个人身份信息(PII)和服务器。下列用于hr.employees
集合的自动加密规则将taxid
和
taxid-short
字段标记为自动客户端字段级加密。官方的MongoDB 4.2兼容驱动程序和mongo
配置有这些规则的4.2 Shell自动对taxid
and taxid-short
字段进行加密,以对hr.employees
集合进行写入或读取操作
。
Mongo
构造函数创建数据库连接,该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则
。有关
示例,请参阅连接到启用了客户端自动加密的MongoDB群集。MongoClient
)来创建数据库连接,该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则。请参考驱动程序API参考,以获取更完整的文档和教程。重要
自动客户端字段级加密支持JSON模式语法的一个子集,严格只定义加密行为。千万 不能在自动加密规则指定文档验证关键字。要定义文档验证规则,请配置 服务器端模式验证。
encrypt
模式关键字¶encrypt
¶宾语
表示<fieldName>
必须加密。该encrypt
对象具有以下要求:
encrypt
对象中不能有任何同级字段
<fieldName>
。encrypt
必须是该<fieldName>
对象的唯一子代
。encrypt
不能在items
或additionalItems
关键字的任何子模式中指定
。具体而言,自动客户端字段级加密不支持对数组的各个元素进行加密。该encrypt
对象可以包含只以下字段:
encrypt
在发布自动加密的读取或写入操作时,将任何其他字段包含到对象中会导致错误
如果省略keyId
或
algorithm
,则
mongocryptd将检查父字段的完整树,并尝试从encryptMetadata
指定选项的最近对象构造这些
选项。bsonType
无法继承,根据的值可能是必需的
algorithm
。
如果mongocryptd
无法encrypt
使用为对象指定的字段和任何必需的encryptMetadata
继承密钥构造完整的对象
,则自动加密将失败并返回错误。
encrypt.
algorithm
¶串
表示加密的值时要使用的加密算法<fieldName>
。仅支持以下算法
:
AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic
有关加密算法的完整文档,请参阅“ 加密算法”。
如果省略,则mongocryptd会在父字段的整个树中检查最近的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
javascriptWithScope
如果encrypt.algorithm
或其继承的值是
AED_AES_256_CBC_HMAC_SHA_512-Random
,bsonType
则是可选的,并且可以指定支持的bson类型的数组。对于具有字段bsonType
的array
或object
,客户端加密整个阵列或对象,而不是他们的单个元件。
encrypt.bsonType
它不支持以下类型,无论encrypt.algorithm
或继承值:
minKey
maxKey
null
undefined
encrypt.
keyId
¶UUID数组
用于加密字段值的数据加密密钥的UUID。在数组内指定一个字符串。UUID是子类型的BSON
二进制数据元素
4
。
如果省略,则mongocryptd会在父字段的整个树中检查最近的
encryptMetadata.keyId
键并继承该值。如果不keyId
存在父
级,则自动字段级加密将失败并返回错误。
该keyId
值或继承值必须
存在于指定的自动加密部分的关键库
的配置选项。如果指定的数据加密密钥不存在,则自动加密失败。
兼容MongoDB 4.2的官方驱动程序对指定UUID具有特定于语言的要求。请参阅 驱动程序文档, 以获取有关实现客户端字段级加密的完整文档。
encryptMetadata
模式关键字¶encryptMetadata
¶宾语
定义encrypt
嵌套在同级对象中的对象properties
可以继承的加密选项。如果
encrypt
缺少支持加密所需的选项,请mongocryptd
搜索整个父对象树以找到encryptMetadata
指定缺少选项的对象。
encryptMetadata
必须在子方案中用指定。不能指定给或关键字的任何子模式。具体而言,自动客户端字段级加密不支持对数组的各个元素进行加密。bsonType:
"object"
encryptMetadata
items
additionalItems
该encryptMetadata
对象可以包含只以下字段。encrypt
在发出自动加密的读取或写入操作时,将任何其他字段包含到对象中会导致错误:
encryptMetadata.
algorithm
¶串
用于加密给定字段的加密算法。如果某个
encrypt
对象缺少该
algorithm
字段,则mongocryptd
搜索整个父对象树以找到encryptMetadata
指定的
对象
encryptMetadata.algorithm
。
仅支持以下算法:
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。如果某个
encrypt
对象缺少该
keyId
字段,则mongocryptd
搜索整个父对象树以找到encryptMetadata
指定的对象encryptMetadata.keyId
。
UUID是
子类型的BSON 二进制数据元素4
。
数据加密密钥必须存在于作为自动加密配置选项一部分指定的密钥库中。指定的配置选项还必须包括对用于创建数据密钥的密钥管理服务(KMS)和客户主密钥(CMK)的适当访问。如果数据加密密钥不存在,或者客户端无法使用指定的KMS和CMK解密密钥,则自动加密将失败。
兼容MongoDB 4.2的官方驱动程序对指定UUID具有特定于语言的要求。请参阅 驱动程序文档, 以获取有关实现客户端字段级加密的完整文档。
考虑一个集合MedCo.patients
,其中每个文档具有以下结构:
以下字段包含可能要查询的个人身份信息(PII):
passportId
bloodType
insurance.policyNumber
insurance.provider
的确定性 加密算法保证的一个值的加密输出保持静止。这允许查询特定值以增加对频率分析恢复的敏感性为代价返回有意义的结果。因此,确定性加密算法可以满足数据的加密和可查询性要求。
以下字段包含受法律保护的个人身份信息(PII),这些信息可能永远不会被查询:
medicalRecords
该随机加密算法保证值的加密输出始终是唯一的。这样可以防止对特定字段值的查询返回有意义的结果,同时支持对字段内容的最高保护。因此,随机加密算法可以满足数据的加密和可查询性要求。
以下架构指定了满足上述MedCo.patients
收集要求的自动加密规则:
上述自动加密规则标记passportId
,
bloodType
,insurance.policyNumber
,insurance.provider
,和medicalRecords
用于加密的字段。
passportId
,bloodType
,insurance.policyNumber
,和
provider
字段要求使用指定的密钥加密确定性。medicalRecords
字段要求使用指定的密钥进行随机加密。尽管客户端字段级加密不支持加密单个数组元素,但随机加密支持加密
整个数组字段而不是字段中的单个元素。自动加密规则示例为medicalRecords
字段指定了随机加密,
以加密整个阵列。如果自动加密规则中指定encrypt
或
encryptMetadata
内medicalRecords.items
或
medicalRecords.additionalItems
,自动字段级加密失败并返回一个错误。
官方的MongoDB 4.2兼容驱动程序和mongo
外壳程序
要求在创建数据库连接对象的过程中指定自动加密规则:
Mongo()
构造函数创建数据库连接。schemaMap
为ClientSideFieldLevelEncryptionOptions参数的密钥
指定自动加密规则。有关
完整的示例,请参阅
连接到启用了客户端自动加密的MongoDB群集。MongoClient
)来创建数据库连接,该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则。请参考驱动程序API参考,以获取更完整的文档和教程。对于所有客户端,客户端字段级加密参数中指定的keyVault
和必须授予对自动加密规则中指定的数据加密密钥和用于加密数据加密密钥的客户主密钥的访问权限。kmsProviders
考虑一个集合MedCo.patients
,其中每个文档具有以下结构:
以下字段包含可以查询的私有数据:
passportId
bloodType
insurance.policyNumber
insurance.provider
的确定性 加密算法保证的一个值的加密输出保持静止。这允许查询特定值以增加对频率分析恢复的敏感性为代价返回有意义的结果。因此,确定性加密算法可以满足数据的加密和可查询性要求。
以下字段包含可能永远不会查询的私有数据:
medicalRecords
该随机加密算法保证值的加密输出始终是唯一的。这样可以防止对特定字段值的查询返回有意义的结果,同时支持对字段内容的最高保护。因此,随机加密算法可以满足数据的加密和可查询性要求。
以下架构指定了满足MedCo.patients
集合加密要求的自动加密规则:
上述自动加密规则标记passportId
,
bloodType
,insurance.policyNumber
,insurance.provider
,和medicalRecords
用于加密的字段。
passportId
,bloodType
,insurance.policyNumber
,和
provider
领域从父继承加密设置
encryptMetadata
字段。具体而言,这些字段继承algorithm
和keyId
值,这些值和
值使用指定的数据加密密钥指定确定性加密。medicalRecords
字段要求使用指定的密钥进行随机加密。这些encrypt
选项将覆盖在父encryptMetadata
字段中指定的选项。尽管客户端字段级加密不支持加密单个数组元素,但随机加密支持加密
整个数组字段而不是字段中的单个元素。自动加密规则示例为medicalRecords
字段指定了随机加密,
以加密整个阵列。如果自动加密规则中指定encrypt
或
encryptMetadata
内medicalRecords.items
或
medicalRecords.additionalItems
,自动字段级加密失败并返回一个错误。
官方的MongoDB 4.2兼容驱动程序和mongo
外壳程序
要求在创建数据库连接对象的过程中指定自动加密规则:
Mongo()
构造函数创建数据库连接。schemaMap
为ClientSideFieldLevelEncryptionOptions参数的密钥
指定自动加密规则。有关
完整的示例,请参阅
连接到启用了客户端自动加密的MongoDB群集。MongoClient
)来创建数据库连接,该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则。请参考驱动程序API参考,以获取更完整的文档和教程。对于所有客户端,客户端字段级加密参数中指定的keyVault
和必须授予对自动加密规则中指定的数据加密密钥和用于加密数据加密密钥的客户主密钥的访问权限。kmsProviders