ext/curl: add socket callback options bridging to ext/sockets

[xavierleune]

Summary

This PR exposes libcurl's three socket-level callback options, which were previously unavailable in PHP:

• CURLOPT_SOCKOPTFUNCTION — invoked after a socket is created but before it is connected, to tune low-level socket options.
• CURLOPT_OPENSOCKETFUNCTION — invoked to create the socket for a connection, after the address has been resolved but before connect().
• CURLOPT_CLOSESOCKETFUNCTION — invoked when libcurl is done with a socket.

The main motivation is application security. CURLOPT_OPENSOCKETFUNCTION in particular lets an application inspect the resolved IP address and refuse the connection, which is the robust way to implement SSRF protection (it happens after DNS resolution, so it also defeats DNS-rebinding to internal addresses — something hostname/URL allow-listing cannot do). CURLOPT_SOCKOPTFUNCTION allows socket hardening (SO_BINDTODEVICE, keep-alive, packet marks, …).

API

The C callbacks take/return a raw curl_socket_t file descriptor, which pure PHP cannot create or read. To make the options usable from plain PHP, the callbacks exchange ext/sockets Socket objects, built on top of the C API already
exported by ext/sockets (socket_ce, the php_socket struct and socket_import_file_descriptor()):

// $purpose is CURLSOCKTYPE_IPCXN or CURLSOCKTYPE_ACCEPT
curl_setopt($ch, CURLOPT_SOCKOPTFUNCTION,
    function (CurlHandle $ch, Socket $socket, int $purpose): int {
        socket_set_option($socket, SOL_SOCKET, SO_KEEPALIVE, 1);
        return CURL_SOCKOPT_OK; // or CURL_SOCKOPT_ERROR / CURL_SOCKOPT_ALREADY_CONNECTED
    });

// $address = ['family' => int, 'socktype' => int, 'protocol' => int,
//             'ip' => string, 'port' => int]
curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
    function (CurlHandle $ch, int $purpose, array $address): Socket|false {
        // return false to abort the connection (CURL_SOCKET_BAD)
        return socket_create($address['family'], $address['socktype'], $address['protocol']);
    });

curl_setopt($ch, CURLOPT_CLOSESOCKETFUNCTION,
    function (CurlHandle $ch, Socket $socket): void {
        socket_close($socket);
    });

Example: blocking private/reserved IPs (SSRF protection)

Because CURLOPT_OPENSOCKETFUNCTION receives the resolved address, it can reject any request that would reach a private or reserved range — even if the attacker supplied a public hostname that resolves to an internal IP:

function ssrf_safe_curl(string $url): CurlHandle
{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_OPENSOCKETFUNCTION,
        function (CurlHandle $ch, int $purpose, array $address): Socket|false {
            // Reject the connection if the resolved IP is private or reserved.
            $isPublic = filter_var(
                $address['ip'],
                FILTER_VALIDATE_IP,
                FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE
            );

            if ($isPublic === false) {
                // e.g. 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16, 169.254.0.0/16,
                //      ::1, fc00::/7, … -> abort the connection.
                return false;
            }

            return socket_create($address['family'], $address['socktype'], $address['protocol']);
        });

    return $ch;
}

$ch = ssrf_safe_curl('http://169.254.169.254/latest/meta-data/'); // cloud metadata
var_dump(curl_exec($ch));                 // bool(false)
var_dump(curl_errno($ch) === CURLE_COULDNT_CONNECT); // bool(true)

Implementation notes

• The whole feature is guarded by HAVE_SOCKETS. ext/curl gains a ZEND_MOD_REQUIRED("sockets") dependency (plus PHP_ADD_EXTENSION_DEP); when built without ext/sockets, curl still builds, just without these options.
• File descriptors owned by libcurl are detached (bsd_socket = -1) before the temporary Socket object is released, to avoid a double close.
• CURLOPT_CLOSESOCKETFUNCTION is disabled right before curl_easy_cleanup(), so libcurl closes pooled sockets natively instead of calling into PHP while the handle is being destroyed (which can happen during GC/shutdown). The callback still fires for sockets closed during a transfer.
• Setting any of the options to null restores libcurl's native default.
• New constants: CURLOPT_SOCKOPTFUNCTION, CURLOPT_OPENSOCKETFUNCTION, CURLOPT_CLOSESOCKETFUNCTION, CURL_SOCKOPT_OK, CURL_SOCKOPT_ERROR, CURL_SOCKOPT_ALREADY_CONNECTED, CURLSOCKTYPE_IPCXN, CURLSOCKTYPE_ACCEPT.

