Keys and Key Vaults¶

On this page

Overview
Keys
s

Overview¶

In this guide, you can learn details about the following components of :

s
s (DEK)
s (CMK)

To view step by step guides demonstrating how to use the preceding components to set up a enabled client, see the following resources:

<qe-quick-start>
<qe-tutorial-automatic-encryption>

Keys¶

A **** (CMK) is the key you use to encrypt your s (DEK). The CMK is the most sensitive key in . If your CMK is compromised, all of your encrypted data can be decrypted.

Important

Use a Remote Key Management Service Provider

Ensure you store your () on a remote KMS.

To learn more about why you should use a remote , see Reasons to Use a Remote KMS.

To view a list of all supported providers, see the KMS Providers page.

A (DEK) is the key you use to encrypt the fields in your MongoDB documents. You store your in your encrypted with your CMK. Without access to your CMK, your client application cannot decrypt your which in turn cannot decrypt your data. To learn more about s, see <qe-reference-key-vault>.

Important

Deleting Keys

If you delete a (DEK), all fields encrypted with that DEK become permanently unreadable.

If you delete a CMK, all fields encrypted with DEKs encrypted with that CMK become permanently unreadable.

To view diagrams detailing how your DEK, CMK, and interact in all supported Key Management Service (KMS) provider architectures, see KMS Providers.

s¶

Your is the MongoDB collection you use to store ** (DEK) documents**. DEK documents are BSON documents that contain s and have the following structure:

copy

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

You create your as you would a standard MongoDB collection. Your must have a unique index on the keyAltNames field. To check if the unique index exists, you can run the listIndexes command against the . If the unique index does not exist, applications must create it before performing DEK management.

To learn how to create a MongoDB collection, see Databases and Collections.

Tip

mongosh Feature

The mongosh method KeyVault.createKey() automatically creates a unique index on the keyAltNames field if one does not exist.

Permissions¶

Applications with read access to the can retrieve DEKs by querying the collection. However, only applications with access to the CMK used to encrypt a DEK can use that DEK for encryption or decryption. You must grant your application access to both the and your CMK to encrypt and decrypt documents with a DEK.

To learn how to grant access to a MongoDB collection, see Manage Users and Roles in the MongoDB manual.

To learn how to grant your application access to your CMK, see the <qe-tutorial-automatic-encryption> tutorial.

Key Vault Cluster¶

By default, MongoDB stores the on the connected cluster. MongoDB also supports hosting the on a different MongoDB deployment than the connected cluster. Applications must have access to both the cluster that hosts your

and the connection cluster to perform operations.

To specify the cluster that hosts your , use the keyVaultClient field of your client’s MongoClient object. To learn more about the -specific configuration options in your client’s MongoClient object, see the <qe-reference-mongo-client> guide.

Update a¶

To add a to your , use the createKey method of a ClientEncryption object.

To delete or update a , use standard CRUD operations. You store a in MongoDB as a document, and you can apply any document operation to a .

To view a tutorial that shows how to create a , see the Quick Start.

Tip

mongosh Specific Features

mongosh provides the following additional methods for working with your :

← Encrypted Collection Management Encryption Key Management →