GeezerVison

Description

RFC: https://wiki.php.net/rfc/curl_opensocketfunction (under discussion)
Discussion: "SSRF protection in curl", [email protected]
Supersedes #23657.

This adds CURLOPT_OPENSOCKETFUNCTION, with libcurl's name and value. Its callback allows or refuses each socket libcurl is about to create, after DNS resolution and before connect():

curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $handle, string $address, int $port): bool {
        // Only publicly routable addresses; a UNIX socket path is not an IP.
        return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false;
    });

This is the point where an SSRF policy can be enforced reliably: on the address actually about to be contacted, for every redirect hop and every address libcurl tries, whatever spelling the URL used and whatever DNS answered.

Semantics

• $handle comes first, as in the other ext/curl callbacks. curl_getinfo($handle, CURLINFO_EFFECTIVE_URL) tells which URL the address is for, redirects included.
• $address is the literal IP address, or the path of a UNIX socket. An abstract socket name keeps its leading NUL byte.
• $port is 0 for a UNIX socket, as CURLOPT_PREREQFUNCTION and CURLINFO_PRIMARY_PORT report it.
• When the callback returns:
  • true: ext/curl creates the socket with socket(family, socktype, protocol), which is what libcurl documents as the hook's default behaviour. Everything libcurl does next is unchanged.
  • false: the connection is refused. libcurl tries the next address of the host, if any, and the transfer fails with CURLE_COULDNT_CONNECT once none is left.
  • Any other value: a TypeError is raised and the connection is refused.
  • An exception: the connection is refused and the exception propagates.
• Some endpoints cannot be described to the callback: other address families, other socket purposes, and AF_UNIX on Windows. These are refused without calling it.
• The option behaves like the other callable options:
  • null removes it;
  • curl_reset() clears it;
  • curl_copy_handle() and clone carry it over;
  • it is reported to the cycle collector.
• The callback is invoked for each socket created. A connection reused from the pool of the handle, of its multi handle, or of a share is not vetted again. CURLOPT_PREREQFUNCTION runs before every request, reused connections included. UPGRADING documents this, along with proxies and CURLOPT_PROTOCOLS_STR.

No descriptor is ever exposed to userland, and ext/curl gains no dependency on ext/sockets. The return type can later be widened, and parameters appended, without breaking existing callbacks.

Tests

• Allow and refuse, including with curl_multi, and libcurl trying the next address after a refusal.
• Exceptions, including one thrown by a destructor after the callback returned true.
• Redirects.
• Every address family, including IPv4-mapped IPv6 and UNIX and abstract sockets.
• file://, which opens no socket.
• Connection reuse, CURLOPT_FRESH_CONNECT and CURLOPT_PREREQFUNCTION. These use a small keep-alive server, keepalive_server.inc, since the CLI server closes every connection.
• Copy, clone and reset, and a callback that removes itself.
• Invalid callables and return values, and exceptions.
• Cycle collection, and freeing a handle while its connection stays pooled.

Polyfill

curl_hardening implements the same API for PHP 8.3 to 8.6. It stays inert on a PHP that provides the option natively.