Merge branch 'sready-main-patch-42060' into 'main'

Update param-spec.txt, document padding params from params-spec.txt

See merge request tpo/core/torspec!90

1 files changed, 67 insertions, 20 deletions

diff --git a/attic/text_formats/param-spec.txt b/attic/text_formats/param-spec.txt
index d8ea80b..af2da8c 100644
--- a/attic/text_formats/param-spec.txt
+++ b/attic/text_formats/param-spec.txt
@@ -1,4 +1,3 @@
-
                            Tor network parameters
 
 This file lists the recognized parameters that can appear on the "params"
@@ -368,27 +367,75 @@ Table of Contents
     Min: 0. Max: 50000. Default 1000.
     First appeared: 0.4.0.3-alpha.
 
-    "circpad_global_allowed_cells" -- DOCDOC
-
-    "circpad_global_max_padding_pct" -- DOCDOC
-
-    "circpad_padding_disabled" -- DOCDOC
-
-    "circpad_padding_reduced" -- DOCDOC
-
-    "nf_conntimeout_clients" -- DOCDOC
-
-    "nf_conntimeout_relays" -- DOCDOC
-
-    "nf_ito_high_reduced" -- DOCDOC
-
-    "nf_ito_low" -- DOCDOC
-
-    "nf_ito_low_reduced" -- DOCDOC
+    "circpad_global_allowed_cells" -- This is the number of padding 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
+    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.
+    Min: 0. Max: 100. Default: 0
+
+    "circpad_padding_disabled" -- If set to 1, no circuit padding machines
+    will negotiate, and all current padding machines will cease padding
+    immediately.
+    Min: 0. Max: 1. Default: 0
 
-    "nf_pad_before_usage" -- DOCDOC
+    "circpad_padding_reduced" -- If set to 1, only circuit padding
+    machines marked as "reduced"/"low overhead" will be used.
+    (Currently no such machines are marked as "reduced overhead").
+    Min: 0. Max: 1. Default: 0
 
-    "nf_pad_relays" -- DOCDOC
+    "nf_conntimeout_clients"
+      - The number of seconds to keep never-used circuits opened and
+        available for clients to use. Note that the actual client timeout is
+        randomized uniformly from this value to twice this value.
+      - The number of seconds to keep idle (not currently used) canonical
+        channels are open and available. (We do this to ensure a sufficient
+        time duration of padding, which is the ultimate goal.)
+      - This value is also used to determine how long, after a port has been
+        used, we should attempt to keep building predicted circuits for that
+        port. (See path-spec.txt section 2.1.1.)  This behavior was
+        originally added to work around implementation limitations, but it
+        serves as a reasonable default regardless of implementation.
+      - For all use cases, reduced padding clients use half the consensus
+        value.
+      - Implementations MAY mark circuits held open past the reduced padding
+        quantity (half the consensus value) as "not to be used for streams",
+        to prevent their use from becoming a distinguisher.
+    Min: 60. Max: 86400. Default: 1800
+
+    "nf_conntimeout_relays" -- The number of seconds that idle
+    relay-to-relay connections are kept open.
+    Min: 60. Max: 604800. Default: 3600
+
+    "nf_ito_low" -- The low end of the range to send padding when
+    inactive, in ms.
+    Min: 0. Max: 60000. Default: 1500
+
+    "nf_ito_high" -- The high end of the range to send padding, in ms.
+    If nf_ito_low == nf_ito_high == 0, padding will be disabled.
+    Min: nf_ito_low. Max: 60000. Default: 9500
+
+    "nf_ito_low_reduced" -- For reduced padding clients: the low
+    end of the range to send padding when inactive, in ms.
+    Min: 0. Max: 60000. Default: 9000
+
+    "nf_ito_high_reduced" -- For reduced padding clients: the high
+    end of the range to send padding, in ms.
+    Min: nf_ito_low_reduced. Max: 60000. Default: 14000
+
+    "nf_pad_before_usage" -- If set to 1, OR connections are padded
+    before the client uses them for any application traffic. If 0,
+    OR connections are not padded until application data begins.
+    Min: 0. Max: 1. Default: 1
+
+    "nf_pad_relays" -- If set to 1, we also pad inactive
+    relay-to-relay connections.
+    Min: 0. Max: 1. Default: 0
 
     "nf_pad_single_onion" -- DOCDOC