Docs Home → MongoDB Manual

CSFLE Encryption SchemasCSFLE加密架构

On this page本页内容

MongoDB's Queryable Encryption feature is available (GA) in MongoDB 7.0 and later. To learn more about Queryable Encryption and compare its benefits with Client-Side Field Level Encryption, see Queryable Encryption.

Overview概述

Note

Enterprise Feature企业功能

The automatic feature of field level encryption is only available in MongoDB Enterprise 4.2 or later, and MongoDB Atlas 4.2 or later clusters.字段级加密的自动功能仅在MongoDB Enterprise 4.2或更高版本以及MongoDB Atlas 4.2或更新版本的集群中可用。

New in version 4.2. 4.2版新增。

Encryption schemas contain user-specified rules that identify which fields must be encrypted and how to encrypt those fields. 加密模式包含用户指定的规则，这些规则标识哪些字段必须加密以及如何加密这些字段。Applications must specify the automatic encryption rules using a strict subset of the JSON Schema Draft 4 standard syntax and the following encryption-specific keywords:

  • Encrypt加密 specifies the encryption options to use when encrypting the current field.指定加密当前字段时要使用的加密选项。
  • Encrypt Metadata加密元数据 specifies inheritable encryption options.指定可继承的加密选项。

For the MongoDB 4.2+ shell, use the Mongo() constructor to create the database connection with the automatic encryption rules included as part of the Client-Side Field Level Encryption configuration object. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for an example.

For the official MongoDB 4.2+ compatible drivers, use the driver-specific database connection constructor (MongoClient) to create the database connection with the automatic encryption rules included as part of the Client-Side Field Level Encryption configuration object. To learn more about CSFLE-specific MongoClient options, see the mongo client page.

Important

Don't Specify Document Validation Keywords In Your Encryption Schema不要在加密架构中指定文档验证键

Do not specify document validation keywords in the automatic encryption rules. To define document validation rules, configure schema validation.不要在自动加密规则中指定文档验证键。若要定义文档验证规则，请配置架构验证。

Definition定义

encrypt

Object

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

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. encrypt must be the only child of the <fieldName> object.
  • encrypt cannot be specified within 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 encrypt 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在encrypt对象中包含任何其他字段会导致在发出自动加密的读或写操作时出错

If keyId or algorithm are omitted, the Shared Library checks all parent fields and attempts to construct those options from the nearest encryptMetadata object that specifies the option. bsonType cannot be inherited and may be required depending on the value of algorithm.

If the Shared Library 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.如果共享库无法使用为对象指定的字段和任何所需的encryptMetadata继承键来构造完全encrypt对象，则自动加密将失败并返回错误。

encrypt.algorithm

String

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

  • AEAD_AES_256_CBC_HMAC_SHA_512-Random
  • AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

For complete documentation on the encryption algorithms, see Fields and Encryption Types.

If omitted, the Shared Library checks all parent fields for the closest ancestor containing an 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.

If encrypt.algorithm or its inherited value is AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType must specify a single type. bsonType does not support any of the following BSON types with the deterministic encryption algorithm:

  • double
  • decimal128
  • bool
  • object
  • array
  • javascriptWithScope (Deprecated in MongoDB 4.4)

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. For fields with bsonType of array or object, the client encrypts the entire array or object and not their individual elements.

encrypt.bsonType does not support the following types regardless of encrypt.algorithm or its inherited value:

  • minKey
  • maxKey
  • null
  • undefined
encrypt.keyId

Array of single UUID

The UUID of the Data Encryption Key to use for encrypting field values. The UUID is a BSON binary data element of subtype 4.

Specify one string inside the array.

If omitted, the Shared Library checks all parent fields for the closest ancestor containing an encryptMetadata.keyId key and inherits that value. If no parent keyId exists, automatic field level encryption fails and returns an error.

The keyId or its inherited value must exist in the Key Vault collection specified as part of the automatic 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. Defer to the driver documentation for complete documentation on implementing client-side field level encryption.

encryptMetadata

