[tor-commits] [tor/release-0.3.5] tweak manpage bits about v3 onion svc client auth

[dgoulet at torproject.org]

commit d023de945a7037bb4ec66f81aa83588d53184099
Author: Mike Tigas <mike.tigas at gmail.com>
Date:   Fri Oct 12 17:15:11 2018 -0400

    tweak manpage bits about v3 onion svc client auth
    
    make a couple things more explicit, like not needing to set "HiddenServiceAuthorizeClient" & etc
---
 doc/tor.1.txt | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 406372433..2d5237c84 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -1090,14 +1090,16 @@ The following options are useful only for clients (that is, if
     **HiddenServiceAuthorizeClient** option.
 
 [[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__::
-    Path to the directory containing the hidden service authorization file. The
-    files MUST have the suffix ".auth_private". Each file is for a single
-    onion address and their format is:
+    Path to the directory containing v3 hidden service authorization files.
+    Each file is for a single onion address, and the files MUST have the suffix
+    ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be:
  +
       <onion-address>:descriptor:x25519:<base32-encoded-privkey>
  +
-    The <onion-address> MUST NOT have the ".onion" suffix. See the
-    rend-spec-v3.txt Appendix G for more information.
+    The <onion-address> MUST NOT have the ".onion" suffix. The
+    <base32-encoded-privkey> is the base32 representation of the raw key bytes
+    only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of
+    https://spec.torproject.org/[torspec] for more information.
 
 [[LongLivedPorts]] **LongLivedPorts** __PORTS__::
     A list of ports for services that tend to have long-running connections
@@ -2839,7 +2841,8 @@ The following options are used to configure a hidden service.
     clients without authorization any more. Generated authorization data can be
     found in the hostname file. Clients need to put this authorization data in
     their configuration file using **HidServAuth**. This option is only for v2
-    services.
+    services; v3 services configure client authentication in a subdirectory of
+    HiddenServiceDir instead (see the **Client Authorization** section).
 
 [[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**::
    If set to 1, then connections to unrecognized ports do not cause the
@@ -2941,19 +2944,26 @@ Client Authorization
 (Version 3 only)
 
 To configure client authorization on the service side, the
-"<HiddenServiceDir>/authorized_clients/" needs to exists. Each file in that
-directory should be suffixed with ".auth" (the file name is irrelevant) and
-its content format MUST be:
+"<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file
+in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the
+file name is irrelevant) and its content format MUST be:
 
         <auth-type>:<key-type>:<base32-encoded-public-key>
 
 The supported <auth-type> are: "descriptor". The supported <key-type> are:
-"x25519". Each file MUST contain one line only. Any malformed file will be
-ignored.
+"x25519". The <base32-encoded-privkey> is the base32 representation of the raw
+key bytes only (32 bytes for x25519).
+
+Each file MUST contain one line only. Any malformed file will be
+ignored. Client authorization will only be enabled for the service if tor
+successfully loads at least one authorization file.
 
 Note that once you've configured client authorization, anyone else with the
 address won't be able to access it from this point on. If no authorization is
-configured, the service will be accessible to all.
+configured, the service will be accessible to anyone with the onion address.
+
+See the Appendix G in the rend-spec-v3.txt file of
+https://spec.torproject.org/[torspec] for more information.
 
 TESTING NETWORK OPTIONS
 -----------------------