[or-cvs] Write most of the rest of the howto.txt
Nick Mathewson
nickm at seul.org
Mon Jul 11 20:18:35 UTC 2005
Update of /home/or/cvsroot/control/doc
In directory moria:/tmp/cvs-serv10291/doc
Modified Files:
howto.txt
Log Message:
Write most of the rest of the howto.txt
Index: howto.txt
===================================================================
RCS file: /home/or/cvsroot/control/doc/howto.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- howto.txt 11 Jul 2005 19:46:23 -0000 1.2
+++ howto.txt 11 Jul 2005 20:18:33 -0000 1.3
@@ -63,7 +63,8 @@
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
+ information on Tor's extensions to the SOCKS protocol, including
+ extensions that let you do DNS lookups over SOCKS, see
"socks-extensions.txt" in the Tor distribution.
1.1. Notes on DNS
@@ -419,6 +420,12 @@
# Tell Tor about it
conn.post_descriptor(desc)
+ With the v1 protocol:
+
+ +POSTDESCRIPTOR
+ <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.]
@@ -426,28 +433,152 @@
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
+ B. For example, suppose you are writing an anonymized DNS resolver.
+ While you can already ask Tor to resolve addresses like "tor.eff.org"
+ using the SOCKS interface, some special addresses (like
+ "6sxoyfb3h2nvok2d.onion" or "tor.eff.org.tor26.exit") don't correspond to
+ normal IP addresses. To get around this, your DNS resolver could ask Tor
+ to map unallocated IP addresses to these special hostnames, and then pass
+ those IP addresses back to the requesting application. When the
+ application tries to connect to the IP, Tor will redirect the request to
+ the correct hostname.
+ In Java:
+
+ String onionAddr = "6sxoyfb3h2nvok2d.onion";
+ // Make all requests for 127.0.0.100 be rewritten to the chosen addr.
+ conn.mapAddress("127.0.0.100", onionAddr);
+ // Ask Tor to choose an unallocated IP address to be rewritten to the
+ // chosen address.
+ String newAddress = conn.mapAddress("0.0.0.0", onionAddr);
+ // To remove the mapping for an address, map it to itself
+ conn.mapAddress("127.0.0.100", "127.0.0.100");
+
+ In Python:
+
+ onionAddr = "6sxoyfb3h2nvok2d.onion"
+ # Make all requests for 127.0.0.100 be rewritten to the chosen addr.
+ conn.map_address("127.0.0.100", onionAddr)
+ # Ask Tor to choose an unallocated IP address to be rewritten to the
+ # chosen address.
+ newAddress = conn.map_address("0.0.0.0", onionAddr)
+ # To remove the mapping for an address, map it to itself
+ conn.map_address("127.0.0.100", "127.0.0.100")
+
+ From the v1 control interface:
+
+ MAPADDRESS 127.0.0.1=6sxoyfb3h2nvok2d.onion
+ MAPADDRESS 0.0.0.0=6sxoyfb3h2nvok2d.onion
+
+ Note that you can receive a list of the address mappings set from the
+ 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,
+ attaching streams to circuits, and so on. (Note that it is possible to
+ make Tor pretty nonfunctional by use of these features; act with care.)
+ To manipulate a circuit or stream, you will need its ID; you can learn
+ about these IDs in one of three ways:
-2.7. Man
+ 1. Call a function that creates a new circuit/stream: it will return
+ the ID.
+ 2. Listen for an event that tells you that a circuit or stream's
+ status has changed. (See 2.5 above)
-Mapaddress
+ 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]
-extendcircuit, attachstream, closestream, redirectstream,
- closecircuit
+ 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
+ exit from the last node in the server's path), *redirect* a stream
+ (changing its target address), or *close* a server or stream.
-x.x. Authentication and security
+ Note that it is only safe to redirect or attach a stream that is not open:
+ that is, one that has not already sent a BEGIN or RESOLVE cell, or one
+ which has been detached.
-x.x. Getting started with the v1 control protocol
+ See the Tor documentation, especially XXXX or XXXX, for more information
+ about what streams and circuits are and how they work.
+
+ In Java:
+
+ // Launch a new circuit through the routers moria1 and moria2
+ String circID = conn.extendCircuit("0", "moria1,moria2");
+ // Extend the circuit through tor26
+ conn.extendCircuit(circID, "tor26");
+ String streamID = ....; // Learn about a stream somehow.
+ // Change its target address
+ conn.redirectStream(streamID, "tor.eff.org");
+ // Attach it to our circuit
+ conn.attachStream(streamID, circID);
+ // Close the stream (The byte is the 'reason' for closing it; see
+ // tor-spec.txt)
+ conn.closeStream(streamID, 0);
+ // Close the circuit ("true" means "only if it has no live streams")
+ conn.closeCircuit(circID, true);
+
+ In Python:
+
+ # Launch a new circuit through the routers moria1 and moria2
+ circID = conn.extend_circuit("0", ["moria1", "moria2"])
+ # Extend the circuit through tor26
+ conn.extend_circuit(circID, ["tor26"])
+ streamID = .... # Learn about a stream somehow.
+ # Change its target address
+ conn.redirect_stream(streamID, "tor.eff.org")
+ # Attach it to our circuit
+ conn.attach_stream(streamID, circID)
+ # Close the stream
+ conn.close_stream(streamID)
+ # Close the circuit (IFUNUSED means "only if it has no live streams")
+ conn.closeCircuit(circID, flags=["IFUNUSED"])
+3. General topics
+
+3.1. Naming servers
+
+ XXXX
+3.2. Authentication and security
+
+ XXXX
+
+4. Getting started with the v1 control protocol
+
+ The "v1" Tor control protocol is line-based: you send Tor lines, each
+ ending with a CR LF pair, and Tor replies with a set of lines, each ending
+ with a CR LF pair.
+
+ When multi-line data needs to be encoded, it is terminated by a single
+ line containing only a period. Lines in that data that start with a period
+ have an additional single period added to the front. When one of the
+ commands you send is followed by multi-line data, its name starts with a
+ plus (such as +POSTDESCRIPTOR).
+
+ Your controller will need to parse Tor's replies. Each of these replies
+ is also line-based. Each reply line starts with a three-character status
+ code (such as "250" for success), and a single "continuation" character
+ ("+", "-", or " "). The rest of the line is the reply message.
+
+ If the continuation character is " ", this line is the last in the reply.
+ If the continuation character is "+", the reply line is followed by
+ multi-line data, and more lines. Otherwise, if the continuation character
+ is "-", the reply line is followed by more lines.
+
+ Not every reply line you receive from the controller is in response to an
+ immediately preceding control message. Status codes that start with the
+ character "6" are _events_ in response to an earlier SETEVENTS command,
+ and are sent asynchronously.
+
+ See control-spec.txt for full documentation.
References:
[1] http://archive.socks.permeo.com/protocol/socks4.protocol
More information about the tor-commits
mailing list