自动加密规则_MonogDB 中文网

MongoDB 中文手册

参考 > 安全 > 客户端字段级加密 > 自动客户端字段级加密 > 自动加密规则

在本页面

encrypt 架构关键字
encryptMetadata 架构关键字
例子

企业功能

字段级加密的自动功能仅在MongoDB 4.2 Enterprise和MongoDB Atlas 4.2集群中可用。

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

加密模式关键字 -指定加密当前字段时要使用的加密选项。
cryptoMetadata架构关键字 -指定可继承的加密选项。

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

复制

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

在taxid和taxid-short领域包含必须受到保护，免受未授权查看客户端上的个人身份信息（PII）和服务器。下列用于hr.employees集合的自动加密规则将taxid和 taxid-short字段标记为自动客户端字段级加密。官方的MongoDB 4.2兼容驱动程序和mongo配置有这些规则的4.2 Shell自动对taxid and 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 4.2 Shell，使用Mongo构造函数创建数据库连接，该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则。有关示例，请参阅连接到启用了客户端自动加密的MongoDB群集。
对于与MongoDB 4.2兼容的官方驱动程序，请使用特定于驱动程序的数据库连接构造函数（例如MongoClient）来创建数据库连接，该数据库连接包含作为客户端字段级加密配置对象一部分的自动加密规则。请参考驱动程序API参考，以获取更完整的文档和教程。

重要

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

`encrypt`模式关键字¶

"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，则 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`模式关键字¶

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

encryptMetadata¶

宾语

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

encryptMetadata必须在子方案中用指定。不能指定给或关键字的任何子模式。具体而言，自动客户端字段级加密不支持对数组的各个元素进行加密。bsonType: "object"encryptMetadataitemsadditionalItems

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

algorithm
keyId

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，其中每个文档具有以下结构：

复制

{
  "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收集要求的自动加密规则：

复制

{
  "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" : "string"
        }
      },
      "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字段指定了随机加密，以加密整个阵列。如果自动加密规则中指定encrypt或 encryptMetadata内medicalRecords.items或 medicalRecords.additionalItems，自动字段级加密失败并返回一个错误。

官方的MongoDB 4.2兼容驱动程序和mongo外壳程序要求在创建数据库连接对象的过程中指定自动加密规则：

对于MongoDB 4.2 Shell，请使用Mongo()构造函数创建数据库连接。schemaMap为ClientSideFieldLevelEncryptionOptions参数的密钥指定自动加密规则。有关完整的示例，请参阅连接到启用了客户端自动加密的MongoDB群集。
对于与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集合加密要求的自动加密规则：

复制

{
  "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" : "string"
        }
      },
      "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兼容驱动程序和mongo外壳程序要求在创建数据库连接对象的过程中指定自动加密规则：

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

MongoDB 中文手册

自动加密规则

encrypt模式关键字¶

encryptMetadata模式关键字¶

例子¶

自动加密多个字段¶

自动加密多个字段具有继承¶

`encrypt`模式关键字¶

`encryptMetadata`模式关键字¶