-
Notifications
You must be signed in to change notification settings - Fork 12
/
scramblesuit-spec.txt
364 lines (285 loc) · 18.4 KB
/
scramblesuit-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
ScrambleSuit Protocol Specification
Philipp Winter
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.
1. Overview
ScrambleSuit is a pluggable transport protocol for the obfsproxy
obfuscation framework [0]. Its entire payload is computationally
indistinguishable from randomness, it modifies its flow signature to foil
simple statistical classifiers and it employs authenticated encryption to
disguise the transported protocol.
For the motivation, a protocol overview, the threat model and an
evaluation, please refer to the original research paper [1]. This protocol
specification discusses a subset of the research paper in greater detail to
facilitate alternative implementations of the protocol. Besides, this
specification is intended to be updated if necessary whereas the research
paper will remain as is.
2. Authentication
There exist two ways for a client to authenticate itself towards a
ScrambleSuit server. First, by redeeming a session ticket. Second, by
conducting a UniformDH handshake. While a valid session ticket might not
always be available, a client is always able to conduct a UniformDH
handshake. Both authentication mechanisms rely on a previously shared
secret without which authentication cannot succeed. Requiring a shared
secret should thwart active probing attacks.
As stated in the research paper [1], a server only replies to a client if
the client can prove knowledge of the shared secret. As long as clients
cannot prove knowledge of the shared secret, servers MUST NOT reply. If
authentication did not succeed after 1532 bytes have been received, the
server SHOULD stop processing incoming data to prevent denial-of-service
attacks. The server MAY close the TCP connection. Alternatively, the
server MAY proceed to accept data but it SHOULD stop buffering or
processing the data, thus effectively ignoring the client.
2.1 UniformDH Handshake
A client can authenticate itself towards a ScrambleSuit server by
conducting a UniformDH handshake. UniformDH was originally proposed in the
obfs3 protocol specification [2]. ScrambleSuit uses obfs3's 1536-bit
UniformDH handshake. Note that in order for a UniformDH handshake to
succeed, both parties MUST share a 160-bit secret k_B which is exchanged
out-of-band over Tor's BridgeDB component. ScrambleSuit bridges
automatically publish their k_B key.
A UniformDH handshake consists of two messages: one from the client to the
server and one from the server to the client. The diagram below
illustrates the handshake. After the randomly chosen 192-byte UniformDH
public key X, random padding P_C is appended. The length of the padding
must be randomly chosen from {0..1308} bytes. After the padding, a 16-byte
mark M_C is appended which is defined as:
M = HMAC-SHA256-128(k_B, X)
The mark is used to easily locate the MAC which is the last element of the
client's handshake message. The 16-byte MAC is defined as:
MAC = HMAC-SHA256-128(k_B, X | P_C | M_C | E)
The variable E is a string representation of the current Unix epoch divided
by 3600. It represents the amount of hours which have passed since the
epoch. It is used by the client and the server to prove liveness. For
example, the Unix timestamp 1378768086 would map to E = 1378768086 / 3600 =
"382991". While the client MUST determine E, the server can simply echo
the client's E in its response.
The server's handshake message is created analogous to the client.
After conducting UniformDH, a client and server agreed on a 192-byte random
number. This random number is then hashed using SHA256 to obtain the
256-bit master key k_t. Session keys are then derived from k_t as
discussed in Section 2.3.
Client Server Legend:
| X | P_C | M_C | MAC(X | P_C | M_C | E) | X: client public key
| ---------------------------------------> | Y: server public key
| Y | P_S | M_S | MAC(Y | P_S | M_S | E) | P_{C,S}: padding
| <--------------------------------------- | M_{C,S}: mark to locate MAC
| AEnc(k_t+1 | T_t+1) | E: approximate timestamp
| <--------------------------------------- | k_t+1: future master key
| AEnc(Tor traffic) | T_t+1: future ticket
| <--------------------------------------> |
Immediately after the handshake succeeded, the server proceeds to issue and
send a new session ticket T_t+1 together with the according master key
k_t+1. Session tickets are discussed in Section 2.2. This tuple can then
be used by the client to authenticate itself the next time it connects to
the server. After the newly issued ticket, encrypted and authenticated Tor
traffic is finally exchanged between the client and the server.
2.2 Session Ticket Handshake
Alternatively to UniformDH, implementations SHOULD support session tickets.
A client can authenticate itself towards a ScrambleSuit server by redeeming
a 112-byte session ticket T. Such a ticket contains the master key k_t and
is encrypted and authenticated using keys only known to the server. The
structure of a session ticket is discussed in Section 5.1. If a valid
session ticket is available, a client SHOULD redeem it rather than conduct
a UniformDH handshake.
The handshake consists of one single message which is sent by the client to
the server. The diagram below illustrates the handshake. After the
112-byte session ticket, random padding P is appended. The padding must be
uniformly chosen from {0..1388} bytes. After the padding, a 16-byte mark M
is appended which is defined as:
M = HMAC-SHA256-128(k_sh, T)
The mark is used to easily locate the MAC which is the last part of the
handshake. k_sh is the 256-bit HMAC key which is used by the client to
authenticate outgoing data. It is derived from k_t (which is embedded in
the ticket) as described in Section 2.3. The MAC is defined as:
MAC = HMAC-SHA256-128(k_sh, T | P | M | E)
The variable E is a string representation of the current Unix epoch divided
by 3600. It represents the amount of hours which have passed since the
epoch. It is used by the client and the server to prove liveness. For
example, the Unix timestamp 1378768086 would map to E = 1378768086 / 3600 =
"382991". While the client MUST determine E, the server can simply echo
the client's E in its response.
Client Server Legend:
| T | P | M | MAC(T | P | M | E) | T: session ticket
| -------------------------------> | P: random padding
| AEnc(k_t+1 | T_t+1) | M: mark to locate the MAC
| <------------------------------- | E: approximate timestamp
| AEnc(Tor traffic) | k_t+1: future master key
| <------------------------------> | T_t+1: future ticket
The server is initially unable to distinguish between a session ticket
handshake and a UniformDH handshake as both handshakes are computationally
indistinguishable from randomness. Therefore, it first tries to
opportunistically decrypt the session ticket T after verifying its MAC. If
the ticket's MAC (which should not be confused with the handshake message's
MAC) is valid and the ticket can be decrypted and is not yet expired, the
server then verifies the MAC which is built over T | P | M | E. If this
MAC is valid, the handshake succeeded. The server, like the client, then
proceeds to derive session keys from the 256-bit master key as described in
Section 2.3.
After a ticket handshake succeeded, the server replies by issuing a new
session ticket T_t+1 together with the according master key k_t+1. The
tuple can then be used by the client to authenticate itself the next time.
2.3 Key Derivation
After authenticating either by redeeming a ticket or by running UniformDH,
a client and server will have a shared 256-bit master key. Overall, 144
bytes of key material is derived from the master key using HKDF based on
SHA256. For expansion, the master key is used as HKDF's PRK and the empty
string as HKDF's "info" argument.
The 144-byte output is used as follows. The byte offsets are in decimal.
Bytes 000:031 - 256-bit AES-CTR session key to send data.
Bytes 032:039 - 64-bit AES-CTR IV to send data.
Bytes 040:071 - 256-bit AES-CTR session key to receive data.
Bytes 072:079 - 64-bit AES-CTR IV to receive data.
Bytes 080:111 - 256-bit HMAC-SHA256-128 key to send data.
Bytes 112:143 - 256-bit HMAC-SHA256-128 key to receive data.
3. Header Format
ScrambleSuit defines a 21-byte message header which contains the
transported data. After authentication, all data is transported by
encrypting it, authenticating it, and wrapping it in ScrambleSuit messages
whose header is depicted below.
+----------+------------+--------------+--------+------------+------------+
| 16 bytes | 2 bytes | 2 bytes | 1 byte | (optional) | (optional) |
| MAC | Total len. | Payload len. | Flags | Payload | Padding |
+----------+------------+--------------+--------+------------+------------+
\_ Plain _/ \____________ Encrypted and authenticated __________________/
The 16-byte MAC refers to HMAC-SHA256-128 which is keyed by a dedicated
HMAC key which is derived from the session's master key (see Section 2.3).
The MAC authenticates the remainder of the message. In accordance with the
encrypt-then-MAC principle, the MAC is built over the already-encrypted
remainder of the message.
The 2-byte total length refers to the overall length of the message
excluding the header whereas the 2-byte payload length refers to the
payload only. The difference between total length and payload length is
padding which is used for packet length obfuscation. Note that both fields
can be set to 0 which results in an empty protocol message. ScrambleSuit's
maximum message length is 1448 bytes. Exluding the header, this results in
1427 bytes for the transported data.
The 1-byte flag field is used for protocol signalling. Below, all defined
flags along with their semantics are explained.
Flag name | Bit # | Description
----------------+-------+--------------------------------------------------
FLAG_PAYLOAD | 1 | The entire payload consists of encrypted
| | application data which must be forwarded to the
| | application.
----------------+-------+--------------------------------------------------
FLAG_NEW_TICKET | 2 | The payload holds a newly issued session ticket
| | and master key. The format is:
| | 32-byte master key | 112-byte ticket
----------------+-------+--------------------------------------------------
FLAG_PRNG_SEED | 3 | The payload holds the PRNG seed which is used to
| | derive obfuscation distributions. The format is:
| | 32-byte PRNG seed
----------------+-------+--------------------------------------------------
Finally, a ScrambleSuit message contains the transported data which is
followed by padding. Padding MUST always be discarded. Since padding is
always encrypted, client and server MAY simply pad with 0 bytes.
When ScrambleSuit protocol messages are received, the receiver first MUST
validate the MAC. The receiver may only process messages if the MAC is
valid. If the MAC is invalid, the TCP connection MUST be terminated
immediately.
4. Protocol Polymorphism
Implementations SHOULD implement protocol polymorphism whose purpose is to
modify ScrambleSuit's flow signature. In particular, the packet length
distribution and the distribution of inter-arrival times are modified.
To alter these two flow signatures, implementations maintain two discrete
probability distributions from which random samples are drawn. These
random samples dictate specific inter-arrival times and packet lengths.
Both probability distributions are generated based on a random 256-bit PRNG
seed which is unique for every ScrambleSuit server. Servers communicate
their seed to clients in a dedicated protocol message whose FLAG_PRNG_SEED
bit is set. The client then extracts the PRNG seed and derives its own
probability distributions.
4.1 Deriving Probability Distributions
Probability distributions SHOULD be derived from the 256-bit seed using a
cryptographically secure PRNG. After the CSPRNG was seeded, the amount of
bins for the respective probability distribution must be determined.
Depending on the CSPRNG's output, the amount SHOULD be uniformly chosen
from {1..100}. The exact way how the CSPRNG's output is used is up to the
implementation.
After the amount of bins has been determined, every bin is assigned a value
together with a corresponding probability which is in the interval ]0, 1].
The probability of all bins sums up to 1. Again, the exact way how the
CSPRNG's output is used is up to the implementation.
For the packet length distribution, all values SHOULD be in {21..1448}.
For the inter-arrival time distribution, all values SHOULD be in the
interval [0, 0.01].
Since the distributions are generated randomly, it is possible that they
cause particularly bad throughput. To prevent this, implementations MAY
trade off obfuscation for additional throughput by carefully tuning the
above parameters.
4.2 Packet Length Obfuscation
In general, ScrambleSuit transmits MTU-sized segments as long as there is
enough data in the send buffer. Packet length obfuscation only kicks in
once the send buffer is almost processed and a segment smaller than the MTU
would have to be sent.
Instead of simply flushing the send buffer, a random sample from the
discrete packet length probability distribution is drawn. Padding messages
are then appended so that the size of the last segment in the burst equals
the freshly drawn sample.
4.3 Inter-arrival Time Obfuscation
To obfuscate inter-arrival times, implementations could maintain a
dedicated send buffer. As long as there is data in the send buffer, random
samples from the inter-arrival time distribution are drawn. The thread
processing the send buffer is then paused for the duration of the freshly
drawn sample until the next MTU-sized chunk is written to the wire. This
process is repeated until the send buffer is empty.
Note that inter-arrival time obfuscation has a drastic impact on
throughput. As a result, implementations MAY implement packet length
obfuscation but ignore inter-arrival time obfuscation.
5. Session Tickets
ScrambleSuit employs a subset of RFC 5077 [3] as its session ticket
mechanism. In a nutshell, clients can redeem session tickets to
authenticate themselves and bootstrap a ScrambleSuit connection. This
section discusses the format of session tickets and how server's manage
them.
5.1 Session Ticket Structure
Session tickets contain a server's state with the most important element
being the 32-byte master key. The state structure is encrypted using
16-byte AES-CBC and authenticated using HMAC-SHA256. Refer to Section X.X
for how the server manages this key pair. The basic structure of a
112-byte session ticket is depicted below:
+----------+----------+----------+
| 16 bytes | 64 bytes | 32 bytes |
| IV | E(state) | HMAC |
+----------+----------+----------+
The 16-byte IV is used for AES-CBC, MUST come from a CSPRNG and MUST be
different for every session ticket. The 64-byte encrypted state is
described below. The 32-byte HMAC authenticates the ticket. It is defined
as follows:
HMAC = HMAC-SHA256(k, IV | E(state))
Server's MUST verify the HMAC before attempting to decrypt the state.
E(state), the 64-byte encrypted server state, has the following structure
in its decrypted form:
+------------+------------+------------+----------+
| 4 bytes | 18 bytes | 32 bytes | 10 bytes |
| Issue date | Identifier | Master key | Padding |
+------------+------------+------------+----------+
The 4-byte issue date is a Unix epoch and specifies when the ticket was
issued by the server. The 18-byte identifier contains the ASCII string
"ScrambleSuitTicket". It is checked by the server in order to make sure
that the ticket was decrypted successfully. The 32-byte master key is used
to derive session keys as described in Section 2.3. The 10-byte padding is
used to pad the entire structure to 64 byte; a multiple of AES' block size.
The padding is ignored and it MAY consist of 0 bytes.
5.2 Session Ticket Management
Session tickets are encrypted and authenticated with a pair of keys only
known to the server. As a result, tickets are computationally
indistinguishable from randomness and opaque to clients as well as passive
observers.
For encryption, AES-CBC with a 16-byte key is used. For authentication,
HMAC-SHA256 with a 32-byte key is used. The server has to make sure that
the two keys are stored safely. Furthermore, the server SHOULD regularly
rotate its keys. A reasonable key rotation interval would be once a week.
At any given point in time, the server SHOULD have a current, valid key
pair as well as the previous, superseded key pair. The current key pair
SHOULD be used to issue and verify new tickets. The superseded key pair
SHOULD be used to verify tickets which cannot be verified with the current
key pair. The superseded key pair further SHOULD NOT be used to issue new
tickets.
References
[0] https://www.torproject.org/projects/obfsproxy.html.en
[1] http://www.cs.kau.se/philwint/pdf/wpes2013.pdf
[2] https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/doc/obfs3/obfs3-protocol-spec.txt
[3] https://tools.ietf.org/html/rfc5077