/
dir-spec.txt
4291 lines (3126 loc) · 174 KB
/
dir-spec.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
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
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
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
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
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
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
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
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
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
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
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
951
952
953
954
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
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Tor directory protocol, version 3
Table of Contents
0. Scope and preliminaries
0.1. History
0.2. Goals of the version 3 protoc
0.3. Some Remaining questions
1. Outline
1.1. What's different from version 2?
1.2. Document meta-format
1.3. Signing documents
1.4. Voting timeline
2. Router operation and formats
2.1. Uploading server descriptors and extra-info documents
2.1.1. Server descriptor format
2.1.2. Extra-info document format
2.1.3. Nonterminals in server descriptors
3. Directory authority operation and formats
3.1. Creating key certificates
3.2. Accepting server descriptor and extra-info document uploads
3.3. Computing microdescriptors
3.4. Exchanging votes
3.4.1. Vote and consensus status document formats
3.4.2. Assigning flags in a vote
3.4.3. Serving bandwidth list files
3.5. Downloading missing certificates from other directory authorities
3.6. Downloading server descriptors from other directory authorities
3.7. Downloading extra-info documents from other directory authorities
3.8. Computing a consensus from a set of votes
3.8.0.1. Deciding which Ids to include.
3.8.0.2. Deciding which descriptors to include
3.8.1. Forward compatibility
3.8.2. Encoding port lists
3.8.3. Computing Bandwidth Weights
3.9. Computing consensus flavors
3.9.1. ns consensus
3.9.2. Microdescriptor consensus
3.10. Exchanging detached signatures
3.11. Publishing the signed consensus
4. Directory cache operation
4.1. Downloading consensus status documents from directory authorities
4.2. Downloading server descriptors from directory authorities
4.3. Downloading microdescriptors from directory authorities
4.4. Downloading extra-info documents from directory authorities
4.5. Consensus diffs
4.5.1. Consensus diff format
4.5.2. Serving and requesting diff
4.6 Retrying failed downloads
5. Client operation
5.1. Downloading network-status documents
5.2. Downloading server descriptors or microdescriptors
5.3. Downloading extra-info documents
5.4. Using directory information
5.4.1. Choosing routers for circuits.
5.4.2. Managing naming
5.4.3. Software versions
5.4.4. Warning about a router's status.
5.5. Retrying failed downloads
6. Standards compliance
6.1. HTTP headers
6.2. HTTP status codes
A. Consensus-negotiation timeline.
B. General-use HTTP URLs
C. Converting a curve25519 public key to an ed25519 public key
D. Inferring missing proto lines.
E. Limited ed diff format
0. Scope and preliminaries
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
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.
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
XXX timeline
XXX fill in XXXXs
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
0.1. History
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.
The Version 1 Directory protocol
--------------------------------
Early versions of Tor (0.0.2) introduced "Directory authorities": servers
that served signed "directory" documents containing a list of signed
"server 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 the list they were getting
was attested by a trusted directory authority.
Later versions (0.0.8) 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 server descriptors that clients
already had.
* Every directory authority 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 server 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 server 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 server descriptors was
used by two fields that are not actually used by Tor routers
(namely read-history and write-history). 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
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.
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.
1. Outline
There is a small set (say, around 5-10) of semi-trusted directory
authorities. A default list of authorities is shipped with the Tor
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 server 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 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 server descriptors. Clients download missing descriptors
from caches; caches and authorities download from authorities.
Descriptors are downloaded by the hash of the descriptor, not by the
relay's identity key: this prevents directory servers from attacking
clients by giving them descriptors nobody else uses.
All directory information is uploaded and downloaded with HTTP.
1.1. What's different from version 2?
Clients used to download multiple network status documents,
corresponding roughly to "status votes" above. They would compute the
result of the vote on the client side.
Authorities used to 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.
All of the information in extra-info documents used to be kept in the
main descriptors.
1.2. Document meta-format
Server 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 zero 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-],
but may not start with -.
An Object is a block of encoded data in pseudo-Privacy-Enhanced-Mail (PEM)
style format: that is, lines of encoded data MAY be wrapped by inserting
an ascii linefeed ("LF", also called newline, or "NL" here) character
(cf. RFC 4648 §3.1). When line wrapping, implementations MUST wrap lines
at 64 characters. Upon decoding, implementations MUST ignore and discard
all linefeed characters.
More formally:
NL = The ascii LF character (hex value 0x0a).
Document ::= (Item | NL)+
Item ::= KeywordLine Object?
KeywordLine ::= Keyword (WS Argument)* NL
Keyword = KeywordStart KeywordChar*
KeywordStart ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9'
KeywordChar ::= KeywordStart | '-'
Argument := ArgumentChar+
ArgumentChar ::= any graphical printing ASCII character.
WS = (SP | TAB)+
Object ::= BeginLine Base64-encoded-data EndLine
BeginLine ::= "-----BEGIN " Keyword (" " Keyword)* "-----" NL
EndLine ::= "-----END " Keyword (" " Keyword)* "-----" NL
A Keyword may not be "-----BEGIN".
The BeginLine and EndLine of an Object must use the same keyword.
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.
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.
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.
"At end, exactly once": These items MUST occur in every instance of
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.
For forward compatibility, each item MUST allow extra arguments at the
end of the line unless otherwise noted. So if an item's description below
is given as:
"thing" int int int NL
then implementations SHOULD accept this string as well:
"thing 5 9 11 13 16 12" NL
but not this string:
"thing 5" NL
and not this string:
"thing 5 10 thing" NL
.
Whenever an item DOES NOT allow extra arguments, we will tag it with
"no extra arguments".
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.
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 PKCS#1 1.5 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.
The signature does not include the algorithmIdentifier specified in PKCS #1.
Unless specified 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*.
1.4. Voting timeline
Every consensus document has a "valid-after" (VA) time, a "fresh-until"
(FU) time and a "valid-until" (VU) time. VA MUST precede FU, which MUST
in turn precede VU. Times are chosen so that every consensus will be
"fresh" until the next consensus becomes valid, and "valid" for a while
after. At least 3 consensuses should be valid at any given time.
The timeline for a given consensus is as follows:
VA-DistSeconds-VoteSeconds: The authorities exchange votes. Each authority
uploads their vote to all other authorities.
VA-DistSeconds-VoteSeconds/2: The authorities try to download any
votes they don't have.
Authorities SHOULD also reject any votes that other authorities try to
upload after this time. (0.4.4.1-alpha was the first version to reject votes
in this way.)
Note: Refusing late uploaded votes minimizes the chance of a consensus
split, particular when authorities are under bandwidth pressure. If an
authority is struggling to upload its vote, and finally uploads to a
fraction of authorities after this period, they will compute a consensus
different from the others. By refusing uploaded votes after this time,
we increase the likelihood that most authorities will use the same vote
set.
Rejecting late uploaded votes does not fix the problem entirely. If
some authorities are able to download a specific vote, but others fail
to do so, then there may still be a consensus split. However, this
change does remove one common cause of consensus splits.
VA-DistSeconds: The authorities calculate the consensus and exchange
signatures. (This is the earliest point at which anybody can
possibly get a given consensus if they ask for it.)
VA-DistSeconds/2: The authorities try to download any signatures
they don't have.
VA: All authorities have a multiply signed consensus.
VA ... FU: Caches download the consensus. (Note that since caches have
no way of telling what VA and FU are until they have downloaded
the consensus, they assume that the present consensus's VA is
equal to the previous one's FU, and that its FU is one interval after
that.)
FU: The consensus is no longer the freshest consensus.
FU ... (the current consensus's VU): Clients download the consensus.
(See note above: clients guess that the next consensus's FU will be
two intervals after the current VA.)
VU: The consensus is no longer valid; clients should continue to try to
download a new consensus if they have not done so already.
VU + 24 hours: Clients will no longer use the consensus at all.
VoteSeconds and DistSeconds MUST each be at least 20 seconds; FU-VA and
VU-FU MUST each be at least 5 minutes.
2. Router operation and formats
2.1. Uploading server descriptors and extra-info documents
ORs SHOULD generate a new server descriptor and a new extra-info
document whenever any of the following events have occurred:
- A period of time (18 hrs by default) has passed since the last
time a descriptor was generated.
- A descriptor field other than bandwidth or uptime has changed.
- Its uptime is less than 24h and bandwidth has changed by a factor of 2
from the last time a descriptor was generated, and at least a given
interval of time (3 hours by default) has passed since then.
- Its uptime has been reset (by restarting).
- It receives a networkstatus consensus in which it is not listed.
- It receives a networkstatus consensus in which it is listed
with the StaleDesc flag.
[XXX this list is incomplete; see router_differences_are_cosmetic()
in routerlist.c for others]
ORs SHOULD NOT publish a new server descriptor or extra-info document
if none of the above events have occurred and not much time has passed
(12 hours by default).
Tor versions older than 0.3.5.1-alpha ignore uptime when checking for
bandwidth changes.
After generating a descriptor, ORs upload them to every directory
authority they know, by posting them (in order) to the URL
http://<hostname:port>/tor/
Server descriptors may not exceed 20,000 bytes in length; extra-info
documents may not exceed 50,000 bytes in length. If they do, the
authorities SHOULD reject them.
2.1.1. Server descriptor format
Server descriptors consist of the following items.
In lines that take multiple arguments, extra arguments SHOULD be
accepted and ignored. Many of the nonterminals below are defined in
section 2.1.3.
Note that many versions of Tor will generate an extra newline at the
end of their descriptors. Implementations MUST tolerate one or
more blank lines at the end of a single descriptor or a list of
concatenated descriptors. New implementations SHOULD NOT generate
such blank lines.
"router" nickname address ORPort SOCKSPort DirPort NL
[At start, exactly once.]
Indicates the beginning of a server descriptor. "nickname" must be a
valid router nickname as specified in section 2.1.3. "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;
SOCKSPort is deprecated and should always be 0; and DirPort is the
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. (At least one of DirPort and ORPort SHOULD be set;
authorities MAY reject any descriptor with both DirPort and ORPort of
0.)
"identity-ed25519" NL "-----BEGIN ED25519 CERT-----" NL certificate
"-----END ED25519 CERT-----" NL
[Exactly once, in second position in document.]
[No extra arguments]
The certificate is a base64-encoded Ed25519 certificate (see
cert-spec.txt) with terminating =s removed. When this element
is present, it MUST appear as the first or second element in
the router descriptor.
The certificate has CERT_TYPE of [04]. It must include a
signed-with-ed25519-key extension (see cert-spec.txt,
section 2.2.1), so that we can extract the master identity key.
[Before Tor 0.4.5.1-alpha, this field was optional.]
"master-key-ed25519" SP MasterKey NL
[Exactly once]
Contains the base-64 encoded ed25519 master key as a single
argument. If it is present, it MUST match the identity key
in the identity-ed25519 entry.
[Before Tor 0.4.5.1-alpha, this field was optional.]
"bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL
[Exactly once]
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 relay can handle. The
relay remembers the max bandwidth sustained output over any ten
second period in the past 5 days, and another sustained input. The
"observed" value is the lesser of these two numbers.
Tor versions released before 2018 only kept bandwidth-observed for one
day. These versions are no longer supported or recommended.
"platform" string NL
[At most once]
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.
"published" YYYY-MM-DD HH:MM:SS NL
[Exactly once]
The time, in UTC, when this descriptor (and its corresponding
extra-info document if any) was generated.
"fingerprint" fingerprint NL
[At most once]
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.]
"hibernating" bool NL
[At most once]
If the value is 1, then the Tor relay 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.]
"uptime" number NL
[At most once]
The number of seconds that this OR process has been running.
"onion-key" NL a public key in PEM format
[Exactly once]
[No extra arguments]
This key is used to encrypt CREATE cells for this OR. The key MUST be
accepted for at least 1 week after any new key is published in a
subsequent descriptor. It MUST be 1024 bits.
The key encoding is the encoding of the key as a PKCS#1 RSAPublicKey
structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC
KEY-----" and "-----END RSA PUBLIC KEY-----".
"onion-key-crosscert" NL a RSA signature in PEM format.
[Exactly once]
[No extra arguments]
This element contains an RSA signature, generated using the
onion-key, of the following:
A SHA1 hash of the RSA identity key,
i.e. RSA key from "signing-key" (see below) [20 bytes]
The Ed25519 identity key,
i.e. Ed25519 key from "master-key-ed25519" [32 bytes]
If there is no Ed25519 identity key, or if in some future version
there is no RSA identity key, the corresponding field must be
zero-filled.
Parties verifying this signature MUST allow additional data
beyond the 52 bytes listed above.
This signature proves that the party creating the descriptor
had control over the secret key corresponding to the
onion-key.
[Before Tor 0.4.5.1-alpha, this field was optional whenever
identity-ed25519 was absent.]
"ntor-onion-key" base-64-encoded-key
[Exactly once]
A curve25519 public key used for the ntor circuit extended
handshake. It's the standard encoding of the OR's curve25519
public key, encoded in base 64. The trailing '=' sign MAY be
omitted from the base64 encoding. The key MUST be accepted
for at least 1 week after any new key is published in a
subsequent descriptor.
[Before Tor 0.4.5.1-alpha, this field was optional.]
"ntor-onion-key-crosscert" SP Bit NL
"-----BEGIN ED25519 CERT-----" NL certificate
"-----END ED25519 CERT-----" NL
[Exactly once]
[No extra arguments]
A signature created with the ntor-onion-key, using the
certificate format documented in cert-spec.txt, with type
[0a]. The signed key here is the master identity key.
Bit must be "0" or "1". It indicates the sign of the ed25519
public key corresponding to the ntor onion key. If Bit is "0",
then implementations MUST guarantee that the x-coordinate of
the resulting ed25519 public key is positive. Otherwise, if
Bit is "1", then the sign of the x-coordinate MUST be negative.
To compute the ed25519 public key corresponding to a curve25519
key, and for further explanation on key formats, see appendix C.
This signature proves that the party creating the descriptor
had control over the secret key corresponding to the
ntor-onion-key.
[Before Tor 0.4.5.1-alpha, this field was optional whenever
identity-ed25519 was absent.]
"signing-key" NL a public key in PEM format
[Exactly once]
[No extra arguments]
The OR's long-term RSA identity key. It MUST be 1024 bits.
The encoding is as for "onion-key" above.
"accept" exitpattern NL
"reject" exitpattern NL
[Any number]
These lines describe an "exit policy": the rules that an OR follows
when deciding whether to allow a new stream to a given address. The
'exitpattern' syntax is described below. There MUST be at least one
such entry. The rules are considered in order; if no rule matches,
the address will be accepted. For clarity, the last such entry SHOULD
be accept *:* or reject *:*.
"ipv6-policy" SP ("accept" / "reject") SP PortList NL
[At most once.]
An exit-policy summary as specified in sections 3.4.1 and 3.8.2,
summarizing
the router's rules for connecting to IPv6 addresses. A missing
"ipv6-policy" line is equivalent to "ipv6-policy reject
1-65535".
"overload-general" SP version SP YYYY-MM-DD HH:MM:SS NL
[At most once.]
Indicates that a relay has reached an "overloaded state" which can be
one or many of the following load metrics:
- Any OOM invocation due to memory pressure
- Any ntor onionskins are dropped
- TCP port exhaustion
The timestamp is when at least one metrics was detected. It should always
be at the hour and thus, as an example, "2020-01-10 13:00:00" is an
expected timestamp. Because this is a binary state, if the line is
present, we consider that it was hit at the very least once somewhere
between the provided timestamp and the "published" timestamp of the
document which is when the document was generated.
The overload-general line should remain in place for 72 hours since last
triggered. If the limits are reached again in this period, the timestamp
is updated, and this 72 hour period restarts.
The 'version' field is set to '1' for now.
(Introduced in tor-0.4.6.1-alpha, but moved from extra-info to general
descriptor in tor-0.4.6.2-alpha)
"router-sig-ed25519" SP Signature NL
[Exactly once.]
It MUST be the next-to-last element in the descriptor, appearing
immediately before the RSA signature. It MUST contain an Ed25519
signature of a SHA256 digest of the entire document. This digest is
taken from the first character up to and including the first space
after the "router-sig-ed25519" string. Before computing the digest,
the string "Tor router descriptor signature v1" is prefixed to the
document.
The signature is encoded in Base64, with terminating =s removed.
The signing key in the identity-ed25519 certificate MUST
be the one used to sign the document.
[Before Tor 0.4.5.1-alpha, this field was optional whenever
identity-ed25519 was absent.]
"router-signature" NL Signature NL
[At end, exactly once]
[No extra arguments]
The "SIGNATURE" object contains a signature of the PKCS1-padded
hash of the entire server descriptor, taken from the beginning of the
"router" line, through the newline after the "router-signature" line.
The server descriptor is invalid unless the signature is performed
with the router's identity key.
"contact" info NL
[At most once]
Describes a way to contact the relay's administrator, preferably
including an email address and a PGP key fingerprint.
"bridge-distribution-request" SP Method NL
[At most once, bridges only.]
The "Method" describes how a Bridge address is distributed by
BridgeDB. Recognized methods are: "none", "any", "https", "email",
"moat". If set to "none", BridgeDB will avoid distributing your bridge
address. If set to "any", BridgeDB will choose how to distribute your
bridge address. Choosing any of the other methods will tell BridgeDB to
distribute your bridge via a specific method:
- "https" specifies distribution via the web interface at
https://bridges.torproject.org;
- "email" specifies distribution via the email autoresponder at
bridges@torproject.org;
- "moat" specifies distribution via an interactive menu inside Tor
Browser; and
Potential future "Method" specifiers must be as follows:
Method = (KeywordChar | "_") +
All bridges SHOULD include this line. Non-bridges MUST NOT include
it.
BridgeDB SHOULD treat unrecognized Method values as if they were
"none".
(Default: "any")
[This line was introduced in 0.3.2.3-alpha, with a minimal backport
to 0.2.5.16, 0.2.8.17, 0.2.9.14, 0.3.0.13, 0.3.1.9, and later.]
"family" names NL
[At most once]
'Names' is a space-separated list of relay 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.
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
[At most once]
"write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
[At most once]
(These fields once appeared in router descriptors, but have
appeared in extra-info descriptors since 0.2.0.x.)
"eventdns" bool NL
[At most once]
Declare whether this version of Tor is using the newer enhanced
dns logic. Versions of Tor with this field set to false SHOULD NOT
be used for reverse hostname lookups.
[This option is obsolete. All Tor current relays should be presumed
to have the evdns backend.]
"caches-extra-info" NL
[At most once.]
[No extra arguments]
Present only if this router is a directory cache that provides
extra-info documents.
[Versions before 0.2.0.1-alpha don't recognize this]
"extra-info-digest" SP sha1-digest [SP sha256-digest] NL
[At most once]
"sha1-digest" is a hex-encoded SHA1 digest (using upper-case characters)
of the router's extra-info document, as signed in the router's
extra-info (that is, not including the signature). (If this field is
absent, the router is not uploading a corresponding extra-info
document.)
"sha256-digest" is a base64-encoded SHA256 digest of the extra-info
document. Unlike the "sha1-digest", this digest is calculated over the
entire document, including the signature. This difference is due to
a long-lived bug in the tor implementation that it would be difficult
to roll out an incremental fix for, not a design choice. Future digest
algorithms specified should not include the signature in the data used
to compute the digest.
[Versions before 0.2.7.2-alpha did not include a SHA256 digest.]
[Versions before 0.2.0.1-alpha don't recognize this field at all.]
"hidden-service-dir" NL
[At most once.]
Present only if this router stores and serves hidden service
descriptors. This router supports the descriptor versions declared
in the HSDir "proto" entry. If there is no "proto" entry, this
router supports version 2 descriptors.
"protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP
CIRCUIT-VERSION-LIST NL
[At most once.]
An obsolete list of protocol versions, superseded by the "proto"
entry. This list was never parsed, and has not been emitted
since Tor 0.2.9.4-alpha. New code should neither generate nor
parse this line.
"allow-single-hop-exits" NL
[At most once.]
[No extra arguments]
Present only if the router allows single-hop circuits to make exit
connections. Most Tor relays do not support this: this is
included for specialized controllers designed to support perspective
access and such. This is obsolete in tor version >= 0.3.1.0-alpha.
"or-address" SP ADDRESS ":" PORT NL
[Any number]
ADDRESS = IP6ADDR | IP4ADDR
IPV6ADDR = an ipv6 address, surrounded by square brackets.
IPV4ADDR = an ipv4 address, represented as a dotted quad.
PORT = a number between 1 and 65535 inclusive.
An alternative for the address and ORPort of the "router" line, but with
two added capabilities:
* or-address can be either an IPv4 or IPv6 address
* or-address allows for multiple ORPorts and addresses
A descriptor SHOULD NOT include an or-address line that does nothing but
duplicate the address:port pair from its "router" line.
The ordering of or-address lines and their PORT entries matter because
Tor MAY accept a limited number of address/port pairs. As of
Tor 0.2.3.x only the first address/port pair is advertised and used.
"tunnelled-dir-server" NL
[At most once.]
[No extra arguments]
Present if the router accepts "tunneled" directory requests using a
BEGIN_DIR cell over the router's OR port.
(Added in 0.2.8.1-alpha. Before this, Tor relays accepted
tunneled directory requests only if they had a DirPort open,
or if they were bridges.)
"proto" SP Entries NL
[Exactly once.]
Entries =
Entries = Entry
Entries = Entry SP Entries
Entry = Keyword "=" Values
Values =
Values = Value
Values = Value "," Values
Value = Int
Value = Int "-" Int
Int = NON_ZERO_DIGIT
Int = Int DIGIT
Each 'Entry' in the "proto" line indicates that the Tor relay supports
one or more versions of the protocol in question. Entries should be
sorted by keyword. Values should be numerically ascending within each
entry. (This implies that there should be no overlapping ranges.)
Ranges should be represented as compactly as possible. Ints must be no
larger than 63.
This field was first added in Tor 0.2.9.x.
[Before Tor 0.4.5.1-alpha, this field was optional.]
2.1.2. Extra-info document format
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.
"identity-ed25519"
[As in router descriptors]
"published" YYYY-MM-DD HH:MM:SS NL
[Exactly once.]
The time, in UTC, when this document (and its corresponding router
descriptor if any) was generated. It MUST match the published time
in the corresponding server 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.]
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.
These fields include both IPv4 and IPv6 traffic.
"ipv6-read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM... NL