Why do I get an SSLHandshakeFailed error when I try to connect to my Amazon DocumentDB cluster?

Short description

Secure Socket Layer (SSL) or Transport Layer Security (TLS) configuration is turned on for Amazon DocumentDB clusters by default. This means that only encrypted connections are allowed. If your application doesn't use SSL/TLS connections, then use a custom Amazon DocumentDB cluster parameter group to turn off this option. For more information, see Manage Amazon DocumentDB Cluster TLS Settings.

Note: TLS is a static parameter and requires a reboot of the cluster for the cluster parameter group changes to take effect. For more information, see Modify Amazon DocumentDB cluster parameters.

• The Amazon DocumentDB cluster or instance was recently renamed, and this caused SSL certificate inconsistency.
• You connected to the cluster from outside of a virtual private cloud (VPC) with SSH tunneling.
• You created an Amazon Route 53 CNAME record of the Amazon DocumentDB endpoint

Resolution

Resolve SSL certificate inconsistency

When you create an Amazon DocumentDB instance, an SSL certificate is automatically created and assigned to the DB instance. This SSL certificate, also known as the server side certificate, contains information about the DB cluster, instances, and their endpoints. If you modify a cluster name or instance name, then there's inconsistency at the certificate level.

To update the certificate, reboot the Amazon DocumentDB cluster. Use the sslAllowInvalidHostnames or tlsAllowInvalidHostnames connection string option as a temporary workaround.

Resolve issues with connections from outside the VPC with SSH Tunneling

You might try to connect to your Amazon DocumentDB cluster from outside a VPC. In this scenario, the hostname of the intermediate Amazon Elastic Compute Cloud (Amazon EC2) instance is used for the SSH tunneling process. If an SSL connection is made, then the client expects the hostname to match the Amazon DocumentDB endpoint that's mentioned in the certificate. To turn off hostname validation, use the sslAllowInvalidHostnames or tlsAllowInvalidHostnames option to your connection string.

Note: If you use an SSH tunnel, then don't specify replicaSet=rs0 in your connection string to connect in replica set mode. If you try to connect in replica set mode, then an error is thrown. This happens because the recognition of rs0 as replica set configuration can't be validated in the tunnel setup.

Resolve issues with SSL connections that use a customer managed Route 53 CNAME

If you use SSL/TLS to connect to a customer managed Route 53 CNAME record, then the name of the Route 53 record must match the DB cluster name. You see an error because the hostname isn't the same as the one mentioned in the SSL certificate of the Amazon DocumentDB resource.

Amazon DocumentDB doesn't allow you to upload custom certificates that contain the information you need to establish the SSL connection through a CNAME record. Instead, use the equivalent hostname check ignore flag for the end user connection through the CNAME record, such as sslAllowInvalidHostnames or tlsAllowInvalidHostnames.

Note: It's a best practice to not use sslAllowInvalidHostnames or tlsAllowInvalidHostnames in production for security reasons.

Related information

Connect to an Amazon DocumentDB Cluster from Outside an Amazon VPC

Connect to Amazon DocumentDB as a Replica Set

Connection issues

Encrypt Data in Transit