[tor-commits] [tor] 39/77: manpage: document HiddenServicePoWDefensesEnabled option

[gitolite role]

This is an automated email from the git hooks/post-receive script.

dgoulet pushed a commit to branch main
in repository tor.

commit 98299e0f8b872825cffa5afd007ee7fd5fd2a39a
Author: Micah Elizabeth Scott <beth at torproject.org>
AuthorDate: Mon Feb 27 15:36:22 2023 -0800

    manpage: document HiddenServicePoWDefensesEnabled option
    
    Signed-off-by: Micah Elizabeth Scott <beth at torproject.org>
---
 doc/man/tor.1.txt | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt
index 57992cd8d2..a62c7c7d82 100644
--- a/doc/man/tor.1.txt
+++ b/doc/man/tor.1.txt
@@ -3021,14 +3021,14 @@ Denial of Service mitigation subsystem described above.
     (Default: auto)
 
 
-As for onion services, only one possible mitigation exists. It was intended to
-protect the network first and thus do not help the service availability or
-reachability.
+For onion services, mitigations are a work in progress and multiple options
+are currently available.
 
-The mitigation we put in place is a rate limit of the amount of introduction
-that happens at the introduction point for a service. In other words, it rates
-limit the number of clients that are attempting to reach the service at the
-introduction point instead of at the service itself.
+The introduction point defense is a rate limit on the number of introduction
+requests that will be forwarded to a service by each of its honest
+introduction point routers. This can prevent some types of overwhelming floods
+from reaching the service, but it will also prevent legitimate clients from
+establishing new connections.
 
 The following options are per onion service:
 
@@ -3082,6 +3082,23 @@ The bottom line is that this protects the network by preventing an onion
 service to flood the network with new rendezvous circuits that is reducing load
 on the network.
 
+A secondary mitigation is available, based on prioritized dispatch of rendezvous
+circuits for new connections. The queue is ordered based on effort a client
+chooses to spend at computing a proof-of-work function.
+
+The following options are per onion service:
+
+[[HiddenServicePoWDefensesEnabled]] **HiddenServicePoWDefensesEnabled** **0**|**1**::
+
+    Enable proof-of-work based service DoS mitigation. If set to 1 (enabled),
+    tor will include parameters for an optional client puzzle in the encrypted
+    portion of this hidden service's descriptor. Incoming rendezvous requests
+    will be prioritized based on the amount of effort a client chooses to make
+    when computing a solution to the puzzle. The service will periodically update
+    a suggested amount of effort, based on attack load, and disable the puzzle
+    entirely when the service is not overloaded.
+    (Default: 0)
+
 
 == DIRECTORY AUTHORITY SERVER OPTIONS
 

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.