Object

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

Defines encryption options which an encrypt object nested in the sibling properties may inherit. If an encrypt is missing an option required to support encryption, the Shared Library searches all 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:

encryptMetadata.algorithm

String

The encryption algorithm to use to encrypt a given field. If an encrypt object is missing the algorithm field, the Shared Library searches all parent objects to locate an encryptMetadata object that specifies encryptMetadata.algorithm.

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 Fields and Encryption Types.

If specifying AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, any encrypt object inheriting that value must specify encrypt.bsonType.

encryptMetadata.keyId

Array of single UUID

The UUID of a Data Encryption Key. The UUID is a BSON binary data element of subtype 4.

Specify one string inside the array.

If an encrypt object is missing the keyId field, the Shared Library searches all parent objects to locate an encryptMetadata object that specifies encryptMetadata.keyId.

The Data Encryption Key must exist in the Key Vault collection specified as part of the automatic 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. 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.

Official MongoDB 4.2+ compatible drivers have language-specific requirements for specifying the UUID. Defer to the driver documentation for complete documentation on implementing client-side field level encryption.

Examples实例

Encryption Schema - Multiple Fields加密架构-多个字段

Consider a collection MedCo.patients where each document has the following structure:

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

The following fields contains personally identifiable information (PII) that may be queried:以下字段包含可查询的个人身份信息（PII）：

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

The deterministic encryption algorithm guarantees that the encrypted output of a value remains static. 确定性加密算法保证值的加密输出保持静态。This allows queries for a specific value to return meaningful results at the cost of increased susceptibility to frequency analysis recovery. The deterministic encryption algorithm therefore meets both the encryption and queryability requirements of the data.这允许对特定值的查询返回有意义的结果，但代价是增加了频率分析恢复的敏感性。因此，确定性加密算法同时满足数据的加密和可查询性要求。

The following fields contain legally protected personally identifiable information (PII) that may never be queried:以下字段包含受法律保护的个人身份信息（PII），这些信息可能永远不会被查询：

  • medicalRecords

The randomized encryption algorithm guarantees that the encrypted output of a value is always unique. This prevents queries for a specific field value from returning meaningful results while supporting the highest possible protection of the field contents. The randomized encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following schema specifies automatic encryption rules which meet the above requirements for the 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"
            }
          }
        }
      }
    }
  }
}

The above automatic encryption rules mark the passportId, bloodType, insurance.policyNumber, insurance.provider, and medicalRecords fields for encryption.

  • The passportId, bloodType, insurance.policyNumber, and provider fields require deterministic encryption using the specified key.
  • The medicalRecords field requires randomized encryption using the specified key.

While Client-Side Field Level Encryption does not support encrypting individual array elements, randomized encryption supports encrypting the entire array field rather than individual elements in the field. The example automatic encryption rules specify randomized encryption for the medicalRecords field to encrypt the entire array. If the automatic encryption rules specified encrypt or encryptMetadata within medicalRecords.items or medicalRecords.additionalItems, automatic field level encryption fails and returns an errors.

The official MongoDB 4.2+ compatible drivers, mongosh, and the 4.2 or later legacy mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

  • For mongosh, use the Mongo() constructor to create a database connection. Specify the automatic encryption rules to the schemaMap key of the AutoEncryptionOpts parameter. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.
  • For the official MongoDB 4.2+ compatible drivers, use the driver-specific database connection constructor (MongoClient) to create the database connection with the automatic encryption rules included as part of the Client-Side Field Level Encryption configuration object. Defer to the driver API reference for more complete documentation and tutorials.

For all clients, the keyVault and kmsProviders specified to the Client-Side Field Level Encryption parameter must grant access to both the Data Encryption Keys specified in the automatic encryption rules and the Customer Master Key used to encrypt the Data Encryption Keys.

Encryption Schema - Multiple Fields With Inheritance

Consider a collection MedCo.patients where each document has the following structure:

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

The following fields contain private data that may be queried:

  • passportId
  • bloodType
  • insurance.policyNumber
  • insurance.provider

