rend-v3: Specify the client authorization file format

Signed-off-by: David Goulet <dgoulet@torproject.org>

1 files changed, 46 insertions, 49 deletions

diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt
index e18f502..4f8afa2 100644
--- a/rend-spec-v3.txt
+++ b/rend-spec-v3.txt
@@ -2299,15 +2299,17 @@ Appendix F. Hidden service directory format [HIDSERVDIR-FORMAT]
    This file contains the private master ed25519 key of the onion service.
    [TODO: Offline keys]
 
-  - "./client_authorized_privkeys/"                  [DIRECTORY]
-    "./client_authorized_privkeys/alice.keys"        [FILE]
-    "./client_authorized_privkeys/bob.keys"          [FILE]
-    "./client_authorized_privkeys/charlie.keys"      [FILE]
+  - "./authorized_client/"                  [DIRECTORY]
+    "./authorized_client/alice"             [FILE]
+    "./authorized_client/bob"               [FILE]
+    "./authorized_client/charlie"           [FILE]
 
-   If client authorization is _enabled_, this directory MUST contain a file for
-   each authorized client. Each such file contains the keypair of that client
-   (if generated by the service), or just the public key of the client (if
-   generated by the client). See [CLIENT-AUTH-MGMT] for more details.
+   If client authorization is _enabled_, this directory MUST contain a file
+   for each authorized client. Each such file contains the public key of the
+   configured "client-name" transmitted to the service operator by the client.
+   See [CLIENT-AUTH-MGMT] for more details.
+
+   See section E.1.2 [CLIENT-AUTH-MGMT] for the format of a client file.
 
    (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.)
 
@@ -2324,64 +2326,59 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT]
 
   E.1.1. Hidden Service side
 
-     A hidden service that wants to perform client authorization, adds a new
+     A hidden service that wants to perform client authorization, adds the
      option HiddenServiceAuthorizeClient to its torrc file:
 
-        HiddenServiceAuthorizeClient auth-type client-name,client-name,...
+        HiddenServiceAuthorizeClient <auth-type> <client-name>,...
 
-     The only recognized auth-type value is "basic" which describes the scheme in
-     section [CLIENT-AUTH]. The rest of the line is a comma-separated list of
-     human-readable authorized client names.
+     The only recognized auth-type value is "descriptor" which describes the
+     scheme in section [CLIENT-AUTH]. The rest of the line is a
+     comma-separated list of human-readable authorized client names.
 
      Let's consider that one of the listed client names is "alice". In this
-     case, Tor checks whether the "./client_authorized_privkeys/alice.keys"
-     file is present in the filesystem:
+     case, Tor checks whether the "./authorized_client/alice" file is present
+     on the filesystem and if found, we use the included keys to authenticate.
 
-     If the "alice.keys" file is found, we use the included keys to
-     authenticate Alice.
+  E.1.2. Service-side bookkeeping
 
-     If no "alice.keys" file is found, Tor is tasked with generating Alice's
-     keypair. To do so, Tor generates x25519 and ed25519 keypairs for Alice,
-     then creates the "client_authorized_privkeys/alice.keys" file and writes
-     the private keys inside.
+     This section contains more details on how onion services should be
+     keeping track of the ".keys" file.
 
-     In this last case, the hidden service operator has the responsibility to
-     pass the .key file to Alice in a secure out-of-band way. After the file
-     is passed to Alice, it can be shredded from the filesystem, as only the
-     public keys are required for the hidden service to function.
+     The file contains an ed25519 and x25519 public key for a specific client.
+     The suggested format is as follow:
 
-  E.1.2. Service-side bookkeeping
+        <auth-type>:<key-type>:<encoded-public-key>
 
-     This section contains more details on how onion services should be keeping
-     track of the ".keys" file.
+     As an example for the recognized auth type value "descriptor":
 
-     In particular, inside a ".keys" file, the onion service should be keeping
-     track of whether a key is ed25519 or x25519 and whether it's public or
-     private. An onion service SHOULD have either two private keys (one ed25519
-     and one x25519) or two public keys (one ed25519 and one x25519) in its
-     ".keys" file. The former scenario happens when the service generates the
-     client auth keys, whereas the latter scenario happens when the client
-     generates keys themselves and passes them to the service.
-
-     Here is a suggested scheme for "alice.keys" for the latter scenario:
-     """
-     alice
-     x25519 private c2247870536a192d142d056abefca68d6193158e7c1a59c1654c954eccaff894
-     ed25519 private 66c1a77104d86461b6f98f73acf3cd229c80624495d2d74d6fda1e940080a96b
-     """
+        descriptor:x25519:<base64-encoded-pubkey>
 
   E.1.3. Client side
 
-     A client who wants to register client authorization data for a hidden service
-     needs to add the following line to their torrc:
+     A client who wants to register client authorization data for a hidden
+     service needs to add the following line to their torrc to indicate which
+     "client-name" is configured to use client authorization.
+
+         HiddenServiceClientAuth <auth-type> <client-name>,...
+
+     That "client-name" is the name of the file that tor will look in the
+
+         HiddenServiceClientAuthDir <DIR>
+
+     The "DIR" contains a file named "client-name" which should be one per
+     onion address configured with client authorization.
+
+     If "auth-type" is set to "descriptor", the file contains the private key
+     in binary format:
 
-           HidServAuth onion-address x25519-private-key ed25519-private-key
+        <onion-address>:x25519:<binary private key>
 
-     The keys above are either generated by Alice using a key generation utility,
-     or they are extracted from a ".keys" file provided by the hidden service.
+     The reason to use a binary representation of the key is to discourage the
+     user (a human) to try to copy it around or edit the file.
 
-     In the former case, the client is also tasked with transfering the public
-     keys to the hidden service in a secure out-of-band way.
+     The keypair used for client authorization is created by a third part tool
+     for which the public key needs to be transferred to the service operator
+     in a secure out-of-band way.
 
   E.2. Configuring client authorization using the control port