Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP cURL cannot connect to a server that requires TLS 1.2

ErrorTLS 1.2 not working in cURL

Short answer

A server that requires TLS 1.2 rejects a client that offers an older version. In PHP the version is controlled by CURLOPT_SSLVERSION. Set it to CURL_SSLVERSION_TLSv1_2, which means TLS 1.2 or later, and remove any option that forces SSLv3 or TLS 1.0. Check curl_version() to see which library and cURL version PHP uses.

  • Applies to PHP 8.3, PHP 8.4, libcurl 8.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the cURL version and the TLS library PHP's curl extension uses.

    php -r 'print_r(curl_version());' | grep -E "version|ssl_version"
  2. 2Match what you see, then jump to its fix

    1. 1The request sets CURLOPT_SSLVERSION to TLSv1_0, TLSv1_1 or SSLv3, or the server log shows a protocol mismatch.Your code forces an old protocol versionFix
    2. 2Handshake fails only with servers that require TLS 1.3, or after adding a MAX constant.A maximum version below what the server needsFix

What does the error look like?

  • TLS 1.2 not working in cURL
  • The handshake fails only against servers that require TLS 1.2 or newer

Cause 1 of 2

Your code forces an old protocol version

1Check

SSLv2 is disabled by default since libcurl 7.18.1 and SSLv3 since 7.39.0, and both are refused entirely since 7.77.0. Search your code for a forced version.

grep -rn "CURLOPT_SSLVERSION" src vendor/ 2>/dev/null | head

2Fix

Remove the forced value, or set TLS 1.2 as the minimum. CURL_SSLVERSION_TLSv1_2 means TLS 1.2 or later, so newer versions still work.

curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);

3Verify

Run the request again and confirm it returns a body.

php request.php

Confirmed by curl.se

Did this fix it?

Cause 2 of 2

A maximum version below what the server needs

1Check

CURL_SSLVERSION_MAX_* caps the highest version libcurl will negotiate. Before libcurl 7.61.0 the default maximum was TLS 1.2, and from 7.61.0 it is TLS 1.3 if the TLS library supports it.

grep -rn "CURL_SSLVERSION_MAX" src | head

2Fix

Drop the maximum, or use MAX_DEFAULT. If you need to pin both ends, combine a minimum and a maximum with a bitwise OR.

// allow TLS 1.2 and newer, no cap
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);

// pin exactly TLS 1.2 only if the server requires it
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2 | CURL_SSLVERSION_MAX_TLSv1_2);

3Verify

Repeat the request. The connection completes.

php request.php

Confirmed by curl.se

Did this fix it?

How do I stop it coming back?

  • Do not hard-code SSL versions; set a minimum of TLS 1.2 and leave the maximum open.
  • Keep PHP and its cURL library updated through your operating system's updates.
  • Log curl_error() for every failed request.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.