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.

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

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.

  1. Determine the cluster parameter group that your cluster is using.

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

    2. 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 (Encrypting Data in Transit - 图1) in the upper-left corner of the page.

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

      Encrypting Data in Transit - 图2

    4. Choose the cluster that you’re interested in.

    5. 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 — If you don’t have a custom cluster parameter group that you can use, create one.

      2. Modifying an Amazon DocumentDB Cluster — Modify your cluster to use the custom cluster parameter group.

  2. Determine the current value of the tls cluster parameter.

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

    2. In the navigation pane, choose Parameter groups.

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

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

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

    2. Choose Edit.

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

    4. Choose Modify cluster parameter. The change is applied to each cluster instance when it is rebooted.

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

    2. In the navigation pane, choose Instances.

    3. To specify an instance to reboot, locate the instance in the list of instances, and choose the button to the left of its name.

    4. Choose Actions, and then Reboot. Confirm that you want to reboot by choosing Reboot.

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.

  1. Determine the cluster parameter group that your cluster is using.

    Use the describe-db-clusters command with the following 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.

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

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

    1. [
    2.        [
    3.            "docdb-2019-05-07-13-57-08",
    4.            "custom3-6-param-grp"
    5.        ]
    6. ]

    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 — If you don’t have a custom cluster parameter group that you can use, create one.

    2. Modifying an Amazon DocumentDB Cluster — Modify your cluster to use the custom cluster parameter group.

  2. 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:

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

    1. aws docdb describe-db-cluster-parameters \
    2.     --db-cluster-parameter-group-name custom3-6-param-grp \
    3.     --query 'Parameters[*].[ParameterName,ParameterValue,AllowedValues,ApplyType]'

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

    1. [
    2.     [
    3.         "audit_logs",
    4.         "disabled",
    5.         "enabled,disabled",
    6.         "dynamic"
    7.     ],
    8.     [
    9.         "tls",
    10.         "disabled",
    11.         "disabled,enabled",
    12.         "static"
    13.     ],
    14.     [
    15.         "ttl_monitor",
    16.         "enabled",
    17.         "disabled,enabled",
    18.         "dynamic"
    19.     ]
    20. ]

  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. To change the value of the tls cluster parameter, use the modify-db-cluster-parameter-group operation with the following 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 TLS.

        • disabled — The cluster does not accept secure connections using TLS.

      • 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.
  1. The following code *disables* `tls`, applying the change to each DB instance when it is rebooted.
  3. ```
  4. aws docdb modify-db-cluster-parameter-group \
  5.     --db-cluster-parameter-group-name custom3-6-param-grp \
  6.     --parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"
  7. ```
  9. The following code *enables* `tls`, applying the change to each DB instance when it is rebooted.
  11. ```
  12. aws docdb modify-db-cluster-parameter-group \
  13.     --db-cluster-parameter-group-name custom3-6-param-grp \
  14.     --parameters "ParameterName=tls,ParameterValue=enabled,ApplyMethod=pending-reboot"
  16. ```
  18. Output from this operation looks something like the following (JSON format).
  20. ```
  21. {
  22.     "DBClusterParameterGroupName": "custom3-6-param-grp"
  23. }
  25. ```

  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, use the reboot-db-instance operation with the following parameter:

    • --db-instance-identifier — Required. The identifier for the instance to be rebooted.

    The following code reboots the instance sample-db-instance.

    For Linux, macOS, or Unix:

    1. aws docdb reboot-db-instance \
    2.        --db-instance-identifier sample-db-instance

    For Windows:

    1. aws docdb reboot-db-instance ^
    2.        --db-instance-identifier sample-db-instance

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

    1. {
    2.     "DBInstance": {
    3.         "AutoMinorVersionUpgrade": true,
    4.         "PubliclyAccessible": false,
    5.         "PreferredMaintenanceWindow": "fri:09:32-fri:10:02",
    6.         "PendingModifiedValues": {},
    7.         "DBInstanceStatus": "rebooting",
    8.         "DBSubnetGroup": {
    9.             "Subnets": [
    10.                 {
    11.                     "SubnetStatus": "Active",
    12.                     "SubnetAvailabilityZone": {
    13.                         "Name": "us-east-1a"
    14.                     },
    15.                     "SubnetIdentifier": "subnet-4e26d263"
    16.                 },
    17.                 {
    18.                     "SubnetStatus": "Active",
    19.                     "SubnetAvailabilityZone": {
    20.                         "Name": "us-east-1c"
    21.                     },
    22.                     "SubnetIdentifier": "subnet-afc329f4"
    23.                 },
    24.                 {
    25.                     "SubnetStatus": "Active",
    26.                     "SubnetAvailabilityZone": {
    27.                         "Name": "us-east-1e"
    28.                     },
    29.                     "SubnetIdentifier": "subnet-b3806e8f"
    30.                 },
    31.                 {
    32.                     "SubnetStatus": "Active",
    33.                     "SubnetAvailabilityZone": {
    34.                         "Name": "us-east-1d"
    35.                     },
    36.                     "SubnetIdentifier": "subnet-53ab3636"
    37.                 },
    38.                 {
    39.                     "SubnetStatus": "Active",
    40.                     "SubnetAvailabilityZone": {
    41.                         "Name": "us-east-1b"
    42.                     },
    43.                     "SubnetIdentifier": "subnet-991cb8d0"
    44.                 },
    45.                 {
    46.                     "SubnetStatus": "Active",
    47.                     "SubnetAvailabilityZone": {
    48.                         "Name": "us-east-1f"
    49.                     },
    50.                     "SubnetIdentifier": "subnet-29ab1025"
    51.                 }
    52.             ],
    53.             "SubnetGroupStatus": "Complete",
    54.             "DBSubnetGroupDescription": "default",
    55.             "VpcId": "vpc-91280df6",
    56.             "DBSubnetGroupName": "default"
    57.         },
    58.         "PromotionTier": 2,
    59.         "DBInstanceClass": "db.r5.4xlarge",
    60.         "InstanceCreateTime": "2018-11-05T23:10:49.905Z",
    61.         "PreferredBackupWindow": "00:00-00:30",
    62.         "KmsKeyId": "arn:aws:kms:us-east-1:012345678901:key/0961325d-a50b-44d4-b6a0-a177d5ff730b",
    63.         "StorageEncrypted": true,
    64.         "VpcSecurityGroups": [
    65.             {
    66.                 "Status": "active",
    67.                 "VpcSecurityGroupId": "sg-77186e0d"
    68.             }
    69.         ],
    70.         "EngineVersion": "3.6.0",
    71.         "DbiResourceId": "db-SAMPLERESOURCEID",
    72.         "DBInstanceIdentifier": "sample-cluster-instance-00",
    73.         "Engine": "docdb",
    74.         "AvailabilityZone": "us-east-1a",
    75.         "DBInstanceArn": "arn:aws:rds:us-east-1:012345678901:db:sample-cluster-instance-00",
    76.         "BackupRetentionPeriod": 1,
    77.         "Endpoint": {
    78.             "Address": "sample-cluster-instance-00.corcjozrlsfc.us-east-1.docdb.amazonaws.com",
    79.             "Port": 27017,
    80.             "HostedZoneId": "Z2R2ITUGPM61AM"
    81.         },
    82.         "DBClusterIdentifier": "sample-cluster"
    83.     }
    84. }

    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.