Database Manual / Security / Encryption / In-Use Encryption

Encryption Keys and Key Vaults加密键和键库

Queryable Encryption equality and range queries are fully supported in production. Prefix, suffix, and substring queries are only available in public preview in MongoDB 8.2. Do not enable these query types in production. GA functionality of prefix, suffix and substring query types will be incompatible with the preview feature.可查询的加密相等性和范围查询在生产环境中得到了完全支持。前缀、后缀和子字符串查询仅在MongoDB 8.2的公共预览中可用。不要在生产环境中启用这些查询类型。前缀、后缀和子字符串查询类型的GA功能将与预览功能不兼容。

Overview概述

In this guide, you can learn details about the following components of In-Use Encryption:在本指南中，您可以了解有关正在使用的加密的以下组件的详细信息：

  • Data Encryption Keys (DEK)s数据加密键（DEK）
  • Customer Master Keys (CMK)s客户主键（CMK）
  • Key Vault collections键库集合
  • Key Management System (KMS)键管理系统（KMS）

To view step by step guides demonstrating how to use the preceding components to set up a Queryable Encryption or Client-Side Field Level Encryption enabled client, see the following resources:要查看演示如何使用上述组件设置启用了可查询加密或客户端字段级加密的客户端的分步指南，请参阅以下资源：

Data Encryption Keys and the Customer Master Key数据加密键和客户主键

In-use encryption uses a multi-level key hierarchy to protect your data, often called "envelope encryption" or "wrapping keys".在用加密使用多级键层次结构来保护数据，通常称为“信封加密”或“包装键”。

A Customer Master Key (CMK), sometimes called a Key Management System (KMS) key, is the top-level key you create in your customer provisioned key provider, such as a cloud KMS. 客户主键（CMK），有时也称为键管理系统（KMS）键，是您在客户配置的键提供商（如云KMS）中创建的顶级键。The CMK encrypts Data Encryption Keys (DEK), which in turn encrypt the fields in your documents. Without access to a CMK, your client application cannot decrypt the associated DEKs.CMK对数据加密键（DEK）进行加密，进而对文档中的字段进行加密。如果无法访问CMK，客户端应用程序将无法解密关联的DEK。

MongoDB stores DEKs, encrypted with your CMK, in the Key Vault collection as BSON documents. MongoDB can never decrypt the DEKs, as key management is client-side and customer controlled.MongoDB将使用CMK加密的DEK作为BSON文档存储在键库集合中。MongoDB永远无法解密DEK，因为键管理是客户端和客户控制的。

If you delete a DEK, all fields encrypted with that DEK become permanently unreadable. If you delete a CMK, all fields encrypted with a DEK using that CMK become permanently unreadable.如果删除DEK，则使用该DEK加密的所有字段都将永久不可读。如果删除CMK，则使用该CMK用DEK加密的所有字段都将永久不可读。

Warning

The Customer Master Key is the most sensitive key in Queryable Encryption. If your CMK is compromised, all of your encrypted data can be decrypted. Use a remote Key Management System to store your CMK.客户主键是可查询加密中最敏感的键。如果CMK被泄露，所有加密数据都可以被解密。使用远程键管理系统存储CMK。

Important

Use a Remote Key Management Service Provider使用远程键管理服务提供商

Store your Customer Master Key on a remote Key Management System (KMS).将客户主键存储在远程键管理系统（KMS）上。

To learn more about why you should use a remote KMS, see Reasons to Use a Remote Key Management System.要了解有关为什么应该使用远程KMS的更多信息，请参阅使用远程键管理系统的原因。

To view a list of all supported KMS providers, see the KMS Providers page.要查看所有支持的KMS提供程序的列表，请参阅KMS提供程序页面。

Key Rotation关键点旋转

You rotate your CMK either manually or automatically on your provisioned key provider. MongoDB has no visibility into this process. Once you rotate the CMK, MongoDB uses it to wrap all new DEKs. It does not re-wrap existing encrypted DEKs. These are still wrapped with the prior CMK.您可以在配置的键提供程序上手动或自动轮换CMK。MongoDB对这个过程没有可见性。一旦你旋转了CMK，MongoDB就会用它来包装所有新的DEK。它不会重新包装现有的加密DEK。这些仍然用之前的CMK包装。

To rotate some or all of the encrypted DEKs in your key vault, use the KeyVault.rewrapManyDataKey() method. 要旋转键库中的部分或全部加密DEK，请使用KeyVault.rewrapManyDataKey()方法。It seamlessly re-wraps keys with the new CMK specified, without interrupting your application. The DEKs themselves are left unchanged after re-wrapping them with the new CMK.它使用指定的新CMK无缝地重新包装键，而不会中断应用程序。DEK本身在用新的CMK重新包装后保持不变。

For details on rotating keys, see Rotate Encryption Keys.有关旋转键的详细信息，请参阅旋转加密键。

Key Vault Collections键库集合

Your Key Vault collection is the MongoDB collection you use to store encrypted Data Encryption Key (DEK) documents. DEK documents are BSON documents that contain DEKs and have the following structure:键库集合是用于存储加密数据加密键（DEK）文档的MongoDB集合。DEK文档是包含DEK的BSON文档，具有以下结构：

{
  "_id" : UUID(<string>),
  "status" : <int>,
  "masterKey" : {<object>},
  "updateDate" : ISODate(<string>),
  "keyMaterial" : BinData(0,<string>),
  "creationDate" : ISODate(<string>),
  "keyAltNames" : <array>
}

