Amazon DocumentDB
Developer Guide

Encrypting Data at Rest in Amazon DocumentDB

The storage encryption facility in Amazon DocumentDB (with MongoDB compatibility) provides an additional layer of data protection by helping secure your data against unauthorized access to the underlying storage. You can use the storage encryption capabilities in Amazon DocumentDB for additional data security and to meet compliance requirements for data-at-rest encryption.

You encrypt data at rest in your Amazon DocumentDB cluster by specifying the storage encryption option when you create your cluster. Storage encryption is enabled cluster-wide and is applied to all instances, including the primary instance and any replicas, and also your cluster’s storage volume. Data that is encrypted at rest includes your cluster’s data, indexes, logs, automated backups (if enabled), replicas, and snapshots.

Amazon DocumentDB uses the 256-bit Advanced Encryption Standard (AES-256) to encrypt your data. When using an Amazon DocumentDB cluster with encryption at rest enabled, you don't need to modify your application logic or client connection. Amazon DocumentDB handles encryption and decryption of your data transparently, with minimal impact on performance.

The storage encryption facility in Amazon DocumentDB is available for all instance sizes and in all AWS Regions where Amazon DocumentDB is available.

Managing Amazon DocumentDB Encryption Keys

Amazon DocumentDB uses the AWS Key Management Service (AWS KMS) to retrieve and manage encryption keys. AWS KMS combines secure, highly available hardware and software to provide a key management system scaled for the cloud. Using AWS KMS, you can create encryption keys and define the policies that control how these keys can be used. AWS KMS supports AWS CloudTrail, so you can audit key usage to verify that keys are being used appropriately.

Your AWS KMS keys can be used in combination with Amazon DocumentDB and supported AWS services such as Amazon Simple Storage Service (Amazon S3), Amazon Relational Database Service (Amazon RDS), Amazon Elastic Block Store (Amazon EBS), and Amazon Redshift. For a list of services that support AWS KMS, see How AWS Services use AWS KMS in the AWS Key Management Service Developer Guide. For information about AWS KMS, see, What is AWS Key Management Service?

If you want full control over a key, then you must create a customer managed key. You cannot delete, revoke, or rotate default keys provisioned by AWS KMS.

You can view audit logs of every action taken with a customer managed key by using AWS CloudTrail. For more information, see What Is AWS CloudTrail?

Important

If you disable the key for an encrypted Amazon DocumentDB cluster, you cannot read from or write to that cluster. When Amazon DocumentDB encounters a cluster that is encrypted by a key that it doesn't have access to, it puts the cluster into a terminal state. In this state, the cluster is no longer available, and the current state of the database can't be recovered. To restore the cluster, you must re-enable access to the encryption key for Amazon DocumentDB, and then restore the cluster from a backup.

Enabling Encryption at Rest for an Amazon DocumentDB Cluster

Important

You must enable storage encryption via the AWS CLI. Currently you cannot enable storage encryption from the AWS Management Console.

To encrypt an Amazon DocumentDB cluster, you must specify the --storage-encrypted option when creating the cluster. Amazon DocumentDB clusters do not enable storage encryption by default. Following is an example of creating an Amazon DocumentDB cluster with storage encryption enabled.

aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username yourMasterUsername \ --master-user-password yourMasterPassword \ --storage-encrypted

When you create an encrypted Amazon DocumentDB cluster, you can specify an AWS KMS key identifier, as in the following example.

For Linux, macOS, or Unix:

aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --port 27017 \ --engine docdb \ --master-username yourMasterUsername \ --master-user-password yourMasterPassword \ --storage-encrypted \ --kms-key-id key-arn-or-alias

If you don't specify an AWS KMS key identifier, Amazon DocumentDB uses the default AWS managed service customer master key (CMK). Amazon DocumentDB creates a separate CMK for each AWS Region in your AWS account. For more information, see AWS Key Management Service Concepts.

To get started on creating your own CMK, see Getting Started in the AWS Key Management Service Developer Guide.

After you create an encrypted cluster, you can't change the CMK for that cluster. Be sure to determine your encryption key requirements before you create your encrypted cluster.

Important

If Amazon DocumentDB can no longer gain access to the encryption key for a cluster—for example, when access to a key is revoked—the encrypted cluster goes into a terminal state. In this case, you can only restore the cluster from a backup. We strongly recommend that you always enable backups for encrypted clusters to guard against the loss of encrypted data in your databases.

Limitations for Amazon DocumentDB Encrypted Instances

The following limitations exist for Amazon DocumentDB encrypted clusters:

  • You can enable storage encryption for an Amazon DocumentDB cluster only at the time that it is created, not after the cluster has been created. You can create an encrypted copy of an unencrypted cluster in two ways:

    1. Create a snapshot of the unencrypted cluster, and then create a new cluster from the unencrypted snapshot while specifying an AWS KMS key ID.

    2. Create a snapshot of the unencrypted cluster, create an encrypted copy of the unencrypted snapshot, and then create a new cluster from the encrypted snapshot.

    For more information, see the following topics:

  • Amazon DocumentDB clusters with storage encryption enabled cannot be modified to disable encryption.

  • All instances in an Amazon DocumentDB cluster are encrypted with the same key.