PHP: rfc:curl_opensocketfunction

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Vetting cURL connections with CURLOPT_OPENSOCKETFUNCTION ======
  * Version: 0.2
  * Date: 2026-11-12
  * Author: Xavier Leune, xavier.leune@gmail.com
  * Status: Under Discussion
  * Implementation: https://github.com/php/php-src/pull/25414
  * Discussion thread: https://news-web.php.net/php.internals/133085
  * Voting thread: tbd

===== Introduction =====

Applications that fetch URLs supplied by their users (webhooks, link previews,
image proxies, feed readers, OAuth or OpenID discovery) are exposed to
Server-Side Request Forgery: the URL points at a host that should not be
reachable, such as 127.0.0.1, a cloud metadata endpoint (169.254.169.254), or a
service on the internal network. This RFC adds a cURL option to allow or refuse
each connection, on the address actually about to be contacted:

<PHP>
<?php

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

?>
</PHP>

The only reliable place to make that decision is **after DNS resolution and
before connect()**. ext/curl currently offers no hook there, so libraries work
around it:

  * They resolve the host themselves, check the result, and pin it with CURLOPT_RESOLVE. Symfony's ''NoPrivateNetworkHttpClient'' does this. The resolution is blocking, it duplicates libcurl's own, and it has to follow every redirect by hand.
  * They parse the URL and validate the host. This misses the many spellings libcurl accepts for the same address (''2130706433'', ''0x7f.1'', ''127.1'', IPv4-mapped IPv6), and it is defeated by DNS rebinding, since the name is resolved again at connect time.

Several projects reported both problems in the discussion thread. libcurl
already has the right hook, CURLOPT_OPENSOCKETFUNCTION, which is called with the
resolved address of every socket it is about to create. This RFC exposes it,
reduced to the decision it needs to make.

===== Proposal =====

A new option, ''CURLOPT_OPENSOCKETFUNCTION'', registers a callback that allows
or refuses each connection:

<PHP>
<?php

/**
 * @var int
 * @cvalue CURLOPT_OPENSOCKETFUNCTION
 */
const CURLOPT_OPENSOCKETFUNCTION = UNKNOWN; // 20163, libcurl's value

// The callback:
function (CurlHandle $handle, string $address, int $port): bool {}

?>
</PHP>

The callback's parameters:

  * ''$handle'': the CurlHandle performing the transfer. It comes first, as in every other ext/curl callback. For a copy made with curl_copy_handle() or ''clone'', it is the copy. ''curl_getinfo($handle, CURLINFO_EFFECTIVE_URL)'' tells which URL the address is for, redirects included.
  * ''$address'': the literal IPv4 or IPv6 address, in the form inet_ntop() produces. For a UNIX socket, the path given with CURLOPT_UNIX_SOCKET_PATH or CURLOPT_ABSTRACT_UNIX_SOCKET. An abstract name keeps its leading NUL byte.
  * ''$port'': the destination port, or 0 for a UNIX socket, as CURLOPT_PREREQFUNCTION and CURLINFO_PRIMARY_PORT report it.

==== Semantics ====

  * **true** allows the connection. ext/curl then creates the socket with ''socket(family, socktype, protocol)'', which is what libcurl documents as the default behaviour of the hook. Everything libcurl does next (non-blocking mode, CURLOPT_INTERFACE and CURLOPT_LOCALPORT, CURLOPT_SOCKOPTFUNCTION, TCP options) is unchanged. An allowed connection is therefore established exactly as it would have been without the option.
  * **false** refuses it. libcurl then tries the next address of the host, if any, and the transfer fails with CURLE_COULDNT_CONNECT once none is left.
  * Any other return value raises a TypeError and refuses the connection.
  * An exception thrown by the callback refuses the connection and propagates out of curl_exec() or curl_multi_exec(), like an exception from any other ext/curl callback.

The callback is invoked once per socket, not once per transfer:

  * When a host resolves to several addresses, or with Happy Eyeballs on a dual stack host, it is invoked for each address libcurl tries.
  * Every redirect hop that opens a new connection is vetted.
  * A connection reused from libcurl's pool creates no socket, so the callback is not invoked for it. A handle reuses connections from its own pool, from its multi handle, and from a share with CURL_LOCK_DATA_CONNECT; setting the same callback on every handle that uses a given pool ensures each pooled connection was allowed when it was opened. To vet reused connections as well, use CURLOPT_PREREQFUNCTION, which runs before every request.

What cannot be described to the callback is refused without invoking it, so that
a policy can never be bypassed by an endpoint it was not shown:

  * address families other than AF_INET, AF_INET6 and AF_UNIX;
  * sockets created for a purpose other than CURLSOCKTYPE_IPCXN, the only one libcurl uses today;
  * on Windows, AF_UNIX endpoints (see Open Issues).

The option behaves like every other callable option of ext/curl:
  * ''null'' removes it;
  * curl_reset() clears it;
  * curl_copy_handle() and ''clone'' carry it over;
  * the callback is reported to the cycle collector;
  * an invalid callable throws the same TypeError as for the other options.

