Docs Menu

Docs Home → Develop Applications → MongoDB Manual

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()

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

1

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:

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

2

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>"
      }
   }
)

  1. 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.

  2. Specify the KMS provider

  3. 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.

← Keys and Key Vaults
KMS Providers →

On this page