clue / socks-server
Async SOCKS proxy server (SOCKS4, SOCKS4a and SOCKS5), built on top of React PHP
Requires
- php: >=5.3
- evenement/evenement: ~1.0|~2.0
- react/event-loop: 0.3.*|0.4.*
- react/promise: ^2.1 || ^1.2
- react/socket: ^0.7
- react/stream: ^0.6 || ^0.5 || ^0.4.2
Requires (Dev)
- clue/connection-manager-extra: ^0.7
- phpunit/phpunit: ^5.0 || ^4.8
This package is not auto-updated.
Last update: 2022-02-01 13:02:45 UTC
README
This package has now been merged into clue/socks-react and only exists for BC reasons.
$ composer require clue/socks-react
If you've previously used this package to build a SOCKS server,
upgrading should take no longer than a few minutes.
All classes have been merged as-is from the latest v0.7.0
release with no
other changes, so you can simply update your code to use the updated namespace
like this:
// old from clue/socks-server $server = new Clue\React\Socks\Server\Server($loop, $socket); // new $server = new Clue\React\Socks\Server($loop, $socket);
See https://github.com/clue/php-socks-react for more details.
The below documentation applies to the last release of this package. Further development will take place in the updated clue/socks-react, so you're highly recommended to upgrade as soon as possible.
Legacy clue/socks-server
Async SOCKS proxy server (SOCKS4, SOCKS4a and SOCKS5), built on top of React PHP.
The SOCKS protocol family can be used to easily tunnel TCP connections independent of the actual application level protocol, such as HTTP, SMTP, IMAP, Telnet etc.
Table of contents
Quickstart example
Once installed, you can use the following code to create a SOCKS
proxy server listening for connections on localhost:1080
:
$loop = React\EventLoop\Factory::create(); // listen on localhost:1080 $socket = new Socket($loop); $socket->listen(1080,'localhost'); // start a new server listening for incoming connection on the given socket $server = new Server($loop, $socket); $loop->run();
See also the examples.
Usage
Server
The Server
is responsible for accepting incoming communication from SOCKS clients
and forwarding the requested connection to the target host.
It also registers everything with the main EventLoop
and an underlying TCP/IP socket server like this:
$loop = \React\EventLoop\Factory::create(); // listen on localhost:$port $socket = new Socket($loop); $socket->listen($port,'localhost'); $server = new Server($loop, $socket);
If you need custom connector settings (DNS resolution, timeouts etc.), you can explicitly pass a
custom instance of the ConnectorInterface
:
// use local DNS server $dnsResolverFactory = new DnsFactory(); $resolver = $dnsResolverFactory->createCached('127.0.0.1', $loop); // outgoing connections to target host via interface 192.168.10.1 $connector = new DnsConnector( new TcpConnector($loop, array('bindto' => '192.168.10.1:0')), $resolver ); $server = new Server($loop, $socket, $connector);
Protocol version
The Server
supports all protocol versions (SOCKS4, SOCKS4a and SOCKS5) by default.
While SOCKS4 already had (a somewhat limited) support for SOCKS BIND
requests
and SOCKS5 added generic UDP support (SOCKS UDPASSOCIATE
), this library
focuses on the most commonly used core feature of SOCKS CONNECT
.
In this mode, a SOCKS server acts as a generic proxy allowing higher level
application protocols to work through it.
SOCKS4 | SOCKS4a | SOCKS5 | |
---|---|---|---|
Protocol specification | SOCKS4.protocol | SOCKS4A.protocol | RFC 1928 |
Tunnel outgoing TCP connections | ✓ | ✓ | ✓ |
Remote DNS resolving | ✗ | ✓ | ✓ |
IPv6 addresses | ✗ | ✗ | ✓ |
Username/Password authentication | ✗ | ✗ | ✓ (as per RFC 1929) |
Handshake # roundtrips | 1 | 1 | 2 (3 with authentication) |
Handshake traffic + remote DNS |
17 bytes ✗ |
17 bytes + hostname + 1 |
variable (+ auth + IPv6) + hostname - 3 |
Note, this is not a full SOCKS5 implementation due to missing GSSAPI authentication (but it's unlikely you're going to miss it anyway).
If want to explicitly set the protocol version, use the supported values 4
, 4a
or 5
:
$server->setProtocolVersion(5);
In order to reset the protocol version to its default (i.e. automatic detection),
use null
as protocol version.
$server->setProtocolVersion(null);
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.
Because your authentication mechanism might take some time to actually check the provided authentication credentials (like querying a remote database or webservice), the server side uses a Promise based interface. While this might seem complex at first, it actually provides a very simple way to handle simultanous connections in a non-blocking fashion and increases overall performance.
$server->setAuth(function ($username, $password) { // either return a boolean success value right away // or use promises for delayed authentication });
Or if you only accept static authentication details, you can use the simple array-based authentication method as a shortcut:
$server->setAuthArray(array( 'tom' => 'password', 'admin' => 'root' ));
See also the second example.
If you do not want to use authentication anymore:
$server->unsetAuth();
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 a SOCKS
connector from the following SOCKS client package:
$ composer require clue/socks-react:^0.7
You can now create a SOCKS Client
instance like this:
// set next SOCKS server localhost:$targetPort as target $connector = new React\Socket\TcpConnector($loop); $client = new Clue\React\Socks\Client('user:pass@127.0.0.1:' . $targetPort, $connector); // listen on localhost:$middlemanPort $socket = new Socket($loop); $socket->listen($middlemanPort, 'localhost'); // start a new server which forwards all connections to the other SOCKS server $server = new Server($loop, $socket, $client);
See also the example #11.
Proxy chaining can happen on the server side and/or the client side:
-
If you ask your client to chain through multiple proxies, then each proxy server does not really know anything about chaining at all. This means that this is a client-only property and not part of this project. For example, you can find this in the companion SOCKS client side project clue/socks-react.
-
If you ask your server to chain through another proxy, then your client does not really know anything about chaining at all. This means that this is a server-only property and can be implemented as above.
Install
The recommended way to install this library is through Composer. New to Composer?
This will install the latest supported version:
$ composer require clue/socks-server:^0.7
See also the CHANGELOG for details about version upgrades.
Tests
To run the test suite, you first need to clone this repo and then install all dependencies through Composer:
$ composer install
To run the test suite, go to the project root and run:
$ php vendor/bin/phpunit
License
MIT, see LICENSE
More
- If you're looking for an end-user SOCKS server daemon, you may want to use clue/psocksd.
- If you're looking for a SOCKS client implementation, consider using clue/socks-react.