Docs Home → MongoDB Manual

Explicit Encryption显式加密

On this page本页内容

Queryable Encryption with equality queries is generally available (GA) in MongoDB 7.0 and later. 具有相等查询的可查询加密在MongoDB 7.0及更高版本中通常可用（GA）。The Queryable Encryption Public Preview, released in version 6.0, is no longer supported. Data encrypted using the Public Preview is incompatible with the feature release. 不再支持6.0版本中发布的“可查询加密预览”。使用公共预览加密的数据与功能版本不兼容。For more information, see Compatibility Changes in MongoDB 7.0.有关更多信息，请参阅MongoDB 7.0中的兼容性更改。

Overview概述

Learn how to use the explicit encryption mechanism of Queryable Encryption. Explicit encryption lets you specify the key material used to encrypt fields. 了解如何使用Queryable encryption的显式加密机制。显式加密允许您指定用于加密字段的键材料。It provides fine-grained control over security, at the cost of increased complexity when configuring collections and writing code for MongoDB Drivers.它提供了对安全性的细粒度控制，但在为MongoDB驱动程序配置集合和编写代码时会增加复杂性。

Explicit encryption is a mechanism in which you specify how to encrypt and decrypt fields in your document for each operation you perform on your database.显式加密是一种机制，在该机制中，您可以为对数据库执行的每个操作指定如何加密和解密文档中的字段。

Explicit encryption is available in the following MongoDB products:显式加密在以下MongoDB产品中可用：

  • MongoDB Community Server
  • MongoDB Enterprise Advanced
  • MongoDB Atlas

Use Explicit Encryption使用显式加密

Create a ClientEncryption Instance创建ClientEncryption实例

ClientEncryption is an abstraction used across drivers and mongosh that encapsulates the Key Vault collection and KMS operations involved in explicit encryption.ClientEncryption是一种跨驱动程序和mongosh使用的抽象，它封装了显式加密中涉及的键库集合和KMS操作。

To create a ClientEncryption instance, specify:要创建ClientEncryption实例，请指定：

  • A kmsProviders object configured with access to the KMS hosting your Customer Master KeykmsProviders对象配置为可以访问托管客户主键的KMS
  • The namespace of your Key Vault collection键库集合的命名空间
  • If you use MongoDB Community Server, set the bypassQueryAnalysis option to True如果使用MongoDB Community Server，请将bypassQueryAnalysis选项设置为True
  • A MongoClient instance with access to your Key Vault collection可以访问键库集合的MongoClient实例

For more ClientEncryption options, see MongoClient Options for Queryable Encryption.有关更多ClientEncryption选项，请参阅MongoClient可查询加密选项。

Encrypt Fields in Read and Write Operations读取和写入操作中的加密字段

You must update read and write operations throughout your application such that your application encrypts fields before performing read and write operations.您必须在整个应用程序中更新读写操作，以便应用程序在执行读写操作之前对字段进行加密。

To encrypt fields, use the encrypt method of your ClientEncryption instance. Specify the following:要加密字段，请使用ClientEncryption实例的encrypt方法。指定以下内容：

  • The value to be encrypted要加密的值
  • The algorithm used, either Indexed or Unindexed使用的算法，Indexed(已索引)或Unindexed(未索引)
  • The ID of the Data Encryption Key数据加密键的ID
  • The contention factor (if you are using the Indexed algorithm)争用因子（如果您使用的是Indexed算法）
  • If performing a read operation, set the query type defined for your field (if you are using the Indexed algorithm)如果执行读取操作，请设置为字段定义的查询类型（如果使用的是Indexed算法）
Note

Query Types查询类型

The query type only applies to read operations.查询类型仅适用于读取操作。

To learn more about query types, see Query Types.要了解有关查询类型的详细信息，请参阅查询类型。

Algorithm Choice算法选择

Use the Indexed algorithm if you specify a queryType on the field.如果在字段上指定queryType，请使用Indexed算法。

Indexed supports equality queries. Indexed支持相等查询。Indexed fields require an index on the server. 字段需要服务器上的索引。The index is created by specifying the encryptedFields option in db.createCollection().通过在db.createCollection()中指定encryptedFields选项来创建索引。

Automatic Decryption自动解密

To decrypt fields automatically, configure your MongoClient instance as follows:要自动解密字段，请按如下方式配置MongoClient实例：

  • Specify a kmsProviders object指定kmsProviders对象
  • Specify your Key Vault collection指定键保管库集合
  • If you use MongoDB Community Server, set the bypassQueryAnalysis option to True如果使用MongoDB Community Server，请将bypassQueryAnalysis选项设置为True
Note

Automatic Decryption in MongoDB Community ServerMongoDB社区服务器中的自动解密

Automatic decryption is available in MongoDB Community Server. MongoDB Community Server提供自动解密功能。Automatic encryption requires MongoDB Enterprise or MongoDB Atlas.自动加密需要MongoDB Enterprise或MongoDB Atlas。

Server-Side Field Level Encryption Enforcement服务器端字段级加密强制

Specify Fields for Encryption指定加密字段 to enforce encryption of specific fields in a collection.以强制对集合中的特定字段进行加密。

Indexed fields require an index on the server. 字段需要服务器上的索引。The index is created by specifying the encryptedFields option in db.createCollection().通过在db.createCollection()中指定encryptedFields选项来创建索引。

If your MongoDB instance enforces the encryption of specific fields, any client performing Queryable Encryption with explicit encryption must encrypt those fields as specified. To learn how to set up server-side Queryable Encryption enforcement, see Field Encryption and Queryability.如果您的MongoDB实例强制对特定字段进行加密，则任何使用显式加密执行可查询加密客户端都必须按照指定对这些字段进行加密。要了解如何设置服务器端可查询加密强制，请参阅字段加密和可查询性。

Learn More了解更多信息

To learn more about Key Vault collections, Data Encryption Keys, and Customer Master Keys, see Keys and Key Vaults.要了解有关键库集合、数据加密键和客户主键的详细信息，请参阅键和键库。

To learn more about KMS providers and kmsProviders objects, see KMS Providers.要了解有关KMS提供程序和kmsProviders对象的详细信息，请参阅KMS提供器。