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

Short description

By default, Amazon DocumentDB turns on Secure Socket Layer (SSL) or Transport Layer Security (TLS) configuration and allows only encrypted connections. 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 Managing Amazon DocumentDB Cluster TLS Settings.

Note: TLS is a static parameter. You must reboot the cluster to apply all the cluster parameter group changes. For more information, see Modifying Amazon DocumentDB cluster parameters.

You might receive an "SSLHandshakeFailed" error for one of the following reasons:

• You rename the Amazon DocumentDB cluster or instance and this causes SSL certificate inconsistency.
• You connect to the cluster from outside of a virtual private cloud (VPC) with SSH tunneling.
• You create an Amazon Route 53 CNAME record of the Amazon DocumentDB endpoint.

Resolution

Resolve SSL certificate inconsistency

When you create an Amazon DocumentDB instance, Amazon DocumentDB automatically creates and assigns an SSL certificate to the DB instance. This SSL 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

When you connect to your Amazon DocumentDB cluster from outside a VPC, SSH tunneling uses the hostname of the intermediate Amazon Elastic Compute Cloud (Amazon EC2) instance. If you make an SSL/TLS connection, 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: When you use an SSH tunnel, don't specify replicaSet=rs0 in your connection string to connect in replica set mode. The tunnel setup can't validate the recognition of rs0 as replica set configuration, and you receive an error when you try to connect in replica set mode.

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 receive 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 security best practice to not use sslAllowInvalidHostnames or tlsAllowInvalidHostnames in production.

Related information

Connecting to an Amazon DocumentDB cluster from outside an Amazon VPC

Connecting to Amazon DocumentDB as a replica set

Troubleshooting connection issues

Encrypting Data in Transit