clue/reactphp-socks

README

clue/reactphp-socks

Async SOCKS proxy connector client and server implementation, tunnel any TCP/IP-based protocol through a SOCKS5 or SOCKS4(a) proxy server, built on top of ReactPHP.

The SOCKS proxy protocol family (SOCKS5, SOCKS4 and SOCKS4a) is commonly used to tunnel HTTP(S) traffic through an intermediary ("proxy"), to conceal the origin address (anonymity) or to circumvent address blocking (geoblocking). While many (public) SOCKS proxy servers often limit this to HTTP(S) port 80 and 443 only, this can technically be used to tunnel any TCP/IP-based protocol (HTTP, SMTP, IMAP etc.). This library provides a simple API to create these tunneled connections for you. Because it implements ReactPHP's standard ConnectorInterface, it can simply be used in place of a normal connector. This makes it fairly simple to add SOCKS proxy support to pretty much any existing higher-level protocol implementation. Besides the client side, it also provides a simple SOCKS server implementation which allows you to build your own SOCKS proxy servers with custom business logic.

Async execution of connections - Send any number of SOCKS requests in parallel and process their responses as soon as results come in. The Promise-based design provides a sane interface to working with out of order responses and possible connection errors.
Standard interfaces - Allows easy integration with existing higher-level components by implementing ReactPHP's standard ConnectorInterface.
Lightweight, SOLID design - Provides a thin abstraction that is just good enough and does not get in your way. Builds on top of well-tested components and well-established concepts instead of reinventing the wheel.
Good test coverage - Comes with an automated tests suite and is regularly tested against actual proxy servers in the wild.

Table of contents

Support us
Quickstart example
Usage
- Client
- Server
Servers
Install
Tests
License
More

Support us

I maintain an ecosystem of open-source projects that have been downloaded hundreds of millions of times and are actively maintained and continuously improved. If you find any of these projects useful, please consider becoming a sponsor on GitHub. Your support helps ensure long-term maintenance and continued development. Thank you! 🚀

Quickstart example

Once installed, you can use the following code to send a secure HTTPS request to google.com through a local SOCKS proxy server:

<?php

require __DIR__ . '/vendor/autoload.php';

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false
));

$browser = new React\Http\Browser($connector);

$browser->get('https://google.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
    var_dump($response->getHeaders(), (string) $response->getBody());
}, function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

If you're not already running any other SOCKS proxy server, you can use the following code to create a SOCKS proxy server listening for connections on 127.0.0.1:1080:

<?php

require __DIR__ . '/vendor/autoload.php';

// start a new SOCKS proxy server
$socks = new Clue\React\Socks\Server();

// listen on 127.0.0.1:1080
$socket = new React\Socket\SocketServer('127.0.0.1:1080');
$socks->listen($socket);

Usage

Client

The Client is responsible for communication with your SOCKS server instance.

Its constructor simply accepts a SOCKS proxy URI with the SOCKS proxy server address:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

You can omit the port if you're using the default SOCKS port 1080:

$proxy = new Clue\React\Socks\Client('127.0.0.1');

If you need custom connector settings (DNS resolution, TLS parameters, timeouts, proxy servers etc.), you can explicitly pass a custom instance of the ConnectorInterface:

$connector = new React\Socket\Connector(array(
    'dns' => '127.0.0.1',
    'tcp' => array(
        'bindto' => '192.168.10.1:0'
    )
));

$proxy = new Clue\React\Socks\Client('my-socks-server.local:1080', $connector);

This is one of the two main classes in this package. Because it implements ReactPHP's standard ConnectorInterface, it can simply be used in place of a normal connector. Accordingly, it provides only a single public method, the connect() method. The connect(string $uri): PromiseInterface<ConnectionInterface, Exception> method can be used to establish a streaming connection. It returns a Promise which either fulfills with a ConnectionInterface on success or rejects with an Exception on error.

This makes it fairly simple to add SOCKS proxy support to pretty much any higher-level component:

- $acme = new AcmeApi($connector);
+ $proxy = new Clue\React\Socks\Client('127.0.0.1:1080', $connector);
+ $acme = new AcmeApi($proxy);

Plain TCP connections

SOCKS proxies are most frequently used to issue HTTP(S) requests to your destination. However, this is actually performed on a higher protocol layer and this connector is actually inherently a general-purpose plain TCP/IP connector. As documented above, you can simply invoke its connect() method to establish a streaming plain TCP/IP connection and use any higher level protocol like so:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$proxy->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
    echo 'connected to www.google.com:80';
    $connection->write("GET / HTTP/1.0\r\n\r\n");

    $connection->on('data', function ($chunk) {
        echo $chunk;
    });
});

You can either use the Client directly or you may want to wrap this connector in ReactPHP's Connector:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false
));

