rend-v3: Switch to single-file-per-client client auth UX.

1 files changed, 38 insertions, 28 deletions

diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt
index dbd3103..e18f502 100644
--- a/rend-spec-v3.txt
+++ b/rend-spec-v3.txt
@@ -2299,25 +2299,15 @@ 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_pubkeys"                      [FILE]
-
-   If client authorization is _enabled_, this is a newline-separated file of
-   "<client name> <pubkeys> entries for authorized clients. You can think of it
-   as the ~/.ssh/authorized_keys of onion services. See [CLIENT-AUTH-MGMT] for
-   more details.
-
-   (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.)
-
-
   - "./client_authorized_privkeys/"                  [DIRECTORY]
-    "./client_authorized_privkeys/alice.privkey"     [FILE]
-    "./client_authorized_privkeys/bob.privkey"       [FILE]
-    "./client_authorized_privkeys/charlie.privkey"   [FILE]
+    "./client_authorized_privkeys/alice.keys"        [FILE]
+    "./client_authorized_privkeys/bob.keys"          [FILE]
+    "./client_authorized_privkeys/charlie.keys"      [FILE]
 
-   If client authorization is _enabled_ _AND_ if the hidden service is
-   responsible for generating and distributing private keys for its clients,
-   then this directory contains files with client's private keys. 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 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.
 
    (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.)
 
@@ -2344,23 +2334,43 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT]
      human-readable authorized client names.
 
      Let's consider that one of the listed client names is "alice". In this
-     case, Tor checks the "client_authorized_pubkeys" file for any entries
-     with client_name being "alice". If an "alice" entry is found, we use the
-     relevant pubkeys to authenticate Alice.
+     case, Tor checks whether the "./client_authorized_privkeys/alice.keys"
+     file is present in the filesystem:
 
-     If no "alice" entry is found in the "client_authorized_pubkeys" file, Tor
-     is tasked with generating public/private keys for Alice. To do so, Tor
-     generates x25519 and ed25519 keypairs for Alice, then makes a
-     "client_authorized_privkeys/alice.privkey" file and writes the private
-     keys inside; it also adds an entry for alice to the
-     "client_authorized_pubkeys" file.
+     If the "alice.keys" file is found, we use the included keys to
+     authenticate Alice.
+
+     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.
 
      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.
 
-  E.1.2. Client side
+  E.1.2. Service-side bookkeeping
+
+     This section contains more details on how onion services should be keeping
+     track of the ".keys" file.
+
+     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
+     """
+
+  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:
@@ -2368,7 +2378,7 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT]
            HidServAuth onion-address x25519-private-key ed25519-private-key
 
      The keys above are either generated by Alice using a key generation utility,
-     or they are extracted from a .key file provided by the hidden service.
+     or they are extracted from a ".keys" file provided by the hidden service.
 
      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.