forked from torproject/torspec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tor-spec.txt
2427 lines (1868 loc) · 105 KB
/
tor-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 Protocol Specification
Roger Dingledine
Nick Mathewson
Table of Contents
0. Preliminaries
0.1. Notation and encoding
0.2. Security parameters
0.3. Ciphers
0.4. A bad hybrid encryption algorithm, for legacy purposes
1. System overview
1.1. Keys and names
2. Connections
2.1. Picking TLS ciphersuites
2.2. TLS security considerations
3. Cell Packet format
4. Negotiating and initializing connections
4.1. Negotiating versions with VERSIONS cells
4.2. CERTS cells
4.3. AUTH_CHALLENGE cells
4.4. AUTHENTICATE cells
4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret
4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705
4.5. NETINFO cells
5. Circuit management
5.1. CREATE and CREATED cells
5.1.1. Choosing circuit IDs in create cells
5.1.2. EXTEND and EXTENDED cells
5.1.3. The "TAP" handshake
5.1.4. The "ntor" handshake
5.1.5. CREATE_FAST/CREATED_FAST cells
5.2. Setting circuit keys
5.2.1. KDF-TOR
5.2.2. KDF-RFC5869
5.3. Creating circuits
5.3.1. Canonical connections
5.4. Tearing down circuits
5.5. Routing relay cells
5.5.1. Circuit ID Checks
5.5.2. Forward Direction
5.5.2.1. Routing from the Origin
5.5.2.2. Relaying Forward at Onion Routers
5.5.3. Backward Direction
5.5.3.1. Relaying Backward at Onion Routers
5.5.4. Routing to the Origin
5.6. Handling relay_early cells
6. Application connections and stream management
6.1. Relay cells
6.2. Opening streams and transferring data
6.2.1. Opening a directory stream
6.3. Closing streams
6.4. Remote hostname lookup
7. Flow control
7.1. Link throttling
7.2. Link padding
7.3. Circuit-level flow control
7.3.1. SENDME Cell Format
7.4. Stream-level flow control
8. Handling resource exhaustion
8.1. Memory exhaustion
9. Subprotocol versioning
9.1. "Link"
9.2. "LinkAuth"
9.3. "Relay"
9.4. "HSIntro"
9.5. "HSRend"
9.6. "HSDir"
9.7. "DirCache"
9.8. "Desc"
9.9. "Microdesc"
9.10. "Cons"
9.11. "Padding"
9.12. "FlowCtrl"
Note: This document aims to specify Tor as currently implemented, though it
may take it a little time to become fully up to date. Future versions of Tor
may implement improved protocols, and compatibility is not guaranteed.
We may or may not remove compatibility notes for other obsolete versions of
Tor as they become obsolete.
This specification is not a design document; most design criteria
are not examined. For more information on why Tor acts as it does,
see tor-design.pdf.
0. Preliminaries
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. Notation and encoding
PK -- a public key.
SK -- a private key.
K -- a key for a symmetric cipher.
a|b -- concatenation of 'a' and 'b'.
[A0 B1 C2] -- a three-byte sequence, containing the bytes with
hexadecimal values A0, B1, and C2, in that order.
H(m) -- a cryptographic hash of m.
We use "byte" and "octet" interchangeably. Possibly we shouldn't.
0.1.1. Encoding integers
Unless we explicitly say otherwise below, all numeric values in the
Tor protocol are encoded in network (big-endian) order. So a "32-bit
integer" means a big-endian 32-bit integer; a "2-byte" integer means
a big-endian 16-bit integer, and so forth.
0.2. Security parameters
Tor uses a stream cipher, a public-key cipher, the Diffie-Hellman
protocol, and a hash function.
KEY_LEN -- the length of the stream cipher's key, in bytes.
PK_ENC_LEN -- the length of a public-key encrypted message, in bytes.
PK_PAD_LEN -- the number of bytes added in padding for public-key
encryption, in bytes. (The largest number of bytes that can be encrypted
in a single public-key operation is therefore PK_ENC_LEN-PK_PAD_LEN.)
DH_LEN -- the number of bytes used to represent a member of the
Diffie-Hellman group.
DH_SEC_LEN -- the number of bytes used in a Diffie-Hellman private key (x).
HASH_LEN -- the length of the hash function's output, in bytes.
PAYLOAD_LEN -- The longest allowable cell payload, in bytes. (509)
CELL_LEN(v) -- The length of a Tor cell, in bytes, for link protocol
version v.
CELL_LEN(v) = 512 if v is less than 4;
= 514 otherwise.
0.3. Ciphers
These are the ciphers we use _unless otherwise specified_. Several of
them are deprecated for new use.
For a stream cipher, unless otherwise specified, we use 128-bit AES in
counter mode, with an IV of all 0 bytes. (We also require AES256.)
For a public-key cipher, unless otherwise specified, we use RSA with
1024-bit keys and a fixed exponent of 65537. We use OAEP-MGF1
padding, with SHA-1 as its digest function. We leave the optional
"Label" parameter unset. (For OAEP padding, see
ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/pkcs-1v2-1.pdf)
We also use the Curve25519 group and the Ed25519 signature format in
several places.
For Diffie-Hellman, unless otherwise specified, we use a generator
(g) of 2. For the modulus (p), we use the 1024-bit safe prime from
rfc2409 section 6.2 whose hex representation is:
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E08"
"8A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B"
"302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9"
"A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6"
"49286651ECE65381FFFFFFFFFFFFFFFF"
As an optimization, implementations SHOULD choose DH private keys (x) of
320 bits. Implementations that do this MUST never use any DH key more
than once.
[May other implementations reuse their DH keys?? -RD]
[Probably not. Conceivably, you could get away with changing DH keys once
per second, but there are too many oddball attacks for me to be
comfortable that this is safe. -NM]
For a hash function, unless otherwise specified, we use SHA-1.
KEY_LEN=16.
DH_LEN=128; DH_SEC_LEN=40.
PK_ENC_LEN=128; PK_PAD_LEN=42.
HASH_LEN=20.
We also use SHA256 and SHA3-256 in some places.
When we refer to "the hash of a public key", unless otherwise
specified, we mean the SHA-1 hash of the DER encoding of an ASN.1 RSA
public key (as specified in PKCS.1).
All "random" values MUST be generated with a cryptographically
strong pseudorandom number generator seeded from a strong entropy
source, unless otherwise noted.
0.4. A bad hybrid encryption algorithm, for legacy purposes.
Some specifications will refer to the "legacy hybrid encryption" of a
byte sequence M with a public key PK. It is computed as follows:
1. If the length of M is no more than PK_ENC_LEN-PK_PAD_LEN,
pad and encrypt M with PK.
2. Otherwise, generate a KEY_LEN byte random key K.
Let M1 = the first PK_ENC_LEN-PK_PAD_LEN-KEY_LEN bytes of M,
and let M2 = the rest of M.
Pad and encrypt K|M1 with PK. Encrypt M2 with our stream cipher,
using the key K. Concatenate these encrypted values.
Note that this "hybrid encryption" approach does not prevent
an attacker from adding or removing bytes to the end of M. It also
allows attackers to modify the bytes not covered by the OAEP --
see Goldberg's PET2006 paper for details. Do not use it as the basis
for new protocols! Also note that as used in Tor's protocols, case 1
never occurs.
1. System overview
Tor is a distributed overlay network designed to anonymize
low-latency TCP-based applications such as web browsing, secure shell,
and instant messaging. Clients choose a path through the network and
build a ``circuit'', in which each node (or ``onion router'' or ``OR'')
in the path knows its predecessor and successor, but no other nodes in
the circuit. Traffic flowing down the circuit is sent in fixed-size
``cells'', which are unwrapped by a symmetric key at each node (like
the layers of an onion) and relayed downstream.
1.1. Keys and names
Every Tor relay has multiple public/private keypairs:
These are 1024-bit RSA keys:
- A long-term signing-only "Identity key" used to sign documents and
certificates, and used to establish relay identity.
- A medium-term TAP "Onion key" used to decrypt onion skins when accepting
circuit extend attempts. (See 5.1.) Old keys MUST be accepted for a
while after they are no longer advertised. Because of this,
relays MUST retain old keys for a while after they're rotated. (See
"onion key lifetime parameters" in dir-spec.txt.)
- A short-term "Connection key" used to negotiate TLS connections.
Tor implementations MAY rotate this key as often as they like, and
SHOULD rotate this key at least once a day.
This is Curve25519 key:
- A medium-term ntor "Onion key" used to handle onion key handshakes when
accepting incoming circuit extend requests. As with TAP onion keys,
old ntor keys MUST be accepted for at least one week after they are no
longer advertised. Because of this, relays MUST retain old keys for a
while after they're rotated. (See "onion key lifetime parameters" in
dir-spec.txt.)
These are Ed25519 keys:
- A long-term "master identity" key. This key never
changes; it is used only to sign the "signing" key below. It may be
kept offline.
- A medium-term "signing" key. This key is signed by the master identity
key, and must be kept online. A new one should be generated
periodically. It signs nearly everything else.
- A short-term "link authentication" key, used to authenticate
the link handshake: see section 4 below. This key is signed
by the "signing" key, and should be regenerated frequently.
The RSA identity key and Ed25519 master identity key together identify a
router uniquely. Once a router has used an Ed25519 master identity key
together with a given RSA identity key, neither of those keys may ever be
used with a different key.
2. Connections
Connections between two Tor relays, or between a client and a relay,
use TLS/SSLv3 for link authentication and encryption. All
implementations MUST support the SSLv3 ciphersuite
"TLS_DHE_RSA_WITH_AES_128_CBC_SHA" if it is available. They SHOULD
support better ciphersuites if available.
There are three ways to perform TLS handshakes with a Tor server. In
the first way, "certificates-up-front", both the initiator and
responder send a two-certificate chain as part of their initial
handshake. (This is supported in all Tor versions.) In the second
way, "renegotiation", the responder provides a single certificate,
and the initiator immediately performs a TLS renegotiation. (This is
supported in Tor 0.2.0.21 and later.) And in the third way,
"in-protocol", the initial TLS negotiation completes, and the
parties bootstrap themselves to mutual authentication via use of the
Tor protocol without further TLS handshaking. (This is supported in
0.2.3.6-alpha and later.)
Each of these options provides a way for the parties to learn it is
available: a client does not need to know the version of the Tor
server in order to connect to it properly.
In "certificates up-front" (a.k.a "the v1 handshake"),
the connection initiator always sends a
two-certificate chain, consisting of an X.509 certificate using a
short-term connection public key and a second, self-signed X.509
certificate containing its identity key. The other party sends a similar
certificate chain. The initiator's ClientHello MUST NOT include any
ciphersuites other than:
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
In "renegotiation" (a.k.a. "the v2 handshake"),
the connection initiator sends no certificates, and
the responder sends a single connection certificate. Once the TLS
handshake is complete, the initiator renegotiates the handshake, with each
party sending a two-certificate chain as in "certificates up-front".
The initiator's ClientHello MUST include at least one ciphersuite not in
the list above -- that's how the initiator indicates that it can
handle this handshake. For other considerations on the initiator's
ClientHello, see section 2.1 below.
In "in-protocol" (a.k.a. "the v3 handshake"), the initiator sends no
certificates, and the
responder sends a single connection certificate. The choice of
ciphersuites must be as in a "renegotiation" handshake. There are
additionally a set of constraints on the connection certificate,
which the initiator can use to learn that the in-protocol handshake
is in use. Specifically, at least one of these properties must be
true of the certificate:
* The certificate is self-signed
* Some component other than "commonName" is set in the subject or
issuer DN of the certificate.
* The commonName of the subject or issuer of the certificate ends
with a suffix other than ".net".
* The certificate's public key modulus is longer than 1024 bits.
The initiator then sends a VERSIONS cell to the responder, which then
replies with a VERSIONS cell; they have then negotiated a Tor
protocol version. Assuming that the version they negotiate is 3 or higher
(the only ones specified for use with this handshake right now), the
responder sends a CERTS cell, an AUTH_CHALLENGE cell, and a NETINFO
cell to the initiator, which may send either CERTS, AUTHENTICATE,
NETINFO if it wants to authenticate, or just NETINFO if it does not.
For backward compatibility between later handshakes and "certificates
up-front", the ClientHello of an initiator that supports a later
handshake MUST include at least one ciphersuite other than those listed
above. The connection responder examines the initiator's ciphersuite list
to see whether it includes any ciphers other than those included in the
list above. If extra ciphers are included, the responder proceeds as in
"renegotiation" and "in-protocol": it sends a single certificate and
does not request
client certificates. Otherwise (in the case that no extra ciphersuites
are included in the ClientHello) the responder proceeds as in
"certificates up-front": it requests client certificates, and sends a
two-certificate chain. In either case, once the responder has sent its
certificate or certificates, the initiator counts them. If two
certificates have been sent, it proceeds as in "certificates up-front";
otherwise, it proceeds as in "renegotiation" or "in-protocol".
To decide whether to do "renegotiation" or "in-protocol", the
initiator checks whether the responder's initial certificate matches
the criteria listed above.
All new relay implementations of the Tor protocol MUST support
backwards-compatible renegotiation; clients SHOULD do this too. If
this is not possible, new client implementations MUST support both
"renegotiation" and "in-protocol" and use the router's
published link protocols list (see dir-spec.txt on the "protocols" entry)
to decide which to use.
In all of the above handshake variants, certificates sent in the clear
SHOULD NOT include any strings to identify the host as a Tor relay. In
the "renegotiation" and "backwards-compatible renegotiation" steps, the
initiator SHOULD choose a list of ciphersuites and TLS extensions
to mimic one used by a popular web browser.
Even though the connection protocol is identical, we will think of the
initiator as either an onion router (OR) if it is willing to relay
traffic for other Tor users, or an onion proxy (OP) if it only handles
local requests. Onion proxies SHOULD NOT provide long-term-trackable
identifiers in their handshakes.
In all handshake variants, once all certificates are exchanged, all
parties receiving certificates must confirm that the identity key is as
expected. If the key is not as expected, the party must close the
connection.
(When initiating a connection, if a reasonably live consensus is
available, then the expected identity key is taken from that
consensus. But when initiating a connection otherwise, the expected
identity key is the one given in the hard-coded authority or
fallback list. Finally, when creating a connection because of an
EXTEND/EXTEND2 cell, the expected identity key is the one given in
the cell.)
When connecting to an OR, all parties SHOULD reject the connection if that
OR has a malformed or missing certificate. When accepting an incoming
connection, an OR SHOULD NOT reject incoming connections from parties with
malformed or missing certificates. (However, an OR should not believe
that an incoming connection is from another OR unless the certificates
are present and well-formed.)
[Before version 0.1.2.8-rc, ORs rejected incoming connections from ORs and
OPs alike if their certificates were missing or malformed.]
Once a TLS connection is established, the two sides send cells
(specified below) to one another. Cells are sent serially. Standard
cells are CELL_LEN(link_proto) bytes long, but variable-length cells
also exist; see Section 3. Cells may be sent embedded in TLS records
of any size or divided across TLS records, but the framing of TLS
records MUST NOT leak information about the type or contents of the
cells.
TLS connections are not permanent. Either side MAY close a connection
if there are no circuits running over it and an amount of time
(KeepalivePeriod, defaults to 5 minutes) has passed since the last time
any traffic was transmitted over the TLS connection. Clients SHOULD
also hold a TLS connection with no circuits open, if it is likely that a
circuit will be built soon using that connection.
Client-only Tor instances are encouraged to avoid using handshake
variants that include certificates, if those certificates provide
any persistent tags to the relays they contact. If clients do use
certificates, they SHOULD NOT keep using the same certificates when
their IP address changes. Clients MAY send certificates using any
of the above handshake variants.
2.1. Picking TLS ciphersuites
Clients SHOULD send a ciphersuite list chosen to emulate some popular
web browser or other program common on the internet. Clients may send
the "Fixed Cipheruite List" below. If they do not, they MUST NOT
advertise any ciphersuite that they cannot actually support, unless that
cipher is one not supported by OpenSSL 1.0.1.
The fixed ciphersuite list is:
TLS1_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS1_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS1_DHE_RSA_WITH_AES_256_SHA
TLS1_DHE_DSS_WITH_AES_256_SHA
TLS1_ECDH_RSA_WITH_AES_256_CBC_SHA
TLS1_ECDH_ECDSA_WITH_AES_256_CBC_SHA
TLS1_RSA_WITH_AES_256_SHA
TLS1_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS1_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS1_ECDHE_RSA_WITH_RC4_128_SHA
TLS1_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS1_DHE_RSA_WITH_AES_128_SHA
TLS1_DHE_DSS_WITH_AES_128_SHA
TLS1_ECDH_RSA_WITH_RC4_128_SHA
TLS1_ECDH_RSA_WITH_AES_128_CBC_SHA
TLS1_ECDH_ECDSA_WITH_RC4_128_SHA
TLS1_ECDH_ECDSA_WITH_AES_128_CBC_SHA
SSL3_RSA_RC4_128_MD5
SSL3_RSA_RC4_128_SHA
TLS1_RSA_WITH_AES_128_SHA
TLS1_ECDHE_ECDSA_WITH_DES_192_CBC3_SHA
TLS1_ECDHE_RSA_WITH_DES_192_CBC3_SHA
SSL3_EDH_RSA_DES_192_CBC3_SHA
SSL3_EDH_DSS_DES_192_CBC3_SHA
TLS1_ECDH_RSA_WITH_DES_192_CBC3_SHA
TLS1_ECDH_ECDSA_WITH_DES_192_CBC3_SHA
SSL3_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
SSL3_RSA_DES_192_CBC3_SHA
[*] The "extended renegotiation is supported" ciphersuite, 0x00ff, is
not counted when checking the list of ciphersuites.
If the client sends the Fixed Ciphersuite List, the responder MUST NOT
select any ciphersuite besides TLS_DHE_RSA_WITH_AES_256_CBC_SHA,
TLS_DHE_RSA_WITH_AES_128_CBC_SHA, and SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA:
such ciphers might not actually be supported by the client.
If the client sends a v2+ ClientHello with a list of ciphers other then
the Fixed Ciphersuite List, the responder can trust that the client
supports every cipher advertised in that list, so long as that ciphersuite
is also supported by OpenSSL 1.0.1.
Responders MUST NOT select any TLS ciphersuite that lacks ephemeral keys,
or whose symmetric keys are less then KEY_LEN bits, or whose digests are
less than HASH_LEN bits. Responders SHOULD NOT select any SSLv3
ciphersuite other than the DHE+3DES suites listed above.
2.2. TLS security considerations
Implementations MUST NOT allow TLS session resumption -- it can
exacerbate some attacks (e.g. the "Triple Handshake" attack from
Feb 2013), and it plays havoc with forward secrecy guarantees.
Implementations SHOULD NOT allow TLS compression -- although we don't
know a way to apply a CRIME-style attack to current Tor directly,
it's a waste of resources.
3. Cell Packet format
The basic unit of communication for onion routers and onion
proxies is a fixed-width "cell".
On a version 1 connection, each cell contains the following
fields:
CircID [CIRCID_LEN bytes]
Command [1 byte]
Payload (padded with padding bytes) [PAYLOAD_LEN bytes]
On a version 2 or higher connection, all cells are as in version 1
connections, except for variable-length cells, whose format is:
CircID [CIRCID_LEN octets]
Command [1 octet]
Length [2 octets; big-endian integer]
Payload (some commands MAY pad) [Length bytes]
Most variable-length cells MAY be padded with padding bytes, except
for VERSIONS cells, which MUST NOT contain any additional bytes.
(The payload of VPADDING cells consists of padding bytes.)
On a version 2 connection, variable-length cells are indicated by a
command byte equal to 7 ("VERSIONS"). On a version 3 or
higher connection, variable-length cells are indicated by a command
byte equal to 7 ("VERSIONS"), or greater than or equal to 128.
CIRCID_LEN is 2 for link protocol versions 1, 2, and 3. CIRCID_LEN
is 4 for link protocol version 4 or higher. The first VERSIONS cell,
and any cells sent before the first VERSIONS cell, always have
CIRCID_LEN == 2 for backward compatibility.
The CircID field determines which circuit, if any, the cell is
associated with.
The 'Command' field of a fixed-length cell holds one of the following
values:
0 -- PADDING (Padding) (See Sec 7.2)
1 -- CREATE (Create a circuit) (See Sec 5.1)
2 -- CREATED (Acknowledge create) (See Sec 5.1)
3 -- RELAY (End-to-end data) (See Sec 5.5 and 6)
4 -- DESTROY (Stop using a circuit) (See Sec 5.4)
5 -- CREATE_FAST (Create a circuit, no PK) (See Sec 5.1)
6 -- CREATED_FAST (Circuit created, no PK) (See Sec 5.1)
8 -- NETINFO (Time and address info) (See Sec 4.5)
9 -- RELAY_EARLY (End-to-end data; limited)(See Sec 5.6)
10 -- CREATE2 (Extended CREATE cell) (See Sec 5.1)
11 -- CREATED2 (Extended CREATED cell) (See Sec 5.1)
12 -- PADDING_NEGOTIATE (Padding negotiation) (See Sec 7.2)
Variable-length command values are:
7 -- VERSIONS (Negotiate proto version) (See Sec 4)
128 -- VPADDING (Variable-length padding) (See Sec 7.2)
129 -- CERTS (Certificates) (See Sec 4.2)
130 -- AUTH_CHALLENGE (Challenge value) (See Sec 4.3)
131 -- AUTHENTICATE (Client authentication)(See Sec 4.5)
132 -- AUTHORIZE (Client authorization) (Not yet used)
The interpretation of 'Payload' depends on the type of the cell.
VPADDING/PADDING:
Payload contains padding bytes.
CREATE/CREATE2: Payload contains the handshake challenge.
CREATED/CREATED2: Payload contains the handshake response.
RELAY/RELAY_EARLY: Payload contains the relay header and relay body.
DESTROY: Payload contains a reason for closing the circuit.
(see 5.4)
Upon receiving any other value for the command field, an OR must
drop the cell. Since more cell types may be added in the future, ORs
should generally not warn when encountering unrecognized commands.
The cell is padded up to the cell length with padding bytes.
Senders set padding bytes depending on the cell's command:
VERSIONS: Payload MUST NOT contain padding bytes.
AUTHORIZE: Payload is unspecified and reserved for future use.
Other variable-length cells:
Payload MAY contain padding bytes at the end of the cell.
Padding bytes SHOULD be set to NUL.
RELAY/RELAY_EARLY: Payload MUST be padded to PAYLOAD_LEN with padding
bytes. Padding bytes SHOULD be set to random values.
Other fixed-length cells:
Payload MUST be padded to PAYLOAD_LEN with padding bytes.
Padding bytes SHOULD be set to NUL.
We recommend random padding in RELAY/RELAY_EARLY cells, so that the cell
content is unpredictable. See the format of relay cells in section 6.1
for detail.
For other cells, TLS authenticates cell content, so randomized padding
bytes are redundant.
Receivers MUST ignore padding bytes.
PADDING cells are currently used to implement connection keepalive.
If there is no other traffic, ORs and OPs send one another a PADDING
cell every few minutes.
CREATE, CREATE2, CREATED, CREATED2, and DESTROY cells are used to
manage circuits; see section 5 below.
RELAY cells are used to send commands and data along a circuit; see
section 6 below.
VERSIONS and NETINFO cells are used to set up connections in link
protocols v2 and higher; in link protocol v3 and higher, CERTS,
AUTH_CHALLENGE, and AUTHENTICATE may also be used. See section 4
below.
4. Negotiating and initializing connections
After Tor instances negotiate handshake with either the "renegotiation" or
"in-protocol" handshakes, they must exchange a set of cells to set up
the Tor connection and make it "open" and usable for circuits.
When the renegotiation handshake is used, both parties immediately
send a VERSIONS cell (4.1 below), and after negotiating a link
protocol version (which will be 2), each send a NETINFO cell (4.5
below) to confirm their addresses and timestamps. No other intervening
cell types are allowed.
When the in-protocol handshake is used, the initiator sends a
VERSIONS cell to indicate that it will not be renegotiating. The
responder sends a VERSIONS cell, a CERTS cell (4.2 below) to give the
initiator the certificates it needs to learn the responder's
identity, an AUTH_CHALLENGE cell (4.3) that the initiator must include
as part of its answer if it chooses to authenticate, and a NETINFO
cell (4.5). As soon as it gets the CERTS cell, the initiator knows
whether the responder is correctly authenticated. At this point the
initiator behaves differently depending on whether it wants to
authenticate or not. If it does not want to authenticate, it MUST
send a NETINFO cell. If it does want to authenticate, it MUST send a
CERTS cell, an AUTHENTICATE cell (4.4), and a NETINFO. When this
handshake is in use, the first cell must be VERSIONS, VPADDING, or
AUTHORIZE, and no other cell type is allowed to intervene besides
those specified, except for VPADDING cells.
The AUTHORIZE cell type is reserved for future use by scanning-resistance
designs.
[Tor versions before 0.2.3.11-alpha did not recognize the AUTHORIZE cell,
and did not permit any command other than VERSIONS as the first cell of
the in-protocol handshake.]
4.1. Negotiating versions with VERSIONS cells
There are multiple instances of the Tor link connection protocol. Any
connection negotiated using the "certificates up front" handshake (see
section 2 above) is "version 1". In any connection where both parties
have behaved as in the "renegotiation" handshake, the link protocol
version must be 2. In any connection where both parties have behaved
as in the "in-protocol" handshake, the link protocol must be 3 or higher.
To determine the version, in any connection where the "renegotiation"
or "in-protocol" handshake was used (that is, where the responder
sent only one certificate at first and where the initiator did not
send any certificates in the first negotiation), both parties MUST
send a VERSIONS cell. In "renegotiation", they send a VERSIONS cell
right after the renegotiation is finished, before any other cells are
sent. In "in-protocol", the initiator sends a VERSIONS cell
immediately after the initial TLS handshake, and the responder
replies immediately with a VERSIONS cell. (As an exception to this rule,
if both sides support the "in-protocol" handshake, either side may send
VPADDING cells at any time.)
The payload in a VERSIONS cell is a series of big-endian two-byte
integers. Both parties MUST select as the link protocol version the
highest number contained both in the VERSIONS cell they sent and in the
versions cell they received. If they have no such version in common,
they cannot communicate and MUST close the connection. Either party MUST
close the connection if the versions cell is not well-formed (for example,
if it contains an odd number of bytes).
Any VERSIONS cells sent after the first VERSIONS cell MUST be ignored.
(To be interpreted correctly, later VERSIONS cells MUST have a CIRCID_LEN
matching the version negotiated with the first VERSIONS cell.)
Since the version 1 link protocol does not use the "renegotiation"
handshake, implementations MUST NOT list version 1 in their VERSIONS
cell. When the "renegotiation" handshake is used, implementations
MUST list only the version 2. When the "in-protocol" handshake is
used, implementations MUST NOT list any version before 3, and SHOULD
list at least version 3.
Link protocols differences are:
1 -- The "certs up front" handshake.
2 -- Uses the renegotiation-based handshake. Introduces
variable-length cells.
3 -- Uses the in-protocol handshake.
4 -- Increases circuit ID width to 4 bytes.
5 -- Adds support for link padding and negotiation (padding-spec.txt).
4.2. CERTS cells
The CERTS cell describes the keys that a Tor instance is claiming
to have. It is a variable-length cell. Its payload format is:
N: Number of certs in cell [1 octet]
N times:
CertType [1 octet]
CLEN [2 octets]
Certificate [CLEN octets]
Any extra octets at the end of a CERTS cell MUST be ignored.
Relevant certType values are:
1: Link key certificate certified by RSA1024 identity
2: RSA1024 Identity certificate, self-signed.
3: RSA1024 AUTHENTICATE cell link certificate, signed with RSA1024 key.
4: Ed25519 signing key, signed with identity key.
5: TLS link certificate, signed with ed25519 signing key.
6: Ed25519 AUTHENTICATE cell key, signed with ed25519 signing key.
7: Ed25519 identity, signed with RSA identity.
The certificate format for certificate types 1-3 is DER encoded
X509. For others, the format is as documented in cert-spec.txt.
Note that type 7 uses a different format from types 4-6.
A CERTS cell may have no more than one certificate of each CertType.
To authenticate the responder as having a given Ed25519,RSA identity key
combination, the initiator MUST check the following.
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* The CERTS cell contains exactly one CertType 4 Ed25519
"Id->Signing" cert.
* The CERTS cell contains exactly one CertType 5 Ed25519
"Signing->link" certificate.
* The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"
cross-certificate.
* All X.509 certificates above have validAfter and validUntil dates;
no X.509 or Ed25519 certificates are expired.
* All certificates are correctly signed.
* The certified key in the Signing->Link certificate matches the
SHA256 digest of the certificate that was used to
authenticate the TLS connection.
* The identity key listed in the ID->Signing cert was used to
sign the ID->Signing Cert.
* The Signing->Link cert was signed with the Signing key listed
in the ID->Signing cert.
* The RSA->Ed25519 cross-certificate certifies the Ed25519
identity, and is signed with the RSA identity listed in the
"ID" certificate.
* The certified key in the ID certificate is a 1024-bit RSA key.
* The RSA ID certificate is correctly self-signed.
To authenticate the responder as having a given RSA identity only,
the initiator MUST check the following:
* The CERTS cell contains exactly one CertType 1 "Link" certificate.
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* Both certificates have validAfter and validUntil dates that
are not expired.
* The certified key in the Link certificate matches the
link key that was used to negotiate the TLS connection.
* The certified key in the ID certificate is a 1024-bit RSA key.
* The certified key in the ID certificate was used to sign both
certificates.
* The link certificate is correctly signed with the key in the
ID certificate
* The ID certificate is correctly self-signed.
In both cases above, checking these conditions is sufficient to
authenticate that the initiator is talking to the Tor node with the
expected identity, as certified in the ID certificate(s).
To authenticate the initiator as having a given Ed25519,RSA
identity key combination, the responder MUST check the following:
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* The CERTS cell contains exactly one CertType 4 Ed25519
"Id->Signing" certificate.
* The CERTS cell contains exactly one CertType 6 Ed25519
"Signing->auth" certificate.
* The CERTS cell contains exactly one CertType 7 "RSA->Ed25519"
cross-certificate.
* All X.509 certificates above have validAfter and validUntil dates;
no X.509 or Ed25519 certificates are expired.
* All certificates are correctly signed.
* The identity key listed in the ID->Signing cert was used to
sign the ID->Signing Cert.
* The Signing->AUTH cert was signed with the Signing key listed
in the ID->Signing cert.
* The RSA->Ed25519 cross-certificate certifies the Ed25519
identity, and is signed with the RSA identity listed in the
"ID" certificate.
* The certified key in the ID certificate is a 1024-bit RSA key.
* The RSA ID certificate is correctly self-signed.
To authenticate the initiator as having an RSA identity key only,
the responder MUST check the following:
* The CERTS cell contains exactly one CertType 3 "AUTH" certificate.
* The CERTS cell contains exactly one CertType 2 "ID" certificate.
* Both certificates have validAfter and validUntil dates that
are not expired.
* The certified key in the AUTH certificate is a 1024-bit RSA key.
* The certified key in the ID certificate is a 1024-bit RSA key.
* The certified key in the ID certificate was used to sign both
certificates.
* The auth certificate is correctly signed with the key in the
ID certificate.
* The ID certificate is correctly self-signed.
Checking these conditions is NOT sufficient to authenticate that the
initiator has the ID it claims; to do so, the cells in 4.3 and 4.4
below must be exchanged.
4.3. AUTH_CHALLENGE cells
An AUTH_CHALLENGE cell is a variable-length cell with the following
fields:
Challenge [32 octets]
N_Methods [2 octets]
Methods [2 * N_Methods octets]
It is sent from the responder to the initiator. Initiators MUST
ignore unexpected bytes at the end of the cell. Responders MUST
generate every challenge independently using a strong RNG or PRNG.
The Challenge field is a randomly generated string that the
initiator must sign (a hash of) as part of authenticating. The
methods are the authentication methods that the responder will
accept. Only two authentication methods are defined right now:
see 4.4.1 and 4.4.2 below.
4.4. AUTHENTICATE cells
If an initiator wants to authenticate, it responds to the
AUTH_CHALLENGE cell with a CERTS cell and an AUTHENTICATE cell.
The CERTS cell is as a server would send, except that instead of
sending a CertType 1 (and possibly CertType 5) certs for arbitrary link
certificates, the initiator sends a CertType 3 (and possibly
CertType 6) cert for an RSA/Ed25519 AUTHENTICATE key.
This difference is because we allow any link key type on a TLS
link, but the protocol described here will only work for specific key
types as described in 4.4.1 and 4.4.2 below.
An AUTHENTICATE cell contains the following:
AuthType [2 octets]
AuthLen [2 octets]
Authentication [AuthLen octets]
Responders MUST ignore extra bytes at the end of an AUTHENTICATE
cell. Recognized AuthTypes are 1 and 3, described in the next
two sections.
Initiators MUST NOT send an AUTHENTICATE cell before they have
verified the certificates presented in the responder's CERTS
cell, and authenticated the responder.
4.4.1. Link authentication type 1: RSA-SHA256-TLSSecret
If AuthType is 1 (meaning "RSA-SHA256-TLSSecret"), then the
Authentication field of the AUTHENTICATE cell contains the following:
TYPE: The characters "AUTH0001" [8 octets]
CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]
SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets]
SLOG: A SHA256 hash of all bytes sent from the responder to the
initiator as part of the negotiation up to and including the
AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell,
the AUTH_CHALLENGE cell, and any padding cells. [32 octets]
CLOG: A SHA256 hash of all bytes sent from the initiator to the
responder as part of the negotiation so far; that is, the
VERSIONS cell and the CERTS cell and any padding cells. [32
octets]
SCERT: A SHA256 hash of the responder's TLS link certificate. [32
octets]
TLSSECRETS: A SHA256 HMAC, using the TLS master secret as the
secret key, of the following:
- client_random, as sent in the TLS Client Hello
- server_random, as sent in the TLS Server Hello
- the NUL terminated ASCII string:
"Tor V3 handshake TLS cross-certification"
[32 octets]
RAND: A 24 byte value, randomly chosen by the initiator. (In an
imitation of SSL3's gmt_unix_time field, older versions of Tor
sent an 8-byte timestamp as the first 8 bytes of this field;
new implementations should not do that.) [24 octets]
SIG: A signature of a SHA256 hash of all the previous fields
using the initiator's "Authenticate" key as presented. (As
always in Tor, we use OAEP-MGF1 padding; see tor-spec.txt
section 0.3.)
[variable length]
To check the AUTHENTICATE cell, a responder checks that all fields
from TYPE through TLSSECRETS contain their unique
correct values as described above, and then verifies the signature.
The server MUST ignore any extra bytes in the signed data after
the RAND field.
Responders MUST NOT accept this AuthType if the initiator has
claimed to have an Ed25519 identity.
(There is no AuthType 2: It was reserved but never implemented.)
4.4.2. Link authentication type 3: Ed25519-SHA256-RFC5705.
If AuthType is 3, meaning "Ed25519-SHA256-RFC5705", the
Authentication field of the AuthType cell is as below:
Modified values and new fields below are marked with asterisks.
TYPE: The characters "AUTH0003" [8 octets]
CID: A SHA256 hash of the initiator's RSA1024 identity key [32 octets]
SID: A SHA256 hash of the responder's RSA1024 identity key [32 octets]
CID_ED: The initiator's Ed25519 identity key [32 octets]
SID_ED: The responder's Ed25519 identity key, or all-zero. [32 octets]
SLOG: A SHA256 hash of all bytes sent from the responder to the
initiator as part of the negotiation up to and including the
AUTH_CHALLENGE cell; that is, the VERSIONS cell, the CERTS cell,
the AUTH_CHALLENGE cell, and any padding cells. [32 octets]
CLOG: A SHA256 hash of all bytes sent from the initiator to the
responder as part of the negotiation so far; that is, the
VERSIONS cell and the CERTS cell and any padding cells. [32
octets]
SCERT: A SHA256 hash of the responder's TLS link certificate. [32
octets]
TLSSECRETS: The output of an RFC5705 Exporter function on the
TLS session, using as its inputs:
- The label string "EXPORTER FOR TOR TLS CLIENT BINDING AUTH0003"
- The context value equal to the initiator's Ed25519 identity key.
- The length 32.
[32 octets]
RAND: A 24 byte value, randomly chosen by the initiator. [24 octets]
SIG: A signature of all previous fields using the initiator's
Ed25519 authentication key (as in the cert with CertType 6).
[variable length]
To check the AUTHENTICATE cell, a responder checks that all fields
from TYPE through TLSSECRETS contain their unique
correct values as described above, and then verifies the signature.
The server MUST ignore any extra bytes in the signed data after
the RAND field.
4.5. NETINFO cells
If version 2 or higher is negotiated, each party sends the other a
NETINFO cell. The cell's payload is:
TIME (Timestamp) [4 bytes]
OTHERADDR (Other OR's address) [variable]
ATYPE (Address type) [1 byte]
ALEN (Address length) [1 byte]
AVAL (Address value in NBO) [ALEN bytes]
NMYADDR (Number of this OR's addresses) [1 byte]
NMYADDR times:
ATYPE (Address type) [1 byte]
ALEN (Address length) [1 byte]
AVAL (Address value in NBO)) [ALEN bytes]
Recognized address types (ATYPE) are:
[04] IPv4.
[06] IPv6.
ALEN MUST be 4 when ATYPE is 0x04 (IPv4) and 16 when ATYPE is 0x06
(IPv6). If the ALEN value is wrong for the given ATYPE value, then
the provided address should be ignored.
The timestamp is a big-endian unsigned integer number of seconds
since the Unix epoch. Implementations MUST ignore unexpected bytes
at the end of the cell. Clients SHOULD send "0" as their timestamp, to
avoid fingerprinting.
Implementations MAY use the timestamp value to help decide if their
clocks are skewed. Initiators MAY use "other OR's address" to help
learn which address their connections may be originating from, if they do
not know it; and to learn whether the peer will treat the current
connection as canonical. Implementations SHOULD NOT trust these
values unconditionally, especially when they come from non-authorities,
since the other party can lie about the time or IP addresses it sees.
Initiators SHOULD use "this OR's address" to make sure
that they have connected to another OR at its canonical address.
(See 5.3.1 below.)
5. Circuit management
5.1. CREATE and CREATED cells
Users set up circuits incrementally, one hop at a time. To create a
new circuit, OPs send a CREATE/CREATE2 cell to the first node, with
the first half of an authenticated handshake; that node responds with
a CREATED/CREATED2 cell with the second half of the handshake. To
extend a circuit past the first hop, the OP sends an EXTEND/EXTEND2
relay cell (see section 5.1.2) which instructs the last node in the
circuit to send a CREATE/CREATE2 cell to extend the circuit.
There are two kinds of CREATE and CREATED cells: The older
"CREATE/CREATED" format, and the newer "CREATE2/CREATED2" format. The
newer format is extensible by design; the older one is not.
A CREATE2 cell contains:
HTYPE (Client Handshake Type) [2 bytes]
HLEN (Client Handshake Data Len) [2 bytes]