[or-cvs] Add proposal to control spec for a simple way to bind IP ad...

[Nick Mathewson]

Update of /home/or/cvsroot/tor/doc
In directory moria.mit.edu:/tmp/cvs-serv27688

Modified Files:
	control-spec.txt 
Log Message:
Add proposal to control spec for a simple way to bind IP addresses to hostnames. Example: "Please make all requests for 10.200.0.1 go to foobarbaz.onion".  This feature would be needed for any attempt to write a torified DNS proxy.  Needs more thought and more comments.

Index: control-spec.txt
===================================================================
RCS file: /home/or/cvsroot/tor/doc/control-spec.txt,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- control-spec.txt	17 Dec 2004 22:32:23 -0000	1.11
+++ control-spec.txt	6 Jan 2005 02:02:18 -0000	1.12
@@ -78,11 +78,16 @@
 
         0x0007 Unauthorized.
                [The client tried to send a command that requires
-                authorization, but it hasn't sent a valid AUTHENTICATE message.]
+                authorization, but it hasn't sent a valid AUTHENTICATE
+                message.]
 
         0x0008 Failed authentication attempt
                [The client sent a well-formed authorization message.]
 
+        0x0009 Resource exhausted
+               [The server didn't have enough of a given resource to
+                fulfill a given request.]
+
   The rest of the body should be a human-readable description of the error.
 
   In general, new error codes should only be added when they don't fall under
@@ -212,6 +217,75 @@
   The server responds with DONE if the signal is recognized (or simply
   closes the socket if it was asked to close immediately), else ERROR.
 
+3.11. MAPADDRESS (Type 0x000A)
+
+  [Proposal; not finalized]
+
+  Sent from the client to the server.  The body contains:
+     Original address type [1 octet]
+     Original address [Variable length]
+     Replacement address type [1 octet]
+     Replacement address [Variable length]
+
+  Addresses types can be:
+     [0x01] for an IPv4 address (4 octets)
+     [0x02] for an IPv6 address (16 octets)
+     [0x03] for a hostname (variable-length, NUL-terminated)
+
+  The client sends this message to the server in order to tell it that future
+  SOCKS requests for connections to the original address should be replaced
+  with connections to the specified replacement address.  If the addresses
+  are well-formed, and the server is able to fulfill the request, the server
+  replies with a single ADDRESSMAPPED message containing the source and
+  destination addresses.  If request is malformed, the server replies with
+  a syntax error message.  The server can't fulfill the request, it replies
+  with an internal ERROR message.
+
+  The client may decline to provide a body for the original address, and
+  instead send a special null address (0.0.0.0 for IPv4, ::0 for IPv6, or "."
+  for hostname).  This signifies that the server should choose the original
+  address itself, and return that address in the ADDRESSMAPPED message.  The
+  server should an element of address space that is unlikely to be in actual
+  use.  If there is already an address mapped to the destination address, the
+  server may reuse that mapping.
+
+  If the original address is already mapped to a different address, the old
+  mapping is removed.  If the original address and the destination address
+  are the same, the server removes any mapping in place for the original
+  address.
+
+  {Note: This feature is designed to be used to help Tor-ify applications
+  that need to use SOCKS4 or hostname-less SOCKS5.  There are three
+  approaches to doing this:
+     1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
+     2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
+        feature) to resolve the hostname remotely.  This doesn't work
+        with special addresses like x.onion or x.y.exit.
+     3. Use MAPADDRESS to map an IP address to the desired hostname, and then
+        arrange to fool the application into thinking that the hostname
+        has resolved to that IP.
+  This functionality is designed to help implement the 3rd approach.}
+
+  [XXXX When, if ever, can mappings expire?  Should they expire?]
+  [XXXX What addresses, if any, are safe to use?]
+
+3.12 ADDRESSMAPPED (Type 0x000B)
+
+  [Proposal; not finalized]
+
+  Same format as MAPADDRESS.
+
+  This message is sent from the server to the client in response to a
+  MAPADDRESS or GETALLMAPPINGS message.
+
+3.13 GETALLMAPPINGS (Type 0x000C)
+
+  [Proposal; not finalized]
+
+  Sent from the client to the server.  The server replies by sending an
+  ADDRESSMAPPED message for each current address mapping set by MAPADDRESS or
+  otherwise, followed by a DONE message.
+
 4. Implementation notes
 
 4.1. There are four ways we could authenticate, for now: