dir-spec.txt 57.6 KB
Newer Older
1
2
$Id$

3
                      Tor directory protocol, version 3
4
5
6

0. Scope and preliminaries

7
8
   This directory protocol is used by Tor version 0.2.0.x-alpha and later.
   See dir-spec-v1.txt for information on the protocol used up to the
9
10
   0.1.0.x series, and dir-spec-v2.txt for information on the protocol
   used by the 0.1.1.x and 0.1.2.x series.
11
12
13
14
15
16
17
18
19
20
21
22
23

   Caches and authorities must still support older versions of the
   directory protocols, until the versions of Tor that require them are
   finally out of commission.  See Section XXXX on backward compatibility.

   This document merges and supersedes the following proposals:

       101  Voting on the Tor Directory System
       103  Splitting identity key from regularly used signing key
       104  Long and Short Router Descriptors

   AS OF 3 MAY 2007, THIS SPECIFICATION HAS NOT YET BEEN COMPLETELY
   IMPLEMENTED.
24

25
0.1. History
26

27
28
29
   The earliest versions of Onion Routing shipped with a list of known
   routers and their keys.  When the set of routers changed, users needed to
   fetch a new list.
30

31
32
   The Version 1 Directory protocol
   --------------------------------
33

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
   [XXX say which versions added what.]

   Early versions of Tor introduced "Directory authorities": servers that
   served signed "directory" documents containing a list of signed "router
   descriptors", along with short summary of the status of each router.
   Thus, clients could get up-to-date information on the state of the
   network automatically, and be certain that they list they were getting
   was attested by a trusted directory authority.

   Later versions added directory caches, which download directories from
   the authorities and serve them to clients.  Non-caches fetch from the
   caches in preference to fetching from the authorities, thus distributing
   bandwidth requirements.

   Also added during the version 1 directory protocol were "router status"
   documents: short documents that listed only the up/down status of the
   routers on the network, rather than a complete list of all the
   descriptors.  Clients and caches would fetch these documents far more
   frequently than they would fetch full directories.

   The Version 2 Directory Protocol
   --------------------------------

   During the Tor 0.1.1.x series, Tor revised its handling of directory
   documents in order to address two major problems:

      * Directories had grown quite large (over 1MB), and most directory
        downloads consisted mainly of router descriptors that clients
        already had.

      * Every directory authorities was a trust bottleneck: if a single
        directory authority lied, it could make clients believe for a time
        an arbitrarily distorted view of the Tor network.  (Clients
        trusted the most recent signed document they downloaded.) Thus,
        adding more authorities would make the system less secure, not
        more.

   To address these, we extended the directory protocol so that
   authorities now published signed "network status" documents.  Each
   network status listed, for every router in the network: a hash of its
   identity key, a hash of its most recent descriptor, and a summary of
   what the authority believed about its status.  Clients would download
   the authorities' network status documents in turn, and believe
   statements about routers iff they were attested to by more than half of
   the authorities.

   Instead of downloading all router descriptors at once, clients
   downloaded only the descriptors that they did not have.  Descriptors
   were indexed by their digests, in order to prevent malicious caches
   from giving different versions of a router descriptor to different
   clients.

   Routers began working harder to upload new descriptors only when their
   contents were substantially changed.


0.2. Goals of the version 3 protocol

   Version 3 of the Tor directory protocol tries to solve the following
   issues:

      * A great deal of bandwidth used to transmit router descriptors was
        used by two fields that are not actually used by Tor routers.  We
        save about 60% by moving them into a separate document that most
        clients do not fetch or use.

      * It was possible under certain perverse circumstances for clients
        to download an unusual set of network status documents, thus
        partitioning themselves from clients who have a more recent and/or
        typical set of documents.  Even under the best of circumstances,
        clients were sensitive to the ages of the network status documents
        they downloaded.  Therefore, instead of having the clients
        correlate multiple network status documents, we have the
        authorities collectively vote on a single consensus network status
        document.

      * The most sensitive data in the entire network (the identity keys
        of the directory authorities) needed to be stored unencrypted so
Roger Dingledine's avatar
Roger Dingledine committed
112
113
114
        that the authorities can sign network-status documents on the fly.
        Now, the authorities' identity keys are stored offline, and used
        to certify medium-term signing keys that can be rotated.
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

0.3. Some Remaining questions

   Things we could solve on a v3 timeframe:

     The SHA-1 hash is showing its age.  We should do something about our
     dependency on it.  We could probably future-proof ourselves here in
     this revision, at least so far as documents from the authorities are
     concerned.

     Too many things about the authorities are hardcoded by IP.

     Perhaps we should start accepting longer identity keys for routers
     too.

   Things to solve eventually:

     Requiring every client to know about every router won't scale forever.

     Requiring every directory cache to know every router won't scale
     forever.
136

137

138
139
1. Outline

140
   There is a small set (say, around 5-10) of semi-trusted directory
141
   authorities.  A default list of authorities is shipped with the Tor
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
   software.  Users can change this list, but are encouraged not to do so,
   in order to avoid partitioning attacks.

   Every authority has a very-secret, long-term "Authority Identity Key".
   This is stored encrypted and/or offline, and is used to sign "key
   certificate" documents.  Every key certificate contains a medium-term
   (3-12 months) "authority signing key", that is used by the authority to
   sign other directory information.  (Note that the authority identity
   key is distinct from the router identity key that the authority uses
   in its role as an ordinary router.)

   Routers periodically upload signed "routers descriptors" to the
   directory authorities describing their keys, capabilities, and other
   information.  Routers may also upload signed "extra info documents"
   containing information that is not required for the Tor protocol.
   Directory authorities serve router descriptors indexed by router
   identity, or by hash of the descriptor.

   Routers may act as directory caches to reduce load on the directory
   authorities.  They announce this in their descriptors.

   Periodically, each directory authority periodically generates a view of
   the current descriptors and status for known routers.  They send a
   signed summary of this view (a "status vote") to the other
   authorities.  The authorities compute the result of this vote, and sign
   a "consensus status" document containing the result of the vote.

   Directory caches download, cache, and re-serve consensus documents.

   Clients, directory caches, and directory authorities all use consensus
   documents to find out when their list of routers is out-of-date.
   (Directory authorities also use vote statuses.) If it is, they download
   any missing router descriptors.  Clients download missing descriptors
175
   from caches; caches and authorities download from authorities.
176
177
178
   Descriptors are downloaded by the hash of the descriptor, not by the
   server's identity key: this prevents servers from attacking clients by
   giving them descriptors nobody else uses.
179
180
181

   All directory information is uploaded and downloaded with HTTP.

182
183
   [Authorities also generate and caches also cache documents produced and
   used by earlier versions of this protocol; see section XXX for notes.]
184

185
1.1. What's different from version 2?
186

187
188
189
   Clients used to download a multiple network status documents,
   corresponding roughly to "status votes" above.  They would compute the
   result of the vote on the client side.
190

191
192
193
   Authorities used sign documents using the same private keys they used
   for their roles as routers.  This forced them to keep these extremely
   sensitive keys in memory unencrypted.
194

195
196
   All of the information in extra-info documents used to be kept in the
   main descriptors.
197
198


199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
1.2. Document meta-format

  Router descriptors, directories, and running-routers documents all obey the
  following lightweight extensible information format.

  The highest level object is a Document, which consists of one or more
  Items.  Every Item begins with a KeywordLine, followed by one or more
  Objects. A KeywordLine begins with a Keyword, optionally followed by
  whitespace and more non-newline characters, and ends with a newline.  A
  Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  An Object is a block of encoded data in pseudo-Open-PGP-style
  armor. (cf. RFC 2440)

  More formally:

    Document ::= (Item | NL)+
    Item ::= KeywordLine Object*
    KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
    Keyword = KeywordChar+
    KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
    ArgumentChar ::= any printing ASCII character except NL.
    WS = (SP | TAB)+
    Object ::= BeginLine Base-64-encoded-data EndLine
    BeginLine ::= "-----BEGIN " Keyword "-----" NL
    EndLine ::= "-----END " Keyword "-----" NL
224

225
226
    The BeginLine and EndLine of an Object must use the same keyword.

227
228
229
230
231
232
233
234
235
236
237
238
239
  When interpreting a Document, software MUST ignore any KeywordLine that
  starts with a keyword it doesn't recognize; future implementations MUST NOT
  require current clients to understand any KeywordLine not currently
  described.

  The "opt" keyword was used until Tor 0.1.2.5-alpha for non-critical future
  extensions.  All implementations MUST ignore any item of the form "opt
  keyword ....." when they would not recognize "keyword ....."; and MUST
  treat "opt keyword ....."  as synonymous with "keyword ......" when keyword
  is recognized.

  Implementations before 0.1.2.5-alpha rejected any document with a
  KeywordLine that started with a keyword that they didn't recognize.
240
241
242
243
244
  When generating documents that need to be read by older versions of Tor,
  implementations MUST prefix items not recognized by older versions of
  Tor with an "opt" until those versions of Tor are obsolete.  [Note that
  key certificates, status vote documents, extra info documents, and
  status consensus documents will never by read by older versions of Tor.]
245

246
247
248
249
250
  Other implementations that want to extend Tor's directory format MAY
  introduce their own items.  The keywords for extension items SHOULD start
  with the characters "x-" or "X-", to guarantee that they will not conflict
  with keywords used by future versions of Tor.

251
252
253
254
255
256
257
258
259
260
  In our document descriptions below, we tag Items with a multiplicity in
  brackets.  Possible tags are:

    "At start, exactly once": These items MUST occur in every instance of
      the document type, and MUST appear exactly once, and MUST be the
      first item in their documents.

    "Exactly once": These items MUST occur exactly one time in every
      instance of the document type.

Roger Dingledine's avatar
Roger Dingledine committed
261
    "At end, exactly once": These items MUST occur in every instance of
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
      the document type, and MUST appear exactly once, and MUST be the
      last item in their documents.

    "At most once": These items MAY occur zero or one times in any
      instance of the document type, but MUST NOT occur more than once.

    "Any number": These items MAY occur zero, one, or more times in any
      instance of the document type.

    "Once or more": These items MUST occur at least once in any instance
      of the document type, and MAY occur more.

1.3. Signing documents

   Every signable document below is signed in a similar manner, using a
   given "Initial Item", a final "Signature Item", a digest algorithm, and
   a signing key.

   The Initial Item must be the first item in the document.
281

282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
   The Signature Item has the following format:

     <signature item keyword> [arguments] NL SIGNATURE NL

   The "SIGNATURE" Object contains a signature (using the signing key) of
   the PKCS1-padded digest of the entire document, taken from the
   beginning of the Initial item, through the newline after the Signature
   Item's keyword and its arguments.

   Unless otherwise, the digest algorithm is SHA-1.

   All documents are invalid unless signed with the correct signing key.

   The "Digest" of a document, unless stated otherwise, is its digest *as
   signed by this signature scheme*.

2. Router operation and formats

   ORs SHOULD generate a new router descriptor and a new extra-info
   document whenever any of the following events have occurred:
302

303
      - A period of time (18 hrs by default) has passed since the last
304
305
306
307
308
        time a descriptor was generated.

      - A descriptor field other than bandwidth or uptime has changed.

      - Bandwidth has changed by more than +/- 50% from the last time a
309
310
        descriptor was generated, and at least a given interval of time
        (20 mins by default) has passed since then.
311

312
      - Its uptime has been reset (by restarting).
313

314
315
   After generating a descriptor, ORs upload them to every directory
   authority they know, by posting them (in order) to the URL
316

317
      http://<hostname:port>/tor/
318

319
320
2.1. Router descriptor format

321
322
323
   Router descriptors consist of the following items.  For backward
   compatibility, there should be an extra NL at the end of each router
   descriptor.
324

325
326
   In lines that take multiple arguments, extra arguments SHOULD be
   accepted and ignored.
327

328
     "router" nickname address ORPort SOCKSPort DirPort NL
329

330
       [At start, exactly once.]
331
332
333
334
335

       Indicates the beginning of a router descriptor.  "address" must be an
       IPv4 address in dotted-quad format. The last three numbers indicate
       the TCP ports at which this OR exposes functionality. ORPort is a port
       at which this OR accepts TLS connections for the main OR protocol;
336
       SOCKSPort is deprecated and should always be 0; and DirPort is the
337
338
339
340
       port at which this OR accepts directory-related HTTP connections.  If
       any port is not supported, the value 0 is given instead of a port
       number.

341
342
343
    "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL

       [Exactly once]
344
345
346
347
348
349
350
351
352
353

       Estimated bandwidth for this router, in bytes per second.  The
       "average" bandwidth is the volume per second that the OR is willing to
       sustain over long periods; the "burst" bandwidth is the volume that
       the OR is willing to sustain in very short intervals.  The "observed"
       value is an estimate of the capacity this server can handle.  The
       server remembers the max bandwidth sustained output over any ten
       second period in the past day, and another sustained input.  The
       "observed" value is the lesser of these two numbers.

354
355
356
    "platform" string NL

       [At most once]
357
358
359
360
361

       A human-readable string describing the system on which this OR is
       running.  This MAY include the operating system, and SHOULD include
       the name and version of the software implementing the Tor protocol.

362
363
364
365
366
367
    "published" YYYY-MM-DD HH:MM:SS NL

       [Exactly once]

       The time, in GMT, when this descriptor (and its corresponding
       extra-info document if any)  was generated.
368

369
    "fingerprint" fingerprint NL
370

371
       [At most once]
372
373
374
375
376
377
378
379
380

       A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
       hex, with a single space after every 4 characters) for this router's
       identity key. A descriptor is considered invalid (and MUST be
       rejected) if the fingerprint line does not match the public key.

       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
        be marked with "opt" until earlier versions of Tor are obsolete.]

381
382
383
    "hibernating" bool NL

       [At most once]
384
385
386
387
388
389
390

       If the value is 1, then the Tor server was hibernating when the
       descriptor was published, and shouldn't be used to build circuits.

       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be
        marked with "opt" until earlier versions of Tor are obsolete.]

391
392
393
    "uptime" number NL

       [At most once]
394
395
396
397
398

       The number of seconds that this OR process has been running.

    "onion-key" NL a public key in PEM format

399
400
       [Exactly once]

401
       This key is used to encrypt EXTEND cells for this OR.  The key MUST be
402
       accepted for at least 1 week after any new key is published in a
403
       subsequent descriptor. It MUST be 1024 bits.
404
405
406

    "signing-key" NL a public key in PEM format

407
       [Exactly once]
408

409
410
411
412
413
414
       The OR's long-term identity key.  It MUST be 1024 bits.

    "accept" exitpattern NL
    "reject" exitpattern NL

       [Any number]
415

416
       These lines describe the rules that an OR follows when
417
       deciding whether to allow a new stream to a given address.  The
418
       'exitpattern' syntax is described below.  The rules are considered in
419
       order; if no rule matches, the address will be accepted.  For clarity,
420
       the last such entry SHOULD be accept *:* or reject *:*.
421
422
423

    "router-signature" NL Signature NL

424
425
       [At end, exactly once]

426
427
428
429
430
431
432
433
       The "SIGNATURE" object contains a signature of the PKCS1-padded
       hash of the entire router descriptor, taken from the beginning of the
       "router" line, through the newline after the "router-signature" line.
       The router descriptor is invalid unless the signature is performed
       with the router's identity key.

    "contact" info NL

434
435
436
437
       [At most once]

       Describes a way to contact the server's administrator, preferably
       including an email address and a PGP key fingerprint.
438
439
440

    "family" names NL

441
442
        [At most once]

443
444
445
446
        'Names' is a space-separated list of server nicknames or
        hexdigests. If two ORs list one another in their "family" entries,
        then OPs should treat them as a single OR for the purpose of path
        selection.
447
448
449
450
451
452

        For example, if node A's descriptor contains "family B", and node B's
        descriptor contains "family A", then node A and node B should never
        be used on the same circuit.

    "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
453
        [At most once]
454
    "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
455
        [At most once]
456
457
458
459
460
461
462
463
464
465

        Declare how much bandwidth the OR has used recently. Usage is divided
        into intervals of NSEC seconds.  The YYYY-MM-DD HH:MM:SS field
        defines the end of the most recent interval.  The numbers are the
        number of bytes used in the most recent intervals, ordered from
        oldest to newest.

        [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
         be marked with "opt" until earlier versions of Tor are obsolete.]

466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
        [See also migration notes in section 2.2.1.]

   "caches-extra-info" 0|1 NL

       [At most once.]

       True if this router is a directory cache that provides extra-info
       documents.  If absent, the value should be treated as false.

       [Versions before 0.2.0.1-alpha don't recognize this, and versions
        before 0.1.2.5-alpha will reject descriptors containing it unless
        it is prefixed with "opt"; it should be so prefixed until these
        versions are obsolete.]

   "extra-info-digest" digest NL

       [At most once]

       "Digest" is a hex-encoded digest (using upper-case characters)
       of the router's extra-info document, as signed in the router's
       extra-info.  (If this field is absent, the router is not uploading
       a corresponding extra-info document.)

       [Versions before 0.2.0.1-alpha don't recognize this, and versions
        before 0.1.2.5-alpha will reject descriptors containing it unless
        it is prefixed with "opt"; it should be so prefixed until these
        versions are obsolete.]

