Socket
Socket
Sign inDemoInstall

txsocksx

Package Overview
Dependencies
0
Maintainers
3
Alerts
File Explorer

Install Socket

Protect your apps from supply chain attacks

Install

txsocksx

Twisted client endpoints for SOCKS{4,4a,5}

    1.15.0.2

Maintainers
3

Readme

.. image:: https://img.shields.io/travis/habnabit/txsocksx/master.svg?style=flat-square
   :target: https://travis-ci.org/habnabit/txsocksx

.. image:: https://img.shields.io/coveralls/habnabit/txsocksx/master.svg?style=flat-square
   :target: https://coveralls.io/r/habnabit/txsocksx?branch=master


========
txsocksx
========

|txsocksx| is SOCKS4/4a and SOCKS5 client endpoints for `Twisted`_ 10.1 or
greater. The code is available on github: https://github.com/habnabit/txsocksx


Examples
========

These examples assume familiarity with how to use `Twisted endpoints`_. For
simplicity, most of the examples will use SOCKS5.


Authenticating
--------------

One specifies authentication methods to a |SOCKS5ClientEndpoint| via the
*methods* parameter. For example, to connect using the username ``spam`` and
password ``eggs``::

  exampleEndpoint = SOCKS5ClientEndpoint(
      'example.com', 6667, proxyEndpoint, methods={'login': ('spam', 'eggs')})

However, this will disable anonymous authentication. To use either login or
anonymous authentication, specify both methods::

  exampleEndpoint = SOCKS5ClientEndpoint(
      'example.com', 6667, proxyEndpoint, methods={'login': ('spam', 'eggs'),
                                                   'anonymous': ()})

The ``methods`` dict must always map from a string to a tuple.


SOCKS4
~~~~~~

SOCKS4 has no authentication, but does have a configurable "user ID" which
defaults to an empty string::

  exampleEndpoint = SOCKS4ClientEndpoint(
      'example.com', 6667, proxyEndpoint, user='spam')


Connecting to a thing over tor
------------------------------

To connect to ``example.com`` on port 6667 over tor, one creates a
|SOCKS5ClientEndpoint| wrapping the endpoint of the tor server::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  exampleEndpoint = SOCKS5ClientEndpoint('example.com', 6667, torServerEndpoint)

Establishing the connection from there proceeds like usual::

  deferred = exampleEndpoint.connect(someFactory)

|txsocksx| will not do any DNS resolution, so the hostname ``example.com``
will not leak; tor will receive the hostname directly and do the DNS lookup
itself.

Tor allows connections by SOCKS4 or SOCKS5, and does not expect a user ID to be
sent when using the SOCKS4 client.


Cancelling a connection
-----------------------

Sometimes one tires of waiting and wants to abort the connection attempt. For
example, to abort the whole connection attempt after ten seconds::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  exampleEndpoint = SOCKS5ClientEndpoint('example.com', 6667, torServerEndpoint)
  deferred = exampleEndpoint.connect(someFactory)
  reactor.callLater(10, deferred.cancel)

This is a trivial example; real code should cancel the `IDelayedCall`_ returned
by ``reactor.callLater`` when the deferred fires. The code would then look like
this::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  exampleEndpoint = SOCKS5ClientEndpoint('example.com', 6667, torServerEndpoint)
  deferred = exampleEndpoint.connect(someFactory)
  canceler = reactor.callLater(10, deferred.cancel)

  def cancelCanceler(result):
      if canceler.active():
          canceler.cancel()
      return result
  deferred.addBoth(cancelCanceler)


Making HTTP requests
--------------------

Twisted's builtin `Agent`_ HTTP client did not support being handed an
arbitrary endpoint before 15.0, so |txsocksx| provides an ``Agent`` for maximum
compatibility.

While |txsocksx| requires only Twisted 10.1, |txsocksx.http| requires Twisted
12.1 or greater. Its usage is almost identical to normal ``Agent`` usage::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  agent = SOCKS5Agent(reactor, proxyEndpoint=torServerEndpoint)
  deferred = agent.request('GET', 'http://example.com/')

Note that the ``proxyEndpoint`` parameter *must* be passed as a keyword
argument. There is a second, optional, keyword-only argument for passing
additional arguments to the |SOCKS5ClientEndpoint| as |SOCKS5Agent|
constructs it::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  agent = SOCKS5Agent(reactor, proxyEndpoint=torServerEndpoint,
                      endpointArgs=dict(methods={'login': ('spam', 'eggs')}))
  deferred = agent.request('GET', 'http://example.com/')

|SOCKS5Agent| transparently supports HTTPS via |TLSWrapClientEndpoint|.

For users with Twisted 15.0 or greater, |SOCKS5Agent| also implements
`IAgentEndpointFactory`_.


Upgrading to TLS
----------------

Sometimes one wants to switch to speaking TLS as soon as the proxy negotiation
is finished. For that, there is |txsocksx.tls|. After wrapping an endpoint with
|TLSWrapClientEndpoint|, the connection will be upgraded to using TLS
immediately after proxy negotiation finishes::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  exampleEndpoint = SOCKS5ClientEndpoint('example.com', 6667, torServerEndpoint)
  tlsEndpoint = TLSWrapClientEndpoint(exampleEndpoint)
  deferred = tlsEndpoint.connect(someFactory)


Proxying over a proxy
---------------------

Because of |txsocksx|'s composable design, it's trivial to connect from one SOCKS
proxy to another::

  torServerEndpoint = TCP4ClientEndpoint(reactor, '127.0.0.1', 9050)
  firstProxyEndpoint = SOCKS5ClientEndpoint(
      'first-proxy.example.com', 1080, torServerEndpoint)
  secondProxyEndpoint = SOCKS4ClientEndpoint(
      'second-proxy.example.com', 1080, firstProxyEndpoint)
  finalHop = SOCKS5ClientEndpoint(
      'example.com', 113, secondProxyEndpoint)
  deferred = finalHop.connect(someFactory)


.. _Twisted: http://twistedmatrix.com/
.. _Twisted endpoints: http://twistedmatrix.com/documents/current/core/howto/endpoints.html
.. _IDelayedCall: http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.IDelayedCall.html
.. _Agent: http://twistedmatrix.com/documents/current/web/howto/client.html
.. _IAgentEndpointFactory: http://twistedmatrix.com/documents/current/api/twisted.web.iweb.IAgentEndpointFactory.html

.. |SOCKS5ClientEndpoint| replace:: ``SOCKS5ClientEndpoint``
.. |SOCKS5Agent| replace:: ``SOCKS5Agent``
.. |TLSWrapClientEndpoint| replace:: ``TLSWrapClientEndpoint``
.. |txsocksx| replace:: ``txsocksx``
.. |txsocksx.http| replace:: ``txsocksx.http``
.. |txsocksx.tls| replace:: ``txsocksx.tls``

FAQs


Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc