commit d5a0678ec727dfeb37127c9893903e9d6799e883
Author: Taylor Yu <catalyst(a)torproject.org>
Date: Fri Jul 20 16:01:20 2018 -0500
Say CREATE/CREATE2, etc. where needed
Not all of the text describing CREATE, CREATED, EXTEND, or EXTENDED
cells was updated when the "2"-suffixed versions were added.
Closes ticket 26894.
---
tor-spec.txt | 79 ++++++++++++++++++++++++++++++++----------------------------
1 file changed, 42 insertions(+), 37 deletions(-)
diff --git a/tor-spec.txt b/tor-spec.txt
index ef0e12e..b88befe 100644
--- a/tor-spec.txt
+++ b/tor-spec.txt
@@ -309,9 +309,10 @@ see tor-design.pdf.
(When initiating a connection, if a reasonably live consensus is
available, then the expected identity key is taken from that
consensus. But when initiating a connection otherwise, the expected
- identity key is the one given in the hard-coded authority or fallback
- list. Finally, when creating a connection because of an EXTEND cell, the
- expected identity key is the one given in the cell.)
+ identity key is the one given in the hard-coded authority or
+ fallback list. Finally, when creating a connection because of an
+ EXTEND/EXTEND2 cell, the expected identity key is the one given in
+ the cell.)
When connecting to an OR, all parties SHOULD reject the connection if that
OR has a malformed or missing certificate. When accepting an incoming
@@ -468,8 +469,8 @@ see tor-design.pdf.
The interpretation of 'Payload' depends on the type of the cell.
PADDING: Payload is unused.
- CREATE: Payload contains the handshake challenge.
- CREATED: Payload contains the handshake response.
+ CREATE/CREATE2: Payload contains the handshake challenge.
+ CREATED/CREATED2: Payload contains the handshake response.
RELAY: Payload contains the relay header and relay body.
DESTROY: Payload contains a reason for closing the circuit.
(see 5.4)
@@ -483,8 +484,8 @@ see tor-design.pdf.
If there is no other traffic, ORs and OPs send one another a PADDING
cell every few minutes.
- CREATE, CREATED, and DESTROY cells are used to manage circuits;
- see section 5 below.
+ CREATE, CREATE2, CREATED, CREATED2, and DESTROY cells are used to
+ manage circuits; see section 5 below.
RELAY cells are used to send commands and data along a circuit; see
section 6 below.
@@ -854,12 +855,12 @@ see tor-design.pdf.
5.1. CREATE and CREATED cells
Users set up circuits incrementally, one hop at a time. To create a
- new circuit, OPs send a CREATE cell to the first node, with the first
- half of an authenticated handshake; that node responds with a CREATED
- cell with the second half of the handshake. To extend a circuit past
- the first hop, the OP sends an EXTEND relay cell (see section 5.1.2)
- which instructs the last node in the circuit to send a CREATE cell to
- extend the circuit.
+ new circuit, OPs send a CREATE/CREATE2 cell to the first node, with
+ the first half of an authenticated handshake; that node responds with
+ a CREATED/CREATED2 cell with the second half of the handshake. To
+ extend a circuit past the first hop, the OP sends an EXTEND/EXTEND2
+ relay cell (see section 5.1.2) which instructs the last node in the
+ circuit to send a CREATE/CREATE2 cell to extend the circuit.
There are two kinds of CREATE and CREATED cells: The older
"CREATE/CREATED" format, and the newer "CREATE2/CREATED2" format. The
@@ -912,21 +913,21 @@ see tor-design.pdf.
5.1.1. Choosing circuit IDs in create cells
- The CircID for a CREATE cell is an arbitrarily chosen nonzero integer,
- selected by the node (OP or OR) that sends the CREATE cell. In link
- protocol 3 or lower, CircIDs are 2 bytes long; in protocol 4 or
- higher, CircIDs are 4 bytes long.
+ The CircID for a CREATE/CREATE2 cell is an arbitrarily chosen
+ nonzero integer, selected by the node (OP or OR) that sends the
+ CREATE/CREATE2 cell. In link protocol 3 or lower, CircIDs are 2
+ bytes long; in protocol 4 or higher, CircIDs are 4 bytes long.
- To prevent CircID collisions, when one node sends a CREATE cell to
- another, it chooses from only one half of the possible values based
- on the ORs' public identity keys.
+ To prevent CircID collisions, when one node sends a CREATE/CREATE2
+ cell to another, it chooses from only one half of the possible
+ values based on the ORs' public identity keys.
In link protocol version 3 or lower, if the sending node has a lower
key, it chooses a CircID with an MSB of 0; otherwise, it chooses a
CircID with an MSB of 1. (Public keys are compared numerically by
modulus.) With protocol version 3 or lower, a client with no public key
MAY choose any CircID it wishes, since clients never need to process a
- CREATE cell.
+ CREATE/CREATE2 cell.
In link protocol version 4 or higher, whichever node initiated the
connection sets its MSB to 1, and whichever node didn't initiate the
@@ -1234,11 +1235,12 @@ see tor-design.pdf.
open a new connection to that router.
4. Choose a circID not already in use on the connection with the
- first router in the chain; send a CREATE cell along the
- connection, to be received by the first onion router.
+ first router in the chain; send a CREATE/CREATE2 cell along
+ the connection, to be received by the first onion router.
- 5. Wait until a CREATED cell is received; finish the handshake
- and extract the forward key Kf_1 and the backward key Kb_1.
+ 5. Wait until a CREATED/CREATED2 cell is received; finish the
+ handshake and extract the forward key Kf_1 and the backward
+ key Kb_1.
6. For each subsequent onion router R (R_2 through R_N), extend
the circuit to R.
@@ -1248,11 +1250,11 @@ see tor-design.pdf.
1. Create an onion skin, encrypted to R_M's public onion key.
- 2. Send the onion skin in a relay EXTEND cell along
+ 2. Send the onion skin in a relay EXTEND/EXTEND2 cell along
the circuit (see sections 5.1.2 and 5.5).
- 3. When a relay EXTENDED cell is received, verify KH, and
- calculate the shared keys. The circuit is now extended.
+ 3. When a relay EXTENDED/EXTENDED2 cell is received, verify KH,
+ and calculate the shared keys. The circuit is now extended.
When an onion router receives an EXTEND relay cell, it sends a CREATE
cell to the next onion router, with the enclosed onion skin as its
@@ -1377,7 +1379,8 @@ see tor-design.pdf.
5.5.2. Forward Direction
- The forward direction is the direction that CREATE cells are sent.
+ The forward direction is the direction that CREATE/CREATE2 cells
+ are sent.
5.5.2.1. Routing from the Origin
@@ -1407,7 +1410,8 @@ see tor-design.pdf.
5.5.3. Backward Direction
- The backward direction is the opposite direction from CREATE cells.
+ The backward direction is the opposite direction from
+ CREATE/CREATE2 cells.
5.5.3.1. Relaying Backward at Onion Routers
@@ -1439,12 +1443,12 @@ see tor-design.pdf.
inbound RELAY_EARLY cells, it MUST close the circuit immediately.
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
+ EXTEND/EXTEND2 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.
- [Starting with Tor 0.2.3.11-alpha, relays should
- reject any EXTEND cell not received in a RELAY_EARLY cell.]
+ [Starting with Tor 0.2.3.11-alpha, relays should reject any
+ EXTEND/EXTEND2 cell not received in a RELAY_EARLY cell.]
6. Application connections and stream management
@@ -1935,10 +1939,11 @@ see tor-design.pdf.
9.3. "Relay"
- The "relay" protocols are those used to handle CREATE cells, and those that
- handle the various RELAY cell types received after a CREATE cell. (Except,
- relay cells used to manage introduction and rendezvous points are managed
- with the "HSIntro" and "HSRend" protocols respectively.)
+ The "relay" protocols are those used to handle CREATE/CREATE2
+ cells, and those that handle the various RELAY cell types received
+ after a CREATE/CREATE2 cell. (Except, relay cells used to manage
+ introduction and rendezvous points are managed with the "HSIntro"
+ and "HSRend" protocols respectively.)
Current versions are: