From 60a3d2503ead69df27b05987df6ce5e4ce08ac05 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 15 Nov 2023 18:14:19 -0500 Subject: Clarify and interlink EST_INTRO_DOS_EXT extension --- spec/param-spec.md | 23 ++++++++++++++++++----- spec/rend-spec/introduction-protocol.md | 10 +++++++++- spec/tor-spec/subprotocol-versioning.md | 2 +- 3 files changed, 28 insertions(+), 7 deletions(-) diff --git a/spec/param-spec.md b/spec/param-spec.md index 088ee77..ee96dfd 100644 --- a/spec/param-spec.md +++ b/spec/param-spec.md @@ -305,22 +305,35 @@ 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). + +"HiddenServiceEnableIntroDoSDefense" -- This parameter makes +introduction points +start using a rate-limiting defense if they support it. +Introduction points use this value when no +[denial-of-service parameters extension] is sent. Min: 0. Max: 1. Default: 0. First appeared: 0.4.2.1-alpha. -"HiddenServiceEnableIntroDoSBurstPerSec" -- Maximum burst to be used + +"HiddenServiceEnableIntroDoSBurstPerSec" -- Default maximum burst +rate to be used for token bucket for the introduction point rate-limiting. +Introduction points use this value when no +[denial-of-service parameters extension] is sent. Min: 0. Max: INT32_MAX. Default: 200 First appeared: 0.4.2.1-alpha. -"HiddenServiceEnableIntroDoSRatePerSec" -- Refill rate to be used + +"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 +[denial-of-service parameters extension] is sent. Min: 0. Max: INT32_MAX. Default: 25 First appeared: 0.4.2.1-alpha. +[denial-of-service parameters extension]: ./rend-spec/introduction-protocol.md#EST_INTRO_DOS_EXT + ## Denial-of-service parameters {#dos} diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index dee054f..bdedef7 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -175,8 +175,16 @@ EXT_FIELD_TYPE: 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. 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. -## "HSIntro" +## "HSIntro" {#HSIntro} The "HSIntro" protocol handles introduction points. -- cgit v1.2.3-54-g00ecf From e8b55f1b2327960688b9b01699ed11cb224f4b14 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 16 Nov 2023 11:24:04 -0500 Subject: Revise the description of the DOS_PARAMS extension The changes: - The extension's name is now as given in C Tor and Arti. Previously it had no short name. - We use tables to describe the parameter's format. - We forward-reference the extension from a list of extensions. - We note that a burst is not "per second" but do not rename anything. - We include anchors for linking to the parameters. - We generally make the description more terse. - We repair a run-on section. --- spec/param-spec.md | 11 ++-- spec/rend-spec/introduction-protocol.md | 104 +++++++++++++++++--------------- 2 files changed, 64 insertions(+), 51 deletions(-) diff --git a/spec/param-spec.md b/spec/param-spec.md index ee96dfd..3ff4fb1 100644 --- a/spec/param-spec.md +++ b/spec/param-spec.md @@ -310,7 +310,7 @@ First-appeared: 0.3.3.0-alpha. introduction points start using a rate-limiting defense if they support it. Introduction points use this value when no -[denial-of-service parameters extension] is sent. +[`DOS_PARAMS` extension] is sent. Min: 0. Max: 1. Default: 0. First appeared: 0.4.2.1-alpha. @@ -319,20 +319,23 @@ First appeared: 0.4.2.1-alpha. rate to be used for token bucket for the introduction point rate-limiting. Introduction points use this value when no -[denial-of-service parameters extension] is sent. +[`DOS_PARAMS` extension] is sent. Min: 0. Max: INT32_MAX. Default: 200 First appeared: 0.4.2.1-alpha. +> Note that the above parameter is slightly misnamed: +> a burst is not meaningfully "per second". + "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 -[denial-of-service parameters extension] is sent. +[`DOS_PARAMS` extension] is sent. Min: 0. Max: INT32_MAX. Default: 25 First appeared: 0.4.2.1-alpha. -[denial-of-service parameters extension]: ./rend-spec/introduction-protocol.md#EST_INTRO_DOS_EXT +[`DOS_PARAMS` extension]: ./rend-spec/introduction-protocol.md#DOS_PARAMS diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index bdedef7..75e9a0d 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,67 +121,70 @@ 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. + + -#### 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 + +The `DOS_PARAMS` extension 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. +If used, it needs to be encoded within the `EXT_*` extension fields +of the +`ESTABLISH_INTRO` message defined in the previous section. -```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 `EXT_FIELD_TYPE` value for the `DOS_PARAMS` extension is `[01]`. - EXT_FIELD content format is: +The content is defined as follows: - N_PARAMS [1 byte] - N_PARAMS times: - PARAM_TYPE [1 byte] - PARAM_VALUE [8 byte] +| Field | Size | Description | +| ----------------- | ---- | -------------------- | +| `N_PARAMS` | 1 | Number of parameters | +| `N_PARAMS` times: | | | +| - PARAM_TYPE | 1 | Identifier for a parameter | +| - PARAM_VALUE | 8 | Integer value | - The PARAM_TYPE possible values are: +Recognized values for `PARAM_TYPE` in this extension are: - [01] -- DOS_INTRODUCE2_RATE_PER_SEC - The rate per second of INTRODUCE2 cell relayed to the - service. +| `PARAM_TYPE` | Name | Min | Max | +| ----------- | -------------------------------- | --- | ---------- | +| `[01]` | [`DOS_INTRODUCE2_RATE_PER_SEC`] | 0 | 0x7fffffff | +| `[02]` | [`DOS_INTRODUCE2_BURST_PER_SEC`] | 0 | 0x7fffffff | - [02] -- DOS_INTRODUCE2_BURST_PER_SEC - The burst 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 - The PARAM_VALUE size is 8 bytes in order to accommodate 64bit values. - It MUST match the specified limit for the following PARAM_TYPE: +Together, these parameters configure a token bucket +that determines how many INTRODUCE2 messages +the introduction point may send to the service. - [01] -- Min: 0, Max: 2147483647 - [02] -- Min: 0, Max: 2147483647 + +The `DOS_INTRODUCE2_RATE_PER_SEC` parameter defines the maximum +average rate of messages; + + +The `DOS_INTRODUCE2_BURST_PER_SEC` parameter defines the largest +allowable burst of messages +(that is, the size of the token bucket). + - 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. +> Technically speaking, the `BURST` is not actually "per second": +> only a _rate_ has an associated time. - The burst can NOT be smaller than the rate. If so, the parameters - should be ignored by the introduction point. +If either of these parameters is set to 0, +the defense is disabled, +and the introduction point should ignore the other parameter. - Any valid value does have precedence over the network wide consensus - 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 -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 @@ -188,13 +199,12 @@ This extension can only be used with relays supporting the protocol version Introduced in tor-0.4.2.1-alpha. -```text -3.1.2. 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.] -``` +## 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 -- cgit v1.2.3-54-g00ecf From e5231436e4c4bd396067419b8128e0dadab9b1dd Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 20 Nov 2023 15:40:59 +0000 Subject: Several DOS_PARAMS suggestions from @diziet --- spec/param-spec.md | 4 ++-- spec/rend-spec/introduction-protocol.md | 8 +++----- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/spec/param-spec.md b/spec/param-spec.md index 3ff4fb1..d2bfff8 100644 --- a/spec/param-spec.md +++ b/spec/param-spec.md @@ -310,7 +310,7 @@ First-appeared: 0.3.3.0-alpha. introduction points start using a rate-limiting defense if they support it. Introduction points use this value when no -[`DOS_PARAMS` extension] is sent. +[`DOS_PARAMS` extension] is sent in the ESTABLISH_INTRO message. Min: 0. Max: 1. Default: 0. First appeared: 0.4.2.1-alpha. @@ -319,7 +319,7 @@ First appeared: 0.4.2.1-alpha. 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. +[`DOS_PARAMS` extension] is sent in the ESTABLISH_INTRO message. Min: 0. Max: INT32_MAX. Default: 200 First appeared: 0.4.2.1-alpha. diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 75e9a0d..68118b4 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -128,16 +128,14 @@ later in INTRODUCE1 cells. #### Denial-of-Service defense extension (DOS\_PARAMS) {#EST_INTRO_DOS_EXT} -The `DOS_PARAMS` extension is used to send Denial-of-Service (DoS) parameters to +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 `EXT_*` extension fields -of the -`ESTABLISH_INTRO` message defined in the previous section. - The `EXT_FIELD_TYPE` value for the `DOS_PARAMS` extension is `[01]`. The content is defined as follows: -- cgit v1.2.3-54-g00ecf From b2dc43b1c552b42e66f53b530766972a98a1a3c5 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Mon, 20 Nov 2023 10:47:22 -0500 Subject: Tweak explanation of BURST_PER_SEC to use the word "_misnamed" --- spec/rend-spec/introduction-protocol.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md index 68118b4..94b7145 100644 --- a/spec/rend-spec/introduction-protocol.md +++ b/spec/rend-spec/introduction-protocol.md @@ -171,7 +171,8 @@ allowable burst of messages (that is, the size of the token bucket). -> Technically speaking, the `BURST` is not actually "per second": +> Technically speaking, the `BURST` parameter is misnamed +> in that it is not actually "per second": > only a _rate_ has an associated time. If either of these parameters is set to 0, -- cgit v1.2.3-54-g00ecf