diff options
Diffstat (limited to 'spec/tor-spec/relay-cells.md')
| -rw-r--r-- | spec/tor-spec/relay-cells.md | 118 |
1 files changed, 81 insertions, 37 deletions
diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md index 346899b..f1f7997 100644 --- a/spec/tor-spec/relay-cells.md +++ b/spec/tor-spec/relay-cells.md @@ -13,7 +13,7 @@ End nodes that accept streams may be: - directory servers (RELAY_BEGIN_DIR, anonymous or non-anonymous), - onion services (RELAY_BEGIN, anonymous via a rendezvous point). -The payload of each unencrypted relay cell consists of an +The body of each unencrypted relay cell consists of an enveloped relay message, encoded as follows: | Field | Size @@ -24,7 +24,7 @@ enveloped relay message, encoded as follows: | Digest | 4 bytes | Length | 2 bytes | Data | Length bytes -| Padding | PAYLOAD_LEN - 11 - Length bytes +| Padding | CELL_BODY_LEN - 11 - Length bytes > TODO: When we implement [prop340](../proposals/340-packed-and-fragmented.md), > we should clarify which parts of the above are about @@ -32,40 +32,82 @@ enveloped relay message, encoded as follows: The relay commands are: -| Command | Identifier | Direction | Control? -| ------- | ---------- | --------- | -------- -| 1 | RELAY_BEGIN | forward | -| 2 | RELAY_DATA | forward or backward | -| 3 | RELAY_END | forward or backward | -| 4 | RELAY_CONNECTED | backward | -| 5 | RELAY_SENDME | forward or backward | sometimes control -| 6 | RELAY_EXTEND | forward | control -| 7 | RELAY_EXTENDED | backward | control -| 8 | RELAY_TRUNCATE | forward | control -| 9 | RELAY_TRUNCATED | backward | control -| 10 | RELAY_DROP | forward or backward | control -| 11 | RELAY_RESOLVE | forward | -| 12 | RELAY_RESOLVED | backward | -| 13 | RELAY_BEGIN_DIR | forward | -| 14 | RELAY_EXTEND2 | forward | control -| 15 | RELAY_EXTENDED2 | backward | control -| 16..18 | Reserved for UDP; Not yet in use, see [prop339]. -| 19..22 | Reserved for Conflux, see [prop329]. -| 32..40 | Used for hidden services; see the [rendezvous spec]. -| 41..42 | Used for circuit padding; see ["Circuit-level padding"] in the padding spec. -| 43 | XON (See Sec 4 of [prop324]) | forward or backward | -| 44 | XOFF (See Sec 4 of [prop324]) | forward or backward | +| Command | Identifier | Type | Description +| ------- | ---------- | ---- | ----------- +| <th>Core protocol</th> +| 1 | [BEGIN] | **F** | Open a stream +| 2 | [DATA] | **F**/**B** | Transmit data +| 3 | [END] | **F**/**B** | Close a stream +| 4 | [CONNECTED] | **B** | Stream has successfully opened +| 5 | [SENDME] | **F**/**B**, **C?** | Acknowledge traffic +| 6 | [EXTEND] | **F**, **C** | Extend a circuit with TAP (obsolete) +| 7 | [EXTENDED] | **B**, **C** | Finish extending a circuit with TAP (obsolete) +| 8 | [TRUNCATE] | **F**, **C** | Remove nodes from a circuit (unused) +| 9 | [TRUNCATED] | **B**, **C** | Report circuit truncation (unused) +| 10 | [DROP] | **F**/**B**, **C** | Long-range padding +| 11 | [RESOLVE] | **F** | Hostname lookup +| 12 | [RESOLVED] | **B** | Hostname lookup reply +| 13 | [BEGIN_DIR] | **F** | Open stream to directory cache +| 14 | [EXTEND2] | **F**, **C** | Extend a circuit +| 15 | [EXTENDED2] | **B**, **C** | Finish extending a circuit +| 16..18 | Reserved | | For UDP; see [prop339]. +| <th>Conflux</th> +| 19 | [CONFLUX_LINK][prop329] | **F**, **C** | Link circuits into a bundle +| 20 | [CONFLUX_LINKED][prop329] | **B**, **C** | Acknowledge link request +| 21 | [CONFLUX_LINKED_ACK][prop329] | **F**, **C** | Acknowledge CONFLUX_LINKED message (for timing) +| 22 | [CONFLUX_SWITCH][prop329] | **F**/**B**, **C** | Switch between circuits in a bundle +| <th>Onion services</th> +| 32 | [ESTABLISH_INTRO] | **F**, **C** | Create introduction point +| 33 | [ESTABLISH_RENDEZVOUS] | **F**, **C** | Create rendezvous point +| 34 | [INTRODUCE1] | **F**, **C** | Introduction request (to intro point) +| 35 | [INTRODUCE2] | **B**, **C** | Introduction request (to service) +| 36 | [RENDEZVOUS1] | **F**, **C** | Rendezvous request (to rendezvous point) +| 37 | [RENDEZVOUS2] | **B**, **C** | Rendezvous request (to client) +| 38 | [INTRO_ESTABLISHED] | **B**, **C** | Acknowledge ESTABLISH_INTRO +| 39 | [RENDEZVOUS_ESTABLISHED] | **B**, **C** | Acknowledge ESTABLISH_RENDEZVOUS +| 40 | [INTRODUCE_ACK] | **B**, **C** | Acknowledge INTRODUCE1 +| <th>Circuit padding</th> +| 41 | [PADDING_NEGOTIATE][circ-padding] | **F**, **C** | Negotiate circuit padding +| 42 | [PADDING_NEGOTIATED][circ-padding] | **B**, **C** | Negotiate circuit padding +| <th>Flow control</th> +| 43 | [XON][prop324] | **F**/**B** | Stream-level flow control +| 44 | [XOFF][prop324] | **F**/**B** | Stream-level flow control [prop324]: ../proposals/324-rtt-congestion-control.txt [prop329]: ../proposals/329-traffic-splitting.md [prop339]: ../proposals/339-udp-over-tor.md -[rendezvous spec]: ../rend-spec/index.md -["Circuit-level padding"]: ../padding-spec/circuit-level-padding.md#circuit-level-padding - -Commands labelled as "forward" must only be sent by the originator -of the circuit. Commands labelled as "backward" must only be sent by -other nodes in the circuit back to the originator. Commands marked -as either can be sent either by the originator or other nodes. +[circ-padding]: ../padding-spec/circuit-level-padding.md#circuit-level-padding +[BEGIN]: ./opening-streams.md#opening +[CONNECTED]: ./opening-streams.md#opening +[DATA]: ./opening-streams.md#transmitting +[DROP]: ./opening-streams.md#transmitting +[BEGIN_DIR]: ./opening-streams.md#opening-a-directory-stream +[END]: ./closing-streams.md#closing-streams +[RESOLVE]: ./remote-hostname-lookup.md +[RESOLVED]: ./remote-hostname-lookup.md +[EXTEND]: ./create-created-cells.md#EXTEND +[EXTEND2]: ./create-created-cells.md#EXTEND +[EXTENDED]: ./create-created-cells.md#EXTEND +[EXTENDED2]: ./create-created-cells.md#EXTEND +[TRUNCATE]: ./tearing-down-circuits.md +[TRUNCATED]: ./tearing-down-circuits.md +[SENDME]: ./flow-control.md#sendme-message-format +[ESTABLISH_INTRO]: ../rend-spec/introduction-protocol.md#EST_INTRO +[INTRO_ESTABLISHED]: ../rend-spec/introduction-protocol.md#INTRO_ESTABLISHED +[INTRODUCE1]: ../rend-spec/introduction-protocol.md#SEND_INTRO1 +[INTRODUCE2]: ../rend-spec/introduction-protocol.md#PROCESS_INTRO2 +[INTRODUCE_ACK]: ../rend-spec/introduction-protocol.md#SEND_INTRO1 +[ESTABLISH_RENDEZVOUS]: ../rend-spec/rendezvous-protocol.md#EST_REND_POINT +[RENDEZVOUS_ESTABLISHED]: ../rend-spec/rendezvous-protocol.md#EST_REND_POINT +[RENDEZVOUS1]: ../rend-spec/rendezvous-protocol.md#JOIN_REND +[RENDEZVOUS2]: ../rend-spec/rendezvous-protocol.md#JOIN_REND + +- **F** (Forward): Must only be sent by the originator of the circuit. +- **B** (Backward): Must only be sent by other nodes in the circuit + back towards the originator. +- **F**/**B** (Forward or backward): May be sent in either direction. +- **C**: (Control) must have a zero-valued stream ID. + (Other commands must have a nonzero stream ID.) The 'recognized' field is used as a simple indication that the cell is still encrypted. It is an optimization to avoid calculating @@ -78,12 +120,12 @@ that we should relay, the 'recognized' field will usually be nonzero, but will accidentally be zero with P=2^-16. When handling a relay cell, if the 'recognized' in field in a -decrypted relay payload is zero, the 'digest' field is computed as +decrypted relay cell is zero, the 'digest' field is computed as the first four bytes of the running digest of all the bytes that have been destined for this hop of the circuit or originated from this hop of the circuit, seeded from Df or Db respectively (obtained in [Setting circuit keys](./setting-circuit-keys.md#setting-circuit-keys)), -and including this relay cell's entire payload +and including this relay cell's entire body (taken with the digest field set to zero). Note that these digests _do_ include the padding bytes at the end of the cell, not only those up to "Len". If the digest is correct, the cell is considered "recognized" @@ -100,14 +142,16 @@ All relay messages pertaining to the same tunneled stream have the same stream ID. StreamIDs are chosen arbitrarily by the OP. No stream may have a StreamID of zero. Rather, relay messages that affect the entire circuit rather than a particular stream use a StreamID of zero --- they are marked in the table above as "\[control\]" style +-- they are marked in the table above as "**C**" ([control") style cells. (Sendme cells are marked as "sometimes control" because they can include a StreamID or not depending on their purpose -- see [Flow control](./flow-control.md#flow-control).) 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 unencrypted payload is padded with padding bytes. Implementations +the relay cell's body which contain the body of the message. +The remainder of +the unencrypted relay cell's body is padded with padding bytes. +Implementations handle padding bytes of unencrypted relay cells as they do padding bytes for other cell types; see [Cell Packet format](./cell-packet-format.md#cell-packet-format). |