diff options
Diffstat (limited to 'rend-spec-v3.txt')
| -rw-r--r-- | rend-spec-v3.txt | 137 |
1 files changed, 78 insertions, 59 deletions
diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index 8b3996b..141cfa0 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -1124,8 +1124,8 @@ Table of contents: 2.5.1. First layer of encryption [HS-DESC-FIRST-LAYER] The first layer of HS descriptor encryption is designed to protect - descriptor confidentiality against entities who don't know the blinded - public key of the hidden service. + descriptor confidentiality against entities who don't know the public + identity key of the hidden service. 2.5.1.1. First layer encryption logic @@ -1136,6 +1136,11 @@ Table of contents: SECRET_DATA = blinded-public-key STRING_CONSTANT = "hsdir-superencrypted-data" + The encryption scheme in [HS-DESC-ENCRYPTION-KEYS] uses the service + credential which is derived from the public identity key (see [SUBCRED]) to + ensure that only entities who know the public identity key can decrypt the + first descriptor layer. + The ciphertext is placed on the "superencrypted" field of the descriptor. Before encryption the plaintext is padded with NUL bytes to the nearest @@ -1209,7 +1214,7 @@ Table of contents: And here is what the hidden service computes: SECRET_SEED = x25519(hs_y, client_X) - KEYS = KDF(SECRET_SEED, 40) + KEYS = KDF(subcredential | SECRET_SEED, 40) CLIENT-ID = fist 8 bytes of KEYS COOKIE-KEY = last 32 bytes of KEYS @@ -1338,6 +1343,15 @@ Table of contents: The link-specifiers is a base64 encoding of a link specifier block in the format described in BUILDING-BLOCKS. + The client SHOULD NOT reject any LSTYPE fields which it doesn't + recognize; instead, it should use them verbatim in its EXTEND + request to the introduction point. + + The client MAY perform basic validity checks on the link + specifiers in the descriptor. These checks SHOULD NOT leak + detailed information about the client's version, configuration, + or consensus. (See 3.3 for service link specifier handling.) + "onion-key" SP "ntor" SP key NL [Exactly once per introduction point] @@ -1388,7 +1402,7 @@ Table of contents: legacy protocol (v2) that is <= 0.2.9 or the protocol version value "HSIntro 3". - "legacy-key-cert NL certificate NL + "legacy-key-cert" NL certificate NL [None or at most once per introduction point] @@ -1666,7 +1680,7 @@ Table of contents: If the cell is not a replay, it decrypts the ENCRYPTED field, establishes a shared key with the client, and authenticates the whole contents of the cell as having been unmodified since they left the - client. There may be multiple ways of decrypting the ENCRYTPED field, + client. There may be multiple ways of decrypting the ENCRYPTED field, depending on the chosen type of the encryption key. Requirements for an introduction handshake protocol are described in [INTRO-HANDSHAKE-REQS]. We specify one below in section @@ -1697,9 +1711,10 @@ Table of contents: in [BUILDING-BLOCKS], the "TLS-over-TCP, IPv4" and "Legacy node identity" specifiers must be present. - The hidden service SHOULD NOT reject any LSTYPE fields which it - doesn't recognize; instead, it should use them verbatim in its EXTEND - request to the rendezvous point. + The hidden service should handle invalid or unrecognised link specifiers + the same way as clients do in section 2.5.2.2. In particular, services + MAY perform basic validity checks on link specifiers, and SHOULD NOT + reject unrecognised link specifiers, to avoid information leaks. The ONION_KEY_TYPE field is: @@ -2284,29 +2299,21 @@ 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.) - + - "./authorized_clients/" [DIRECTORY] + "./authorized_clients/alice.auth" [FILE] + "./authorized_clients/bob.auth" [FILE] + "./authorized_clients/charlie.auth" [FILE] - - "./client_authorized_privkeys/" [DIRECTORY] - "./client_authorized_privkeys/alice.privkey" [FILE] - "./client_authorized_privkeys/bob.privkey" [FILE] - "./client_authorized_privkeys/charlie.privkey" [FILE] + If client authorization is enabled, this directory MUST contain a ".auth" + file for each authorized client. Each such file contains the public key of + the respective client. The files are transmitted to the service operator by + the client. - 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. + See section [CLIENT-AUTH-MGMT] for more details and the format of the client file. (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.) -Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT] +Appendix G. Managing authorized client data [CLIENT-AUTH-MGMT] Hidden services and clients can configure their authorized client data either using the torrc, or using the control port. This section presents a suggested @@ -2315,52 +2322,64 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT] (NOTE: client authorization is not implemented as of 0.3.2.1-alpha.) - E.1. Configuring client authorization using torrc + G.1. Configuring client authorization using torrc + + G.1.1. Hidden Service side configuration + + A hidden service that wants to enable client authorization, needs to + populate the "authorized_clients/" directory of its HiddenServiceDir + directory with the ".auth" files of its authorized clients. + + When Tor starts up with a configured onion service, Tor checks its + <HiddenServiceDir>/authorized_clients/ directory for ".auth" files, and if + any recognized and parseable such files are found, then client + authorization becomes activated for that service. + + G.1.2. Service-side bookkeeping + + This section contains more details on how onion services should be keeping + track of their client ".auth" files. - E.1.1. Hidden Service side + For the "descriptor" authentication type, the ".auth" file MUST contain + the x25519 public key of that client. Here is a suggested file format: - A hidden service that wants to perform client authorization, adds a new - option HiddenServiceAuthorizeClient to its torrc file: + <auth-type>:<key-type>:<base32-encoded-public-key> - HiddenServiceAuthorizeClient auth-type client-name,client-name,... + Here is an an example: - 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. + descriptor:x25519:OM7TGIVRYMY6PFX6GAC6ATRTA5U6WW6U7A4ZNHQDI6OVL52XVV2Q - 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. + Tor SHOULD ignore lines it does not recognize. + Tor SHOULD ignore files that don't use the ".auth" suffix. - 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. + G.1.3. Client side configuration - 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. + A client who wants to register client authorization data for onion + services needs to add the following line to their torrc to indicate the + directory which hosts ".auth_private" files containing client-side + credentials for onion services: - E.1.2. Client side + ClientOnionAuthDir <DIR> - A client who wants to register client authorization data for a hidden service - needs to add the following line to their torrc: + The <DIR> contains a file with the suffix ".auth_private" for each onion + service the client is authorized with. Tor should scan the directory for + ".auth_private" files to find which onion services require client + authorization from this client. - HidServAuth onion-address x25519-private-key ed25519-private-key + For the "descriptor" auth-type, a ".auth_private" file contains the + private x25519 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. + <onion-address>:descriptor:x25519:<base32-encoded-privkey> - 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 party tool + for which the public key needs to be transferred to the service operator + in a secure out-of-band way. The third party tool SHOULD add appropriate + headers to the private key file to ensure that users won't accidentally + give out their private key. - E.2. Configuring client authorization using the control port + G.2. Configuring client authorization using the control port - E.2.1. Service side + G.2.1. Service side A hidden service also has the option to configure authorized clients using the control port. The idea is that hidden service operators can use @@ -2375,7 +2394,7 @@ Appendix E. Managing authorized client data [CLIENT-AUTH-MGMT] Hidden services who use the control port interface for client auth need to perform their own key management. - E.2.2. Client side + G.2.2. Client side There should also be a control port interface for clients to register authorization data for hidden services without having to use the |