clean up the torbl-design draft

svn:r9835

1 files changed, 27 insertions, 21 deletions

diff --git a/doc/contrib/torbl-design.txt b/doc/contrib/torbl-design.txt
index ee6e6aac52..dac1234162 100644
--- a/doc/contrib/torbl-design.txt
+++ b/doc/contrib/torbl-design.txt
@@ -7,27 +7,28 @@ Status:
 
 Why?
 
-  It's useful for third parties to be able to tell when they've got a
-  connection from a Tor exit node.  Potential aplications range from
+  It's useful for third parties to be able to tell when a given connection
+  is coming from a Tor exit node.  Potential applications range from
   "anonymous user" cloaks on IRC networks like oftc, to networks like
   Freenode that apply special authentication rules to users from these
-  IPs, to systems like Wikipedia that want to make a priority of
+  IPs, to systems like Wikipedia that may want to make a priority of
   _unblocking_ shared IPs more liberally than non-shared IPs, since shared
   IPs presumably have non-abusive users as well as abusive ones.
 
   Since Tor provides exit policies, not every Tor server will connect to
   every address:port combination on the Internet.  Unless you're trying to
   penalize hosts for supporting anonymity, it makes more sense to answer
-  the fine-grained question "which Tor servers will connect to _me_" than
+  the fine-grained question "which Tor servers will connect to _me_?" than
   the coarse-grained question "which Tor servers exist?"  The fine-grained
   approach also helps Tor server ops who share an IP with their Tor
-  server: if they want to access a site that blocks Tor users, they can
-  add that site to their exit policy, and the site can learn that they
-  won't send it anonymous connections.
-
-  Tor already ships with a tool (the "exitlist" script) to identify which
-  Tor nodes might open anonymous connections to any given exit address.
-  But this is a bit tricky to set up, and isn't seeing much use.
+  server: if they want to access a site that blocks Tor users, they
+  can exclude that site from their exit policy, and the site can learn
+  that they won't send it anonymous connections.
+
+  Tor already ships with a tool (the "contrib/exitlist" script) to
+  identify which Tor nodes might open anonymous connections to any given
+  exit address.  But this is a bit tricky to set up, so only sites like
+  Freenode and OFTC that are dedicated to privacy use it.
   Conversely, providers of some DNSBL implementations are providing
   coarse-grained lists of Tor hosts -- sometimes even listing servers that
   permit no exit connections at all.  This is rather a problem, since
@@ -40,9 +41,12 @@ How?
   cached-routers.new files as new routers arrive.  To tell whether a given
   server allows connections to a certain address:port combo, look at the
   definitions in dir-spec.txt or follow the logic of the current exitlist
-  script.
+  script. If bug 405 is still open when you work on this
+  (http://bugs.noreply.org/flyspray/index.php?do=details&id=405), you'll
+  probably want to extend it to look at only the newest descriptor for
+  each server, so you don't use obsolete exit policy data.
 
-  FetchUselessDescriptors would probably be a good option to enable.
+  FetchUselessDescriptors would probably be a good torrc option to enable.
 
   If you're also running a directory cache, you get extra-fresh
   information.
@@ -61,7 +65,7 @@ The DNS interface
   possibly a bad idea.
 
 
-  "General IP:Port"
+  Query type 1: "General IP:Port"
 
     Format:
         {IP1}.{port}.{IP2}.ip-port.torhosts.example.com
@@ -77,7 +81,7 @@ The DNS interface
 
     Example use:
         I'm running an IRC server at w.x.y.z:9999, and I want to tell
-        whether an incoming connections are from Tor servers.  I set
+        whether an incoming connection is from a Tor server.  I set
         up my IRC server to give a special mask to any user coming from
         an IP listed in 9999.z.y.x.w.ip-port.torhosts.example.com.
 
@@ -86,7 +90,7 @@ The DNS interface
         if it's a Tor server that allows connections to my ircd.
 
 
-  "IP-port group."
+  Query type 2: "IP-port group"
 
     Format:
         {IP}.{listname}.list.torhosts.example.com
@@ -100,7 +104,7 @@ The DNS interface
         Suppose torhosts.example.com has a list of IP:Port called "foo".
         There is an A record for 4.3.2.1.foo.list.torhosts.example.com
         if and only if 1.2.3.4 is a Tor server that permits connections
-        to one of the addresses in list "foo|.
+        to one of the addresses in list "foo".
 
     Example use:
         Suppose torhosts.example.com has a list of hosts in "examplenet",
@@ -116,7 +120,7 @@ The DNS interface
         just a few foonet addresses to my exit policy.
 
 
-  "My IP, with port."
+  Query type 3: "My IP, with port"
 
     Format:
         {IP}.{port}.me.torhosts.example.com
@@ -138,8 +142,7 @@ The DNS interface
         This would be easiest to use, but DNS gets in the way. If you
         create DNS records that give different results depending on who is
         asking, you mess up caching.  There could be a fix here, but might
-        now.
-        here.
+        not.
 
 
   RECOMMENDATION: Just build ip-port for now, and see what demand is
@@ -157,4 +160,7 @@ Other issues:
   masks wider than /8 make me nervous here, as do port ranges.
 
   We need an answer for what to do about hosts which exit from different
-  IPs than their advertised IP.
+  IPs than their advertised IP. One approach would be for the DNSBL
+  to launch periodic requests to itself through all exit servers whose
+  policies allow it -- and then see where the requests actually come from.
+