Manage Customer Keys with AWS KMS

Key Concepts

MongoDB Master Key

MongoDB Master Key is an encryption key used by the MongoDB Server to encrypt the WiredTiger Storage Engine. The key isn't stored in the MongoDB database, but it's supplied externally through KMIP or a local keyfile. When the MongoDB server starts, it obtains the master key from the KMIP or local file and then stores it in memory. This key is then used to decrypt the data stored in the WiredTiger storage engine.

Atlas maintains a layer that translates requests between MongoDB Server and a CMK that you created in AWS. To translate the requests, Atlas uses the layer to request the CMK to create an encrypted data encryption key (DEK). This encrypted DEK is generated per Atlas deployment.

For example, for a three node M10+ replica set as shown in the following figure, there are three unique encrypted DEKs, one per node. Atlas stores the encrypted DEK on disk on each node in the Atlas cluster. When the cluster starts up, the Atlas layer decrypts the DEK using the customer provided encryption key and supplies this to the MongoDB Server.

Per Database Encryption Key in a MongoDB Cluster

MongoDB Server maintains a per database encryption key in the MongoDB cluster. In the preceding figure, there are three databases on the MongoDB cluster, each of which is encrypted with a unique database encryption key. Each of these keys are then encrypted with the MongoDB Master Key.

Data Encryption Key (in cloud provider terminology) or MongoDB Master Key

Atlas uses the customer provided encryption key to create an encrypted DEK. Atlas also uses a customer key management instance to decrypt this encrypted DEK and supply the resulting plaintext key to the MongoDB Server over the wire using TLS. When MongoDB Server uses this plaintext key, it refers to it as the MongoDB Master Key, whereas a cloud provider's customer key management instance might refer to it as a DEK. To learn more about DEKs, see Data Keys.

Customer Master Key (CMK)

Customer Master Key is a concept of a customer key management instance. CMKs are used to encrypt and decrypt a MongoDB Master Key (or DEK). The CMK exists only on the customer key management instance. To learn more about CMKs, see Data Keys.

Prerequisites

To enable customer-managed keys with AWS KMS for a MongoDB project, you must:

• Use an M10 or larger cluster.

• Use Cloud Backups to encrypt your backup snapshots. Legacy Backups are not supported.

• Have a symmetric AWS KMS key . To learn how to create a key, see Creating Keys in the AWS documentation.

  Note

  To ensure resilience in the event of a regional outage, configure your KMS key to be a multi-Region key.

  To learn more, see Reconfigure AWS KMS Region During an Outage.

• Have an AWS IAM role with sufficient privileges. Atlas must have permission to perform the following actions with your key:

  • DescribeKey

  • Encrypt

  • Decrypt

  Note

  If you wish to use the AWS KMS key with an AWS IAM role from a different AWS account instead of that of the IAM role which created the AWS KMS key , ensure you have sufficient privileges:

  • Add a key policy statement under the AWS KMS key to include the external AWS account.

  • Add an IAM inline policy for the IAM role in the external AWS account.

  For a comprehensive discussion of IAM roles and customer master keys, see the AWS documentation.

  After confirming the above privileges, you can follow the usual steps to configure the KMS settings in Atlas, with the following exception:

  • You must provide the full ARN for the AWS KMS key (e.g. arn:aws:kms:eu-west-2:111122223333:key/12345678-1234-1234-1234-12345678) instead of the master key ID (e.g. 12345678-1234-1234-1234-12345678) in the AWS KMS key ID field.

  To learn how to create an IAM role, see IAM Roles in the AWS documentation.

  Atlas uses the same IAM role and AWS KMS key settings for all clusters in a project for which Encryption at Rest is enabled.

• If your AWS KMS configuration requires it, allow access from Atlas IP addresses and the public IP addresses or DNS hostnames of your cluster nodes so that Atlas can communicate with your KMS. If the node IP addresses change, you must update your configuration to avoid connectivity interruptions.

Enable Role-Based Access to Your Encryption Key for a Project

Switch to Role-Based Access to Your Encryption Key for a Project

Enable Customer Key Management for an Atlas Cluster

After you Enable Role-Based Access to Your Encryption Key for a Project, you must enable customer key management for each Atlas cluster that contains data that you want to encrypt.

For new clusters, toggle the Manage your own encryption keys setting to Yes when you create the cluster.

For existing clusters:

MongoDB Master Key - MongoDB Responsibility

When you use your own cloud provider KMS, Atlas automatically rotates the MongoDB master key (or DEK) every 90 days. These keys are rotated on a rolling basis and the process does not require the data to be rewritten.

Your AWS CMK - Your Responsibility

Atlas does not automatically rotate the AWS CMK used for AWS-provided Encryption at Rest.

As a best practice, Atlas creates an alert to remind you to rotate your AWS CMK every 90 days by default when you enable Encryption at Rest for an Atlas project. You can configure the time period of this alert.

You can rotate your AWS CMK yourself or configure your AWS KMS instance to automatically rotate your CMK. If you configure automatic AWS CMK rotation, the default time period for rotation is approximately 365 days.

If you have already set up an automatic CMK rotation in AWS and don't want to receive the Atlas alert to rotate your CMK every 90 days, you can modify the default alert period to be greater than 365 days.

This page explains how to create a new key and update the CMK ID in Atlas to rotate your Atlas project CMK. This method of key rotation supports more granular control of the rotation period compared to AWS KMS automatic CMK rotation.

Procedure

Procedure

To reconfigure your AWS KMS region, complete the following steps in Atlas: