From 119b053a8ad9cf8139a159cda30e04d2a3887914 Mon Sep 17 00:00:00 2001 From: David Goulet Date: Wed, 4 Apr 2018 10:22:13 -0400 Subject: [PATCH 1/3] doc: Improve DoS section of the man page tor.1 Add to the Denial of Service section of the man page an explanation about the three different mitigation Tor has. Fixes #25248. Signed-off-by: David Goulet --- changes/ticket25248 | 4 ++++ doc/tor.1.txt | 57 +++++++++++++++++++++++++++++++++++---------- 2 files changed, 49 insertions(+), 12 deletions(-) create mode 100644 changes/ticket25248 diff --git a/changes/ticket25248 b/changes/ticket25248 new file mode 100644 index 000000000..67ccdb631 --- /dev/null +++ b/changes/ticket25248 @@ -0,0 +1,4 @@ + o Documentation (manpage, denial of service): + - Better detail the denial of service options by listing the different + mitigation in place. Closes ticket 25248. + diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 9aad3af98..8bb27fa5a 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -2755,17 +2755,49 @@ The following options are used to configure a hidden service. DENIAL OF SERVICE MITIGATION OPTIONS ------------------------------------ +Tor has three built-in mitigation options that can be individually +enabled/disabled and fine-tuned, but by default Tor directory authorities will +define reasonable values for relays and no explicit configuration is required +to make use of these protections. The mitigations are: + + 1. If a single client address makes too many concurrent connections (this + is configurable via DoSConnectionMaxConcurrentCount), hang up on + further connections. + + + 2. If a single client IP address (v4 or v6) makes circuits too quickly + (default values are more than 3 per second, with an allowed burst of 90, + see DoSCircuitCreationRate and DoSCircuitCreationBurst) while also having + too many connections open (default is 3, see + DoSCircuitCreationMinConnections), tor will refuse any new circuit + (CREATE cells) for the next while (random value between 1 and 2 hours). + + + 3. If a client asks to establish a rendezvous point to you directly (ex: + Tor2Web client), ignore the request. + +These defenses can be manually controlled by torrc options, but relays will +also take guidance from consensus parameters, so there's no need to configure +anything manually. In doubt, do not change those values. + +The values set by the consensus, if any, can be found here: +https://consensus-health.torproject.org/#consensusparams + +If any of the DoS mitigations are enabled, an heartbeat message will appear in +your log at NOTICE level which looks like: + + DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. + 2238 connections closed. 8052 single hop clients refused. + The following options are useful only for a public relay. They control the -Denial of Service mitigation subsystem. +Denial of Service mitigation subsystem described above. [[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: - Enable circuit creation DoS mitigation. If enabled, tor will cache client - IPs along with statistics in order to detect circuit DoS attacks. If an - address is positively identified, tor will activate defenses against the - address. See the DoSCircuitCreationDefenseType option for more details. - This is a client to relay detection only. "auto" means use the consensus - parameter. If not defined in the consensus, the value is 0. + Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will + cache client IPs along with statistics in order to detect circuit DoS + attacks. If an address is positively identified, tor will activate + defenses against the address. See the DoSCircuitCreationDefenseType option + for more details. This is a client to relay detection only. "auto" means + use the consensus parameter. If not defined in the consensus, the value is 0. (Default: auto) [[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: @@ -2809,14 +2841,15 @@ Denial of Service mitigation subsystem. The base time period in seconds that the DoS defense is activated for. The actual value is selected randomly for each activation from N+1 to 3/2 * N. "0" means use the consensus parameter. If not defined in the consensus, - the value is 3600 seconds (1 hour). (Default: 0) + the value is 3600 seconds (1 hour). + (Default: 0) [[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: - Enable the connection DoS mitigation. For client address only, this allows - tor to mitigate against large number of concurrent connections made by a - single IP address. "auto" means use the consensus parameter. If not - defined in the consensus, the value is 0. + Enable the connection DoS mitigation. If set to 1 (enabled), for client + address only, this allows tor to mitigate against large number of + concurrent connections made by a single IP address. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. (Default: auto) [[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: From 712a7d76a00789e88de731dc7f69616119bbe3e1 Mon Sep 17 00:00:00 2001 From: David Goulet Date: Thu, 12 Apr 2018 10:40:03 -0400 Subject: [PATCH 2/3] doc: Move DOS options below SERVER options Signed-off-by: David Goulet --- doc/tor.1.txt | 257 +++++++++++++++++++++++++------------------------- 1 file changed, 129 insertions(+), 128 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 8bb27fa5a..8ce374c12 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -2406,6 +2406,135 @@ details.) (Default: 0) +DENIAL OF SERVICE MITIGATION OPTIONS +------------------------------------ + +Tor has three built-in mitigation options that can be individually +enabled/disabled and fine-tuned, but by default Tor directory authorities will +define reasonable values for relays and no explicit configuration is required +to make use of these protections. The mitigations are: + + 1. If a single client address makes too many concurrent connections (this is + configurable via DoSConnectionMaxConcurrentCount), hang up on further + connections. + + + 2. If a single client IP address (v4 or v6) makes circuits too quickly + (default values are more than 3 per second, with an allowed burst of 90, + see DoSCircuitCreationRate and DoSCircuitCreationBurst) while also having + too many connections open (default is 3, see + DoSCircuitCreationMinConnections), tor will refuse any new circuit (CREATE + cells) for the next while (random value between 1 and 2 hours). + + + 3. If a client asks to establish a rendezvous point to you directly (ex: + Tor2Web client), ignore the request. + +These defenses can be manually controlled by torrc options, but relays will +also take guidance from consensus parameters, so there's no need to configure +anything manually. In doubt, do not change those values. + +The values set by the consensus, if any, can be found here: +https://consensus-health.torproject.org/#consensusparams + +If any of the DoS mitigations are enabled, an heartbeat message will appear in +your log at NOTICE level which looks like: + + DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. + 2238 connections closed. 8052 single hop clients refused. + +The following options are useful only for a public relay. They control the +Denial of Service mitigation subsystem described above. + +[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: + + Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will + cache client IPs along with statistics in order to detect circuit DoS + attacks. If an address is positively identified, tor will activate + defenses against the address. See the DoSCircuitCreationDefenseType option + for more details. This is a client to relay detection only. "auto" means + use the consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: + + Minimum threshold of concurrent connections before a client address can be + flagged as executing a circuit creation DoS. In other words, once a client + address reaches the circuit rate and has a minimum of NUM concurrent + connections, a detection is positive. "0" means use the consensus + parameter. If not defined in the consensus, the value is 3. + (Default: 0) + +[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: + + The allowed circuit creation rate per second applied per client IP + address. If this option is 0, it obeys a consensus parameter. If not + defined in the consensus, the value is 3. + (Default: 0) + +[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: + + The allowed circuit creation burst per client IP address. If the circuit + rate and the burst are reached, a client is marked as executing a circuit + creation DoS. "0" means use the consensus parameter. If not defined in the + consensus, the value is 90. + (Default: 0) + +[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address. The + possible values are: + + + 1: No defense. + + + 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: + + The base time period in seconds that the DoS defense is activated for. The + actual value is selected randomly for each activation from N+1 to 3/2 * N. + "0" means use the consensus parameter. If not defined in the consensus, + the value is 3600 seconds (1 hour). + (Default: 0) + +[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: + + Enable the connection DoS mitigation. If set to 1 (enabled), for client + address only, this allows tor to mitigate against large number of + concurrent connections made by a single IP address. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: + + The maximum threshold of concurrent connection from a client IP address. + Above this limit, a defense selected by DoSConnectionDefenseType is + applied. "0" means use the consensus parameter. If not defined in the + consensus, the value is 100. + (Default: 0) + +[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address for the + connection mitigation. The possible values are: + + + 1: No defense. + + + 2: Immediately close new connections. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: + + Refuse establishment of rendezvous points for single hop clients. In other + words, if a client directly connects to the relay and sends an + ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + + DIRECTORY AUTHORITY SERVER OPTIONS ---------------------------------- @@ -2752,134 +2881,6 @@ The following options are used to configure a hidden service. including setting SOCKSPort to "0". Can not be changed while tor is running. (Default: 0) -DENIAL OF SERVICE MITIGATION OPTIONS ------------------------------------- - -Tor has three built-in mitigation options that can be individually -enabled/disabled and fine-tuned, but by default Tor directory authorities will -define reasonable values for relays and no explicit configuration is required -to make use of these protections. The mitigations are: - - 1. If a single client address makes too many concurrent connections (this - is configurable via DoSConnectionMaxConcurrentCount), hang up on - further connections. - + - 2. If a single client IP address (v4 or v6) makes circuits too quickly - (default values are more than 3 per second, with an allowed burst of 90, - see DoSCircuitCreationRate and DoSCircuitCreationBurst) while also having - too many connections open (default is 3, see - DoSCircuitCreationMinConnections), tor will refuse any new circuit - (CREATE cells) for the next while (random value between 1 and 2 hours). - + - 3. If a client asks to establish a rendezvous point to you directly (ex: - Tor2Web client), ignore the request. - -These defenses can be manually controlled by torrc options, but relays will -also take guidance from consensus parameters, so there's no need to configure -anything manually. In doubt, do not change those values. - -The values set by the consensus, if any, can be found here: -https://consensus-health.torproject.org/#consensusparams - -If any of the DoS mitigations are enabled, an heartbeat message will appear in -your log at NOTICE level which looks like: - - DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. - 2238 connections closed. 8052 single hop clients refused. - -The following options are useful only for a public relay. They control the -Denial of Service mitigation subsystem described above. - -[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: - - Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will - cache client IPs along with statistics in order to detect circuit DoS - attacks. If an address is positively identified, tor will activate - defenses against the address. See the DoSCircuitCreationDefenseType option - for more details. This is a client to relay detection only. "auto" means - use the consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - -[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: - - Minimum threshold of concurrent connections before a client address can be - flagged as executing a circuit creation DoS. In other words, once a client - address reaches the circuit rate and has a minimum of NUM concurrent - connections, a detection is positive. "0" means use the consensus - parameter. If not defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: - - The allowed circuit creation rate per second applied per client IP - address. If this option is 0, it obeys a consensus parameter. If not - defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: - - The allowed circuit creation burst per client IP address. If the circuit - rate and the burst are reached, a client is marked as executing a circuit - creation DoS. "0" means use the consensus parameter. If not defined in the - consensus, the value is 90. - (Default: 0) - -[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address. The - possible values are: - - 1: No defense. - 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. -+ - "0" means use the consensus parameter. If not defined in the consensus, - the value is 2. - (Default: 0) - -[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: - - The base time period in seconds that the DoS defense is activated for. The - actual value is selected randomly for each activation from N+1 to 3/2 * N. - "0" means use the consensus parameter. If not defined in the consensus, - the value is 3600 seconds (1 hour). - (Default: 0) - -[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: - - Enable the connection DoS mitigation. If set to 1 (enabled), for client - address only, this allows tor to mitigate against large number of - concurrent connections made by a single IP address. "auto" means use the - consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - -[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: - - The maximum threshold of concurrent connection from a client IP address. - Above this limit, a defense selected by DoSConnectionDefenseType is - applied. "0" means use the consensus parameter. If not defined in the - consensus, the value is 100. - (Default: 0) - -[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address for the - connection mitigation. The possible values are: - - 1: No defense. - 2: Immediately close new connections. -+ - "0" means use the consensus parameter. If not defined in the consensus, - the value is 2. - (Default: 0) - -[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: - - Refuse establishment of rendezvous points for single hop clients. In other - words, if a client directly connects to the relay and sends an - ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the - consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - TESTING NETWORK OPTIONS ----------------------- From 21b347e291871ab89c140c9842f72cee76dd1c29 Mon Sep 17 00:00:00 2001 From: Mike Perry Date: Wed, 11 Apr 2018 02:47:00 +0000 Subject: [PATCH 3/3] doc: Fix typo and clarify that DoS options are relay only --- doc/tor.1.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 8ce374c12..369cdb526 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -2412,7 +2412,8 @@ DENIAL OF SERVICE MITIGATION OPTIONS Tor has three built-in mitigation options that can be individually enabled/disabled and fine-tuned, but by default Tor directory authorities will define reasonable values for relays and no explicit configuration is required -to make use of these protections. The mitigations are: +to make use of these protections. The mitigations take place at relays, +and are as follows: 1. If a single client address makes too many concurrent connections (this is configurable via DoSConnectionMaxConcurrentCount), hang up on further @@ -2429,13 +2430,13 @@ to make use of these protections. The mitigations are: Tor2Web client), ignore the request. These defenses can be manually controlled by torrc options, but relays will -also take guidance from consensus parameters, so there's no need to configure -anything manually. In doubt, do not change those values. +also take guidance from consensus parameters using these same names, so there's +no need to configure anything manually. In doubt, do not change those values. The values set by the consensus, if any, can be found here: https://consensus-health.torproject.org/#consensusparams -If any of the DoS mitigations are enabled, an heartbeat message will appear in +If any of the DoS mitigations are enabled, a heartbeat message will appear in your log at NOTICE level which looks like: DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.