2.2. Extra-info documents

   Extra-info documents consist of the following items:

    "extra-info" Nickname Fingerprint NL
        [At start, exactly once.]

        Identifies what router this is an extra info descriptor for.
        Fingerprint is encoded in hex (using upper-case letters), with
        no spaces.
504

505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
    "published"

       [Exactly once.]

       The time, in GMT, when this document (and its corresponding router
       descriptor if any) was generated.  It MUST match the published time
       in the corresponding router descriptor.

    "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
        [At most once.]
    "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
        [At most once.]

        As documented in 2.1 above.  See migration notes in section 2.2.1.

    "router-signature" NL Signature NL
        [At end, exactly once.]

        A document signature as documented in section 1.3, using the
        initial item "extra-info" and the final item "router-signature",
        signed with the router's identity key.

2.2.1. Moving history fields to extra-info documents.

   Tools that want to use the read-history and write-history values SHOULD
   download extra-info documents as well as router descriptors.  Such
   tools SHOULD accept history values from both sources; if they appear in
   both documents, the values in the extra-info documents are authoritative.

   At some future time, to save space, new versions of Tor will no longer
   generate router descriptors containing read-history or write-history.
   Tools should continue to accept read-history and write-history values
   in router descriptors produced by older versions of Tor.

2.3. Nonterminals in router descriptors
540
541

   nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
542
543
   hexdigest ::= a '$', followed by 20 hexadecimal characters.
      [Represents a server by the digest of its identity key.]
544
545
546
547

   exitpattern ::= addrspec ":" portspec
   portspec ::= "*" | port | port "-" port
   port ::= an integer between 1 and 65535, inclusive.
548

549
550
551
      [Some implementations incorrectly generate ports with value 0.
       Implementations SHOULD accept this, and SHOULD NOT generate it.]

552
553
554
555
556
557
558
559
560
   addrspec ::= "*" | ip4spec | ip6spec
   ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
   ip4 ::= an IPv4 address in dotted-quad format
   ip4mask ::= an IPv4 mask in dotted-quad format
   num_ip4_bits ::= an integer between 0 and 32
   ip6spec ::= ip6 | ip6 "/" num_ip6_bits
   ip6 ::= an IPv6 address, surrounded by square brackets.
   num_ip6_bits ::= an integer between 0 and 128

561
562
   bool ::= "0" | "1"

563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
3. Formats produced by directory authorities.

   Every authority has two keys used in this protocol: a signing key, and
   an authority identity key.  (Authorities also have a router identity
   key used in their role as a router and by earlier versions of the
   directory protocol.)  The identity key is used from time to time to
   sign new key certificates using new signing keys; it is very sensitive.
   The signing key is used to sign key certificates and status documents.

   There are three kinds of documents generated by directory authorities:

     Key certificates
     Status votes
     Status consensuses

   Each is discussed below.

3.1. Key certificates

   Key certificates consist of the following items:

    "dir-key-certificate-version" version NL

        [At start, exactly once.]

        Determines the version of the key certificate.  MUST be "3" for
        the protocol described in this document.  Implementations MUST
        reject formats they don't understand.

    "fingerprint" fingerprint NL

        [Exactly once.]

        Hexadecimal encoding without spaces based on the authority's
        identity key.

    "dir-identity-key" NL a public key in PEM format

        [Exactly once.]

        The long-term authority identity key for this authority.  This key
        SHOULD be at least 2048 bits long; it MUST NOT be shorter than
        1024 bits.

    "dir-key-published" YYYY-MM-DD HH:MM:SS NL

        [Exactly once.]

        The time (in GMT) when this document and corresponding key were
        last generated.

    "dir-key-expires" YYYY-MM-DD HH:MM:SS NL

        [Exactly once.]

        A time (in GMT) after which this key is no longer valid.

    "dir-signing-key" NL a key in PEM format

        [Exactly once.]

        The directory server's public signing key.  This key MUST be at
        least 1024 bits, and MAY be longer.

    "dir-key-certification" NL Signature NL

        [At end, exactly once.]

        A document signature as documented in section 1.3, using the
        initial item "dir-key-certificate-version" and the final item
        "dir-key-certification", signed with the authority identity key.

   Authorities MUST generate a new signing key and corresponding
   certificate before the key expires.