Tests

Added .phpt coverage for each option (success, abort/error paths, invalid return types/values, null, curl_copy_handle) plus a trampoline test. The full ext/curl suite passes with no regressions.

Fixes: https://bugs.php.net/bug.php?id=62906

[xavierleune]

@Girgias 👋 hi gina, do you mind having a look on this one ?

[Girgias]

This looks sensible, although this probably would only ever work if ext/socket (and possibly ext/curl) are built statically into PHP. Which might be a problem for distributions.

I'm not really an expert in how to determine and handle optional dependencies, especially if they can be shared objects. So maybe @devnexen or @remicollet have pointers?

[devnexen]

I m not entirely certain that the ZEND_MOD_REQUIRED approach is necessarily the best in that case ... but I may look more into the sockets part itself and leave the dependency aspect to Remi, he probably knows better.

[xavierleune]

@Girgias @devnexen thanks for the feedback. You're right, ZEND_MOD_REQUIRED was not the better approach. I pushed a new one that removes the hard dependency between curl & sockets. It's aligned with ext/phar (optional deps on apc/bz2/openssl/zlib) & ext/exif (optional deps on mbstring).

[devnexen]

Instinctively speaking, I think this PR is fine (at least feature wise). However, I would like to see more test cases. e.g. what happens when you set TCP_NODELAY while curl se CURLOPT_TCP_NODELAY. What happens if you set the socket to blocking mode, what curl does ?

[xavierleune]

@devnexen new test cases added, with a little fix around socket closing. About custom options, libcurl seems to apply it's own option after the callback returns. So the implementation seems robust.
The failing test seems unrelated to this pull request.

[xavierleune]

@devnexen great catch on the sockopt exception path. You're right that it was inconsistent with opensocket/ssh_hostkey. Fixed: the callback now returns CURL_SOCKOPT_ERROR when EG(exception) is set after the call, so libcurl aborts instead of connecting with a half-configured socket. A new test case (Testing a callback that throws aborts the connection) covers this.

For the stream-backed Socket case in opensocket — looking at socket_free_obj(), when zstream is set it bypasses the bsd_socket check entirely and delegates the close to the backing php_stream. Our bsd_socket = -1 detach
is silently ignored in that path, so libcurl + the stream would both close the same fd. Rather than try to wrest fd ownership away from the stream (which would mean reaching into ext/sockets internals), the extension now
refuses such Sockets explicitly with a TypeError. New test added. While I was on that path I applied the same protection to already-closed Sockets (bsd_socket < 0): without it libcurl would just report a generic CURLE_COULDNT_CONNECT instead of pointing at the actual cause.

The socket_close() from within the sockopt callback case is also covered now: the callback returns CURL_SOCKOPT_ERROR after closing, libcurl aborts cleanly, no double-close. Test asserts curl_exec === false and
curl_errno !== 0.

Following the same logic I noticed curl_multi_free_obj() had the same exposure: curl_multi_cleanup() closes the multi's pooled connections and fires the close callback of every attached easy handle, and at that point the
easy handles' close FCCs are still initialised (they live as long as mh->easyh holds them). I added the equivalent FCC teardown there too, so the close callback can never fire from inside the multi's destructor either.

Two small coverage additions while I was in: a CURL_SOCKOPT_ALREADY_CONNECTED return-value test (asserts the constant flows through to libcurl), and a curl_reset() test that confirms the socket FCC is dropped when the
handle is reset.

[devnexen]

looking good in my opinion, note I am only judging the feature itself.

[xavierleune]

Thanks a lot for your help and great feedbacks @devnexen

[bukka]

We are working on something slightly related so please don't merge this until we get better idea about the implications. Basically we want to expose the underlying socket for polling but if it can be also represented with Socket, it might potentially complicate things. This is not a stop for this, we just need to check it out first.

[bukka]

CC @arnaud-lb

[bukka]

Also this is related note in updated docs: https://github.com/curl/curl/pull/22081/changes . I wonder if it could be potentially a bit confusing for users when different sockets are used. But it shouldn't be really an issue, just something to be aware of.

[shyim]

It would be nice if this could be backported as a security "tool" to all supported PHP versions. We wanna use this in our application to protect against DNS-rebind/SSRF protection. Kinda callback to CURLOPT_OPENSOCKETFUNCTION and reject connections against private IPs. Doing this right now on user-land is pretty uggly and easy to mess up.

[xavierleune]

@bukka thanks for the heads-up ! No-rush but the feature freezer for PHP 8.6 is coming quickly, maybe there is a draft PR or a sketch I can read to check if it fits well together ? I'm happy to adjust the api here if required to smooth things on your side (I may need some help/guidance but I'm always willing to help).

@shyim that's a great idea and that's the exact use case I've in mind, I think this may be difficult regarding the version policy. Perhaps you may share this idea on internals (in reaction to my original thread) to get some feedback from maintainers ?

[xavierleune]

@Girgias heeeelp 😄 I don't know how to get forward on this. I already sent 2 emails with exactly 0 answer on internals, WDYT ? Thanks !

[Sjord]

Looks good to me!

@arnaud-lb Could you take a look at this?

[Sjord]

@bukka

We are working on something slightly related so please don't merge this until we get better idea about the implications.

Do you have more information on this? A pull request link? Is this PR still good to go?

[xavierleune]

@Sjord thanks for the ping of @bukka and @arnaud-lb. It seems that everyone has their hands full. How can I help to get this merged into 8.6 ? I've been told that this may go after feature freeze, but 2 betas already have been released. I hope this change can make it soon.

[Sjord]

@mbeccati Could you take a look at this? It is basically done and it would be nice if it went into PHP 8.6, but it's been stuck for a while for unclear reasons.

[mbeccati]

@Sjord I don't think we can safely merge, unless we've got green lights from @bukka and @arnaud-lb. Sorry, we can't just bypass that.

[bukka]

Sorry, we are super busy with security stuff.

I'm honestly not so sure if mixing up curl and socket ext object is a good idea and if it wouldn't be better to have our limited abstraction where we control it rather than providing user callback. The thing that worries me is is what happens if you keep the created socket so the object is alive and then the IO is mixed up with the curl execution. It might get even messier if such socket gets turned into the stream.

I actually let Claude do the investigation exactly in that area - it didn't find an IO issue (it wasn't doing too much testing though) but it found double close as well as other issues when just CURLOPT_SOCKOPTFUNCTION. This was a really quick scan but it shows to me that it's not exactly ready and we might need to think about this more especially if we are considering including the hooks / reactor stuff. So it will likely need delay.

Here are some PoC example that it gave it to me:

<?php
/* PoC: the Socket handed INTO the sockopt callback can be turned into a stream
 * with socket_export_stream(). That stream keeps its own copy of curl's fd, so
 * the extension's bsd_socket=-1 detach no longer protects it: curl and the
 * stream both close the same descriptor number. After fd reuse the stream's
 * second close destroys an unrelated resource.
 */
$port = 18093;
$pid = pcntl_fork();
if ($pid === 0) { server($port); exit; }
usleep(300000);

$keep = null;
$ch = curl_init("http://127.0.0.1:$port/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SOCKOPTFUNCTION, function ($ch, $s, $p) use (&$keep) {
    $keep = socket_export_stream($s);      // stream now owns curl's fd
    return CURL_SOCKOPT_OK;
});
var_dump(curl_exec($ch));                    // curl finishes, but still owns the fd

unset($keep);                               // (1) stream dtor closes curl's fd N
                                            //     -> now closed once, while curl still thinks it owns it
$victim = fopen(__FILE__, 'r');             // (2) OS hands fd N to this file
var_dump(fread($victim, 5));                // reads "<?php" fine
unset($ch);                                 // (3) curl closes fd N a SECOND time == closes $victim's fd
var_dump(fread($victim, 5));                // victim's descriptor was pulled out from under it
echo "done\n";

pcntl_wait($st);

