Skip to content

Commit 1229206

Browse files
clueclue
committed
Update README.md
1 parent dbfa25a commit 1229206

1 file changed

Lines changed: 120 additions & 80 deletions

File tree

‎README.md‎

Lines changed: 120 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,6 @@ Async SOCKS client library to connect to SOCKS4, SOCKS4a and SOCKS5 proxy server
44
as well as a SOCKS server implementation, capable of handling multiple concurrent
55
connections in a non-blocking fashion.
66

7-
## Description
8-
9-
The SOCKS protocol family can be used to easily tunnel TCP connections independent
10-
of the actual application level protocol, such as HTTP, SMTP, IMAP, Telnet, etc.
11-
127
## Quickstart example
138

149
Once [installed](#install), you can use the following code to create a connection
@@ -27,46 +22,12 @@ $loop->run();
2722

2823
See also the [examples](examples).
2924

30-
### Tunnelled TCP connections
31-
32-
The `Client` uses a [Promise](https://github.com/reactphp/promise)-based interface which makes working with asynchronous functions a breeze.
33-
Let's open up a TCP [Stream](https://github.com/reactphp/stream) connection and write some data:
34-
```PHP
35-
$tcp = $client->createConnector();
36-
37-
$tcp->create('www.google.com',80)->then(function (React\Stream\Stream $stream) {
38-
echo 'connected to www.google.com:80';
39-
$stream->write("GET / HTTP/1.0\r\n\r\n");
40-
// ...
41-
});
42-
```
43-
44-
### SSL/TLS encrypted
45-
46-
If you want to connect to arbitrary SSL/TLS servers, there sure too is an easy to use API available:
47-
```PHP
48-
$ssl = $client->createSecureConnector();
49-
50-
// now create an SSL encrypted connection (notice the $ssl instead of $tcp)
51-
$ssl->create('www.google.com',443)->then(function (React\Stream\Stream $stream) {
52-
// proceed with just the plain text data
53-
// everything is encrypted/decrypted automatically
54-
echo 'connected to SSL encrypted www.google.com';
55-
$stream->write("GET / HTTP/1.0\r\n\r\n");
56-
// ...
57-
});
58-
```
59-
60-
### HTTP requests
25+
## Description
6126

62-
HTTP operates on a higher layer than this low-level SOCKS implementation.
63-
If you want to issue HTTP requests, you can add a dependency for
64-
[clue/buzz-react](https://github.com/clue/php-buzz-react).
65-
It can interact with this library by issuing all
66-
[http requests through a SOCKS server](https://github.com/clue/php-buzz-react#socks-proxy).
67-
This works for both plain HTTP and SSL encrypted HTTPS requests.
27+
The SOCKS protocol family can be used to easily tunnel TCP connections independent
28+
of the actual application level protocol, such as HTTP, SMTP, IMAP, Telnet etc.
6829

69-
## SOCKS Protocol versions & differences
30+
### SOCKS Protocol versions & differences
7031

7132
While SOCKS4 already had (a somewhat limited) support for `SOCKS BIND` requests
7233
and SOCKS5 added generic UDP support (`SOCKS UDPASSOCIATE`), this library
@@ -128,7 +89,95 @@ application protocols to work through it.
12889
Note, this is __not__ a full SOCKS5 implementation due to missing GSSAPI
12990
authentication (but it's unlikely you're going to miss it anyway).
13091

131-
### Explicitly setting protocol version
92+
### Using SSH as a SOCKS server
93+
94+
If you already have an SSH server set up, you can easily use it as a SOCKS
95+
tunnel end point. On your client, simply start your SSH client and use
96+
the `-D [port]` option to start a local SOCKS server (quoting the man page:
97+
a `local "dynamic" application-level port forwarding`) by issuing:
98+
99+
`$ ssh -D 9050 ssh-server`
100+
101+
```PHP
102+
$client = new Client('127.0.0.1:9050', $loop);
103+
```
104+
105+
### Using the Tor (anonymity network) to tunnel SOCKS connections
106+
107+
The [Tor anonymity network](http://www.torproject.org) client software is designed
108+
to encrypt your traffic and route it over a network of several nodes to conceal its origin.
109+
It presents a SOCKS4 and SOCKS5 interface on TCP port 9050 by default
110+
which allows you to tunnel any traffic through the anonymity network.
111+
In most scenarios you probably don't want your client to resolve the target hostnames,
112+
because you would leak DNS information to anybody observing your local traffic.
113+
Also, Tor provides hidden services through an `.onion` pseudo top-level domain
114+
which have to be resolved by Tor.
115+
116+
```PHP
117+
$client = new Client('127.0.0.1:9050', $loop);
118+
$client->setResolveLocal(false);
119+
```
120+
121+
## Usage
122+
123+
### Client
124+
125+
The `Client` is responsible for communication with your SOCKS server instance.
126+
It also registers everything with the main [`EventLoop`](https://github.com/reactphp/event-loop#usage).
127+
It accepts a SOCKS server URI like this:
128+
129+
```php
130+
$loop = \React\EventLoop\Factory::create();
131+
$client = new Client('127.0.0.1:1080', $loop);
132+
```
133+
134+
If you need custom connector settings (DNS resolution, timeouts etc.), you can explicitly pass a
135+
custom instance of the [`ConnectorInterface`](https://github.com/reactphp/socket-client#connectorinterface):
136+
137+
```php
138+
$client = new Client('127.0.0.1:1080', $loop, $connector);
139+
```
140+
141+
#### Tunnelled TCP connections
142+
143+
The `Client` uses a [Promise](https://github.com/reactphp/promise)-based interface which makes working with asynchronous functions a breeze.
144+
Let's open up a TCP [Stream](https://github.com/reactphp/stream) connection and write some data:
145+
```PHP
146+
$tcp = $client->createConnector();
147+
148+
$tcp->create('www.google.com',80)->then(function (React\Stream\Stream $stream) {
149+
echo 'connected to www.google.com:80';
150+
$stream->write("GET / HTTP/1.0\r\n\r\n");
151+
// ...
152+
});
153+
```
154+
155+
#### SSL/TLS encrypted
156+
157+
If you want to connect to arbitrary SSL/TLS servers, there sure too is an easy to use API available:
158+
```PHP
159+
$ssl = $client->createSecureConnector();
160+
161+
// now create an SSL encrypted connection (notice the $ssl instead of $tcp)
162+
$ssl->create('www.google.com',443)->then(function (React\Stream\Stream $stream) {
163+
// proceed with just the plain text data
164+
// everything is encrypted/decrypted automatically
165+
echo 'connected to SSL encrypted www.google.com';
166+
$stream->write("GET / HTTP/1.0\r\n\r\n");
167+
// ...
168+
});
169+
```
170+
171+
#### HTTP requests
172+
173+
HTTP operates on a higher layer than this low-level SOCKS implementation.
174+
If you want to issue HTTP requests, you can add a dependency for
175+
[clue/buzz-react](https://github.com/clue/php-buzz-react).
176+
It can interact with this library by issuing all
177+
[http requests through a SOCKS server](https://github.com/clue/php-buzz-react#socks-proxy).
178+
This works for both plain HTTP and SSL encrypted HTTPS requests.
179+
180+
#### Explicitly setting protocol version
132181

133182
This library supports the SOCKS4, SOCKS4a and SOCKS5 protocol versions.
134183
Usually, there's no need to worry about which protocol version is being used.
@@ -138,22 +187,18 @@ the `Client` automatically uses the _best_ protocol available.
138187
In general this library automatically switches to higher protocol versions
139188
when needed, but tries to keep things simple otherwise and sticks to lower
140189
protocol versions when possible.
141-
The `Server` supports all protocol versions by default.
142190

143191
If want to explicitly set the protocol version, use the supported values `4`, `4a` or `5`:
144192

145193
```PHP
146-
// valid protocol versions:
147194
$client->setProtocolVersion('4a');
148-
$server->setProtocolVersion(5);
149195
```
150196

151197
In order to reset the protocol version to its default (i.e. automatic detection),
152198
use `null` as protocol version.
153199

154200
```PHP
155201
$client->setProtocolVersion(null);
156-
$server->setProtocolVersion(null);
157202
```
158203

159204
### Remote vs. local DNS resolving
@@ -206,6 +251,33 @@ version 5 and complains if you have explicitly set anything else.
206251
$client->setAuth('username', 'password');
207252
```
208253

254+
If you do not want to use authentication anymore:
255+
256+
```PHP
257+
$client->unsetAuth();
258+
```
259+
260+
### Server
261+
262+
#### Server protocol
263+
264+
The `Server` supports all protocol versions by default.
265+
266+
If want to explicitly set the protocol version, use the supported values `4`, `4a` or `5`:
267+
268+
```PHP
269+
$server->setProtocolVersion(5);
270+
```
271+
272+
In order to reset the protocol version to its default (i.e. automatic detection),
273+
use `null` as protocol version.
274+
275+
```PHP
276+
$server->setProtocolVersion(null);
277+
```
278+
279+
#### Server authentication
280+
209281
Setting authentication on the `Server` enforces each further connected client
210282
to use protocol version 5.
211283
If a client tries to use any other protocol version, does not send along
@@ -238,41 +310,9 @@ $server->setAuthArray(array(
238310
If you do not want to use authentication anymore:
239311

240312
```PHP
241-
$client->unsetAuth();
242313
$server->unsetAuth();
243314
```
244315

245-
## Usage
246-
247-
### Using SSH as a SOCKS server
248-
249-
If you already have an SSH server set up, you can easily use it as a SOCKS
250-
tunnel end point. On your client, simply start your SSH client and use
251-
the `-D [port]` option to start a local SOCKS server (quoting the man page:
252-
a `local "dynamic" application-level port forwarding`) by issuing:
253-
254-
`$ ssh -D 9050 ssh-server`
255-
256-
```PHP
257-
$client = new Client($loop, '127.0.0.1', 9050);
258-
```
259-
260-
### Using the Tor (anonymity network) to tunnel SOCKS connections
261-
262-
The [Tor anonymity network](http://www.torproject.org) client software is designed
263-
to encrypt your traffic and route it over a network of several nodes to conceal its origin.
264-
It presents a SOCKS4 and SOCKS5 interface on TCP port 9050 by default
265-
which allows you to tunnel any traffic through the anonymity network.
266-
In most scenarios you probably don't want your client to resolve the target hostnames,
267-
because you would leak DNS information to anybody observing your local traffic.
268-
Also, Tor provides hidden services through an `.onion` pseudo top-level domain
269-
which have to be resolved by Tor.
270-
271-
```PHP
272-
$client = new Client($loop, '127.0.0.1', 9050);
273-
$client->setResolveLocal(false);
274-
```
275-
276316
## Install
277317

278318
The recommended way to install this library is [through composer](http://getcomposer.org). [New to composer?](http://getcomposer.org/doc/00-intro.md)

0 commit comments

Comments
 (0)