forked from torproject/torspec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
217-ext-orport-auth.txt
177 lines (120 loc) · 5.78 KB
/
217-ext-orport-auth.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
Filename: 217-ext-orport-auth.txt
Title: Tor Extended ORPort Authentication
Author: George Kadianakis
Created: 28-11-2012
Status: Closed
Target: 0.2.5.x
1. Overview
This proposal defines a scheme for Tor components to authenticate to
each other using a shared-secret.
2. Motivation
Proposal 196 introduced new ways for pluggable transport proxies to
communicate with Tor. The communication happens using TCP in the same
fashion that controllers speak to the ControlPort.
To defend against cross-protocol attacks [0] on the transport ports,
we need to define an authentication scheme that will restrict passage
to unknown clients.
Tor's ControlPort uses an authentication scheme called safe-cookie
authentication [1]. Unfortunately, the design of the safe-cookie
authentication was influenced by the protocol structure of the
ControlPort and the need for backwards compatibility of the
cookie-file and can't be easily reused in other use cases.
3. Goals
The general goal of Extended ORPort authentication is to authenticate
the client based on a shared-secret that only authorized clients
should know.
Furthermore, its implementation should be flexible and easy to reuse,
so that it can be used as the authentication mechanism in front of
future Tor helper ports (for example, in proposal 199).
Finally, the protocol is able to support multiple authentication
schemes and each of them has different goals.
4. Protocol Specification
4.1. Initial handshake
When a client connects to the Extended ORPort, the server sends:
AuthTypes [variable]
EndAuthTypes [1 octet]
Where,
+ AuthTypes are the authentication schemes that the server supports
for this session. They are multiple concatenated 1-octet values that
take values from 1 to 255.
+ EndAuthTypes is the special value 0.
The client reads the list of supported authentication schemes and
replies with the one he prefers to use:
AuthType [1 octet]
Where,
+ AuthType is the authentication scheme that the client wants to use
for this session. A valid authentication type takes values from 1 to
255. A value of 0 means that the client did not like the
authentication types offered by the server.
If the client sent an AuthType of value 0, or an AuthType that the
server does not support, the server MUST close the connection.
4.2. Authentication types
4.2.1 SAFE_COOKIE handshake
Authentication type 1 is called SAFE_COOKIE.
4.2.1.1. Motivation and goals
The SAFE_COOKIE scheme is pretty-much identical to the authentication
scheme that was introduced for the ControlPort in proposal 193.
An additional goal of the SAFE_COOKIE authentication scheme (apart
from the goals of section 2), is that it should not leak the contents
of the cookie-file to untrusted parties.
Specifically, the SAFE_COOKIE protocol will never leak the actual
contents of the file. Instead, it uses a challenge-response protocol
(similar to the HTTP digest authentication of RFC2617) to ensure that
both parties know the cookie without leaking it.
4.2.1.2. Cookie-file format
The format of the cookie-file is:
StaticHeader [32 octets]
Cookie [32 octets]
Where,
+ StaticHeader is the following string:
"! Extended ORPort Auth Cookie !\x0a"
+ Cookie is the shared-secret. During the SAFE_COOKIE protocol, the
cookie is called CookieString.
Extended ORPort clients MUST make sure that the StaticHeader is
present in the cookie file, before proceeding with the
authentication protocol.
Details on how Tor locates the cookie file can be found in section 5
of proposal 196. Details on how transport proxies locate the cookie
file can be found in pt-spec.txt.
4.2.1.3. Protocol specification
A client that performs the SAFE_COOKIE handshake begins by sending:
ClientNonce [32 octets]
Where,
+ ClientNonce is 32 octets of random data.
Then, the server replies with:
ServerHash [32 octets]
ServerNonce [32 octets]
Where,
+ ServerHash is computed as:
HMAC-SHA256(CookieString,
"ExtORPort authentication server-to-client hash" | ClientNonce | ServerNonce)
+ ServerNonce is 32 random octets.
Upon receiving that data, the client computes ServerHash herself and
validates it against the ServerHash provided by the server.
If the server-provided ServerHash is invalid, the client MUST
terminate the connection.
Otherwise the client replies with:
ClientHash [32 octets]
Where,
+ ClientHash is computed as:
HMAC-SHA256(CookieString,
"ExtORPort authentication client-to-server hash" | ClientNonce | ServerNonce)
Upon receiving that data, the server computes ClientHash herself and
validates it against the ClientHash provided by the client.
Finally, the server replies with:
Status [1 octet]
Where,
+ Status is 1 if the authentication was successfull. If the
authentication failed, Status is 0.
4.3. Post-authentication
After completing the Extended ORPort authentication successfully, the
two parties should proceed with the Extended ORPort protocol on the
same TCP connection.
5. Acknowledgments
Thanks to Robert Ransom for helping with the proposal and designing
the original safe-cookie authentication scheme. Thanks to Nick
Mathewson for advices and reviews of the proposal.
[0]:
http://archives.seul.org/or/announce/Sep-2007/msg00000.html
[1]:
https://gitweb.torproject.org/torspec.git/blob/79f488c32c43562522e5592f2c19952dc7681a65:/control-spec.txt#l1069