Document RELAY_EARLY cells in tor-spec.txt: proposal 110 is mostly implemented, and the rest of it will need to wait until all current Tor 0.2.0.x clients are obsolete to close.

svn:r17816

2 files changed, 28 insertions, 3 deletions

diff --git a/doc/spec/proposals/110-avoid-infinite-circuits.txt b/doc/spec/proposals/110-avoid-infinite-circuits.txt
index 2637003ce..1834cd34a 100644
--- a/doc/spec/proposals/110-avoid-infinite-circuits.txt
+++ b/doc/spec/proposals/110-avoid-infinite-circuits.txt
@@ -57,6 +57,12 @@ Design:
   data cells over the stream as relay_early cells, regardless of their
   actual type.
 
+  (Note that a circuit that is out of relay_early cells MUST NOT be
+  cannibalized later, since it can't extend.  Note also that it's always okay
+  to use regular RELAY cells when sending non-EXTEND commands targetted at
+  the first hop of a circuit, since there is no intermediate hop to try to
+  learn the relay command type.)
+
   Each intermediate server would pass on the same type of cell that it
   received (either relay or relay_early), and the cell's destination
   will be able to learn whether it's allowed to contain an Extend request.
diff --git a/doc/spec/tor-spec.txt b/doc/spec/tor-spec.txt
index 8dfa0da71..77a91cad8 100644
--- a/doc/spec/tor-spec.txt
+++ b/doc/spec/tor-spec.txt
@@ -289,6 +289,7 @@ see tor-design.pdf.
          6 -- CREATED_FAST (Circuit created, no PK) (See Sec 5.1)
          7 -- VERSIONS    (Negotiate proto version) (See Sec 4)
          8 -- NETINFO     (Time and address info)   (See Sec 4)
+         9 -- RELAY_EARLY (End-to-end data; limited) (See sec 5.6)
 
    The interpretation of 'Payload' depends on the type of the cell.
       PADDING: Payload is unused.
@@ -623,9 +624,9 @@ see tor-design.pdf.
 
 5.5. Routing relay cells
 
-   When an OR receives a RELAY cell, it checks the cell's circID and
-   determines whether it has a corresponding circuit along that
-   connection.  If not, the OR drops the RELAY cell.
+   When an OR receives a RELAY or RELAY_EARLY cell, it checks the cell's
+   circID and determines whether it has a corresponding circuit along that
+   connection.  If not, the OR drops the cell.
 
    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 payload
@@ -653,6 +654,24 @@ see tor-design.pdf.
 
    For more information, see section 6 below.
 
+5.6. Handling relay_early cells
+
+   A RELAY_EARLY cell is designed to limit the length any circuit can reach.
+   When an OR receives a RELAY_EARLY cell, and the next node in the circuit
+   is speaking v2 of the link protocol or later, the OR relays the cell as a
+   RELAY_EARLY cell.  Otherwise, it relays it as a RELAY cell.
+
+   If a node ever receives more than 8 RELAY_EARLY cells on a given circuit,
+   it SHOULD close the circuit.
+
+   When speaking v2 of the link protocol or later, clients MUST only send
+   EXTEND cells inside RELAY_EARLY cells.  Clients SHOULD send the first ~8
+   RELAY cells that are not targeted at the first hop of any circuit as
+   RELAY_EARLY cells too, in order to partially conceal the circuit length.
+
+   [In a future version of Tor, servers will reject any EXTEND cell not
+   received in a RELAY_EARLY cell.  See proposal 110.]
+
 6. Application connections and stream management
 
 6.1. Relay cells