diff options
| -rw-r--r-- | mdbook/proposals/book.toml | 1 | ||||
| -rw-r--r-- | spec/rend-spec/protocol-overview.md | 13 | ||||
| -rw-r--r-- | spec/tor-spec/relay-cells.md | 104 |
3 files changed, 84 insertions, 34 deletions
diff --git a/mdbook/proposals/book.toml b/mdbook/proposals/book.toml index e466b1b..5253388 100644 --- a/mdbook/proposals/book.toml +++ b/mdbook/proposals/book.toml @@ -287,4 +287,5 @@ enable = false "/345.html" = "./345-specs-in-mdbook.html" "/346.html" = "./346-protovers-again.html" "/347.html" = "./347-domain-separation.html" +"/348.html" = "./348-udp-app-support.html" # END AUTO-GENERATED REDIRECTS diff --git a/spec/rend-spec/protocol-overview.md b/spec/rend-spec/protocol-overview.md index a50b3d1..9f7c96f 100644 --- a/spec/rend-spec/protocol-overview.md +++ b/spec/rend-spec/protocol-overview.md @@ -40,9 +40,16 @@ circuits, and the cryptographic handshake gives the two parties a shared key and proves to the client that it is indeed talking to the hidden service. -Once the two circuits are joined, the client can use Tor RELAY cells -to deliver relay messages -to the server. RELAY_BEGIN messages open streams to an external process +Once the two circuits are joined, the client can use Tor relay cells +to deliver relay messages to the server: +Whenever the rendezvous point receives as relay cell from one of +the circuits, it transmits it to the other. +(It accepts both RELAY and RELAY_EARLY cells, +and retransmits them all as RELAY cells.) + +The two parties use these relay messages to implement Tor's +usual application stream protocol: +RELAY_BEGIN messages open streams to an external process or processes configured by the server; RELAY_DATA messages are used to communicate data on those streams, and so forth. diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md index a6c6b1c..f1f7997 100644 --- a/spec/tor-spec/relay-cells.md +++ b/spec/tor-spec/relay-cells.md @@ -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 @@ -100,7 +142,7 @@ 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).) |