commit b7a2685507a7e8b681040933109b9b4f3cd06099 Author: George Kadianakis desnacked@riseup.net Date: Tue Jul 10 21:55:54 2018 +0300
rend-v3: Switch to single-file-per-client client auth UX. --- rend-spec-v3.txt | 66 ++++++++++++++++++++++++++++++++------------------------ 1 file 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.