[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:
howto.txt
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.
conn.saveConf();
- 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
information.
- [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,
+ 127.0.0.1. 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