diff --git a/doc/spec/rend-spec.txt b/doc/spec/rend-spec.txt index daaacc233e..cab97097bc 100644 --- a/doc/spec/rend-spec.txt +++ b/doc/spec/rend-spec.txt @@ -627,14 +627,14 @@ g^x Diffie-Hellman data, part 1 [128 octets] OR (in the v3 intro protocol) VER Version byte: set to 3. [1 octet] - AUTHT Auth type [1 octet] + AUTHT The auth type that is used [1 octet] AUTHL Length of auth data [2 octets] AUTHD Auth data [variable] TS A timestamp [4 octets] IP Rendezvous point's address [4 octets] PORT Rendezvous point's OR port [2 octets] ID Rendezvous point identity ID [20 octets] - KLEN Length of onion key [2 octets] + KLEN Length of onion key [2 octets] KEY Rendezvous point onion key [KLEN octets] RC Rendezvous cookie [20 octets] g^x Diffie-Hellman data, part 1 [128 octets] @@ -736,7 +736,181 @@ 2. Authentication and authorization. -Foo. + The rendezvous protocol as described in Section 1 provides a few options + for implementing client-side authorization. There are two steps in the + rendezvous protocol that can be used for performing client authorization: + when downloading and decrypting parts of the hidden service descriptor and + at Bob's Tor client before contacting the rendezvous point. A service + provider can restrict access to his service at these two points to + authorized clients only. + + There are currently two authorization protocols specified that are + described in more detail below: + + 1. The first protocol allows a service provider to restrict access + to clients with a previously received secret key only, but does not + attempt to hide service activity from others. + + 2. The second protocol, albeit being feasible for a limited set of about + 16 clients, performs client authorization and hides service activity + from everyone but the authorized clients. + +2.1. Service with large-scale client authorization + + The first client authorization protocol aims at performing access control + while consuming as few additional resources as possible. A service + provider should be able to permit access to a large number of clients + while denying access for everyone else. However, the price for + scalability is that the service won't be able to hide its activity from + unauthorized or formerly authorized clients. + + The main idea of this protocol is to encrypt the introduction-point part + in hidden service descriptors to authorized clients using symmetric keys. + This ensures that nobody else but authorized clients can learn which + introduction points a service currently uses, nor can someone send a + valid INTRODUCE1 message without knowing the introduction key. Therefore, + a subsequent authorization at the introduction point is not required. + + A service provider generates symmetric "descriptor cookies" for his + clients and distributes them outside of Tor. The suggested key size is + 128 bits, so that descriptor cookies can be encoded in 22 base64 chars + (which can hold up to 22 * 5 = 132 bits, leaving 4 bits to encode the + authorization type (here: "0") and allow a client to distinguish this + authorization protocol from others like the one proposed below). + Typically, the contact information for a hidden service using this + authorization protocol looks like this: + + v2cbb2l4lsnpio4q.onion Ll3X7Xgz9eHGKCCnlFH0uz + + When generating a hidden service descriptor, the service encrypts the + introduction-point part with a single randomly generated symmetric + 128-bit session key using AES-CTR as described for v2 hidden service + descriptors in rend-spec. Afterwards, the service encrypts the session + key to all descriptor cookies using AES. Authorized client should be able + to efficiently find the session key that is encrypted for him/her, so + that 4 octet long client ID are generated consisting of descriptor cookie + and initialization vector. Descriptors always contain a number of + encrypted session keys that is a multiple of 16 by adding fake entries. + Encrypted session keys are ordered by client IDs in order to conceal + addition or removal of authorized clients by the service provider. + + ATYPE Authorization type: set to 1. [1 octet] + ALEN Number of clients := 1 + ((clients - 1) div 16) [1 octet] + for each symmetric descriptor cookie: + ID Client ID: H(descriptor cookie | IV)[:4] [4 octets] + SKEY Session key encrypted with descriptor cookie [16 octets] + (end of client-specific part) + RND Random data [(15 - ((clients - 1) mod 16)) * 20 octets] + IV AES initialization vector [16 octets] + IPOS Intro points, encrypted with session key [remaining octets] + + An authorized client needs to configure Tor to use the descriptor cookie + when accessing the hidden service. Therefore, a user adds the contact + information that she received from the service provider to her torrc + file. Upon downloading a hidden service descriptor, Tor finds the + encrypted introduction-point part and attempts to decrypt it using the + configured descriptor cookie. (In the rare event of two or more client + IDs being equal a client tries to decrypt all of them.) + + Upon sending the introduction, the client includes her descriptor cookie + as auth type "1" in the INTRODUCE2 cell that she sends to the service. + The hidden service checks whether the included descriptor cookie is + authorized to access the service and either responds to the introduction + request, or not. + +2.2. Authorization for limited number of clients + + A second, more sophisticated client authorization protocol goes the extra + mile of hiding service activity from unauthorized clients. With all else + being equal to the preceding authorization protocol, the second protocol + publishes hidden service descriptors for each user separately and gets + along with encrypting the introduction-point part of descriptors to a + single client. This allows the service to stop publishing descriptors for + removed clients. As long as a removed client cannot link descriptors + issued for other clients to the service, it cannot derive service + activity any more. The downside of this approach is limited scalability. + Even though the distributed storage of descriptors (cf. proposal 114) + tackles the problem of limited scalability to a certain extent, this + protocol should not be used for services with more than 16 clients. (In + fact, Tor should refuse to advertise services for more than this number + of clients.) + + A hidden service generates an asymmetric "client key" and a symmetric + "descriptor cookie" for each client. The client key is used as + replacement for the service's permanent key, so that the service uses a + different identity for each of his clients. The descriptor cookie is used + to store descriptors at changing directory nodes that are unpredictable + for anyone but service and client, to encrypt the introduction-point + part, and to be included in INTRODUCE2 cells. Once the service has + created client key and descriptor cookie, he tells them to the client + outside of Tor. The contact information string looks similar to the one + used by the preceding authorization protocol (with the only difference + that it has "1" encoded as auth-type in the remaining 4 of 132 bits + instead of "0" as before). + + When creating a hidden service descriptor for an authorized client, the + hidden service uses the client key and descriptor cookie to compute + secret ID part and descriptor ID: + + secret-id-part = H(time-period | descriptor-cookie | replica) + + descriptor-id = H(client-key[:10] | secret-id-part) + + The hidden service also replaces permanent-key in the descriptor with + client-key and encrypts introduction-points with the descriptor cookie. + + ATYPE Authorization type: set to 2. [1 octet] + IV AES initialization vector [16 octets] + IPOS Intro points, encr. with descriptor cookie [remaining octets] + + When uploading descriptors, the hidden service needs to make sure that + descriptors for different clients are not uploaded at the same time (cf. + Section 1.1) which is also a limiting factor for the number of clients. + + When a client is requested to establish a connection to a hidden service + it looks up whether it has any authorization data configured for that + service. If the user has configured authorization data for authorization + protocol "2", the descriptor ID is determined as described in the last + paragraph. Upon receiving a descriptor, the client decrypts the + introduction-point part using its descriptor cookie. Further, the client + includes its descriptor cookie as auth-type "2" in INTRODUCE2 cells that + it sends to the service. + +2.3. Hidden service configuration + + A hidden service that is meant to perform client authorization adds a + new option HiddenServiceAuthorizeClient to its hidden service + configuration. This option contains the authorization type which is + either "1" for the protocol described in 2.1 or "2" for the protocol in + 2.2 and a comma-separated list of human-readable client names, so that + Tor can create authorization data for these clients: + + HiddenServiceAuthorizeClient auth-type client-name,client-name,... + + If this option is configured, HiddenServiceVersion is automatically + reconfigured to contain only version numbers of 2 or higher. + + Tor stores all generated authorization data for the authorization + protocols described in Sections 2.1 and 2.2 in a new file using the + following file format: + + "client-name" human-readable client identifier NL + "descriptor-cookie" 128-bit key ^= 22 base64 chars NL + + If the authorization protocol of Section 2.2 is used, Tor also generates + and stores the following data: + + "client-key" NL a public key in PEM format + +2.4. Client configuration + + Clients need to make their authorization data known to Tor using another + configuration option that contains a service name (mainly for the sake of + convenience), the service address, and the descriptor cookie that is + required to access a hidden service (the authorization protocol number is + encoded in the descriptor cookie): + + HidServAuth service-name service-address descriptor-cookie 3. Hidden service directory operation