[or-cvs] move the how-to-use-tor-as-an-application section to the end,
arma at seul.org
arma at seul.org
Tue Aug 16 03:22:32 UTC 2005
Update of /home2/or/cvsroot/control/doc
In directory moria:/home/arma/work/onion/cvs/control/doc
Modified Files:
howto.txt
Log Message:
move the how-to-use-tor-as-an-application section to the end,
so it won't throw people off.
the better answer is to move it somewhere else entirely, since i
think only nick believes this file is where he'd look for this info.
Index: howto.txt
===================================================================
RCS file: /home2/or/cvsroot/control/doc/howto.txt,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- howto.txt 15 Aug 2005 08:39:31 -0000 1.6
+++ howto.txt 16 Aug 2005 03:22:30 -0000 1.7
@@ -18,105 +18,12 @@
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:
-
- - 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
- SOCKS4a)
- 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
- failure)
- 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, including
- extensions that let you do DNS lookups over SOCKS, 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.
-
- See http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#SOCKSAndDNS for
- more details.
-
-1.2. Notes on authentication by IP address
-
- 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 begin 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
- problem.
-
-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
+1. Writing a controller
- If you want your application to use Tor in a more fine-grained manner
- (i.e., not just to anonymize your application's connections) you need
- to write a "controller". A controller is a program that connects
- to the Tor client and sends it commands. With a controller, you can
- examine and change Tor's configuration on the fly, change how circuits
- are built, and perform other operations.
+ A controller is a program that connects to the Tor client and sends
+ it commands. With a controller, you can examine and change Tor's
+ configuration on the fly, change how circuits are built, and perform
+ other operations.
As of the most recent version (0.1.0.11), Tor does not have its controller
interface enabled by default. You need to configure it to listen on some
@@ -137,7 +44,7 @@
0.1.1.0. Earlier versions used an older and trickier control protocol which
is not covered here; see "control-spec-v0.txt" for details.
-2.1. Getting started
+1.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
@@ -180,7 +87,7 @@
(For more information on using the v1 protocol directly, see x.x)
-2.2. Configuration and information
+1.2. Configuration and information
Now that you've got a connection to Tor, what can you do with it?
@@ -230,7 +137,7 @@
For a list of configuration options recognized by Tor, see the main Tor
manual page.
-2.2.1. Using order-sensitive configuration variables
+1.2.1. Using order-sensitive configuration variables
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-
@@ -252,7 +159,7 @@
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
+1.3. Getting status information
Tor exposes other status information beyond those set in configuration
options. You can access this information with the "getInfo" method.
@@ -278,7 +185,7 @@
For a complete list of recognized keys, see "control-spec.txt".
-2.4. Signals
+1.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
@@ -306,7 +213,7 @@
(See control-spec.txt for an up-to-date list.)
-2.5. Listening for events
+1.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
@@ -339,7 +246,7 @@
Using the v1 protocol: (See x.x for information on parsing the results)
SETEVENTS DEBUG INFO NOTICE WARN ERR
-2.5.1. Kinds of events
+1.5.1. Kinds of events
The following event types are currently recognized:
@@ -399,7 +306,7 @@
(See control-spec.txt for an up-to-date list.)
-2.5.2. Threading issues
+1.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,
@@ -419,7 +326,7 @@
conn.launch_thread(daemon=0) # Not in daemon mode
-2.6. Overriding directory functionality
+1.6. Overriding directory functionality
You can tell Tor about new server descriptors. (Ordinarily, it learns
about these from the directory server.) In Java:
@@ -442,7 +349,7 @@
<the descriptor goes here>
.
-2.7. Mapping addresses
+1.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
@@ -487,7 +394,7 @@
control interface by requesting the status value "addr-mappings/control".
See 2.3 above.
-2.8. Managing streams and circuits.
+1.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
@@ -551,9 +458,9 @@
# Close the circuit (IFUNUSED means "only if it has no live streams")
conn.closeCircuit(circID, flags=["IFUNUSED"])
-3. General topics
+2. General topics
-3.1. Naming servers
+2.1. Naming servers
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
@@ -564,7 +471,7 @@
For example, moria1's digest is:
"$FFCB46DB1339DA84674C70D7CB586434C4370441."
-3.2. Authentication and security
+2.2. Authentication and security
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
@@ -603,7 +510,7 @@
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
+3. 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
@@ -632,6 +539,97 @@
See control-spec.txt for full documentation.
+4. 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:
+
+ - 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
+ SOCKS4a)
+ 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
+ failure)
+ 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, including
+ extensions that let you do DNS lookups over SOCKS, see
+ "socks-extensions.txt" in the Tor distribution.
+
+4.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.
+
+ See http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#SOCKSAndDNS for
+ more details.
+
+4.2. Notes on authentication by IP address
+
+ 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 begin 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
+ problem.
+
+4.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?
+
References:
[1] http://archive.socks.permeo.com/protocol/socks4.protocol
[2] http://archive.socks.permeo.com/protocol/socks4a.protocol
More information about the tor-commits
mailing list