[or-cvs] Commit incomplete howto document with missing bits and inte...

Nick Mathewson nickm at seul.org
Mon Jul 11 19:10:30 UTC 2005

Update of /home/or/cvsroot/control/doc
In directory moria:/tmp/cvs-serv7756/doc

Added Files:
Log Message:
Commit incomplete howto document with missing bits and interface XXXXs

--- NEW FILE: howto.txt ---
$Id: howto.txt,v 1.1 2005/07/11 19:10:28 nickm Exp $

                Interfacing with Tor: Clients and Controllers
   Copyright 2005 Nick Mathewson -- see LICENSE for licensing information

0. About this document

   This document has instructions for writing programs to interface with
   Tor.  You should read it if you want to write a Tor controller, of if you
   want to make your programs work with Tor correctly.

0.1. Further reading

   You should probably have a good idea of what Tor does and how it works;
   see the main Tor documentation for more detail.

   If you want full specifications for the data formats and protocols Tor
   uses, see tor-spec.txt, control-spec.txt, and socks-extensions.txt, all of
   which are included with the Tor distribution.

1. Making a program use Tor

   Suppose you have a simple network application, and you want that
   application to send its traffic over Tor.  This is pretty simple to do:
   here's how.

     - Make sure your protocol is stream based.  If you're using TCP, you're
       fine; if you're using UDP or another non-TCP protocol, Tor can't cope
       right now.

     - Make sure that connections are unidirectional.  That is, make sure
       that your protocol can run with one host (the 'originating host' or
       'client') originating all the connections to the other (the
       'responding host' or 'server').  If the responding host has to open
       TCP connections back to the originating host, it won't be able to do
       so when the originating host is anonymous.

     - For anonymous clients: Get your program to support SOCKS4a or SOCKS5
       with hostnames.  Right now, when your clients open a connection, they
       probably do a two step process of:
         * Resolve the server's hostname to an IP address.
         * Connect to the server.
       Instead, make sure that they can:
         * Connect to a local SOCKS proxy.
         * Tell the SOCKS proxy about the server's hostname and port.
           In SOCKS4a, this is done by sending these bytes, in order:
             0x04                 (socks version)
             0x01                 (connect)
             PORT                 (two bytes, most signficant byte first)
             0x00 0x00 0x00 0x01  (fake IP address: tells proxy to use
             0x00                 (empty username field)
             HOSTNAME             (target hostname)
             0x00                 (marks the end of the hostname field)
         * Wait for the SOCKS proxy to connect to the server.
           In SOCKS4a, it will reply with these bytes in order:
             0x00                 (response version)
             STATUS               (0x5A means success; other values mean
             PORT                 (not set)
             ADDRESS              (not set)

     - For hidden services: Make sure that your program can be configured to
       accept connections from the local host only.

   For more information on SOCKS, see references [1], [2], and [3].  For more
   information on Tor's extensions to the SOCKS protocol, see
   "socks-extensions.txt" in the Tor distribution.

1.1. Notes on DNS

   Note that above, we encourage you to use SOCKS4a or SOCKS5 with hostnames
   instead of using SOCKS4 or SOCKS5 with IP addresses.  This is because your
   program needs to make Tor do its hostname lookups anonymously.  If your
   program resolves hostnames on its own (by calling gethostbyname or a
   similar API), then it will effectively broadcast the names of the hosts it
   is about to connect to.

1.2. Notes on authentication

   If your service uses IP addresses to prevent abuse, you should consider
   switching to a different model.  Once your software works with Tor,
   annoying people may being using Tor to conceal their IP addresses.  If the
   best abuse-prevention scheme you have is IP based, you'll be forced to
   choose between blocking all users who want privacy, and allowing abuse.
   If you've implemented a better authorization scheme, you won't have this

1.3. Cleaning your protocol

   You aren't done just because your connections are anonymous.  You need to
   consider whether the application itself is doing things to compromise your
   users' anonymity.  Here are some things to watch out for:

   Information Leaks
     - Does your application include any information about the user
       in the protocol?

     - Does your application include any information about the user's
       computer in the protocol?  This can include not only the computer's IP
       address or MAC address, but also the version of the software, the
       processor type, installed hardware, or any other information that can
       be used to tell users apart.

     - Do different instances of your application behave differently?  If
       there are configuration options that make it easy to tell users apart,
       are they really necessary?

2. Writing a controller

   If you want your application to use Tor in a more fine-grained manner (and
   not just to anonymize your application's connections) you need to write a
   "controller".  A controller is a program that connects to Tor and sends it
   commands.  With a controller, you can examine and change Tor's
   configuration on the fly, change how circuits are built, and other

   As of the most recent version (, Tor does not have its controller
   interface enabled by default.  You need to configure it to listen on some
   local port by using the "ControlPort" configuration directive, either in
   the torrc file, like this:

       ControlPort 9100

   Or on the command line, like this:

       tor -controlport 9100

   Then your controller can connect to Tor.  But see the notes on
   authentication below (x.x).

   This document covers the Python and Java interfaces to Tor, and the
   underlying "v1" control protocol introduced in Tor version Earlier versions used an older and tricker control protocol which
   is not covered here; see "control-spec-v0.txt" for details.

2.1. Getting started

   When you're writing a controller, you can either connect to Tor's control
   port and send it commands directly, or you can use one of the libraries
   we've written to automate this for you.  Right now, there are libraries in
   Java and Python.

   First, you need to load the library and open a new connection to the Tor
   process.  In Java:

     import net.freehaven.tor.control.TorControlConnection;
     import java.net.Socket;

     public class Demo {
       public static final void main(String[] args) {
         Socket s = new Socket("", 9100);
         TorControlConnection conn = TorControlConnection.getConnection(s);
         conn.authenticate(new byte[0]); // See section x.x
         // ...

   In Python:

      import socket
      import TorCtl

      s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
      s.connect(("", 9100))
      conn = TorCtl.get_connection(s)
      conn.authenticate("")  # See section x.x
      # ...

   The factory method that you use to create a connection will check whether
   the version of Tor you've connected to supports the newer ("v1")
   text-based control protocol or the older ("v0") binary control protocol.

   Using the v1 protocol, just connect to the control port and say:


   (For more information on using the v1 protocol directly, see x.x)

2.2. Configuration and information

   Now that you've got a connection to Tor, what can you do with it?

   One of the easiest operations is manipulating Tor's configuration
   parameters.  You can retrieve or change the value of any configuration
   variable by calling the appropriate method.

   In Java:

       // Get one configuration variable.
       String contact = conn.getConf("contact");
       // Get a set of configuration variables.
       Map values = conn.getConf(Arrays.asList(new String[]{
              "contact", "orport", "socksport"}));
       // Change a single configuration variable
       conn.setConf("BandwidthRate", "1 MB");
       // Change several configuration variables
       conn.setConf(Arrays.asList(new String[]{
              "HiddenServiceDir /home/tor/service1",
              "HiddenServicePort 80",
       // Flush the configuration to disk.

       XXXX getconf must handle multiple values correctly.

   In Python:
       # Get one configuration variable
       _, contact = conn.get_option("contact") #XXXX bad iface
       # Get a set of configuration variables.
       options = conn.get_option(["contact", "orport", "socksport"])
       // Change a single configuration variable
       conn.set_option("BandwidthRate", "1 MB")
       // Change several configuration variables
              ("HiddenServiceDir", "/home/tor/service1"),
              ("HiddenServicePort", "80")])
       // Flush the configuration to disk.

   Talking to Tor directly:

       GETCONF contact
       GETCONF contact orport socksport
       SETCONF bandwidthrate="1 MB"
       SETCONF HiddenServiceDir=/home/tor/service1 HiddenServicePort=80

   For a list of configuration options recognized by Tor, see the main Tor
   manual page.

2.2.1. Using order-sensitive configuration variables


2.3. Getting status information

   Tor exposes other status information beyond those set in configuration
   options.  You can access this information with the "getInfo" method.
   In Java:

       // get a single value.
       String version = conn.getInfo("version");
       // get several values
       Map vals = conn.getInfo(Arrays.asList(new String[]{
          "addr-mappings/config", "version"}));

   In Python:

       # Get a single value
       version = conn.get_info("version")
       # Get several values
       vals = conn.get_info(["addr-mappings/config", "version"])

   Using the v1 control interface directly:

       GETINFO version
       GETINFO addr-mappings/config version

   For a complete list of recognized keys, see "control-spec.txt".

2.4. Signals

   You can send named "signals" to the Tor process to have it perform
   certain recognized actions.  For example, the "RELOAD" signal makes Tor
   reload its configuration file.  (If you're used to Unix platforms, this
   has the same effect as sending a HUP to the Tor process.)

   In Java:


   In Python:


   Using the v1 control protocol:


   The recognized signal names are:
       "RELOAD" -- Reload configuration information
       "SHUTDOWN" -- Start a clean shutdown of the Tor process
       "DUMP" -- Write current statistics to the logs
       "DEBUG" -- Switch the logs to debugging verbosity
       "HALT" -- Stop the Tor process immediately.

   (See control-spec.txt for an up-to-date list.)

2.5. Listening for events

   Tor can tell you when certain events happen.  To learn about these events,
   first you need to give the control connection an "EventHandler" object to
   receive the events of interest.  Then, you tell the Tor process which
   events it should send you.

   These examples intercept and display log messages.  In Java:

       import net.freehaven.tor.control.NullEventHandler;
       import net.freehaven.tor.control.EventHandler;
       // We extend NullEventHandler so that we don't need to provide empty
       // implementations for all the events we don't care about.
       // ...
       EventHandler eh = new NullEventHandler() {
          public void message(String severity, String msg) {
            System.out.println("["+severity+"] "+msg);
       conn.setEvents(Arrays.asList(new String[]{
          "INFO", "NOTICE", "WARN", "ERR"}));

   In Python:

       class LogHandler:
           def msg(self, severity, message):
               print "[%s] %s"%(severity, message)
       con.set_events(["INFO", "NOTICE", "WARN", "ERR"])

    Using the v1 protocol:  (See x.x for information on parsing the results)

2.5.1. Kinds of events

    The following event types are currently recognized:

      CIRC: The status of a circuit has changed.
        These events include an ID string to identify the circuit, the new status
        of the circuit, and a list of the the routers in the circuit's
        current path.  The possible status values are:
          LAUNCHED -- the circuit has just been started; no work has been
            done yet to build it.
          EXTENDED -- the circuit has just been extended a single step.
          BUILT -- the circuit is finished.
          FAILED -- the circuit could not be built, and has been abandoned.
          CLOSED -- a successfully built circuit is now closed.

      STREAM: The status of an application stream has changed.
        These events include an string to identity the stream, the new status
        of the stream, the ID of the circuit (if any) that the stream is
        using, and the destination of the stream.  Recognized status values
          NEW -- an application has asked for an anonymous connection
          NEWRESOLVED -- an application has asked for an anonymous hostname
          SENTCONNECT -- the stream has been attached to a circuit, and we
              have sent a connection request down the circuit
          SENTRESOLVE -- the stream has been attached to a circuit, and we
              have sent a lookup request down the circuit
          SUCCEEDED -- the stream has been connected, or the lookup request
              has been answered
          FAILED -- the stream failed and cannot be retried
          CLOSED -- the stream closed normally
          DETACHED -- the stream was detached from its circuit, but could be
              reattached to another.

      ORCONN: The status of a connection to an OR has changed.
        These events include a string to identify the OR, and the status of
        the connection.  Current status values are:
          LAUNCHED -- we have started a connection to the OR
          CONNECTED -- we are successfully connected to the OR
          FAILED -- we could not successfully connect to the OR
          CLOSED -- an existing connection to the OR has been closed.

      BW: Amount of bandwidth used in the last second.
        These events include the number of bytes read, and the number of
        bytes written.

      INFO, NOTICE, WARN, ERR: Tor has logged a message.
        These events include the severity of the message, and its textual

      NEWDESC: A new server descriptor has been received.
        These events include a list of IDs for the servers whose descriptors
        have changed.

      ADDRMAP: Tor has added a new address mapping.
        These events include the address mapped, its new value, and the time
        when the mapping will expire.

   (See control-spec.txt for an up-to-date list.)

2.5.2. Threading issues

    In the Python and Java control libraries, responses from the Tor
    controller are handled in a separate thread of execution.  Ordinarily,
    this thread is a "daemon thread" that exits when your other threads are
    finished.  This could be a problem if you want your main thread to stop,
    and have the rest of your program's functionality handled by events from
    the Tor control interface.  To make the controller thread stay alive when
    your other threads are finished, call the controller's "launch thread"
    method after you create the controller, and before you call the
    authenticate method.

    In Java:

        conn.launchThread(false);  // Not in daemon mode

    In Python:

        conn.launch_thread(daemon=0)  # Not in daemon mode

2.6. Overriding directory functionality

   You can tell Tor about new server descriptors.  (Ordinarily, it learns
   about these from the directory server.)  In Java:

       // Get a descriptor from some source
       String desc = ...;
       // Tell Tor about it

   In Python:

       # Get a descriptor from some source
       desc = ...
       # Tell Tor about it

   [XXXX We need some way to adjust server status, and to tell tor not to
   download directories/network-status, and a way to force a download.]

2.7. Mapping addresses

   Sometimes it is desirable to map one address to another, so that a
   connection request to address "A" will result in a connection to address
   B.  For example, suppose you are writing an anonymized DNS resolver.  While
   you can ask Tor to resolve 

   [XXXX It would be nice to request address lookups from the controller
   without using SOCKS.]

2.7. Man


extendcircuit, attachstream, closestream, redirectstream,

x.x. Authentication and security

x.x. Getting started with the v1 control protocol

 [1] http://archive.socks.permeo.com/protocol/socks4.protocol
 [2] http://archive.socks.permeo.com/protocol/socks4a.protocol
 [3] SOCKS5: RFC1928

More information about the tor-commits mailing list