==== What the callback sees ====

The callback is invoked for the sockets libcurl creates for the transfer. It
works alongside the existing options, which the documentation will point to:

  * CURLOPT_PROTOCOLS_STR and CURLOPT_REDIR_PROTOCOLS_STR select the schemes a transfer may use, for instance ''"http,https"''. Schemes such as ''file://'' open no socket.
  * With a proxy, the callback is given the proxy's address. CURLOPT_PROXY set to an empty string ignores proxies configured in the environment.
  * Connections made for CURLOPT_DOH_URL are not passed to it.

==== Why a bool, and not a socket ====

In libcurl, the callback returns the socket it created. An earlier proposal
(GH-22159) mirrored that and returned a ''Socket'' from ext/sockets. Review
raised the following objections, and this RFC agrees with them:

  * ext/curl would depend on ext/sockets.
  * Ownership of the descriptor becomes ambiguous between PHP and libcurl, and closing it properly requires CURLOPT_CLOSESOCKETFUNCTION as well.
  * Almost no use case needs anything beyond allow/refuse: the option has existed in libcurl for nearly two decades, and the requests for it in PHP are about filtering.

The bool also keeps the door open. Widening the return type later to, say,
''bool|CurlSocket'' (a curl-specific socket description, as suggested in review)
would not break any existing callback, and neither would appending parameters.
The leading parameters are the only part that cannot change later. They are
the ones most likely to be useful: the handle, then what libcurl knows about
the endpoint.

==== Why the libcurl name ====

A second proposal (GH-23657) used a PHP-specific name,
CURLOPT_PRECONNECTFUNCTION, precisely because the semantics differ from
libcurl's. The discussion preferred keeping ext/curl a thin layer over libcurl,
with libcurl's option names and values. CURLOPT_OPENSOCKETFUNCTION has
libcurl's value, and its documentation will describe the difference.

==== Why no address family ====

Version 0.1 passed a ''CurlAddressFamily'' enum (''IpV4'', ''IpV6'', ''Unix'')
before the address, and a null port for UNIX sockets. Review on the pull
request showed that the address alone is enough:

  * An IP-based policy rejects socket paths by itself: filter_var() with FILTER_VALIDATE_IP returns false for a path or an abstract name, so the refusal is the default.
  * A policy that does accept some UNIX sockets can tell them apart with the same filter_var() call. IPv4 and IPv6 are told apart with FILTER_FLAG_IPV4 and FILTER_FLAG_IPV6.
  * A port of 0 for UNIX sockets is what CURLOPT_PREREQFUNCTION and CURLINFO_PRIMARY_PORT already report, so all three agree.
  * The family can mislead: an IPv4-mapped IPv6 address (''::ffff:127.0.0.1'') reaches an IPv4 host from an AF_INET6 socket. A policy has to look at the address anyway.
  * It saves a new global type.

The only address the callback cannot classify is a relative socket path that
looks like an IP, such as a file named ''10.0.0.5''. That path comes from
CURLOPT_UNIX_SOCKET_PATH, which is set by the application, not by the URL.

If a use case for the family appears, it can be appended as a parameter later
without breaking existing callbacks.

==== Examples ====

Allowing only publicly routable addresses:

<PHP>
<?php

$ch = curl_init('https://www.php.net/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_PROTOCOLS_STR, 'http,https');
curl_setopt($ch, CURLOPT_REDIR_PROTOCOLS_STR, 'http,https');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $handle, string $address, int $port): bool {
        return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false;
    });

$body = curl_exec($ch);

?>
</PHP>

FILTER_FLAG_GLOBAL_RANGE follows the IANA special-purpose address registries.
Applications that want a deny list maintained for outgoing requests can use
the one of Symfony's ''NoPrivateNetworkHttpClient'',
[[https://github.com/symfony/symfony/blob/8.2/src/Symfony/Component/HttpFoundation/IpUtils.php#L19|IpUtils::PRIVATE_SUBNETS]],
which also refuses the NAT64 prefixes (''64:ff9b::/96'' and
''64:ff9b:1::/48''). FILTER_FLAG_GLOBAL_RANGE accepts them, as the IANA
registry lists the well-known prefix as globally reachable, while an address
such as ''64:ff9b::a9fe:a9fe'' reaches 169.254.169.254 through a NAT64
gateway:

<PHP>
<?php

use Symfony\Component\HttpFoundation\IpUtils;

curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $handle, string $address, int $port): bool {
        return filter_var($address, FILTER_VALIDATE_IP) !== false
            && !IpUtils::checkIp($address, IpUtils::PRIVATE_SUBNETS);
    });

?>
</PHP>

Edge case: an IPv4-mapped IPv6 address is reported in its IPv6 form.
FILTER_FLAG_GLOBAL_RANGE refuses it, as it refuses every address of the
''::ffff:0:0/96'' block, ''::ffff:8.8.8.8'' included: it does not look at the
embedded IPv4 address. So does Symfony's ''IpUtils::PRIVATE_SUBNETS''.

