Keys and Key Vaults (original) (raw)

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

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

Your Data Encryption Key (DEK) is the key MongoDB uses to encrypt the fields in your documents. You store your DEK in a document in the Key Vault collection, encrypted with your Customer Master Key (CMK).

Your Customer Master Key is the key MongoDB uses to encrypt your Data Encryption Keys during creation. Without access to a CMK, your client application cannot decrypt the associated DEKs.

If you delete a DEK, all fields encrypted with thatDEK become permanently unreadable. If you delete a CMK, all fields encrypted with a DEKusing that CMK become permanently unreadable.

Warning

The Customer Master Key is the most sensitive key in Queryable Encryption. If yourCMK is compromised, all of your encrypted data can be decrypted. Use a remote Key Management System to store your CMK.

Important

Use a Remote Key Management Service Provider

Store your Customer Master Key on a remote Key Management System (KMS).

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

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

To view diagrams detailing how your DEK, CMK, and Key Vault collection interact in all supported KMS provider architectures, seeKMS Providers.

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:


{

  "_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 aunique index on the keyAltNames field. To check if the unique index exists, run the listIndexescommand against the Key Vault collection:


1

db.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, your application must create it before performing DEK management.

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

Tip

mongosh Feature

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

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.

Applications with read access to the Key Vault collection can retrieve encrypted Data Encryption Key (DEK)s by querying the collection. However, only applications with access to the Customer Master Key (CMK) used to encrypt a DEK can use that DEKfor 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, seeManage Users and Rolesin the MongoDB manual.

To learn how to grant your application access to your Customer Master Key, see theTutorials tutorial.

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 Queryable Encryption operations.

To specify the cluster that hosts your Key Vault collection, use thekeyVaultClient field of your client's MongoClient object. To learn more about the Queryable Encryption-specific configuration options in your client's MongoClient object, see MongoClient Options for Queryable Encryption.

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

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

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

Tip

mongosh Specific Features