In person, a handshake can be used to greet someone or finalize an agreement with them. The same is true online.
When devices on a network — say, a browser and a web server — share encryption algorithms, keys, and other details about their connection before finally agreeing to exchange data, it’s called an SSL handshake. During this handshake, the browser and server might ask to see each other’s SSL certificates to verify them.
This handshake is essential for establishing a secure connection before transferring data, so it’s important to understand what an SSL handshake is and what to do if it fails.
The SSL handshake is the process in which a client and server establish the encryption algorithms and secret keys they will use to communicate with each other securely, and exchange and validate each other’s digital certificates.
Note: SSL and TLS are both cryptographic protocols that enable clients and servers operating over a network to communicate with each other securely. TLS has replaced SSL, but SSL is still a more commonly used term so we’ll continue to use it in this post.
SSL Handshake Steps
The exact steps in an SSL handshake vary depending on the version of SSL the client and server decide to use, but the general process is outlined below.
- The client says hello. This “client hello” message lists cryptographic information, including the SSL version to use to communicate with each other. It also lists which encryption algorithms it supports, which are known as Cipher Suites.
- The server responds hello. This “server hello” message contains important information, like which CipherSuite it chose, and its digital certificate. It might also request the client’s certificate.
- The client verifies the server’s certificate. It also sends several byte strings, including one for allowing both the client and the server to compute a secret key for encrypting subsequent messages, including the “finished” messages. If the server sends a client certificate request, it will also send a byte string encrypted with its own private key and digital certificate.
- The server verifies the client's certificate. This step only takes place if client authentication is required.
- The client says “I’m finished.” This “finished” message indicates that the client has completed its part of the handshake.
- The server says “I’m finished, too.” This “finished” message indicates that the sever has completed its part of the handshake.
For the remainder of the session, the server and client can now exchange messages that are encrypted with the same secret key, which was shared in step three. This is known as symmetric encryption. You can learn more about symmetric encryption, and how it differs from asymmetric encryption, in this post.
The steps above will occur if the process goes smoothly. But what if it doesn’t? Below we’ll walk through how to resolve an “SSL Handshake Failed” error message.
What is SSL Handshake Failed?
SSL Handshake Failed is an error message that occurs when the client or server wasn’t able to establish a secure connection.
This might occur if:
- The client is using the wrong date or time.
- The client is a browser and its specific configuration is causing the error.
- The connection is being intercepted by a third party on the client-side.
- The client and server do not support the same SSL version.
- The client and server are using different Cipher Suites.
- The client or server’s certificate is invalid.
The SSL Handshake Failed error message may appear differently, depending on the client application you’re using or server you’re trying to communicate with. For example, in GitHub, it will look something like this:
If you’re using Cloudflare, on the other hand, an SSL Handshake Failed will appear as a 525 error that looks something like this:
Now that you know some of the causes of the SSL Handshake Failed error, let’s look at some solutions.
How to Fix SSL Handshake Failed
- Correct the time and date on the client device.
- Try another browser.
- Add website to allowlist.
- Update browser to use the latest SSL protocol.
- Check browser and server support for Cipher Suites.
- Verify your SSL certificate is accurate and valid.
1. Correct the time and date on the client device.
Let’s start with the easiest fix. If the system time and date is incorrect on your computer or device, then it can cause the SSL Handshake Failed error. That’s because time is essential when it comes to SSL certificates: they have finite lifespans and become invalid past their expiration date.
If you check your system time and date and it’s correct, then move on to the next step.
2. Try another browser.
It’s possible that the browser you’re using is causing the SSL Handshake Failed error. It could be your settings, browser plugins, or another issue. To see if this is the problem, just switch to another browser.
Let’s say you were trying to connect to a website using Google Chrome, and it works just fine in Safari. In that case, you’ll have to narrow down what the problem is. Go back and reset Google Chrome (or whatever browser you were using) to its default settings and disable all your plugins. Then re-configure your settings and enable your plugins one-by-one, testing your ability to connect to the website each time. You should be able to isolate the specific setting or plugin that caused the SSL Handshake Failed that way.
If you try another browser and you still see the SSL Handshake Failed error, then move on to the next step.
3. Add website to allowlist.
It’s also possible that your firewall is causing the SSL Handshake Failed error by intercepting your request for inspection. To rule it out as the cause, you can temporarily deactivate your firewall —but that can leave you vulnerable to attack.
Instead, try adding the website to your allowlist. Here’s the process for Google Chrome:
- On your admin console homepage, go to Devices > Chrome.
- Click Settings> Users & browsers.
- Leave the top organizational unit selected (it’s selected by default). This will apply the setting to all users and enrolled browsers.
- Scroll to URL Blocking and enter the website you are trying to access under Blocked URL exceptions.
- Click Save.
If you try visiting that site again and you still see the SSL Handshake Failed error, then move on to the next step.
4. Update browser to use the latest SSL protocol.
It’s possible that you’re getting the SSL Handshake Failed error because your device (the client) and server do not support the same SSL version, which is resulting in a protocol mismatch. For example, let’s say your browser only supports TLS 1.1 and your server only supports TLS 1.2 or 1.3 (the latest version). If these two try to establish a secure connection, then it will likely result in an SSL Handshake Failed error.
In that case, you’ll need to update your browser. Most updated versions of major browsers like Google Chrome have TLS 1.2 automatically enabled. However, even if it is updated, it’s important to make sure it’s configured to to support the latest TLS version.
Here’s the easiest way to check:
- Visit SSL Labs.
- Navigate to Projects.
- Click SSL Client Test.
- Under Protocol Support, it will tell you whether your browser supports the latest versions of TLS.
If you verify that your browser and server are using the same protocol, then move on to the next step.
5. Check browser and server support for Cipher Suites.
Another reason you could be getting the SSL Handshake Failed error is that the client and server are using different Cipher Suites. Just like a protocol mismatch, a client and server who do not have mutual support for the same CipherSuite will not be able to establish a secure connection.
You can compare which Cipher Suites your browser support to which the server of the website you’re trying to visit supports by once again visiting SSL Labs.
- First, navigate to Projects.
- Click SSL Client Test.
- Scroll down to Protocol Features, where it will list which Cipher Suites your browser supports, in order of preference.
- Now, open SSL Labs in another tab, and navigate to Projects.
- Click SSL Server Test.
- Type in the domain name you are trying to visit that is resulting in the SSL Handshake Failed error.
- Scroll down to Configuration, where it will list which Cipher Suites the server supports, in order of preference.
If you verify that your browser and server are using the same CipherSuite, then move on to the next step.
6. Verify your SSL certificate is accurate and valid.
Any number of issues on an SSL certificate can prevent an SSL handshake from being completed. This may result in an SSL Handshake Failed error or another error message that ultimately means the handshake failed. For example, you might see something like this:
If the SSL certificate has an incorrect host name, for example, or it’s past its expiration date, then the handshake will likely fail. So it’s important to ensure your SSL certificate is installed correctly and renewed when needed.
You can use an online tool like the above-mentioned SSL Server Test or SSL Shopper to test that your SSL configuration is installed, valid, and trusted in just a few minutes.
When a Client and Server Don’t Want to Shake Hands
Since an SSL handshake is an essential step in keeping data transferred over the internet secure, it’s important that users understand what the SSL Handshake Failed error means and how to fix it. By following the steps above, you should be able to resolve the issue and establish a secure connection between your device and the server you’re trying to connect to.