[tor-commits] [torspec/master] rend-v3: Specify the client authorization file format
asn at torproject.org
asn at torproject.org
Tue Aug 14 11:24:10 UTC 2018
commit d0d151989f44c01758e2d9b9834bce29cce693dc
Author: David Goulet <dgoulet at 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 at 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
More information about the tor-commits
mailing list