Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Encrypting Connections Using TLS

By default, a newly created Amazon DocumentDB cluster only accepts secure connections using Transport Layer Security (TLS).

Managing Your Public Key

Before you can connect using TLS, you first need to download the public key for Amazon DocumentDB. You can download the public key using the following command:

wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

When you visit this URL, you download a file named rds-combined-ca-bundle.pem. When you connect to your Amazon DocumentDB cluster, you specify the .pem file public key, as shown in this example:

mongo --ssl --host endpoint –-sslCAFile rds-combined-ca-bundle.pem --username yourMasterUsername --password yourMasterPassword

When connecting to Amazon DocumentDB using TLS, you must use the service provided public key. Amazon DocumentDB does not support customer public keys or certificates.

Managing Amazon DocumentDB Cluster TLS Settings

You can manage your Amazon DocumentDB cluster TLS settings using the AWS Management Console or AWS CLI. See the following sections to learn how to verify and modify your current TLS settings.

Using the AWS Management Console

To manage encryption using TLS and the AWS Management Console, such as identifying parameter groups, verifying the TLS value, and making needed modifications, use the following steps. You can follow the link in each step to a section where the action is explained in greater detail.

  1. Determine the cluster parameter group your cluster is using Because default cluster parameter groups cannot be modified, 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 may need to first create a custom cluster parameter group. For more information, see Creating an Amazon DocumentDB Cluster Parameter Group.

  2. Determine the current value of the tls cluster parameter

  3. 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.

  4. Rebooting an Amazon DocumentDB Instance Reboot each instance of the cluster so the change is applied to all instances in the cluster.

Determine the cluster parameter group your cluster is using

To determine the cluster parameter group for an Amazon DocumentDB cluster, use the following procedure.

To determine which cluster parameter group your cluster is using

  1. Open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. From the navigation pane, choose Clusters.

  3. From the list of clusters, choose the name of the cluster you are interested in.

  4. Scroll down to the bottom of Cluster details and locate the Cluster parameter group, then make of note of the cluster parameter group's name.

    
                              Cluster's parameter group name.

    If the name of the cluster's parameter group is default, i.e. 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:

Determine the current value of the tls cluster parameter

To determine the cluster parameter values of this cluster parameter group, follow these steps.

To determine the value of tls

  1. Open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. From the navigation pane, choose Parameter groups.

  3. From the list of cluster parameter groups, choose the name of the cluster parameter group you are interested in.

  4. Locate the Cluster parameters section then in the list of cluster parameters locate the tls cluster parameter row.

    
                              Cluster's parameter group name.

    There are four columns that are important to you at this time.

    • 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 only be applied when the instances are rebooted. Changes to dynamic cluster parameters can be applied either immediately or when the instances are rebooted.

Modify the value of the tls cluster parameter

To change the value of the tls cluster parameter, continue from the preceeding section by following these steps.

To change the value of tls

  1. Choose the button to the left of the cluster parameter's name (tls).

  2. Choose Edit.

  3. To change the value of tls, in the Modify tls dialog, choose the value you want for the cluster parameter from the dropdown list.

  4. Choose Modify cluster parameter. The change will be applied to each cluster instance when it is rebooted. For more information, see Rebooting an Amazon DocumentDB Instance.

Using the AWS CLI

To manage encryption using TLS and the AWS CLI, such as identifying parameter groups, verifying the TLS value, and making needed modifications, use the following steps. You can follow the link in each step to a section where the action is explained in greater detail.

  1. Determine the cluster parameter group your cluster is using Because default cluster parameter groups cannot be modified, 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 may need to first create a custom cluster parameter group. For more information, see Creating an Amazon DocumentDB Cluster Parameter Group.

  2. Determine the current value of the tls cluster parameter

  3. 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.

  4. Rebooting an Amazon DocumentDB Instance Reboot each instance of the cluster so the change is applied to all instances in the cluster.

Determine the cluster parameter group your cluster is using

To determine the cluster parameter group for an Amazon DocumentDB cluster, use the describe-db-clusters command with the following parameters.

Parameters

  • --db-cluster-identifier—Required. The name of the cluster of interest.

  • --query—Optional. A query that limits the output to just the fields of interest, in this case the cluster name and its cluster parameter group name.

aws docdb describe-db-clusters \ --db-cluster-identifier docdb-2019-05-07-13-57-08 \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterParameterGroup]'

Output from this operation looks something like the following (JSON format).

[ [ "docdb-2019-05-07-13-57-08", "custom3-6-param-grp" ] ]

If the name of the cluster's parameter group is default, i.e. 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:

Determine the current value of the tls cluster parameter

To get more information about this cluster parameter group, use the describe-db-cluster-parameters operation with the following parameters.

Parameters

  • --db-cluster-parameter-group-name—Required. Use the cluster parameter group name from the output of the previous command.

  • --query—Optional. A query that limits the output to just the fields of interest, in this case the ParameterName, ParameterValue, AllowedValues, and ApplyType.

aws docdb describe-db-cluster-parameters \ --db-cluster-parameter-group-name custom3-6-param-grp \ --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", "static" ], [ "ttl_monitor", "enabled", "disabled,enabled", "dynamic" ] ]

Modify the value of the tls cluster parameter

To change the value of the tls cluster parameter, use the modify-db-cluster-parameter-group operation with the following parameters.

Parameters

  • --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 only accepts secure connections using Transport Layer Security (TLS).

      • disabled—The cluster does not accept secure connections using Transport Layer Security (TLS).

    • ApplyMethod—When this modification is to be applied. For static cluster parameters, like tls, 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. See Rebooting an Amazon DocumentDB Instance.

The following code disables tls, applying the change to each DB instance when it is rebooted.

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name custom3-6-param-grp \ --parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"

The following code enables tls, applying the change to each DB instance when it is rebooted.

aws docdb modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name custom3-6-param-grp \ --parameters "ParameterName=tls,ParameterValue=enabled,ApplyMethod=pending-reboot"

Output from this operation looks something like the following (JSON format).

{ "DBClusterParameterGroupName": "custom3-6-param-grp" }