# Data protection in Amazon DocumentDB
The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in Amazon DocumentDB (with MongoDB compatibility). As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/). For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*.
For data protection purposes, we recommend that you protect AWS account credentials and set up individual users with AWS IAM Identity Center or AWS Identity and Access Management (IAM). That way, each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
+ Use multi-factor authentication (MFA) with each account.
+ Use SSL/TLS to communicate with AWS resources. We require TLS 1.2 and recommend TLS 1.3.
+ Set up API and user activity logging with AWS CloudTrail. For information about using CloudTrail trails to capture AWS activities, see [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html) in the *AWS CloudTrail User Guide*.
+ Use AWS encryption solutions, along with all default security controls within AWS services.
+ Use advanced managed security services such as Amazon Macie, which assists in discovering and securing sensitive data that is stored in Amazon S3.
+ If you require FIPS 140-3 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/).
We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form text fields such as a **Name** field. This includes when you work with Amazon DocumentDB or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form text fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.
**Topics**
+ [
# Client-side field level encryption
](field-level-encryption.md)
+ [Encrypting data at rest](encryption-at-rest.md)
+ [
# Encrypting data in transit
](security.encryption.ssl.md)
+ [
# Key management
](security.encryption.ssl.public-key.md)
# Client-side field level encryption
Amazon DocumentDB client-side field level encryption (FLE) allows you to encrypt sensitive data in your client applications before it is transferred to a Amazon DocumentDB cluster. Sensitive data remains encrypted when it is stored and processed in a cluster and is decrypted at the client application when retrieved.
**Topics**
+ [
## Getting started
](#fle-getting-started)
+ [
## Querying in client-side FLE
](#fle-querying)
+ [
## Limitations
](#fle-limitationa)
## Getting started
The initial configuration of client-side FLE in Amazon DocumentDB is a four-step process that includes creating an encryption key, associating a role to the application, configuring the application, and defining CRUD operation with encryption options.
**Topics**
+ [
### Step 1: Create the encryption keys
](#fle-step-create-key)
+ [
### Step 2: Associate a role with the application
](#fle-step-associate-role)
+ [
### Step 3: Configure the application
](#fle-step-config-app)
+ [
### Step 4: Define a CRUD operation
](#fle-step-crud-ops)
+ [
### Example: client-side field level encryption configuration file
](#fle-config-example)
### Step 1: Create the encryption keys
Using AWS Key Management Service, create a symmetric key that is used for encrypting and decrypting the sensitive data field and provide it the necessary IAM usage permissions. AWS KMS stores the Customer Key (CK) which is used to encrypt Data Keys (DKs). We recommend storing the Customer Key in KMS to strengthen your security posture. The Data Key is the secondary key which is stored in an Amazon DocumentDB collection and is required to encrypt sensitive fields before storing the document in Amazon DocumentDB. The Customer Key encrypts the Data Key which in turn encrypts and decrypts your data. If you are using a global cluster, you can create a multi-region key that can be used by different service roles in different regions.
For more information about the AWS Key Management Service, including how to create a key, see the [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
### Step 2: Associate a role with the application
Create an IAM policy with appropriate AWS KMS permissions. This policy allows IAM identities to which it is attached to encrypt and decrypt the KMS key specified in resource field. Your application assumes this IAM role to authenticate with AWS KMS.
The policy should look similar to this:
```
{ "Effect": "Allow",
"Action": ["kms:Decrypt", "kms:Encrypt"],
"Resource": "Customer Key ARN"
}
```
### Step 3: Configure the application
By now you defined a Customer Key in AWS KMS and created an IAM role and provided it the right IAM permissions to access the Customer Key. Import the required packages.
```
import boto3
import json
import base64
from pymongo import MongoClient
from pymongo.encryption import (Algorithm,
ClientEncryption)
```
```
# create a session object:
my_session = boto3.session.Session()
# get access_key and secret_key programmatically using get_frozen_credentials() method:
current_credentials = my_session.get_credentials().get_frozen_credentials()
```
1. Specify ‘aws’ as KMS provider type and input your account credentials which were retrieved in the previous step.
```
provider = "aws"
kms_providers = {
provider: {
"accessKeyId": current_credentials.access_key,
"secretAccessKey": current_credentials.secret_key
}
}
```
1. Specify the customer key which is used to encrypt the data key:
```
customer_key = {
“region”: “AWS region of the customer_key”,
“key”: “customer_key ARN”
}
key_vault_namespace = "encryption.dataKeys"
key_alt_name = 'TEST_DATA_KEY'
```
1. Configure the MongoClient object:
```
client = MongoClient(connection_string)
coll = client.test.coll
coll.drop()
client_encryption = ClientEncryption(
kms_providers, # pass in the kms_providers variable from the previous step
key_vault_namespace = key_vault_namespace,
client,
coll.codec_options
)
```
1. Generate your Data Key:
```
data_key_id = client_encryption.create_data_key(provider,
customer_key,
key_alt_name = [key_alt_name])
```
1. Retrieve your existing Data Key:
```
data_key = DataKey("aws",
master_key = customer_key)
key_id = data_key["_id"]
data_key_id = client[key_vault_namespace].find_one({"_id": key_id})
```
### Step 4: Define a CRUD operation
Define the CRUD operation with encryption options.
1. Define the collection to write/read/delete a single document:
```
coll = client.gameinfo.users
```
1. Explicit Encryption - encrypt fields and insert:
**Note**
Exactly one of "key\$1id" or "key\$1alt\$1name" must be provided.
```
encrypted_first_name = client_encryption.encrypt(
"Jane",
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
key_alt_name=data_key_id
)
encrypted_last_name = client_encryption.encrypt(
"Doe",
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
key_alt_name=data_key_id
)
encrypted_dob = client_encryption.encrypt(
"1990-01-01",
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Random,
key_alt_name=data_key_id
)
coll.insert_one(
{"gamerTag": "jane_doe90",
"firstName": encrypted_first_name,
"lastName": encrypted_last_name,
"dateOfBirth":encrypted_dob,
"Favorite_games":["Halo","Age of Empires 2","Medal of Honor"]
})
```
### Example: client-side field level encryption configuration file
In the following example, replace each *user input placeholder* with your own information.
```
# import python packages:
import boto3
import json
import base64
from pymongo import MongoClient
from pymongo.encryption import (Algorithm,
ClientEncryption)
def main():
# create a session object:
my_session = boto3.session.Session()
# get aws_region from session object:
aws_region = my_session.region_name
# get access_key and secret_key programmatically using get_frozen_credentials() method:
current_credentials = my_session.get_credentials().get_frozen_credentials()
provider = "aws"
# define the kms_providers which is later used to create the Data Key:
kms_providers = {
provider: {
"accessKeyId": current_credentials.access_key,
"secretAccessKey": current_credentials.secret_key
}
}
# enter the kms key ARN. Replace the example ARN value.
kms_arn = "arn:aws:kms:us-east-1:123456789:key/abcd-efgh-ijkl-mnop"
customer_key = {
"region": aws_region,
"key":kms_arn
}
# secrets manager is used to strore and retrieve user credentials for connecting to an Amazon DocumentDB cluster.
# retrieve the secret using the secret name. Replace the example secret key.
secret_name = "/dev/secretKey"
docdb_credentials = json.loads(my_session.client(service_name = 'secretsmanager', region_name = "us-east-1").get_secret_value(SecretId = secret_name)['SecretString'])
connection_params = '/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false'
conn_str = 'mongodb://' + docdb_credentials["username"] + ':' + docdb_credentials["password"] + '@' + docdb_credentials["host"] + ':' + str(docdb_credentials["port"]) + connection_params
client = MongoClient(conn_str)
coll = client.test.coll
coll.drop()
# store the encryption data keys in a key vault collection (having naming convention as db.collection):
key_vault_namespace = "encryption.dataKeys"
key_vault_db_name, key_vault_coll_name = key_vault_namespace.split(".", 1)
# set up the key vault (key_vault_namespace) for this example:
key_vault = client[key_vault_db_name][key_vault_coll_name]
key_vault.drop()
key_vault.create_index("keyAltNames", unique=True)
client_encryption = ClientEncryption(
kms_providers,
key_vault_namespace,
client,
coll.codec_options)
# create a new data key for the encrypted field:
data_key_id = client_encryption.create_data_key(provider, master_key=customer_key, key_alt_names=["some_key_alt_name"], key_material = None)
# explicitly encrypt a field:
encrypted_first_name = client_encryption.encrypt(
"Jane",
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
key_id=data_key_id
)
coll.insert_one(
{"gamerTag": "jane_doe90",
"firstName": encrypted_first_name
})
doc = coll.find_one()
print('Encrypted document: %s' % (doc,))
# explicitly decrypt the field:
doc["encryptedField"] = client_encryption.decrypt(doc["encryptedField"])
print('Decrypted document: %s' % (doc,))
# cleanup resources:
client_encryption.close()
client.close()
if __name__ == "__main__":
main()
```
## Querying in client-side FLE
Amazon DocumentDB supports point equality queries with client-side FLE. Inequality and comparison queries can return inaccurate results. Read and write operations may have unexpected or incorrect behavior as compared to issuing that same operation against the decrypted value.
For example, to query filters for documents where gamerscore is greater than 500:
```
db.users.find( {
"gamerscore" : { $gt : 500 }
})
```
The client uses an explicit encryption method to encrypt the query value:
```
encrypted_gamerscore_filter = client_encryption.encrypt(
500,
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
key_alt_name=data_key_id
)
db.users.find( {
"gamerscore" : { $gt : encrypted_gamerscore_filter }
} )
```
In the find operation, Amazon DocumentDB compares the encrypted value of 500 to the encrypted field values stored in each document using the greater than inequality check. The inequality check in the find operation may return a different result when performed using decrypted data and value, even though the operation succeeds in generating results.
## Limitations
The following limitations apply to Amazon DocumentDB client-side field level encrytion:
+ Amazon DocumentDB supports only point equality queries. Inequality and comparison queries can return inaccurate results. Read and write operations may have unexpected or incorrect behavior as compared to issuing that same operation against the decrypted value. To query filters for documents where gamerscore is greater than 500.
```
db.users.find( {
"gamerscore" : { $gt : 500 }
})
```
The client uses an explicit encryption method to encrypt the query value.
```
encrypted_gamerscore_filter = client_encryption.encrypt(
500,
Algorithm.AEAD_AES_256_CBC_HMAC_SHA_512_Deterministic,
key_alt_name=data_key_id
)
db.users.find({
"gamerscore" : { $gt : encrypted_gamerscore_filter }
})
```
In the find operation, Amazon DocumentDB compares the encrypted value of 500 to the encrypted field values stored in each document using the greater than inequality check. The inequality check in the find operation may return a different result when performed using decrypted data and value, even though the operation succeeds in generating results.
+ Amazon DocumentDB does not support explicit client-side FLE from the Mongo Shell. However, the feature works with any of our supported drivers.
# Encrypting Amazon DocumentDB data at rest
**Note**
AWS KMS is replacing the term *customer master key (CMK)* with *AWS KMS key* and *KMS key*. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term.
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. It is also applied to your cluster’s storage volume, data, indexes, logs, automated backups, and snapshots.
Amazon DocumentDB uses the 256-bit Advanced Encryption Standard (AES-256) to encrypt your data using encryption keys stored in AWS Key Management Service (AWS KMS). 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.
Amazon DocumentDB integrates with AWS KMS and uses a method known as envelope encryption to protect your data. When an Amazon DocumentDB cluster is encrypted with an AWS KMS, Amazon DocumentDB asks AWS KMS to use your KMS key to [ generate a ciphertext data key](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) to encrypt the storage volume. The ciphertext data key is encrypted using the KMS key that you define, and is stored along with the encrypted data and storage metadata. When Amazon DocumentDB needs to access your encrypted data, it requests AWS KMS to decrypt the ciphertext data key using your KMS key and caches the plaintext data key in memory to efficiently encrypt and decrypt data in the storage volume.
The storage encryption facility in Amazon DocumentDB is available for all supported instance sizes and in all AWS Regions where Amazon DocumentDB is available.
## Enabling encryption at rest for an Amazon DocumentDB cluster
You can enable or disable encryption at rest on an Amazon DocumentDB cluster when the cluster is provisioned using either the AWS Management Console or the AWS Command Line Interface (AWS CLI). Clusters that you create using the console have encryption at rest enabled by default. Clusters that you create using the AWS CLI have encryption at rest disabled by default. Therefore, you must explicitly enable encryption at rest using the `--storage-encrypted` parameter. In either case, after the cluster is created, you can't change the encryption at rest option.
Amazon DocumentDB uses AWS KMS to retrieve and manage encryption keys, and to define the policies that control how these keys can be used. If you don't specify an AWS KMS key identifier, Amazon DocumentDB uses the default AWS managed service KMS key. Amazon DocumentDB creates a separate KMS key for each AWS Region in your AWS account. For more information, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html).
To get started on creating your own KMS key, see [ Getting Started](https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html) in the *AWS Key Management Service Developer Guide*.
**Important**
You must use a symmetric encryption KMS key to encrypt your cluster as Amazon DocumentDB supports only symmetric encryption KMS keys. Do not use an asymmetric KMS key to attempt to encrypt the data in your Amazon DocumentDB clusters. For more information, see [ Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
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. For Amazon DocumentDB, backups are always enabled for 1 day.
In addition, if you disable the key for an encrypted Amazon DocumentDB cluster, you will eventually lose read and write access 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.
**Important**
You cannot change the KMS key for an encrypted cluster after you have already created it. Be sure to determine your encryption key requirements before you create your encrypted cluster.
------
#### [ Using the AWS Management Console ]
You specify the encryption at rest option when you create a cluster. Encryption at rest is enabled by default when you create a cluster using the AWS Management Console. It can't be changed after the cluster is created.
**To specify the encryption at rest option when creating your cluster**
1. Create an Amazon DocumentDB cluster as described in the [Getting Started](https://docs.aws.amazon.com/documentdb/latest/developerguide/connect-ec2.launch-cluster.html) section. However, in step 6, do not choose **Create cluster**.
1. Under the **Authentication** section, choose **Show advanced settings**.
1. Scroll down to the **Encryption-at-rest** section.
1. Choose the option that you want for encryption at rest. Whichever option you choose, you can't change it after the cluster is created.
+ To encrypt data at rest in this cluster, choose **Enable encryption**.
+ If you don't want to encrypt data at rest in this cluster, choose **Disable encryption**.
1. Choose the primary key that you want. Amazon DocumentDB uses the AWS Key Management Service (AWS KMS) to retrieve and manage encryption keys, and to define the policies that control how these keys can be used. If you don't specify an AWS KMS key identifier, Amazon DocumentDB uses the default AWS managed service KMS key. For more information, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html).
**Note**
After you create an encrypted cluster, you can't change the KMS key for that cluster. Be sure to determine your encryption key requirements before you create your encrypted cluster.
1. Complete the other sections as needed, and create your cluster.
------
#### [ Using the AWS CLI ]
To encrypt an Amazon DocumentDB cluster using the AWS CLI, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html) command and specify the `--storage-encrypted` option. Amazon DocumentDB clusters created using the AWS CLI do not enable storage encryption by default.
The following example creates an Amazon DocumentDB cluster with storage encryption enabled.
In the following examples, replace each *user input placeholder* with your cluster's information.
**Example**
For Linux, macOS, or Unix:
```
aws docdb create-db-cluster \
--db-cluster-identifier mydocdbcluster \
--port 27017 \
--engine docdb \
--master-username SampleUser1 \
--master-user-password primaryPassword \
--storage-encrypted
```
For Windows:
```
aws docdb create-db-cluster ^
--db-cluster-identifier SampleUser1 ^
--port 27017 ^
--engine docdb ^
--master-username SampleUser1 ^
--master-user-password primaryPassword ^
--storage-encrypted
```
When you create an encrypted Amazon DocumentDB cluster, you can specify an AWS KMS key identifier, as in the following example.
**Example**
For Linux, macOS, or Unix:
```
aws docdb create-db-cluster \
--db-cluster-identifier SampleUser1 \
--port 27017 \
--engine docdb \
--master-username primaryUsername \
--master-user-password yourPrimaryPassword \
--storage-encrypted \
--kms-key-id key-arn-or-alias
```
For Windows:
```
aws docdb create-db-cluster ^
--db-cluster-identifier SampleUser1 ^
--port 27017 ^
--engine docdb ^
--master-username SampleUser1 ^
--master-user-password primaryPassword ^
--storage-encrypted ^
--kms-key-id key-arn-or-alias
```
**Note**
After you create an encrypted cluster, you can't change the KMS key for that cluster. Be sure to determine your encryption key requirements before you create your encrypted cluster.
------
## Limitations for Amazon DocumentDB encrypted clusters
The following limitations exist for Amazon DocumentDB encrypted clusters.
+ You can enable or disable encryption at rest for an Amazon DocumentDB cluster only at the time that it is created, not after the cluster has been created. However, you can create an encrypted copy of an unencrypted cluster by creating a snapshot of the unencrypted cluster, and then restoring the unencrypted snapshot as a new cluster while specifying the encryption at rest option.
For more information, see the following topics:
+ [Creating a manual cluster snapshot](backup_restore-create_manual_cluster_snapshot.md)
+ [Restoring from a cluster snapshot](backup_restore-restore_from_snapshot.md)
+ [Copying Amazon DocumentDB cluster snapshots](backup_restore-copy_cluster_snapshot.md)
+ Amazon DocumentDB clusters with storage encryption enabled can't be modified to disable encryption.
+ All instances, automated backups, snapshots, and indexes in an Amazon DocumentDB cluster are encrypted with the same KMS key.
# Encrypting data in transit
You can use Transport Layer Security (TLS) to encrypt the connection between your application and an Amazon DocumentDB cluster. By default, encryption in transit is enabled for newly created Amazon DocumentDB clusters. It can optionally be disabled when the cluster is created, or at a later time. When encryption in transit is enabled, secure connections using TLS are required to connect to the cluster. For more information connecting to Amazon DocumentDB using TLS, see [Connecting programmatically to Amazon DocumentDB](connect_programmatically.md).
## Managing Amazon DocumentDB cluster TLS settings
Encryption in transit for an Amazon DocumentDB cluster is managed via the TLS parameter in a [cluster parameter group](https://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups.html). You can manage your Amazon DocumentDB cluster TLS settings using the AWS Management Console or the AWS Command Line Interface (AWS CLI). See the following sections to learn how to verify and modify your current TLS settings.
------
#### [ Using the AWS Management Console ]
Follow these steps to perform management tasks for TLS encryption using the console—such as identifying parameter groups, verifying the TLS value, and making needed modifications.
**Note**
Unless you specify differently when you create a cluster, your cluster is created with the default cluster parameter group. The parameters in the `default` cluster parameter group can't be modified (for example, `tls` enabled/disabled). So if your cluster is using a `default` cluster parameter group, you need to modify the cluster to use a non-default cluster parameter group. First, you might need to create a custom cluster parameter group. For more information, see [Creating Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-create.md).
1. **Determine the cluster parameter group that your cluster is using.**
1. Open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Clusters**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Note that in the **Clusters** navigation box, the column **Cluster Identifier** shows both clusters and instances. Instances are listed underneath clusters. See the screenshot below for reference.
![\[Image of the Clusters navigation box showing a list of existing cluster links and their corresponding instance links.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/clusters.png)
1. Choose the cluster that you're interested in.
1. Choose the **Configuration** tab and scroll down to the bottom of **Cluster details** and locate the **Cluster parameter group**. Note the name of the cluster parameter group.
If the name of the cluster's parameter group is `default` (for example, `default.docdb3.6`), you must create a custom cluster parameter group and make it the cluster's parameter group before you continue. For more information, see the following:
1. [Creating Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-create.md) — If you don't have a custom cluster parameter group that you can use, create one.
1. [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md) — Modify your cluster to use the custom cluster parameter group.
1. **Determine the current value of the `tls` cluster parameter.**
1. Open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Parameter groups**.
1. In the list of cluster parameter groups, choose the name of the cluster parameter group you are interested in.
1. Locate the **Cluster parameters** section. In the list of cluster parameters, locate the `tls` cluster parameter row. At this point, the following four columns are important:
+ **Cluster parameter name** — The name of the cluster parameters. For managing TLS, you're interested in the `tls` cluster parameter.
+ **Values** — The current value of each cluster parameter.
+ **Allowed values** — A list of values that can be applied to a cluster parameter.
+ **Apply type** — Either **static** or **dynamic**. Changes to static cluster parameters can be applied only when the instances are rebooted. Changes to dynamic cluster parameters can be applied either immediately or when the instances are rebooted.
1. **Modify the value of the `tls` cluster parameter.**
If the value of `tls` is not what is needs to be, modify its value for this cluster parameter group. To change the value of the `tls` cluster parameter, continue from the preceding section by following these steps.
1. Choose the button to the left of the cluster parameter's name (`tls`).
1. Choose **Edit**.
1. To change the value of `tls`, in the **Modify `tls`** dialog box, choose the value that you want for the cluster parameter in the drop-down list.
Valid values are:
+ **disabled** — Disables TLS
+ **enabled** — Enables TLS versions 1.0 through 1.3.
+ **fips-140-3** — Enables TLS with FIPS. The cluster only accepts secure connections per the requirements of the Federal Information Processing Standards (FIPS) publication 140-3. This is only supported starting with Amazon DocumentDB 5.0 (engine version 3.0.3727) clusters in these regions: ca-central-1, us-west-2, us-east-1, us-east-2, us-gov-east-1, us-gov-west-1.
+ **tls1.2\$1** — Enables TLS version 1.2 and above. This is only supported starting with Amazon DocumentDB 4.0 (engine version 2.0.10980) and Amazon DocumentDB (engine version 3.0.11051).
+ **tls1.3\$1** — Enables TLS version 1.3 and above. This is only supported starting with Amazon DocumentDB 4.0 (engine version 2.0.10980) and Amazon DocumentDB (engine version 3.0.11051).
![\[Image of a cluster-specific Modify TLS dialog box.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/modify-tls.png)
1. Choose **Modify cluster parameter**. The change is applied to each cluster instance when it is rebooted.
1. **Reboot the Amazon DocumentDB instance.**
Reboot each instance of the cluster so that the change is applied to all instances in the cluster.
1. Open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Instances**.
1. To specify an instance to reboot, locate the instance in the list of instances, and choose the button to the left of its name.
1. Choose **Actions**, and then **Reboot**. Confirm that you want to reboot by choosing **Reboot**.
------
#### [ Using the AWS CLI ]
Follow these steps to perform management tasks for TLS encryption using the AWS CLI—such as identifying parameter groups, verifying the TLS value, and making needed modifications.
**Note**
Unless you specify differently when you create a cluster, the cluster is created with the default cluster parameter group. The parameters in the `default` cluster parameter group can't be modified (for example, `tls` enabled/disabled). So if your cluster is using a `default` cluster parameter group, you need to modify the cluster to use a non-default cluster parameter group. You might need to first create a custom cluster parameter group. For more information, see [Creating Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-create.md).
1. **Determine the cluster parameter group that your cluster is using.**
Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html) command with the following options:
+ `--db-cluster-identifier`
+ `--query`
In the following example, replace each *user input placeholder* with your cluster's information.
```
aws docdb describe-db-clusters \
--db-cluster-identifier mydocdbcluster \
--query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'
```
Output from this operation looks something like the following (JSON format):
```
[
[
"mydocdbcluster",
"myparametergroup"
]
]
```
If the name of the cluster's parameter group is `default` (for example, `default.docdb3.6`), you must have a custom cluster parameter group and make it the cluster's parameter group before you continue. For more information, see the following topics:
1. [Creating Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-create.md) — If you don't have a custom cluster parameter group that you can use, create one.
1. [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md) — Modify your cluster to use the custom cluster parameter group.
1. **Determine the current value of the `tls` cluster parameter.**
To get more information about this cluster parameter group, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-cluster-parameters.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-cluster-parameters.html) command with the following options:
+ `--db-cluster-parameter-group-name`
+ `--query`
Limits the output to just the fields of interest: `ParameterName`, `ParameterValue`,`AllowedValues`, and `ApplyType`.
In the following example, replace each *user input placeholder* with your cluster's information.
```
aws docdb describe-db-cluster-parameters \
--db-cluster-parameter-group-name myparametergroup \
--query 'Parameters[*].[ParameterName,ParameterValue,AllowedValues,ApplyType]'
```
Output from this operation looks something like the following (JSON format):
```
[
[
"audit_logs",
"disabled",
"enabled,disabled",
"dynamic"
],
[
"tls",
"disabled",
"disabled,enabled,fips-140-3,tls1.2+,tls1.3+",
"static"
],
[
"ttl_monitor",
"enabled",
"disabled,enabled",
"dynamic"
]
]
```
1. **Modify the value of the `tls` cluster parameter.**
If the value of `tls` is not what it needs to be, modify its value for this cluster parameter group. To change the value of the `tls` cluster parameter, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster-parameter-group.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster-parameter-group.html) command with the following options:
+ `--db-cluster-parameter-group-name` — Required. The name of the cluster parameter group to modify. This cannot be a `default.*` cluster parameter group.
+ `--parameters` — Required. A list of the cluster parameter group's parameters to modify.
+ `ParameterName` — Required. The name of the cluster parameter to modify.
+ `ParameterValue` — Required. The new value for this cluster parameter. Must be one of the cluster parameter's `AllowedValues`.
+ `enabled` — The cluster accepts secure connections using TLS version 1.0 through 1.3.
+ `disabled` — The cluster does not accept secure connections using TLS.
+ `fips-140-3` — The cluster only accepts secure connections per the requirements of the Federal Information Processing Standards (FIPS) publication 140-3. This is only supported starting with Amazon DocumentDB 5.0 (engine version 3.0.3727) clusters in these regions: ca-central-1, us-west-2, us-east-1, us-east-2, us-gov-east-1, us-gov-west-1.
+ `tls1.2+` — The cluster accepts secure connections using TLS version 1.2 and above. This is only supported starting with Amazon DocumentDB 4.0 (engine version 2.0.10980) and Amazon DocumentDB 5.0 (engine version 3.0.11051).
+ `tls1.3+` — The cluster accepts secure connections using TLS version 1.3 and above. This is only supported starting with Amazon DocumentDB 4.0 (engine version 2.0.10980) and Amazon DocumentDB 5.0 (engine version 3.0.11051).
+ `ApplyMethod` — When this modification is to be applied. For static cluster parameters like `tle`, this value must be `pending-reboot`.
+ `pending-reboot` — Change is applied to an instance only after it is rebooted. You must reboot each cluster instance individually for this change to take place across all of the cluster's instances.
In the following examples, replace each *user input placeholder* with your cluster's information.
The following code *disables* `tls`, applying the change to each instance when it is rebooted.
```
aws docdb modify-db-cluster-parameter-group \
--db-cluster-parameter-group-name myparametergroup \
--parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"
```
The following code *enables* `tls` (version 1.0 through 1.3) applying the change to each instance when it is rebooted.
```
aws docdb modify-db-cluster-parameter-group \
--db-cluster-parameter-group-name myparametergroup \
--parameters "ParameterName=tls,ParameterValue=enabled,ApplyMethod=pending-reboot"
```
The following code *enables* TLS with `fips-140-3`, applying the change to each instance when it is rebooted.
```
aws docdb modify-db-cluster-parameter-group \
‐‐db-cluster-parameter-group-name myparametergroup2 \
‐‐parameters "ParameterName=tls,ParameterValue=fips-140-3,ApplyMethod=pending-reboot"
```
Output from this operation looks something like the following (JSON format):
```
{
"DBClusterParameterGroupName": "myparametergroup"
}
```
1. **Reboot your Amazon DocumentDB instance.**
Reboot each instance of the cluster so that the change is applied to all instances in the cluster. To reboot an Amazon DocumentDB instance, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/reboot-db-instance.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/reboot-db-instance.html) command with the following option:
+ `--db-instance-identifier`
The following code reboots the instance `mydocdbinstance`.
In the following examples, replace each *user input placeholder* with your cluster's information.
**Example**
For Linux, macOS, or Unix:
```
aws docdb reboot-db-instance \
--db-instance-identifier mydocdbinstance
```
For Windows:
```
aws docdb reboot-db-instance ^
--db-instance-identifier mydocdbinstance
```
Output from this operation looks something like the following (JSON format):
```
{
"DBInstance": {
"AutoMinorVersionUpgrade": true,
"PubliclyAccessible": false,
"PreferredMaintenanceWindow": "fri:09:32-fri:10:02",
"PendingModifiedValues": {},
"DBInstanceStatus": "rebooting",
"DBSubnetGroup": {
"Subnets": [
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1a"
},
"SubnetIdentifier": "subnet-4e26d263"
},
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1c"
},
"SubnetIdentifier": "subnet-afc329f4"
},
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1e"
},
"SubnetIdentifier": "subnet-b3806e8f"
},
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1d"
},
"SubnetIdentifier": "subnet-53ab3636"
},
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1b"
},
"SubnetIdentifier": "subnet-991cb8d0"
},
{
"SubnetStatus": "Active",
"SubnetAvailabilityZone": {
"Name": "us-east-1f"
},
"SubnetIdentifier": "subnet-29ab1025"
}
],
"SubnetGroupStatus": "Complete",
"DBSubnetGroupDescription": "default",
"VpcId": "vpc-91280df6",
"DBSubnetGroupName": "default"
},
"PromotionTier": 2,
"DBInstanceClass": "db.r5.4xlarge",
"InstanceCreateTime": "2018-11-05T23:10:49.905Z",
"PreferredBackupWindow": "00:00-00:30",
"KmsKeyId": "arn:aws:kms:us-east-1:012345678901:key/0961325d-a50b-44d4-b6a0-a177d5ff730b",
"StorageEncrypted": true,
"VpcSecurityGroups": [
{
"Status": "active",
"VpcSecurityGroupId": "sg-77186e0d"
}
],
"EngineVersion": "3.6.0",
"DbiResourceId": "db-SAMPLERESOURCEID",
"DBInstanceIdentifier": "mydocdbinstance",
"Engine": "docdb",
"AvailabilityZone": "us-east-1a",
"DBInstanceArn": "arn:aws:rds:us-east-1:012345678901:db:sample-cluster-instance-00",
"BackupRetentionPeriod": 1,
"Endpoint": {
"Address": "mydocdbinstance.corcjozrlsfc.us-east-1.docdb.amazonaws.com",
"Port": 27017,
"HostedZoneId": "Z2R2ITUGPM61AM"
},
"DBClusterIdentifier": "mydocdbcluster"
}
}
```
It takes a few minutes for your instance to reboot. You can use the instance only when its status is *available*. You can monitor the instance's status using the console or AWS CLI. For more information, see [Monitoring an Amazon DocumentDB instance's status](monitoring_docdb-instance_status.md).
------
# Key management
Amazon DocumentDB uses 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](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html) in the *AWS Key Management Service Developer Guide*. For information about AWS KMS, see [What is AWS Key Management Service?](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)