[RFC] control-spec: Specify add/remove/view client auth commands (client-side).
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/3a26880e80617210b4729f... 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. Let me know what you think! Thanks! :)
On 06 May (18:19:58), George Kadianakis wrote:
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/3a26880e80617210b4729f...
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.
Very nice! (Replying here so tor-dev@ sees it all and do not miss comments on the PR.) 1. So yes on the naming and a way to highlight service vs client. The command naming scheme on the control port is a bit chaotic and I'm all for one trying to come up with "namespace" a bit better. HSPOST, HSFETCH, ADD_ONION, DEL_ONION... We can't change the above but we can at least from now on try to come up with a better naming related to onion services. Something like: - ONION_CLIENT_ADD_AUTH - ONION_CLIENT_DEL_AUTH - ONION_CLIENT_LIST_AUTH I know a bit long but these commands in the end should rarely be typed by a human person anyway. And if we have service side only commands, we use: - ONION_SERVICE_... Not sure we'll ever have a command that applies to both a service and a client... maybe who knows, but then we can either do two commands or just generalized on: - ONION_ ... 2. We need LIST/ADD/DEL to specifies what code is returned in case of success and error. There can be many errors like "Key blob unparseable" or "HSAddress" is invalid or "a client auth already exists" which I assume for this we will force the user to remove/add instead of replacing. 3. The VIEW_ONION_CLIENT_AUTH, for "Type", I think you need to define this differenlty: [SP "Type=" TYPE] and then define TYPE: TYPE can be: "Permanent" - <description>... Cheers! David -- nUXe6UT7bN7R6NGT2ZAAfdBXWLxXg2jRjmun1U49Zcs=
On 5/6/19 11:19 AM, George Kadianakis wrote:
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/3a26880e80617210b4729f...
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.
Let me know what you think!
Thanks for working on this. I have a couple of comments: 1. How does Permanent get set? Should there by an option added to ADD_ONION_CLIENT_AUTH to let the client say "store this on disk"? 2. For VIEW_ONION_CLIENT_AUTH it would be nice if the HSAddress parameter was optional. We may want to build an interface that allows users to see all of their keys and choose which ones to remove, etc. -- Mark Smith Pearl Crescent http://pearlcrescent.com/
Mark Smith <mcs@pearlcrescent.com> writes:
2. For VIEW_ONION_CLIENT_AUTH it would be nice if the HSAddress parameter was optional. We may want to build an interface that allows users to see all of their keys and choose which ones to remove, etc.
A few random points: I like dgoulet's naming, with "ONION_CLIENT" up front. Why do we need VIEW (with the private keys) at all? (I'm thinking e.g. when multiple controllers are connected). If we do need a "view" command, maybe it should only show the key-IDs (and not the actual private keys)? This, then, would either make ClientName= non-optional, or the ADD command should return the name of the key. It might be less confusing to read the spec if you replaced "tells the server" with "tells tor" or "tells the connected Tor". Further to Mark's question earlier, I think the spec should say more about where/how long these keys will be stored. Since implementers seem to want control of their keys for service-side things, I would imagine the same will be true on the client-side -- that is, an option for "ephemeral" in the sense that "Tor stores these only in memory". FWIW, the (current) implementation in txtorcon basically encourages an approach where you keep the keys "in Tor" for as little time as possible. You *can* add them permanently, but the "nice" API is a context-manager, so you'd have code somewhat like this: tor = await txtorcon.connect(...) async with tor.onion_authentication("http://timaq4ygg2iegci7.onion/", "token-blob"): agent = tor.web_agent() resp = await agent.request(b'GET', "http://timaq4ygg2iegci7.onion/") body = await readBody(resp) # here, auth is removed from tor as we leave the context-manager -- meejah
On namespaces... Like MIBs, APIs, file systems, most anything, it's usually... least specific left to most specific right ... DNS also maintains hier but in reverse direction. add_foo_thing1 add_thing1 add_thing2 see_bar_thing1 string_assorted_junk_this ... gives you hierarchies of *add* filled with all sorts of random things, doesn't sort, and leads to documentation being scattered as well, with assorted junk everywhere. ONION_CLIENT_AUTH_ADD is most clear... ONION (ok, what about onion), CLIENT (ok, what about client), AUTH (ok, and...) ADD (aha yes do that). And docs are self ordering into nice sections. ONION_CLIENT_ADD_AUTH doesn't follow because it reverses the last two thus breaking things again. "We can't change" Sometimes these positions can hold you back, allow random in new things, expend mantenance on old chaos, etc. If project codebases have a lot of legacy chaos, downstream can appreciate and support refactoring in major releases, even if they have to do a little work themselves to get that. Announced mapping of legacy command support for removal in next major releases can help there too.
grarpamp <grarpamp@gmail.com> writes:
ONION_CLIENT_AUTH_ADD ONION_CLIENT_ADD_AUTH
+1
"We can't change"
Yeah, this is a tough one in some ways. Incremental change is best, but in some ways a wholesale re-thinking could be good as well. I am just one "control library author", but many of txtorcon's APIs seek to hide away the actual control-protocol verbs etc. so changing the "raw" Tor control-protocol API to be spelled out better is low priority (for me). As far as "re-thinking", I personally would be keen to see a capability-based approach so that potentially very fine-grained permissions can be granted (e.g. "you may add a single ephemeral onion service"). This need is somewhat answered already by proxies -- and in any case "some separate program" is the best place to prototype a "completely new" protocol. The reality is we're currently in a situation where a lot of people don't want to give any program control-protocol access (and rightly so) because it's such a vast amount of information and control. Thus, it's likely that any "tor-using application" (beyond "use SOCKS5") has basically no choice but to launch its own instance of tor. Maybe this is the best thing to do anyway? -- meejah
(1) On 5/7/19 2:16 AM, grarpamp wrote:
ONION_CLIENT_AUTH_ADD
is most clear... ONION (ok, what about onion), CLIENT (ok, what about client), AUTH (ok, and...) ADD (aha yes do that). And docs are self ordering into nice sections.
ONION_CLIENT_ADD_AUTH
doesn't follow because it reverses the last two thus breaking things again.
That's cool. But according to what dgoulet proposed, if we use both ONION_CLIENT_AUTH_ADD and ONION_SERVICE_AUTH_ADD. The latter will sound like it's an authentication of the service not the client. At least for me :) If you want the least specific left and the most specific right, I think ONION_AUTH_CLIENT_ADD and ONION_AUTH_SERVICE_ADD would be better. (2) I think, to be more specific, I would rather use X25519PubKey and X25519PrivKey instead of just X25519Key. (3) Is PERMANENT a type? Is there any other type other than PERMANENT? I think I consider it as a TRUE/FALSE flag.
On 5/7/19, Suphanat Chunhapanya <haxx.pop@gmail.com> wrote:
That's cool. But according to what dgoulet proposed, if we use both ONION_CLIENT_AUTH_ADD and ONION_SERVICE_AUTH_ADD. The latter will sound like it's an authentication of the service not the client. At least for me :)
And or maybe that seem more like managing the onion service ID itself too, rather than just authentication for fetching or connecting to it. Part of problem may be brain grouping of the underscores. "onion" "client|service" "auth" "add|del|view" "onion" "client|service auth" "add|del|view" "onion client|service" "auth" "add|del|view"
If you want the least specific left and the most specific right, I think ONION_AUTH_CLIENT_ADD and ONION_AUTH_SERVICE_ADD would be better.
Maybe your sense would be better... "onion auth" for "client|service" do "add|del|view" or if there's want to keep "onion" string as the MIB root... "onion" re "auth" for "client|service" do "add|del|view" Though seems mostly agreed on onion first and verb last, so whatever works for people in the middle :)
Mark Smith <mcs@pearlcrescent.com> writes:
On 5/6/19 11:19 AM, George Kadianakis wrote:
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/3a26880e80617210b4729f...
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.
Let me know what you think!
Thanks for working on this. I have a couple of comments:
1. How does Permanent get set? Should there by an option added to ADD_ONION_CLIENT_AUTH to let the client say "store this on disk"?
Yes we do want that! We just thought it adds to engineering complexity and it shouldn't get in as part of the first implementation (i.e. as an s27-must). I will still add it to the spec, and just not implement it.
2. For VIEW_ONION_CLIENT_AUTH it would be nice if the HSAddress parameter was optional. We may want to build an interface that allows users to see all of their keys and choose which ones to remove, etc.
Good point! Will do. Will probs have a revision for this list tomorrow!
George Kadianakis <desnacked@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/3a26880e80617210b4729f...
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". +
participants (6)
-
David Goulet -
George Kadianakis -
grarpamp -
Mark Smith -
meejah -
Suphanat Chunhapanya