[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[or-cvs] move the how-to-use-tor-as-an-application section to the end,



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