3.2. Vote and consensus status documents

   Votes and consensuses are more strictly formatted then other documents
   in this specification, since different authorities must be able to
   generate exactly the same consensus given the same set of votes.

   The procedure for deciding when to generate vote and consensus status
   documents are described in section XXX below.

   Status documents contain a preamble, an authority section, a list of
   router status entries, and one more footers signature, in that order.

   Unlike other formats described above, a SP in these documents must be a
   single space character (hex 20).

   Some items appear only in votes, and some items appear only in
   consensuses.  Unless specified, items occur in both.

   The preamble contains the following items.  They MUST occur in the
   order given here:

    "network-status-version" SP version NL.

        [At start, exactly once.]

        A document format version.  For this specification, the version is
        "3".

    "vote-status" SP type NL

        [Exactly once.]

        The status MUST be "vote" or "consensus", depending on the type of
        the document.

    "published" SP YYYY-MM-DD SP HH:MM:SS NL

675
676
677
678
679
680
        [Exactly once for votes; Does not occur in consensuses.]

        The publication time for this status document (if a vote).

    "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL

681
682
        [Exactly once.]

683
        The start of the Interval for this vote (if a consensus.)
684

685
    "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL
686
687
688
689
690
691
692
693
694
695
696

        [Exactly once.]

        A time after which this vote or consensus will no longer be valid.

    "client-versions" SP VersionList NL

        [At most once.]

        A comma-separated list of recommended client versions, in
        ascending order.  If absent, no opinion is held about client
697
        versions.
698
699
700
701
702
703
704

    "server-versions" SP VersionList NL

        [At most once.]

        A comma-separated list of recommended server versions, in
        ascending order.  If absent, no opinion is held about server
705
        versions.
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792

    "known-flags" SP FlagList NL

        [Exactly once.]

        A space-separated list of all of the flags that this document
        might contain.  A flag is "known" either because the authority
        knows about them and might set them (if in a vote), or because
        enough votes were counted for the consensus for an authoritative
        opinion to have been formed about their status.


   The authority section of a vote contains the following items, followed
   in turn by the authority's current key certificate:

    "dir-source" SP nickname SP identity SP address SP IP SP dirport NL

        [Exactly once, at start]

        Describes this authority.  The nickname is a convenient identifier
        for the authority.  The identity is a hex fingerprint of the
        authority's current identity key.  The address is the server's
        hostname.  The IP is the server's current IP address, and dirport
        is its current directory port.

    "contact" SP string NL

        [At most once.]

        An arbitrary string describing how to contact the directory
        server's administrator.  Administrators should include at least an
        email address and a PGP fingerprint.

   The authority section of a consensus contains groups the following
   items, in the order given, with one group for each authority that
   contributed to the consensus:

    "dir-source" SP nickname SP address SP IP SP dirport NL

        [Exactly once, at start]

        As in the authority section of a vote.

    "contact" SP string NL

        [At most once.]

        As in the authority section of a vote.

    "fingerprint" SP fingerprint NL

        [Exactly once.]

        A hex fingerprint, without spaces, of the authority's current
        identity key.

    "vote-digest" SP digest NL

        [Exactly once.]

        A digest of the vote from the authority that contributed to this
        consensus.

   Each router status entry contains the following items.  Router status
   entries are sorted in ascending order by identity digest.

    "r" SP nickname SP identity SP digest SP publication SP IP SP ORPort
        SP DirPort NL

        [At start, exactly once.]

        "Nickname" is the OR's nickname.  "Identity" is a hash of its
        identity key, encoded in base64, with trailing equals sign(s)
        removed.  "Digest" is a hash of its most recent descriptor (as
        signed), encoded in base64 as "identity".  "Publication" is the
        publication time of its most recent descriptor, in the form
        YYYY-MM-DD HH:MM:SS, in GMT.  "IP" is its current IP address;
        ORPort is its current OR port, "DirPort" is it's current directory
        port, or "0" for "none".

    "s" SP Flags NL

        [At most once.]

        A series of space-separated status flags, in alphabetical order.
        Currently documented flags are:

