[or-cvs] fix most torctl issues; move rest into TODO

Nick Mathewson nickm at seul.org
Thu Jul 14 20:26:13 UTC 2005

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

Modified Files:
Log Message:
fix most torctl issues; move rest into TODO

Index: howto.txt
RCS file: /home/or/cvsroot/control/doc/howto.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- howto.txt	13 Jul 2005 05:15:36 -0000	1.4
+++ howto.txt	14 Jul 2005 20:26:11 -0000	1.5
@@ -191,9 +191,9 @@
    In Java:
        // Get one configuration variable.
-       String contact = conn.getConf("contact");
+       List options = conn.getConf("contact");
        // Get a set of configuration variables.
-       Map values = conn.getConf(Arrays.asList(new String[]{
+       List options = conn.getConf(Arrays.asList(new String[]{
               "contact", "orport", "socksport"}));
        // Change a single configuration variable
        conn.setConf("BandwidthRate", "1 MB");
@@ -205,11 +205,9 @@
        // 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
+       options = conn.get_option("contact")
        # Get a set of configuration variables.
        options = conn.get_option(["contact", "orport", "socksport"])
        // Change a single configuration variable
@@ -234,7 +232,25 @@
 2.2.1. Using order-sensitive configuration variables
-   XXXX
+   In the above example, you'll note that configuration options are returned
+   as a list of key-value pairs, and not in the more intuitive map-from-keys-
+   to-values form that you might expect.  This is because some of Tor's
+   configuration options can appear more than once, and the ordering of these
+   options often matters.  The 'Log' option is an example: if more than one
+   log is configured, the option will appear more than once.  Sometimes
+   options are interrelated: the HiddenServicePort option applies to the
+   immediately previous HiddenServiceDir.
+   (To retrieve all the hidden service settings, in order, fetch the value of
+   the virtual "HiddenServiceOptions" variable.)
+   When you are setting these options, you must set them all at once.  For
+   example, suppose that there are three logs configured:
+      Log debug-debug file /tmp/debug_log
+      Log notice-err file /tmp/tor_log
+      Log err file /tmp/errors
+   If you want to change the third log file option, you need to re-send the other
+   two settings, so that Tor knows not to delete them.
 2.3. Getting status information
@@ -426,9 +442,6 @@
        <the descriptor goes here>
-   [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
@@ -474,9 +487,6 @@
    control interface by requesting the status value "addr-mappings/control".
    See 2.3 above.
-   [XXXX It would be nice to request address lookups from the controller
-   without using SOCKS.]
 2.8. Managing streams and circuits.
    Tor allows controllers to exercise fine control over building circuits,
@@ -494,7 +504,7 @@
       3. Get a list of all circuits and streams by getting the appropriate
          status information values; see control-spec.txt for more
-         [XXXX There should be functions to get and parse these values]
    Once you have these IDs, you can *extend* a circuit (by adding a new
    Tor server to its path), *attach* a stream to a circuit (causing it to
@@ -545,11 +555,53 @@
 3.1. Naming servers
-   XXXX
+   Where the name of a server is called for, it is safest to refer to a
+   server by its identity digest.  This is the same as the server's
+   fingerprint, with the spaces removed, preceded by a $.  This prevents
+   your program from getting confused by multiple servers with the same
+   nickname.  (Yes, this is possible.)
+   For example, moria1's digest is:
+   "$FFCB46DB1339DA84674C70D7CB586434C4370441."
 3.2. Authentication and security
-   XXXX
+   By default, Tor will open control ports on the localhost address,
+  This means that only connections from programs on the same
+   computer will be allowed.  This isn't very secure, however: it allows any
+   program run by any user to give commands to your Tor process.  To prevent
+   this, Tor allows you to set a password for authentication.  The best time
+   to do this is before Tor is started, so that there won't be a window of
+   vulnerability.
+   There are two ways to set up authentication: by asking Tor to generate a
+   cookie file, or by passing Tor a hashed password.
+   If you're on an operating system with good filesystem security (so that
+   other users can't read Tor's files), and your controller is running as a
+   user that can read Tor's files, pass Tor the "--CookieAuthentication 1"
+   option when you start it.  Tor will create a file in its data directory
+   called "control_auth_cookie".  All your controller needs to do is to pass
+   the contents of this file to authenticate() when it connects to Tor.
+   If you'd rather not trust the filesystem, or if Tor is set to run as a
+   different user, you can use password security.  You don't need to have
+   users pick these passwords; you should have the controller generate them
+   randomly when it starts Tor.  Tor doesn't take the password directly; that
+   would risk exposure.  Instead, it wants a secure hash of the password in
+   its HashedControlPassword option.  You can get one of these hashes by
+   running "tor --hash-password", or by calling the provided functions in the
+   controller libraries.
+   In Java:
+      // Create a new random password and its hash.
+      PasswordDigest d = PasswordDigest.generateDigest();
+      byte[] s = d.getSecret(); // pass this to autenticate
+      String h = d.getHashedPassword() // pass this to the Tor on startup.
+   In recent versions of Python (with os.urandom):
+      secret = os.urandom(32) # pass this to authenticate
+      hash = TorCtl.s2k_gen(secret) # pass this to Tor on startup.
 4. Getting started with the v1 control protocol

More information about the tor-commits mailing list