Automatic Encryption Rules自动加密规则

encrypt Schema Keyword架构关键字

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

encrypt

Object

Indicates that <fieldName> must be encrypted. 指示<fieldName>必须加密。The encrypt object has the following requirements:encrypt对象具有以下要求：

• encrypt cannot have any sibling fields in the <fieldName> object. <fieldName>对象中encrypt不能有任何同级字段。encrypt must be the only child of the <fieldName> object.必须是<fieldName>对象的唯一子级。
• encrypt cannot be specified within any subschema of the items or additionalItems keywords. 不能在items或additionalItems关键字的任何子模式中指定。Specifically, automatic client-side field level encryption does not support encrypting individual elements of an array.具体来说，自动客户端字段级加密不支持对数组的各个元素进行加密。

The encrypt object can contain only the following fields:encrypt对象只能包含以下字段：

• algorithm
• bsonType
• keyId

Including any other field to the encrypt object results in errors when issuing automatically encrypted read or write operations在发出自动加密的读或写操作时，在encrypt对象中包含任何其他字段都会导致错误

If keyId or algorithm are omitted, the mongocryptd checks the full tree of parent fields and attempts to construct those options from the nearest encryptMetadata object that specifies the option. 如果省略了keyId或algorithm，mongocryptd将检查父字段的完整树，并尝试从指定选项的最近的encryptMetadata对象构造这些选项。bsonType cannot be inherited and may be required depending on the value of algorithm.不能继承，可能需要根据algorithm的值而定。

If mongocryptd cannot construct the full encrypt object using the fields specified to the object and any required encryptMetadata-inherited keys, automatic encryption fails and returns an error.如果mongocrypted无法使用指定给对象的字段和任何必需的encryptMetadata继承的密钥构造完全encrypt 对象，则自动加密失败并返回错误。

encrypt.algorithm

String

Indicates which encryption algorithm to use when encrypting values of <fieldName>. 指示加密<fieldName>值时要使用的加密算法。Supports the following algorithms only:仅支持以下算法：

• AEAD_AES_256_CBC_HMAC_SHA_512-Random
• AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

For complete documentation on the encryption algorithms, see Encryption Algorithms.有关加密算法的完整文档，请参阅加密算法。

If omitted, mongocryptd checks the full tree of parent fields for the nearest encryptMetadata.algorithm key and inherits that value. If no parent algorithm exists, automatic field level encryption fails and returns an error.

• If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, the encrypt object requires the encrypt.bsonType field.
• If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Random, the encrypt object may include the encrypt.bsonType field.

encrypt.bsonType

String | Array of Strings

The BSON type of the field being encrypted. Required if encrypt.algorithm is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.要加密的字段的BSON类型。如果encrypt.algorithm为AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，则需要。

If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonTypemust specify a single type. 如果encrypt.algorithm或其继承值为AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，则bsonType必须指定单个类型。bsonType does notsupport any of the following BSON types with the deterministic encryption algorithm:bsonType不支持具有确定性加密算法的以下任何BSON类型：

• double
• decimal128
• bool
• object
• array
• javascriptWithScope (Deprecated)

If encrypt.algorithm or its inherited value is AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType is optional and may specify an array of supported bson types. 如果encrypt.algorithm或其继承值为AED_AES_256_CBC_HMAC_SHA_512-Random，则bsonType是可选的，可以指定受支持的bson类型的数组。For fields with bsonType of array or object, the client encrypts the entire array or object and not their individual elements.对于bsonType为array或object的字段，客户端将加密整个数组或对象，而不是其单个元素。

encrypt.bsonType does not support the following types regardless of encrypt.algorithm or its inherited value:无论encrypt.algorithm或其继承值如何，都不支持以下类型：

• minKey
• maxKey
• null
• undefined

encrypt.keyId

Array of single UUID单个UUID数组

The UUID of the data encryption key to use for encrypting field values. 用于加密字段值的数据加密密钥的UUID。The UUID is a BSON binary data element of subtype 4.UUID是子类型4的BSON二进制数据元素。

Specify one string inside the array.在数组中指定一个字符串。

If omitted, mongocryptd checks the full tree of parent fields for the nearest encryptMetadata.keyId key and inherits that value. 如果省略，mongocryptd将检查父字段的完整树中最近的encryptMetadata.keyId密钥，并继承该值。If no parent keyId exists, automatic field level encryption fails and returns an error.如果不存在父keyId，则自动字段级加密失败并返回错误。

The keyId or its inherited value mustexist in the key vault specified as part of the auto encryption configuration options. If the specified data encryption key does not exist, automatic encryption fails.如果指定的数据加密密钥不存在，则自动加密失败。

Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. 官方MongoDB 4.2+兼容驱动程序对指定UUID有特定语言的要求。Defer to the driver documentation for complete documentation on implementing client-side field level encryption.

encryptMetadata Schema Keyword架构关键字

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

encryptMetadata

Object

Defines encryption options which an encrypt object nested in the sibling properties may inherit. 定义嵌套在同级properties中的encrypt对象可以继承的加密选项。If an encrypt is missing an option required to support encryption, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies the missing option.

encryptMetadata must be specified in subschemas with bsonType: "object". encryptMetadata cannot be specified to any subschema of the items or additionalItems keywords. Specifically, automatic client-side field level encryption does not support encrypting individual elements of an array.

The encryptMetadata object can contain only the following fields. Including any other field to the encrypt object results in errors when issuing automatically encrypted read or write operations:

• algorithm
• keyId

encryptMetadata.algorithm

String

The encryption algorithm to use to encrypt a given field. 用于加密给定字段的加密算法。If an encrypt object is missing the algorithm field, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies encryptMetadata.algorithm.如果encrypt对象缺少algorithm字段，mongocrypted将搜索整个父对象树，以查找指定encryptMetadata.algorithm的encryptMetadata对象。

Supports the following algorithms only:仅支持以下算法：

• AEAD_AES_256_CBC_HMAC_SHA_512-Random
• AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

For complete documentation on the encryption algorithms, see Encryption Algorithms.有关加密算法的完整文档，请参阅加密算法。

If specifying AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, any encrypt object inheriting that value must specify encrypt.bsonType.如果指定AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic，则继承该值的任何encrypt对象都必须指定encrypt.bsonType。

encryptMetadata.keyId

Array of single UUID单个UUID数组

The UUID of a data encryption key. 数据加密密钥的UUID。The UUID is a BSON binary data element of subtype 4.UUID是子类型4的BSON二进制数据元素。

Specify one string inside the array.在数组中指定一个字符串。

If an encrypt object is missing the keyId field, mongocryptd searches the entire tree of parent objects to locate an encryptMetadata object that specifies encryptMetadata.keyId.如果encrypt对象缺少keyId字段，mongocrypted将搜索整个父对象树，以查找指定encryptMetadata.keyId的encryptMetadata对象。

The data encryption key must exist in the key vault specified as part of the auto encryption configuration options. 数据加密密钥必须存在于作为自动加密配置选项的一部分指定的密钥库中。The specified configuration options must also include appropriate access to the Key Management Service (KMS) and Customer Master Key (CMK) used to create the data key. 指定的配置选项还必须包括对用于创建数据密钥的密钥管理服务（KMS）和客户主密钥（CMK）的适当访问。Automatic encryption fails if the data encryption key does not exist or if the client cannot decrypt the key with the specified KMS and CMK.如果数据加密密钥不存在，或者客户端无法使用指定的KMS和CMK解密密钥，则自动加密失败。

Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. 官方MongoDB 4.2+兼容驱动程序对指定UUID有特定语言的要求。Defer to the driver documentation for complete documentation on implementing client-side field level encryption.有关实现客户端字段级加密的完整文档，请参阅驱动程序文档。

Examples示例

• Automatically Encrypt Multiple Fields自动加密多个字段
• Automatically Encrypt Multiple Fields With Inheritance使用继承自动加密多个字段

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

{
  "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"
            }
          }
        }
      }
    }
  }
}

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

{
  "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"
            }
          }
        }
      }
    }
  }
}