Client-Side Field Level Encryption客户端字段级加密

Supported Encryption Methods支持的加密方法

MongoDB supports two methods of client-side field level encryption using the official MongoDB 4.2+ compatible drivers:MongoDB支持两种使用官方MongoDB 4.2+兼容驱动程序的客户端字段级加密方法：

Explicit (manual) encryption of fields字段的显式（手动）加密

Official MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell support explicitly encrypting or decrypting fields with a specific data encryption key and encryption algorithm.官方MongoDB 4.2+兼容驱动程序、mongosh和MongoDB 4.2或更高版本的旧mongo shell支持使用特定数据加密密钥和加密算法显式加密或解密字段。

Applications must modify any code associated with constructing read and write operations to include encryption/decryption logic via the driver encryption library. 应用程序必须修改与构建读写操作相关的任何代码，以通过驱动程序加密库包含加密/解密逻辑。Applications are responsible for selecting the appropriate data encryption key for encryption/decryption on a per-operation basis.应用程序负责在每次操作的基础上选择适当的数据加密密钥进行加密/解密。

For more information, see Explicit (Manual) Client-Side Field Level Encryption.有关更多信息，请参阅显式（手动）客户端字段级加密。

Automatic encryption of fields字段的自动加密

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或更晚版本集群中可用。

Official MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell support automatically encrypting fields in read and write operations.官方MongoDB 4.2+兼容驱动程序、mongosh和MongoDB 4.2或更高版本的旧mongo shell支持在读写操作中自动加密字段。

Applications must create a database connection object (e.g. MongoClient) with the automatic encryption configuration settings. 应用程序必须使用自动加密配置设置创建数据库连接对象（例如MongoClient）。The configuration settings must include automatic encryption rules using a strict subset of the JSON Schema Draft 4 standard syntax and encryption-specific schema keywords. 配置设置必须包括使用JSON模式草稿4标准语法的严格子集和加密特定模式关键字的自动加密规则。Applications do not have to modify code associated with the read/write operation. 应用程序不必修改与读/写操作相关的代码。See Automatic Encryption Rules for complete documentation on automatic encryption rules.有关自动加密规则的完整文档，请参阅自动加密规则。

For more information, see Automatic Client-Side Field Level Encryption.有关更多信息，请参阅自动客户端字段级加密。

MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell automatically decrypt Binary subtype 6 objects created using client-side field level encryption. MongoDB 4.2+兼容的驱动程序、mongosh和MongoDB 4.2或更高版本的旧mongo shell会自动解密使用客户端字段级加密创建的Binary子类型6对象。For more information on automatic decryption, see Automatic Field Decryption.有关自动解密的详细信息，请参阅自动字段解密。

Encryption Components加密组件

The following diagram illustrates the relationships between the driver and each encryption component:下图说明了驱动程序和每个加密组件之间的关系：

• libmongocrypt is the Apache-licensed open-source core cryptography library used by the official MongoDB 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell for powering client-side field level encryption. libmongocrypt是Apache授权的开源核心加密库，由官方MongoDB 4.2+兼容驱动程序、mongosh和MongoDB 4.2或更高版本的遗留mongo shell使用，用于支持客户端字段级加密。Some drivers may require specific integration steps to install or link the library. 某些驱动程序可能需要特定的集成步骤来安装或链接库。Defer to driver documentation for more complete information.有关更完整的信息，请参阅驱动程序文档。
• mongocryptd supports Automatic Client-Side Field Level Encryption and is only available with MongoDB Enterprise. mongocryptd支持自动客户端字段级加密，仅适用于MongoDB Enterprise。mongocryptd does not perform cryptographic functions.mongocrypted不执行加密功能。
• The Key Vault is a MongoDB collection that stores all data encryption keys used to encrypt values. 密钥库是一个MongoDB集合，存储用于加密值的所有数据加密密钥。Data encryption keys are themselves encrypted using a Customer Master Key (CMK) prior to storage in the collection. 数据加密密钥本身在存储在集合中之前使用客户主密钥（CMK）进行加密。The key vault may reside on a different MongoDB cluster than the one storing the encrypted data.密钥库可以驻留在不同于存储加密数据的MongoDB集群上。

• The Key Management Service (KMS) stores the Customer Master Key (CMK) used to encrypt data encryption keys. MongoDB supports the following KMS providers:密钥管理服务（KMS）存储用于加密数据加密密钥的客户主密钥（CMK）。MongoDB支持以下KMS提供商：

  • Amazon Web Services KMS亚马逊网络服务KMS
  • Azure Key Vault
  • Google Cloud Platform KMS
  • Locally Managed Key
• The MongoDB cluster which stores the encrypted data may also enforce client-side field level encryption. 存储加密数据的MongoDB集群还可以实施客户端字段级加密。See Enforce Field Level Encryption Schema for more information.有关详细信息，请参阅强制字段级加密架构。

Encryption Algorithms加密算法

MongoDB client-side field level encryption uses the encrypt-then-MAC approach combined with either a deterministic or random initialization vector to encrypt field values. MongoDB客户端字段级加密使用encrypt-then-MAC方法结合确定性或随机初始化向量来加密字段值。MongoDB only supports the AEAD AES-256-CBC encryption algorithm with HMAC-SHA-512 MAC.MongoDB仅支持带有HMAC-SHA-512 MAC的AEAD AES-256-CBC加密算法。

{
 "personal_information" : {
   "ssn" : "123-45-6789",
   "credit_score" : 750,
   "credit_cards" : [ "1234-5678-9012-3456", "9876-5432-1098-7654"]
 },
 "phone_numbers" : [ "(212) 555-0153" ]
}

Automatic Field Decryption自动字段解密

The BinData blob metadata includes the data encryption key _id and encryption algorithm used to encrypt the binary data. BinData blob元数据包括用于加密二进制数据的数据加密密钥_id和加密算法。The 4.2+ compatible drivers, mongosh, and the MongoDB 4.2 or later legacy mongo shell use this metadata to attempt automatic decryption of BinData subtype 6 objects. 4.2+兼容驱动程序mongosh和MongoDB 4.2或更高版本的mongoshell使用此元数据尝试自动解密BinData子类型6对象。The automatic decryption process works as follows:自动解密过程的工作原理如下：

1. Check the BinData blob metadata for the data encryption key and encryption algorithm used to encrypt the value.检查BinData blob元数据中用于加密值的数据加密密钥和加密算法。
2. Check the key vault configured in the current database connection for the specified data encryption key. 检查在当前数据库连接中配置的密钥保管库中指定的数据加密密钥。If the key vault does not contain the specified key, automatic decryption fails and the driver returns the BinData blob.如果密钥库不包含指定的密钥，则自动解密失败，驱动程序将返回BinData blob。
3. Check the data encryption key metadata for the Customer Master Key (CMK) used to encrypt the key material.检查用于加密密钥材料的客户主密钥（CMK）的数据加密密钥元数据。

4. For the Amazon Web Services KMS, Azure Key Vault, or Google Cloud Platform KMS, send the data encryption key to the KMS provider for decryption. 对于Amazon Web Services KMS、Azure Key Vault或Google Cloud Platform KMS，请将数据加密密钥发送给KMS提供商进行解密。If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the BinData blob.如果CMK不存在或连接配置未授予对CMK的访问权限，则解密失败，驱动程序返回BinData blob。

   For the Locally Managed Key, retrieve the local key and decrypt the data encryption key. 对于本地管理密钥，检索本地密钥并解密数据加密密钥。If the local key specified in the database configuration was not used to encrypt the data encryption key, decryption fails and the driver returns the BinData blob.如果数据库配置中指定的本地密钥未用于加密数据加密密钥，则解密失败，驱动程序将返回BinData blob。

5. Decrypt the BinData value using the decrypted data encryption key and appropriate algorithm.使用解密的数据加密密钥和适当的算法解密BinData值。

Applications with access to the MongoDB server that do not also have access to the required master key and data encryption keys cannot decrypt the BinData values.具有MongoDB服务器访问权限的应用程序，如果无法访问所需的主密钥和数据加密密钥，则无法解密BinData值。

For more information on configuring the database connection for client-side field level encryption, see the Mongo() constructor or defer to the documentation for your preferred driver's client construction method.有关为客户端字段级加密配置数据库连接的更多信息，请参阅Mongo()构造函数，或参考首选驱动程序客户端构造方法的文档。

Enforce Field Level Encryption Schema强制字段级加密架构

Starting with MongoDB 4.2, the server supports using schema validation to enforce encryption of specific fields in a collection. 从MongoDB 4.2开始，服务器支持使用模式验证来强制加密集合中的特定字段。Use the automatic encryption rule keywords with the $jsonSchema validation object to indicate which fields require encryption. 在$jsonSchema验证对象中使用自动加密规则关键字来指示哪些字段需要加密。The server rejects any write operations to that collection where the specified fields are not Binary (BinData) subtype 6 objects.如果指定的字段不是Binary (BinData)子类型6对象，服务器将拒绝对该集合的任何写入操作。

