> This page location: /docs.md > /docs/management.md > /docs/atlas/create-connect-deployments.md > /docs/atlas/manage-clusters.md > /docs/atlas/customize-storage.md > /docs/atlas/security-kms-encryption.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Manage Customer Keys with AWS KMS

You can configure your Atlas project to use an AWS (Amazon Web Services) [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) for accessing your AWS (Amazon Web Services) KMS (Key Management Service) keys for Encryption at Rest. You can either use an existing role or create a new role when you enable Encryption at Rest for your project.

**Note:**

The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility)

This page covers configuring customer key management on your Atlas project for role-based access. You can also set up AWS PrivateLink in your AWS (Amazon Web Services) KMS (Key Management Service) to ensure that all traffic between Atlas and your AWS (Amazon Web Services) KMS (Key Management Service) takes place over AWS (Amazon Web Services)'s private network interfaces.

If you have not yet enabled Encryption at Rest for your new or existing Atlas project, follow the [Enable Role-Based Access for Your Encryption Key for a Project](https://www.mongodb.com/docs/atlas/security/aws-kms-over-public-network.md#std-label-aws-kms-enable-project) procedure to enable Encryption at Rest for your Atlas project. If you have an Atlas project for which you have already enabled Encryption at Rest and configured credentials-based access to your encryption keys, follow the [Switch to Role-Based Access for Your Encryption Key for a Project](https://www.mongodb.com/docs/atlas/security/aws-kms-over-public-network.md#std-label-aws-kms-switch-project) procedure to switch to role-based access to your encryption keys.

**Note: Atlas Infinite**

[Atlas Infinite](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-Atlas-Infinite) in public preview supports customer-managed keys through AWS (Amazon Web Services) KMS (Key Management Service). To learn how encryption at rest works for Atlas Infinite, see [Atlas Infinite Encryption.](https://www.mongodb.com/docs/atlas/security-encryption-at-rest-overview.md#std-label-atlas-infinite-encryption-at-rest)

You must configure customer key management for the Atlas project before enabling it on clusters in that project.

**See also:**

- [Set Up Unified AWS Access](https://www.mongodb.com/docs/atlas/security/set-up-unified-aws-access.md#std-label-set-up-unified-aws-access)

## Required Access

To configure customer key management, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project.

Users with [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access must add themselves to the project as a `Project Owner`.

## Enable Customer-Managed Keys with AWS KMS

Customer key management in Atlas follows a process called [envelope encryption](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#enveloping). This process creates multiple layers of encryption by encrypting one key with another key. To enable customer key management, Atlas uses the following encryption keys:

Customer-managed keys are encryption keys that you create, own, and manage in AWS KMS. You create the CMK (customer-managed key) in AWS KMS and connect it to Atlas at the [Project](https://www.mongodb.com/docs/atlas/organizations-projects.md#std-label-projects) level. To learn more about the CMK (customer-managed key)s used in AWS KMS, see [AWS KMS Documentation](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys).

Atlas uses this key only to encrypt the MongoDB Master Keys.

Each node in your Atlas cluster creates a MongoDB Master Key. MongoDB Master Keys are encryption keys that a MongoDB Server uses to encrypt the per-database encryption keys. Atlas saves an encrypted copy of the key locally.

This key is encrypted with the CMK (customer-managed key) and encrypts the per-database encryption keys.

Each node in your Atlas cluster also creates an encryption key per database in your cluster. Atlas uses these keys to read and write data via WiredTiger, which also encrypts and stores these keys.

This key is encrypted with the MongoDB Master Key.

### Example

Consider the following encryption hierarchy for a three-node replica set. Atlas uses the CMK (customer-managed key) from AWS KMS to encrypt a unique MongoDB Master Key for each node in the cluster. Each node also contains three databases, each of which is encrypted with a unique per-database encryption key. When the cluster starts up, Atlas decrypts the MongoDB Master Key by using the CMK (customer-managed key) from AWS KMS and supplies this to the MongoDB Server.

**Note:**

If you revoke Atlas's access to the CMK (customer-managed key), Atlas shuts down the nodes in your cluster and you can't access your data until you restore access to the CMK (customer-managed key).

![Diagram of CMK workflow with AWS KMS and Atlas](/images/aws-kms-cmk-diagram.png)

## Rotate your AWS Customer Master Key

**Note:**

This feature is not available for any of the following deployments:

- Free clusters

- Flex clusters

To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits)

### MongoDB Master Key - MongoDB Responsibility

When you use your own cloud provider KMS (Key Management Service), Atlas automatically rotates MongoDB Master Keys at least every 90 days. Your key rotation will begin during a [maintenance window](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window.md#std-label-configure-maintenance-window), if you have one configured. Deferring maintenance (either manually or automatically) may cause the key to be rotated past the 90-day mark. Keys are rotated on a rolling basis and the process does not require the data to be rewritten.

### Your AWS (Amazon Web Services) CMK (customer-managed key) - Your Responsibility

Atlas does *not* automatically rotate the AWS (Amazon Web Services) CMK (customer-managed key) used for AWS (Amazon Web Services)-provided Encryption at Rest.

As a best practice, Atlas creates an [`alert`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-AWS-encryption-key-elapsed-time-since-last-rotation-is-above--n--days) to remind you to rotate your AWS (Amazon Web Services) CMK (customer-managed key) every 90 days by default when you [enable Encryption at Rest](https://www.mongodb.com/docs/atlas/security/aws-kms-over-public-network.md#std-label-aws-enable-cluster-encryption-at-rest) for an Atlas project. You can configure the time period of this alert.

You can rotate your AWS (Amazon Web Services) CMK (customer-managed key) yourself or configure your AWS (Amazon Web Services) KMS (Key Management Service) instance to [automatically rotate](http://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) your CMK (customer-managed key). If you configure automatic AWS (Amazon Web Services) CMK (customer-managed key) rotation, the default time period for rotation is approximately 365 days.

If you have already set up an automatic CMK (customer-managed key) rotation in AWS (Amazon Web Services) and don't want to receive the Atlas alert to rotate your CMK (customer-managed key) every 90 days, you can [modify](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-configure-alerts) the default alert period to be greater than 365 days or [disable](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-disable-alert-setting) the alert.

This page explains how to create a new key and update the CMK (customer-managed key) ID in Atlas to rotate your Atlas project CMK (customer-managed key). This method of key rotation supports more granular control of the rotation period compared to AWS (Amazon Web Services) KMS (Key Management Service) automatic CMK (customer-managed key) rotation.

**Important: Cloud Backups with Encryption at Rest**

For clusters using [Encryption at Rest](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms) and [Back Up Your Cluster](https://www.mongodb.com/docs/atlas/backup/cloud-backup/overview.md#std-label-backup-cloud-provider), Atlas uses the project's CMK (customer-managed key) and AWS (Amazon Web Services) IAM (Identity and Access Management) user credentials at the time of the snapshot to automatically encrypt the snapshot data files. This is an additional layer of encryption on the existing encryption applied to all Atlas storage and snapshot volumes.

Atlas does *not* re-encrypt snapshots with the new CMK (customer-managed key) after rotation. Do *not* delete the old CMK (customer-managed key) until you check *every* backup-enabled cluster in the project for any snapshots still using that CMK (customer-managed key). Atlas deletes backups in accordance to the [Backup Scheduling, Retention, and On-Demand Snapshots](https://www.mongodb.com/docs/atlas/backup/cloud-backup/scheduling.md#std-label-cloud-provider-retention-policy). After Atlas deletes all snapshots depending on a given CMK (customer-managed key), you can delete that CMK (customer-managed key) safely.

### Procedure

1. In Atlas, go to the Advanced page for your project.

   If it's not already displayed, select the organization that contains your project from the  Organizations menu in the navigation bar.

   If it's not already displayed, select your project from the Projects menu in the navigation bar.

   In the sidebar, click Database & Network Access under the Security heading.

   In the sidebar, click Advanced.

   The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays.

2. For the Encryption at Rest using your Key Management section, click Edit .

3. Update the AWS (Amazon Web Services) CMK (customer-managed key) details.

   Enter the following information:

   | Field | Action |
   | --- | --- |
   | AWS IAM role | Select an existing AWS (Amazon Web Services) IAM role that already has access to your KMS (Key Management Service) keys, or authorize a new role and grant this role access to your KMS (Key Management Service) keys with the following permissions: [DescribeKey](http://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html); [Encrypt](http://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html); [Decrypt](http://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) To learn more, see [Role-Based Access to Your Encryption Key for a Project.](https://www.mongodb.com/docs/atlas/security/aws-kms-over-public-network.md#std-label-aws-kms-enable-project) |
   | Customer Master Key ID | Enter your AWS customer master key ID. |
   | Customer Master Key Region | Select the AWS (Amazon Web Services) region in which you created your AWS (Amazon Web Services) CMK (customer-managed key). Atlas lists only AWS (Amazon Web Services) regions that support AWS (Amazon Web Services) KMS (Key Management Service). |

   Click Save.

   Atlas displays a banner in the Atlas console during the CMK (customer-managed key) rotation process. Do **not** delete or disable the CMK (customer-managed key) until your changes have deployed.

## Reconfigure AWS KMS Region During an Outage

During a regional outage, your AWS (Amazon Web Services) KMS (Key Management Service) region might become unavailable. If you've enabled [Encryption at Rest using Customer Key Management](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-security-kms-encryption), you can perform encrypt and decrypt operations while at least one node is still available. However, if all nodes become unavailable, you can't perform cryptographic operations. A node becomes unavailable if it restarts during the outage.

To get the unavailable nodes to a healthy state, you can reconfigure your current AWS (Amazon Web Services) KMS (Key Management Service) region to an available region. To change your KMS (Key Management Service) region, your AWS (Amazon Web Services) KMS (Key Management Service) key must be a [multi-Region key](http://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview). To create a multi-Region Key, see the [AWS documentation.](http://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-create)

**Note:**

You can't convert a single-Region key to a multi-Region Key.

### Procedure

To reconfigure your AWS (Amazon Web Services) KMS (Key Management Service) region, complete the following steps in Atlas:

1. In Atlas, go to the Advanced page for your project.

   If it's not already displayed, select the organization that contains your project from the  Organizations menu in the navigation bar.

   If it's not already displayed, select your project from the Projects menu in the navigation bar.

   In the sidebar, click Database & Network Access under the Security heading.

   In the sidebar, click Advanced.

   The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays.

2. For the Encryption at Rest using your Key Management section, click Edit .

3. Verify your AWS (Amazon Web Services) CMK (customer-managed key) credentials.

   To ensure that Atlas doesn't re-encrypt your data, verify that the AWS IAM role and Customer Master Key ID reflect your existing credentials.

4. Update the Customer Master Key Region.

   Select another AWS (Amazon Web Services) region for which you have configured your multi-Region key.

5. Click Save.

## Next Steps

You can use a customer-managed key (CMK) from your AWS (Amazon Web Services) KMS (Key Management Service) over a public network or over AWS PrivateLink. To learn more, see the following:

- [Manage Customer Keys with AWS Over a Public Network](https://www.mongodb.com/docs/atlas/security/aws-kms-over-public-network.md#std-label-security-aws-kms-public-network)

- [Manage Customer Keys with AWS Over Private Endpoints](https://www.mongodb.com/docs/atlas/security/aws-kms-over-private-endpoint.md#std-label-security-aws-kms-pvt-endpoint)

### Enable Customer-Managed Keys for Search Nodes

By default, MongoDB and [search processes](https://www.mongodb.com/docs/search/query/query-ref.md#std-label-about-mongot) run on the same nodes. With this architecture, customer-managed encryption applies to your database data, but it does not apply to search indexes.

When you enable [dedicated Search Nodes](https://www.mongodb.com/docs/search/deployment/deployment-options.md#std-label-what-is-search-node), search processes run on separate nodes. This allows you to enable [Search Node Data Encryption](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-enable-search-node-encryption), so you can encrypt both database data and search indexes with the same customer-managed keys for comprehensive encryption coverage.

**Note:**

Database nodes and Search Nodes use different encryption methods with the same customer-managed keys. Database nodes use the [WiredTiger Encrypted Storage Engine](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/#encrypted-storage-engine), while Search Nodes use encryption at the disk level.

## Related Topics

- To learn more about MongoDB Encryption at Rest, see [Encryption at Rest](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/) in the MongoDB server documentation.

- To learn more about Encryption at Rest with Cloud Backups, see [Storage Engine and Cloud Backup Encryption.](https://www.mongodb.com/docs/atlas/backup/cloud-backup/cloud-backup-encryption.md#std-label-encrypted-cloud-provider-snapshot)
