-
Notifications
You must be signed in to change notification settings - Fork 84
/
ext-orport-spec.txt
226 lines (152 loc) · 7.23 KB
/
ext-orport-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
Extended ORPort for pluggable transports
George Kadianakis, Nick Mathewson
Table of Contents
1. Overview
2. Establishing a connection and authenticating.
2.1. Authentication type: SAFE_COOKIE
2.1.2. Cookie-file format
2.1.3. SAFE_COOKIE Protocol specification
3. The extended ORPort protocol
3.1. Protocol
3.2. Command descriptions
3.2.1. USERADDR
3.2.2. TRANSPORT
4. Security Considerations
1. Overview
This document describes the "Extended ORPort" protocol, a wrapper
around Tor's ordinary ORPort protocol for use by bridges that
support pluggable transports. It provides a way for server-side PTs
and bridges to exchange additional information before beginning
the actual OR connection.
See `tor-spec.txt` for information on the regular OR protocol, and
`pt-spec.txt` for information on pluggable transports.
This protocol was originally proposed in proposal 196, and
extended with authentication in proposal 217.
2. Establishing a connection and authenticating.
When a client (that is to say, a server-side pluggable transport)
connects to an 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,
chooses one, and sends it back:
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.
2.1. Authentication type: SAFE_COOKIE
We define one authentication type: SAFE_COOKIE. Its AuthType
value is 1. It is based on the client proving to the bridge that
it can access a given "cookie" file on disk. The purpose of
authentication is to defend against cross-protocol attacks.
If the Extended ORPort is enabled, Tor should regenerate the cookie
file on startup and store it in
$DataDirectory/extended_orport_auth_cookie.
The location of the cookie can be overridden by using the
configuration file parameter ExtORPortCookieAuthFile, which is
defined as:
ExtORPortCookieAuthFile <path>
where <path> is a filesystem path.
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.
2.1.3. SAFE_COOKIE 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, 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, 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 successful. If the
authentication failed, Status is 0.
3. The extended ORPort protocol
Once a connection is established and authenticated, the parties
communicate with the protocol described here.
3.1. Protocol
The extended server port protocol is as follows:
COMMAND [2 bytes, big-endian]
BODYLEN [2 bytes, big-endian]
BODY [BODYLEN bytes]
Commands sent from the transport proxy to the bridge are:
[0x0000] DONE: There is no more information to give. The next
bytes sent by the transport will be those tunneled over it.
(body ignored)
[0x0001] USERADDR: an address:port string that represents the
client's address.
[0x0002] TRANSPORT: a string of the name of the pluggable
transport currently in effect on the connection.
Replies sent from tor to the proxy are:
[0x1000] OKAY: Send the user's traffic. (body ignored)
[0x1001] DENY: Tor would prefer not to get more traffic from
this address for a while. (body ignored)
[0x1002] CONTROL: (Not used)
Parties MUST ignore command codes that they do not understand.
If the server receives a recognized command that does not parse, it
MUST close the connection to the client.
3.2. Command descriptions
3.2.1. USERADDR
An ASCII string holding the TCP/IP address of the client of the
pluggable transport proxy. A Tor bridge SHOULD use that address to
collect statistics about its clients. Recognized formats are:
1.2.3.4:5678
[1:2::3:4]:5678
(Current Tor versions may accept other formats, but this is a bug:
transports MUST NOT send them.)
The string MUST not be NUL-terminated.
3.2.2. TRANSPORT
An ASCII string holding the name of the pluggable transport used by
the client of the pluggable transport proxy. A Tor bridge that
supports multiple transports SHOULD use that information to collect
statistics about the popularity of individual pluggable transports.
The string MUST not be NUL-terminated.
Pluggable transport names are C-identifiers and Tor MUST check them
for correctness.
4. Security Considerations
Extended ORPort or TransportControlPort do _not_ provide link
confidentiality, authentication or integrity. Sensitive data, like
cryptographic material, should not be transferred through them.
An attacker with superuser access is able to sniff network traffic,
and capture TransportControlPort identifiers and any data passed
through those ports.
Tor SHOULD issue a warning if the bridge operator tries to bind
Extended ORPort to a non-localhost address.
Pluggable transport proxies SHOULD issue a warning if they are
instructed to connect to a non-localhost Extended ORPort.