$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
    echo 'connected to www.google.com:80';
    $connection->write("GET / HTTP/1.0\r\n\r\n");

    $connection->on('data', function ($chunk) {
        echo $chunk;
    });
});

Secure TLS connections

This class can also be used if you want to establish a secure TLS connection (formerly known as SSL) between you and your destination, such as when using secure HTTPS to your destination site. You can simply wrap this connector in ReactPHP's Connector:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false
));

$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
    // proceed with just the plain text data
    // everything is encrypted/decrypted automatically
    echo 'connected to SSL encrypted www.google.com';
    $connection->write("GET / HTTP/1.0\r\n\r\n");

    $connection->on('data', function ($chunk) {
        echo $chunk;
    });
});

HTTP requests

This library also allows you to send HTTP requests through a SOCKS proxy server.

In order to send HTTP requests, you first have to add a dependency for ReactPHP's async HTTP client. This allows you to send both plain HTTP and TLS-encrypted HTTPS requests like this:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false
));

$browser = new React\Http\Browser($connector);

$browser->get('https://example.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
    var_dump($response->getHeaders(), (string) $response->getBody());
}, function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

See also ReactPHP's HTTP client and any of the examples for more details.

Protocol version

This library supports the SOCKS5 and SOCKS4(a) protocol versions. It focuses on the most commonly used core feature of connecting to a destination host through the SOCKS proxy server. In this mode, a SOCKS proxy server acts as a generic proxy allowing higher level application protocols to work through it.

	SOCKS5	SOCKS4(a)
Protocol specification	RFC 1928	SOCKS4.protocol / SOCKS4A.protocol
Tunnel outgoing TCP/IP connections	✓	✓
Remote DNS resolution	✓	✗ / ✓
IPv6 addresses	✓	✗
Username/Password authentication	✓ (as per RFC 1929)	✗
Handshake # roundtrips	2 (3 with authentication)	1
Handshake traffic + remote DNS	variable (+ auth + IPv6) + hostname - 3	17 bytes + hostname + 1
Incoming BIND requests	not implemented	not implemented
UDP datagrams	not implemented	✗
GSSAPI authentication	not implemented	✗

By default, the Client communicates via SOCKS5 with the SOCKS server. This is done because SOCKS5 is the latest version from the SOCKS protocol family and generally has best support across other vendors. You can also omit the default socks:// URI scheme. Similarly, the socks5:// URI scheme acts as an alias for the default socks:// URI scheme.

// all three forms are equivalent
$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');
$proxy = new Clue\React\Socks\Client('socks://127.0.0.1:1080');
$proxy = new Clue\React\Socks\Client('socks5://127.0.0.1:1080');

If want to explicitly set the protocol version to SOCKS4(a), you can use the URI scheme socks4:// as part of the SOCKS URI:

$proxy = new Clue\React\Socks\Client('socks4://127.0.0.1:1080');

DNS resolution

By default, the Client does not perform any DNS resolution at all and simply forwards any hostname you're trying to connect to to the SOCKS server. The remote SOCKS server is thus responsible for looking up any hostnames via DNS (this default mode is thus called remote DNS resolution). As seen above, this mode is supported by the SOCKS5 and SOCKS4a protocols, but not the original SOCKS4 protocol, as the protocol lacks a way to communicate hostnames.

On the other hand, all SOCKS protocol versions support sending destination IP addresses to the SOCKS server. In this mode you either have to stick to using IPs only (which is ofen unfeasable) or perform any DNS lookups locally and only transmit the resolved destination IPs (this mode is thus called local DNS resolution).

The default remote DNS resolution is useful if your local Client either can not resolve target hostnames because it has no direct access to the internet or if it should not resolve target hostnames because its outgoing DNS traffic might be intercepted (in particular when using the Tor network).

As noted above, the Client defaults to using remote DNS resolution. However, wrapping the Client in ReactPHP's Connector actually performs local DNS resolution unless explicitly defined otherwise. Given that remote DNS resolution is assumed to be the preferred mode, all other examples explicitly disable DNS resolution like this:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false
));

If you want to explicitly use local DNS resolution (such as when explicitly using SOCKS4), you can use the following code:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

// set up Connector which uses Google's public DNS (8.8.8.8)
$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => '8.8.8.8'
));

Authentication

This library supports username/password authentication for SOCKS5 servers as defined in RFC 1929.

On the client side, simply pass your username and password to use for authentication (see below). For each further connection the client will merely send a flag to the server indicating authentication information is available. Only if the server requests authentication during the initial handshake, the actual authentication credentials will be transmitted to the server.

Note that the password is transmitted in cleartext to the SOCKS proxy server, so this methods should not be used on a network where you have to worry about eavesdropping.

You can simply pass the authentication information as part of the SOCKS URI:

$proxy = new Clue\React\Socks\Client('alice:password@127.0.0.1:1080');

