Troubleshooting SSL Handshake Errors with Curl

Understanding SSL Handshake Errors with Curl

Secure communication over the internet relies heavily on the SSL/TLS protocol. When using tools like curl to interact with servers over HTTPS, you might occasionally encounter errors during the SSL/TLS handshake process. A common error message is “curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number”. This tutorial will explain what this error signifies and how to resolve it, covering common causes and troubleshooting steps.

What Does the Error Mean?

The “wrong version number” error indicates a mismatch in the SSL/TLS protocol version negotiated between the curl client and the server. The server expects a specific version of the protocol, but curl either isn’t offering it, is offering an unsupported version, or the initial handshake information is corrupted. This can occur for several reasons, ranging from incorrect server configuration to client-side proxy settings. The error doesn’t necessarily mean that SSL/TLS is fundamentally broken; it means the two endpoints can’t agree on how to establish a secure connection.

Common Causes and Solutions

Let’s explore the most frequent causes of this error and how to fix them:

1. Proxy Server Issues:

This is the most common culprit, especially in corporate or institutional networks. If you are behind a proxy, the proxy server might be interfering with the SSL/TLS handshake.

• Incorrect Proxy Configuration: Ensure that your curl command or environment variables are correctly configured to use the proxy. Verify the proxy address, port, and protocol. Pay close attention to the protocol: you should typically use http:// for the proxy even if you are connecting to an https:// destination. curl will then handle the secure connection to the target server.

  You can set the proxy using either command-line arguments:

  curl -x http://your_proxy_server:proxy_port https://www.example.com
  

  Or by setting environment variables:

  export http_proxy=http://your_proxy_server:proxy_port
  export https_proxy=http://your_proxy_server:proxy_port
  curl https://www.example.com
  

• Proxy Protocol Mismatch: As mentioned, if your proxy is expecting a different protocol (e.g., HTTPS for the proxy itself) than what curl is offering, the handshake will fail. Double-check your proxy configuration.

• Proxy Not Handling HTTPS: Ensure your proxy server is configured to correctly handle HTTPS connections. Some older proxies may only support HTTP.

2. Server Configuration Issues:

Although less common when the problem originates on the client side, server misconfiguration can cause this error.

• Incorrect SSL/TLS Certificate: The server’s SSL/TLS certificate might be invalid, expired, or not correctly configured. While this often manifests as different errors, it can sometimes lead to handshake failures. Use online SSL checker tools to verify the server’s certificate.
• Unsupported SSL/TLS Versions: The server might only support older SSL/TLS versions that are no longer considered secure and are disabled by default in newer curl and OpenSSL versions. While generally not the ideal solution (as it weakens security), you can try forcing curl to use a specific version if you have no control over the server (e.g., --tlsv1.2).
• Firewall Interference: A firewall between the client and server might be blocking certain SSL/TLS versions or ports.

3. Client-Side Configuration Issues:

• ~/.curlrc Configuration: Check your ~/.curlrc file for any incorrect proxy settings or other configurations that might be interfering with the connection. Remove or correct any problematic lines.
• /etc/hosts File: An incorrect entry in your /etc/hosts file could be redirecting the domain name to an unexpected IP address, causing the handshake to fail. Verify that the domain name resolves to the correct IP address.
• Outdated curl or OpenSSL: While usually not the direct cause, using very old versions of curl or OpenSSL can sometimes lead to compatibility issues. Consider updating to the latest stable versions.

Troubleshooting Steps

1. Simplify the Command: Start with a simple curl command without any extra options:

   curl https://www.example.com
   

   If this fails, the problem is likely related to the basic connection or server configuration.

2. Verbose Output: Use the -v (verbose) option to get more detailed information about the connection process:

   curl -v https://www.example.com
   

   Examine the output carefully for any clues about the error, such as the SSL/TLS versions being negotiated.

3. Test Without a Proxy: If you suspect a proxy issue, try connecting without a proxy by unsetting the http_proxy and https_proxy environment variables.

4. Check Network Connectivity: Ensure you have a stable internet connection and can reach the server.

5. Use openssl s_client: For more advanced debugging, use the openssl s_client command to establish an SSL/TLS connection manually and inspect the handshake process.

By systematically investigating these potential causes and using the provided troubleshooting steps, you should be able to resolve the "wrong version number" error and establish a secure connection with the server.