some patches on nick's commit

svn:r177

doc/tor-spec.txt

@@ -222,7 +222,7 @@ which reveals the downstream node.
 
 3. Cell Packet format
 
-   The basic unit of communication between onion routers and onion
+   The basic unit of communication for onion routers and onion
    proxies is a fixed-width "Cell."  Each Cell contains the following
    fields:
 
@@ -242,10 +242,10 @@ which reveals the downstream node.
 
    The interpretation of 'Length' and 'Payload' depend on the type of
    the cell.
-      PADDING: Length is 0; Payload is 128 bytes of 0's. 
+      PADDING: Length is 0; Payload is 120 bytes of 0's. 
       CREATE: Length is a value between 1 and 120; the first 'length'
-        bytes or payload contain a portion of an onion.
-      DATA: Length is a value between 4 [5?] and 120; the first 'length'
+        bytes of payload contain a portion of an onion.
+      DATA: Length is a value between 4 and 120; the first 'length'
         bytes of payload contain useful data.
       DESTROY: Neither field is used.
       SENDME: Length encodes a window size, payload is unused.
@@ -281,10 +281,12 @@ which reveals the downstream node.
          Key seed material        [16 bytes]
                              [Total: 28 bytes]
 
+     The value of Version is currently 2.
+
      The forward and backward ciphers fields can take the following values:
           0: Identity 
           1: Single DES in OFB
-	  2: RC4
+          2: RC4
 
      The port and address field denote the IPV4 address and port of
      the next onion router in the circuit, or are set to 0 for the
@@ -294,8 +296,6 @@ which reveals the downstream node.
      Jan 1970); by default, it is set to the current time plus one
      day.
 
-     The value of OR_VERSION is currently 2.
-
    When constructing an onion to create a circuit from OR_1,
    OR_2... OR_N,  the onion creator performs the following steps:
 
@@ -305,7 +305,7 @@ which reveals the downstream node.
   
          A. Create an onion layer L, setting Version=2,
             BackCipher=DES/OFB(1), ForwardCipher=DES/OFB(2), 
-	    ExpirationTime=now + 1 day, and Seed=16 random bytes.
+            ExpirationTime=now + 1 day, and Seed=16 random bytes.
 
             If I=N, set Port=Address=0.  Else, set Port and Address to
             the IPV4 port and address of OR_{I+1}.
@@ -330,7 +330,8 @@ which reveals the downstream node.
 
        2. Choose an ACI not already in use on the connection with the
           first router in the chain.  If our address/port pair is
-          numerically higher than the 
+          numerically higher than the address/port pair of the other
+          side, then let the high bit of the ACI be 1, else 0.
 
        3. To send M over the wire, prepend a 4-byte integer containing
           Len(M).  Call the result M'.  Let N=ceil(Len(M')/120).
@@ -350,9 +351,9 @@ which reveals the downstream node.
           with this ACI, drop the cell.
 
           Otherwise, if we have no circuit along this connection with
-	  this ACI, let L = the integer value of the first 4 bytes of 
+          this ACI, let L = the integer value of the first 4 bytes of 
           the payload.  Create a half-open circuit with this ACI, and
-	  begin queueing CREATE cells for this circuit.
+          begin queueing CREATE cells for this circuit.
 
           Otherwise, we have a half-open circuit.  If the total
           payload length of the CREATE cells for this circuit is at
@@ -362,15 +363,14 @@ which reveals the downstream node.
        2. Once we have a complete onion, decrypt the first 128 bytes
           of the onion with this OR's RSA private key, and extract
           the outmost onion layer.  If the version, back cipher, or
-          forward cipher is unrecognized, drop the onion [XXXX then
-          what? -NM].  If the expiration time is in the past, then
-          drop the onion [XXXX then what? -NM].
+          forward cipher is unrecognized, or the expiration time is
+          in the past, then tear down the circuit (see section 4.2).
 
           Compute K1 through K3 as above.  Use K1 to decrypt the rest
           of the onion using DES/OFB.
 
           If we are not the exit node, remove the first layer from the
-          decrypted onion, and send it the remainder to the next OR
+          decrypted onion, and send the remainder to the next OR
           on the circuit, as specified above.  (Note that we'll
           choose a different ACI for this circuit on the connection
           with the next OR.)
@@ -382,16 +382,17 @@ which reveals the downstream node.
 4.2. Tearing down circuits
 
    Circuits are torn down when an unrecoverable error occurs along
-   the circuit, when all topics on a circuit are closed and the
-   circuit's intended lifetime is over, or when (.... ?).
+   the circuit, or when all topics on a circuit are closed and the
+   circuit's intended lifetime is over.
 
    To tear down a circuit, an OR or OP sends a DESTROY cell with that
-   circuit's ACI to every adjacent node on that circuit.
+   direction's ACI to the adjacent nodes on that circuit.
 
    Upon receiving a DESTROY cell, an OR frees resources associated
-   with the corresponding circuit, and (if not the start or end of the
-   circuit) sends a DESTROY cell for that circuit to the next OR in
-   the circuit.
+   with the corresponding circuit. If it's not the start or end of the
+   circuit, it sends a DESTROY cell for that circuit to the next OR in
+   the circuit. If the node is the start or end of the circuit, then
+   it tears down any associated edge connections (see section 5.1).
 
    After a DESTROY cell has been processed, an OR ignores all data or
    destroy cells for the corresponding circuit.
@@ -402,24 +403,24 @@ which reveals the downstream node.
    determines whether it has a corresponding circuit along that
    connection.  If not, the OR drops the DATA cell.
 
-   Otherwise, if the OR is not at the edge of the circuit, it
-   de/encrypts the length field and the payload with DES/OFB, as
-   follows:
+   Otherwise, if the OR is not at the OP edge of the circuit (that is,
+   either an 'exit node' or a non-edge node), it de/encrypts the length
+   field and the payload with DES/OFB, as follows:
         'Forward' data cell (same direction as onion):
             Use K2 as key; encrypt.
         'Back' data cell (opposite direction from onion):
             Use K3 as key; decrypt.
 
-   Otherwise, the OR is at the edge of the circuit, and it generates
-   and processes the length and payload fields of DATA cells as
-   described in section 5 below.  (To encrypt or decrypt DATA cells,
-   the OP node de/encrypts the length and payload fields with DES/OFB as
+   Otherwise, if the data cell has arrived to the OP edge of the circuit,
+   the OP de/encrypts the length and payload fields with DES/OFB as
    follows:
          OP sends data cell:
-	    For I=1...N, decrypt with K2_I.
+            For I=1...N, decrypt with K2_I.
          OP receives data cell:
-            For I=N...1, encrypt with K3_I
-   )
+            For I=N...1, encrypt with K3_I.
+
+   Edge nodes process the length and payload fields of DATA cells as
+   described in section 5 below.
 
 5. Application connections and topic management
 
@@ -432,14 +433,14 @@ which reveals the downstream node.
    The first 4 bytes of each data cell are reserved as follows:
          Topic command           [1 byte]
          Unused, set to 0.       [1 byte]
-	 Topic ID                [2 bytes]
+         Topic ID                [2 bytes]
 
    The recognized topic commands are:
          1 -- TOPIC_BEGIN
-	 2 -- TOPIC_DATA
-	 3 -- TOPIC_END
-	 4 -- TOPIC_CONNECTED
-	 5 -- TOPIC_SENDME
+         2 -- TOPIC_DATA
+         3 -- TOPIC_END
+         4 -- TOPIC_CONNECTED
+         5 -- TOPIC_SENDME
 
    All DATA cells pertaining to the same tunneled connection have the
    same topic ID.
@@ -447,7 +448,7 @@ which reveals the downstream node.
    To create a new anonymized TCP connection, the OP sends a
    TOPIC_BEGIN data cell with a payload encoding the address and port
    of the destination host.  The payload format is:
-         ADDRESS ',' PORT '\000'
+         ADDRESS | ',' | PORT | '\000'
    where ADDRESS may be a DNS hostname, or an IPv4 address in
    dotted-quad format; and where PORT is encoded in decimal.
 
@@ -502,7 +503,7 @@ which reveals the downstream node.
    how many cells it is allowed to send to the next hop in the circuit
    before queueing cells.  This 'window' value is initially set to
    1000 cells in each direction.  Each edge node on a circuit sends a
-   SENDME cell (with length=100) every time it has receives 100 cells
+   SENDME cell (with length=100) every time it has received 100 cells
    on the circuit.  When a node receives a SENDME cell for a circuit,
    it increases the circuit's window in the corresponding by the value
    of the cell's length field, and (if not an edge node) passes an