[tor-dev] [RFC] control-spec: Specify add/remove/view client auth commands (client-side).

[George Kadianakis]

George Kadianakis <desnacked at riseup.net> writes:

> Hello list,
>
> here is a control spec patch for adding v3 client auth commands to
> add/remove/view clients from the client-side (so Tor Browser -> Tor):
>                 https://github.com/torproject/torspec/pull/81/commits/3a26880e80617210b4729f96664ef9f0345b0b7c
>
> I'm currently unhappy with the naming of those commands, and in general
> with how easy it is to confuse them with the (non-existent) service-side
> commands. I'm wondering how to name them better so that when we add the
> respective service-side commands (at some point we should) there is no
> confusion.
>

Thanks for all the comments. I think I took everything into account, and
I'm inlining an updated version of the patch. My apologies if I forgot
something.

There will likely be updates (e.g. on the error codes) as we get to
implement this, because we always forget something.

Thanks for the feedback, very much appreciated! :)

---

+
+ 3.30. ONION_CLIENT_AUTH_ADD
+ 
+   The syntax is:
+     "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 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. ONION_CLIENT_AUTH_REMOVE
+ 
+   The syntax is:
+     "ONION_CLIENT_AUTH_REMOVE" SP HSAddress
+                                SP "X25519PrivKey=" PrivateKeyBlob CRLF
+ 
+   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. ONION_CLIENT_AUTH_VIEW
+ 
+   The syntax is:
+     "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF
+ 
+   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-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF
+     *("250-CLIENT X25519PrivKey=" PrivateKeyBlob
+                               [SP "ClientName=" Nickname]
+                               [SP "Type=" TYPE] CRLF)
+     "250 OK" CRLF
+ 
+   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".
+