Docs Menu

Docs Home → Develop Applications → MongoDB Manual

Keys and Key Vaults

On this page

  • Overview
  • Keys
  • Key Vault Collections
  • Key Vault collection Name
  • Permissions
  • Key Vault Cluster
  • Update a Key Vault Collection

Overview

In this guide, you can learn details about the following components of Client-Side Field Level Encryption (CSFLE):

  • Key Vault collections

  • Data Encryption Keys (DEK)

  • Customer Master Keys (CMK)

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

Keys

A Customer Master Key (CMK) is the key you use to encrypt your Data Encryption Keys (DEK). The CMK is the most sensitive key in CSFLE. 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 Customer Master Key (CMK) on a remote KMS.

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

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

A Data Encryption Key (DEK) is the key you use to encrypt the fields in your MongoDB documents. You store your Data Encryption Key in your Key Vault collection encrypted with your CMK. Without access to your CMK, your client application cannot decrypt your Data Encryption Key which in turn cannot decrypt your data. To learn more about Key Vault collections, see Key Vault Collections.

Important

Deleting Keys

If you delete a Data Encryption Key (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 Key Vault collection interact in all supported Key Management Service (KMS) provider architectures, see KMS Providers.

Key Vault Collections

Your Key Vault collection is the MongoDB collection you use to store Data Encryption Key (DEK) documents. DEK documents are BSON documents that contain Data Encryption Keys and have the following structure:

{
  "_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, you can run the listIndexes command against the Key Vault collection:

1db.runCommand({
2   listIndexes: "__keyVault",
3});
1{
2   cursor: {
3      id: Long("0"),
4      ns: 'encryption.__keyVault',
5      firstBatch: [
6         { v: 2, key: { _id: 1 }, name: '_id_' }
7         ]
8   },
9   ok: 1,
10}

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.

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.

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.

Permissions

Applications with read access to the Key Vault collection 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 Key Vault collection 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 Tutorials tutorial.

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. Applications must have access to both the cluster that hosts your Key Vault collection and the connection cluster to perform CSFLE operations.

To specify the cluster that hosts your Key Vault collection, use the keyVaultClient field of your client's MongoClient object. To learn more about the CSFLE-specific configuration options in your client's MongoClient object, see the CSFLE-Specific MongoClient Options guide.

Update a Key Vault Collection

To add a DEK to your Key Vault collection, use the createKey method of a ClientEncryption object.

To delete or update a DEK, use one of the following mechanisms:

  • The rewrapManyDataKey method

  • Standard CRUD operations

To learn more about the rewrapManyDataKey method, see the documentation of the method for your client or driver:

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.

←  Encryption SchemasEncryption Key Management →

On this page