<PHP>
<?php

$ch = curl_init('http://[::ffff:127.0.0.1]:8080/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $handle, string $address, int $port): bool {
        var_dump($address, $port);
        return filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false;
    });

var_dump(curl_exec($ch));
var_dump(curl_errno($ch) === CURLE_COULDNT_CONNECT);

// string(16) "::ffff:127.0.0.1"
// int(8080)
// bool(false)
// bool(true)

?>
</PHP>

Edge case: a redirect to an internal address is refused at the hop that would
reach it, and the handle tells which URL that hop was for:

<PHP>
<?php

$ch = curl_init('https://example.com/redirects-to-metadata');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $handle, string $address, int $port): bool {
        $allowed = filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_GLOBAL_RANGE) !== false;
        if (!$allowed) {
            error_log(sprintf('Refused %s:%d for %s', $address, $port,
                curl_getinfo($handle, CURLINFO_EFFECTIVE_URL)));
        }
        return $allowed;
    });

curl_exec($ch);

?>
</PHP>

===== Backward Incompatible Changes =====

One new global symbol, the ''CURLOPT_OPENSOCKETFUNCTION'' constant. Code that
declares it in the global namespace will conflict. A search of public code on
GitHub found no use of it outside the polyfill below, which declares it only
when ext/curl does not.

===== Proposed PHP Version(s) =====

Next PHP 8.x.

===== RFC Impact =====

==== To the Ecosystem ====

IDEs, language servers and static analysers need a stub for the new constant.
Nothing else changes for them: the callback is an ordinary callable.

HTTP libraries built on ext/curl, such as Symfony HttpClient and Guzzle, can
vet connections with the option instead of resolving hosts themselves.

''curl_hardening'' (https://github.com/xavierleune/curl-hardening, MIT) is a
polyfill that implements this exact API for PHP 8.3 to 8.6. On a PHP that
provides the option natively, it registers nothing and stays inert, so code
written against this RFC runs unchanged on both.

==== To Existing Extensions ====

ext/curl only. The callback adds no cost to handles that do not set the option.

==== To SAPIs ====

None.

===== Open Issues =====

  * On Windows, ext/curl does not describe AF_UNIX endpoints (Winsock lacks ''sockaddr_un'' in the headers ext/curl uses). With the option set, such connections are therefore refused without calling the callback, which fails closed. They could be supported through ''afunix.h'' if there is demand.

===== Future Scope =====

  * **Streams.** The same need exists for ''file_get_contents()'' and the ''http://'' wrapper, as raised in the discussion. The decision has to be made per request, so it belongs in each API rather than in a global setting. A stream context option deserves its own RFC.
  * **Passing the address family.** It can be appended as a parameter if a use case appears (see "Why no address family").
  * **Returning a socket description.** If use cases emerge, the return type can be widened (see "Why a bool, and not a socket").

===== Voting Choices =====

----

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Add CURLOPT_OPENSOCKETFUNCTION to ext/curl as outlined in the RFC?" voteType="single" closed="true" closeon="2026-12-31T00:00:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====

https://github.com/php/php-src/pull/25414. The tests cover:
  * allow and refuse, including under curl_multi;
  * redirects;
  * reporting of IPv4, IPv6 and IPv4-mapped IPv6 addresses, and of UNIX and abstract sockets;
  * that ''file://'' opens no socket;
  * connection reuse, CURLOPT_FRESH_CONNECT and CURLOPT_PREREQFUNCTION;
  * copy, ''clone'' and reset, and a callback that removes itself;
  * invalid callables and return values, and exceptions;
  * cycle collection, and release of a handle whose connection stays pooled.

===== Implementation =====

After the RFC is implemented, this section will contain the version it was
merged into, a link to the commit, and a link to the manual entry.

===== References =====

  * libcurl: https://curl.se/libcurl/c/CURLOPT_OPENSOCKETFUNCTION.html
  * Symfony, deny list of non-public ranges: https://github.com/symfony/symfony/blob/8.2/src/Symfony/Component/HttpFoundation/IpUtils.php#L19
  * Symfony, NoPrivateNetworkHttpClient: https://github.com/symfony/symfony/blob/8.2/src/Symfony/Component/HttpClient/NoPrivateNetworkHttpClient.php
  * GH-22159, GH-23657: earlier proposals and their review
  * internals@: "SSRF protection in curl" (October 2026)

===== Rejected Features =====

  * Returning a Socket from ext/sockets (see "Why a bool, and not a socket").
  * A PHP-specific option name (see "Why the libcurl name").
  * A ''CurlAddressFamily'' enum parameter and a null port for UNIX sockets (see "Why no address family").
  * A ''$purpose'' parameter: libcurl only uses CURLSOCKTYPE_IPCXN; anything else is refused without calling the callback.

===== Changelog =====

  * 0.1 (2026-11-12): Initial version.
  * 0.2 (2026-11-12): Removed the CurlAddressFamily parameter; the port of a UNIX socket is 0 instead of null, as in CURLOPT_PREREQFUNCTION.
Page Tools