For example, the following collMod command modifies the hr.employees collection to include a validator. 例如，以下collMod命令修改hr.employees集合以包含validator。The $jsonSchema validation object includes client-side field level encryption keywords to indicate that:$jsonSchema验证对象包括客户端字段级加密关键字，以指示：

• The taxid field must be encrypted. taxid字段必须加密。Clients should use the specified data encryption key and the randomized encryption algorithm when encrypting the field.客户端在加密字段时应使用指定的数据加密密钥和随机化加密算法。
• The taxid-short field must be encrypted. Clients should use the specified data encryption key and the deterministic encryption algorithm when encrypting the field.taxid-short字段必须加密。客户端在加密字段时应使用指定的数据加密密钥和确定性加密算法。

db.getSiblingDB("hr").runCommand(
  {
    "collMod" : "employees",
    "validator" : {
      "$jsonSchema" : {
        "bsonType" : "object",
        "properties" : {
          "taxid" : {
            "encrypt" : {
              "keyId" : [UUID("e114f7ad-ad7a-4a68-81a7-ebcb9ea0953a")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
            }
          },
          "taxid-short" : {
            "encrypt" : {
              "keyId" : [UUID("33408ee9-e499-43f9-89fe-5f8533870617")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
)

Clients performing explicit (manual) field level encryption mustencrypt at minimum the taxid and taxid-short fields using the same settings as the remote $jsonSchema prior to issuing the write operation.执行显式（手动）字段级加密的客户端在发出写入操作之前，必须使用与远程$jsonSchema相同的设置至少加密taxid和taxid-short字段。

Clients performing automatic client-side field level encryption have specific behavior depending on the database connection configuration:执行自动客户端字段级加密的客户端具有特定的行为，具体取决于数据库连接配置：

• If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object contains a key for the specified collection, the client uses that object to perform automatic field level encryption and ignores the remote schema. 如果连接ClientSideFieldLevelEncryptionOptions schemaMap对象包含指定集合的密钥，则客户端将使用该对象执行自动字段级加密，并忽略远程模式。The local rules must encrypt at minimum those the taxid and taxid-short fields.本地规则必须至少加密taxid和taxid-short字段。

• If the connection ClientSideFieldLevelEncryptionOptionsschemaMap object does not contain a key for the specified collection, the client downloads the server-side remote schema for the collection and uses it to perform automatic field level encryption.如果连接ClientSideFieldLevelEncryptionOptions schemaMap对象不包含指定集合的密钥，则客户端将下载该集合的服务器端远程模式，并使用它执行自动字段级加密。

  This configuration requires the client to trust the server has a valid schema with respect to automatic field level encryption. 此配置要求客户端信任服务器具有关于自动字段级加密的有效架构。The client only uses the remote schema to perform automatic field level encryption and does not enforce any other validation rules specified in the schema.客户端仅使用远程模式执行自动字段级加密，不强制执行模式中指定的任何其他验证规则。

Since the MongoDB server cannot decrypt nor introspect the contents of the encrypted field, it cannot validate that clients used the specified encryption options to encrypt a given field. 由于MongoDB服务器无法解密或检查加密字段的内容，因此无法验证客户端是否使用指定的加密选项对给定字段进行加密。This allows two clients to insert encrypted data using different keyIDs or encryption algorithms for a specific field. 这允许两个客户端使用不同的密钥ID或特定字段的加密算法插入加密数据。While some workloads may require independent field level encryption implementations, inconsistent implementation of encryption options for a field across clients may result in incorrect or unexpected behavior of queries against the encrypted field.虽然某些工作负载可能需要独立的字段级加密实现，但跨客户端的字段加密选项实现不一致可能会导致针对加密字段的查询行为不正确或意外。

For example, client A encrypts the PII field using random encryption while client B encrypts the PII field using deterministic encryption. 例如，客户机A使用随机加密对PII字段进行加密，而客户机B使用确定性加密对PII字段进行加密。The randomized encryption algorithm always returns a different unique value while the deterministic algorithm always returns the same value. 随机加密算法总是返回不同的唯一值，而确定性算法总是返回相同的值。Queries expecting deterministically encrypted data for that field return inconsistent results, as the server cannot match any of the randomly encrypted fields.由于服务器无法匹配任何随机加密的字段，因此需要该字段的确定加密数据的查询返回不一致的结果。

Driver Compatibility Table驱动程序兼容性表

MongoDB 4.2 client-side field level encryption is only available with the following official 4.2+ compatible driver versions:MongoDB 4.2客户端字段级加密仅适用于以下官方4.2+兼容驱动程序版本：

Please refer to the driver reference documentation for syntax and implementation examples.有关语法和实现示例，请参阅驱动程序参考文档。