When working with external or internal APIs, a million things can make it return errors: missing HTTP headers, sending an invalid authorization credential because you forgot to append "Bearer" to your API token, or even just a simple typo on the endpoint you're trying to use.
Those issues can be frustrating, and sometimes take hours of banging your head against the keyboard or reading documentation to figure out what's wrong, but the solutions are easy. Another issue that is generally much harder to fix is debugging an SSL error.
What is SSL/TLS? (the short version)
SSL, or Secure Sockets Layer, is a security standard technology to help establish an encrypted connection between two systems: a server and a client (browser), or a server and another server, for example.
After SSL had been updated to 3.0, instead of increasing the next version number to 3.1 or 4.0, it was instead changed to TLS 1.0 (why?). Much like the OpenAPI Specification and Swagger nowadays, SSL and TLS are still used interchangeably when talking about the protocol or certificates.
How to Debug SSL Errors
Debugging SSL errors can be challenging for a few reasons. Error messages returned because of SSL issues are not always specific, or don't give indications on how to fix the problem. Another reason is the way different browsers, language stacks, or tools handle SSL. For example, you might be testing an API using cURL at first and getting a successful response from an endpoint, only to find the same request doesn't work from your Node.js application.
So, how can we start debugging these SSL errors?
Common Errors
Two of the most common issues we have seen out in the wild and helped our customers with are actually really easy to fix: invalid certificates, and incomplete certificate chains.
Even though they are two different errors, depending on the tool or stack you're using you might see the same error message. For example, this is what you would see in Runscope:
Error contacting host SSL: certificate signed by unknown authority
That is also the same message we return in case the server has a self-signed certificate, which is a common use case during development.
For self-signed certificates, we recommend simply turning off SSL validation temporarily in whichever tool you're using. In Runscope, you can disable SSL verification in your test by going to the test's environment -> Behaviors -> Validate SSL, or for all tests in your bucket by going to Bucket Settings -> Traffic Inspector -> Verify SSL Certificates.
CA Certificate List
When running into this error, the first thing we need to do is make sure the tool that we're using supports the authority that created our SSL certificate. At Runscope, for example, we use the Mozilla CA Included Certificate List. You can usually find what the tool you're using supports with a quick Google search or by reaching out to their support team.
SSLLabs SSL Server Test
If the server's SSL certificate provider is part of the list, then the next step we can take to debug the issue is to use SSLLabs SSL Server Test tool. This is a free tool that will perform a deep analysis of any public SSL web server you point to.
SSLLabs results will give the hostname a grade ranging from A+ to F, or M and T (more info about the ratings). Scrolling down the report, we can see more information about the certificates, and warnings in case there any issues found. For example, if a certificate is not trusted you'll be able to see it next to the Trusted line:
And, you can also check the Issuer to make sure that is included in the certificate list your server or browser is using.
Incomplete Certificate Chain
The most common issue that SSLLabs uncovers and we have seen across our customers is the "Incomplete" error in the Chain Issues line:
SSL certificate chains can be handled differently across different browsers and tools. If a browser or a tool is trying to connect to a server, it will try to check if its certificate was issued by a trusted CA. If it's not, it will try to see if that intermediate certificate was instead issued by a trusted CA, and so on. Those intermediate certificates can be bundled into one file, or they might be links that the browser or tool has to follow. And some browsers or tools won't follow those links, causing this SSL error to pop up.
To fix this issue, if you have control of the server, you can just bundle all intermediate certificates into a single file and update your server with it. You can usually find instructions on how to do that with a quick Google search of "<your certificate provider> bundle certificates".
Other Resources
These are two of the most common error, and fixes, for SSL/TLS that we see. If you have any other issues you've run into, please let us know and we would love to add them here!
You can also check out this more thorough guide on "SSL/TLS - Typical problems and how to debug them" for help in debugging other issues.