txtorcon Documentation Release 1.0.0 meejah January 25, 2017 Contents 1 Documentation 3 1.1 Introduction...............................................3 1.1.1 Features Overview.......................................3 1.1.2 Shell-cast Overview.......................................4 1.1.3 Known Users..........................................4 1.2 Installing txtorcon............................................4 1.2.1 Latest Release..........................................4 1.2.2 Compatibility..........................................5 1.2.3 Tor Configuration........................................5 1.2.4 Source Code...........................................5 1.2.5 Development Environment...................................6 1.2.6 Integration Tests........................................6 1.2.7 Dependencies / Requirements.................................6 1.3 Programming Guide...........................................7 1.3.1 API Stability..........................................7 1.3.2 A Tor Instance.........................................8 1.3.3 A Note On Style........................................8 1.3.4 Tracking and Changing Tor’s Configuration..........................8 1.3.5 Monitor and Change Tor’s State................................9 1.3.6 Making Connections Over Tor................................. 10 1.3.7 Onion (Hidden) Services.................................... 11 1.3.8 Custom Circuits......................................... 14 1.3.9 Attaching Streams to Circuits.................................. 15 1.4 Examples................................................. 15 1.4.1 Web: clients........................................... 15 1.4.2 Web: servers (services)..................................... 17 1.4.3 Starting Tor........................................... 21 1.4.4 Circuits and Streams...................................... 24 1.4.5 Configuration.......................................... 28 1.4.6 Events.............................................. 29 1.4.7 Miscellaneous.......................................... 29 1.5 Contributions............................................... 31 1.5.1 Contact Information....................................... 31 1.5.2 Public Key........................................... 31 1.5.3 Pull Requests.......................................... 32 1.5.4 Making a Release........................................ 32 2 Official Releases: 35 i 2.1 Releases................................................. 35 2.1.1 upcoming: 1.0.0......................................... 35 2.1.2 unreleased............................................ 36 2.1.3 v0.18.0............................................. 36 2.1.4 v0.17.0............................................. 36 2.1.5 v0.16.1............................................. 36 2.1.6 v0.16.0............................................. 36 2.1.7 v0.15.1............................................. 36 2.1.8 v0.15.0............................................. 37 2.1.9 v0.14.1............................................. 37 2.1.10 v0.14.0............................................. 37 2.1.11 v0.13.0............................................. 38 2.1.12 v0.12.0............................................. 38 2.1.13 v0.11.0............................................. 38 2.1.14 v0.10.1............................................. 39 2.1.15 v0.10.0............................................. 39 2.1.16 v0.9.2.............................................. 39 2.1.17 v0.9.1.............................................. 40 2.1.18 v0.8.2.............................................. 40 2.1.19 v0.8.1.............................................. 40 2.1.20 v0.8.0.............................................. 41 2.1.21 v0.7............................................... 41 2.1.22 v0.6............................................... 41 2.1.23 v0.5............................................... 42 2.1.24 v0.4............................................... 42 2.1.25 v0.3............................................... 42 2.1.26 v0.2............................................... 42 2.1.27 v0.1............................................... 43 3 API Documentation 45 3.1 API Documentation........................................... 45 3.1.1 High Level API......................................... 45 3.1.2 Tracking and Changing Live Tor State............................. 47 3.1.3 Reading and Writing Live Tor Configuration.......................... 54 3.1.4 Endpoints and Related Classes................................. 57 3.1.5 Low-Level Protocol Classes.................................. 61 3.1.6 txtorcon.interface Module.............................. 66 3.1.7 txtorcon.util Module.................................. 69 4 Indices and tables 71 ii txtorcon Documentation, Release 1.0.0 • docs: https://txtorcon.readthedocs.org or http://timaq4ygg2iegci7.onion • 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. Supported and tested platforms: Python 2.7+, Python 3.5+, PyPy 5.0.0+ using Twisted 15.5.0+, 16.3.0+ or later. Contents 1 txtorcon Documentation, Release 1.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. With txtorcon you can launch tor; connect to already-running tor instances; use tor as a client (via SOCKS5); set up 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 would be of interest to anyone wishing to write event-based software in Python that uses the Tor network as a client or a service (or just wants to 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 python-txtorcon $ twistd web --port "onion:80" --path ~/public_html txtorcon strives to provide sane and safe defaults. 1.1.1 Features Overview Currently, txtorcon is capable of: • making arbitrary client connections to other services over Tor; • 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; 3 txtorcon Documentation, Release 1.0.0 • 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 Known Users • magic-wormhole “get things from one computer to another, safely” • Tahoe-LAFS a Free and Open encrypted distributed storage system • txtorcon received a brief mention at 29C3 starting at 12:20 (or via youtube). • carml command-line utilities for Tor • foolscap RPC system inspired by Twisted’s built-in “Perspective Broker” package. • APAF anonymous Python application framework • OONI the Open Observatory of Network Interference • exitaddr scan Tor exit addresses • txtorhttpproxy simple HTTP proxy in Twisted • bulb Web-based Tor status monitor • onionvpn “ipv6 to onion service virtual public network adapter” • torperf2 new Tor node network performance measurement service • torweb web-based Tor controller/monitor • potator “A Tor-based Decentralized Virtual Private Network Application” 1.2 Installing txtorcon 1.2.1 Latest Release txtorcon is on PyPI and in Debian since jessie (thanks to Lunar and now irl!). So, one of these should work: • install latest release: pip install txtorcon • Debian or Ubuntu: apt-get install python-txtorcon • Watch an asciinema demo for an overview. 4 Chapter 1. Documentation txtorcon Documentation, Release 1.0.0 Rendered documentation for the latest release is at txtorcon.readthedocs.org. What exists for release-notes are in “Releases”. If you’re still using wheezy, python-txtorcon is also in wheezy-backports. To install, do this as root: # echo "deb http://ftp.ca.debian.org/debian/ wheezy-backports main" >> /etc/apt/sources.list # apt-get update # apt-get install python-txtorcon It also appears txtorcon is in Gentoo but I don’t use Gentoo (if anyone has a shell-snippet that installs it, send a pull-request). I am told this package also needs a maintainer; see XXX. Installing the wheel