Note that both the username and password must be percent-encoded if they contain special characters:

$user = 'he:llo';
$pass = 'p@ss';
$url = rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1:1080';

$proxy = new Clue\React\Socks\Client($url);

The authentication details will be transmitted in cleartext to the SOCKS proxy server only if it requires username/password authentication. If the authentication details are missing or not accepted by the remote SOCKS proxy server, it is expected to reject each connection attempt with an exception error code of SOCKET_EACCES (13).

Authentication is only supported by protocol version 5 (SOCKS5), so passing authentication to the Client enforces communication with protocol version 5 and complains if you have explicitly set anything else:

// throws InvalidArgumentException
new Clue\React\Socks\Client('socks4://alice:password@127.0.0.1:1080');

Proxy chaining

The Client is responsible for creating connections to the SOCKS server which then connects to the target host.

Client -> SocksServer -> TargetHost

Sometimes it may be required to establish outgoing connections via another SOCKS server. For example, this can be useful if you want to conceal your origin address.

Client -> MiddlemanSocksServer -> TargetSocksServer -> TargetHost

The Client uses any instance of the ConnectorInterface to establish outgoing connections. In order to connect through another SOCKS server, you can simply use another SOCKS connector from another SOCKS client like this:

// https via the proxy chain  "MiddlemanSocksServer -> TargetSocksServer -> TargetHost"
// please note how the client uses TargetSocksServer (not MiddlemanSocksServer!),
// which in turn then uses MiddlemanSocksServer.
// this creates a TCP/IP connection to MiddlemanSocksServer, which then connects
// to TargetSocksServer, which then connects to the TargetHost
$middle = new Clue\React\Socks\Client('127.0.0.1:1080');
$target = new Clue\React\Socks\Client('example.com:1080', $middle);

$connector = new React\Socket\Connector(array(
    'tcp' => $target,
    'dns' => false
));

$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
    // …
});

Connection timeout

By default, the Client does not implement any timeouts for establishing remote connections. Your underlying operating system may impose limits on pending and/or idle TCP/IP connections, anywhere in a range of a few minutes to several hours.

Many use cases require more control over the timeout and likely values much smaller, usually in the range of a few seconds only.

You can use ReactPHP's Connector to decorate any given ConnectorInterface instance. It provides the same connect() method, but will automatically reject the underlying connection attempt if it takes too long:

$proxy = new Clue\React\Socks\Client('127.0.0.1:1080');

$connector = new React\Socket\Connector(array(
    'tcp' => $proxy,
    'dns' => false,
    'timeout' => 3.0
));

$connector->connect('tcp://google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
    // connection succeeded within 3.0 seconds
});

SOCKS over TLS

All SOCKS protocol versions support forwarding TCP/IP based connections and higher level protocols. This implies that you can also use secure TLS connections to transfer sensitive data across SOCKS proxy servers. This means that no eavesdropper nor the proxy server will be able to decrypt your data.

However, the initial SOCKS communication between the client and the proxy is usually via an unencrypted, plain TCP/IP connection. This means that an eavesdropper may be able to see where you connect to and may also be able to see your SOCKS authentication details in cleartext.

As an alternative, you may establish a secure TLS connection to your SOCKS proxy before starting the initial SOCKS communication. This means that no eavesdroppper will be able to see the destination address you want to connect to or your SOCKS authentication details.

You can use the sockss:// URI scheme or use an explicit SOCKS protocol version like this:

$proxy = new Clue\React\Socks\Client('sockss://127.0.0.1:1080');

$proxy = new Clue\React\Socks\Client('socks4s://127.0.0.1:1080');

Unix domain sockets

All SOCKS protocol versions support forwarding TCP/IP based connections and higher level protocols. In some advanced cases, it may be useful to let your SOCKS server listen on a Unix domain socket (UDS) path instead of a IP:port combination. For example, this allows you to rely on file system permissions instead of having to rely on explicit authentication.

You can use the socks+unix:// URI scheme or use an explicit SOCKS protocol version like this:

$proxy = new Clue\React\Socks\Client('socks+unix:///tmp/proxy.sock');

$proxy = new Clue\React\Socks\Client('socks4+unix:///tmp/proxy.sock');

Similarly, you can also combine this with authentication like this:

$proxy = new Clue\React\Socks\Client('socks+unix://alice:password@/tmp/proxy.sock');

Note that Unix domain sockets (UDS) are considered advanced usage and PHP only has limited support for this. In particular, enabling secure TLS may not be supported.

Note that the SOCKS protocol does not support the notion of UDS paths. The above works reasonably well because UDS is only used for the connection between client and proxy server and the path will not actually passed over the protocol. This implies that this does also not support proxy chaining over multiple UDS paths.

Server

The Server is responsible for accepting incoming communication from SOCKS clients and forwarding the requested connection to the target host. It supports the SOCKS5 and SOCKS4(a) protocol versions by default. You can start listening on an underlying TCP/IP socket server like this:

$socks = new Clue\React\Socks\Server();

// listen on 127.0.0.1:1080
$socket = new React\Socket\SocketServer('127.0.0.1:1080');
$socks->listen($socket);

This class takes an optional LoopInterface|null $loop parameter that can be used to pass the event loop instance to use for this object. You can use a null value here in order to use the default loop. This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance.

Additionally, the Server constructor accepts optional parameters to explicitly configure the connector to use and to require authentication. For more details, read on...

Server connector

The Server uses an instance of ReactPHP's ConnectorInterface to establish outgoing connections for each incoming connection request.

If you need custom connector settings (DNS resolution, TLS parameters, timeouts, proxy servers etc.), you can explicitly pass a custom instance of the ConnectorInterface:

$connector = new React\Socket\Connector(array(
    'dns' => '127.0.0.1',
    'tcp' => array(
        'bindto' => '192.168.10.1:0'
    )
));

$socks = new Clue\React\Socks\Server(null, $connector);

If you want to forward the outgoing connection through another SOCKS proxy, you may also pass a Client instance as a connector, see also server proxy chaining for more details.

Internally, the Server uses ReactPHP's normal connect() method, but it also passes the original client IP as the ?source={remote} parameter. The source parameter contains the full remote URI, including the protocol and any authentication details, for example socks://alice:password@1.2.3.4:5678 or socks4://1.2.3.4:5678 for legacy SOCKS4(a). You can use this parameter for logging purposes or to restrict connection requests for certain clients by providing a custom implementation of the ConnectorInterface.

Server authentication

By default, the Server does not require any authentication from the clients. You can enable authentication support so that clients need to pass a valid username and password before forwarding any connections.

Setting authentication on the Server enforces each further connected client to use protocol version 5 (SOCKS5). If a client tries to use any other protocol version, does not send along authentication details or if authentication details can not be verified, the connection will be rejected.

If you only want to accept static authentication details, you can simply pass an additional assoc array with your authentication details to the Server like this:

$socks = new Clue\React\Socks\Server(null, null, array(
    'alice' => 'password',
    'bob' => 's3cret!1'
));

Server proxy chaining

The Server is responsible for creating connections to the target host.

Client -> SocksServer -> TargetHost

Sometimes it may be required to establish outgoing connections via another SOCKS server. For example, this can be useful if your target SOCKS server requires authentication, but your client does not support sending authentication information (e.g. like most webbrowser).

Client -> MiddlemanSocksServer -> TargetSocksServer -> TargetHost

The Server uses any instance of the ConnectorInterface to establish outgoing connections. In order to connect through another SOCKS server, you can simply use the Client SOCKS connector from above. You can create a SOCKS Client instance like this:

// set next SOCKS server example.com:1080 as target
$proxy = new Clue\React\Socks\Client('alice:password@example.com:1080');

// start a new server which forwards all connections to the other SOCKS server
$socks = new Clue\React\Socks\Server(null, $proxy);

// listen on 127.0.0.1:1080
$socket = new React\Socket\SocketServer('127.0.0.1:1080');
$socks->listen($socket);

Server SOCKS over TLS

Both SOCKS5 and SOCKS4(a) protocol versions support forwarding TCP/IP based connections and higher level protocols. This implies that you can also use secure TLS connections to transfer sensitive data across SOCKS proxy servers. This means that no eavesdropper nor the proxy server will be able to decrypt your data.

However, the initial SOCKS communication between the client and the proxy is usually via an unencrypted, plain TCP/IP connection. This means that an eavesdropper may be able to see where the client connects to and may also be able to see the SOCKS authentication details in cleartext.

As an alternative, you may listen for SOCKS over TLS connections so that the client has to establish a secure TLS connection to your SOCKS proxy before starting the initial SOCKS communication. This means that no eavesdroppper will be able to see the destination address the client wants to connect to or their SOCKS authentication details.

You can simply start your listening socket on the tls:// URI scheme like this:

$socks = new Clue\React\Socks\Server();

// listen on tls://127.0.0.1:1080 with the given server certificate
$socket = new React\Socket\SocketServer('tls://127.0.0.1:1080', array(
    'tls' => array(
        'local_cert' => __DIR__ . '/localhost.pem',
    )
));
$socks->listen($socket);

Server Unix domain sockets

Both SOCKS5 and SOCKS4(a) protocol versions support forwarding TCP/IP based connections and higher level protocols. In some advanced cases, it may be useful to let your SOCKS server listen on a Unix domain socket (UDS) path instead of a IP:port combination. For example, this allows you to rely on file system permissions instead of having to rely on explicit authentication.

You can simply start your listening socket on the unix:// URI scheme like this:

$socks = new Clue\React\Socks\Server();

README