From f6e0dc2a6e2f4c95d4390ea1b7672faa4dd6a982 Mon Sep 17 00:00:00 2001 From: Karsten Loesing Date: Thu, 29 Jul 2010 10:57:51 +0200 Subject: [PATCH 1/4] Rename all RELAY_* cell types to RELAY_COMMAND_*. --- doc/spec/rend-spec.txt | 94 +++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 43 deletions(-) diff --git a/doc/spec/rend-spec.txt b/doc/spec/rend-spec.txt index e5bc18e836..3de6d1dfb5 100644 --- a/doc/spec/rend-spec.txt +++ b/doc/spec/rend-spec.txt @@ -104,14 +104,14 @@ 0.3. Constants and new cell types Relay cell types - 32 -- RELAY_ESTABLISH_INTRO - 33 -- RELAY_ESTABLISH_RENDEZVOUS - 34 -- RELAY_INTRODUCE1 - 35 -- RELAY_INTRODUCE2 - 36 -- RELAY_RENDEZVOUS1 - 37 -- RELAY_RENDEZVOUS2 - 38 -- RELAY_INTRO_ESTABLISHED - 39 -- RELAY_RENDEZVOUS_ESTABLISHED + 32 -- RELAY_COMMAND_ESTABLISH_INTRO + 33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS + 34 -- RELAY_COMMAND_INTRODUCE1 + 35 -- RELAY_COMMAND_INTRODUCE2 + 36 -- RELAY_COMMAND_RENDEZVOUS1 + 37 -- RELAY_COMMAND_RENDEZVOUS2 + 38 -- RELAY_COMMAND_INTRO_ESTABLISHED + 39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED 40 -- RELAY_COMMAND_INTRODUCE_ACK 0.4. Version overview @@ -406,7 +406,7 @@ The OP establishes a new introduction circuit to each introduction point. These circuits MUST NOT be used for anything but hidden service introduction. To establish the introduction, Bob sends a - RELAY_ESTABLISH_INTRO cell, containing: + RELAY_COMMAND_ESTABLISH_INTRO cell, containing: KL Key length [2 octets] PK Introduction public key [KL octets] @@ -429,15 +429,19 @@ check fails, the OP discards the cell; otherwise, it associates the circuit with Bob's public key, and dissociates any other circuits currently associated with PK. On success, the OR sends Bob a - RELAY_INTRO_ESTABLISHED cell with an empty payload. + RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload. - Bob's OP does not include its own public key in the RELAY_ESTABLISH_INTRO - cell, but the public key of a freshly generated introduction key pair. - The OP also includes these fresh public keys in the v2 hidden service - descriptor together with the other introduction point information. The - reason is that the introduction point does not need to and therefore - should not know for which hidden service it works, so as to prevent it - from tracking the hidden service's activity. + Bob's OP uses either Bob's public key or a freshly generated, single-use + service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the + configured hidden service descriptor version. The public key is used for + v0 descriptors, the service key for v2 descriptors. In the latter case, the + service keys of all introduction points are included in the v2 hidden + service descriptor together with the other introduction point information. + The reason is that the introduction point does not need to and therefore + should not know for which hidden service it works, so as to prevent it from + tracking the hidden service's activity. If the hidden service is configured + to publish both v0 and v2 descriptors, two separate sets of introduction + points are established. 1.4. Bob's OP advertises his service descriptor(s). @@ -551,7 +555,7 @@ and Alice's OP does not have an established circuit to that service, the OP builds a rendezvous circuit. It does this by establishing a circuit to a randomly chosen OR, and sending a - RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell + RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell contains: RC Rendezvous cookie [20 octets] @@ -561,9 +565,9 @@ The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by Alice's OP. - Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the - RC with the circuit that sent it. It replies to Alice with an empty - RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success. + Upon receiving a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell, the OR associates + the RC with the circuit that sent it. It replies to Alice with an empty + RELAY_COMMAND_RENDEZVOUS_ESTABLISHED cell to indicate success. Alice's OP MUST NOT use the circuit which sent the cell for any purpose other than rendezvous with the given location-hidden service. @@ -571,7 +575,7 @@ 1.8. Introduction: from Alice's OP to Introduction Point Alice builds a separate circuit to one of Bob's chosen introduction - points, and sends it a RELAY_INTRODUCE1 cell containing: + points, and sends it a RELAY_COMMAND_INTRODUCE1 cell containing: Cleartext PK_ID Identifier for Bob's PK [20 octets] @@ -601,7 +605,7 @@ The hybrid encryption to Bob's PK works just like the hybrid encryption in CREATE cells (see tor-spec). Thus the payload of the - version 0 RELAY_INTRODUCE1 cell on the wire will contain + version 0 RELAY_COMMAND_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246 bytes, and the version 1 and version 2 introduction formats have other sizes. @@ -612,7 +616,7 @@ If Alice has downloaded a v2 descriptor, she uses the contained public key ("service-key") instead of Bob's public key to create the - RELAY_INTRODUCE1 cell as described above. + RELAY_COMMAND_INTRODUCE1 cell as described above. 1.8.1. Other introduction formats we don't use. @@ -637,24 +641,27 @@ If the Introduction Point recognizes PK_ID as a public key which has established a circuit for introductions as in 1.3 above, it sends the body - of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit. - (If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.) + of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding + circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is + discarded.) - After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an - empty RELAY_COMMAND_INTRODUCE_ACK cell. If no RELAY_INTRODUCE2 cell can - be sent, the OR replies to Alice with a non-empty cell to indicate an - error. (The semantics of the cell body may be determined later; the - current implementation sends a single '1' byte on failure.) + After sending the RELAY_COMMAND_INTRODUCE2 cell, the OR replies to Alice + with an empty RELAY_COMMAND_INTRODUCE_ACK cell. If no + RELAY_COMMAND_INTRODUCE2 cell can be sent, the OR replies to Alice with a + non-empty cell to indicate an error. (The semantics of the cell body may be + determined later; the current implementation sends a single '1' byte on + failure.) - When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with - the private key for the corresponding hidden service, and extracts the + When Bob's OP receives the RELAY_COMMAND_INTRODUCE2 cell, it decrypts it + with the private key for the corresponding hidden service, and extracts the rendezvous point's nickname, the rendezvous cookie, and the value of g^x chosen by Alice. 1.10. Rendezvous Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous - point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing: + point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit, + containing: RC Rendezvous cookie [20 octets] g^y Diffie-Hellman [128 octets] KH Handshake digest [20 octets] @@ -662,7 +669,7 @@ (Bob's OP MUST NOT use this circuit for any other purpose.) If the RP recognizes RC, it relays the rest of the cell down the - corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing: + corresponding circuit in a RELAY_COMMAND_RENDEZVOUS2 cell, containing: g^y Diffie-Hellman [128 octets] KH Handshake digest [20 octets] @@ -670,10 +677,10 @@ (If the RP does not recognize the RC, it discards the cell and tears down the circuit.) - When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which - has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received - a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor - circuit extend process: they establish a 60-octet string as + When Alice's OP receives a RELAY_COMMAND_RENDEZVOUS2 cell on a circuit which + has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet + received a reply, it uses g^y and H(g^xy) to complete the handshake as in + the Tor circuit extend process: they establish a 60-octet string as K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02]) and generate KH = K[0..15] @@ -692,7 +699,7 @@ 1.11. Creating streams To open TCP connections to Bob's location-hidden service, Alice's OP sends - a RELAY_BEGIN cell along the established circuit, using the special + a RELAY_COMMAND_BEGIN cell along the established circuit, using the special address "", and a chosen port. Bob's OP chooses a destination IP and port, based on the configuration of the service connected to the circuit, and opens a TCP stream. From then on, Bob's OP treats the stream as an @@ -700,9 +707,10 @@ [ Except he doesn't include addr in the connected cell or the end cell. -RD] - Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open - multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any - other address along her circuit to Bob; if she does, Bob MUST reject them. + Alice MAY send multiple RELAY_COMMAND_BEGIN cells along the circuit, to open + multiple streams to Bob. Alice SHOULD NOT send RELAY_COMMAND_BEGIN cells + for any other address along her circuit to Bob; if she does, Bob MUST reject + them. 2. Authentication and authorization. From 6e4c06598f08092d61edefbef97c8de610aad33a Mon Sep 17 00:00:00 2001 From: Karsten Loesing Date: Thu, 29 Jul 2010 13:33:16 +0200 Subject: [PATCH 2/4] Interchange sections 1.2 and 1.3. --- doc/spec/rend-spec.txt | 93 +++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 47 deletions(-) diff --git a/doc/spec/rend-spec.txt b/doc/spec/rend-spec.txt index 3de6d1dfb5..2a32f899ca 100644 --- a/doc/spec/rend-spec.txt +++ b/doc/spec/rend-spec.txt @@ -123,7 +123,7 @@ - Hidden service descriptor: the binary-based v0 was the default for a long time, and an ascii-based v2 has been added by proposal - 114. See 1.2. + 114. See 1.3. - Hidden service descriptor propagation mechanism: currently related to the hidden service descriptor version -- v0 publishes to the original @@ -146,7 +146,48 @@ service. Bob provides a mapping from each of these virtual ports to a local IP:Port pair. -1.2. Bob's OP generates service descriptors. +1.2. Bob's OP establishes his introduction points. + + The OP establishes a new introduction circuit to each introduction + point. These circuits MUST NOT be used for anything but hidden service + introduction. To establish the introduction, Bob sends a + RELAY_COMMAND_ESTABLISH_INTRO cell, containing: + + KL Key length [2 octets] + PK Bob's public key [KL octets] + HS Hash of session info [20 octets] + SIG Signature of above information [variable] + + [XXX011, need to add auth information here. -RD] + + To prevent replay attacks, the HS field contains a SHA-1 hash based on the + shared secret KH between Bob's OP and the introduction point, as + follows: + HS = H(KH | "INTRODUCE") + That is: + HS = H(KH | [49 4E 54 52 4F 44 55 43 45]) + (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .) + + Upon receiving such a cell, the OR first checks that the signature is + correct with the included public key. If so, it checks whether HS is + correct given the shared state between Bob's OP and the OR. If either + check fails, the OP discards the cell; otherwise, it associates the + circuit with Bob's public key, and dissociates any other circuits + currently associated with PK. On success, the OR sends Bob a + RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload. + + If a hidden service is configured to publish only v2 hidden service + descriptors, Bob's OP does not include its own public key in the + RELAY_COMMAND_ESTABLISH_INTRO cell, but the public key of a freshly + generated key pair. The OP also includes these fresh public keys in the v2 + hidden service descriptor together with the other introduction point + information. The reason is that the introduction point does not need to + and therefore should not know for which hidden service it works, so as + to prevent it from tracking the hidden service's activity. If the hidden + service is configured to publish both, v0 and v2 descriptors, two + separate sets of introduction points are established. + +1.3. Bob's OP generates service descriptors. The first time the OP provides an advertised service, it generates a public/private keypair (stored locally). @@ -332,7 +373,7 @@ A signature of all fields above with the private key of the hidden service. -1.2.1. Other descriptor formats we don't use. +1.3.1. Other descriptor formats we don't use. Support for the V0 descriptor format was dropped in 0.2.2.0-alpha-dev: @@ -401,48 +442,6 @@ Currently only AUTHT of [00 00] is supported, with an AUTHL of 0. See section 2 of this document for details on auth mechanisms. -1.3. Bob's OP establishes his introduction points. - - The OP establishes a new introduction circuit to each introduction - point. These circuits MUST NOT be used for anything but hidden service - introduction. To establish the introduction, Bob sends a - RELAY_COMMAND_ESTABLISH_INTRO cell, containing: - - KL Key length [2 octets] - PK Introduction public key [KL octets] - HS Hash of session info [20 octets] - SIG Signature of above information [variable] - - [XXX011, need to add auth information here. -RD] - - To prevent replay attacks, the HS field contains a SHA-1 hash based on the - shared secret KH between Bob's OP and the introduction point, as - follows: - HS = H(KH | "INTRODUCE") - That is: - HS = H(KH | [49 4E 54 52 4F 44 55 43 45]) - (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .) - - Upon receiving such a cell, the OR first checks that the signature is - correct with the included public key. If so, it checks whether HS is - correct given the shared state between Bob's OP and the OR. If either - check fails, the OP discards the cell; otherwise, it associates the - circuit with Bob's public key, and dissociates any other circuits - currently associated with PK. On success, the OR sends Bob a - RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload. - - Bob's OP uses either Bob's public key or a freshly generated, single-use - service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the - configured hidden service descriptor version. The public key is used for - v0 descriptors, the service key for v2 descriptors. In the latter case, the - service keys of all introduction points are included in the v2 hidden - service descriptor together with the other introduction point information. - The reason is that the introduction point does not need to and therefore - should not know for which hidden service it works, so as to prevent it from - tracking the hidden service's activity. If the hidden service is configured - to publish both v0 and v2 descriptors, two separate sets of introduction - points are established. - 1.4. Bob's OP advertises his service descriptor(s). Bob's OP opens a stream to each directory server's directory port via Tor. @@ -486,7 +485,7 @@ Bob's OP publishes a new v2 descriptor once an hour or whenever its content changes. V2 descriptors can be found by clients within a given time period of 24 hours, after which they change their ID as described - under 1.2. If a published descriptor would be valid for less than 60 + under 1.3. If a published descriptor would be valid for less than 60 minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind and the client 30 minutes ahead), Bob's OP publishes the descriptor under the ID of both, the current and the next publication period. @@ -640,7 +639,7 @@ 1.9. Introduction: From the Introduction Point to Bob's OP If the Introduction Point recognizes PK_ID as a public key which has - established a circuit for introductions as in 1.3 above, it sends the body + established a circuit for introductions as in 1.2 above, it sends the body of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is discarded.) From 9ecb64c44dd02e813c2ccd5d3a377a212b17440b Mon Sep 17 00:00:00 2001 From: Karsten Loesing Date: Thu, 29 Jul 2010 15:30:57 +0200 Subject: [PATCH 3/4] Clean up Section 1 of rend-spec.txt. --- doc/spec/rend-spec.txt | 289 ++++++++++++++++++++++------------------- 1 file changed, 156 insertions(+), 133 deletions(-) diff --git a/doc/spec/rend-spec.txt b/doc/spec/rend-spec.txt index 2a32f899ca..daaacc233e 100644 --- a/doc/spec/rend-spec.txt +++ b/doc/spec/rend-spec.txt @@ -20,11 +20,10 @@ Bob does this by anonymously advertising a public key for his service, along with a list of onion routers to act as "Introduction Points" for his service. He creates forward circuits to those - introduction points, and tells them about his public key. To + introduction points, and tells them about his service. To connect to Bob, Alice first builds a circuit to an OR to act as her "Rendezvous Point." She then connects to one of Bob's chosen - introduction points, optionally provides authentication or - authorization information, and asks it to tell him about her Rendezvous + introduction points, and asks it to tell him about her Rendezvous Point (RP). If Bob chooses to answer, he builds a circuit to her RP, and tells it to connect him to Alice. The RP joins their circuits together, and begins relaying cells. Alice's 'BEGIN' @@ -64,23 +63,21 @@ 0.2. Protocol outline - 1. Bob->Bob's OP: "Offer IP:Port as - public-key-name:Port". [configuration] + 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration] (We do not specify this step; it is left to the implementor of Bob's OP.) - 2. Bob's OP generates keypair and rendezvous service descriptor: - "Meet public-key X at introduction point A, B, or C." (signed) + 2. Bob's OP generates a long-term keypair. 3. Bob's OP->Introduction point via Tor: [introduction setup] - "This pk is me." + "This public key is (currently) associated to me." - 4. Bob's OP->directory service via Tor: publishes Bob's service - descriptor [advertisement] + 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor + [advertisement] + "Meet public-key X at introduction point A, B, or C." (signed) - 5. Out of band, Alice receives a [x.y.]z.onion:port address. - She opens a SOCKS connection to her OP, and requests - x.y.z.onion:port. + 5. Out of band, Alice receives a z.onion:port address. + She opens a SOCKS connection to her OP, and requests z.onion:port. 6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.] @@ -89,17 +86,19 @@ setup.] 8. Alice connects to the Introduction point via Tor, and tells it about - her rendezvous point and optional authentication/authorization - information. (Encrypted to Bob.) [Introduction 1] + her rendezvous point. (Encrypted to Bob.) [Introduction 1] 9. The Introduction point passes this on to Bob's OP via Tor, along the introduction circuit. [Introduction 2] 10. Bob's OP decides whether to connect to Alice, and if so, creates a circuit to Alice's RP via Tor. Establishes a shared circuit. - [Rendezvous.] + [Rendezvous 1] - 11. Alice's OP sends begin cells to Bob's OP. [Connection] + 11. The Rendezvous point forwards Bob's confirmation to Alice's OP. + [Rendezvous 2] + + 12. Alice's OP sends begin cells to Bob's OP. [Connection] 0.3. Constants and new cell types @@ -121,14 +120,14 @@ other parts remained the same. The following list of potentially versioned protocol parts should help reduce some confusion: - - Hidden service descriptor: the binary-based v0 was the default for - a long time, and an ascii-based v2 has been added by proposal - 114. See 1.3. + - Hidden service descriptor: the binary-based v0 was the default for a + long time, and an ASCII-based v2 has been added by proposal 114. The + v0 descriptor format has been deprecated in 0.2.2.1-alpha. See 1.3. - Hidden service descriptor propagation mechanism: currently related to the hidden service descriptor version -- v0 publishes to the original hs directory authorities, whereas v2 publishes to a rotating subset - of relays with the "hsdir" flag; see 1.4 and 1.6. + of relays with the "HSDir" flag; see 1.4 and 1.6. - Introduction protocol for how to generate an introduction cell: v0 specified a nickname for the rendezvous point and assumed the @@ -148,17 +147,21 @@ 1.2. Bob's OP establishes his introduction points. + The first time the OP provides an advertised service, it generates + a public/private keypair (stored locally). + + The OP choses a small number of Tor servers as introduction points. The OP establishes a new introduction circuit to each introduction point. These circuits MUST NOT be used for anything but hidden service introduction. To establish the introduction, Bob sends a RELAY_COMMAND_ESTABLISH_INTRO cell, containing: KL Key length [2 octets] - PK Bob's public key [KL octets] + PK Bob's public key or service key [KL octets] HS Hash of session info [20 octets] SIG Signature of above information [variable] - [XXX011, need to add auth information here. -RD] + KL is the length of PK, in octets. To prevent replay attacks, the HS field contains a SHA-1 hash based on the shared secret KH between Bob's OP and the introduction point, as @@ -176,24 +179,46 @@ currently associated with PK. On success, the OR sends Bob a RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload. - If a hidden service is configured to publish only v2 hidden service - descriptors, Bob's OP does not include its own public key in the - RELAY_COMMAND_ESTABLISH_INTRO cell, but the public key of a freshly - generated key pair. The OP also includes these fresh public keys in the v2 - hidden service descriptor together with the other introduction point - information. The reason is that the introduction point does not need to - and therefore should not know for which hidden service it works, so as - to prevent it from tracking the hidden service's activity. If the hidden - service is configured to publish both, v0 and v2 descriptors, two - separate sets of introduction points are established. + Bob's OP uses either Bob's public key or a freshly generated, single-use + service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the + configured hidden service descriptor version. The public key is used for + v0 descriptors, the service key for v2 descriptors. In the latter case, the + service keys of all introduction points are included in the v2 hidden + service descriptor together with the other introduction point information. + The reason is that the introduction point does not need to and therefore + should not know for which hidden service it works, so as to prevent it from + tracking the hidden service's activity. If the hidden service is configured + to publish both v0 and v2 descriptors, two separate sets of introduction + points are established. 1.3. Bob's OP generates service descriptors. - The first time the OP provides an advertised service, it generates - a public/private keypair (stored locally). + For versions before 0.2.2.1-alpha, Bob's OP periodically generates and + publishes a descriptor of type "V0". - Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors. The - format of a "V2" descriptor is as follows: + The "V0" descriptor contains: + + KL Key length [2 octets] + PK Bob's public key [KL octets] + TS A timestamp [4 octets] + NI Number of introduction points [2 octets] + Ipt A list of NUL-terminated ORs [variable] + SIG Signature of above fields [variable] + + TS is the number of seconds elapsed since Jan 1, 1970. + + The members of Ipt may be either (a) nicknames, or (b) identity key + digests, encoded in hex, and prefixed with a '$'. Clients must + accept both forms. Services must only generate the second form. + Once 0.0.9.x is obsoleted, we can drop the first form. + + [It's ok for Bob to advertise 0 introduction points. He might want + to do that if he previously advertised some introduction points, + and now he doesn't have any. -RD] + + Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors in + addition to (or instead of) "V0" descriptors. The format of a "V2" + descriptor is as follows: "rendezvous-service-descriptor" descriptor-id NL @@ -201,11 +226,7 @@ Indicates the beginning of the descriptor. "descriptor-id" is a periodically changing identifier of 160 bits formatted as 32 base32 - chars that is calculated by the hidden service and its clients. If - the optional "descriptor-cookie" is used, this "descriptor-id" - cannot be computed by anyone else. (Everyone can verify that this - "descriptor-id" belongs to the rest of the descriptor, even without - knowing the optional "descriptor-cookie", as described below.) The + chars that is calculated by the hidden service and its clients. The "descriptor-id" is calculated by performing the following operation: descriptor-id = @@ -218,28 +239,16 @@ permanent-id = H(public-key)[:10] "H(time-period | descriptor-cookie | replica)" is the (possibly - secret) id part that is - necessary to verify that the hidden service is the true originator - of this descriptor. It can only be created by the hidden service - and its clients, but the "signature" below can only be created by - the service. + secret) id part that is necessary to verify that the hidden service is + the true originator of this descriptor and that is therefore contained + in the descriptor, too. The descriptor ID can only be created by the + hidden service and its clients, but the "signature" below can only be + created by the service. - "descriptor-cookie" is an optional secret password of 128 bits that - is shared between the hidden service provider and its clients. + "time-period" changes periodically as a function of time and - "replica" denotes the number of the non-consecutive replica. - - (Each descriptor is replicated on a number of _consecutive_ nodes - in the identifier ring by making every storing node responsible - for the identifier intervals starting from its 3rd predecessor's - ID to its own ID. In addition to that, every service publishes - multiple descriptors with different descriptor IDs in order to - distribute them to different places on the ring. Therefore, - "replica" chooses one of the _non-consecutive_ replicas. -KL) - - The "time-period" changes periodically depending on the global time and - as a function of "permanent-id". The current value for "time-period" can - be calculated using the following formula: + "permanent-id". The current value for "time-period" can be calculated + using the following formula: time-period = (current-time + permanent-id-byte * 86400 / 256) / 86400 @@ -253,6 +262,15 @@ of the overall operation is a (network-ordered) 32-bit integer, e.g. 13753 or 0x000035B9 with the example values given above. + "descriptor-cookie" is an optional secret password of 128 bits that + is shared between the hidden service provider and its clients. If the + descriptor-cookie is left out, the input to the hash function is 128 + bits shorter. + + "replica" denotes the number of the replica. A service publishes + multiple descriptors with different descriptor IDs in order to + distribute them to different places on the ring. + "version" version-number NL [Exactly once] @@ -306,13 +324,16 @@ The unencrypted string may begin with: - ["service-authentication" auth-type NL auth-data ... reserved] + "service-authentication" auth-type auth-data NL - [At start, any number] + [Any number] The service-specific authentication data can be used to perform client authentication. This data is independent of the selected - introduction point as opposed to "intro-authentication" below. + introduction point as opposed to "intro-authentication" below. The + format of auth-data (base64-encoded or PEM format) depends on + auth-type. See section 2 of this document for details on auth + mechanisms. Subsequently, an arbitrary number of introduction point entries may follow, each containing the following data: @@ -351,14 +372,16 @@ The public key that can be used to encrypt messages to the hidden service. - ["intro-authentication" auth-type NL auth-data ... reserved] + "intro-authentication" auth-type auth-data NL [Any number] The introduction-point-specific authentication data can be used to perform client authentication. This data depends on the selected introduction point as opposed to "service-authentication" - above. + above. The format of auth-data (base64-encoded or PEM format) + depends on auth-type. See section 2 of this document for details + on auth mechanisms. (This ends the fields in the encrypted portion of the descriptor.) @@ -444,13 +467,15 @@ 1.4. Bob's OP advertises his service descriptor(s). - Bob's OP opens a stream to each directory server's directory port via Tor. - (He may re-use old circuits for this.) Over this stream, Bob's OP makes - an HTTP 'POST' request, to a URL "/tor/rendezvous/publish" relative to the - directory server's root, containing as its body Bob's service descriptor. + Bob's OP advertises his service descriptor to a fixed set of v0 hidden + service directory servers and/or a changing subset of all v2 hidden service + directories. - Bob should upload a service descriptor for each version format that - is supported in the current Tor network. + For versions before 0.2.2.1-alpha, Bob's OP opens a stream to each v0 + directory server's directory port via Tor. (He may re-use old circuits for + this.) Over this stream, Bob's OP makes an HTTP 'POST' request, to a URL + "/tor/rendezvous/publish" relative to the directory server's root, + containing as its body Bob's service descriptor. Upon receiving a descriptor, the directory server checks the signature, and discards the descriptor if the signature does not match the enclosed @@ -464,11 +489,12 @@ after its timestamp. At least every 18 hours, Bob's OP uploads a fresh descriptor. - Bob's OP publishes v2 descriptors to a changing subset of all v2 hidden - service directories. Therefore, Bob's OP opens a stream via Tor to each - responsible hidden service directory. (He may re-use old circuits - for this.) Over this stream, Bob's OP makes an HTTP 'POST' request to a - URL "/tor/rendezvous2/publish" relative to the hidden service + If Bob's OP is configured to publish v2 descriptors, it does so to a + changing subset of all v2 hidden service directories instead of the + authoritative directory servers. Therefore, Bob's OP opens a stream via + Tor to each responsible hidden service directory. (He may re-use old + circuits for this.) Over this stream, Bob's OP makes an HTTP 'POST' + request to a URL "/tor/rendezvous2/publish" relative to the hidden service directory's root, containing as its body Bob's service descriptor. At any time, there are 6 hidden service directories responsible for @@ -490,49 +516,36 @@ and the client 30 minutes ahead), Bob's OP publishes the descriptor under the ID of both, the current and the next publication period. -1.5. Alice receives a x.y.z.onion address. +1.5. Alice receives a z.onion address. When Alice receives a pointer to a location-hidden service, it is as a - hostname of the form "z.onion" or "y.z.onion" or "x.y.z.onion", where - z is a base-32 encoding of a 10-octet hash of Bob's service's public - key, computed as follows: + hostname of the form "z.onion", where z is a base-32 encoding of a + 10-octet hash of Bob's service's public key, computed as follows: 1. Let H = H(PK). 2. Let H' = the first 80 bits of H, considering each octet from most significant bit to least significant bit. - 2. Generate a 16-character encoding of H', using base32 as defined + 3. Generate a 16-character encoding of H', using base32 as defined in RFC 3548. (We only use 80 bits instead of the 160 bits from SHA1 because we don't need to worry about arbitrary collisions, and because it will make handling the url's more convenient.) - The string "x", if present, is the base-32 encoding of the - authentication/authorization required by the introduction point. - The string "y", if present, is the base-32 encoding of the - authentication/authorization required by the hidden service. - Omitting a string is taken to mean auth type [00 00]. - See section 2 of this document for details on auth mechanisms. - [Yes, numbers are allowed at the beginning. See RFC 1123. -NM] 1.6. Alice's OP retrieves a service descriptor. - Similarly to the description in section 1.4, Alice's OP fetches a v2 - descriptor from a randomly chosen hidden service directory out of the - changing subset of 6 nodes. If the request is unsuccessful, Alice retries - the other remaining responsible hidden service directories in a random - order. Alice relies on Bob to care about a potential clock skew between - the two by possibly storing two sets of descriptors (see end of section - 1.4). + Alice's OP fetches the service descriptor from the fixed set of v0 hidden + service directory servers and/or a changing subset of all v2 hidden service + directories. - Alice's OP opens a stream via Tor to the chosen v2 hidden service - directory. (She may re-use old circuits for this.) Over this stream, - Alice's OP makes an HTTP 'GET' request for the document - "/tor/rendezvous2/", where z is replaced with the encoding of the - descriptor ID. The directory replies with a 404 HTTP response if it does - not recognize , and otherwise returns Bob's most recently uploaded - service descriptor. + For versions before 0.2.2.1-alpha, Alice's OP opens a stream to a directory + server via Tor, and makes an HTTP GET request for the document + '/tor/rendezvous/', where '' is replaced with the encoding of Bob's + public key as described above. (She may re-use old circuits for this.) The + directory replies with a 404 HTTP response if it does not recognize , + and otherwise returns Bob's most recently uploaded service descriptor. If Alice's OP receives a 404 response, it tries the other directory servers, and only fails the lookup if none recognize the public key hash. @@ -548,6 +561,24 @@ [Caching may make her partitionable, but she fetched it anonymously, and we can't very well *not* cache it. -RD] + If Alice's OP is running 0.2.1.10-alpha or higher, it fetches v2 hidden + service descriptors. Versions before 0.2.2.1-alpha are fetching both v0 and + v2 descriptors in parallel. Similar to the description in section 1.4, + Alice's OP fetches a v2 descriptor from a randomly chosen hidden service + directory out of the changing subset of 6 nodes. If the request is + unsuccessful, Alice retries the other remaining responsible hidden service + directories in a random order. Alice relies on Bob to care about a potential + clock skew between the two by possibly storing two sets of descriptors (see + end of section 1.4). + + Alice's OP opens a stream via Tor to the chosen v2 hidden service + directory. (She may re-use old circuits for this.) Over this stream, + Alice's OP makes an HTTP 'GET' request for the document + "/tor/rendezvous2/", where z is replaced with the encoding of the + descriptor ID. The directory replies with a 404 HTTP response if it does + not recognize , and otherwise returns Bob's most recently uploaded + service descriptor. + 1.7. Alice's OP establishes a rendezvous point. When Alice requests a connection to a given location-hidden service, @@ -559,8 +590,6 @@ RC Rendezvous cookie [20 octets] - [XXX011 this looks like an auth mechanism. should we generalize here? -RD] - The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by Alice's OP. @@ -596,11 +625,28 @@ KEY Rendezvous point onion key [KLEN octets] RC Rendezvous cookie [20 octets] 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] + 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] + KEY Rendezvous point onion key [KLEN octets] + RC Rendezvous cookie [20 octets] + g^x Diffie-Hellman data, part 1 [128 octets] - PK_ID is the hash of Bob's public key. RP is NUL-padded and - terminated. In version 0, it must contain a nickname. In version 1, - it must contain EITHER a nickname or an identity key digest that is - encoded in hex and prefixed with a '$'. + PK_ID is the hash of Bob's public key or the service key, depending on the + hidden service descriptor version. In case of a v0 descriptor, Alice's OP + uses Bob's public key. If Alice has downloaded a v2 descriptor, she uses + the contained public key ("service-key"). + + RP is NUL-padded and terminated. In version 0 of the intro protocol, RP + must contain a nickname. In version 1, it must contain EITHER a nickname or + an identity key digest that is encoded in hex and prefixed with a '$'. The hybrid encryption to Bob's PK works just like the hybrid encryption in CREATE cells (see tor-spec). Thus the payload of the @@ -613,29 +659,6 @@ v1, and v2 since 0.1.1.x. As of Tor 0.2.0.7-alpha and 0.1.2.18, clients switched to using the v2 intro format. - If Alice has downloaded a v2 descriptor, she uses the contained public - key ("service-key") instead of Bob's public key to create the - RELAY_COMMAND_INTRODUCE1 cell as described above. - -1.8.1. Other introduction formats we don't use. - - We briefly speculated about using the following format for the - "encrypted to Bob's PK" part of the introduction, but no Tors have - ever generated these. - - VER Version byte: set to 3. [1 octet] - ATYPE An address type (typically 4) [1 octet] - ADDR Rendezvous point's IP address [4 or 16 octets] - PORT Rendezvous point's OR port [2 octets] - AUTHT The auth type that is supported [2 octets] - AUTHL Length of auth data [1 octet] - AUTHD Auth data [variable] - ID Rendezvous point identity ID [20 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] - 1.9. Introduction: From the Introduction Point to Bob's OP If the Introduction Point recognizes PK_ID as a public key which has From 1cf6da821c3aa27e8d81c674b9c1c63d951dd0cc Mon Sep 17 00:00:00 2001 From: Karsten Loesing Date: Thu, 29 Jul 2010 16:07:00 +0200 Subject: [PATCH 4/4] Add two authoritzation protocols to rend-spec.txt. --- doc/spec/rend-spec.txt | 180 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 3 deletions(-) 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