manpage: document HiddenServicePoWDefensesEnabled option

Signed-off-by: Micah Elizabeth Scott <beth@torproject.org>

1 files 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