[tor-commits] [torspec/master] control-spec: Various improvements following mailing list feedback.

[dgoulet at torproject.org]

commit ce38ad7e46da9840c7d211837c4bffb62d525ebf
Author: George Kadianakis <desnacked at riseup.net>
Date:   Tue May 7 19:03:48 2019 +0300

    control-spec: Various improvements following mailing list feedback.
    
    - Rename all commands to be less arbitrary
    
    - "Tells the server" -> "Tells the connected Tor"
    
    - Make TYPE an actual type thing. We only support one for now, but that's OK.
      Controllers and Tor can take shortcuts if needed.
    
    - Specify where credentials get stored.
    
    - Support viewing all the credentials.
    
    - Support the ADD command adding permanent credentials.
    
    - Change X25519Key to X25519PrivKey.
---
 control-spec.txt | 62 ++++++++++++++++++++++++++++++++------------------------
 1 file changed, 36 insertions(+), 26 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index 21e104e..c2b8f1b 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1811,60 +1811,70 @@
 
   [HSPOST was added in Tor 0.2.7.1-alpha]
 
-3.30. ADD_ONION_CLIENT_AUTH
+3.30. ONION_CLIENT_AUTH_ADD
 
   The syntax is:
-    "ADD_ONION_CLIENT_AUTH" SP HSAddress
-                            SP "X25519Key=" PrivateKeyBlob
-                            [SP "ClientName=" Nickname] CRLF
+    "ONION_CLIENT_AUTH_ADD" SP HSAddress
+                            SP "X25519PrivKey=" PrivateKeyBlob
+                            [SP "ClientName=" Nickname]
+                            [SP "Type=" TYPE] CRLF
 
     HSAddress = 56*Base32Character
     PrivateKeyBlob = base64 encoding of x25519 key
 
-  Tells the server to add client-side v3 client auth credentials for the onion
-  service with "HSAddress". The "PrivateKeyBlob" is the x25519 private key that
-  should be used for this client, and "Nickname" is an optional nickname for
-  the client.
+  Tells the connected Tor to add client-side v3 client auth credentials for the
+  onion service with "HSAddress". The "PrivateKeyBlob" is the x25519 private
+  key that should be used for this client, and "Nickname" is an optional
+  nickname for the client.
+
+  TYPE is a comma-separated tuple of types for this new client. For now, the
+  currently supported types are:
+    "Permanent" - This client's credentials should be stored in the filesystem.
+                  If this is not set, the client's credentials are epheremal
+                  and stored in memory.
 
   On success, "250 OK" is returned. Otherwise, the following error codes exist:
     251 - Client with with this "PrivateKeyBlob" already existed.
     512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname"
     551 - Client with with this "Nickname" already exists
 
-3.31. REMOVE_ONION_CLIENT_AUTH
+3.31. ONION_CLIENT_AUTH_REMOVE
 
   The syntax is:
-    "REMOVE_ONION_CLIENT_AUTH" SP HSAddress
-                               SP "X25519Key=" PrivateKeyBlob CRLF
+    "ONION_CLIENT_AUTH_REMOVE" SP HSAddress
+                               SP "X25519PrivKey=" PrivateKeyBlob CRLF
 
-  Tells the server to remove the client-side v3 client auth credentials for the
-  onion service with "HSAddress" and client with key "PrivateKeyBlob".
+  Tells the connected Tor to remove the client-side v3 client auth credentials
+  for the onion service with "HSAddress" and client with key "PrivateKeyBlob".
 
   On success "250 OK" is returned. Otherwise, the following error codes exist:
     512 - Syntax error in "HSAddress", or "PrivateKeyBlob".
     251 - Client with "PrivateKeyBlob" did not exist.
 
-3.32. VIEW_ONION_CLIENT_AUTH
+3.32. ONION_CLIENT_AUTH_VIEW
 
   The syntax is:
-    "VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF
+    "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF
 
-  Tells the server to list all the stored client-side v3 client auth
-  credentials for "HSAddress".
+  Tells the connected Tor to list all the stored client-side v3 client auth
+  credentials for "HSAddress". If no "HSAddress" is provided, list all the
+  stored client-side v3 client auth credentials.
 
   The server reply format is:
-    "250-VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF
-    *("250-CLIENT X25519Key=" PrivateKeyBlob
+    "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF
+    *("250-CLIENT X25519PrivKey=" PrivateKeyBlob
                               [SP "ClientName=" Nickname]
-                              [SP "Type=Permanent"] CRLF)
+                              [SP "Type=" TYPE] CRLF)
     "250 OK" CRLF
 
-  Where "PrivateKeyBlob" is the x25519 private key of this client. If the
-  client auth credentials are stored in the filesystem, "Type=Permanent" is
-  returned as part of the output. "Nickname" is an optional nickname for this
-  client, which can be set either through the ADD_ONION_CLIENT_AUTH command, or
-  it's the filename of this client if the credentials are stored in the
-  filesystem.
+  Where "PrivateKeyBlob" is the x25519 private key of this client. "Nickname"
+  is an optional nickname for this client, which can be set either through the
+  ONION_CLIENT_AUTH_ADD command, or it's the filename of this client if the
+  credentials are stored in the filesystem.
+
+  TYPE is a comma-separated field of types for this client, the currently
+  supported types are:
+      "Permanent" - This client's credentials are stored in the filesystem.
 
   On success "250 OK" is returned. Otherwise, the following error codes exist:
     512 - Syntax error in "HSAddress".