793
          "Authority" if the router is a directory authority.
794
795
796
          "BadExit" if the router is believed to be useless as an exit node
             (because its ISP censors it, because it is behind a restrictive
             proxy, or for some similar reason).
797
          "BadDirectory" if the router is believed to be useless as a
Roger Dingledine's avatar
Roger Dingledine committed
798
799
800
             directory cache (because its directory port isn't working,
             its bandwidth is always throttled, or for some similar
             reason).
801
          "Exit" if the router is useful for building general-purpose exit
Roger Dingledine's avatar
Roger Dingledine committed
802
             circuits.
803
          "Fast" if the router is suitable for high-bandwidth circuits.
Roger Dingledine's avatar
Roger Dingledine committed
804
          "Guard" if the router is suitable for use as an entry guard.
805
806
          "Named" if the router's identity-nickname mapping is canonical,
             and this authority binds names.
807
          "Stable" if the router is suitable for long-lived circuits.
Roger Dingledine's avatar
Roger Dingledine committed
808
          "Running" if the router is currently usable.
809
          "Valid" if the router has been 'validated'.
810
          "V2Dir" if the router implements this protocol.
811

812
    "v" SP version NL
813

814
        [At most once.]
815

816
817
818
819
820
821
822
        The version of the Tor protocol that this server is running.  If
        the value begins with "Tor" SP, the rest of the string is a Tor
        version number, and the protocol is "The Tor protocol as supported
        by the given version of Tor."  Otherwise, if the value begins with
        some other string, Tor has upgraded to a more sophisticated
        protocol versioning system, and the protocol is "a version of the
        Tor protocol more recent than any we recognize."
823

824
825
   The signature section contains the following item, which appears
   Exactly Once for a vote, and At Least Once for a consensus.
826

827
    "directory-signature" SP identity SP digest NL Signature
828

829
830
831
832
833
834
835
836
837
838
839
        This is a signature of the status document, with the initial item
        "network-status-version", and the signature item
        "directory-signature", using the signing key.  (In this case, we
        take the hash through the _space_ after directory-signature, not
        the newline: this ensures that all authorities sign the same
        thing.)  "identity" is the hex-encoded digest of the authority
        identity key of the signing authority, and "digest" is the
        hex-encoded digest of the current authority signing key of the
        signing authority.

3.3. Deciding how to vote.
840

841
   (This section describes how directory authorities choose which status
842
   flags to apply to routers, as of Tor 0.2.0.0-alpha-dev. Later directory
843
844
845
   authorities MAY do things differently, so long as clients keep working
   well.  Clients MUST NOT depend on the exact behaviors in this section.)

846
847
848
   In the below definitions, a router is considered "active" if it is
   running, valid, and not hibernating.

849
850
851
   "Valid" -- a router is 'Valid' if it is running a version of Tor not
   known to be broken, and the directory authority has not blacklisted
   it as suspicious.
