prop224: Specify rough directory format of hidden services.

1 files changed, 53 insertions, 27 deletions

diff --git a/proposals/224-rend-spec-ng.txt b/proposals/224-rend-spec-ng.txt
index 814fd74..4a685e5 100644
--- a/proposals/224-rend-spec-ng.txt
+++ b/proposals/224-rend-spec-ng.txt
@@ -2096,15 +2096,46 @@ Appendix E. Reserved numbers
       Note: The value "0A" is skipped because it's reserved for the onion key
             cross-certifying ntor identity key from proposal 228.
 
-Appendix F. Managing authorized client data [CLIENT-AUTH-MGMT]
+Appendix F. Hidden service directory format [HIDSERVDIR-FORMAT]
+
+  This appendix section specifies the contents of the HiddenServiceDir directory:
+
+  - "hostname"                                       [FILE]
+
+   This file contains the onion address of the onion service.
+
+  - "private_key_ed25519"                            [FILE]
+
+   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.
+
+  - "./client_authorized_privkeys/"                  [DIRECTORY]
+    "./client_authorized_privkeys/alice.privkey"     [FILE]
+    "./client_authorized_privkeys/bob.privkey"       [FILE]
+    "./client_authorized_privkeys/charlie.privkey"   [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.
+
+Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT]
 
   Hidden services and clients can configure their authorized client data either
   using the torrc, or using the control port. This section presents a suggested
-  scheme for configuring client authorization.
+  scheme for configuring client authorization. Please see appendix
+  [HIDSERVDIR-FORMAT] for more information about relevant hidden service files.
 
-  F.1. Configuring client authorization using torrc
+  E.1. Configuring client authorization using torrc
 
-  F.1.1. Hidden Service side
+  E.1.1. Hidden Service side
 
 	  A hidden service that wants to perform client authorization, adds a new
 	  option HiddenServiceAuthorizeClient to its torrc file:
@@ -2115,29 +2146,24 @@ Appendix F. Managing authorized client data [CLIENT-AUTH-MGMT]
 	  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 the directory at "DataDirectory/hidden_service/client_auth/" for
-	  any files with filename alice.key or alice.pub .
-
-	  Files ending in .key contain private keys for authorized clients, whereas
-	  .pub files contain public keys for authorized clients. In general, authorized
-	  clients should send their public keys to the hidden service operator, and the
-	  operator should place them in the filesystem as .pub files. Only .pub files
-	  are useful to the hidden service, whereas .key files are there only if the
-	  hidden service had to generate its client's keypairs as described below.
+	  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.
 
-	  If no alice.key or alice.pub files exist, Tor is tasked with generating
-	  client keys for Alice. To do so, Tor generates x25519 and ed25519 keypairs
-	  for Alice, then makes an alice.key file and writes the private keys inside;
-	  it also makes an alice.pub file and writes the public keys inside.
-	  [XXX what format? it should be convenient so that client can just copy-paste]
+	  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.
 
-	  In this 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.
+	  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.
 
-  F.1.2. Client side
+  E.1.2. Client side
 
 	  A client who wants to register client authorization data for a hidden service
 	  needs to add the following line to their torrc:
@@ -2150,9 +2176,9 @@ Appendix F. Managing authorized client data [CLIENT-AUTH-MGMT]
 	  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.
 
-  F.2. Configuring client authorization using the control port
+  E.2. Configuring client authorization using the control port
 
-  F.2.1. Service side
+  E.2.1. Service side
 
 	  A hidden service also has the option to configure authorized clients
 	  using the control port. The idea is that hidden service operators can use
@@ -2167,7 +2193,7 @@ Appendix F. Managing authorized client data [CLIENT-AUTH-MGMT]
 	  Hidden services who use the control port interface for client auth need
 	  to perform their own key management.
 
-  F.2.2. Client side
+  E.2.2. Client side
 
 	  There should also be a control port interface for clients to register
 	  authorization data for hidden services without having to use the