document socks extensions and dns lookup code

svn:r1976

3 files changed, 91 insertions, 9 deletions

diff --git a/doc/TODO b/doc/TODO
index 4c427d8ba..d899f6dbd 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -18,7 +18,7 @@ For scalability:
 
 For dtor:
 
-      pre1:
+NICK  pre1:
         - make all ORs serve the directory too.
           - "AuthoritativeDir 1" for dirservers
           - non-authorative servers with dirport publish opt dircacheport
@@ -48,7 +48,7 @@ For dtor:
           - also use this in intro points and rendezvous points, and
             hidserv descs.
           - figure out what to do about ip:port:differentkey
-        - ORs connect on demand. attach circuits to new connections, keep
+ARMA    - ORs connect on demand. attach circuits to new connections, keep
           create cells around somewhere, send destroy if fail.
         - nickname defaults to first piece of hostname
         - running-routers list refers to nickname if verified, else
@@ -86,11 +86,12 @@ NICK    . Windows port
           o works as client
             - deal with pollhup / reached_eof on all platforms
           . robust as a client
-          - works as server
+          . works as server
             - can be configured
           - robust as a server
+	  . Usable as NT service
           - docs for building in win
-          - installer?
+          - installer
 
         - Docs
           - FAQ
@@ -109,9 +110,9 @@ NICK    . packages
 
         - code
           - better warn/info messages
-          - let tor do resolves.
-          - extend socks4 to do resolves?
-          - make script to ask tor for resolves
+          o let tor do resolves.
+          o extend socks4 to do resolves?
+          o make script to ask tor for resolves
           - tsocks
             - gather patches, submit to maintainer
             - intercept gethostbyname and others, do resolve via tor
@@ -146,7 +147,7 @@ Other details and small and hard things:
         . Scrubbing proxies
                 - Find an smtp proxy?
                 . Get socks4a support into Mozilla
-        X Extend by nickname/hostname/something, not by IP.
+        - Extend by hostname, not by IP.
         - Need a relay teardown cell, separate from one-way ends.
         - Make it harder to circumvent bandwidth caps: look at number of bytes
           sent across sockets, not number sent inside TLS stream.
@@ -155,7 +156,6 @@ Other details and small and hard things:
           just as likely to be us as not.
 
 
-
 ***************************Future tasks:****************************
 
 Rendezvous and hidden services:
diff --git a/doc/socks-extensions.txt b/doc/socks-extensions.txt
new file mode 100644
index 000000000..fabf28f7a
--- /dev/null
+++ b/doc/socks-extensions.txt
@@ -0,0 +1,60 @@
+$Id$
+Tor's extensions to the SOCKS protocol
+
+1. Overview
+
+  The SOCKS protocol provides a generic interface for TCP proxies.  Client
+  software connects to a SOCKS server via TCP, and requests a TCP connection
+  to another address and port.  The SOCKS server establishes the connection,
+  and reports success or failure to the client.  After the connection has
+  been established, the client application uses the TCP stream as usual.
+
+  Tor supports SOCKS4 as defined in [1], SOCKS4A as defined in [2], and
+  SOCKS5 as defined in [3].
+
+  The stickiest issue for Tor in supporting clients, in practice, is forcing
+  DNS lookups to occur at the OR side: if clients do their own DNS lookup,
+  the DNS server can learn which addresses the client wants to reach.
+  SOCKS4 supports addressing by IPv4 address; SOCKS4A is a kludge on top of
+  SOCKS4 to allow addressing by hostname; SOCKS5 supports IPv4, IPv6, and
+  hostnames.
+
+1.1. Extent of support
+
+  Tor supports the SOCKS4, SOCKS4A, and SOCKS5 standards, except as follows:
+
+  BOTH:
+  - The BIND command is not supported.
+
+  SOCKS4,4A:
+  - SOCKS4 usernames are ignored.
+
+  SOCKS5:
+  - The (SOCKS5) "UDP ASSOCIATE" command is not supported.
+  - IPv6 is not supported in CONNECT commands.
+  - Only the "NO AUTHENTICATION" (SOCKS5) authentication method [00] is
+    supported.
+
+2. Name lookup
+
+  As an extension to SOCKS4A and SOCKS5, Tor implements a new command value,
+  "RESOLVE" [F0].  When Tor receives a "RESOLVE" SOCKS command, it initiates
+  a remote lookup of the hostname provided as the target address in the SOCKS
+  request.  The reply is either an error (if the address couldn't be
+  resolved) or a success response.  In the case of success, the address is
+  stored in the portion of the SOCKS response reserved for remote IP address.
+
+  (We support RESOLVE in SOCKS4A too, even though it is unnecessary.)
+
+3. HTTP-resistance
+
+  Tor checks the first byte of each socks request to see whether it looks
+  more like an HTTP request (that is, it starts with a "G", "H", or "P").  If
+  so, Tor returns a small webpage, telling the user that his/her browser is
+  misconfigured.  This is helpful for the many users who mistakenly try to
+  use Tor as an HTTP proxy instead of a SOCKS proxy.
+
+References:
+ [1] http://archive.socks.permeo.com/protocol/socks4.protocol
+ [2] http://archive.socks.permeo.com/protocol/socks4a.protocol
+ [3] SOCKS5: RFC1928
diff --git a/doc/tor-spec.txt b/doc/tor-spec.txt
index 3f909cd7b..d9940bc9c 100644
--- a/doc/tor-spec.txt
+++ b/doc/tor-spec.txt
@@ -360,6 +360,8 @@ TODO: (very soon)
          8 -- RELAY_TRUNCATE
          9 -- RELAY_TRUNCATED
         10 -- RELAY_DROP
+        11 -- RELAY_RESOLVE
+        12 -- RELAY_RESOLVED
 
    The 'Recognized' field in any unencrypted relay payload is always
    set to zero; the 'digest' field is computed as the first four bytes
@@ -465,6 +467,26 @@ TODO: (very soon)
    If an edge node encounters an error on any stream, it sends a
    'RELAY_END' cell (if possible) and closes the stream immediately.
 
+5.4. Remote hostname lookup
+
+   To find the address associated with a hostname, the OP sends a
+   RELAY_RESOLVE cell containing the hostname to be resolved.  The OR
+   replies with an RELAY_RESOLVED cell containing a status byte, and any
+   number of answers.  Each answer is of the form:
+       Type   (1 octet)
+       Length (1 octet)
+       Value  (variable-width)
+   "Length" is the length of the Value field.  "Type" is one of:
+      0x04 -- IPv4 address
+      0x06 -- IPv6 address
+      0xF0 -- Error, transient
+      0xF1 -- Error, nontransient
+
+    If any answer has a type of 'Error', then no other answer may be given.
+
+    The RELAY_RESOLVE cell must use a nonzero, distinct streamID; the
+    corresponding RELAY_RESOLVED cell must use the same streamID.  No stream
+    is actually created by the OR when resolving the name.
 
 6. Flow control