Docs Home → MongoDB Manual

Keys and Key Vaults键和键库

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概述

In this guide, you can learn details about the following components of Client-Side Field Level Encryption (CSFLE):在本指南中，您可以了解有关客户端字段级加密（CSFLE）的以下组件的详细信息：

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

To view step by step guides demonstrating how to use the preceding components to set up a CSFLE enabled client, see the following resources:要查看演示如何使用前面的组件来设置启用CSFLE的客户端的分步指南，请参阅以下资源：

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文档存储在Key Vault集合中。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. 您可以在已配置的键提供商上手动或自动轮换CMK。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. MongoDB对此过程一无所知。一旦旋转CMK，MongoDB就会使用它来包装所有新的DEK。它不会重新包装现有的加密DEK。These are still wrapped with the prior CMK.这些仍然被先前的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无缝地重新包装键，而不会中断您的应用程序。在用新的CMK重新包装DEK之后，DEK本身保持不变。

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. 您可以像创建标准MongoDB集合一样创建键库集合。键保管库集合的keyAltNames字段必须具有唯一索引。To check if the unique index exists, run the listIndexes command against the Key Vault collection:要检查唯一索引是否存在，请对键保管库集合运行listIndexes命令：

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

Output:输出：

{
   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.mongosh方法KeyVault.createKey()会自动在keyAltNames字段上创建一个唯一索引（如果不存在）。

To view diagrams detailing how your DEK, CMK, and Key Vault collection interact in all supported KMS provider architectures, see CSFLE KMS Providers.要查看详细说明DEK、CMK和键保管库集合在所有受支持的KMS提供程序体系结构中如何交互的图表，请参阅CSFLE 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数据库来存储与加密相关的集合。如果您使用此集合的管理数据库，您的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. 但是，只有能够访问用于加密DEK的客户主键（CMK）的应用程序才能使用该DEK进行加密或解密。You must grant your application access to both the Key Vault collection and your CMK to encrypt and decrypt documents with a 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 CMK, see the Tutorials tutorial.要了解如何授予应用程序访问CMK的权限，请参阅教程。

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 CSFLE-specific configuration options in your client's MongoClient object, see CSFLE-Specific MongoClient Options.要了解有关客户端MongoClient对象中特定于CSFLE的配置选项的更多信息，请参阅特定于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 methodrewriteManyDataKey方法
  • Standard CRUD operations标准CRUD操作

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

Tip

mongosh Specific Features特定功能

mongosh provides the following additional methods for working with your Key Vault collection:提供了以下用于处理键库集合的其他方法：

To view a tutorial that shows how to create a DEK, see the Quick Start.要查看显示如何创建DEK的教程，请参阅快速入门。