commit d0d151989f44c01758e2d9b9834bce29cce693dc Author: David Goulet <dgoulet@torproject.org> Date: Thu Jul 12 11:22:55 2018 -0400 rend-v3: Specify the client authorization file format Signed-off-by: David Goulet <dgoulet@torproject.org> --- rend-spec-v3.txt | 95 +++++++++++++++++++++++++++----------------------------- 1 file changed, 46 insertions(+), 49 deletions(-) diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index e18f502..4f8afa2 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -2299,15 +2299,17 @@ 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_privkeys/" [DIRECTORY] - "./client_authorized_privkeys/alice.keys" [FILE] - "./client_authorized_privkeys/bob.keys" [FILE] - "./client_authorized_privkeys/charlie.keys" [FILE] + - "./authorized_client/" [DIRECTORY] + "./authorized_client/alice" [FILE] + "./authorized_client/bob" [FILE] + "./authorized_client/charlie" [FILE] - 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. + If client authorization is _enabled_, this directory MUST contain a file + for each authorized client. Each such file contains the public key of the + configured "client-name" transmitted to the service operator by the client. + See [CLIENT-AUTH-MGMT] for more details. + + See section E.1.2 [CLIENT-AUTH-MGMT] for the format of a client file. (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.) @@ -2324,64 +2326,59 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT] E.1.1. Hidden Service side - A hidden service that wants to perform client authorization, adds a new + A hidden service that wants to perform client authorization, adds the option HiddenServiceAuthorizeClient to its torrc file: - HiddenServiceAuthorizeClient auth-type client-name,client-name,... + HiddenServiceAuthorizeClient <auth-type> <client-name>,... - The only recognized auth-type value is "basic" which describes the scheme in - section [CLIENT-AUTH]. The rest of the line is a comma-separated list of - human-readable authorized client names. + The only recognized auth-type value is "descriptor" which describes the + scheme in 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 whether the "./client_authorized_privkeys/alice.keys" - file is present in the filesystem: + case, Tor checks whether the "./authorized_client/alice" file is present + on the filesystem and if found, we use the included keys to authenticate. - If the "alice.keys" file is found, we use the included keys to - authenticate Alice. + E.1.2. Service-side bookkeeping - 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. + This section contains more details on how onion services should be + keeping track of the ".keys" file. - 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. + The file contains an ed25519 and x25519 public key for a specific client. + The suggested format is as follow: - E.1.2. Service-side bookkeeping + <auth-type>:<key-type>:<encoded-public-key> - This section contains more details on how onion services should be keeping - track of the ".keys" file. + As an example for the recognized auth type value "descriptor": - 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 - """ + descriptor:x25519:<base64-encoded-pubkey> 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: + A client who wants to register client authorization data for a hidden + service needs to add the following line to their torrc to indicate which + "client-name" is configured to use client authorization. + + HiddenServiceClientAuth <auth-type> <client-name>,... + + That "client-name" is the name of the file that tor will look in the + + HiddenServiceClientAuthDir <DIR> + + The "DIR" contains a file named "client-name" which should be one per + onion address configured with client authorization. + + If "auth-type" is set to "descriptor", the file contains the private key + in binary format: - HidServAuth onion-address x25519-private-key ed25519-private-key + <onion-address>:x25519:<binary private key> - The keys above are either generated by Alice using a key generation utility, - or they are extracted from a ".keys" file provided by the hidden service. + The reason to use a binary representation of the key is to discourage the + user (a human) to try to copy it around or edit the file. - 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. + The keypair used for client authorization is created by a third part tool + for which the public key needs to be transferred to the service operator + in a secure out-of-band way. E.2. Configuring client authorization using the control port