You create your Key Vault collection as you would a standard MongoDB collection. Your Key Vault collection must have a unique index on the keyAltNames field. To check if the unique index exists, run the listIndexes command against the Key Vault collection:您可以像创建标准MongoDB集合一样创建键库集合。键库集合必须在keyAltNames字段上具有唯一索引。要检查唯一索引是否存在，请对键库集合运行listIndexes命令：

db.runCommand({
   listIndexes: "__keyVault",
});

{
   cursor: {
      id: Long("0"),
      ns: 'encryption.__keyVault',
      firstBatch: [
         { v: 2, key: { _id: 1 }, name: '_id_' }
         ]
   },
   ok: 1,
}

If the unique index does not exist, your application must create it before performing DEK management.如果唯一索引不存在，应用程序必须在执行DEK管理之前创建它。

To learn how to create a MongoDB collection, see Databases and Collections.要了解如何创建MongoDB集合，请参阅数据库和集合。

Tip

mongosh Feature

The mongosh method KeyVault.createKey() automatically creates a unique index on the keyAltNames field if one does not exist.如果keyAltNames字段不存在唯一索引，mongosh方法KeyVault.createKey()会自动在该字段上创建一个唯一索引。

To view diagrams detailing how your DEK, CMK, and Key Vault collection interact in all supported KMS provider architectures, see KMS Providers.要查看详细说明DEK、CMK和键库集合在所有支持的KMS提供程序架构中如何交互的图表，请参阅KMS提供程序。

Key Vault collection Name键库集合名称

You may use any non-admin namespace to store your Key Vault collection. 您可以使用任何非管理员命名空间来存储键库集合。By convention, the examples throughout this documentation use the encryption.__keyVault namespace.按照惯例，本文档中的示例都使用encryption.__keyVault命名空间。

Warning

Do not use the admin database to store encryption-related collections. If you use the admin database for this collection, your MongoDB client may not be able to access or decrypt your data due to lack of permissions.不要使用admin数据inventory储与加密相关的集合。如果您使用此集合的管理数据库，则由于缺乏权限，MongoDB客户端可能无法访问或解密数据。

Permissions权限

Applications with read access to the Key Vault collection can retrieve encrypted Data Encryption Key (DEK)s by querying the collection. 具有键库集合read权限的应用程序可以通过查询该集合来检索加密的数据加密键（DEK）。However, only applications with access to the Customer Master Key (CMK) used to encrypt a DEK can use that DEK for encryption or decryption. You must grant your application access to both the Key Vault collection and your CMK to encrypt and decrypt documents with a DEK.但是，只有能够访问用于加密DEK的客户主键（CMK）的应用程序才能使用该DEK进行加密或解密。您必须授予应用程序访问键库集合和CMK的权限，才能使用DEK对文档进行加密和解密。

To learn how to grant access to a MongoDB collection, see Manage Users and Roles in the MongoDB manual.要了解如何授予对MongoDB集合的访问权限，请参阅MongoDB手册中的管理用户和角色。

To learn how to grant your application access to your Customer Master Key, see the Queryable Encryption Automatic Encryption Tutorial or CSFLE Automatic Encryption Tutorial.要了解如何授予应用程序访问客户主键的权限，请参阅可查询加密自动加密教程或CSFLE自动加密教程。

Key Vault Cluster键保险库集群

By default, MongoDB stores the Key Vault collection on the connected cluster. MongoDB also supports hosting the Key Vault collection on a different MongoDB deployment than the connected cluster. 默认情况下，MongoDB将键库集合存储在连接的集群上。MongoDB还支持在与连接的集群不同的MongoDB部署上托管键库集合。Applications must have access to both the cluster that hosts your Key Vault collection and the connection cluster to perform Queryable Encryption operations.应用程序必须能够访问承载键库集合的群集和连接群集，才能执行可查询加密操作。

To specify the cluster that hosts your Key Vault collection, use the keyVaultClient field of your client's MongoClient object. 要指定托管键库集合的集群，请使用客户端MongoClient对象的keyVaultClient字段。To learn more about the specific configuration options in your client's MongoClient object, see the MongoClient Options for Queryable Encryption or MongoClient Options for CSFLE.要了解有关客户端MongoClient对象中特定配置选项的更多信息，请参阅用于可查询加密的MongoClient选项或用于CSFLE的MongoClientOptions。

Update a Key Vault Collection更新键库集合

To add a DEK to your Key Vault collection, use the createKey method of a ClientEncryption object.要将DEK添加到键库集合中，请使用ClientEncryption对象的createKey方法。

To delete or update a DEK, use one of the following mechanisms:要删除或更新DEK，请使用以下机制之一：

  • The rewrapManyDataKey methodrewrapManyDataKey方法
  • Standard CRUD operations标准CRUD操作

To learn more about the rewrapManyDataKey method, see the documentation of the method for your client or driver:要了解有关rewrapManyDataKey方法的更多信息，请参阅客户端或驱动程序的方法文档：

Tip

mongosh Specific Featuresmongosh特有特征

mongosh provides the following additional methods for working with your Key Vault collection:mongosh提供了以下使用键库集合的附加方法：

To view a tutorial that shows how to create a Data Encryption Key, see the Queryable Encryption Quick Start or the CSFLE Quick Start.要查看显示如何创建数据加密键的教程，请参阅可查询加密快速入门或CSFLE快速入门。