txtorcon Documentation Release 20.0.0 meejah Jun 09, 2020 Contents 1 Documentation 3 1.1 Introduction...............................................3 1.1.1 Features Overview.......................................3 1.1.2 Shell-cast Overview.......................................4 1.1.3 Example Code.........................................4 1.1.4 Known Users..........................................5 1.2 Installing txtorcon............................................6 1.2.1 Latest Release..........................................6 1.2.2 Compatibility..........................................6 1.2.3 Tor Configuration........................................7 1.2.4 Source Code...........................................7 1.2.5 Development Environment...................................7 1.2.6 Integration Tests........................................8 1.2.7 Dependencies / Requirements.................................8 1.3 Programming Guide...........................................8 1.3.1 API Stability..........................................9 1.3.2 High Level Overview......................................9 1.3.3 A Tor Instance......................................... 10 1.3.4 A Note On Style........................................ 11 1.3.5 Tracking and Changing Tor’s Configuration.......................... 11 1.3.6 Monitor and Change Tor’s State................................ 12 1.3.7 Making Connections Over Tor................................. 13 1.3.8 Onion (Hidden) Services.................................... 14 1.3.9 Custom Circuits......................................... 17 1.3.10 Building Your Own Circuits.................................. 18 1.4 Examples................................................. 19 1.4.1 Web: clients........................................... 19 1.4.2 Starting Tor........................................... 23 1.4.3 Circuits and Streams...................................... 26 1.4.4 Events.............................................. 29 1.4.5 Miscellaneous.......................................... 30 1.5 Using Asyncio Libraries with txtorcon................................. 32 1.5.1 web_onion_service_aiohttp.py ........................... 32 1.6 Contributions............................................... 34 1.6.1 Contact Information....................................... 34 1.6.2 Public Key........................................... 35 i 1.6.3 Pull Requests.......................................... 35 1.6.4 Making a Release........................................ 35 2 Official Releases: 39 2.1 Releases................................................. 39 2.1.1 v20.0.0............................................. 39 2.1.2 v19.1.0............................................. 40 2.1.3 v19.0.0............................................. 40 2.1.4 v18.3.0............................................. 40 2.1.5 v18.2.0............................................. 40 2.1.6 v18.1.0............................................. 40 2.1.7 v18.0.2............................................. 41 2.1.8 v18.0.1............................................. 41 2.1.9 v18.0.0............................................. 41 2.1.10 v0.20.0............................................. 42 2.1.11 v0.19.3............................................. 42 2.1.12 v0.19.2............................................. 43 2.1.13 v0.19.1............................................. 43 2.1.14 v0.19.0............................................. 43 2.1.15 v0.18.0............................................. 44 2.1.16 v0.17.0............................................. 44 2.1.17 v0.16.1............................................. 44 2.1.18 v0.16.0............................................. 44 2.1.19 v0.15.1............................................. 44 2.1.20 v0.15.0............................................. 44 2.1.21 v0.14.2............................................. 45 2.1.22 v0.14.1............................................. 45 2.1.23 v0.14.0............................................. 45 2.1.24 v0.13.0............................................. 46 2.1.25 v0.12.0............................................. 46 2.1.26 v0.11.0............................................. 46 2.1.27 v0.10.1............................................. 47 2.1.28 v0.10.0............................................. 47 2.1.29 v0.9.2.............................................. 47 2.1.30 v0.9.1.............................................. 48 2.1.31 v0.8.2.............................................. 48 2.1.32 v0.8.1.............................................. 48 2.1.33 v0.8.0.............................................. 49 2.1.34 v0.7............................................... 49 2.1.35 v0.6............................................... 49 2.1.36 v0.5............................................... 50 2.1.37 v0.4............................................... 50 2.1.38 v0.3............................................... 50 2.1.39 v0.2............................................... 50 2.1.40 v0.1............................................... 51 3 API Documentation 53 3.1 API Documentation........................................... 53 3.1.1 High Level API......................................... 53 3.1.2 Tracking and Changing Live Tor State............................. 60 3.1.3 Reading and Writing Live Tor Configuration.......................... 68 3.1.4 Endpoints and Related Classes................................. 70 3.1.5 Onion APIs........................................... 75 3.1.6 Low-Level Protocol Classes.................................. 81 ii 3.1.7 txtorcon.socks Module.................................. 87 3.1.8 txtorcon.interface Module.............................. 89 3.1.9 txtorcon.util Module.................................. 93 4 Indices and tables 95 Index 97 iii iv txtorcon Documentation, Release 20.0.0 • docs: – v3 onion: http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/ – v2 onion: http://timaq4ygg2iegci7.onion – clearnet: https://txtorcon.readthedocs.org • code: https://github.com/meejah/txtorcon • torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git • If this is your first time exploring txtorcon, please look at the Introduction first. These docs are for version 20.0.0. Supported and tested platforms: Python 3.5+, PyPy 5.0.0+, Python 2.7+ (deprecated) using Twisted 15.5.0+, 16.3.0+, or 17.1.0+ (see travis). Asycnio inter-operation is now possible, see Using Asyncio Libraries with txtorcon Contents 1 txtorcon Documentation, Release 20.0.0 2 Contents CHAPTER 1 Documentation 1.1 Introduction txtorcon is an implementation of the control-spec for Tor using the Twisted networking library for Python( supports Py2, PyPy and Py3). txtorcon gives you a live view of all Tor state and the ability to control most aspects of Tor’s operation. With txtorcon you can launch tor; connect to already-running tor instances; use tor as a client (via SOCKS5); set up (onion) services over tor; change all aspects of configuration; track live state (active circuits and streams, etc); do DNS via Tor; and query other information from the tor daemon. txtorcon is the library to use if you want to write event-based software in Python that uses the Tor network as a client or a service (or integrate Tor support for existing Twisted-using applications, or display information about a locally running tor). Twisted already provides many robust protocol implementations, deployment, logging and integration with GTK, Qt and other graphics frameworks – so txtorcon can be used for command-line or GUI applications or integrate with long-lived daemons easily. In fact, due to support for endpoints (adding the tor: and onion: plugins), many Twisted applications can now integrate with Tor with no code changes. For example, you can use the existing Twisted webserver via twistd to serve your ~/public_html directory over an onion service: $ sudo apt-get install --install-suggests python-txtorcon $ twistd web --port "onion:80" --path ~/public_html (You should ideally enable the Tor project repositories first). txtorcon strives to provide sane and safe defaults. txtorcon is a Tor project. The applications Tahoe-LAFS and Crossbar.io have successfully integrated Tor support using txtorcon. 1.1.1 Features Overview Currently, txtorcon is capable of: • making arbitrary client connections to other services over Tor; 3 txtorcon Documentation, Release 20.0.0 • configuring twisted.web.client.Agent instances to do Web requests over Tor; • doing both of the above over specific circuits; • listening as an Onion service; • maintaining up-to-date (live) state information about Tor: Circuits, Streams and Routers (relays); • maintaining current (live) configuration information; • maintaining representation of Tor’s address mappings (with expiry); • interrogating initial state of all three of the above; • listening for and altering stream -> circuit mappings; • building custom circuits; • Circuit and Stream state listeners; • listening for any Tor EVENT; • launching and/or controlling a Tor instance (including Tor Browser Bundle); • complete Twisted endpoint support (both “onion”/server side and client-side). This means you may be able to use existing Twisted software via Tor with no code changes. It also is the preferred way to connect (or listen) in Twisted. Comments (positive or negative) appreciated. Even better if they come with patches 1.1.2 Shell-cast Overview A text-only screencast-type overview of some of txtorcon’s features, from asciinema.org: 1.1.3