function server(int $port): void {
    $s = stream_socket_server("tcp://127.0.0.1:$port", $e, $m);
    if (!$s) exit(1);
    $c = stream_socket_accept($s, 5);
    if (!$c) exit;
    $req = '';
    while (($l = fgets($c)) !== false && rtrim($l) !== '') $req .= $l;
    fwrite($c, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok");
    fclose($c);
}

<?php
/* PoC: use-after-free via a share handle. The share owns the connection cache
 * (CURL_LOCK_DATA_CONNECT). Freeing the easy handle leaves a pooled connection
 * whose closesocket_client points at it; curl_share_cleanup() then fires the
 * close callback on freed memory. No teardown exists in curl_share_free_obj().
 */
$port = 18092;
$pid = pcntl_fork();
if ($pid === 0) { server($port); exit; }
usleep(300000);

$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);

$ch = curl_init("http://127.0.0.1:$port/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SHARE, $sh);
curl_setopt($ch, CURLOPT_CLOSESOCKETFUNCTION, function ($ch, $s) { /* noop */ });
var_dump(curl_exec($ch));

unset($ch);   // easy handle (clientp) freed; connection lives on in the share
echo "easy handle freed; connection still held by the share\n";

unset($sh);   // curl_share_cleanup() -> close cb on freed handle == UAF
echo "share freed\n";

if (function_exists("posix_kill")) posix_kill($pid, SIGKILL); pcntl_wait($st);

function server(int $port): void {
    $s = stream_socket_server("tcp://127.0.0.1:$port", $e, $m);
    if (!$s) exit(1);
    $c = stream_socket_accept($s, 5);
    if (!$c) exit;
    for ($i = 0; $i < 50; $i++) {
        $req = '';
        while (($l = fgets($c)) !== false && rtrim($l) !== '') $req .= $l;
        if ($req === '') break;
        fwrite($c, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: keep-alive\r\n\r\nok");
    }
}

<?php
/* PoC: use-after-free when a curl easy handle with CURLOPT_CLOSESOCKETFUNCTION
 * is removed from a multi handle and freed, while its keep-alive connection
 * stays in the multi's connection pool. curl_multi_cleanup() later fires the
 * close callback with a clientp pointing at the freed handle.
 *
 * Run under valgrind to see the invalid read; may also just crash.
 */
$port = 18091;
$pid = pcntl_fork();
if ($pid === 0) { server($port); exit; }        // child: server
usleep(300000);                                   // let the server bind

$ch = curl_init("http://127.0.0.1:$port/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CLOSESOCKETFUNCTION, function ($ch, $s) { /* noop */ });

$mh = curl_multi_init();
curl_multi_add_handle($mh, $ch);
do { curl_multi_exec($mh, $running); if ($running) curl_multi_select($mh); } while ($running);
var_dump(curl_multi_getcontent($ch));

curl_multi_remove_handle($mh, $ch);  // connection stays pooled in $mh
unset($ch);                          // easy handle (clientp) is freed here
echo "easy handle freed; connection still pooled in the multi\n";

unset($mh);                          // curl_multi_cleanup() -> close cb on freed handle == UAF
echo "multi freed\n";

if (function_exists("posix_kill")) posix_kill($pid, SIGKILL); pcntl_wait($st);

function server(int $port): void {
    $s = stream_socket_server("tcp://127.0.0.1:$port", $e, $m);
    if (!$s) exit(1);
    $c = stream_socket_accept($s, 5);
    if (!$c) exit;
    for ($i = 0; $i < 50; $i++) {
        $req = '';
        while (($l = fgets($c)) !== false && rtrim($l) !== '') $req .= $l;
        if ($req === '') break;
        fwrite($c, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: keep-alive\r\n\r\nok");
    }
}

[arnaud-lb]

We should introduce only CURLOPT_OPENSOCKETFUNCTION, with limited functionality: the callback should return only bool (not a socket). false to reject the connection, or true to accept it (the socket is created by internal code in that case). This seems enough to implement robust SSRF protection and doesn't preclude full support for returning a socket, or for other callbacks, later.

[bukka]

Just to clarify, this is not like rejection of this. I think we can make it safe but we need to look really in detail on the implementation and what could be the side effects and make sure it cannot crash. Unfortunately there is not much time and we need to deal with security issues right now and then look more into the async stuff.

[xavierleune]

@bukka if you're open to @arnaud-lb suggestion, I may work on this next week, including the risk of use after free that you pointed in your previous comment. WDYT ?
And if we feel like it we may implement the full userland socket creation in a future version.

Thanks to both of you for your feedbacks, good luck with the security issues.