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