« back to all changes in this revision
Viewing changes to doc/spec/rend-spec.txt
- browse files at revision 11
- compare with another revision
- download diff
- download tarball
- view history from revision 11
- Committer: Package Import Robot
- Author(s): Peter Palfrader
- Date: 2011-12-15 21:25:18 UTC
- mfrom: (1.6.1) (6.1.16 sid)
- Revision ID: package-import@ubuntu.com-20111215212518-4eaqirobd1uhcmxb
Tags: 0.2.1.32-1
New upstream version, fixing a heap overflow bug related to Tor's
SOCKS code (CVE-2011-2778).
SOCKS code (CVE-2011-2778).
- files added:
- doc/spec/README
- files removed:
- compile
- files modified:
- ChangeLog
added
removed
doc/spec/rend-spec.txt
1
$Id$
2
3
Tor Rendezvous Specification
4
5
0. Overview and preliminaries
6
7
Read
8
https://www.torproject.org/doc/design-paper/tor-design.html#sec:rendezvous
9
before you read this specification. It will make more sense.
10
11
Rendezvous points provide location-hidden services (server
12
anonymity) for the onion routing network. With rendezvous points,
13
Bob can offer a TCP service (say, a webserver) via the onion
14
routing network, without revealing the IP of that service.
15
16
Bob does this by anonymously advertising a public key for his
17
service, along with a list of onion routers to act as "Introduction
18
Points" for his service. He creates forward circuits to those
19
introduction points, and tells them about his public key. To
20
connect to Bob, Alice first builds a circuit to an OR to act as
21
her "Rendezvous Point." She then connects to one of Bob's chosen
22
introduction points, optionally provides authentication or
23
authorization information, and asks it to tell him about her Rendezvous
24
Point (RP). If Bob chooses to answer, he builds a circuit to her
25
RP, and tells it to connect him to Alice. The RP joins their
26
circuits together, and begins relaying cells. Alice's 'BEGIN'
27
cells are received directly by Bob's OP, which passes data to
28
and from the local server implementing Bob's service.
29
30
Below we describe a network-level specification of this service,
31
along with interfaces to make this process transparent to Alice
32
(so long as she is using an OP).
33
34
0.1. Notation, conventions and prerequisites
35
36
In the specifications below, we use the same notation and terminology
37
as in "tor-spec.txt". The service specified here also requires the
38
existence of an onion routing network as specified in that file.
39
40
H(x) is a SHA1 digest of x.
41
PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
42
PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
43
Public keys are all RSA, and encoded in ASN.1.
44
All integers are stored in network (big-endian) order.
45
All symmetric encryption uses AES in counter mode, except where
46
otherwise noted.
47
48
In all discussions, "Alice" will refer to a user connecting to a
49
location-hidden service, and "Bob" will refer to a user running a
50
location-hidden service.
51
52
An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
53
54
An OR is (as defined elsewhere) an "Onion Router" or Tor server.
55
56
An "Introduction point" is a Tor server chosen to be Bob's medium-term
57
'meeting place'. A "Rendezvous point" is a Tor server chosen by Alice to
58
be a short-term communication relay between her and Bob. All Tor servers
59
potentially act as introduction and rendezvous points.
60
61
0.2. Protocol outline
62
63
1. Bob->Bob's OP: "Offer IP:Port as
64
public-key-name:Port". [configuration]
65
(We do not specify this step; it is left to the implementor of
66
Bob's OP.)
67
68
2. Bob's OP generates keypair and rendezvous service descriptor:
69
"Meet public-key X at introduction point A, B, or C." (signed)
70
71
3. Bob's OP->Introduction point via Tor: [introduction setup]
72
"This pk is me."
73
74
4. Bob's OP->directory service via Tor: publishes Bob's service
75
descriptor [advertisement]
76
77
5. Out of band, Alice receives a [x.y.]z.onion:port address.
78
She opens a SOCKS connection to her OP, and requests
79
x.y.z.onion:port.
80
81
6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
82
83
7. Alice's OP chooses a rendezvous point, opens a circuit to that
84
rendezvous point, and establishes a rendezvous circuit. [rendezvous
85
setup.]
86
87
8. Alice connects to the Introduction point via Tor, and tells it about
88
her rendezvous point and optional authentication/authorization
89
information. (Encrypted to Bob.) [Introduction 1]
90
91
9. The Introduction point passes this on to Bob's OP via Tor, along the
92
introduction circuit. [Introduction 2]
93
94
10. Bob's OP decides whether to connect to Alice, and if so, creates a
95
circuit to Alice's RP via Tor. Establishes a shared circuit.
96
[Rendezvous.]
97
98
11. Alice's OP sends begin cells to Bob's OP. [Connection]
99
100
0.3. Constants and new cell types
101
102
Relay cell types
103
32 -- RELAY_ESTABLISH_INTRO
104
33 -- RELAY_ESTABLISH_RENDEZVOUS
105
34 -- RELAY_INTRODUCE1
106
35 -- RELAY_INTRODUCE2
107
36 -- RELAY_RENDEZVOUS1
108
37 -- RELAY_RENDEZVOUS2
109
38 -- RELAY_INTRO_ESTABLISHED
110
39 -- RELAY_RENDEZVOUS_ESTABLISHED
111
40 -- RELAY_COMMAND_INTRODUCE_ACK
112
113
0.4. Version overview
114
115
There are several parts in the hidden service protocol that have
116
changed over time, each of them having its own version number, whereas
117
other parts remained the same. The following list of potentially
118
versioned protocol parts should help reduce some confusion:
119
120
- Hidden service descriptor: the binary-based v0 was the default for
121
a long time, and an ascii-based v2 has been added by proposal
122
114. See 1.2.
123
124
- Hidden service descriptor propagation mechanism: currently related to
125
the hidden service descriptor version -- v0 publishes to the original
126
hs directory authorities, whereas v2 publishes to a rotating subset
127
of relays with the "hsdir" flag; see 1.4 and 1.6.
128
129
- Introduction protocol for how to generate an introduction cell:
130
v0 specified a nickname for the rendezvous point and assumed the
131
relay would know about it, whereas v2 now specifies IP address,
132
port, and onion key so the relay doesn't need to already recognize
133
it. See 1.8.
134
135
1. The Protocol
136
137
1.1. Bob configures his local OP.
138
139
We do not specify a format for the OP configuration file. However,
140
OPs SHOULD allow Bob to provide more than one advertised service
141
per OP, and MUST allow Bob to specify one or more virtual ports per
142
service. Bob provides a mapping from each of these virtual ports
143
to a local IP:Port pair.
144
145
1.2. Bob's OP generates service descriptors.
146
147
The first time the OP provides an advertised service, it generates
148
a public/private keypair (stored locally). Periodically, the OP
149
generates and publishes a descriptor of type "V0".
150
151
The "V0" descriptor contains:
152
153
KL Key length [2 octets]
154
PK Bob's public key [KL octets]
155
TS A timestamp [4 octets]
156
NI Number of introduction points [2 octets]
157
Ipt A list of NUL-terminated ORs [variable]
158
SIG Signature of above fields [variable]
159
160
KL is the length of PK, in octets.
161
TS is the number of seconds elapsed since Jan 1, 1970.
162
163
The members of Ipt may be either (a) nicknames, or (b) identity key
164
digests, encoded in hex, and prefixed with a '$'. Clients must
165
accept both forms. Services must only generate the second form.
166
Once 0.0.9.x is obsoleted, we can drop the first form.
167
168
[It's ok for Bob to advertise 0 introduction points. He might want
169
to do that if he previously advertised some introduction points,
170
and now he doesn't have any. -RD]
171
172
Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors in
173
addition to "V0" descriptors. The format of a "V2" descriptor is as
174
follows:
175
176
"rendezvous-service-descriptor" descriptor-id NL
177
178
[At start, exactly once]
179
180
Indicates the beginning of the descriptor. "descriptor-id" is a
181
periodically changing identifier of 160 bits formatted as 32 base32
182
chars that is calculated by the hidden service and its clients. If
183
the optional "descriptor-cookie" is used, this "descriptor-id"
184
cannot be computed by anyone else. (Everyone can verify that this
185
"descriptor-id" belongs to the rest of the descriptor, even without
186
knowing the optional "descriptor-cookie", as described below.) The
187
"descriptor-id" is calculated by performing the following operation:
188
189
descriptor-id =
190
H(permanent-id | H(time-period | descriptor-cookie | replica))
191
192
"permanent-id" is the permanent identifier of the hidden service,
193
consisting of 80 bits. It can be calculated by computing the hash value
194
of the public hidden service key and truncating after the first 80 bits:
195
196
permanent-id = H(public-key)[:10]
197
198
"H(time-period | descriptor-cookie | replica)" is the (possibly
199
secret) id part that is
200
necessary to verify that the hidden service is the true originator
201
of this descriptor. It can only be created by the hidden service
202
and its clients, but the "signature" below can only be created by
203
the service.
204
205
"descriptor-cookie" is an optional secret password of 128 bits that
206
is shared between the hidden service provider and its clients.
207
208
"replica" denotes the number of the non-consecutive replica.
209
210
(Each descriptor is replicated on a number of _consecutive_ nodes
211
in the identifier ring by making every storing node responsible
212
for the identifier intervals starting from its 3rd predecessor's
213
ID to its own ID. In addition to that, every service publishes
214
multiple descriptors with different descriptor IDs in order to
215
distribute them to different places on the ring. Therefore,
216
"replica" chooses one of the _non-consecutive_ replicas. -KL)
217
218
The "time-period" changes periodically depending on the global time and
219
as a function of "permanent-id". The current value for "time-period" can
220
be calculated using the following formula:
221
222
time-period = (current-time + permanent-id-byte * 86400 / 256)
223
/ 86400
224
225
"current-time" contains the current system time in seconds since
226
1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
227
(unsigned) byte of the permanent identifier (which is in network
228
order), e.g. 143. Adding the product of "permanent-id-byte" and
229
86400 (seconds per day), divided by 256, prevents "time-period" from
230
changing for all descriptors at the same time of the day. The result
231
of the overall operation is a (network-ordered) 32-bit integer, e.g.
232
13753 or 0x000035B9 with the example values given above.
233
234
"version" version-number NL
235
236
[Exactly once]
237
238
The version number of this descriptor's format. In this case: 2.
239
240
"permanent-key" NL a public key in PEM format
241
242
[Exactly once]
243
244
The public key of the hidden service which is required to verify the
245
"descriptor-id" and the "signature".
246
247
"secret-id-part" secret-id-part NL
248
249
[Exactly once]
250
251
The result of the following operation as explained above, formatted as
252
32 base32 chars. Using this secret id part, everyone can verify that
253
the signed descriptor belongs to "descriptor-id".
254
255
secret-id-part = H(time-period | descriptor-cookie | replica)
256
257
"publication-time" YYYY-MM-DD HH:MM:SS NL
258
259
[Exactly once]
260
261
A timestamp when this descriptor has been created.
262
263
"protocol-versions" version-string NL
264
265
[Exactly once]
266
267
A comma-separated list of recognized and permitted version numbers
268
for use in INTRODUCE cells; these versions are described in section
269
1.8 below.
270
271
"introduction-points" NL encrypted-string
272
273
[At most once]
274
275
A list of introduction points. If the optional "descriptor-cookie" is
276
used, this list is encrypted with AES in CTR mode with a random
277
initialization vector of 128 bits that is written to
278
the beginning of the encrypted string, and the "descriptor-cookie" as
279
secret key of 128 bits length.
280
281
The string containing the introduction point data (either encrypted
282
or not) is encoded in base64, and surrounded with
283
"-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".
284
285
The unencrypted string may begin with:
286
287
["service-authentication" auth-type NL auth-data ... reserved]
288
289
[At start, any number]
290
291
The service-specific authentication data can be used to perform
292
client authentication. This data is independent of the selected
293
introduction point as opposed to "intro-authentication" below.
294
295
Subsequently, an arbitrary number of introduction point entries may
296
follow, each containing the following data:
297
298
"introduction-point" identifier NL
299
300
[At start, exactly once]
301
302
The identifier of this introduction point: the base-32 encoded
303
hash of this introduction point's identity key.
304
305
"ip-address" ip-address NL
306
307
[Exactly once]
308
309
The IP address of this introduction point.
310
311
"onion-port" port NL
312
313
[Exactly once]
314
315
The TCP port on which the introduction point is listening for
316
incoming onion requests.
317
318
"onion-key" NL a public key in PEM format
319
320
[Exactly once]
321
322
The public key that can be used to encrypt messages to this
323
introduction point.
324
325
"service-key" NL a public key in PEM format
326
327
[Exactly once]
328
329
The public key that can be used to encrypt messages to the hidden
330
service.
331
332
["intro-authentication" auth-type NL auth-data ... reserved]
333
334
[Any number]
335
336
The introduction-point-specific authentication data can be used
337
to perform client authentication. This data depends on the
338
selected introduction point as opposed to "service-authentication"
339
above.
340
341
(This ends the fields in the encrypted portion of the descriptor.)
342
343
"signature" NL signature-string
344
345
[At end, exactly once]
346
347
A signature of all fields above with the private key of the hidden
348
service.
349
350
1.2.1. Other descriptor formats we don't use.
351
352
The V1 descriptor format was understood and accepted from
353
0.1.1.5-alpha-cvs to 0.2.0.6-alpha-dev, but no Tors generated it and
354
it was removed:
355
356
V Format byte: set to 255 [1 octet]
357
V Version byte: set to 1 [1 octet]
358
KL Key length [2 octets]
359
PK Bob's public key [KL octets]
360
TS A timestamp [4 octets]
361
PROTO Protocol versions: bitmask [2 octets]
362
NI Number of introduction points [2 octets]
363
For each introduction point: (as in INTRODUCE2 cells)
364
IP Introduction point's address [4 octets]
365
PORT Introduction point's OR port [2 octets]
366
ID Introduction point identity ID [20 octets]
367
KLEN Length of onion key [2 octets]
368
KEY Introduction point onion key [KLEN octets]
369
SIG Signature of above fields [variable]
370
371
A hypothetical "V1" descriptor, that has never been used but might
372
be useful for historical reasons, contains:
373
374
V Format byte: set to 255 [1 octet]
375
V Version byte: set to 1 [1 octet]
376
KL Key length [2 octets]
377
PK Bob's public key [KL octets]
378
TS A timestamp [4 octets]
379
PROTO Rendezvous protocol versions: bitmask [2 octets]
380
NA Number of auth mechanisms accepted [1 octet]
381
For each auth mechanism:
382
AUTHT The auth type that is supported [2 octets]
383
AUTHL Length of auth data [1 octet]
384
AUTHD Auth data [variable]
385
NI Number of introduction points [2 octets]
386
For each introduction point: (as in INTRODUCE2 cells)
387
ATYPE An address type (typically 4) [1 octet]
388
ADDR Introduction point's IP address [4 or 16 octets]
389
PORT Introduction point's OR port [2 octets]
390
AUTHT The auth type that is supported [2 octets]
391
AUTHL Length of auth data [1 octet]
392
AUTHD Auth data [variable]
393
ID Introduction point identity ID [20 octets]
394
KLEN Length of onion key [2 octets]
395
KEY Introduction point onion key [KLEN octets]
396
SIG Signature of above fields [variable]
397
398
AUTHT specifies which authentication/authorization mechanism is
399
required by the hidden service or the introduction point. AUTHD
400
is arbitrary data that can be associated with an auth approach.
401
Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
402
See section 2 of this document for details on auth mechanisms.
403
404
1.3. Bob's OP establishes his introduction points.
405
406
The OP establishes a new introduction circuit to each introduction
407
point. These circuits MUST NOT be used for anything but hidden service
408
introduction. To establish the introduction, Bob sends a
409
RELAY_ESTABLISH_INTRO cell, containing:
410
411
KL Key length [2 octets]
412
PK Bob's public key [KL octets]
413
HS Hash of session info [20 octets]
414
SIG Signature of above information [variable]
415
416
[XXX011, need to add auth information here. -RD]
417
418
To prevent replay attacks, the HS field contains a SHA-1 hash based on the
419
shared secret KH between Bob's OP and the introduction point, as
420
follows:
421
HS = H(KH | "INTRODUCE")
422
That is:
423
HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
424
(KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
425
426
Upon receiving such a cell, the OR first checks that the signature is
427
correct with the included public key. If so, it checks whether HS is
428
correct given the shared state between Bob's OP and the OR. If either
429
check fails, the OP discards the cell; otherwise, it associates the
430
circuit with Bob's public key, and dissociates any other circuits
431
currently associated with PK. On success, the OR sends Bob a
432
RELAY_INTRO_ESTABLISHED cell with an empty payload.
433
434
If a hidden service is configured to publish only v2 hidden service
435
descriptors, Bob's OP does not include its own public key in the
436
RELAY_ESTABLISH_INTRO cell, but the public key of a freshly generated
437
key pair. The OP also includes these fresh public keys in the v2 hidden
438
service descriptor together with the other introduction point
439
information. The reason is that the introduction point does not need to
440
and therefore should not know for which hidden service it works, so as
441
to prevent it from tracking the hidden service's activity. If the hidden
442
service is configured to publish both, v0 and v2 descriptors, two
443
separate sets of introduction points are established.
444
445
1.4. Bob's OP advertises his service descriptor(s).
446
447
Bob's OP opens a stream to each directory server's directory port via Tor.
448
(He may re-use old circuits for this.) Over this stream, Bob's OP makes
449
an HTTP 'POST' request, to a URL "/tor/rendezvous/publish" relative to the
450
directory server's root, containing as its body Bob's service descriptor.
451
452
Bob should upload a service descriptor for each version format that
453
is supported in the current Tor network.
454
455
Upon receiving a descriptor, the directory server checks the signature,
456
and discards the descriptor if the signature does not match the enclosed
457
public key. Next, the directory server checks the timestamp. If the
458
timestamp is more than 24 hours in the past or more than 1 hour in the
459
future, or the directory server already has a newer descriptor with the
460
same public key, the server discards the descriptor. Otherwise, the
461
server discards any older descriptors with the same public key and
462
version format, and associates the new descriptor with the public key.
463
The directory server remembers this descriptor for at least 24 hours
464
after its timestamp. At least every 18 hours, Bob's OP uploads a
465
fresh descriptor.
466
467
If Bob's OP is configured to publish v2 descriptors instead of or in
468
addition to v0 descriptors, it does so to a changing subset of all v2
469
hidden service directories instead of the authoritative directory
470
servers. Therefore, Bob's OP opens a stream via Tor to each
471
responsible hidden service directory. (He may re-use old circuits
472
for this.) Over this stream, Bob's OP makes an HTTP 'POST' request to a
473
URL "/tor/rendezvous2/publish" relative to the hidden service
474
directory's root, containing as its body Bob's service descriptor.
475
476
At any time, there are 6 hidden service directories responsible for
477
keeping replicas of a descriptor; they consist of 2 sets of 3 hidden
478
service directories with consecutive onion IDs. Bob's OP learns about
479
the complete list of hidden service directories by filtering the
480
consensus status document received from the directory authorities. A
481
hidden service directory is deemed responsible for all descriptor IDs in
482
the interval from its direct predecessor, exclusive, to its own ID,
483
inclusive; it further holds replicas for its 2 predecessors. A
484
participant only trusts its own routing list and never learns about
485
routing information from other parties.
486
487
Bob's OP publishes a new v2 descriptor once an hour or whenever its
488
content changes. V2 descriptors can be found by clients within a given
489
time period of 24 hours, after which they change their ID as described
490
under 1.2. If a published descriptor would be valid for less than 60
491
minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind
492
and the client 30 minutes ahead), Bob's OP publishes the descriptor
493
under the ID of both, the current and the next publication period.
494
495
1.5. Alice receives a x.y.z.onion address.
496
497
When Alice receives a pointer to a location-hidden service, it is as a
498
hostname of the form "z.onion" or "y.z.onion" or "x.y.z.onion", where
499
z is a base-32 encoding of a 10-octet hash of Bob's service's public
500
key, computed as follows:
501
502
1. Let H = H(PK).
503
2. Let H' = the first 80 bits of H, considering each octet from
504
most significant bit to least significant bit.
505
2. Generate a 16-character encoding of H', using base32 as defined
506
in RFC 3548.
507
508
(We only use 80 bits instead of the 160 bits from SHA1 because we
509
don't need to worry about arbitrary collisions, and because it will
510
make handling the url's more convenient.)
511
512
The string "x", if present, is the base-32 encoding of the
513
authentication/authorization required by the introduction point.
514
The string "y", if present, is the base-32 encoding of the
515
authentication/authorization required by the hidden service.
516
Omitting a string is taken to mean auth type [00 00].
517
See section 2 of this document for details on auth mechanisms.
518
519
[Yes, numbers are allowed at the beginning. See RFC 1123. -NM]
520
521
1.6. Alice's OP retrieves a service descriptor.
522
523
Alice opens a stream to a directory server via Tor, and makes an HTTP GET
524
request for the document '/tor/rendezvous/<z>', where '<z>' is replaced
525
with the encoding of Bob's public key as described above. (She may re-use
526
old circuits for this.) The directory replies with a 404 HTTP response if
527
it does not recognize <z>, and otherwise returns Bob's most recently
528
uploaded service descriptor.
529
530
If Alice's OP receives a 404 response, it tries the other directory
531
servers, and only fails the lookup if none recognize the public key hash.
532
533
Upon receiving a service descriptor, Alice verifies with the same process
534
as the directory server uses, described above in section 1.4.
535
536
The directory server gives a 400 response if it cannot understand Alice's
537
request.
538
539
Alice should cache the descriptor locally, but should not use
540
descriptors that are more than 24 hours older than their timestamp.
541
[Caching may make her partitionable, but she fetched it anonymously,
542
and we can't very well *not* cache it. -RD]
543
544
Alice's OP fetches v2 descriptors in parallel to v0 descriptors. Similarly
545
to the description in section 1.4, the OP fetches a v2 descriptor from a
546
randomly chosen hidden service directory out of the changing subset of
547
6 nodes. If the request is unsuccessful, Alice retries the other
548
remaining responsible hidden service directories in a random order.
549
Alice relies on Bob to care about a potential clock skew between the two
550
by possibly storing two sets of descriptors (see end of section 1.4).
551
552
Alice's OP opens a stream via Tor to the chosen v2 hidden service
553
directory. (She may re-use old circuits for this.) Over this stream,
554
Alice's OP makes an HTTP 'GET' request for the document
555
"/tor/rendezvous2/<z>", where z is replaced with the encoding of the
556
descriptor ID. The directory replies with a 404 HTTP response if it does
557
not recognize <z>, and otherwise returns Bob's most recently uploaded
558
service descriptor.
559
560
1.7. Alice's OP establishes a rendezvous point.
561
562
When Alice requests a connection to a given location-hidden service,
563
and Alice's OP does not have an established circuit to that service,
564
the OP builds a rendezvous circuit. It does this by establishing
565
a circuit to a randomly chosen OR, and sending a
566
RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
567
contains:
568
569
RC Rendezvous cookie [20 octets]
570
571
[XXX011 this looks like an auth mechanism. should we generalize here? -RD]
572
573
The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
574
Alice's OP.
575
576
Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the
577
RC with the circuit that sent it. It replies to Alice with an empty
578
RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success.
579
580
Alice's OP MUST NOT use the circuit which sent the cell for any purpose
581
other than rendezvous with the given location-hidden service.
582
583
1.8. Introduction: from Alice's OP to Introduction Point
584
585
Alice builds a separate circuit to one of Bob's chosen introduction
586
points, and sends it a RELAY_INTRODUCE1 cell containing:
587
588
Cleartext
589
PK_ID Identifier for Bob's PK [20 octets]
590
Encrypted to Bob's PK: (in the v0 intro protocol)
591
RP Rendezvous point's nickname [20 octets]
592
RC Rendezvous cookie [20 octets]
593
g^x Diffie-Hellman data, part 1 [128 octets]
594
OR (in the v1 intro protocol)
595
VER Version byte: set to 1. [1 octet]
596
RP Rendezvous point nick or ID [42 octets]
597
RC Rendezvous cookie [20 octets]
598
g^x Diffie-Hellman data, part 1 [128 octets]
599
OR (in the v2 intro protocol)
600
VER Version byte: set to 2. [1 octet]
601
IP Rendezvous point's address [4 octets]
602
PORT Rendezvous point's OR port [2 octets]
603
ID Rendezvous point identity ID [20 octets]
604
KLEN Length of onion key [2 octets]
605
KEY Rendezvous point onion key [KLEN octets]
606
RC Rendezvous cookie [20 octets]
607
g^x Diffie-Hellman data, part 1 [128 octets]
608
609
PK_ID is the hash of Bob's public key. RP is NUL-padded and
610
terminated. In version 0, it must contain a nickname. In version 1,
611
it must contain EITHER a nickname or an identity key digest that is
612
encoded in hex and prefixed with a '$'.
613
614
The hybrid encryption to Bob's PK works just like the hybrid
615
encryption in CREATE cells (see tor-spec). Thus the payload of the
616
version 0 RELAY_INTRODUCE1 cell on the wire will contain
617
20+42+16+20+20+128=246 bytes, and the version 1 and version 2
618
introduction formats have other sizes.
619
620
Through Tor 0.2.0.6-alpha, clients only generated the v0 introduction
621
format, whereas hidden services have understood and accepted v0,
622
v1, and v2 since 0.1.1.x. As of Tor 0.2.0.7-alpha and 0.1.2.18,
623
clients switched to using the v2 intro format.
624
625
If Alice has downloaded a v2 descriptor, she uses the contained public
626
key ("service-key") instead of Bob's public key to create the
627
RELAY_INTRODUCE1 cell as described above.
628
629
1.8.1. Other introduction formats we don't use.
630
631
We briefly speculated about using the following format for the
632
"encrypted to Bob's PK" part of the introduction, but no Tors have
633
ever generated these.
634
635
VER Version byte: set to 3. [1 octet]
636
ATYPE An address type (typically 4) [1 octet]
637
ADDR Rendezvous point's IP address [4 or 16 octets]
638
PORT Rendezvous point's OR port [2 octets]
639
AUTHT The auth type that is supported [2 octets]
640
AUTHL Length of auth data [1 octet]
641
AUTHD Auth data [variable]
642
ID Rendezvous point identity ID [20 octets]
643
KLEN Length of onion key [2 octets]
644
KEY Rendezvous point onion key [KLEN octets]
645
RC Rendezvous cookie [20 octets]
646
g^x Diffie-Hellman data, part 1 [128 octets]
647
648
1.9. Introduction: From the Introduction Point to Bob's OP
649
650
If the Introduction Point recognizes PK_ID as a public key which has
651
established a circuit for introductions as in 1.3 above, it sends the body
652
of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit.
653
(If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.)
654
655
After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an
656
empty RELAY_COMMAND_INTRODUCE_ACK cell. If no RELAY_INTRODUCE2 cell can
657
be sent, the OR replies to Alice with a non-empty cell to indicate an
658
error. (The semantics of the cell body may be determined later; the
659
current implementation sends a single '1' byte on failure.)
660
661
When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with
662
the private key for the corresponding hidden service, and extracts the
663
rendezvous point's nickname, the rendezvous cookie, and the value of g^x
664
chosen by Alice.
665
666
1.10. Rendezvous
667
668
Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
669
point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing:
670
RC Rendezvous cookie [20 octets]
671
g^y Diffie-Hellman [128 octets]
672
KH Handshake digest [20 octets]
673
674
(Bob's OP MUST NOT use this circuit for any other purpose.)
675
676
If the RP recognizes RC, it relays the rest of the cell down the
677
corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing:
678
679
g^y Diffie-Hellman [128 octets]
680
KH Handshake digest [20 octets]
681
682
(If the RP does not recognize the RC, it discards the cell and
683
tears down the circuit.)
684
685
When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which
686
has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received
687
a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor
688
circuit extend process: they establish a 60-octet string as
689
K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
690
and generate
691
KH = K[0..15]
692
Kf = K[16..31]
693
Kb = K[32..47]
694
695
Subsequently, the rendezvous point passes relay cells, unchanged, from
696
each of the two circuits to the other. When Alice's OP sends
697
RELAY cells along the circuit, it first encrypts them with the
698
Kf, then with all of the keys for the ORs in Alice's side of the circuit;
699
and when Alice's OP receives RELAY cells from the circuit, it decrypts
700
them with the keys for the ORs in Alice's side of the circuit, then
701
decrypts them with Kb. Bob's OP does the same, with Kf and Kb
702
interchanged.
703
704
1.11. Creating streams
705
706
To open TCP connections to Bob's location-hidden service, Alice's OP sends
707
a RELAY_BEGIN cell along the established circuit, using the special
708
address "", and a chosen port. Bob's OP chooses a destination IP and
709
port, based on the configuration of the service connected to the circuit,
710
and opens a TCP stream. From then on, Bob's OP treats the stream as an
711
ordinary exit connection.
712
[ Except he doesn't include addr in the connected cell or the end
713
cell. -RD]
714
715
Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open
716
multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any
717
other address along her circuit to Bob; if she does, Bob MUST reject them.
718
719
2. Authentication and authorization.
720
721
Foo.
722
723
3. Hidden service directory operation
724
725
This section has been introduced with the v2 hidden service descriptor
726
format. It describes all operations of the v2 hidden service descriptor
727
fetching and propagation mechanism that are required for the protocol
728
described in section 1 to succeed with v2 hidden service descriptors.
729
730
3.1. Configuring as hidden service directory
731
732
Every onion router that has its directory port open can decide whether it
733
wants to store and serve hidden service descriptors. An onion router which
734
is configured as such includes the "hidden-service-dir" flag in its router
735
descriptors that it sends to directory authorities.
736
737
The directory authorities include a new flag "HSDir" for routers that
738
decided to provide storage for hidden service descriptors and that
739
have been running for at least 24 hours.
740
741
3.2. Accepting publish requests
742
743
Hidden service directory nodes accept publish requests for v2 hidden service
744
descriptors and store them to their local memory. (It is not necessary to
745
make descriptors persistent, because after restarting, the onion router
746
would not be accepted as a storing node anyway, because it has not been
747
running for at least 24 hours.) All requests and replies are formatted as
748
HTTP messages. Requests are initiated via BEGIN_DIR cells directed to
749
the router's directory port, and formatted as HTTP POST requests to the URL
750
"/tor/rendezvous2/publish" relative to the hidden service directory's root,
751
containing as its body a v2 service descriptor.
752
753
A hidden service directory node parses every received descriptor and only
754
stores it when it thinks that it is responsible for storing that descriptor
755
based on its own routing table. See section 1.4 for more information on how
756
to determine responsibility for a certain descriptor ID.
757
758
3.3. Processing fetch requests
759
760
Hidden service directory nodes process fetch requests for hidden service
761
descriptors by looking them up in their local memory. (They do not need to
762
determine if they are responsible for the passed ID, because it does no harm
763
if they deliver a descriptor for which they are not (any more) responsible.)
764
All requests and replies are formatted as HTTP messages. Requests are
765
initiated via BEGIN_DIR cells directed to the router's directory port,
766
and formatted as HTTP GET requests for the document "/tor/rendezvous2/<z>",
767
where z is replaced with the encoding of the descriptor ID.
768
Loggerhead is a web-based interface for Breezy
Version: 2.0.1