| 1 |
Usage |
| 2 |
----- |
| 3 |
|
| 4 |
.. currentmodule:: socksio |
| 5 |
|
| 6 |
TL;DR check the `examples directory |
| 7 |
<https://github.com/sethmlarson/socksio/tree/master/examples/>`_. |
| 8 |
|
| 9 |
Being sans-I/O means that in order to test ``socksio`` you need an I/O |
| 10 |
library. And the most basic I/O is, of course, the standard library’s |
| 11 |
``socket`` module. |
| 12 |
|
| 13 |
You’ll need to know ahead of time the type of SOCKS proxy you want to |
| 14 |
connect to. Assuming we have a SOCKS4 proxy running in our machine on |
| 15 |
port 8080, we will first create a connection to it: |
| 16 |
|
| 17 |
.. code:: python |
| 18 |
|
| 19 |
import socket |
| 20 |
|
| 21 |
sock = socket.create_connection(("localhost", 8080)) |
| 22 |
|
| 23 |
``socksio`` exposes modules for SOCKS4, SOCKS4A and SOCKS5, each of them |
| 24 |
includes a ``Connection`` class: |
| 25 |
|
| 26 |
.. code:: python |
| 27 |
|
| 28 |
from socksio import socks4 |
| 29 |
|
| 30 |
# The SOCKS4 protocol requires a `user_id` to be supplied. |
| 31 |
conn = socks4.SOCKS4Connection(user_id=b"socksio") |
| 32 |
|
| 33 |
Since ``socksio`` is a sans-I/O library, we will use the socket to send |
| 34 |
and receive data to our SOCKS4 proxy. The raw data, however, will be |
| 35 |
created and parsed by our :class:`SOCKS4Connection <socks4.SOCKS4Connection>`. |
| 36 |
|
| 37 |
We need to tell our connection we want to make a request to the proxy. |
| 38 |
We do that by first creating a request object. |
| 39 |
|
| 40 |
In SOCKS4 we only need to send a command along with an IP address and |
| 41 |
port. ``socksio`` exposes the different types of commands as enumerables |
| 42 |
and a convenience :meth:`~socks4.SOCKS4Request.from_address` |
| 43 |
class method in the request classes to create a valid request object: |
| 44 |
|
| 45 |
.. code:: python |
| 46 |
|
| 47 |
# SOCKS4 does not allow domain names, below is an IP for google.com |
| 48 |
request = socks4.SOCKS4Request.from_address( |
| 49 |
socks4.SOCKS4Command.CONNECT, ("216.58.204.78", 80)) |
| 50 |
|
| 51 |
``from_address`` methods are available on all request classes in |
| 52 |
``socksio``, they accept addresses as tuples of ``(address, port)`` as |
| 53 |
well as string ``address:port``. |
| 54 |
|
| 55 |
Now we ask the connection to send our request: |
| 56 |
|
| 57 |
.. code:: python |
| 58 |
|
| 59 |
conn.send(request) |
| 60 |
|
| 61 |
The :class:`SOCKS4Connection <socks4.SOCKS4Connection>` will then compose the |
| 62 |
necessary ``bytes`` in the proper format for us to send to our proxy: |
| 63 |
|
| 64 |
.. code:: python |
| 65 |
|
| 66 |
data = conn.data_to_send() |
| 67 |
sock.sendall(data) |
| 68 |
|
| 69 |
If all goes well the proxy will have sent reply, we just need to read |
| 70 |
from the socket and pass the data to the |
| 71 |
:class:`SOCKS4Connection <socks4.SOCKS4Connection>`: |
| 72 |
|
| 73 |
.. code:: python |
| 74 |
|
| 75 |
data = sock.recv(1024) |
| 76 |
event = conn.receive_data(data) |
| 77 |
|
| 78 |
The connection will parse the data and return an event from it, in this |
| 79 |
case, a :class:`SOCKS4Reply <socks4.SOCKS4Reply>` that includes attributes for |
| 80 |
the fields in the SOCKS reply: |
| 81 |
|
| 82 |
.. code:: python |
| 83 |
|
| 84 |
if event.reply_code != socks4.SOCKS4ReplyCode.REQUEST_GRANTED: |
| 85 |
raise Exception( |
| 86 |
"Server could not connect to remote host: {}".format(event.reply_code) |
| 87 |
) |
| 88 |
|
| 89 |
If all went well the connection has been established correctly and we |
| 90 |
can start sending our request directly to the proxy: |
| 91 |
|
| 92 |
.. code:: python |
| 93 |
|
| 94 |
sock.sendall(b"GET / HTTP/1.1\r\nhost: google.com\r\n\r\n") |
| 95 |
data = receive_data(sock) |
| 96 |
print(data) |
| 97 |
# b'HTTP/1.1 301 Moved Permanently\r\nLocation: http://www.google.com/...` |
| 98 |
|
| 99 |
The same methodology is used for all protocols, check out the |
| 100 |
`examples directory <https://github.com/sethmlarson/socksio/tree/master/examples/>`_ |
| 101 |
for more information. |