CSFLE 加密模式

在此页面上

Overview

定义
举例
加密模式 - 多个字段
加密模式 — 具有继承性的多个字段
加密模式 - 使用模式属性进行加密

可查询加密在 MongoDB 7中正式可用 (GA)。 0 。要了解详情，请参阅可查询加密。

Overview

注意

Enterprise 版功能

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

加密模式包含用户指定的规则，用于确定必须加密哪些字段以及如何加密这些字段。应用程序必须使用JSON schema 4草案标准语法的严格子集来指定自动加密规则以及以下特定于加密的关键字：

Encrypt指定加密当前字段时要使用的加密选项。
加密元数据指定可继承的加密选项。

对于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对象只能包含以下字段：

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

对象

{
  "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对象中包含任何其他字段都会导致错误：

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)和客户主密钥 (CMK) 的适当访问权限。如果数据加密密钥不存在，或者客户端无法使用指定的 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()构造函数创建数据库连接。将自动加密规则指定为AutoEncryptionOpts参数的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()构造函数创建数据库连接。将自动加密规则指定为AutoEncryptionOpts参数的schemaMap密钥。有关完整示例，请参阅连接到已启用客户端自动加密的集群。
对于官方 MongoDB 4.2+ 兼容驱动程序，请使用特定于驱动程序的数据库连接构造函数 ( MongoClient ) 创建数据库连接，其中包含的自动加密规则作为客户端字段级加密配置对象的一部分。请参阅驱动程序 API 参考以获取更完整的文档和教程。

要了解有关 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 关键字。

后退

CSFLE 限制

来年

模式执行

CSFLE 加密模式.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Overview

注意

Enterprise 版功能

重要

不要在加密模式中指定文档验证关键字

定义

举例

加密模式 - 多个字段

加密模式 — 具有继承性的多个字段

加密模式 - 使用模式属性进行加密

CSFLE 加密模式