Updating your Amazon DocumentDB TLS certificates

The certificate authority (CA) certificate for Amazon DocumentDB clusters will update starting in August, 2024. If you are using Amazon DocumentDB clusters with Transport Layer Security (TLS) enabled (the default setting) and you have not rotated your client application and server certificates, the following steps are required to mitigate connectivity issues between your application and your Amazon DocumentDB clusters.

The CA and server certificates were updated as part of standard maintenance and security best practices for Amazon DocumentDB. Client applications must add the new CA certificates to their trust stores, and existing Amazon DocumentDB instances must be updated to use the new CA certificates before this expiration date.

Updating your application and Amazon DocumentDB cluster

Follow the steps in this section to update your application's CA certificate bundle (Step 1) and your cluster's server certificates (Step 2). Before you apply the changes to your production environments, we strongly recommend testing these steps in a development or staging environment.

Step 1: Download the new CA certificate and update your application

Download the new CA certificate and update your application to use the new CA certificate to create TLS connections to Amazon DocumentDB. Download the new CA certificate bundle from https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem. This operation downloads a file named global-bundle.pem.

wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

Next, update your applications to use the new certificate bundle. The new CA bundle contains both the old CA certificate (rds-ca-2019) and the new CA certificates (rds-ca-rsa2048-g1, rds-ca-rsa4096-g1, rds-ca-ecc384-g1). By having both CA certificates in the new CA bundle, you can update your application and cluster in two steps.

For Java applications, you must create a new trust store with the new CA certificate. For instructions, see the Java tab in the Connecting with TLS enabled topic.

To verify that your application is using the latest CA certificate bundle, see How can I be sure that I'm using the newest CA bundle? If you're already using the latest CA certificate bundle in your application, you can skip to Step 2.

For examples of using a CA bundle with your application, see Encrypting data in transit and Connecting with TLS enabled.

Step 2: Update the server certificate

After the application has been updated to use the new CA bundle, the next step is to update the server certificate by modifying each instance in an Amazon DocumentDB cluster. To modify instances to use the new server certificate, see the following instructions.

Amazon DocumentDB provides the following CAs to sign the DB server certificate for a DB instance:

These CA certificates are included in the regional and global certificate bundle. When you use the rds-ca-rsa2048-g1, rds-ca-rsa4096-g1, or rds-ca-ecc384-g1 CA with a database, Amazon DocumentDB manages the DB server certificate on the database. Amazon DocumentDB rotates the DB server certificate automatically before it expires.

Troubleshooting

If you are having issues connecting to your cluster as part of the certificate rotation, we suggest the following:

Frequently Asked Questions

The following are answers to some common questions about TLS certificates.

What if I have questions or issues?

If you have questions or issues, contact AWS Support.

How do I know whether I'm using TLS to connect to my Amazon DocumentDB cluster?

You can determine whether your cluster is using TLS by examining the tls parameter for your cluster’s cluster parameter group. If the tls parameter is set to enabled, you are using the TLS certificate to connect to your cluster. For more information, see Managing Amazon DocumentDB cluster parameter groups.

Why are you updating the CA and server certificates?

The Amazon DocumentDB CA and server certificates are being updated as part of standard maintenance and security best practices for Amazon DocumentDB. The current CA and server certificates are expiring beginning August, 2024.

What happens if I don't take any action by the expiration date?

If you are using TLS to connect to your Amazon DocumentDB cluster and you do not make the certificate change by August, 2024, your applications that connect via TLS will no longer be able to communicate with the Amazon DocumentDB cluster.

Amazon DocumentDB will not rotate your database certificates automatically before expiration. You must update your applications and clusters to use the new CA certificates before or after the expiration date.

How do I know which of my Amazon DocumentDB instances are using the old/new server certificate?

To identify the Amazon DocumentDB instances that still use the old server certificate, you can use either the Amazon DocumentDB AWS Management Console or the AWS CLI.

aws docdb describe-db-instances \
    --filters Name=engine,Values=docdb \
    --query 'DBInstances[*].{CertificateVersion:CACertificateIdentifier,InstanceID:DBInstanceIdentifier}'
         

