aboutsummaryrefslogtreecommitdiff
path: root/tor-spec.txt
diff options
context:
space:
mode:
Diffstat (limited to 'tor-spec.txt')
-rw-r--r--tor-spec.txt132
1 files changed, 82 insertions, 50 deletions
diff --git a/tor-spec.txt b/tor-spec.txt
index 4722da5..97d5159 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
@@ -420,7 +421,7 @@ see tor-design.pdf.
CircID [CIRCID_LEN bytes]
Command [1 byte]
- Payload (padded with 0 bytes) [PAYLOAD_LEN bytes]
+ Payload (padded with padding bytes) [PAYLOAD_LEN bytes]
On a version 2 or higher connection, all cells are as in version 1
connections, except for variable-length cells, whose format is:
@@ -428,7 +429,11 @@ see tor-design.pdf.
CircID [CIRCID_LEN octets]
Command [1 octet]
Length [2 octets; big-endian integer]
- Payload [Length bytes]
+ Payload (some commands MAY pad) [Length bytes]
+
+ Most variable-length cells MAY be padded with padding bytes, except
+ for VERSIONS cells, which MUST NOT contain any additional bytes.
+ (The payload of VPADDING cells consists of padding bytes.)
On a version 2 connection, variable-length cells are indicated by a
command byte equal to 7 ("VERSIONS"). On a version 3 or
@@ -467,24 +472,43 @@ see tor-design.pdf.
132 -- AUTHORIZE (Client authorization) (Not yet used)
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.
- RELAY: Payload contains the relay header and relay body.
+ VPADDING/PADDING:
+ Payload contains padding bytes.
+ CREATE/CREATE2: Payload contains the handshake challenge.
+ CREATED/CREATED2: Payload contains the handshake response.
+ RELAY/RELAY_EARLY: Payload contains the relay header and relay body.
DESTROY: Payload contains a reason for closing the circuit.
(see 5.4)
Upon receiving any other value for the command field, an OR must
drop the cell. Since more cell types may be added in the future, ORs
should generally not warn when encountering unrecognized commands.
- The payload is padded with 0 bytes.
+ The cell is padded up to the cell length with padding bytes.
+
+ Senders set padding bytes depending on the cell's command:
+ VERSIONS: Payload MUST NOT contain padding bytes.
+ AUTHORIZE: Payload is unspecified and reserved for future use.
+ Other variable-length cells:
+ Payload MAY contain padding bytes at the end of the cell.
+ Padding bytes SHOULD be set to NUL.
+ RELAY/RELAY_EARLY: Payload MUST be padded to PAYLOAD_LEN with padding
+ bytes. Padding bytes SHOULD be set to random values.
+ Other fixed-length cells:
+ Payload MUST be padded to PAYLOAD_LEN with padding bytes.
+ Padding bytes SHOULD be set to NUL.
+ We recommend random padding in RELAY/RELAY_EARLY cells, so that the cell
+ content is unpredictable. See proposal 289 for details. For other
+ cells, TLS authenticates cell content, so randomised padding bytes are
+ redundant.
+
+ Receivers MUST ignore padding bytes.
PADDING cells are currently used to implement connection keepalive.
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.
@@ -836,6 +860,7 @@ see tor-design.pdf.
The address format is a type/length/value sequence as given in
section 6.4 below, without the final TTL. The timestamp is a
big-endian unsigned integer number of seconds since the Unix epoch.
+ Implementations MUST ignore unexpected bytes at the end of the cell.
Implementations MAY use the timestamp value to help decide if their
clocks are skewed. Initiators MAY use "other OR's address" to help
@@ -854,12 +879,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 +937,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
@@ -1233,11 +1258,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.
@@ -1247,11 +1273,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
@@ -1261,11 +1287,12 @@ see tor-design.pdf.
cell to the next onion router, with the enclosed HLEN, HTYPE, and HDATA
as its payload.
- As special cases, if the extend cell includes a digest of
- all zeroes, or asks to extend back to the relay that sent the extend
- cell, the circuit will fail and be torn down. The initiating onion
- router chooses some circID not yet used on the connection between the
- two onion routers. (But see section 5.1.1 above, concerning choosing
+ As special cases, if the EXTEND/EXTEND2 cell includes a legacy
+ identity, identity fingerprint, or Ed25519 identity of all zeroes, or
+ asks to extend back to the relay that sent the extend cell, the
+ circuit will fail and be torn down. The initiating onion router
+ chooses some circID not yet used on the connection between the two
+ onion routers. (But see section 5.1.1 above, concerning choosing
circIDs.)
When an onion router receives a CREATE/CREATE2 cell, if it already has a
@@ -1392,7 +1419,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
@@ -1422,7 +1450,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
@@ -1454,12 +1483,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
@@ -1544,7 +1573,9 @@ see tor-design.pdf.
The 'Length' field of a relay cell contains the number of bytes in
the relay payload which contain real payload data. The remainder of
- the payload is padded with NUL bytes.
+ the unencrypted payload is padded with padding bytes. Implementations
+ handle padding bytes of unencrypted relay cells as they do padding
+ bytes for other cell types; see Section 3.
If the RELAY cell is recognized but the relay command is not
understood, the cell must be dropped and ignored. Its contents
@@ -1792,8 +1823,8 @@ see tor-design.pdf.
Link padding can be created by sending PADDING or VPADDING cells
along the connection; relay cells of type "DROP" can be used for
- long-range padding. The contents of a PADDING, VPADDING, or DROP
- cell SHOULD be chosen randomly, and MUST be ignored.
+ long-range padding. The payloads of PADDING, VPADDING, or DROP
+ cells are filled with padding bytes. See Section 3.
If the link protocol is version 5 or higher, link level padding is
enabled as per padding-spec.txt. On these connections, clients may
@@ -1961,10 +1992,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: