Merge branch 'dos_params' into 'main'

Clarify and interlink EST_INTRO_DOS_EXT extension

See merge request tpo/core/torspec!229

3 files changed, 87 insertions, 54 deletions

diff --git a/spec/param-spec.md b/spec/param-spec.md
index 088ee77..d2bfff8 100644
--- a/spec/param-spec.md
+++ b/spec/param-spec.md
@@ -305,22 +305,38 @@ introduction.
 Min 1. Max 10. Default 2.
 First-appeared: 0.3.3.0-alpha.
 
-"HiddenServiceEnableIntroDoSDefense" -- This parameter makes tor
-start using this defense if the introduction point supports it
-(for protover HSIntro=5).
+<a id="HiddenServiceEnableIntroDoSDefense"></a>
+"HiddenServiceEnableIntroDoSDefense" -- This parameter makes
+introduction points
+start using a rate-limiting defense if they support it.
+Introduction points use this value when no
+[`DOS_PARAMS` extension] is sent in the ESTABLISH_INTRO message.
 Min: 0. Max: 1. Default: 0.
 First appeared: 0.4.2.1-alpha.
 
-"HiddenServiceEnableIntroDoSBurstPerSec" -- Maximum burst to be used
+<a id="HiddenServiceEnableIntroDoSBurstPerSec"></a>
+"HiddenServiceEnableIntroDoSBurstPerSec" -- Default maximum burst
+rate to be used
 for token bucket for the introduction point rate-limiting.
+Introduction points use this value when no
+[`DOS_PARAMS` extension] is sent in the ESTABLISH_INTRO message.
 Min: 0. Max: INT32_MAX. Default: 200
 First appeared: 0.4.2.1-alpha.
 
-"HiddenServiceEnableIntroDoSRatePerSec" -- Refill rate to be used
+> Note that the above parameter is slightly misnamed:
+> a burst is not meaningfully "per second".
+
+<a id="HiddenServiceEnableIntroDoSRatePerSec"></a>
+"HiddenServiceEnableIntroDoSRatePerSec" -- Default maximum rate per second
+to be used
 for token bucket for the introduction point rate-limiting.
+Introduction points use this value when no
+[`DOS_PARAMS` extension] is sent.
 Min: 0. Max: INT32_MAX. Default: 25
 First appeared: 0.4.2.1-alpha.
 
+[`DOS_PARAMS` extension]: ./rend-spec/introduction-protocol.md#DOS_PARAMS
+
 <a id="param-spec.txt-9"></a>
 
 ## Denial-of-service parameters {#dos}
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
diff --git a/spec/tor-spec/subprotocol-versioning.md b/spec/tor-spec/subprotocol-versioning.md
index 8d241cc..3e4cae3 100644
--- a/spec/tor-spec/subprotocol-versioning.md
+++ b/spec/tor-spec/subprotocol-versioning.md
@@ -168,7 +168,7 @@ Current versions are as follows.
 
 <a id="tor-spec.txt-9.4"></a>
 
-## "HSIntro"
+## "HSIntro" {#HSIntro}
 
 The "HSIntro" protocol handles introduction points.