How do I modify individual instances in my Amazon DocumentDB cluster to update the server certificate?

We recommend that you update server certificates for all instances in a given cluster at the same time. To modify the instances in your cluster, you can use either the console or the AWS CLI.

What happens if I add a new instance to an existing cluster?

All new instances that are created use the old server certificate and require TLS connections using the old CA certificate. Any new Amazon DocumentDB instances created after January 25, 2024 will default to using the new certificate rds-ca-rsa2048-g1.

What happens if there is an instance replacement or failover on my cluster?

If there is an instance replacement in your cluster, the new instance that is created continues to use the same server certificate that the instance was previously using. We recommend that you update server certificates for all instances at the same time. If a failover occurs in the cluster, the server certificate on the new primary is used.

If I'm not using TLS to connect to my cluster, do I still need to update each of my instances?

We highly recommend enabling TLS. In the event that you do not enable TLS, we still recommend rotating the certificates on your Amazon DocumentDB instances in the event you plan to use TLS to connect to your clusters in the future. If you never plan to use TLS to connect to your Amazon DocumentDB clusters, no action is needed.

If I'm not using TLS to connect to my cluster but I plan to in the future, what should I do?

If you created a cluster before January, 2024, follow Step 1 and Step 2 in the previous section to ensure that your application is using the updated CA bundle, and that each Amazon DocumentDB instance is using the latest server certificate. If you create a cluster after January 25, 2024, your cluster will already have the latest server certificate (rds-ca-rsa2048-g1). To verify that your application is using the latest CA bundle, see If I'm not using TLS to connect to my cluster, do I still need to update each of my instances?

Can the deadline be extended beyond August, 2024?

If your applications are connecting via TLS, the deadline cannot be extended.

How can I be sure that I'm using the newest CA bundle?

To verify that you have the newest bundle, use the following command. To run this command, you must have java installed and the java tools need to be in the PATH variable of your shell. For more information, see Using Java

keytool -printcert -v -file global-bundle.pem

keytool -printcert -v -file global-bundle.p7b

Why do I see "RDS" in the name of the CA bundle?

For certain management features, such as certificate management, Amazon DocumentDB uses operational technology that is shared with Amazon Relational Database Service (Amazon RDS).

When will the new certificate expire?

The new server certificate will expire (generally) as follows:

What kind of errors will I see if I don't take action before the certificate expires?

Error messages will vary depending on your driver. In general, you'll see certificate validation errors that contain the string "certificate has expired".

If I applied the new server certificate, can I revert it back to the old server certificate?

If you need to revert an instance to the old server certificate, we recommend that you do so for all instances in the cluster. You can revert the server certificate for each instance in a cluster by using the AWS Management Console or the AWS CLI.

aws docdb modify-db-instance --db-instance-identifier <db_instance_name> ca-certificate-identifier rds-ca-2019 <--apply-immediately | --no-apply-immediately>

If I restore from a snapshot or a point in time restore, will it have the new server certificate?

If you restore a snapshot or perform a point-in-time restore after August, 2024, the new cluster that is created will use the new CA certificate.

What if I’m having issues connecting directly to my Amazon DocumentDB cluster from any Mac OS?

Mac OS has updated the requirements for trusted certificates. Trusted certificates must now be valid for 397 days or fewer (see https://support.apple.com/en-us/HT211025).

Amazon DocumentDB instance certificates are valid for over four years, longer than the Mac OS maximum. In order to connect directly to an Amazon DocumentDB cluster from a computer running Mac OS, you must allow invalid certificates when creating the TLS connection. In this case, invalid certificates mean that the validity period is longer than 397 days. You should understand the risks before allowing invalid certificates when connecting to your Amazon DocumentDB cluster.

To connect to an Amazon DocumentDB cluster from Mac OS using the AWS CLI, use the tlsAllowInvalidCertificates parameter.

mongo --tls --host <hostname> --username <username> --password <password> --port 27017 --tlsAllowInvalidCertificates