The deterministic encryption algorithm guarantees that the encrypted output of a value remains static. This allows queries for a specific value to return meaningful results at the cost of increased susceptibility to frequency analysis recovery. The deterministic encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following fields contain private data that may never be queried:

  • medicalRecords

The randomized encryption algorithm guarantees that the encrypted output of a value is always unique. This prevents queries for a specific field value from returning meaningful results while supporting the highest possible protection of the field contents. The randomized encryption algorithm therefore meets both the encryption and queryability requirements of the data.

The following schema specifies automatic encryption rules which meet the encryption requirements for the 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"
            }
          }
        }
      }
    }
  }
}

The above automatic encryption rules mark the passportId, bloodType, insurance.policyNumber, insurance.provider, and medicalRecords fields for encryption.

  • The passportId, bloodType, insurance.policyNumber, and provider fields inherit their encryption settings from the parent encryptMetadata field. Specifically, these fields inherit the algorithm and keyId values specifying deterministic encryption with the specified Data Encryption Key.
  • The medicalRecords field requires randomized encryption using the specified key. The encrypt options override those specified in the parent encryptMetadata field.

While Client-Side Field Level Encryption does not support encrypting individual array elements, randomized encryption supports encrypting the entire array field rather than individual elements in the field. The example automatic encryption rules specify randomized encryption for the medicalRecords field to encrypt the entire array. If the automatic encryption rules specified encrypt or encryptMetadata within medicalRecords.items or medicalRecords.additionalItems, automatic field level encryption fails and returns an errors.

The official MongoDB 4.2+ compatible drivers, mongosh, and the 4.2 or later legacy mongo shell require specifying the automatic encryption rules as part of creating the database connection object:

  • For mongosh, use the Mongo() constructor to create a database connection. Specify the automatic encryption rules to the schemaMap key of the AutoEncryptionOpts parameter. See Connect to a Cluster with Automatic Client-Side Encryption Enabled for a complete example.
  • For the official MongoDB 4.2+ compatible drivers, use the driver-specific database connection constructor (MongoClient) to create the database connection with the automatic encryption rules included as part of the Client-Side Field Level Encryption configuration object. Defer to the driver API reference for more complete documentation and tutorials.

For all clients, the keyVault and kmsProviders specified to the Client-Side Field Level Encryption parameter must grant access to both the Data Encryption Keys specified in the automatic encryption rules and the Customer Master Key used to encrypt the Data Encryption Keys.

To learn more about your CMK and Key Vault collection, see the key vaults page.

To learn more about encryption algorithms, see the Encryption algorithms page.

To learn more about CSFLE-specific MongoClient options, see the mongo client page.

Encryption Schema - Encrypt with Pattern Properties

You can use the patternProperties keyword in your encryption schema to define encryption rules for all fields with names that match a regular expression.

Consider a collection MedCo.patients where each document has the following structure:

{
  "fname" : "<string>",
  "lname" : "<string>",
  "passportId_PIIString" : "<string>",
  "bloodType_PIIString" : "<string>",
  "medicalRecords_PIIArray" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber_PIINumber" : "<number>",
    "provider_PIIString" : "<string>"
  }
}

The fields that contain private data are identified by a "_PII<type>" tag appended the end of the field name.

  • passportId_PIIString
  • bloodType_PIIString
  • medicalRecords_PIIArray
  • insurance.policyNumber_PIINumber
  • insurance.provider_PIIString

You can use the patternProperties keyword to configure these fields for encryption, without identifying each field individually, and without using the full field name. Do this by using regular expressions that match all fields that end with the "_PII<type>" tag.

The following JSON schema uses patternProperties and regular expressions to specify which fields to encrypt.

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

The above automatic encryption rules mark the passportId_PIIString, bloodType_PIIString, medicalRecords_PIIArray, insurance.policyNumber_PIINumber, insurance.provider_PIIString fields for encryption.

To Learn more about the patternProperties keyword, see patternProperties Keyword.