diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-11-22 02:34:47 +0000 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-11-22 02:34:47 +0000 |
commit | 7e608a189b4e0c85764399d01f5edf0e8e96c385 (patch) | |
tree | b7a81557e65b4fdbaf3c6241c49c9870bd424389 /spec/rend-spec | |
parent | 5e8bded8de929dd0f34b21f5e9bbc7cca15270b3 (diff) | |
parent | b2dc43b1c552b42e66f53b530766972a98a1a3c5 (diff) | |
download | torspec-7e608a189b4e0c85764399d01f5edf0e8e96c385.tar.gz torspec-7e608a189b4e0c85764399d01f5edf0e8e96c385.zip |
Merge branch 'dos_params' into 'main'
Clarify and interlink EST_INTRO_DOS_EXT extension
See merge request tpo/core/torspec!229
Diffstat (limited to 'spec/rend-spec')
-rw-r--r-- | spec/rend-spec/introduction-protocol.md | 113 |
1 files changed, 65 insertions, 48 deletions
diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index dee054f..94b7145 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -82,6 +82,14 @@ unrecognized EXT_FIELD_TYPE values must be ignored. they may be overridden in the descriptions of individual extensions.) ``` +The following extensions are currently defined: + +| `EXT_FIELD_TYPE` | Name | +| ---------------- | -------------- | +| `[01]` | [`DOS_PARAMS`] | + +[`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") generated during the circuit extension protocol; see tor-spec.txt @@ -113,80 +121,89 @@ 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. + + <a id="rend-spec-v3.txt-3.1.1.1"></a> -#### Denial-of-Service defense extension {#EST_INTRO_DOS_EXT} +#### Denial-of-Service defense extension (DOS\_PARAMS) {#EST_INTRO_DOS_EXT} -This extension can be used to send Denial-of-Service (DoS) parameters to +<a id="DOS_PARAMS"></a> +The `DOS_PARAMS` extension +in ESTABLISH_INTRO +is used to send Denial-of-Service (DoS) parameters to the introduction point in order for it to apply them for the introduction circuit. This is for the [rate limiting DoS mitigation](../dos-spec/overview.md#hs-intro-rate) specifically. -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 -defined as follows: - -EXT_FIELD_TYPE: - -\[01\] -- Denial-of-Service Parameters. +The `EXT_FIELD_TYPE` value for the `DOS_PARAMS` extension is `[01]`. -```text - If this flag is set, the extension should be used by the introduction - point to learn what values the denial of service subsystem should be - using. +The content is defined as follows: - EXT_FIELD content format is: +| Field | Size | Description | +| ----------------- | ---- | -------------------- | +| `N_PARAMS` | 1 | Number of parameters | +| `N_PARAMS` times: | | | +| - PARAM_TYPE | 1 | Identifier for a parameter | +| - PARAM_VALUE | 8 | Integer value | - N_PARAMS [1 byte] - N_PARAMS times: - PARAM_TYPE [1 byte] - PARAM_VALUE [8 byte] +Recognized values for `PARAM_TYPE` in this extension are: - The PARAM_TYPE possible values are: +| `PARAM_TYPE` | Name | Min | Max | +| ----------- | -------------------------------- | --- | ---------- | +| `[01]` | [`DOS_INTRODUCE2_RATE_PER_SEC`] | 0 | 0x7fffffff | +| `[02]` | [`DOS_INTRODUCE2_BURST_PER_SEC`] | 0 | 0x7fffffff | - [01] -- DOS_INTRODUCE2_RATE_PER_SEC - The rate per second of INTRODUCE2 cell relayed to the - service. +[`DOS_INTRODUCE2_RATE_PER_SEC`]: #DOS_INTRODUCE2_RATE_PER_SEC +[`DOS_INTRODUCE2_BURST_PER_SEC`]: #DOS_INTRODUCE2_BURST_PER_SEC - [02] -- DOS_INTRODUCE2_BURST_PER_SEC - The burst per second of INTRODUCE2 cell relayed to the - service. +Together, these parameters configure a token bucket +that determines how many INTRODUCE2 messages +the introduction point may send to the service. - The PARAM_VALUE size is 8 bytes in order to accommodate 64bit values. - It MUST match the specified limit for the following PARAM_TYPE: +<span id="DOS_INTRODUCE2_RATE_PER_SEC"> +The `DOS_INTRODUCE2_RATE_PER_SEC` parameter defines the maximum +average rate of messages; +</span> +<span id="DOS_INTRODUCE2_BURST_PER_SEC"> +The `DOS_INTRODUCE2_BURST_PER_SEC` parameter defines the largest +allowable burst of messages +(that is, the size of the token bucket). +</span> - [01] -- Min: 0, Max: 2147483647 - [02] -- Min: 0, Max: 2147483647 +> Technically speaking, the `BURST` parameter is misnamed +> in that it is not actually "per second": +> only a _rate_ has an associated time. - A value of 0 means the defense is disabled. If the rate per second is - set to 0 (param 0x01) then the burst value should be ignored. And - vice-versa, if the burst value is 0 (param 0x02), then the rate value - should be ignored. In other words, setting one single parameter to 0 - disables the defense. +If either of these parameters is set to 0, +the defense is disabled, +and the introduction point should ignore the other parameter. - The burst can NOT be smaller than the rate. If so, the parameters - should be ignored by the introduction point. +If the burst is lower than the rate, +the introduction point SHOULD ignore the extension. - Any valid value does have precedence over the network wide consensus - parameter. -``` +> Using this extension extends the payload of the ESTABLISH_INTRO cell by 19 +> bytes bringing it from 134 bytes to 155 bytes. -Using this extension extends the payload of the ESTABLISH_INTRO cell by 19 -bytes bringing it from 134 bytes to 155 bytes. +When this extension is not _sent_, +introduction points use default settings +taken from taken from the consensus parameters +[HiddenServiceEnableIntroDoSDefense](../param-spec.md#HiddenServiceEnableIntroDoSDefense), +[HiddenServiceEnableIntroDoSRatePerSec](../param-spec.md#HiddenServiceEnableIntroDoSRatePerSec), +and +[HiddenServiceEnableIntroDoSBurstPerSec](../param-spec.md#HiddenServiceEnableIntroDoSBurstPerSec). This extension can only be used with relays supporting the protocol version -"HSIntro=5". +["HSIntro=5"](../tor-spec/subprotocol-versioning.md#HSIntro). Introduced in tor-0.4.2.1-alpha. -```text -3.1.2. Registering an introduction point on a legacy Tor node - [LEGACY_EST_INTRO] +<a id="rend-spec-v3.txt-3.1.2"></a> - [This section is obsolete and refers to a workaround for now-obsolete Tor - relay versions. It is included for historical reasons.] -``` +## Registering an introduction point on a legacy Tor node {#LEGACY_EST_INTRO} + +> This section is obsolete and refers to a workaround for now-obsolete Tor +> 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 |