diff options
| author | Nick Mathewson <nickm@torproject.org> | 2024-02-06 11:18:31 -0500 |
|---|---|---|
| committer | Nick Mathewson <nickm@torproject.org> | 2024-02-06 13:00:44 -0500 |
| commit | db80b935f799ab44750ff378267b10a967af38e3 (patch) | |
| tree | 12be4d952e51f6102fee807c25532025fad91def | |
| parent | ad73886e2a38255b5b0b599628f67fe820a5c440 (diff) | |
| download | torspec-db80b935f799ab44750ff378267b10a967af38e3.tar.gz torspec-db80b935f799ab44750ff378267b10a967af38e3.zip | |
Apply "cell" and "message" consistently
Done by grepping for "cell" and making sure it was accurate in every
place where it occurs. In tor-spec, I also searched for "message".
Part of #253.
36 files changed, 373 insertions, 345 deletions
diff --git a/spec/control-spec/implementation-notes.md b/spec/control-spec/implementation-notes.md index ebbf113..97ac811 100644 --- a/spec/control-spec/implementation-notes.md +++ b/spec/control-spec/implementation-notes.md @@ -342,7 +342,7 @@ back, indicating that the circuit is ready. Once we've finished our one-hop circuit, we will start a new stream for fetching the networkstatus consensus. We'll stay in this phase -until we get the 'connected' relay cell back, indicating that we've +until we get the RELAY_CONNECTED message back, indicating that we've established a directory connection. ```text @@ -373,7 +373,7 @@ tag=requesting_descriptors summary="Asking for relay descriptors" Once we have a valid networkstatus consensus and we've checked all its signatures, we start asking for relay descriptors. We stay in this -phase until we have received a 'connected' relay cell in response to +phase until we have received a RELAY_CONNECTED message in response to a request for descriptors. ```text @@ -585,7 +585,7 @@ tag=requesting_status summary="Asking for networkstatus consensus" Once we've finished our one-hop circuit, we will start a new stream for fetching the networkstatus consensus. We'll stay in this phase -until we get the 'connected' relay cell back, indicating that we've +until we get the RELAY_CONNECTED message back, indicating that we've established a directory connection. Phase 25: @@ -616,7 +616,7 @@ fetched on hold and fetch the keys so we can verify the signatures. Once we have a valid networkstatus consensus and we've checked all its signatures, we start asking for relay descriptors. We stay in this -phase until we have received a 'connected' relay cell in response to +phase until we have received a RELAY_CONNECTED message in response to a request for descriptors. ```text diff --git a/spec/control-spec/replies.md b/spec/control-spec/replies.md index 4046d6d..6fce9b1 100644 --- a/spec/control-spec/replies.md +++ b/spec/control-spec/replies.md @@ -292,8 +292,8 @@ The syntax is: has become redundant, since some other circuit opened in parallel with it has succeeded.) - The "REMOTE_REASON" field is provided only when we receive a DESTROY or - TRUNCATE cell, and only if extended events are enabled. It contains the + The "REMOTE_REASON" field is provided only when we receive a DESTROY cell or + RELAY_TRUNCATE message, and only if extended events are enabled. It contains the actual reason given by the remote OR for closing the circuit. Clients MUST accept reasons not listed above. Reasons are as listed in tor-spec.txt. [Added in Tor 0.4.3.1-alpha.] @@ -319,8 +319,8 @@ The syntax is: "NEW" / ; New request to connect "NEWRESOLVE" / ; New request to resolve an address "REMAP" / ; Address re-mapped to another - "SENTCONNECT" / ; Sent a connect cell along a circuit - "SENTRESOLVE" / ; Sent a resolve cell along a circuit + "SENTCONNECT" / ; Sent a connect message along a circuit + "SENTRESOLVE" / ; Sent a resolve message along a circuit "SUCCEEDED" / ; Received a reply; stream established "FAILED" / ; Stream failed and not retriable "CLOSED" / ; Stream closed @@ -383,14 +383,14 @@ to talk to itself. accept reasons not listed above. Reasons are as given in tor-spec.txt, except for: - END (We received a RELAY_END cell from the other side of this + END (We received a RELAY_END message from the other side of this stream.) PRIVATE_ADDR (The client tried to connect to a private address like 127.0.0.1 or 10.0.0.1 over Tor.) [XXXX document more. -NM] The "REMOTE_REASON" field is provided only when we receive a RELAY_END - cell, and only if extended events are enabled. It contains the actual + message, and only if extended events are enabled. It contains the actual reason given by the remote OR for closing the stream. Clients MUST accept reasons not listed above. Reasons are as listed in tor-spec.txt. @@ -1524,7 +1524,7 @@ The syntax is: ID is the locally unique circuit identifier that is only included if the circuit originates at this node. -Inbound and outbound refer to the direction of cell flow through the +Inbound and outbound refer to the direction of relay cell flow through the circuit which is either to origin (inbound) or from origin (outbound). InboundQueue and OutboundQueue are identifiers of the inbound and diff --git a/spec/dir-spec/extra-info-document-format.md b/spec/dir-spec/extra-info-document-format.md index e743ff3..0defe70 100644 --- a/spec/dir-spec/extra-info-document-format.md +++ b/spec/dir-spec/extra-info-document-format.md @@ -236,7 +236,7 @@ statuses is as follows: List of statistics about possible failures in the download process of v2/v3 network statuses. Requests are either "direct" HTTP-encoded requests over the relay's directory port, or -"tunneled" requests using a BEGIN_DIR cell over the relay's OR +"tunneled" requests using a BEGIN_DIR relay message over the relay's OR port. The list of possible statistics can change, and statistics can be left out from reporting. The current list of statistics is as follows: @@ -444,7 +444,7 @@ hours. [At most once.] ``` -Approximate number of RELAY cells seen in either direction on a +Approximate number of relay cells seen in either direction on a circuit after receiving and successfully processing a RENDEZVOUS1 cell. @@ -509,19 +509,19 @@ The keyword list is currently as follows: - The current rounding value for cell count fields (10000 by default) write-drop - - The number of RELAY_DROP cells this relay sent + - The number of RELAY_DROP messages this relay sent write-pad - - The number of CELL_PADDING cells this relay sent + - The number of PADDING cells this relay sent write-total - The total number of cells this relay cent read-drop - - The number of RELAY_DROP cells this relay received + - The number of RELAY_DROP messages this relay received read-pad - - The number of CELL_PADDING cells this relay received + - The number of PADDING cells this relay received read-total - The total number of cells this relay received enabled-read-pad - - The number of CELL_PADDING cells this relay received on + - The number of PADDING cells this relay received on connections that support padding enabled-read-total - The total number of cells this relay received on connections diff --git a/spec/dir-spec/server-descriptor-format.md b/spec/dir-spec/server-descriptor-format.md index 9cfaeea..ddd7fb2 100644 --- a/spec/dir-spec/server-descriptor-format.md +++ b/spec/dir-spec/server-descriptor-format.md @@ -471,7 +471,7 @@ Tor 0.2.3.x only the first address/port pair is advertised and used. ```text Present if the router accepts "tunneled" directory requests using a - BEGIN_DIR cell over the router's OR port. + BEGIN_DIR relay message over the router's OR port. (Added in 0.2.8.1-alpha. Before this, Tor relays accepted tunneled directory requests only if they had a DirPort open, or if they were bridges.) diff --git a/spec/dos-spec/memory-exhaustion.md b/spec/dos-spec/memory-exhaustion.md index 2cc55eb..14c1f6b 100644 --- a/spec/dos-spec/memory-exhaustion.md +++ b/spec/dos-spec/memory-exhaustion.md @@ -23,7 +23,7 @@ or derived from a fraction of the total amount of system RAM. As of Tor 0.4.7.x, the MaxMemInQueues mechanism tracks the following kinds of allocation: -- Cells queued on circuits. +- Relay cells queued on circuits. - Per-connection read or write buffers. - On-the-fly compression or decompression state. - Half-open stream records. @@ -59,7 +59,7 @@ oldest data. (For example, a circuit on which a single cell has been queued for 5 minutes would be freed before a circuit where 100 cells have been queued for 5 seconds.) "Data queued on a circuit" includes all data that we could drop if the circuit were destroyed: -not only the cells on the circuit's cell queue, but also any bytes +not only the cells on the circuit's relay cell queue, but also any bytes queued in buffers associated with streams or half-stream records attached to the circuit. diff --git a/spec/dos-spec/overview.md b/spec/dos-spec/overview.md index 0ea0994..81b7e35 100644 --- a/spec/dos-spec/overview.md +++ b/spec/dos-spec/overview.md @@ -32,7 +32,7 @@ Instead C Tor relies on limits for protocol resources, like circuits extensions Relay operators can place hard limits on total bandwidth using the `Bandwidth` or `RelayBandwidth` options. These options can help relay operators avoid bandwidth peaks on their network, however they aren't designed as denial of service prevention mechanisms. Beyond just shaving off harmful bandwidth peaks it's important that normal service is not disrupted too much, and especially not disrupted in a targetable way. -To approximate this goal we rely on [flow control](../tor-spec/flow-control.md) and fair dequeueing of relayed cells. +To approximate this goal we rely on [flow control](../tor-spec/flow-control.md) and fair dequeueing of relay cells. ## Protocol resources diff --git a/spec/hspow-spec/analysis-discussion.md b/spec/hspow-spec/analysis-discussion.md index e021b85..6585d3f 100644 --- a/spec/hspow-spec/analysis-discussion.md +++ b/spec/hspow-spec/analysis-discussion.md @@ -10,7 +10,7 @@ To design a protocol and choose its parameters, we first need to understand a fe ### Overwhelm PoW verification ("top half") {#attack-top-half} -A basic attack here is the adversary spamming with bogus INTRO cells so that the service does not have computing capacity to even verify the proof-of-work. This adversary tries to overwhelm the procedure in the [`v1` verification algorithm](./v1-equix.md#service-verify) section. +A basic attack here is the adversary spamming with bogus INTRODUCE messages so that the service does not have computing capacity to even verify the proof-of-work. This adversary tries to overwhelm the procedure in the [`v1` verification algorithm](./v1-equix.md#service-verify) section. That's why we need the PoW algorithm to have a cheap verification time so that this attack is not possible: we explore this PoW parameter below in the section on [PoW verification](#pow-tuning-verification). @@ -19,9 +19,9 @@ That's why we need the PoW algorithm to have a cheap verification time so that t Given the way [the introduction queue](./common-protocol.md#intro-queue) works, a very effective strategy for the attacker is to totally overwhelm the queue processing by sending more high-effort introductions than the onion service can handle at any given tick. This adversary tries to overwhelm the process of [handling queued introductions](./common-protocol.md#handling-queue). -To do so, the attacker would have to send at least 20 high-effort introduction cells every 100ms, where high-effort is a PoW which is above the estimated level of ["the motivated user"](./motivation.md#user-profiles). +To do so, the attacker would have to send at least 20 high-effort INTRODUCE messages every 100ms, where high-effort is a PoW which is above the estimated level of ["the motivated user"](./motivation.md#user-profiles). -An easier attack for the adversary, is the same strategy but with introduction cells that are all above the comfortable level of ["the standard user"](./motivation.md#user-profiles). +An easier attack for the adversary, is the same strategy but with INTRODUCE messages that are all above the comfortable level of ["the standard user"](./motivation.md#user-profiles). This would block out all standard users and only allow motivated users to pass. ### Hybrid overwhelm strategy {#attack-hybrid} @@ -66,19 +66,19 @@ At the end of this section we will estimate the resources that an attacker needs ### PoW verification {#pow-tuning-verification} -Verifying a PoW token is the first thing that a service does when it receives an INTRODUCE2 cell. Our current implementation is described by the [`v1` verification algorithm](./v1-equix.md#service-verify) specification. +Verifying a PoW token is the first thing that a service does when it receives an INTRODUCE2 message. Our current implementation is described by the [`v1` verification algorithm](./v1-equix.md#service-verify) specification. Verification time is a critical performance parameter. Actual times can be measured by `cargo bench` now, and the verification speeds we achieve are more like 50-120 microseconds. The specific numbers below are dated, but the analysys below is preserved as an illustration of the design space we are optimizing within. To defend against a [top-half attack](#attack-top-half) it's important that we can quickly perform all the steps in-between receiving an introduction request over the network and adding it to our effort-prioritized queue. -All time spent verifying PoW adds overhead to the already existing "top half" part of handling an introduction cell. +All time spent verifying PoW adds overhead to the already existing "top half" part of handling an INTRODUCE message. Hence we should be careful to add minimal overhead here. During our [performance measurements on tor](#tor-measurements) we learned that the "top half" takes about 0.26 msecs in average, without doing any sort of PoW verification. -Using that value we compute the following table, that describes the number of cells we can queue per second (aka times we can perform the "top half" process) for different values of PoW verification time: +Using that value we compute the following table, that describes the number of requests we can queue per second (aka times we can perform the "top half" process) for different values of PoW verification time: -| PoW Verification Time | Total "top half" time | Cells Queued per second +| PoW Verification Time | Total "top half" time | Requests Queued per second | --------------------- | --------------------- | ----------------------- | 0 msec | 0.26 msec | 3846 | 1 msec | 1.26 msec | 793 @@ -94,9 +94,9 @@ Using that value we compute the following table, that describes the number of ce Here is how you can read the table above: -- For a PoW function with a 1ms verification time, an attacker needs to send 793 dummy introduction cells per second to succeed in a [top-half attack](#attack-top-half). -- For a PoW function with a 2ms verification time, an attacker needs to send 442 dummy introduction cells per second to succeed in a [top-half attack](#attack-top-half). -- For a PoW function with a 10ms verification time, an attacker needs to send 97 dummy introduction cells per second to succeed in a [top-half attack](#attack-top-half). +- For a PoW function with a 1ms verification time, an attacker needs to send 793 dummy introduction requests per second to succeed in a [top-half attack](#attack-top-half). +- For a PoW function with a 2ms verification time, an attacker needs to send 442 dummy requests per second to succeed in a [top-half attack](#attack-top-half). +- For a PoW function with a 10ms verification time, an attacker needs to send 97 dummy requests per second to succeed in a [top-half attack](#attack-top-half). Whether an attacker can succeed at that depends on the attacker's resources, but also on the network's capacity. @@ -104,10 +104,10 @@ Our purpose here is to have the smallest PoW verification overhead possible that Note that the table above is simply the result of a naive multiplication and does not take into account all the auxiliary overheads that happen every second like the time to invoke the mainloop, the bottom-half processes, or pretty much anything other than the "top-half" processing. -During our measurements the time to handle INTRODUCE2 cells dominates any other action time: +During our measurements the time to handle introduction requests dominates any other action time: There might be events that require a long processing time, but these are pretty infrequent (like uploading a new HS descriptor) and hence over a long time they smooth out. -Hence extrapolating the total cells queued per second based on a single "top half" time seems like good enough to get some initial intuition. -That said, the values of "Cells queued per second" from the table above, are likely much smaller than displayed above because of all the auxiliary overheads. +Hence extrapolating the total introduction requests queued per second based on a single "top half" time seems like good enough to get some initial intuition. +That said, the values of "Requests queued per second" from the table above, are likely much smaller than displayed above because of all the auxiliary overheads. ### PoW difficulty analysis {#pow-difficulty-analysis} @@ -165,27 +165,27 @@ With the above table we can create some profiles for starting values of our PoW #### Analysis based on Tor's performance {#pow-difficulty-tor} To go deeper here, we can use the [performance measurements on tor](#tor-measurements) to get a more specific intuition on the starting difficulty. -In particular, we learned that completely handling an introduction cell takes 5.55 msecs in average. -Using that value, we can compute the following table, that describes the number of introduction cells we can handle per second for different values of PoW verification: - -| PoW Verification Time | Total time to handle introduction cell | Cells handled per second -| --------------------- | --------------------------------------- | ------------------------ -| 0 msec | 5.55 msec | 180.18 -| 1 msec | 6.55 msec | 152.67 -| 2 msec | 7.55 msec | 132.45 -| 3 msec | 8.55 msec | 116.96 -| 4 msec | 9.55 mesc | 104.71 -| 5 msec | 10.55 msec | 94.79 -| 6 msec | 11.55 msec | 86.58 -| 7 msec | 12.55 msec | 79.68 -| 8 msec | 13.55 msec | 73.80 -| 9 msec | 14.55 msec | 68.73 -| 10 msec | 15.55 msec | 64.31 +In particular, we learned that completely handling an introduction request takes 5.55 msecs in average. +Using that value, we can compute the following table, that describes the number of introduction requests we can handle per second for different values of PoW verification: + +| PoW Verification Time | Total time to handle request | Requests handled per second +| --------------------- | ---------------------------- | ------------------------ +| 0 msec | 5.55 msec | 180.18 +| 1 msec | 6.55 msec | 152.67 +| 2 msec | 7.55 msec | 132.45 +| 3 msec | 8.55 msec | 116.96 +| 4 msec | 9.55 mesc | 104.71 +| 5 msec | 10.55 msec | 94.79 +| 6 msec | 11.55 msec | 86.58 +| 7 msec | 12.55 msec | 79.68 +| 8 msec | 13.55 msec | 73.80 +| 9 msec | 14.55 msec | 68.73 +| 10 msec | 15.55 msec | 64.31 Here is how you can read the table above: -- For a PoW function with a 1ms verification time, an attacker needs to send 152 high-effort introduction cells per second to succeed in a [bottom-half attack](#attack-bottom-half) attack. -- For a PoW function with a 10ms verification time, an attacker needs to send 64 high-effort introduction cells per second to succeed in a [bottom-half attack](#attack-bottom-half) attack. +- For a PoW function with a 1ms verification time, an attacker needs to send 152 high-effort introduction requests per second to succeed in a [bottom-half attack](#attack-bottom-half) attack. +- For a PoW function with a 10ms verification time, an attacker needs to send 64 high-effort introduction requests per second to succeed in a [bottom-half attack](#attack-bottom-half) attack. We can use this table to specify a starting difficulty that won't allow our target adversary to succeed in an [bottom-half attack](#attack-bottom-half) attack. @@ -223,7 +223,7 @@ There are various improvements that can be done in this proposal, and while we a This is just the beginning in DoS defences for Tor and there are various future designs and schemes that we can investigate. Here is a brief summary of these: - "More advanced PoW schemes" -- - We could use more advanced memory-hard PoW schemes like MTP-argon2 or Itsuku to make it even harder for adversaries to create successful PoWs. Unfortunately these schemes have much bigger proof sizes, and they won't fit in INTRODUCE1 cells. See #31223 for more details. + We could use more advanced memory-hard PoW schemes like MTP-argon2 or Itsuku to make it even harder for adversaries to create successful PoWs. Unfortunately these schemes have much bigger proof sizes, and they won't fit in INTRODUCE1 messages. See #31223 for more details. - "Third-party anonymous credentials" -- We can use anonymous credentials and a third-party token issuance server on the clearnet to issue tokens based on PoW or CAPTCHA and then use those tokens to get access to the service. See `[REF_CREDS]` for more details. @@ -267,42 +267,42 @@ The following should be read as if tor is an onion service and thus the end poin Tor uses libevent for its mainloop. For network I/O operations, a mainloop event is used to inform tor if it can read on a certain socket, or a connection object in tor. -From there, this event will empty the connection input buffer (inbuf) by extracting and processing a cell at a time. -The mainloop is single threaded and thus each cell is handled sequentially. +From there, this event will empty the connection input buffer (inbuf) by extracting and processing a request at a time. +The mainloop is single threaded and thus each request is handled sequentially. -Processing an INTRODUCE2 cell at the onion service means a series of operations (in order): +Processing an INTRODUCE2 message at the onion service means a series of operations (in order): -1. Unpack cell from inbuf to local buffer. +1. Unpack relay cell from inbuf to local buffer. 2. Decrypt cell (AES operations). -3. Parse cell header and process it depending on its RELAY_COMMAND. -4. INTRODUCE2 cell handling which means building a rendezvous circuit: +3. Parse relay message and process it depending on its RELAY_COMMAND. +4. INTRODUCE2 handling which means building a rendezvous circuit: - Path selection - Launch circuit to first hop. 5. Return to mainloop event which essentially means back to step (1). -Tor will read at most 32 cells out of the inbuf per mainloop round. +Tor will read at most 32 messages out of the inbuf per mainloop round. ### Requirements for PoW {#tor-pow-queue} -With this proposal, in order to prioritize cells by the amount of PoW work -it has done, cells can *not* be processed sequentially as described above. +With this proposal, in order to prioritize requests by the amount of PoW work +it has done, requests can *not* be processed sequentially as described above. -Thus, we need a way to queue a certain number of cells, prioritize them and then process some cell(s) from the top of the queue (that is, the cells that have done the most PoW effort). +Thus, we need a way to queue a certain number of requests, prioritize them and then process some request(s) from the top of the queue (that is, the requests that have done the most PoW effort). -We thus require a new cell processing flow that is *not* compatible with current tor design. The elements are: +We thus require a new request processing flow that is *not* compatible with current tor design. The elements are: -- Validate PoW and place cells in a priority queue of INTRODUCE2 cells ([the introduction queue](./common-protocol.md#intro-queue)). -- Defer "bottom half" INTRO2 cell processing for after cells have been queued into the priority queue. +- Validate PoW and place requests in a priority queue of introduction requests ([the introduction queue](./common-protocol.md#intro-queue)). +- Defer "bottom half" request processing for after requests have been queued into the priority queue. ### Proposed scheduler {#tor-scheduler} The intuitive way to address the [queueing requirements](#tor-pow-queue) above would be to do this simple and naive approach: -1. Mainloop: Empty inbuf INTRODUCE2 cells into priority queue -2. Process all cells in pqueue +1. Mainloop: Empty inbuf of introduction requests into priority queue +2. Process all requests in pqueue 3. Goto (1) -However, we are worried that handling all those cells before returning to the mainloop opens possibilities of attack by an adversary since the priority queue is not gonna be kept up to date while we process all those cells. +However, we are worried that handling all those requests before returning to the mainloop opens possibilities of attack by an adversary since the priority queue is not gonna be kept up to date while we process all those requests. This means that we might spend lots of time dealing with introductions that don't deserve it. We thus propose to split the INTRODUCE2 handling into two different steps: "top half" and "bottom half" process. @@ -313,7 +313,7 @@ The top half process is responsible for queuing introductions into the priority 1. Unpack cell from inbuf to local buffer. 2. Decrypt cell (AES operations). -3. Parse INTRODUCE2 cell header and validate PoW. +3. Parse INTRODUCE2 message and validate PoW. 4. Return to mainloop event which essentially means step (1). The top-half basically does all operations from the [main loop](#tor-main-loop) section above, excepting (4). @@ -322,17 +322,17 @@ An then, the bottom-half process is responsible for handling introductions and d To achieve this we introduce a new mainloop event to process the priority queue _after_ the top-half event has completed. This new event would do these operations sequentially: -1. Pop INTRODUCE2 cell from priority queue. -2. Parse and process INTRODUCE2 cell. +1. Pop INTRODUCE2 message from priority queue. +2. Parse and process INTRODUCE2 message. 3. End event and yield back to mainloop. #### Scheduling the bottom half process {#sched-bottom-half} The question now becomes: when should the "bottom half" event get triggered from the mainloop? -We propose that this event is scheduled in when the network I/O event queues at least 1 cell into the priority queue. Then, as long as it has a cell in the queue, it would re-schedule itself for immediate execution meaning at the next mainloop round, it would execute again. +We propose that this event is scheduled in when the network I/O event queues at least 1 request into the priority queue. Then, as long as it has a request in the queue, it would re-schedule itself for immediate execution meaning at the next mainloop round, it would execute again. -The idea is to try to empty the queue as fast as it can in order to provide a fast response time to an introduction request but always leave a chance for more cells to appear between cell processing by yielding back to the mainloop. +The idea is to try to empty the queue as fast as it can in order to provide a fast response time to an introduction request but always leave a chance for more requests to appear between request processing by yielding back to the mainloop. With this we are aiming to always have the most up-to-date version of the priority queue when we are completing introductions: this way we are prioritizing clients that spent a lot of time and effort completing their PoW. @@ -340,25 +340,25 @@ If the size of the queue drops to 0, it stops scheduling itself in order to not The network I/O event will re-schedule it in time. Notice that the proposed solution will make the service handle 1 single introduction request at every main loop event. -However, when we do performance measurements we might learn that it's preferable to bump the number of cells in the future from 1 to N where N <= 32. +However, when we do performance measurements we might learn that it's preferable to bump the number of requests in the future from 1 to N where N <= 32. ## Performance measurements -This section will detail the performance measurements we've done on `tor.git` for handling an INTRODUCE2 cell and then a discussion on how much more CPU time we can add (for PoW validation) before it badly degrades our performance. +This section will detail the performance measurements we've done on `tor.git` for handling an INTRODUCE2 message and then a discussion on how much more CPU time we can add (for PoW validation) before it badly degrades our performance. ### Tor measurements {#tor-measurements} -In this section we will derive measurement numbers for the "top half" and "bottom half" parts of handling an introduction cell. +In this section we will derive measurement numbers for the "top half" and "bottom half" parts of handling an introduction request. These measurements have been done on tor.git at commit `80031db32abebaf4d0a91c01db258fcdbd54a471`. -We've measured several set of actions of the INTRODUCE2 cell handling process on Intel(R) Xeon(R) CPU E5-2650 v4. +We've measured several set of actions of the INTRODUCE2 message handling process on Intel(R) Xeon(R) CPU E5-2650 v4. Our service was accessed by an array of clients that sent introduction requests for a period of 60 seconds. 1. Full Mainloop Event - We start by measuring the full time it takes for a mainloop event to process an inbuf containing INTRODUCE2 cells. The mainloop event processed 2.42 cells per invocation on average during our measurements. + We start by measuring the full time it takes for a mainloop event to process an inbuf containing INTRODUCE2 messages. The mainloop event processed 2.42 messages per invocation on average during our measurements. ```text Total measurements: 3279 @@ -367,7 +367,7 @@ Our service was accessed by an array of clients that sent introduction requests Mean: 13.43 msec - 3rd Q.: 16.20 msec - Max: 257.95 msec ``` -2. INTRODUCE2 cell processing (bottom-half) +2. INTRODUCE2 message processing (bottom-half) We also measured how much time the "bottom half" part of the process takes. That's the heavy part of processing an introduction request as seen in step (4) of the [main loop](#tor-main-loop) section above: @@ -382,9 +382,9 @@ Our service was accessed by an array of clients that sent introduction requests 3. Connection data read (top half) Now that we have the above pieces, we can use them to measure just the "top half" part of the procedure. - That's when bytes are taken from the connection inbound buffer and parsed into an INTRODUCE2 cell where basic validation is done. + That's when bytes are taken from the connection inbound buffer and parsed into an INTRODUCE2 message where basic validation is done. - There is an average of 2.42 INTRODUCE2 cells per mainloop event and so we divide that by the full mainloop event mean time to get the time for one cell. + There is an average of 2.42 INTRODUCE2 messages per mainloop event and so we divide that by the full mainloop event mean time to get the time for one message. From that we subtract the "bottom half" mean time to get how much the "top half" takes: ```text @@ -394,10 +394,10 @@ Our service was accessed by an array of clients that sent introduction requests Mean: 0.26 msec ``` -To summarize, during our measurements the average number of INTRODUCE2 cells a mainloop event processed is ~2.42 cells (7931 cells for 3279 mainloop invocations). +To summarize, during our measurements the average number of INTRODUCE2 messages a mainloop event processed is ~2.42 messages (7931 messages for 3279 mainloop invocations). -This means that, taking the mean of mainloop event times, it takes ~5.55msec (13.43/2.42) to completely process an INTRODUCE2 cell. -Then if we look deeper we see that the "top half" of INTRODUCE2 cell processing takes 0.26 msec in average, whereas the "bottom half" takes around 5.33 msec. +This means that, taking the mean of mainloop event times, it takes ~5.55msec (13.43/2.42) to completely process an INTRODUCE2 messages. +Then if we look deeper we see that the "top half" of INTRODUCE2 message processing takes 0.26 msec in average, whereas the "bottom half" takes around 5.33 msec. The heavyness of the "bottom half" is to be expected since that's where 95% of the total work takes place: in particular the rendezvous path selection and circuit launch. diff --git a/spec/hspow-spec/common-protocol.md b/spec/hspow-spec/common-protocol.md index e0910ac..cd98643 100644 --- a/spec/hspow-spec/common-protocol.md +++ b/spec/hspow-spec/common-protocol.md @@ -165,7 +165,7 @@ The first challenge in reacting to failure, in our case, is to even accurately a This proposal introduces a bunch of new ways where a legitimate client can fail to reach the onion service. Furthermore, there is currently no end-to-end way for the onion service to inform the client that the introduction failed. -The INTRO_ACK cell is not end-to-end (it's from the introduction point to the client) and hence it does not allow the service to inform the client that the rendezvous is never gonna occur. +The INTRODUCE_ACK message is not end-to-end (it's from the introduction point to the client) and hence it does not allow the service to inform the client that the rendezvous is never gonna occur. From the client's perspective there's no way to attribute this failure to the service itself rather than the introduction point, so error accounting is performed separately for each introduction-point. Prior mechanisms will discard an introduction point that's required too many retries. diff --git a/spec/hspow-spec/v1-equix.md b/spec/hspow-spec/v1-equix.md index 77b7f95..025af48 100644 --- a/spec/hspow-spec/v1-equix.md +++ b/spec/hspow-spec/v1-equix.md @@ -140,8 +140,8 @@ The specific choice of nonce is entirely up to the client, so parallelization ch ## Client sends its proof in an INTRO1 extension {#intro-ext} -Now that the client has an answer to the puzzle it's time to encode it into an INTRODUCE1 cell. -To do so the client adds an extension to the encrypted portion of the INTRODUCE1 cell by using the EXTENSIONS field. The encrypted portion of the INTRODUCE1 cell only gets read by the onion service and is ignored by the introduction point. +Now that the client has an answer to the puzzle it's time to encode it into an INTRODUCE1 message. +To do so the client adds an extension to the encrypted portion of the INTRODUCE1 message by using the EXTENSIONS field. The encrypted portion of the INTRODUCE1 message only gets read by the onion service and is ignored by the introduction point. This extension includes the chosen nonce and effort in full, as well as the actual Equi-X proof. Clients provide only the first 4 bytes of the seed, enough to disambiguate between multiple recent seeds offered by the service. @@ -154,7 +154,7 @@ When a service receives an INTRODUCE1 with the `PROOF_OF_WORK` extension, it sho If it's not enabled, the extension SHOULD BE ignored. If enabled, even if the suggested effort is currently zero, the service follows the procedure detailed in this section. -If the service requires the `PROOF_OF_WORK` extension but received an INTRODUCE1 cell without any embedded proof-of-work, the service SHOULD consider this cell as a zero-effort introduction for the purposes of the [priority queue](./common-protocol.md#intro-queue). +If the service requires the `PROOF_OF_WORK` extension but received an INTRODUCE1 message without any embedded proof-of-work, the service SHOULD consider this message as a zero-effort introduction for the purposes of the [priority queue](./common-protocol.md#intro-queue). To verify the client's proof-of-work the service MUST do the following steps: diff --git a/spec/padding-spec/circuit-level-padding.md b/spec/padding-spec/circuit-level-padding.md index 086d0f8..85f9137 100644 --- a/spec/padding-spec/circuit-level-padding.md +++ b/spec/padding-spec/circuit-level-padding.md @@ -14,7 +14,7 @@ rate limiting, and circuit application conditions have been added. At present, Tor uses this system to deploy two pairs of circuit padding machines, to obscure differences between the setup phase of client-side -onion service circuits, up to the first 10 cells. +onion service circuits, up to the first 10 relay cells. This specification covers only the resulting behavior of these padding machines, and thus does not cover the state machine implementation details or @@ -31,11 +31,11 @@ advertised as "Padding=2". Because circuit padding machines only become active at certain points in circuit lifetime, and because more than one padding machine may be active at -any given point in circuit lifetime, there is also a padding negotiation -cell and a negotiated response. These are relay commands 41 and 42, with -relay headers as per section 6.1 of tor-spec.txt. +any given point in circuit lifetime, there is also a PADDING_NEGOTIATE +message and a PADDING_NEGOTIATED message. These are relay commands 41 and 42 respectively, +with relay headers as per section 6.1 of tor-spec.txt. -The fields of the relay cell Data payload of a negotiate request are +The fields in the body of a PADDING_NEGOTIATE message are as follows: ```text @@ -61,14 +61,14 @@ as follows: When a client wants to start a circuit padding machine, it first checks that the desired destination hop advertises the appropriate subprotocol version for -that machine. It then sends a circpad_negotiate cell to that hop with +that machine. It then sends a PADDING_NEGOTIATE message to that hop with command=CIRCPAD_COMMAND_START, and machine_type=CIRCPAD_MACHINE_CIRC_SETUP (for the circ setup machine, the destination hop is the second hop in the circuit). The machine_ctr is the count of which machine instance this is on the circuit. It is used to disambiguate shutdown requests. -When a relay receives a circpad_negotiate cell, it checks that it supports -the requested machine, and sends a circpad_negotiated cell, which is formatted +When a relay receives a PADDING_NEGOTIATE message, it checks that it supports +the requested machine, and sends a PADDING_NEGOTIATED message, which is formatted in the data payload of a relay cell with command number 42 (see tor-spec.txt section 6.1), as follows: @@ -102,11 +102,12 @@ Clients MAY send padding cells towards the relay before receiving the circpad_negotiated response, to allow for outbound cover traffic before negotiation completes. -Clients MAY send another circpad_negotiate cell before receiving the +Clients MAY send another PADDING_NEGOTIATE message before receiving the circpad_negotiated response, to allow for rapid machine changes. -Relays MUST NOT send padding cells or circpad_negotiated cells, unless a -padding machine is active. Any padding-related cells that arrive at the client +Relays MUST NOT send padding cells or PADDING_NEGOTIATE messages unless a +padding machine is active. Any padding cells or padding-related messages +that arrive at the client from unexpected relay sources are protocol violations, and clients MAY immediately tear down such circuits to avoid side channel risk. @@ -138,7 +139,7 @@ surrounded in \[brackets\] are outgoing, the others are incoming): \[EXTEND2\] -> EXTENDED2 -> \[EXTEND2\] -> EXTENDED2 -> \[BEGIN\] -> CONNECTED When this is done, the client has established a 3-hop circuit and also opened -a stream to the other end. Usually after this comes a series of DATA cell that +a stream to the other end. Usually after this comes a series of DATA message that either fetches pages, establishes an SSL connection or fetches directory information: @@ -227,7 +228,7 @@ becomes: [EXTEND2] -> EXTENDED2 -> [EXTEND2] -> EXTENDED2 -> [EST_REND] -> REND_EST -> [PADDING_NEGOTIATE] -> [DROP] -> PADDING_NEGOTIATED -> DROP... - After which normal application DATA cells continue on the circuit. + After which normal application DATA-bearing cells continue on the circuit. ``` Hence this way we make rendezvous circuits look like general circuits up @@ -243,8 +244,8 @@ will look alike. ### Circuit setup machine overhead { #setup-overhead } For the intro circuit case, we see that the origin-side machine just sends a -single \[PADDING_NEGOTIATE\] cell, whereas the origin-side machine sends a -PADDING_NEGOTIATED cell and between 7 to 10 DROP cells. This means that the +single PADDING_NEGOTIATE message, whereas the origin-side machine sends a +PADDING_NEGOTIATED message and between 7 to 10 DROP cells. This means that the average overhead of this machine is 11 padding cells per introduction circuit. For the rend circuit case, this machine is quite light. Both sides send 2 diff --git a/spec/padding-spec/connection-level-padding.md b/spec/padding-spec/connection-level-padding.md index c2890d8..f3c0fb7 100644 --- a/spec/padding-spec/connection-level-padding.md +++ b/spec/padding-spec/connection-level-padding.md @@ -6,7 +6,7 @@ ## Background -Tor clients and relays make use of CELL_PADDING to reduce the resolution of +Tor clients and relays make use of PADDING to reduce the resolution of connection-level metadata retention by ISPs and surveillance infrastructure. Such metadata retention is implemented by Internet routers in the form of @@ -114,7 +114,7 @@ If another cell is sent for any reason before this timer expires, the timer is reset to a new random value. If the connection remains inactive until the timer expires, a -single CELL_PADDING cell will be sent on that connection (which will +single PADDING cell will be sent on that connection (which will also start a new timer). In this way, the connection will only be padded in a given direction in @@ -187,7 +187,7 @@ idle, so we expect the actual overhead to be much lower than this. ## Reducing or Disabling Padding via Negotiation { #negotiation } To allow mobile clients to either disable or reduce their padding overhead, -the CELL_PADDING_NEGOTIATE cell (tor-spec.txt section 7.2) may be sent from +the PADDING_NEGOTIATE cell (tor-spec.txt section 7.2) may be sent from clients to relays. This cell is used to instruct relays to cease sending padding. @@ -207,7 +207,7 @@ Tor connection down to 69KB per one-time-use Tor connection. For continual usage, the maximum overhead goes from 103 bytes/sec down to 46 bytes/sec. If a client opts to completely disable padding, it sends a -CELL_PADDING_NEGOTIATE to instruct the relay not to pad, and then does not +PADDING_NEGOTIATE to instruct the relay not to pad, and then does not send any further padding itself. Currently, clients negotiate padding only when a channel is created, @@ -216,9 +216,9 @@ accept padding negotiation messages at any time. If a client which previously negotiated reduced, or disabled, padding, and wishes to re-enable default padding (ie padding according to the consensus -parameters), it SHOULD send CELL_PADDING_NEGOTIATE START with zero in the +parameters), it SHOULD send PADDING_NEGOTIATE START with zero in the ito_low_ms and ito_high_ms fields. (It therefore SHOULD NOT copy the values -from its own established consensus into the CELL_PADDING_NEGOTIATE cell.) +from its own established consensus into the PADDING_NEGOTIATE cell.) This avoids the client needing to send updated padding negotiations if the consensus parameters should change. The recipient's clamping of the timing parameters will cause the recipient to use its notion of the consensus diff --git a/spec/padding-spec/overview.md b/spec/padding-spec/overview.md index 0abe739..594b9d4 100644 --- a/spec/padding-spec/overview.md +++ b/spec/padding-spec/overview.md @@ -5,16 +5,16 @@ Tor supports two classes of cover traffic: connection-level padding, and circuit-level padding. -Connection-level padding uses the CELL_PADDING cell command for cover -traffic, where as circuit-level padding uses the RELAY_COMMAND_DROP relay -command. CELL_PADDING is single-hop only and can be differentiated from +Connection-level padding uses the PADDING cell command for cover +traffic, where as circuit-level padding uses the DROP relay +command. PADDING cells are single-hop only and can be differentiated from normal traffic by Tor relays ("internal" observers), but not by entities monitoring Tor OR connections ("external" observers). -RELAY_COMMAND_DROP is multi-hop, and is not visible to intermediate Tor +DROP relay messages are multi-hop, and is not visible to intermediate Tor relays, because the relay command field is covered by circuit layer -encryption. Moreover, Tor's 'recognized' field allows RELAY_COMMAND_DROP -padding to be sent to any intermediate node in a circuit (as per Section +encryption. Moreover, Tor's 'recognized' field allows DROP messages +to be sent to any intermediate node in a circuit (as per Section 6.1 of tor-spec.txt). Tor uses both connection level and circuit level padding. Connection diff --git a/spec/param-spec.md b/spec/param-spec.md index d2bfff8..c66bb25 100644 --- a/spec/param-spec.md +++ b/spec/param-spec.md @@ -8,7 +8,8 @@ line of a directory consensus. ## Network protocol parameters {#network-protocol} "circwindow" -- the default package window that circuits should be -established with. It started out at 1000 cells, but some research +established with. It started out at 1000 DATA-bearing relay cells, +but some research indicates that a lower value would mean fewer cells in transit in the network at any given time. Min: 100, Max: 1000, Default: 1000 @@ -16,7 +17,7 @@ First-appeared: Tor 0.2.1.20 "UseOptimisticData" -- If set to zero, clients by default shouldn't try to send optimistic data to servers until they have received a -RELAY_CONNECTED cell. +CONNECTED message. Min: 0, Max: 1, Default: 1 First-appeared: 0.2.3.3-alpha Default was 0 before: 0.2.9.1-alpha @@ -37,7 +38,7 @@ Min: 25, Max: 95, Default: 60 First-appeared: 0.2.4 "ExtendByEd25519ID" -- If true, clients should include Ed25519 -identities for relays when generating EXTEND2 cells. +identities for relays when generating EXTEND2 messages. Min: 0. Max: 1. Default: 0. First-appeared: 0.3.0 @@ -61,7 +62,7 @@ First appeared: 0.4.5.1-alpha. ## Performance-tuning parameters {#performance-tuning} "CircuitPriorityHalflifeMsec" -- the halflife parameter used when -weighting which circuit will send the next cell. Obeyed by Tor +weighting which circuit will send the next relay cell. Obeyed by Tor 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter, but mishandled it badly.) @@ -83,13 +84,13 @@ First-appeared: Tor 0.2.2.11-alpha Removed-in: 0.2.2.16-alpha ``` -"NumNTorsPerTAP" -- When balancing ntor and TAP cells at relays, +"NumNTorsPerTAP" -- When balancing ntor and TAP requests at relays, how many ntor handshakes should we perform for each TAP handshake? Min: 1. Max: 100000. Default: 10. First-appeared: 0.2.4.17-rc "circ_max_cell_queue_size" -- This parameter determines the maximum -number of cells allowed per circuit queue. +number of relay cells allowed per circuit queue. Min: 1000. Max: 2147483647 (INT32_MAX). Default: 50000. First-appeared: 0.3.3.6-rc. @@ -201,7 +202,7 @@ previous onion key for an additional onion-key-grace-period-days days after it is replaced. (Introduced in 0.3.1.1-alpha; prior versions of tor hardcoded both of these values to 7 days.) -"AllowNonearlyExtend" -- If true, permit EXTEND cells that are not inside +"AllowNonearlyExtend" -- If true, permit EXTEND/EXTEND2 requests that are not inside RELAY_EARLY cells. Min: 0. Max: 1. Default: 0. First-appeared: 0.2.3.11-alpha @@ -267,7 +268,7 @@ First appeared: 0.4.7.5-alpha. ## V3 onion service parameters {#onion-service} "hs_intro_min_introduce2", "hs_intro_max_introduce2" -- -Minimum/maximum amount of INTRODUCE2 cells allowed per circuits +Minimum/maximum amount of INTRODUCE2 messages allowed per circuit before rotation (actual amount picked at random between these two values). Min: 0. Max: INT32_MAX. Defaults: 16384, 32768. @@ -389,18 +390,18 @@ rendezvous points for single hop clients. ## Padding-related parameters {#padding} "circpad_max_circ_queued_cells" -- The circuitpadding module will -stop sending more padding cells if more than this many cells are in +stop sending more padding relay cells if more than this many cells are in the circuit queue a given circuit. Min: 0. Max: 50000. Default 1000. First appeared: 0.4.0.3-alpha. -"circpad_global_allowed_cells" -- This is the number of padding cells +"circpad_global_allowed_cells" -- This is the number of padding relay cells that must be sent before the 'circpad_global_max_padding_percent' parameter is applied. Min: 0. Max: 65535. Default: 0 "circpad_global_max_padding_pct" -- This is the maximum ratio of -padding cells to total cells, specified as a percent. If the global +padding relay cells to total relay cells, specified as a percent. If the global ratio of padding cells to total cells across all circuits exceeds this percent value, no more padding is sent until the ratio becomes lower. 0 means no limit. diff --git a/spec/rend-spec/encrypting-user-data.md b/spec/rend-spec/encrypting-user-data.md index f3ce6f7..460f71e 100644 --- a/spec/rend-spec/encrypting-user-data.md +++ b/spec/rend-spec/encrypting-user-data.md @@ -3,7 +3,7 @@ # Encrypting data between client and host A successfully completed handshake, as embedded in the -INTRODUCE/RENDEZVOUS cells, gives the client and hidden service host +INTRODUCE/RENDEZVOUS messages, gives the client and hidden service host a shared set of keys Kf, Kb, Df, Db, which they use for sending end-to-end traffic encryption and authentication as in the regular Tor relay encryption protocol, applying encryption with these keys diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 8b841fc..cb7debf 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -37,7 +37,7 @@ the introduction request to the client. ### Extensible ESTABLISH_INTRO protocol {#EST_INTRO} When a hidden service is establishing a new introduction point, it -sends an ESTABLISH_INTRO cell with the following contents: +sends an ESTABLISH_INTRO message with the following contents: ```text AUTH_KEY_TYPE [1 byte] @@ -58,7 +58,7 @@ authentication key and the type of the MAC to use in HANDSHAKE_AUTH. Recognized types are: ```text - [00, 01] -- Reserved for legacy introduction cells; see + [00, 01] -- Reserved for legacy introduction messages; see [LEGACY_EST_INTRO below] [02] -- Ed25519; SHA3-256. ``` @@ -91,20 +91,23 @@ The following extensions are currently defined: [`DOS_PARAMS`]: #DOS_PARAMS The HANDSHAKE_AUTH field contains the MAC of all earlier fields in -the cell using as its key the shared per-circuit material ("KH") +the message using as its key the shared per-circuit material ("KH") generated during the circuit extension protocol; see tor-spec.txt section 5.2, "Setting circuit keys". It prevents replays of -ESTABLISH_INTRO cells. +ESTABLISH_INTRO messages. SIG_LEN is the length of the signature. -SIG is a signature, using AUTH_KEY, of all contents of the cell, up +SIG is a signature, using AUTH_KEY, of all contents of the message, up to but not including SIG_LEN and SIG. These contents are prefixed with the string "Tor establish-intro cell v1". -Upon receiving an ESTABLISH_INTRO cell, a Tor node first decodes the +> (Note that this string is _sic_; +> it predates our efforts to distinguish cells from relay messages.) + +Upon receiving an ESTABLISH_INTRO message, a Tor node first decodes the key and the signature, and checks the signature. The node must reject -the ESTABLISH_INTRO cell and destroy the circuit in these cases: +the ESTABLISH_INTRO message and destroy the circuit in these cases: ```text * If the key type is unrecognized @@ -119,7 +122,7 @@ the ESTABLISH_INTRO cell and destroy the circuit in these cases: ``` Otherwise, the node must associate the key with the circuit, for use -later in INTRODUCE1 cells. +later in INTRODUCE1 messages. @@ -182,7 +185,7 @@ and the introduction point should ignore the other parameter. If the burst is lower than the rate, the introduction point SHOULD ignore the extension. -> Using this extension extends the payload of the ESTABLISH_INTRO cell by 19 +> Using this extension extends the payload of the ESTABLISH_INTRO message by 19 > bytes bringing it from 134 bytes to 155 bytes. When this extension is not _sent_, @@ -206,11 +209,11 @@ Introduced in tor-0.4.2.1-alpha. > relay versions. It is included for historical reasons. Tor nodes should also support an older version of the ESTABLISH_INTRO -cell, first documented in rend-spec.txt. New hidden service hosts +message, first documented in rend-spec.txt. New hidden service hosts must use this format when establishing introduction points at older Tor nodes that do not support the format above in \[EST_INTRO\]. -In this older protocol, an ESTABLISH_INTRO cell contains: +In this older protocol, an ESTABLISH_INTRO message contains: ```text KEY_LEN [2 bytes] @@ -237,9 +240,9 @@ authentication keys. ### Acknowledging establishment of introduction point {#INTRO_ESTABLISHED} After setting up an introduction circuit, the introduction point reports its -status back to the hidden service host with an INTRO_ESTABLISHED cell. +status back to the hidden service host with an INTRO_ESTABLISHED message. -The INTRO_ESTABLISHED cell has the following contents: +The INTRO_ESTABLISHED message has the following contents: ```text N_EXTENSIONS [1 byte] @@ -249,8 +252,8 @@ The INTRO_ESTABLISHED cell has the following contents: EXT_FIELD [EXT_FIELD_LEN bytes] ``` -Older versions of Tor send back an empty INTRO_ESTABLISHED cell instead. -Services must accept an empty INTRO_ESTABLISHED cell from a legacy relay. +Older versions of Tor send back an empty INTRO_ESTABLISHED message instead. +Services must accept an empty INTRO_ESTABLISHED message from a legacy relay. \[The above paragraph is obsolete and refers to a workaround for now-obsolete Tor relay versions. It is included for historical reasons.\] @@ -259,7 +262,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2"></a> -## Sending an INTRODUCE1 cell to the introduction point {#SEND_INTRO1} +## Sending an INTRODUCE1 message to the introduction point {#SEND_INTRO1} In order to participate in the introduction protocol, a client must know the following: @@ -270,12 +273,12 @@ know the following: * The introduction encryption key for that introduction point. ``` -The client sends an INTRODUCE1 cell to the introduction point, +The client sends an INTRODUCE1 message to the introduction point, containing an identifier for the service, an identifier for the encryption key that the client intends to use, and an opaque blob to be relayed to the hidden service host. -In reply, the introduction point sends an INTRODUCE_ACK cell back to +In reply, the introduction point sends an INTRODUCE_ACK message back to the client, either informing it that its request has been delivered, or that its request will not succeed. @@ -289,15 +292,15 @@ either by extending its introduction circuit an additional hop, or by building a new introduction circuit. ```text - [TODO: specify what tor should do when receiving a malformed cell. Drop it? - Kill circuit? This goes for all possible cells.] + [TODO: specify what tor should do when receiving a malformed message. Drop it? + Kill circuit? This goes for all possible messages.] ``` <a id="rend-spec-v3.txt-3.2.1"></a> -### Extensible INTRODUCE1 cell format {#FMT_INTRO1} +### Extensible INTRODUCE1 message format {#FMT_INTRO1} -When a client is connecting to an introduction point, INTRODUCE1 cells +When a client is connecting to an introduction point, INTRODUCE1 messages should be of the form: ```text @@ -316,22 +319,22 @@ should be of the form: The `ENCRYPTED` field is described in the \[PROCESS_INTRO2\] section. AUTH_KEY_TYPE is defined as in \[EST_INTRO\]. Currently, the only value of -AUTH_KEY_TYPE for this cell is an Ed25519 public key \[02\]. +AUTH_KEY_TYPE for this message is an Ed25519 public key \[02\]. The LEGACY_KEY_ID field is used to distinguish between legacy and new style -INTRODUCE1 cells. In new style INTRODUCE1 cells, LEGACY_KEY_ID is 20 zero -bytes. Upon receiving an INTRODUCE1 cell, the introduction point checks the -LEGACY_KEY_ID field. If LEGACY_KEY_ID is non-zero, the INTRODUCE1 cell -should be handled as a legacy INTRODUCE1 cell by the intro point. +INTRODUCE1 messages. In new style INTRODUCE1 messages, LEGACY_KEY_ID is 20 zero +bytes. Upon receiving an INTRODUCE1 messages, the introduction point checks the +LEGACY_KEY_ID field. If LEGACY_KEY_ID is non-zero, the INTRODUCE1 message +should be handled as a legacy INTRODUCE1 message by the intro point. -Upon receiving a INTRODUCE1 cell, the introduction point checks +Upon receiving a INTRODUCE1 message, the introduction point checks whether AUTH_KEY matches the introduction point authentication key for an active introduction circuit. If so, the introduction point sends an -INTRODUCE2 cell with exactly the same contents to the service, and sends an +INTRODUCE2 message with exactly the same contents to the service, and sends an INTRODUCE_ACK response to the client. (Note that the introduction point does not "clean up" the -INTRODUCE1 cells that it retransmits. Specifically, it does not +INTRODUCE1 message that it retransmits. Specifically, it does not change the order or multiplicity of the extensions sent by the client.) @@ -347,7 +350,7 @@ An acceptable proof will raise the priority of this introduction request accordi This is for the [proof-of-work DoS mitigation](../dos-spec/overview.md#hs-intro-pow), described in depth by the [Proof of Work for onion service introduction](../hspow-spec/index.md) specification. If used, it needs to be encoded within the N_EXTENSIONS field of the -ESTABLISH_INTRO cell defined in the previous section. The content is +ESTABLISH_INTRO message defined in the previous section. The content is defined as follows: EXT_FIELD_TYPE: @@ -379,15 +382,15 @@ A correctly functioning client only submits solutions with a version and seed wh An extension with an unknown version or expired seed is suspicious and SHOULD result in introduction failure. This will increase the INTRODUCE1 payload size by 43 bytes since the extension type and length is 2 extra bytes, the N_EXTENSIONS field is always present and currently set to 0 and the EXT_FIELD is 41 bytes. -According to ticket #33650, INTRODUCE1 cells currently have more than 200 bytes available. +According to ticket #33650, INTRODUCE1 messages currently have more than 200 bytes available. Introduced in tor-0.4.8.1-alpha. <a id="rend-spec-v3.txt-3.2.2"></a> -### INTRODUCE_ACK cell format. {#INTRO_ACK} +### INTRODUCE_ACK message format. {#INTRO_ACK} -An INTRODUCE_ACK cell has the following fields: +An INTRODUCE_ACK message has the following fields: ```text STATUS [2 bytes] @@ -399,10 +402,10 @@ An INTRODUCE_ACK cell has the following fields: Recognized status values are: - [00 00] -- Success: cell relayed to hidden service host. + [00 00] -- Success: message relayed to hidden service host. [00 01] -- Failure: service ID not recognized [00 02] -- Bad message format - [00 03] -- Can't relay cell to service + [00 03] -- Can't relay message to service ``` The same rules for multiplicity, ordering, and handling unknown types @@ -410,21 +413,21 @@ apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.3"></a> -## Processing an INTRODUCE2 cell at the hidden service. {#PROCESS_INTRO2} +## Processing an INTRODUCE2 message at the hidden service. {#PROCESS_INTRO2} -Upon receiving an INTRODUCE2 cell, the hidden service host checks whether +Upon receiving an INTRODUCE2 message, the hidden service host checks whether the AUTH_KEY or LEGACY_KEY_ID field matches the keys for this introduction circuit. -The service host then checks whether it has received a cell with these +The service host then checks whether it has received a message with these contents or rendezvous cookie before. If it has, it silently drops it as a -replay. (It must maintain a replay cache for as long as it accepts cells +replay. (It must maintain a replay cache for as long as it accepts messages with the same encryption key. Note that the encryption format below should be non-malleable.) -If the cell is not a replay, it decrypts the ENCRYPTED field, +If the message is not a replay, it decrypts the ENCRYPTED field, establishes a shared key with the client, and authenticates the whole -contents of the cell as having been unmodified since they left the +contents of the message as having been unmodified since they left the client. There may be multiple ways of decrypting the ENCRYPTED field, depending on the chosen type of the encryption key. Requirements for an introduction handshake protocol are described in @@ -459,8 +462,8 @@ in \[BUILDING-BLOCKS\], the "TLS-over-TCP, IPv4" and "Legacy node identity" specifiers must be present. As of 0.4.1.1-alpha, clients include both IPv4 and IPv6 link specifiers -in INTRODUCE1 cells. All available addresses SHOULD be included in the -cell, regardless of the address that the client actually used to extend +in INTRODUCE1 messages. All available addresses SHOULD be included in the +message, regardless of the address that the client actually used to extend to the rendezvous point. The hidden service should handle invalid or unrecognised link specifiers @@ -491,7 +494,7 @@ proposal 340 and thus lower the number of bytes that can be contained in a single relay message.) Note also that current versions of Tor only pad the INTRODUCE2 message up to 246 bytes. -Upon receiving a well-formed INTRODUCE2 cell, the hidden service host +Upon receiving a well-formed INTRODUCE2 message, the hidden service host will have: ```text @@ -508,7 +511,7 @@ apply to the extension fields here as described \[EST_INTRO\] above. ### INTRODUCE1 Extensions The following sections details the currently supported or reserved extensions -of an `INTRODUCE1` cell. +of an `INTRODUCE1` message. #### Congestion Control @@ -558,7 +561,7 @@ effort is currently zero, the service follows the procedure detailed in prop327. If the service requires the PROOF_OF_WORK extension but received an INTRODUCE1 -cell without any embedded proof-of-work, the service SHOULD consider this cell +message without any embedded proof-of-work, the service SHOULD consider this message as a zero-effort introduction for the purposes of the priority queue (see section \[INTRO_QUEUE\] of prop327). @@ -577,17 +580,17 @@ point to the proposal.) ### Introduction handshake encryption requirements {#INTRO-HANDSHAKE-REQS} -When decoding the encrypted information in an INTRODUCE2 cell, a +When decoding the encrypted information in an INTRODUCE2 message, a hidden service host must be able to: ```text - * Decrypt additional information included in the INTRODUCE2 cell, + * Decrypt additional information included in the INTRODUCE2 message, to include the rendezvous token and the information needed to extend to the rendezvous point. * Establish a set of shared keys for use with the client. - * Authenticate that the cell has not been modified since the client + * Authenticate that the message has not been modified since the client generated it. ``` @@ -624,7 +627,7 @@ We also use the following tweak values: m_hsexpand = PROTOID | ":hs_key_expand" ``` -To make an INTRODUCE1 cell, the client must know a public encryption +To make an INTRODUCE1 message, the client must know a public encryption key B for the hidden service on this introduction circuit. The client generates a single-use keypair: @@ -639,14 +642,14 @@ and computes: ENC_KEY = hs_keys[0:S_KEY_LEN] MAC_KEY = hs_keys[S_KEY_LEN:S_KEY_LEN+MAC_KEY_LEN] - and sends, as the ENCRYPTED part of the INTRODUCE1 cell: + and sends, as the ENCRYPTED part of the INTRODUCE1 message: CLIENT_PK [PK_PUBKEY_LEN bytes] ENCRYPTED_DATA [Padded to length of plaintext] MAC [MAC_LEN bytes] ``` -Substituting those fields into the INTRODUCE1 cell body format +Substituting those fields into the INTRODUCE1 message body format described in \[FMT_INTRO1\] above, we have ```text @@ -672,14 +675,14 @@ Here, the encryption key plays the role of B in the regular ntor handshake, and the AUTH_KEY field plays the role of the node ID. The CLIENT_PK field is the public key X. The ENCRYPTED_DATA field is the message plaintext, encrypted with the symmetric key ENC_KEY. The -MAC field is a MAC of all of the cell from the AUTH_KEY through the +MAC field is a MAC of all of the message from the AUTH_KEY through the end of ENCRYPTED_DATA, using the MAC_KEY value as its key. To process this format, the hidden service checks PK_VALID(CLIENT_PK) as necessary, and then computes ENC_KEY and MAC_KEY as the client did above, except using EXP(CLIENT_PK,b) in the calculation of intro_secret_hs_input. The service host then checks whether the MAC is -correct. If it is invalid, it drops the cell. Otherwise, it computes +correct. If it is invalid, it drops the message. Otherwise, it computes the plaintext by decrypting ENCRYPTED_DATA. The hidden service host now completes the service side of the @@ -712,7 +715,7 @@ introduction point encryption key 'b' to compute: AUTH AUTH_INPUT_MAC [MAC_LEN bytes] ``` -These fields will be sent to the client in a RENDEZVOUS1 cell using the +These fields will be sent to the client in a RENDEZVOUS1 message using the HANDSHAKE_INFO element (see \[JOIN_REND\]). The hidden service host now also knows the keys generated by the @@ -743,7 +746,7 @@ prevent replays. We might also want to look for ways to limit the number of keys a user needs to have.) To authenticate with an Ed25519 private key, the user must include an -extension field in the encrypted part of the INTRODUCE1 cell with an +extension field in the encrypted part of the INTRODUCE1 message with an EXT_FIELD_TYPE type of \[02\] and the contents: ```text @@ -760,7 +763,7 @@ key instead?\] Signature is the signature, using Ed25519, of: "hidserv-userauth-ed25519" Nonce (same as above) Pubkey (same as above) - AUTH_KEY (As in the INTRODUCE1 cell) + AUTH_KEY (As in the INTRODUCE1 message) ``` The hidden service host checks this by seeing whether it recognizes @@ -768,7 +771,7 @@ and would accept a signature from the provided public key. If it would, then it checks whether the signature is correct. If it is, then the correct user has authenticated. -Replay prevention on the whole cell is sufficient to prevent replays +Replay prevention on the whole message is sufficient to prevent replays on the authentication. Users SHOULD NOT use the same public key with multiple hidden diff --git a/spec/rend-spec/overview.md b/spec/rend-spec/overview.md index 61aa55a..5ccddd4 100644 --- a/spec/rend-spec/overview.md +++ b/spec/rend-spec/overview.md @@ -151,7 +151,7 @@ value. In sections below, we need to transmit the locations and identities of Tor nodes. We do so in the link identification format used by -EXTEND2 cells in the Tor protocol. +EXTEND2 messages in the Tor protocol. ```text NSPEC (Number of link specifiers) [1 byte] @@ -183,9 +183,9 @@ server's public key. <a id="rend-spec-v3.txt-0.5"></a> -## Assigned relay cell types {#relay-cell-types} +## Assigned relay message types {#relay-cell-types} -These relay cell types are reserved for use in the hidden service +These relay message types are reserved for use in the hidden service protocol. 32 -- RELAY_COMMAND_ESTABLISH_INTRO @@ -232,13 +232,13 @@ protocol. 39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED Sent from rendezvous point to client; acknowledges - receipt of ESTABLISH_RENDEZVOUS cell. Discussed in + receipt of ESTABLISH_RENDEZVOUS message. Discussed in [EST_REND_POINT] 40 -- RELAY_COMMAND_INTRODUCE_ACK Sent from introduction point to client; acknowledges - receipt of INTRODUCE1 cell and reports success/failure. + receipt of INTRODUCE1 message and reports success/failure. Discussed in [INTRO_ACK] ``` diff --git a/spec/rend-spec/protocol-overview.md b/spec/rend-spec/protocol-overview.md index 10c67b9..a50b3d1 100644 --- a/spec/rend-spec/protocol-overview.md +++ b/spec/rend-spec/protocol-overview.md @@ -40,9 +40,10 @@ 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 send Tor RELAY cells -to the server. RELAY_BEGIN cells open streams to an external process -or processes configured by the server; RELAY_DATA cells are used to +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 +or processes configured by the server; RELAY_DATA messages are used to communicate data on those streams, and so forth. <a id="rend-spec-v3.txt-1.2"></a> @@ -330,7 +331,7 @@ Specifically, each authorized client possesses: - An ed25519 keypair which allows the client to compute signatures which prove to the hidden service that the client is authorized. These - signatures are inserted into the INTRODUCE1 cell, and without them the + signatures are inserted into the INTRODUCE1 message, and without them the introduction to the hidden service cannot be completed. See [INTRO-AUTH]. KP_hsc_intro_auth, KS_hsc_intro_auth. ``` diff --git a/spec/rend-spec/rendezvous-protocol.md b/spec/rend-spec/rendezvous-protocol.md index fbd79a1..2b14934 100644 --- a/spec/rend-spec/rendezvous-protocol.md +++ b/spec/rend-spec/rendezvous-protocol.md @@ -4,10 +4,10 @@ Before connecting to a hidden service, the client first builds a circuit to an arbitrarily chosen Tor node (known as the rendezvous -point), and sends an ESTABLISH_RENDEZVOUS cell. The hidden service -later connects to the same node and sends a RENDEZVOUS cell. Once +point), and sends an ESTABLISH_RENDEZVOUS message. The hidden service +later connects to the same node and sends a RENDEZVOUS message. Once this has occurred, the relay forwards the contents of the RENDEZVOUS -cell to the client, and joins the two circuits together. +message to the client, and joins the two circuits together. Single Onion Services attempt to build a non-anonymous single-hop circuit, but use an anonymous 3-hop circuit if: @@ -24,12 +24,12 @@ but use an anonymous 3-hop circuit if: ## Establishing a rendezvous point {#EST_REND_POINT} The client sends the rendezvous point a RELAY_COMMAND_ESTABLISH_RENDEZVOUS -cell containing a 20-byte value. +message containing a 20-byte value. RENDEZVOUS_COOKIE \[20 bytes\] Rendezvous points MUST ignore any extra bytes in an -ESTABLISH_RENDEZVOUS cell. (Older versions of Tor did not.) +ESTABLISH_RENDEZVOUS message. (Older versions of Tor did not.) The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by the client. The client SHOULD choose a new rendezvous cookie for @@ -37,12 +37,12 @@ each new connection attempt. If the rendezvous cookie is already in use on an existing circuit, the rendezvous point should reject it and destroy the circuit. -Upon receiving an ESTABLISH_RENDEZVOUS cell, the rendezvous point associates +Upon receiving an ESTABLISH_RENDEZVOUS message, the rendezvous point associates the cookie with the circuit on which it was sent. It replies to the client -with an empty RENDEZVOUS_ESTABLISHED cell to indicate success. Clients MUST -ignore any extra bytes in a RENDEZVOUS_ESTABLISHED cell. +with an empty RENDEZVOUS_ESTABLISHED message to indicate success. Clients MUST +ignore any extra bytes in a RENDEZVOUS_ESTABLISHED message. -The client MUST NOT use the circuit which sent the cell for any +The client MUST NOT use the circuit which sent the message for any purpose other than rendezvous with the given location-hidden service. The client should establish a rendezvous point BEFORE trying to @@ -53,7 +53,7 @@ connect to a hidden service. ## Joining to a rendezvous point {#JOIN_REND} To complete a rendezvous, the hidden service host builds a circuit to -the rendezvous point and sends a RENDEZVOUS1 cell containing: +the rendezvous point and sends a RENDEZVOUS1 message containing: ```text RENDEZVOUS_COOKIE [20 bytes] @@ -67,10 +67,10 @@ introduction (see \[PROCESS_INTRO2\]) and HANDSHAKE_INFO is defined in If the cookie matches the rendezvous cookie set on any not-yet-connected circuit on the rendezvous point, the rendezvous -point connects the two circuits, and sends a RENDEZVOUS2 cell to the -client containing the HANDSHAKE_INFO field of the RENDEZVOUS1 cell. +point connects the two circuits, and sends a RENDEZVOUS2 message to the +client containing the HANDSHAKE_INFO field of the RENDEZVOUS1 message. -Upon receiving the RENDEZVOUS2 cell, the client verifies that HANDSHAKE_INFO +Upon receiving the RENDEZVOUS2 message, the client verifies that HANDSHAKE_INFO correctly completes a handshake. To do so, the client parses SERVER_PK from HANDSHAKE_INFO and reverses the final operations of section \[NTOR-WITH-EXTRA-DATA\] as shown here: @@ -103,7 +103,7 @@ The first HASH_LEN bytes of K form the forward digest Df; the next HASH_LEN bytes form the backward digest Db; the next S_KEY_LEN bytes form Kf, and the final S_KEY_LEN bytes form Kb. Excess bytes from K are discarded. -Subsequently, the rendezvous point passes relay cells, unchanged, from each +Subsequently, the rendezvous point passes RELAY cells, unchanged, from each of the two circuits to the other. When Alice's OP sends RELAY cells along the circuit, it authenticates with Df, and encrypts them with the Kf, then with all of the keys for the ORs in Alice's side of the circuit; and when @@ -127,12 +127,12 @@ The behavior of ESTABLISH_RENDEZVOUS is unchanged from older versions of this protocol, except that relays should now ignore unexpected bytes at the end. -Old versions of Tor required that RENDEZVOUS cell payloads be exactly +Old versions of Tor required that RENDEZVOUS message payloads be exactly 168 bytes long. All shorter rendezvous payloads should be padded to this length with random bytes, to make them difficult to distinguish from older protocols at the rendezvous point. Relays older than 0.2.9.1 should not be used for rendezvous points by next generation onion services because they enforce too-strict length checks to -rendezvous cells. Hence the "HSRend" protocol from proposal#264 should be +RENDEZVOUS messages. Hence the "HSRend" protocol from proposal#264 should be used to select relays for rendezvous points. diff --git a/spec/rend-spec/text-vectors.md b/spec/rend-spec/text-vectors.md index ad3701b..eadaee2 100644 --- a/spec/rend-spec/text-vectors.md +++ b/spec/rend-spec/text-vectors.md @@ -23,7 +23,7 @@ G.1. Test vectors for hs-ntor / NTOR-WITH-EXTRA-DATA The client wants to make in INTRODUCE request. It generates the following header (everything before the ENCRYPTED portion) - of its INTRODUCE1 cell: + of its INTRODUCE1 message: H = 000000000000000000000000000000000000000002002034E171E4358E501BFF 21ED907E96AC6BFEF697C779D040BBAF49ACC30FC5D21F00 @@ -74,7 +74,7 @@ G.1. Test vectors for hs-ntor / NTOR-WITH-EXTRA-DATA D1A51B7554D8B3692D85AC587FB9E69DF990EFB776D8 ``` -Later the service receives that body in an INTRODUCE2 cell. It +Later the service receives that body in an INTRODUCE2 message. It processes it according to the hs-ntor handshake, and recovers the client's plaintext P. To continue the hs-ntor handshake, the service chooses a curve25519 keypair: @@ -93,7 +93,7 @@ the service chooses a curve25519 keypair: 83402B28CDFD48C8A530A5A3D7D578DB ``` -The service sends back Y | AUTH_INPUT_MAC in its RENDEZVOUS1 cell +The service sends back Y | AUTH_INPUT_MAC in its RENDEZVOUS1 message body. From these, the client finishes the handshake, validates AUTH_INPUT_MAC, and computes the same NTOR_KEY_SEED. diff --git a/spec/socks-extensions.md b/spec/socks-extensions.md index 25b3eab..6fbfff5 100644 --- a/spec/socks-extensions.md +++ b/spec/socks-extensions.md @@ -86,7 +86,7 @@ Tor 0.1.2.4-alpha added a new command value: "CONNECT_DIR" \[F2\]. In this case, Tor will open an encrypted direct TCP connection to the directory port of the Tor server specified by address:port (the port specified should be the ORPort of the server). It uses a one-hop tunnel -and a "BEGIN_DIR" relay cell to accomplish this secure connection. +and a "BEGIN_DIR" relay message to accomplish this secure connection. The F2 command value was removed in Tor 0.2.0.10-alpha in favor of a new use_begindir flag in edge_connection_t. diff --git a/spec/tor-spec/cell-packet-format.md b/spec/tor-spec/cell-packet-format.md index f21e4cb..8f2174d 100644 --- a/spec/tor-spec/cell-packet-format.md +++ b/spec/tor-spec/cell-packet-format.md @@ -176,7 +176,7 @@ with zero-valued bytes. Recipients MUST ignore padding bytes. -> [RELAY] and [RELAY_EARLY] cel payloads +> [RELAY] and [RELAY_EARLY] cell payloads > contain encrypted data, > and are always full > from the point of the view of the channel layer. diff --git a/spec/tor-spec/channels.md b/spec/tor-spec/channels.md index a649409..652b931 100644 --- a/spec/tor-spec/channels.md +++ b/spec/tor-spec/channels.md @@ -23,7 +23,7 @@ the responding relay will always prove cryptographic ownership of one or more [**relay identities**](./relay-keys.md), using a [handshake](./negotiating-channels.md) that combines TLS facilities -and a series of Tor messages. +and a series of Tor cells. <span id="does-initiator-authenticate"> As part of this handshake, @@ -55,8 +55,8 @@ ownership of those identities. > 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/EXTEND2 cell, the expected identity key is the one given in -> the cell.) +> EXTEND/EXTEND2 message, the expected identity key is the one given in +> the message.) <!-- TODO: Integrate that paragraph better, or put it in a better place. --> @@ -66,7 +66,7 @@ Opening a channel is multi-step process: a new TLS session with certain properties, and the responding relay checks and enforces those properties. 2. Both parties - exchange messages over this TLS session + exchange cells over this TLS session in order to establish their identity or identities. 3. Both parties verify that the identities that they received are the ones that they expected. diff --git a/spec/tor-spec/closing-streams.md b/spec/tor-spec/closing-streams.md index 265e9d1..6bbcaeb 100644 --- a/spec/tor-spec/closing-streams.md +++ b/spec/tor-spec/closing-streams.md @@ -3,13 +3,13 @@ # Closing streams{#closing-streams} When an anonymized TCP connection is closed, or an edge node -encounters error on any stream, it sends a 'RELAY_END' cell along the +encounters error on any stream, it sends a 'RELAY_END' message along the circuit (if possible) and closes the TCP connection immediately. If -an edge node receives a 'RELAY_END' cell for any stream, it closes +an edge node receives a 'RELAY_END' message for any stream, it closes the TCP connection completely, and sends nothing more along the circuit for that stream. -The payload of a RELAY_END cell begins with a single 'reason' byte to +The payload of a RELAY_END message begins with a single 'reason' byte to describe why the stream is closing. For some reasons, it contains additional data (depending on the reason.) The values are: @@ -62,13 +62,13 @@ have originated. Implementations SHOULD accept empty RELAY_END messages, and treat them as if they specified REASON_MISC. -Upon receiving a RELAY_END cell, the recipient may be sure that no further -cells will arrive on that stream, and can treat such cells as a protocol +Upon receiving a RELAY_END message, the recipient may be sure that no further +messages will arrive on that stream, and can treat such messages as a protocol violation. -After sending a RELAY_END cell, the sender needs to give the recipient -time to receive that cell. In the meantime, the sender SHOULD remember -how many cells of which types (CONNECTED, SENDME, DATA) that it would have +After sending a RELAY_END message, the sender needs to give the recipient +time to receive that message. In the meantime, the sender SHOULD remember +how many messages of which types (CONNECTED, SENDME, DATA) it would have accepted on that stream, and SHOULD kill the circuit if it receives more than permitted. @@ -85,16 +85,16 @@ onion router. A stream begins in the 'OPEN' state. Upon receiving a 'FIN' from the corresponding TCP connection, the edge node sends a 'RELAY_FIN' -cell along the circuit and changes its state to 'DONE_PACKAGING'. -Upon receiving a 'RELAY_FIN' cell, an edge node sends a 'FIN' to +message along the circuit and changes its state to 'DONE_PACKAGING'. +Upon receiving a 'RELAY_FIN' message, an edge node sends a 'FIN' to the corresponding TCP connection (e.g., by calling shutdown(SHUT_WR)) and changing its state to 'DONE_DELIVERING'. When a stream in already in 'DONE_DELIVERING' receives a 'FIN', it also sends a 'RELAY_FIN' along the circuit, and changes its state to 'CLOSED'. When a stream already in 'DONE_PACKAGING' receives a -'RELAY_FIN' cell, it sends a 'FIN' and changes its state to +'RELAY_FIN' message, it sends a 'FIN' and changes its state to 'CLOSED'. If an edge node encounters an error on any stream, it sends a -'RELAY_END' cell (if possible) and closes the stream immediately. +'RELAY_END' message (if possible) and closes the stream immediately. diff --git a/spec/tor-spec/create-created-cells.md b/spec/tor-spec/create-created-cells.md index 8975cca..95727d0 100644 --- a/spec/tor-spec/create-created-cells.md +++ b/spec/tor-spec/create-created-cells.md @@ -7,7 +7,7 @@ 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 [EXTEND and EXTENDED cells](#EXTEND) which instructs the last +relay message (see [EXTEND and EXTENDED messages](#EXTEND) 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 @@ -55,7 +55,7 @@ or The first format is equivalent to a CREATE2 cell with HTYPE of 'tap' and length of `TAP_C_HANDSHAKE_LEN`. The second format is a way to encapsulate new handshake types into the old CREATE cell format for -migration. See ["EXTEND and EXTENDED cells"](#EXTEND) below. Recognized HTAG values are: +migration. See ["EXTEND and EXTENDED messages"](#EXTEND) below. Recognized HTAG values are: | Value | Description | | ----- | ----------- | @@ -118,12 +118,12 @@ randomly chosen CircID values are all in use (today's Tor stops after 64). <a id="tor-spec.txt-5.1.2"></a> -## EXTEND and EXTENDED cells {#EXTEND} +## EXTEND and EXTENDED messagess {#EXTEND} To extend an existing circuit, the client sends an EXTEND or EXTEND2 -RELAY_EARLY cell to the last node in the circuit. +message, in a RELAY_EARLY cell, to the last node in the circuit. -An EXTEND2 cell's relay payload contains: +An EXTEND2 message's relay payload contains: | Field | Description | Size | | ----- | ----------- | ---- | @@ -155,7 +155,7 @@ For purposes of indistinguishability, implementations SHOULD send these link specifiers, if using them, in this order: \[00\], \[02\], \[03\], \[01\]. -The relay payload for an EXTEND relay cell consists of: +The relay payload for an EXTEND relay message consists of: | Field | Size | ----- | ---- @@ -186,32 +186,32 @@ different RSA identity, it SHOULD NOT attempt to make another connection: it should just fail and DESTROY the circuit. The client MAY include multiple IPv4 or IPv6 link specifiers in an -EXTEND cell; current OR implementations only consider the first +EXTEND message; current OR implementations only consider the first of each type. After checking relay identities, extending ORs generate a -CREATE/CREATE2 cell from the contents of the EXTEND/EXTEND2 cell. +CREATE/CREATE2 cell from the contents of the EXTEND/EXTEND2 message. See [Creating circuits](./creating-circuits.md#creating-circuits) for details. -The payload of an EXTENDED cell is the same as the payload of a +The payload of an EXTENDED message is the same as the payload of a CREATED cell. -The payload of an EXTENDED2 cell is the same as the payload of a +The payload of an EXTENDED2 message is the same as the payload of a CREATED2 cell. \[Support for EXTEND2/EXTENDED2 was added in Tor 0.2.4.8-alpha.\] Clients SHOULD use the EXTEND format whenever sending a TAP -handshake, and MUST use it whenever the EXTEND cell will be handled +handshake, and MUST use it whenever the EXTEND message will be handled by a node running a version of Tor too old to support EXTEND2. In other cases, clients SHOULD use EXTEND2. -When generating an EXTEND2 cell, clients SHOULD include the target's +When generating an EXTEND2 message, clients SHOULD include the target's Ed25519 identity whenever the target has one, and whenever the target supports LinkAuth subprotocol version "3". (See [LinkAuth](./subprotocol-versioning.md#link-auth)). -When encoding a non-TAP handshake in an EXTEND cell, clients SHOULD +When encoding a non-TAP handshake in an EXTEND message, clients SHOULD use the format with 'client handshake type tag'. <a id="tor-spec.txt-5.1.3"></a> @@ -244,7 +244,7 @@ to the server's onion key, giving a client handshake: | - Second part of `g^x` | `DH_LEN-(KP_ENC_LEN-KP_PAD_LEN-KEY_LEN)` bytes The payload for a CREATED cell, or the relay payload for an -EXTENDED cell, contains: +EXTENDED message, contains: | Field | Size | ----- | ---- diff --git a/spec/tor-spec/creating-circuits.md b/spec/tor-spec/creating-circuits.md index eb8de36..10e23b4 100644 --- a/spec/tor-spec/creating-circuits.md +++ b/spec/tor-spec/creating-circuits.md @@ -9,7 +9,7 @@ When creating a circuit through the network, the circuit creator * N MAY be 1 for non-anonymous directory mirror, introduction point, or service rendezvous connections. * N SHOULD be 3 or more for anonymous connections. - Some end nodes accept streams (see ["Relay Cells"](./relay-cells.md#relay-cells)), + Some end nodes accept streams (see ["Opening streams"](./opening-streams.md)), others are introduction or rendezvous points (see the [Rendezvous Spec](../rend-spec/index.md)). 2. Choose a chain of (N-1) onion routers (R_1...R_N-1) to constitute @@ -34,35 +34,35 @@ these steps: 1. Create an onion skin, encrypted to R_M's public onion key. -2. Send the onion skin in a relay EXTEND/EXTEND2 cell along +2. Send the onion skin in a relay EXTEND/EXTEND2 message along the circuit (see - ["EXTEND and EXTENDED cells"](./create-created-cells.md#EXTEND) + ["EXTEND and EXTENDED messages"](./create-created-cells.md#EXTEND) and ["Routing relay cells"](./routing-relay-cells.md#routing-relay-cells)). -3. When a relay EXTENDED/EXTENDED2 cell is received, verify KH, +3. When a relay EXTENDED/EXTENDED2 message 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 +When an onion router receives an EXTEND relay message, it sends a CREATE cell to the next onion router, with the enclosed onion skin as its payload. -When an onion router receives an EXTEND2 relay cell, it sends a CREATE2 +When an onion router receives an EXTEND2 relay message, it sends a CREATE2 cell to the next onion router, with the enclosed HLEN, HTYPE, and HDATA as its payload. The initiating onion router chooses some circID not yet used on the connection between the two onion routers. (But see section ["Choosing circuit IDs in create cells"](./create-created-cells.md#choosing-circid)) -As special cases, if the EXTEND/EXTEND2 cell includes a legacy identity, or +As special cases, if the EXTEND/EXTEND2 message includes a legacy identity, or identity fingerprint of all zeroes, or asks to extend back to the relay that sent the extend cell, the circuit will fail and be torn down. -Ed25519 identity keys are not required in EXTEND2 cells, so all zero +Ed25519 identity keys are not required in EXTEND2 messages, so all zero keys SHOULD be accepted. If the extending relay knows the ed25519 key from the consensus, it SHOULD also check that key. (See -[EXTEND and EXTENDED cells](./create-created-cells.md#EXTEND)) +[EXTEND and EXTENDED message](./create-created-cells.md#EXTEND)) -If an EXTEND2 cell contains the ed25519 key of the relay that sent the -extend cell, the circuit will fail and be torn down. +If an EXTEND2 message contains the ed25519 key of the relay that sent the +EXTEND2 message, the circuit will fail and be torn down. When an onion router receives a CREATE/CREATE2 cell, if it already has a circuit on the given connection with the given circID, it drops the @@ -70,9 +70,9 @@ cell. Otherwise, after receiving the CREATE/CREATE2 cell, it completes the specified handshake, and replies with a CREATED/CREATED2 cell. Upon receiving a CREATED/CREATED2 cell, an onion router packs it payload -into an [EXTENDED/EXTENDED2](./create-created-cells.md#EXTEND) relay cell, and sends -that cell up the circuit. Upon receiving the EXTENDED/EXTENDED2 relay -cell, the OP can retrieve the handshake material. +into an [EXTENDED/EXTENDED2](./create-created-cells.md#EXTEND) relay message, and sends +that message up the circuit. Upon receiving the EXTENDED/EXTENDED2 relay +message, the OP can retrieve the handshake material. (As an optimization, OR implementations may delay processing onions until a break in traffic allows time to do so without harming diff --git a/spec/tor-spec/flow-control.md b/spec/tor-spec/flow-control.md index e0f7ad1..8c3bcce 100644 --- a/spec/tor-spec/flow-control.md +++ b/spec/tor-spec/flow-control.md @@ -33,13 +33,14 @@ information. See [proposal 111] for details. ## Link padding{#link-padding} 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 payloads of PADDING, VPADDING, or DROP -cells are filled with padding bytes. See [Cell Packet format](./cell-packet-format.md#cell-packet-format). +along the connection; relay messages of type "DROP" can be used for +long-range padding. The payloads of PADDING cells, VPADDING cells, or DROP +message are filled with padding bytes. +See [Cell Packet format](./cell-packet-format.md#cell-packet-format). If the link protocol is version 5 or higher, link level padding is enabled as per padding-spec.txt. On these connections, clients may -negotiate the use of padding with a CELL_PADDING_NEGOTIATE command +negotiate the use of padding with a PADDING_NEGOTIATE command whose format is as follows: ```text @@ -69,58 +70,70 @@ For more details on padding behavior, see padding-spec.txt. ## Circuit-level flow control To control a circuit's bandwidth usage, each OR keeps track of two -'windows', consisting of how many RELAY_DATA cells it is allowed to +'windows', consisting of how many DATA-bearing relay cells it is allowed to originate or willing to consume. +(For the purposes of flow control, +we call a relay cell "DATA-bearing" +if it holds a DATA relay message. +Note that this design does _not_ limit relay cells that don't contain +a DATA message; +this limitation may be addressed in the future.) + These two windows are respectively named: the package window (packaged for transmission) and the deliver window (delivered for local streams). Because of our leaky-pipe topology, every relay on the circuit has a pair of windows, and the OP has a pair of windows for every relay on the -circuit. These windows do not apply to relayed cells, however, and a relay -that is never used for streams will never decrement its window or cause the +circuit. +These windows apply only to _originated_ and _consumed_ cells. +They do not, however, apply to _relayed_ cells, +and a relay +that is never used for streams will never decrement its windows or cause the client to decrement a window. Each 'window' value is initially set based on the consensus parameter -'circwindow' in the directory (see dir-spec.txt), or to 1000 data cells if +'circwindow' in the directory (see dir-spec.txt), or to 1000 +DATA-bearing relay cells if no 'circwindow' value is given. In each direction, cells that are not RELAY_DATA cells do not affect the window. -An OR or OP (depending on the stream direction) sends a RELAY_SENDME cell -to indicate that it is willing to receive more cells when its deliver +An OR or OP (depending on the stream direction) sends a RELAY_SENDME message +to indicate that it is willing to receive more DATA-bearing cells when its deliver window goes down below a full increment (100). For example, if the window started at 1000, it should send a RELAY_SENDME when it reaches 900. When an OR or OP receives a RELAY_SENDME, it increments its package window by a value of 100 (circuit window increment) and proceeds to sending the -remaining RELAY_DATA cells. +remaining DATA-bearing cells. If a package window reaches 0, the OR or OP stops reading from TCP connections for all streams on the corresponding circuit, and sends no more -RELAY_DATA cells until receiving a RELAY_SENDME cell. +DATA-bearing cells until receiving a RELAY_SENDME message. If a deliver window goes below 0, the circuit should be torn down. Starting with tor-0.4.1.1-alpha, authenticated SENDMEs are supported (version 1, see below). This means that both the OR and OP need to remember -the rolling digest of the cell that precedes (triggers) a RELAY_SENDME. +the rolling digest of the relay cell that precedes (triggers) a RELAY_SENDME. This can be known if the package window gets to a multiple of the circuit window increment (100). When the RELAY_SENDME version 1 arrives, it will contain a digest that MUST match the one remembered. This represents a proof that the end point of the -circuit saw the sent cells. On failure to match, the circuit should be torn +circuit saw the sent relay cells. On failure to match, the circuit should be torn down. To ensure unpredictability, random bytes should be added to at least one -RELAY_DATA cell within one increment window. In other word, every 100 cells -(increment), random bytes should be introduced in at least one cell. +RELAY_DATA cell within one increment window. In other word, +at every 100 data-bearing cells (increment), +random bytes should be introduced in at least one cell. <a id="tor-spec.txt-7.3.1"></a> -### SENDME Cell Format +### SENDME Message Format -A circuit-level RELAY_SENDME cell always has its StreamID=0. +A circuit-level RELAY_SENDME message always has its StreamID=0. An OR or OP must obey these two consensus parameters in order to know which version to emit and accept. @@ -151,11 +164,11 @@ DATA_LEN and how to handle it. The recognized values are: DIGEST \[20 bytes\] ```text - If the DATA_LEN value is less than 20 bytes, the cell should be + If the DATA_LEN value is less than 20 bytes, the message should be dropped and the circuit closed. If the value is more than 20 bytes, then the first 20 bytes should be read to get the DIGEST value. - The DIGEST is the rolling digest value from the RELAY_DATA cell that + The DIGEST is the rolling digest value from the DATA-bearing relay cell that immediately preceded (triggered) this RELAY_SENDME. This value is matched on the other side from the previous cell sent that the OR/OP must remember. @@ -173,13 +186,14 @@ from the consensus), the circuit should be torn down. ## Stream-level flow control -Edge nodes use RELAY_SENDME cells to implement end-to-end flow +Edge nodes use RELAY_SENDME messages to implement end-to-end flow control for individual connections across circuits. Similarly to -circuit-level flow control, edge nodes begin with a window of cells +circuit-level flow control, edge nodes begin with a window of +DATA-bearing cells (500) per stream, and increment the window by a fixed value (50) -upon receiving a RELAY_SENDME cell. Edge nodes initiate RELAY_SENDME -cells when both a) the window is \<= 450, and b) there are less than +upon receiving a RELAY_SENDME message. Edge nodes initiate RELAY_SENDME +messages when both a) the window is \<= 450, and b) there are less than ten cell payloads remaining to be flushed at that edge. -Stream-level RELAY_SENDME cells are distinguished by having nonzero +Stream-level RELAY_SENDME messages are distinguished by having nonzero StreamID. They are still empty; the body still SHOULD be ignored. diff --git a/spec/tor-spec/negotiating-channels.md b/spec/tor-spec/negotiating-channels.md index b428594..4c1ae1c 100644 --- a/spec/tor-spec/negotiating-channels.md +++ b/spec/tor-spec/negotiating-channels.md @@ -103,11 +103,11 @@ The payload in a VERSIONS cell is a series of big-endian two-byte integers. Both parties MUST select as the link protocol version the highest number contained both in the VERSIONS cell they sent and in the -versions cell they received. +VERSIONS cell they received. If they have no such version in common, they cannot communicate and MUST close the connection. Either party MUST -close the connection if the versions cell is not well-formed (for example, +close the connection if the VERSIONS cell is not well-formed (for example, if the payload contains an odd number of bytes). Any VERSIONS cells sent after the first VERSIONS cell MUST be ignored. diff --git a/spec/tor-spec/obsolete-channels.md b/spec/tor-spec/obsolete-channels.md index 52e716f..0bd47f8 100644 --- a/spec/tor-spec/obsolete-channels.md +++ b/spec/tor-spec/obsolete-channels.md @@ -259,7 +259,7 @@ except as follows: of all the previous fields (that is, `TYPE` through `RAND`), using the initiator's `KS_legacy_linkauth_rsa`. - This field extends through the end of the Authenticate message. + This field extends through the end of the AUTHENTICATE cell. [Random bytes]: ./preliminaries.md#random-values [Ed25519-SHA256-RFC5705]: ./negotiating-channels.md#Ed25519-SHA256-RFC5705 diff --git a/spec/tor-spec/opening-streams.md b/spec/tor-spec/opening-streams.md index 799b4dc..8e63a62 100644 --- a/spec/tor-spec/opening-streams.md +++ b/spec/tor-spec/opening-streams.md @@ -7,7 +7,7 @@ To open a new anonymized TCP connection, the OP chooses an open circuit to an exit that may be able to connect to the destination address, selects an arbitrary StreamID not yet used on that circuit, -and constructs a RELAY_BEGIN cell with a payload encoding the address +and constructs a RELAY_BEGIN message with a payload encoding the address and port of the destination host. The payload format is: ```text @@ -48,12 +48,12 @@ FLAGS, FLAGS is omitted from the message payload. MUST ignore them. ``` -Upon receiving this cell, the exit node resolves the address as +Upon receiving this message, the exit node resolves the address as necessary, and opens a new TCP connection to the target port. If the address cannot be resolved, or a connection can't be established, the -exit node replies with a RELAY_END cell. (See +exit node replies with a RELAY_END message. (See ["Closing streams"](./closing-streams.md#closing-streams).) -Otherwise, the exit node replies with a RELAY_CONNECTED cell, whose +Otherwise, the exit node replies with a RELAY_CONNECTED message, whose payload is in one of the following formats: ```text @@ -88,35 +88,35 @@ attacks.\] ## Transmitting data {#transmitting} Once a connection has been established, the OP and exit node -package stream data in RELAY_DATA cells, and upon receiving such -cells, echo their contents to the corresponding TCP stream. +package stream data in RELAY_DATA message, and upon receiving such +messages, echo their contents to the corresponding TCP stream. If the exit node does not support optimistic data (i.e. its version number is before 0.2.3.1-alpha), then the OP MUST wait -for a RELAY_CONNECTED cell before sending any data. If the exit +for a RELAY_CONNECTED message before sending any data. If the exit node supports optimistic data (i.e. its version number is -0.2.3.1-alpha or later), then the OP MAY send RELAY_DATA cells -immediately after sending the RELAY_BEGIN cell (and before -receiving either a RELAY_CONNECTED or RELAY_END cell). +0.2.3.1-alpha or later), then the OP MAY send RELAY_DATA messages +immediately after sending the RELAY_BEGIN message (and before +receiving either a RELAY_CONNECTED or RELAY_END message). -RELAY_DATA cells sent to unrecognized streams are dropped. If -the exit node supports optimistic data, then RELAY_DATA cells it +RELAY_DATA messages sent to unrecognized streams are dropped. If +the exit node supports optimistic data, then RELAY_DATA messages it receives on streams which have seen RELAY_BEGIN but have not yet been replied to with a RELAY_CONNECTED or RELAY_END are queued. If the stream creation succeeds with a RELAY_CONNECTED, the queue is processed immediately afterwards; if the stream creation fails with a RELAY_END, the contents of the queue are deleted. -Relay RELAY_DROP cells are long-range dummies; upon receiving such -a cell, the OR or OP must drop it. +Relay RELAY_DROP messages are long-range dummies; upon receiving such +a message, the OR or OP must drop it. <a id="tor-spec.txt-6.2.1"></a> ## Opening a directory stream If a Tor relay is a directory server, it should respond to a -RELAY_BEGIN_DIR cell as if it had received a BEGIN cell requesting a -connection to its directory port. RELAY_BEGIN_DIR cells ignore exit +RELAY_BEGIN_DIR message as if it had received a BEGIN message requesting a +connection to its directory port. RELAY_BEGIN_DIR message ignore exit policy, since the stream is local to the Tor process. Directory servers may be: @@ -127,14 +127,14 @@ Directory servers may be: - onion service directories (RELAY_BEGIN_DIR, anonymous). If the Tor relay is not running a directory service, it should respond -with a REASON_NOTDIRECTORY RELAY_END cell. +with a REASON_NOTDIRECTORY RELAY_END message. -Clients MUST generate an all-zero payload for RELAY_BEGIN_DIR cells, +Clients MUST generate an all-zero payload for RELAY_BEGIN_DIR message, and relays MUST ignore the payload. -In response to a RELAY_BEGIN_DIR cell, relays respond either with a -RELAY_CONNECTED cell on success, or a RELAY_END cell on failure. They -MUST send a RELAY_CONNECTED cell all-zero payload, and clients MUST ignore +In response to a RELAY_BEGIN_DIR message, relays respond either with a +RELAY_CONNECTED message on success, or a RELAY_END message on failure. They +MUST send a RELAY_CONNECTED message all-zero payload, and clients MUST ignore the payload. \[RELAY_BEGIN_DIR was not supported before Tor 0.1.2.2-alpha; clients diff --git a/spec/tor-spec/relay-cells.md b/spec/tor-spec/relay-cells.md index 5de6d90..346899b 100644 --- a/spec/tor-spec/relay-cells.md +++ b/spec/tor-spec/relay-cells.md @@ -1,9 +1,9 @@ <a id="tor-spec.txt-6.1"></a> -# Relay cells{#relay-cells} +# Relay cells {#relay-cells} Within a circuit, the OP and the end node use the contents of -RELAY packets to tunnel end-to-end commands and TCP connections +relay cells to tunnel end-to-end commands and TCP connections ("Streams") across circuits. End-to-end commands can be initiated by either edge; streams are initiated by the OP. @@ -13,7 +13,8 @@ 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: +The payload of each unencrypted relay cell consists of an +enveloped relay message, encoded as follows: | Field | Size | ----- | ---- @@ -25,6 +26,10 @@ The payload of each unencrypted RELAY cell consists of: | Data | Length bytes | Padding | PAYLOAD_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 +> the relay cell, and which are the enveloped message. + The relay commands are: | Command | Identifier | Direction | Control? @@ -78,7 +83,7 @@ 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 payload (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" @@ -91,9 +96,9 @@ include forwarded data. Therefore if 'recognized' is zero but the digest does not match, the running digest at that node should not be updated, and the cell should be forwarded on.) -All RELAY cells pertaining to the same tunneled stream have the same +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 cells that affect the +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 cells. (Sendme cells are marked as "sometimes control" because they @@ -117,7 +122,7 @@ then they should all be filled with zero.</span> Implementations MUST NOT rely on the contents of the 'Padding' field. -If the RELAY cell is recognized but the relay command is not +If the relay cell is recognized but the relay command is not understood, the cell must be dropped and ignored. Its contents still count with respect to the digests and flow control windows, though. @@ -129,7 +134,7 @@ The 'Digest' field itself serves the purpose to check if a cell has been fully decrypted, that is, all onion layers have been removed. Having a single field, namely 'Recognized' is not sufficient, as outlined above. -When ENCRYPTING a RELAY cell, an implementation does the following: +When ENCRYPTING a relay cell, an implementation does the following: ```text # Encode the cell in binary (recognized and digest set to zero) @@ -147,7 +152,7 @@ encoded = cmd + [0, 0] + stream_id + digest[0..4] + length + data + # Now we can encrypt the cell by adding the onion layers ... ``` - When DECRYPTING a RELAY cell, an implementation does the following: + When DECRYPTING a relay cell, an implementation does the following: ```text decrypted = decrypt(cell) diff --git a/spec/tor-spec/relay-early.md b/spec/tor-spec/relay-early.md index 1843253..fd7dbf4 100644 --- a/spec/tor-spec/relay-early.md +++ b/spec/tor-spec/relay-early.md @@ -1,6 +1,6 @@ <a id="tor-spec.txt-5.6"></a> -# Handling relay_early cells{#handling-relay-early-cells} +# Handling RELAY_EARLY cells{#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 @@ -12,8 +12,8 @@ outbound circuit, it SHOULD close the circuit. If it receives any inbound RELAY_EARLY cells, it MUST close the circuit immediately. When speaking v2 of the link protocol or later, clients MUST only send -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 +EXTEND/EXTEND2 message 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 diff --git a/spec/tor-spec/remote-hostname-lookup.md b/spec/tor-spec/remote-hostname-lookup.md index 8482660..2793411 100644 --- a/spec/tor-spec/remote-hostname-lookup.md +++ b/spec/tor-spec/remote-hostname-lookup.md @@ -3,10 +3,10 @@ # Remote hostname lookup To find the address associated with a hostname, the OP sends a -RELAY_RESOLVE cell containing the hostname to be resolved with a NUL +RELAY_RESOLVE message containing the hostname to be resolved with a NUL terminating byte. (For a reverse lookup, the OP sends a RELAY_RESOLVE -cell containing an in-addr.arpa address.) The OR replies with a -RELAY_RESOLVED cell containing any number of answers. Each answer is +message containing an in-addr.arpa address.) The OR replies with a +RELAY_RESOLVED message containing any number of answers. Each answer is of the form: ```text @@ -37,7 +37,7 @@ of the form: For backward compatibility, if there are any IPv4 answers, one of those must be given as the first answer. - The RELAY_RESOLVE cell must use a nonzero, distinct streamID; the - corresponding RELAY_RESOLVED cell must use the same streamID. No stream + The RELAY_RESOLVE messge must use a nonzero, distinct streamID; the + corresponding RELAY_RESOLVED message must use the same streamID. No stream is actually created by the OR when resolving the name. ``` diff --git a/spec/tor-spec/routing-relay-cells.md b/spec/tor-spec/routing-relay-cells.md index abe9828..a9e3c49 100644 --- a/spec/tor-spec/routing-relay-cells.md +++ b/spec/tor-spec/routing-relay-cells.md @@ -14,6 +14,9 @@ When a node 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 node drops the cell. +> Here and elsewhere, we refer to RELAY and RELAY_EARLY cells +> collectively as "relay cells". + <a id="tor-spec.txt-5.5.2"></a> ## Forward Direction diff --git a/spec/tor-spec/streams.md b/spec/tor-spec/streams.md index 1aa5491..4d96048 100644 --- a/spec/tor-spec/streams.md +++ b/spec/tor-spec/streams.md @@ -2,6 +2,6 @@ # Application connections and stream management{#application-connections-and-stream-management} -This section describes how clients use RELAY cells to communicate with +This section describes how clients use relay messages to communicate with exit nodes, and how use this communication channel to send and receive application data. diff --git a/spec/tor-spec/subprotocol-versioning.md b/spec/tor-spec/subprotocol-versioning.md index b8ce11d..5f43c71 100644 --- a/spec/tor-spec/subprotocol-versioning.md +++ b/spec/tor-spec/subprotocol-versioning.md @@ -78,7 +78,7 @@ support "1-5". Eventually we will drop "1" and "2". ## "LinkAuth" {#link-auth} -LinkAuth protocols correspond to varieties of Authenticate cells used for +LinkAuth protocols correspond to varieties of AUTHENTICATE cells used for the v3+ link protocols. Current versions are: @@ -94,7 +94,7 @@ Current versions are: ## "Relay" The "relay" protocols are those used to handle CREATE/CREATE2 -cells, and those that handle the various RELAY cell types received +cells, and those that handle the various relay messages 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.) @@ -111,9 +111,9 @@ Current versions are as follows. Relay=2 has limited IPv6 support: - * Clients might not include IPv6 ORPorts in EXTEND2 cells. + * Clients might not include IPv6 ORPorts in EXTEND2 messages. * Relays (and bridges) might not initiate IPv6 connections in - response to EXTEND2 cells containing IPv6 ORPorts, even if they + response to EXTEND2 messages containing IPv6 ORPorts, even if they are configured with an IPv6 ORPort. However, relays support accepting inbound connections to their IPv6 @@ -121,7 +121,7 @@ Current versions are as follows. connections to other relays. * "3" -- relays support extending over IPv6 connections in response to an - EXTEND2 cell containing an IPv6 ORPort. + EXTEND2 message containing an IPv6 ORPort. Bridges might not extend over IPv6, because they try to imitate client behaviour. @@ -129,14 +129,14 @@ Current versions are as follows. A successful IPv6 extend requires: * Relay subprotocol version 3 (or later) on the extending relay, * an IPv6 ORPort on the extending relay, - * an IPv6 ORPort for the accepting relay in the EXTEND2 cell, and + * an IPv6 ORPort for the accepting relay in the EXTEND2 message, and * an IPv6 ORPort on the accepting relay. (Because different tor instances can have different views of the network, these checks should be done when the path is selected. Extending relays should only check local IPv6 information, before attempting the extend.) - When relays receive an EXTEND2 cell containing both an IPv4 and an + When relays receive an EXTEND2 message containing both an IPv4 and an IPv6 ORPort, and there is no existing authenticated connection with the target relay, the extending relay may choose between IPv4 and IPv6 at random. The extending relay might not try the other address, @@ -177,7 +177,7 @@ The "HSIntro" protocol handles introduction points. * "4" -- support ed25519 authentication keys which is defined by the HS v3 protocol as part of [proposal 224] in Tor 0.3.0.4-alpha. - * "5" -- support ESTABLISH_INTRO cell DoS parameters extension for onion + * "5" -- support ESTABLISH_INTRO message DoS parameters extension for onion service version 3 only in Tor 0.4.2.1-alpha. <a id="tor-spec.txt-9.5"></a> @@ -188,7 +188,7 @@ The "HSRend" protocol handles rendezvous points. * "1" -- supports all features in Tor 0.0.6. - * "2" -- supports RENDEZVOUS2 cells of arbitrary length as long as they + * "2" -- supports RENDEZVOUS2 messages of arbitrary length as long as they have 20 bytes of cookie in Tor 0.2.9.1-alpha. <a id="tor-spec.txt-9.6"></a> diff --git a/spec/tor-spec/tearing-down-circuits.md b/spec/tor-spec/tearing-down-circuits.md index 0609307..fadd1fc 100644 --- a/spec/tor-spec/tearing-down-circuits.md +++ b/spec/tor-spec/tearing-down-circuits.md @@ -39,18 +39,18 @@ down any associated edge connections (see [Calculating the 'Digest' field](./relay-cells.md#digest-field)). After a DESTROY cell has been processed, an OR ignores all data or -destroy cells for the corresponding circuit. +DESTROY cells for the corresponding circuit. -To tear down part of a circuit, the OP may send a RELAY_TRUNCATE cell +To tear down part of a circuit, the OP may send a RELAY_TRUNCATE message signaling a given OR (Stream ID zero). That OR sends a DESTROY cell to the next node in the circuit, and replies to the OP with a -RELAY_TRUNCATED cell. +RELAY_TRUNCATED message. -\[Note: If an OR receives a TRUNCATE cell and it has any RELAY cells +\[Note: If an OR receives a TRUNCATE message and it has any relay cells still queued on the circuit for the next node it will drop them without sending them. This is not considered conformant behavior, but it probably won't get fixed until a later version of Tor. Thus, -clients SHOULD NOT send a TRUNCATE cell to a node running any current +clients SHOULD NOT send a TRUNCATE message to a node running any current version of Tor if a) they have sent relay cells through that node, and b) they aren't sure whether those cells have been sent on yet.\] @@ -78,9 +78,9 @@ towards the client, not RELAY_TRUNCATED. behavior created queuing pressure on the intermediary ORs. ``` -The payload of a DESTROY and RELAY_TRUNCATED cell contains a single +The payload of a DESTROY cell or RELAY_TRUNCATED message contains a single octet, describing the reason that the circuit was -closed. RELAY_TRUNCATED cells, and DESTROY cells sent \_towards the +closed. RELAY_TRUNCATED message, and DESTROY cells sent \_towards the client, should contain the actual reason from the list of error codes below. Reasons in DESTROY cell SHOULD NOT be propagated downward or upward, due to potential side channel risk: An OR receiving a DESTROY |