自动加密规则

在此页面上

encrypt Schema Keyword

encryptMetadata Schema Keyword
示例

MongoDB5.0 已于 10 月2024 结束生命周期。不再支持此版本的文档。要升级5.0 部署，请参阅 MongoDB6 。0 升级程序。

注意

Enterprise 版功能

字段级加密的自动功能仅在 MongoDB Enterprise 4.2 或更高版本以及 MongoDB Atlas 4.2 或更高版本集群中可用。

客户端字段级自动加密需要用户指定规则，以确定必须加密哪些字段以及如何加密这些字段。应用程序必须使用JSON4 schema 草案标准语法的严格子集和以下特定于加密的关键字来指定自动加密规则：

encrypt模式关键字— 指定加密当前字段时要使用的加密选项。
encryptMetadata模式关键字— 指定可继承的加密选项。

考虑一个MongoDB 数据库，其中hr数据库中的employees集合包含类似于以下内容的文档：

{
  "fname" : "Jo",
  "lname" : "Doe",
  "taxid" : "123-45-6789",
  "taxid-short" : "6789"
}

taxid和taxid-short字段包含个人身份信息 (PII)，必须保护这些信息免遭客户端和服务器上未经授权的查看。 hr.employees集合的以下自动加密规则将taxid和taxid-short字段标记为自动客户端字段级加密。官方MongoDB 4.2 + 兼容的驱动程序、 mongosh和4 。 2 或更高版本的使用这些规则配置的旧版mongo shell会自动加密 taxid 和 taxid-short 字段，以便对 hr.employees集合进行写入或读取操作。

{
  "hr.employees": {
    "bsonType": "object",
    "properties": {
      "taxid": {
        "encrypt": {
          "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
          "bsonType" : "string"
        }
      },
      "taxid-short": {
        "encrypt": {
          "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType": "string"
        }
      }
    }
  }
}

对于 MongoDB shell，使用 Mongo() 构造函数创建数据库连接，并将自动加密规则作为客户端字段级加密配置对象的一部分。有关示例，请参阅连接到启用了自动客户端加密的集群。
对于官方 MongoDB 驱动程序，请使用特定于驱动程序的数据库连接构造函数（例如 MongoClient ）创建数据库连接，其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。

重要

客户端字段级自动加密支持严格的JSON schema语法子集，仅用于定义加密行为。不要在自动加密规则中指定文档验证关键字。要定义文档验证规则，请配置服务器端模式验证。

`encrypt` Schema Keyword

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}

encrypt

对象

表示必须加密<fieldName> 。 encrypt对象具有以下要求：

encrypt <fieldName>对象中不能有任何同级字段。encrypt必须是<fieldName>对象的唯一子对象。
encrypt 不能在items或additionalItems关键字的任何子模式中指定。具体来说，自动客户端字段级加密不支持加密大量的单个元素。

encrypt对象只能包含以下字段：

algorithm
bsonType
keyId

在发出自动加密的读取或写入操作时，在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` Schema Keyword

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}

encryptMetadata

对象

定义嵌套在同级properties中的encrypt对象可以继承的加密选项。如果encrypt缺少支持加密所需的选项，自动加密共享库将搜索整个父对象树，以找到指定缺少选项的encryptMetadata对象。

encryptMetadata 必须在子模式中指定bsonType: "object" 。不能将encryptMetadata指定为items或additionalItems关键字的任何子模式。具体来说，自动客户端字段级加密不支持加密数组的单个元素。

encryptMetadata对象只能包含以下字段。在发出自动加密的读取或写入操作时，在encrypt对象中包含任何其他字段都会导致错误：

algorithm
keyId

encryptMetadata.algorithm

字符串

用于加密给定字段的加密算法。如果encrypt 对象缺少字段，自动加密共享库将搜索整个父对象树，以找到指定algorithm 的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。 UUID 是 BSON 二进制数据子类型为4 的元素。

指定数组内的一个字符串。

如果encrypt 对象缺少字段，则自动加密共享库会搜索整个父对象树，以找到指定keyId 的encryptMetadata encryptMetadata.keyId对象。

数据加密密钥必须存在于作为自动加密配置选项的一部分指定的密钥保管库中。指定的配置选项还必须包括对用于创建数据密钥的KMS ( KMS )和客户主密钥(集合扫描 ) 的适当访问权限。如果数据加密密钥不存在，或者客户端无法使用指定的KMS和集合扫描解密密钥，则自动加密会失败。

官方 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字段需要使用指定密钥进行随机加密。

虽然客户端字段级加密不支持加密单个大量元素，但随机加密支持加密整个大量字段，而不是字段中的单个元素。示例自动加密规则为medicalRecords字段指定随机加密，以加密整个大量。如果自动加密规则在medicalRecords.items或medicalRecords.additionalItems中指定了encrypt或encryptMetadata ，则自动字段级加密将失败并返回错误。

官方MongoDB 4.2+ 兼容驱动程序、 mongosh和 4.2 或更高版本的旧版mongo shell要求在创建数据库连接对象时指定自动加密规则：

对于mongosh ，使用Mongo()构造函数创建数据库连接。将自动加密规则指定为ClientSideFieldLevelEncryptionOptions参数的schemaMap密钥。有关完整示例，请参阅连接到已启用客户端自动加密的集群。
对于官方 MongoDB 4.2 + 兼容驱动程序，请使用特定于驱动程序的数据库连接构造函数（例如 MongoClient ）创建数据库连接，其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。

对于所有客户端，为客户端字段级加密参数指定的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字段中指定的选项。

官方MongoDB 4.2+ 兼容驱动程序、 mongosh和 4.2 或更高版本的旧版mongo shell要求在创建数据库连接对象时指定自动加密规则：

对于mongosh ，使用Mongo()构造函数创建数据库连接。将自动加密规则指定为ClientSideFieldLevelEncryptionOptions参数的schemaMap密钥。有关完整示例，请参阅连接到已启用客户端自动加密的集群。
对于官方 MongoDB 4.2 + 兼容驱动程序，请使用特定于驱动程序的数据库连接构造函数（例如 MongoClient ）创建数据库连接，其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。

后退

自动客户端字段级加密

来年

具有自动字段级加密的读/写支持

注意

Enterprise 版功能

重要

encrypt Schema Keyword

encryptMetadata Schema Keyword

示例

自动加密多个字段

通过继承自动加密多个字段

`encrypt` Schema Keyword

`encryptMetadata` Schema Keyword