In this guide, you can learn how to manage your encryption keys with a Key Management System (KMS) in your application.
Tip
Rotate and Rewrap
Rotating DEKs consists of rewrapping them with a new Customer Master Key. This guide uses the terms "rotate" and "rewrap" interchangeably.
Overview
This procedure shows you how to rotate encryption keys for Queryable Encryption.
After completing this guide, you can 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 other keys or data before deleting them. Keep your previous CMK enabled on your KMS until you rewrap every DEK that uses it. 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 Encryption 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 Overview: Enable Queryable Encryption.
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:
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 by using KeyVault.rewrapManyDataKey()
The KeyVault.rewrapManyDataKey() method automatically decrypts multiple DEKs and re-encrypts them by using the specified CMK. The method 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
masterKeyby using the new CMK, or omit the argument to rotate keys by using their existing CMK.
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:
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 by using ClientEncryption.RewrapManyDataKey()
The ClientEncryption.RewrapManyDataKey() method automatically decrypts multiple DEKs and re-encrypts them by using the specified CMK. The method then updates the keys in the Key Vault collection.
The following example rewraps the keys that match the specified filter:
var keyVaultClient = new MongoClient( "<connection string URI>"); var clientEncryptionOptions = new ClientEncryptionOptions( keyVaultClient: keyVaultClient, keyVaultNamespace: keyVaultNamespace, kmsProviders: kmsProviders); using var clientEncryption = new ClientEncryption(clientEncryptionOptions); var filter = Builders<BsonDocument>.Filter.Eq( "<filter field>", "<filter value>"); var rewrapManyDataKeyOptions = new RewrapManyDataKeyOptions( provider: "<KMS provider>", masterKey: new BsonDocument { { "<dataKeyOpts Key>", "<dataKeyOpts Value>" } }); var result = clientEncryption.RewrapManyDataKey( filter, rewrapManyDataKeyOptions, CancellationToken.None);
Specify a query filter document to select the keys to rotate. To rotate all keys in the Key Vault collection, pass an empty filter.
If you specify a query filter document, but no keys match, then no keys rotate.
Specify the KMS provider.
Specify the
masterKeyby using the new CMK, or omit it to rotate keys by using their existing CMK.
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:
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 by using ClientEncryption.rewrap_many_data_key()
The ClientEncryption.rewrap_many_data_key() method automatically decrypts multiple DEKs and re-encrypts them by using the specified CMK. The method then updates the keys in the Key Vault collection.
The following example rewraps the keys that match the specified filter:
key_vault_client = MongoClient("<connection string URI>") client_encryption = ClientEncryption( kms_providers, key_vault_namespace, key_vault_client, CodecOptions(uuid_representation=STANDARD), ) result = client_encryption.rewrap_many_data_key( filter={"<filter field>": "<filter value>"}, provider="<KMS provider>", master_key={"<dataKeyOpts Key>": "<dataKeyOpts Value>"}, )
Specify a query filter document to select the keys to rotate. To rotate all keys in the Key Vault collection, pass an empty filter.
If you specify a query filter document, but no keys match, then no keys rotate.
Specify the KMS provider.
Specify the
master_keyby using the new CMK, or omit it to rotate keys by using their existing CMK.
Your DEKs themselves are left unchanged after rewrapping them with the new CMK. The key rotation process is seamless, and does not interrupt your application.