Skip to Content

Fixing the “SSL: SSLV3_ALERT_HANDSHAKE_FAILURE” error in Python

The “SSL: SSLV3_ALERT_HANDSHAKE_FAILURE” error indicates that the server and client in your Python application couldn’t establish a secure connection using SSLv3.

I encountered the “SSL: SSLV3_ALERT_HANDSHAKE_FAILURE” error while working on a project with a tight deadline. This error message meant that the connection between my application and the server was being blocked.

Through research and troubleshooting, I discovered that the cause of the error was a mismatch in the supported cipher suites between my application and the server. A simple adjustment to the configuration settings solved the problem and allowed me to connect successfully.

So I summarized the following article. Hope it can help others.

This can occur due to various reasons, including:

  • Outdated libraries: Your Python environment might use outdated libraries that lack support for newer TLS protocols or cipher suites.
  • Incompatible configurations: The server and client might not be configured with compatible TLS versions, cipher suites, or certificate verification settings.
  • Network issues: Temporary network issues could interfere with the handshake process.

Here’s how you can troubleshoot and fix this error in Python:

1. Update your libraries:

  • Ensure you have the latest versions of the requests and urllib3 libraries installed. These libraries perform HTTP requests and manage SSL connections.
  • Use pip install --upgrade requests and pip install --upgrade urllib3 to update them.

2. Configure TLS settings:

  • Use the verify parameter in your requests to explicitly set the TLS version and verification mode.
  • For example, to use TLS 1.2 and verify the server’s certificate, use:
import requests

response = requests.get("https://example.com", verify="/path/to/ca-certificates.pem")

Replace /path/to/ca-certificates.pem with the actual path to your trusted certificate authority (CA) certificate file.

3. Disable SSLv3:

  • SSLv3 is considered insecure due to known vulnerabilities. Disabling it might allow the connection to succeed using a more secure protocol.
  • Use the ssl_version parameter in your requests to specify a different protocol like TLS 1.2:
response = requests.get("https://example.com", verify=False, ssl_version=ssl.PROTOCOL_TLSv1_2)

4. Check server configuration:

  • Confirm the server supports a compatible TLS version and cipher suite.
  • Contact the server administrator if you’re unsure about the configuration details.

5. Verify your network:

  • Temporary network issues can sometimes interrupt the handshake process.
  • Check your internet connection and ensure no firewall rules are blocking the connection.

6. Consider alternative libraries:

  • If the error persists, consider using alternative libraries like pycurl or aiohttp that offer more advanced TLS configuration options.

Additional Resources:

By following these steps and investigating the specific context of your application, you should be able to identify the cause of the “SSL: SSLV3_ALERT_HANDSHAKE_FAILURE” error and establish a secure connection using a more robust TLS protocol.