Rotate and Rewrap Encryption Keys

On this page

Overview

Related Information
Procedure
Rotate your Customer Master Key on your Key Management System
Rotate your Data Encryption Keys using KeyVault.rewrapManyDataKey()

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB server.

Queryable Encryption with equality queries is generally available (GA) in MongoDB 7.0 and later. The Queryable Encryption Public Preview, released in version 6.0, is no longer supported. Data encrypted using the Public Preview is incompatible with the feature release. For more information, see Compatibility Changes in MongoDB 7.0.

In this guide, you can learn how to manage your encryption keys with a Key Management System (KMS) in your application.

Overview

This procedure shows you how to rotate encryption keys for Queryable Encryption using mongosh. Rotating DEKs consists of rewrapping them with a new Customer Master Key, so the terms "rotate" and "rewrap" are sometimes used interchangeably.

After completing this guide, you should be able to rotate your Customer Master Key (CMK) on your Key Management System, and then rewrap existing DEKs in your Key Vault collection with your new CMK.

Warning

As you rotate keys, confirm that they aren't used to encrypt any keys or data before deleting them. 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.

Related Information

For a detailed explanation of the concepts included in this procedure, refer to the topics below.

To learn more about keys and key vaults, see Keys and Key Vaults. To view a list of supported KMS providers, see the KMS Providers page.

For tutorials detailing how to set up a Queryable Encryption enabled application with each of the supported KMS providers, see the following pages:

Procedure

Rotate your Customer Master Key on your Key Management System

The process for rotating your CMK depends on your KMS provider. For details, refer to your key provider's documentation:

AWS: Rotating AWS KMS Keys
Azure: Configure cryptographic key auto-rotation in Azure Key Vault
GCP: Rotate a key

Once you rotate the CMK, MongoDB uses it to wrap all new DEKs. To re-wrap existing DEKs, continue to the following steps.

Rotate your Data Encryption Keys using `KeyVault.rewrapManyDataKey()`

The KeyVault.rewrapManyDataKey() method automatically decrypts multiple Data Encryption Keys and re-encrypts them using the specified CMK. It then updates the keys in the Key Vault collection.

The method has the following syntax:

let keyVault = db.getMongo().getKeyVault()
keyVault.rewrapManyDataKey(
   {
      "<Query filter document>"
   },
   {
      provider: "<KMS provider>",
      masterKey: {
         "<dataKeyOpts Key>" : "<dataKeyOpts Value>"
      }
   }
)

Specify a query filter document to select the keys to rotate, or omit the argument to rotate all keys in the Key Vault collection
If you specify a query filter document, but no keys match, then no keys rotate.
Specify the KMS provider
Specify the masterKey using the new CMK, or omit the argument to rotate keys using their existing CMK

Your DEKs themselves are left unchanged after re-wrapping them with the new CMK. The key rotation process is seamless, and does not interrupt your application.

Back

Keys and Key Vaults

KMS Providers