852
853
854
855
856
857
858
859
860
861
862
863
864

   "Named" -- Directory authority administrators may decide to support name
   binding.  If they do, then they must maintain a file of
   nickname-to-identity-key mappings, and try to keep this file consistent
   with other directory authorities.  If they don't, they act as clients, and
   report bindings made by other directory authorities (name X is bound to
   identity Y if at least one binding directory lists it, and no directory
   binds X to some other Y'.)  A router is called 'Named' if the router
   believes the given name should be bound to the given key.

   "Running" -- A router is 'Running' if the authority managed to connect to
   it successfully within the last 30 minutes.

865
866
867
868
869
   "Stable" -- A router is 'Stable' if it is active, and either its
   uptime is at least the median uptime for known active routers, or
   its uptime is at least 30 days. Routers are never called stable if
   they are running a version of Tor known to drop circuits stupidly.
   (0.1.1.10-alpha through 0.1.1.16-rc are stupid this way.)
870

871
872
   "Fast" -- A router is 'Fast' if it is active, and its bandwidth is
   in the top 7/8ths for known active routers.
873
874

   "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
875
876
877
   bandwidth is above median for known active routers. If the total
   bandwidth of active non-BadExit Exit servers is less than one third
   of the total bandwidth of all active servers, no Exit is listed as
878
   a Guard.
879
880
881
882
883
884
885
886

   "Authority" -- A router is called an 'Authority' if the authority
   generating the network-status document believes it is an authority.

   "V2Dir" -- A router supports the v2 directory protocol if it has an open
   directory port, and it is running a version of the directory protocol that
   supports the functionality clients need.  (Currently, this is
   0.1.1.9-alpha or later.)
887
888
889
890

   Directory server administrators may label some servers or IPs as
   blacklisted, and elect not to include them in their network-status lists.

Roger Dingledine's avatar
Roger Dingledine committed
891
   Thus, the network-status list includes all non-blacklisted,
892
   non-expired, non-superseded descriptors.
893

894
895
896
897
898
3.4. Computing a consensus from a set of votes

   Given a set of votes, authorities compute the contents of the consensus
   document as follows:

899
     The "valid-after" is the latest of all valid-after times on the votes.
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925

     The "valid-until" is the earliest of all valid-until times on the
     votes.

    "client-versions" and "server-versions" are sorted in ascending
     order; A version is recommended in the consensus if it is recommended
     by more than half of the voting authorities that included a
     client-versions or server-versions lines in their votes.

     The authority item groups (dir-source, contact, fignerprint,
     vote-digest) are taken from the votes of the voting
     authorities. These groups are sorted by the digests of the
     authorities identity keys, in ascending order.

     A router status entry is included in the result if it is included by more
     than half of the authorities (total authorities, not just those whose
     votes we have).  A router entry has a flag set if it is included by
     more than half of the authorities who care about that flag.  Two
     router entries are "the same" if they have the same identity digest.
     We use whatever descriptor digest is attested to by the most
     authorities among the voters, breaking ties in favor of the one with
     the most recent publication time.

     The signatures at the end of the document appear are sorted in
     ascending order by identity digest.

926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
3.4. Detached signatures

   Assuming full connectivity, every authority should compute and sign the
   same consensus directory in each period.  Therefore, it isn't necessary to
   download the consensus computed by each authority; instead, the
   authorities only push/fetch each others' signatures.  A "detached
   signature" document contains items as follows:


    "consensus-digest" SP Digest NL

        [At start, at most once.]

        The digest of the consensus being signed.

    "valid-after" SP YYYY-MM-DD SP HH:MM:SS NL
    "valid-until" SP YYYY-MM-DD SP HH:MM:SS NL

        [As in the consensus]

    "directory signature"

        [As in the consensus; the signature object is the same as in the
        consensus document.]

951

952
953
4. Directory server operation

954
   All directory authorities and directory caches ("directory servers")
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
   implement this section, except as noted.

4.1. Accepting uploads (authorities only)

   When a router posts a signed descriptor to a directory authority, the
   authority first checks whether it is well-formed and correctly
   self-signed.  If it is, the authority next verifies that the nickname
   question is already assigned to a router with a different public key.
   Finally, the authority MAY check that the router is not blacklisted
   because of its key, IP, or another reason.

   If the descriptor passes these tests, and the authority does not already
   have a descriptor for a router with this public key, it accepts the
   descriptor and remembers it.

   If the authority _does_ have a descriptor with the same public key, the
   newly uploaded descriptor is remembered if its publication time is more
   recent than the most recent old descriptor for that router, and either:
      - There are non-cosmetic differences between the old descriptor and the
        new one.
      - Enough time has passed between the descriptors' publication times.
        (Currently, 12 hours.)

   Differences between router descriptors are "non-cosmetic" if they would be
   sufficient to force an upload as described in section 2 above.

   Note that the "cosmetic difference" test only applies to uploaded
   descriptors, not to descriptors that the authority downloads from other
   authorities.

985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
   When a router posts a signed extra-info document to a directory authority,
   the authority again checks it for well-formedness and correct signature,
   and checks that its matches the extra-info-digest in some router
   descriptor that it believes is currently useful.  If so, it accepts it and
   stores it and serves it as requested.  If not, it drops it.

4.2. Voting (authorities only)

   Authorities divide time into Intervals.  Authority administrators SHOULD
   try to all pick the same interval length, and SHOULD pick intervals that
   are commonly used divisions of time (e.g., 5 minutes, 15 minutes, 30
   minutes, 60 minutes, 90 minutes).  Voting intervals SHOULD be chosen to
   divide evenly into a 24-hour day.

   Authorities MUST take pains to ensure that their clocks remain accurate,
   for example by running NTP.