Keys and Key Vaults
On this page
Overview
In this guide, you can learn details about the following components of Queryable Encryption:
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 Queryable 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. 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.
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.
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.
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.
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, see Reasons to Use a Remote Key Management System.
To view a list of all supported KMS providers, see the KMS Providers page.
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.
To rotate some or all of the encrypted DEKs in your key vault, use
the KeyVault.rewrapManyDataKey() method. 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.
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:
{ "_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:
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 method
KeyVault.createKey() automatically creates a
unique index on the keyAltNames field if one does not exist.
To view diagrams detailing how your DEK, CMK, and Key Vault collection interact in all supported KMS provider architectures, see KMS Providers.
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 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 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 Customer Master Key, 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 Queryable Encryption 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 Queryable Encryption-specific configuration options in your
client's MongoClient object, see MongoClient Options for Queryable Encryption.
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
rewrapManyDataKeymethodStandard 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 Data Encryption Key, see the Quick Start.