Inital move of torbutton website into website trunk.
Jacob Appelbaum

Jacob Appelbaum commited on 2008-07-15 05:48:33
Zeige 8 geänderte Dateien mit 4302 Einfügungen und 0 Löschungen.

... ...
@@ -0,0 +1 @@
1
+xsltproc  --output index.html.en  --stringparam section.autolabel.max.depth 2 --stringparam  section.autolabel 1 /usr/share/sgml/docbook/xsl-stylesheets--1.73.2/xhtml/docbook.xsl design.xml 
... ...
@@ -0,0 +1,2312 @@
1
+<?xml version="1.0" encoding="ISO-8859-1"?>
2
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
+     "file:///usr/share/sgml/docbook/xml-dtd-4.4-1.0-30.1/docbookx.dtd">
4
+
5
+<article id="design">
6
+ <articleinfo>
7
+  <title>Torbutton Design Documentation</title>
8
+   <author>
9
+    <firstname>Mike</firstname><surname>Perry</surname>
10
+    <affiliation>
11
+     <address><email>mikeperry.fscked/org</email></address>
12
+    </affiliation>
13
+   </author>
14
+   <pubdate>July 4 2008</pubdate>
15
+ </articleinfo>
16
+
17
+<sect1>
18
+  <title>Introduction</title>
19
+  <para>
20
+
21
+This document describes the goals, operation, and testing procedures of the
22
+Torbutton Firefox extension. It is current as of Torbutton 1.2.0rc5.
23
+
24
+  </para>
25
+  <sect2 id="adversary">
26
+   <title>Adversary Model</title>
27
+   <para>
28
+
29
+A Tor web browser adversary has a number of goals, capabilities, and attack
30
+types that can be used to guide us towards a set of requirements for the
31
+Torbutton extension. Let's start with the goals.
32
+
33
+   </para>
34
+   <sect3>
35
+    <title>Adversary Goals</title>
36
+    <orderedlist>
37
+<!-- These aren't really commands.. But it's the closest I could find in an
38
+acceptable style.. Don't really want to make my own stylesheet -->
39
+     <listitem><command>Bypassing proxy settings</command>
40
+     <para>The adversary's primary goal is direct compromise and bypass of 
41
+Tor, causing the user to directly connect to an IP of the adversary's
42
+choosing.</para>
43
+     </listitem>
44
+     <listitem><command>Correlation of Tor vs Non-Tor Activity</command>
45
+     <para>If direct proxy bypass is not possible, the adversary will likely
46
+happily settle for the ability to correlate something a user did via Tor with
47
+their non-Tor activity. This can be done with cookies, cache identifiers,
48
+javascript events, and even CSS. Sometimes the fact that a user uses Tor may
49
+be enough for some authorities.</para>
50
+     </listitem>
51
+     <listitem><command>History disclosure</command>
52
+     <para>
53
+The adversary may also be interested in history disclosure: the ability to
54
+query a user's history to see if they have issued certain censored search
55
+queries, or visited censored sites.
56
+     </para>
57
+     </listitem>
58
+     <listitem><command>Location information</command>
59
+     <para>
60
+
61
+Location information such as timezone and locality can be useful for the
62
+adversary to determine if a user is in fact originating from one of the
63
+regions they are attempting to control, or to zero-in on the geographical
64
+location of a particular dissident or whistleblower.
65
+
66
+     </para>
67
+     </listitem>
68
+     <listitem><command>Miscellaneous anonymity set reduction</command>
69
+     <para>
70
+
71
+Anonymity set reduction is also useful in attempting to zero in on a
72
+particular individual. If the dissident or whistleblower is using a rare build
73
+of Firefox for an obscure operating system, this can be very useful
74
+information for tracking them down, or at least <link
75
+linkend="fingerprinting">tracking their activities</link>.
76
+
77
+     </para>
78
+     </listitem>
79
+     <listitem><command>History records and other on-disk
80
+information</command>
81
+     <para>
82
+In some cases, the adversary may opt for a heavy-handed approach, such as
83
+seizing the computers of all Tor users in an area (especially after narrowing
84
+the field by the above two pieces of information). History records and cache
85
+data are the primary goals here.
86
+     </para>
87
+     </listitem>
88
+    </orderedlist>
89
+   </sect3>
90
+
91
+   <sect3>
92
+    <title>Adversary Capabilities - Positioning</title>
93
+    <para>
94
+The adversary can position themselves at a number of different locations in
95
+order to execute their attacks.
96
+    </para>
97
+    <orderedlist>
98
+     <listitem><command>Exit Node or Upstream Router</command>
99
+     <para>
100
+The adversary can run exit nodes, or alternatively, they may control routers
101
+upstream of exit nodes. Both of these scenarios have been observed in the
102
+wild.
103
+     </para>
104
+     </listitem>
105
+     <listitem><command>Adservers and/or Malicious Websites</command>
106
+     <para>
107
+The adversary can also run websites, or more likely, they can contract out
108
+ad space from a number of different adservers and inject content that way. For
109
+some users, the adversary may be the adservers themselves. It is not
110
+inconceivable that adservers may try to subvert or reduce a user's anonymity 
111
+through Tor for marketing purposes.
112
+     </para>
113
+     </listitem>
114
+     <listitem><command>Local Network/ISP/Upstream Router</command>
115
+     <para>
116
+The adversary can also inject malicious content at the user's upstream router
117
+when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
118
+activity.
119
+     </para>
120
+     </listitem>
121
+     <listitem><command>Physical Access</command>
122
+     <para>
123
+Some users face adversaries with intermittent or constant physical access.
124
+Users in Internet cafes, for example, face such a threat. In addition, in
125
+countries where simply using tools like Tor is illegal, users may face
126
+confiscation of their computer equipment for excessive Tor usage or just
127
+general suspicion.
128
+     </para>
129
+     </listitem>
130
+    </orderedlist>
131
+   </sect3>
132
+
133
+   <sect3>
134
+    <title>Adversary Capabilities - Attacks</title>
135
+    <para>
136
+The adversary can perform the following attacks from a number of different 
137
+positions to accomplish various aspects of their goals.
138
+    </para>
139
+    <orderedlist>
140
+     <listitem><command>Inserting Javascript</command>
141
+     <para>
142
+Javascript allows the adversary the opportunity to accomplish a number of
143
+their goals. If not properly disabled, Javascript event handlers and timers
144
+can cause the browser to perform network activity after Tor has been disabled,
145
+thus allowing the adversary to correlate Tor and Non-Tor activity. Javascript
146
+also allows the adversary to execute <ulink
147
+url="http://gemal.dk/browserspy/css.html">history disclosure attacks</ulink>:
148
+to query the history via the different attributes of 'visited' links. Finally,
149
+Javascript can be used to query the user's timezone via the
150
+<function>Date()</function> object, and to reduce the anonymity set by querying
151
+the <function>navigator</function> object for operating system, CPU, and user
152
+agent information.
153
+     </para>
154
+     </listitem>
155
+
156
+     <listitem><command>Inserting Plugins</command>
157
+     <para>
158
+
159
+Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
160
+capable of performing network activity that the author has
161
+investigated is also capable of performing network activity independent of
162
+browser proxy settings - and often independent of its own proxy settings.
163
+In addition, plugins can be used to store unique identifiers that are more
164
+difficult to clear than standard cookies. 
165
+<ulink url="http://epic.org/privacy/cookies/flash.html">Flash-based
166
+cookies</ulink> fall into this category, but there are likely numerous other
167
+examples.
168
+
169
+     </para>
170
+     </listitem>
171
+     <listitem><command>Inserting CSS</command>
172
+     <para>
173
+
174
+CSS can also be used to correlate Tor and Non-Tor activity, via the usage of
175
+<ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">CSS
176
+popups</ulink> - essentially CSS-based event handlers that fetch content via
177
+CSS's onmouseover attribute. If these popups are allowed to perform network
178
+activity in a different Tor state than they were loaded in, they can easily
179
+correlate Tor and Non-Tor activity and reveal a user's IP address. In
180
+addition, CSS can also be used without Javascript to perform <ulink
181
+url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only history disclosure
182
+attacks</ulink>.
183
+     </para>
184
+     </listitem>
185
+     <listitem><command>Read and insert cookies</command>
186
+     <para>
187
+
188
+An adversary in a position to perform MITM content alteration can inject
189
+document content elements to both read and inject cookies for
190
+arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
191
+sort of <ulink url="http://seclists.org/bugtraq/2007/Aug/0070.html">active
192
+sidejacking</ulink>.
193
+
194
+     </para>
195
+     </listitem>
196
+     <listitem><command>Create arbitrary cached content</command>
197
+     <para>
198
+
199
+Likewise, the browser cache can also be used to <ulink
200
+url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
201
+identifiers</ulink>. Since by default the cache has no same-origin policy,
202
+these identifiers can be read by any domain, making them an ideal target for
203
+adserver-class adversaries.
204
+
205
+     </para>
206
+     </listitem>
207
+     <listitem id="fingerprinting"><command>Fingerprint users based on browser
208
+attributes</command>
209
+<para>
210
+
211
+There is an absurd amount of information available to websites via attributes
212
+of the browser. This information can be used to reduce anonymity set, or even
213
+<ulink url="http://0x000000.com/index.php?i=520&amp;bin=1000001000">uniquely
214
+fingerprint individual users</ulink>. </para>
215
+<para>
216
+For illustration, let's perform a
217
+back-of-the-envelope calculation on the number of anonymity sets for just the
218
+resolution information available in the <ulink
219
+url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
220
+<ulink
221
+url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>
222
+objects. Browser window resolution information provides something like
223
+(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
224
+information contributes about another factor of 5 (for about 5 resolutions in
225
+typical use). In addition, the dimensions and position of the desktop taskbar
226
+are available, which can reveal hints on OS information. This boosts the count
227
+by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
228
+and Gnome, and None). Subtracting the browser content window
229
+size from the browser outer window size provide yet more information.
230
+Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
231
+2<superscript>3</superscript>=8). Interface effects such as titlebar fontsize
232
+and window manager settings gives a factor of about 9 (say 3 common font sizes
233
+for the titlebar and 3 common sizes for browser GUI element fonts).
234
+Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
235
+2<superscript>29</superscript>, or a 29 bit identifier based on resolution
236
+information alone. </para>
237
+
238
+<para>
239
+
240
+Of course, this space is non-uniform and prone to incremental changes.
241
+However, if a bit vector space consisting of the above extracted attributes
242
+were used instead of the hash approach from <ulink
243
+url="http://0x000000.com/index.php?i=520&amp;bin=1000001000">The Hacker
244
+Webzine article above</ulink>, minor changes in browser window resolution will
245
+no longer generate totally new identifiers. 
246
+
247
+</para>
248
+<para>
249
+
250
+To add insult to injury, <ulink
251
+url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
252
+attacks</ulink> mean that each and every extension on <ulink
253
+url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
254
+to that 2<superscript>29</superscript>. With hundreds of popular extensions
255
+and thousands of extensions total, it is easy to see that this sort of
256
+information is an impressively powerful identifier if used properly by a
257
+competent and determined adversary such as an ad network.  Again, a
258
+nearest-neighbor bit vector space approach here would also gracefully handle
259
+incremental changes to installed extensions.
260
+
261
+</para>
262
+
263
+     </listitem>
264
+     <listitem><command>Remotely or locally exploit browser and/or
265
+OS</command>
266
+     <para>
267
+Last, but definitely not least, the adversary can exploit either general 
268
+browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
269
+install malware and surveillance software. An adversary with physical access
270
+can perform similar actions. Regrettably, this last attack capability is
271
+outside of Torbutton's ability to defend against, but it is worth mentioning
272
+for completeness.
273
+     </para>
274
+     </listitem>
275
+    </orderedlist>
276
+   </sect3>
277
+
278
+  </sect2>
279
+
280
+  <sect2 id="requirements">
281
+   <title>Torbutton Requirements</title>
282
+<note>
283
+
284
+Since many settings satisfy multiple requirements, this design document is
285
+organized primarily by Torbutton components and settings. However, if you are
286
+the type that would rather read the document from the requirements
287
+perspective, it is in fact possible to search for each of the following
288
+requirement phrases in the text to find the relevant features that help meet
289
+that requirement.
290
+
291
+</note>
292
+   <para>
293
+
294
+From the above Adversary Model, a number of requirements become clear. 
295
+
296
+   </para>
297
+
298
+<orderedlist> 
299
+<!-- These aren't really commands.. But it's the closest I could find in an
300
+acceptable style.. Don't really want to make my own stylesheet -->
301
+ <listitem id="proxy"><command>Proxy Obedience</command> 
302
+ <para>The browser
303
+MUST NOT bypass Tor proxy settings for any content.</para></listitem>
304
+ <listitem id="isolation"><command>Network Isolation</command>
305
+ <para>Pages MUST NOT perform any network activity in a Tor state different
306
+ from the state they were originally loaded in.</para></listitem>
307
+ <listitem id="state"><command>State Separation</command>
308
+ <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
309
+ one Tor state MUST NOT be accessible via the network in
310
+ another Tor state.</para></listitem>
311
+ <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
312
+the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
313
+users whose network fingerprint does not obviously betray the fact that they
314
+are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
315
+reveal its presence while Tor is disabled.</para></listitem>
316
+ <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
317
+ in memory beyond the duration of one Tor toggle.</para></listitem>
318
+ <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
319
+ timezone or locale via Tor.</para></listitem>
320
+ <listitem id="setpreservation"><command>Anonymity Set
321
+Preservation</command><para>The browser SHOULD NOT leak any other anonymity set reducing information 
322
+ (such as user agent, extension presence, and resolution information)
323
+automatically via Tor. The assessment of the attacks above should make it clear
324
+that anonymity set reduction is a very powerful method of tracking and
325
+eventually identifying anonymous users.
326
+</para></listitem>
327
+ <listitem id="updates"><command>Update Safety</command><para>The browser
328
+SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
329
+ <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
330
+ enable the user to switch between a number of different proxies. It MUST
331
+ provide full Tor protection in the event a third-party proxy switcher has
332
+ enabled the Tor proxy settings.</para></listitem>
333
+</orderedlist>
334
+  </sect2>
335
+  <sect2 id="layout">
336
+   <title>Extension Layout</title>
337
+
338
+<para>Firefox extensions consist of two main categories of code: 'Components' and
339
+'Chrome'. Components are a fancy name for classes that implement a given
340
+interface or interfaces. In Firefox, components <ulink
341
+url="http://www.xulplanet.com/references/xpcomref/creatingcomps.html">can be
342
+written</ulink> in C++,
343
+Javascript, or a mixture of both. Components have two identifiers: their
344
+'<ulink
345
+url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
346
+ID</ulink>' (a human readable path-like string), and their '<ulink
347
+url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
348
+ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
349
+'Interface ID'. It is possible to 'hook' system components - to reimplement
350
+their interface members with your own wrappers - but only if the rest of the
351
+browser refers to the component by its Contract ID. If the browser refers to
352
+the component by Class ID, it bypasses your hooks in that use case.
353
+Technically, it may be possible to hook Class IDs by unregistering the
354
+original component, and then re-registering your own, but this relies on
355
+obsolete and deprecated interfaces and has proved to be less than
356
+stable.</para>
357
+
358
+<para>'Chrome' is a combination of XML and Javascript used to describe a window.
359
+Extensions are allowed to create 'overlays' that are 'bound' to existing XML
360
+window definitions, or they can create their own windows. The DTD for this XML
361
+is called <ulink
362
+url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
363
+  </sect2>
364
+</sect1>
365
+<sect1>
366
+  <title>Components</title>
367
+  <para>
368
+
369
+Torbutton installs components for two purposes: hooking existing components to
370
+reimplement their interfaces; and creating new components that provide
371
+services to other pieces of the extension.
372
+ 
373
+  </para>
374
+
375
+  <sect2>
376
+   <title>Hooked Components</title>
377
+
378
+<para>Torbutton makes extensive use of Contract ID hooking, and implements some
379
+of its own standalone components as well.  Let's discuss the hooked components
380
+first.</para>
381
+
382
+<sect3 id="sessionstore">
383
+ <title><ulink
384
+url="http://developer.mozilla.org/en/docs/nsISessionStore">@mozilla.org/browser/sessionstore;1</ulink> -
385
+<ulink
386
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore2.js">components/nsSessionStore2.js</ulink>
387
+and <ulink
388
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.js">components/nsSessionStore3.js</ulink></title>
389
+
390
+<para>These components address the <link linkend="disk">Disk Avoidance</link>
391
+requirements of Torbutton. As stated in the requirements, Torbutton needs to
392
+prevent Tor tabs from being written to disk by the Firefox session store for a
393
+number of reasons, primary among them is the fact that Firefox can crash at
394
+any time, and a restart can cause you to fetch tabs in the incorrect Tor
395
+state.</para>
396
+
397
+<para>These components illustrate a complication with Firefox hooking: you can
398
+only hook member functions of a class if they are published in an
399
+interface that the class implements. Unfortunately, the sessionstore has no
400
+published interface that is amenable to disabling the writing out of Tor tabs
401
+in specific. As such, Torbutton had to include the <emphasis>entire</emphasis>
402
+nsSessionStore from both Firefox 2 and Firefox 3, 
403
+with a couple of modifications to prevent tabs that were loaded with Tor
404
+enabled from being written to disk, and some version detection code to
405
+determine which component to load. The <ulink
406
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.diff">diff against the original session
407
+store</ulink> is included in the SVN repository.</para>
408
+</sect3>
409
+<sect3>
410
+<title><ulink
411
+url="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js">@mozilla.org/browser/sessionstartup;1</ulink> -
412
+    <ulink
413
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js">components/crash-observer.js</ulink></title>
414
+
415
+<para>This component wraps the Firefox Session Startup component that is in
416
+charge of <ulink
417
+url="http://developer.mozilla.org/en/docs/Session_store_API">restoring saved
418
+sessions</ulink>. The wrapper's only job is to intercept the
419
+<function>doRestore()</function> function, which is called by Firefox if it is determined that the
420
+browser crashed and the session needs to be restored. The wrapper notifies the
421
+Torbutton chrome that the browser crashed by setting the pref
422
+<command>extensions.torbutton.crashed</command>, or that it is a normal
423
+startup via the pref <command>extensions.torbutton.noncrashed</command>. The Torbutton Chrome <ulink
424
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver">listens for a
425
+preference change</ulink> for this value and then does the appropriate cleanup. This
426
+includes setting the Tor state to the one the user selected for crash recovery
427
+in the preferences window (<command>extensions.torbutton.restore_tor</command>), and
428
+restoring cookies for the corresponding cookie jar, if it exists.</para>
429
+
430
+<para>By performing this notification, this component assists in the 
431
+<link linkend="proxy">Proxy Obedience</link>, and <link
432
+linkend="isolation">Network Isolation</link> requirements.
433
+</para>
434
+
435
+
436
+</sect3>
437
+<sect3>
438
+<title><ulink
439
+url="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html">@mozilla.org/browser/global-history;2</ulink>
440
+- <ulink
441
+  url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
442
+
443
+<para>This component was contributed by <ulink
444
+url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
445
+CSS and Javascript-based methods of history disclosure. The global-history
446
+component is what is used by Firefox to determine if a link was visited or not
447
+(to apply the appropriate style to the link). By hooking the <ulink
448
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_isVisited">isVisited</ulink>
449
+and <ulink 
450
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_addURI">addURI</ulink>
451
+methods, Torbutton is able to selectively prevent history items from being
452
+added or being displayed as visited, depending on the Tor state and the user's
453
+preferences.
454
+</para>
455
+<para>
456
+This component helps satisfy the <link linkend="state">State Separation</link>
457
+and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
458
+</para>
459
+</sect3>
460
+</sect2>
461
+<sect2>
462
+<title>New Components</title>
463
+
464
+<para>Torbutton creates four new components that are used throughout the
465
+extension. These components do not hook any interfaces, nor are they used
466
+anywhere besides Torbutton itself.</para>
467
+
468
+<sect3>
469
+<title><ulink
470
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2
471
+- components/cookie-jar-selector.js</ulink></title>
472
+
473
+<para>The cookie jar selector (also based on code from <ulink
474
+url="http://www.collinjackson.com/">Collin
475
+Jackson</ulink>) is used by the Torbutton chrome to switch between
476
+Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
477
+move the current cookies.txt file to the appropriate backup location
478
+(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
479
+into place.</para>
480
+
481
+<para>
482
+This component helps to address the <link linkend="state">State
483
+Isolation</link> requirement of Torbutton.
484
+</para>
485
+
486
+</sect3>
487
+<sect3>
488
+<title><ulink
489
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
490
+- components/torbutton-logger.js</ulink></title>
491
+
492
+<para>The torbutton logger component allows on-the-fly redirection of torbutton
493
+logging messages to either Firefox stderr
494
+(<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
495
+(<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
496
+available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
497
+change the loglevel on the fly by changing
498
+<command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
499
+</para>
500
+</sect3>
501
+<sect3 id="windowmapper">
502
+
503
+<title><ulink
504
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
505
+- components/window-mapper.js</ulink></title>
506
+
507
+<para>Torbutton tags Firefox <ulink
508
+url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">tabs</ulink> with a special variable that indicates the Tor
509
+state the tab was most recently used under to fetch a page. The problem is
510
+that for many Firefox events, it is not possible to determine the tab that is
511
+actually receiving the event. The Torbutton window mapper allows the Torbutton
512
+chrome and other components to look up a <ulink
513
+url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">browser
514
+tab</ulink> for a given <ulink
515
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDOMWindow.html">HTML content
516
+window</ulink>. It does this by traversing all windows and all browsers, until it
517
+finds the browser with the requested <ulink
518
+url="http://www.xulplanet.com/references/elemref/ref_browser.html#prop_contentWindow">contentWindow</ulink> element. Since the content policy
519
+and page loading in general can generate hundreds of these lookups, this
520
+result is cached inside the component.
521
+</para>
522
+</sect3>
523
+<sect3 id="contentpolicy">
524
+<title><ulink
525
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1
526
+- components/cssblocker.js</ulink></title>
527
+
528
+<para>This is a key component to Torbutton's security measures. When Tor is
529
+toggled, Javascript is disabled, and pages are instructed to stop loading.
530
+However, CSS is still able to perform network operations by loading styles for
531
+onmouseover events and other operations. In addition, favicons can still be
532
+loaded by the browser. The cssblocker component prevents this by implementing
533
+and registering an <ulink
534
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html">nsIContentPolicy</ulink>.
535
+When an nsIContentPolicy is registered, Firefox checks every attempted network
536
+request against its <ulink
537
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html#method_shouldLoad">shouldLoad</ulink>
538
+member function to determine if the load should proceed. In Torbutton's case,
539
+the content policy looks up the appropriate browser tab using the <link
540
+linkend="windowmapper">window mapper</link>,
541
+and checks that tab's load tag against the current Tor state. If the tab was
542
+loaded in a different state than the current state, the fetch is denied.
543
+Otherwise, it is allowed.</para> This helps to achieve the <link
544
+linkend="isolation">Network
545
+Isolation</link> requirements of Torbutton.
546
+
547
+<para>In addition, the content policy also blocks website javascript from
548
+<ulink url="http://pseudo-flaw.net/content/tor/torbutton/">querying for
549
+versions and existence of extension chrome</ulink> while Tor is enabled, and
550
+also masks the presence of Torbutton to website javascript while Tor is
551
+disabled. </para>
552
+
553
+<para>
554
+
555
+Finally, some of the work that logically belongs to the content policy is
556
+instead handled by the <command>torbutton_http_observer</command> and
557
+<command>torbutton_weblistener</command> in <ulink
558
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
559
+Firefox 3 favicon loads, popups, and full page plugins, which for whatever
560
+reason are not passed to the Firefox content policy itself (see Firefox Bugs 
561
+<ulink
562
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and 
563
+<ulink
564
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
565
+
566
+</para>
567
+
568
+<!-- 
569
+FIXME: Hrmm, the content policy doesn't really lend itself well to display 
570
+this way.. People looking for this much detail should consult the source.
571
+
572
+<para>
573
+    <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
574
+    <tgroup cols='5' align='left' colsep='1' rowsep='1'>
575
+       <tbody>
576
+       <row>
577
+         <entry></entry>
578
+         <entry>chrome/resource</entry>
579
+         <entry>a3</entry>
580
+         <entry>a4</entry>
581
+         <entry>a5</entry>
582
+       </row>
583
+       <row>
584
+         <entry>file</entry>
585
+         <entry>b2</entry>
586
+         <entry>b3</entry>
587
+         <entry>b4</entry>
588
+         <entry>b5</entry>
589
+       </row>
590
+       <row>
591
+         <entry>c1</entry>
592
+         <entry>c2</entry>
593
+         <entry>c3</entry>
594
+         <entry>c4</entry>
595
+         <entry>c5</entry>
596
+       </row>
597
+       <row>
598
+         <entry>d1</entry>
599
+         <entry>d2</entry>
600
+         <entry>d3</entry>
601
+         <entry>d4</entry>
602
+         <entry>d5</entry>
603
+       </row>
604
+       </tbody>
605
+       </tgroup>
606
+       </table>
607
+</para>
608
+-->
609
+
610
+<para>
611
+
612
+This helps to fulfill both the <link
613
+linkend="setpreservation">Anonymity Set Preservation</link> and the <link
614
+linkend="undiscoverability">Tor Undiscoverability</link> requirements of
615
+Torbutton.</para>
616
+
617
+</sect3>
618
+</sect2>
619
+</sect1>
620
+<sect1>
621
+ <title>Chrome</title>
622
+
623
+<para>The chrome is where all the torbutton graphical elements and windows are
624
+located. Each window is described as an <ulink
625
+url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
626
+files attached. The scope of these Javascript files is their containing
627
+window.</para>
628
+
629
+<sect2 id="browseroverlay">
630
+<title>Browser Overlay - <ulink
631
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
632
+
633
+<para>The browser overlay, torbutton.xul, defines the toolbar button, the status
634
+bar, and events for toggling the button. The overlay code is in <ulink
635
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
636
+It contains event handlers for preference update, shutdown, upgrade, and
637
+location change events.</para>
638
+
639
+<para>The <ulink
640
+url="http://www.xulplanet.com/references/xpcomref/comps/c_docloaderservice1.html">location
641
+change</ulink> <ulink
642
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">webprogress
643
+listener</ulink>, <command>torbutton_weblistener</command> is perhaps the
644
+most important part of the chrome from a security standpoint. It is a <ulink
645
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">web
646
+progress listener</ulink> that handles
647
+receiving an event every time a page load or iframe load occurs. This class
648
+eventually calls down to <function>torbutton_update_tags()</function> and 
649
+<function>torbutton_hookdoc()</function>, which apply the browser Tor load state tags, plugin
650
+permissions, and install the Javascript hooks to hook the <ulink
651
+url="http://phrogz.net/objJob/object.asp?id=224">Date</ulink> object and
652
+the <ulink
653
+url="http://developer.mozilla.org/en/docs/DOM:window.navigator">navigator</ulink> object (for timezone and platform information,
654
+respectively).</para> 
655
+<para>
656
+The browser overlay helps to satisfy a number of Torbutton requirements. These
657
+are better enumerated in each of the Torbutton preferences below. However,
658
+there are also a number of Firefox preferences set in
659
+<function>torbutton_update_status()</function> that aren't governed by any
660
+Torbutton setting. These are:
661
+</para>
662
+<orderedlist>
663
+
664
+ <listitem><ulink
665
+url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
666
+<para>
667
+This pref is set in an attempt to disable the fetching of LiveBookmarks via
668
+Tor. Since users can potentially collect a large amount of live bookmarks to
669
+very personal sites (blogs of friends, wikipedia articles they maintain,
670
+comment feeds of their own blog), it is not possible to cleanly isolate these
671
+fetches and they are simply disabled during Tor usage.
672
+This helps to address the <link
673
+linkend="state">State Separation</link> requirement.
674
+Unfortunately <ulink
675
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
676
+436250</ulink> prevents this from
677
+functioning completely correctly.
678
+</para>
679
+  </listitem>
680
+
681
+ <listitem><ulink
682
+url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
683
+ <para>
684
+Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
685
+reads from <command>extensions.torbutton.banned_ports</command>) to the list
686
+of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
687
+and the Tor control port, respectively. This is set for both Tor and Non-Tor
688
+usage, and prevents websites from attempting to do http fetches from these
689
+ports to see if they are open, which addresses the <link
690
+linkend="undiscoverability">Tor Undiscoverability</link> requirement.
691
+ </para>
692
+ </listitem>
693
+ <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
694
+ <para>
695
+This setting is currently always disabled. If anyone ever complains saying
696
+that they *want* their browser to be able to send ping notifications to a
697
+page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
698
+my breath. I haven't checked if the content policy is called for pings, but if
699
+not, this setting helps with meeting the <link linkend="isolation">Network
700
+Isolation</link> requirement.
701
+ </para>
702
+ </listitem>
703
+ <listitem><ulink
704
+url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
705
+ <para>
706
+Likewise for this setting. I find it hard to imagine anyone who wants to ask
707
+Google in real time if each URL they visit is safe, especially when the list
708
+of unsafe URLs is downloaded anyway. This helps fulfill the <link
709
+linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
710
+browsing history from ending up on Google's disks.
711
+ </para>
712
+ </listitem>
713
+ <listitem><ulink
714
+url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
715
+ <para>
716
+Safebrowsing does <ulink
717
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
718
+updates under Firefox 2</ulink>, so it is disabled during Tor usage. 
719
+This helps fulfill the <link linkend="updates">Update
720
+Safety</link> requirement. Firefox 3 has the fix for that bug, and so
721
+safebrowsing updates are enabled during Tor usage.
722
+ </para>
723
+ </listitem>
724
+ <listitem><ulink
725
+url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
726
+ <para>
727
+If Tor is enabled, we need to prevent random external applications from
728
+launching without at least warning the user. This group of settings only
729
+partially accomplishes this, however. Applications can still be launched via
730
+plugins. The mechanisms for handling this are described under the "Disable
731
+Plugins During Tor Usage" preference. This helps fulfill the <link
732
+linkend="proxy">Proxy Obedience</link> requirement, by preventing external
733
+applications from accessing network resources at the command of Tor-fetched
734
+pages.
735
+ </para>
736
+</listitem>
737
+</orderedlist>
738
+</sect2>
739
+<sect2>
740
+ <title>Preferences Window - <ulink
741
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
742
+
743
+<para>The preferences window of course lays out the Torbutton preferences, with
744
+handlers located in <ulink
745
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
746
+</sect2>
747
+<sect2>
748
+ <title>Other Windows</title>
749
+
750
+<para>There are additional windows that describe popups for right clicking on
751
+the status bar, the toolbutton, and the about page.</para>
752
+
753
+</sect2>
754
+</sect1>
755
+
756
+<sect1>
757
+ <title>Toggle Code Path</title>
758
+ <para>
759
+
760
+The act of toggling is connected to <function>torbutton_toggle()</function>
761
+via the <ulink
762
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
763
+and <ulink
764
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/popup.xul">popup.xul</ulink>
765
+overlay files. Most of the work in the toggling process is present in <ulink
766
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink> 
767
+
768
+</para>
769
+<para>
770
+
771
+Toggling is a 3 stage process: Button Click, Proxy Update, and
772
+Settings Update. These stages are reflected in the prefs
773
+<command>extensions.torbutton.tor_enabled</command>,
774
+<command>extensions.torbutton.proxies_applied</command>, and
775
+<command>extensions.torbutton.settings_applied</command>. The reason for the
776
+three stage preference update is to ensure immediate enforcement of <link
777
+linkend="isolation">Network Isolation</link> via the <link
778
+linkend="contentpolicy">content policy</link>. Since the content window
779
+javascript runs on a different thread than the chrome javascript, it is
780
+important to properly convey the stages to the content policy to avoid race
781
+conditions and leakage, especially with <ulink
782
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
783
+409737</ulink> unfixed. The content policy does not allow any network activity
784
+whatsoever during this three stage transition.
785
+
786
+ </para>
787
+ <sect2>
788
+  <title>Button Click</title>
789
+  <para>
790
+
791
+This is the first step in the toggling process. When the user clicks the
792
+toggle button or the toolbar, <function>torbutton_toggle()</function> is
793
+called. This function checks the current Tor status by comparing the current
794
+proxy settings to the selected Tor settings, and then sets the proxy settings
795
+to the opposite state, and sets the pref
796
+<command>extensions.torbutton.tor_enabled</command> to reflect the new state.
797
+It is this proxy pref update that gives notification via the <ulink
798
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver">pref
799
+observer</ulink>
800
+<command>torbutton_unique_pref_observer</command> to perform the rest of the
801
+toggle.
802
+
803
+  </para>
804
+ </sect2>
805
+ <sect2>
806
+  <title>Proxy Update</title>
807
+  <para>
808
+
809
+When Torbutton receives any proxy change notifications via its
810
+<command>torbutton_unique_pref_observer</command>, it calls
811
+<function>torbutton_set_status()</function> which checks against the Tor
812
+settings to see if the Tor proxy settings match the current settings. If so,
813
+it calls <function>torbutton_update_status()</function>, which determines if
814
+the Tor state has actually changed, and sets
815
+<command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
816
+state value, and ensures that
817
+<command>extensions.torbutton.tor_enabled</command> is also set to the correct
818
+value. This is decoupled from the button click functionalty via the pref
819
+observer so that other addons (such as SwitchProxy) can switch the proxy
820
+settings between multiple proxies.
821
+
822
+  </para>
823
+ </sect2>
824
+ <sect2>
825
+  <title>Settings Update</title>
826
+  <para>
827
+
828
+The next stage is also handled by
829
+<function>torbutton_update_status()</function>. This function sets scores of
830
+Firefox preferences, saving the original values to prefs under
831
+<command>extensions.torbutton.saved.*</command>, and performs the history
832
+clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
833
+end of its work, it sets
834
+<command>extensions.torbutton.settings_applied</command>, which signifies the
835
+completion of the toggle operation to the <link
836
+linkend="contentpolicy">content policy</link>.
837
+
838
+  </para>
839
+ </sect2>
840
+</sect1>
841
+
842
+<sect1>
843
+ <title>Description of Options</title>
844
+
845
+<para>This section provides a detailed description of Torbutton's options. Each
846
+option is presented as the string from the preferences window, a summary, the
847
+preferences it touches, and the effect this has on the components, chrome, and
848
+browser properties.</para>
849
+ <sect2>
850
+  <title>Test Settings</title>
851
+  <para>
852
+This button under the Proxy Settings tab provides a way to verify that the 
853
+proxy settings are correct, and actually do route through the Tor network. It
854
+performs this check by issuing an <ulink
855
+url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
856
+for <ulink
857
+url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
858
+This is a special page that returns very simple, yet well-formed XHTML that
859
+Torbutton can easily inspect for a hidden link with an id of
860
+<command>TorCheckResult</command> and a target of <command>success</command>
861
+or <command>failure</command> to indicate if the
862
+user hit the page from a Tor IP, a non-Tor IP. This check is handled in
863
+<function>torbutton_test_settings()</function> in <ulink
864
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink>.
865
+Presenting the results to the user is handled by the <ulink
866
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul">preferences
867
+window</ulink>
868
+callback <function>torbutton_prefs_test_settings()</function> in <ulink
869
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js">preferences.js</ulink>.  
870
+
871
+  </para>
872
+ </sect2>
873
+ <sect2 id="plugins">
874
+  <title>Disable plugins on Tor Usage (crucial)</title>
875
+
876
+ <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
877
+
878
+ <para>Enabling this preference causes the above mentioned Torbutton chrome web progress
879
+ listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
880
+ plugins via the browser <ulink
881
+ url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html">docShell</ulink>
882
+ attribute <command>allowPlugins</command>. These flags are set every time a new window is
883
+ created (<function>torbutton_tag_new_browser()</function>), every time a web
884
+load
885
+event occurs
886
+ (<function>torbutton_update_tags()</function>), and every time the tor state is changed
887
+ (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
888
+ prevented from loading by the content policy in <ulink
889
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
890
+ enabled and this option is set.
891
+ </para> 
892
+ 
893
+ <para>Even all this turns out to be insufficient if the user directly
894
+ clicks on a plugin-handled mime-type. <ulink
895
+url="http://www.janusvm.com/goldy/pdf/">In this case</ulink> (and also <ulink
896
+url="http://www.janusvm.com/goldy/side-channels/frames/">this
897
+one</ulink>), the browser decides that
898
+ maybe it should ignore all these other settings and load the plugin anyways,
899
+ because maybe the user really did want to load it (never mind this same
900
+ load-style could happen automatically  with meta-refresh or any number of
901
+ other ways..). To handle these cases, Torbutton stores a list of plugin-handled
902
+ mime-types, and sets the pref
903
+<command>plugin.disable_full_page_plugin_for_types</command> to this list.
904
+Additionally, (since nothing can be assumed when relying on Firefox
905
+preferences and internals) if it detects a load of one of them from the web progress
906
+ listener, it cancels the request, tells the associated DOMWindow 
907
+to stop loading, clears the document, AND throws an exception. Anything short 
908
+of all this and
909
+ the plugin managed to find some way to load.
910
+ </para>
911
+ 
912
+ <para>
913
+ All this could be avoided, of course, if Firefox would either <ulink
914
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
915
+ allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
916
+ loads either <ulink
917
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
918
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
919
+ not very encouraging. 
920
+ </para>
921
+ <para>
922
+
923
+Since most plugins completely ignore browser proxy settings, the actions
924
+performed by this setting are crucial to satisfying the <link
925
+linkend="proxy">Proxy Obedience</link> requirement.
926
+
927
+ </para>
928
+</sect2>
929
+<sect2>
930
+ <title>Isolate Dynamic Content to Tor State (crucial)</title>
931
+
932
+ <para>Option: <command>extensions.torbutton.isolate_content</command></para>
933
+
934
+<para>Enabling this preference is what enables the <ulink
935
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
936
+mentioned above, and causes it to block content load attempts in pages an
937
+opposite Tor state from the current state. Freshly loaded <ulink
938
+url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">browser
939
+tabs</ulink> are tagged 
940
+with a <command>__tb_load_state</command> member in
941
+<function>torbutton_update_tags()</function> and this
942
+value is compared against the current tor state in the content policy.</para>
943
+
944
+<para>It also kills all Javascript in each page loaded under that state by
945
+toggling the <command>allowJavascript</command> <ulink
946
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html">docShell</ulink> property, and issues a
947
+<ulink
948
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebNavigation.html#method_stop">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
949
+equivalent of hitting the STOP button).</para>
950
+
951
+<para>
952
+
953
+Unfortunately, <ulink
954
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
955
+409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
956
+all event handlers, and event handlers registered with <ulink
957
+url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
958
+are still able to execute. The <link linkend="contentpolicy">Torbutton Content
959
+Policy</link> should prevent such code from performing network activity within
960
+the current tab, but activity that happens via a popup window or via a
961
+Javascript redirect can still slip by. For this reason, Torbutton blocks
962
+popups by checking for a valid <ulink
963
+url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
964
+attribute in <function>torbutton_check_progress()</function>. If the window
965
+has an opener from a different Tor state, its load is blocked. The content
966
+policy also takes similar action to prevent Javascript redirects. This also
967
+has the side effect/feature of preventing the user from following any links
968
+from a page loaded in an opposite Tor state.
969
+
970
+</para>
971
+
972
+<para>
973
+This setting is responsible for satisfying the <link
974
+linkend="isolation">Network Isolation</link> requirement.
975
+</para>
976
+
977
+</sect2>
978
+<sect2 id="jshooks">
979
+
980
+<title>Hook Dangerous Javascript (crucial)</title>
981
+
982
+ <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
983
+
984
+<para>This setting enables injection of the <ulink
985
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/jshooks.js">Javascript
986
+hooking code</ulink>. Javascript is injected into
987
+pages to hook the <ulink url="http://phrogz.net/objJob/object.asp?id=224">Date
988
+class</ulink> to mask your timezone. This is done in the chrome in
989
+<function>torbutton_hookdoc()</function>, which is called ultimately by both the 
990
+<ulink
991
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">webprogress
992
+listener</ulink> <command>torbutton_weblistener</command> and the <link
993
+linkend="contentpolicy">content policy</link> (the latter being a hack to handle
994
+javascript: urls). This behavior helps to satisfy the <link
995
+linkend="location">Location Neutrality</link> requirement.
996
+
997
+</para>
998
+<para>
999
+
1000
+In addition, this setting also hooks various resolution properties of the
1001
+<ulink url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink>,
1002
+<ulink
1003
+url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>,
1004
+and <ulink
1005
+url="http://developer.mozilla.org/en/docs/DOM:window.navigator">window.navigator</ulink>
1006
+to mask window size information and user agent properties not handled by the
1007
+standard Firefox user agent override settings. The resolution hooks
1008
+effectively make the Firefox browser window appear to websites as if the renderable area
1009
+takes up the entire desktop, has no toolbar or other GUI element space, and
1010
+the desktop itself has no toolbars.
1011
+These hooks drastically reduce the amount of information available to do <link
1012
+linkend="fingerprinting">anonymity set reduction attacks</link> and help to
1013
+meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
1014
+requirements.
1015
+
1016
+</para>
1017
+</sect2>
1018
+<sect2>
1019
+<title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
1020
+
1021
+ <para>Option: <command>extensions.torbutton.resize_windows</command></para>
1022
+
1023
+<para>
1024
+
1025
+This option drastically cuts down on the number of distinct anonymity sets
1026
+that divide the Tor web userbase. Without this setting, the dimensions for a
1027
+typical browser window range from 600-1200 horizontal pixels and 400-1000
1028
+vertical pixels, or about 600x600 = 360000 different sets. Resizing the
1029
+browser window to multiples of 50 on each side reduces the number of sets by
1030
+50^2, bringing the total number of sets to 144. Of course, the distribution
1031
+among these sets are not uniform, but scaling by 50 will improve the situation
1032
+due to this non-uniformity for users in the less common resolutions.
1033
+Obviously the ideal situation would be to lie entirely about the browser
1034
+window size, but this will likely cause all sorts of rendering issues, and is
1035
+also not implementable in a foolproof way from extension land.
1036
+
1037
+</para>
1038
+<para>
1039
+
1040
+The implementation of this setting is spread across a couple of different
1041
+locations in the Torbutton javascript <link linkend="browseroverlay">browser
1042
+overlay</link>. Since resizing minimized windows causes them to be restored,
1043
+and since maximized windows remember their previous size to the pixel, windows
1044
+must be resized before every document load (at the time of browser tagging)
1045
+via <function>torbutton_check_round()</function>, called by
1046
+<function>torbutton_update_tags()</function>. To prevent drift, the extension
1047
+tracks the original values of the windows and uses this to perform the
1048
+rounding on document load. In addition, to prevent the user from resizing a
1049
+window to a non-50px multiple, a resize listener
1050
+(<function>torbutton_do_resize()</function>) is installed on every new browser
1051
+window to record the new size and round it to a 50px multiple while Tor is
1052
+enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
1053
+are set. This ensures that there is no discrepancy between the 50 pixel cutoff
1054
+and the actual renderable area of the browser (so that it is not possible to
1055
+infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
1056
+
1057
+</para>
1058
+<para>
1059
+This setting helps to meet the <link
1060
+linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1061
+</para>
1062
+</sect2>
1063
+<sect2>
1064
+<title>Disable Updates During Tor (recommended)</title>
1065
+
1066
+  <para>Option: <command>extensions.torbutton.no_updates</command></para>
1067
+
1068
+  <para>This setting causes Torbutton to disable the four <ulink
1069
+url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
1070
+update settings</ulink> during Tor
1071
+  usage: <command>extensions.update.enabled</command>,
1072
+<command>app.update.enabled</command>,
1073
+  <command>app.update.auto</command>, and
1074
+<command>browser.search.update</command>.  These prevent the
1075
+  browser from updating extensions, checking for Firefox upgrades, and
1076
+  checking for search plugin updates while Tor is enabled.
1077
+  </para>
1078
+<para>
1079
+This setting satisfies the <link
1080
+linkend="updates">Update Safety</link> requirement.
1081
+</para>
1082
+</sect2>
1083
+<sect2>
1084
+
1085
+<title>Disable Search Suggestions during Tor (recommended)</title>
1086
+
1087
+  <para>Option: <command>extensions.torbutton.no_search</command></para>
1088
+
1089
+<para>
1090
+This setting causes Torbutton to disable <ulink
1091
+url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1092
+during Tor usage.
1093
+This governs if you get Google search suggestions during Tor
1094
+usage. Your Google cookie is transmitted with google search suggestions, hence
1095
+this is recommended to be disabled.
1096
+
1097
+</para>
1098
+<para>
1099
+While this setting doesn't satisfy any Torbutton requirements, the fact that
1100
+cookies are transmitted for partially typed queries does not seem desirable
1101
+for Tor usage.
1102
+</para>
1103
+</sect2>
1104
+<sect2>
1105
+<title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1106
+  <para>Option:
1107
+   <simplelist>
1108
+   <member><command>extensions.torbutton.block_tor_file_net</command></member>
1109
+   <member><command>extensions.torbutton.block_nontor_file_net</command></member>
1110
+   </simplelist>
1111
+  </para>
1112
+
1113
+<para>
1114
+
1115
+These settings prevent file urls from performing network operations during the
1116
+respective Tor states. Firefox 2's implementation of same origin policy allows
1117
+file urls to read and <ulink
1118
+url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
1119
+arbitrary files from the local filesystem</ulink> to arbitrary websites. To
1120
+make matters worse, the 'Content-Disposition' header can be injected
1121
+arbitrarily by exit nodes to trick users into running arbitrary html files in
1122
+the local context. These preferences cause the <link
1123
+linkend="contentpolicy">content policy</link> to block access to any network
1124
+resources from File urls during the appropriate Tor state.
1125
+
1126
+</para>
1127
+<para>
1128
+
1129
+This preference helps to ensure Tor's <link linkend="isolation">Network
1130
+Isolation</link> requirement, by preventing file urls from executing network
1131
+operations in opposite Tor states. Also, allowing pages to submit arbitrary
1132
+files to arbitrary sites just generally seems like a bad idea.
1133
+ 
1134
+</para>
1135
+</sect2>
1136
+<sect2>
1137
+
1138
+<title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1139
+
1140
+  <para>Options: 
1141
+   <simplelist>
1142
+   <member><command>extensions.torbutton.close_nontor</command></member>
1143
+   <member><command>extensions.torbutton.close_tor</command></member>
1144
+   </simplelist>
1145
+  </para>
1146
+
1147
+<para>
1148
+
1149
+These settings cause Torbutton to enumerate through all windows and close all
1150
+tabs in each window for the appropriate Tor state. This code can be found in
1151
+<function>torbutton_update_status()</function>.  The main reason these settings
1152
+exist is as a backup mechanism in the event of any Javascript or content policy
1153
+leaks due to <ulink
1154
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1155
+409737</ulink>.  Torbutton currently tries to block all Javascript network
1156
+activity via the content policy, but until that bug is fixed, there is some
1157
+risk that there are alternate ways to bypass the policy. This option is
1158
+available as an extra assurance of <link linkend="isolation">Network
1159
+Isolation</link> for those who would like to be sure that when Tor is toggled
1160
+all page activity has ceased. It also serves as a potential future workaround
1161
+in the event a content policy failure is discovered, and provides an additional
1162
+level of protection for the <link linkend="disk">Disk Avoidance</link>
1163
+protection so that browser state is not sitting around waiting to be swapped
1164
+out longer than necessary.
1165
+
1166
+</para>
1167
+<para>
1168
+While this setting doesn't satisfy any Torbutton requirements, the fact that
1169
+cookies are transmitted for partially typed queries does not seem desirable
1170
+for Tor usage.
1171
+</para>
1172
+</sect2>
1173
+
1174
+<sect2>
1175
+<title>Isolate Access to History navigation to Tor state (crucial)</title>
1176
+  <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1177
+  <para>
1178
+This setting determines if Torbutton installs an <ulink
1179
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistoryListener.html">nsISHistoryListener</ulink>
1180
+attached to the <ulink
1181
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html">sessionHistory</ulink> of 
1182
+of each browser's <ulink
1183
+url="http://www.xulplanet.com/references/xpcomref/comps/c_webshell1.html">webNavigatator</ulink>.
1184
+The nsIShistoryListener is instantiated with a reference to the containing
1185
+browser window and blocks the back, forward, and reload buttons on the browser
1186
+navigation bar when Tor is in an opposite state than the one to load the
1187
+current tab. In addition, Tor clears the session history during a new document
1188
+load if this setting is enabled. 
1189
+
1190
+  </para>
1191
+  <para>
1192
+
1193
+This is marked as a crucial setting in part
1194
+because Javascript access to the history object is indistinguishable from 
1195
+user clicks, and because
1196
+<ulink
1197
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1198
+409737</ulink> allows javascript to execute in opposite Tor states, javascript
1199
+can issue reloads after Tor toggle to reveal your original IP. Even without
1200
+this bug, however, Javascript is still able to access previous pages in your
1201
+session history that may have been loaded under a different Tor state, to
1202
+attempt to correlate your activity.
1203
+
1204
+   </para>
1205
+   <para>
1206
+
1207
+This setting helps to fulfill Torbutton's <link linkend="state">State
1208
+Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
1209
+requirements.
1210
+
1211
+   </para>
1212
+</sect2>
1213
+
1214
+
1215
+<sect2>
1216
+<title>History Access Settings</title>
1217
+
1218
+  <para>Options:
1219
+  <simplelist>
1220
+   <member><command>extensions.torbutton.block_thread</command></member>
1221
+   <member><command>extensions.torbutton.block_nthread</command></member>
1222
+   <member><command>extensions.torbutton.block_thwrite</command></member>
1223
+   <member><command>extensions.torbutton.block_nthwrite</command></member>
1224
+  </simplelist>
1225
+  </para>
1226
+
1227
+<para>These four settings govern the behavior of the <ulink
1228
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js">components/ignore-history.js</ulink>
1229
+history blocker component mentioned above. By hooking the browser's view of
1230
+the history itself via the <ulink
1231
+url="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html">mozilla.org/browser/global-history;2</ulink>
1232
+component, this mechanism defeats all document-based <ulink
1233
+url="http://gemal.dk/browserspy/css.html">history disclosure
1234
+attacks</ulink>, including <ulink
1235
+url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
1236
+</para>
1237
+<para>
1238
+
1239
+On Firefox 3, the history write settings also govern if Torbutton sets
1240
+<command>browser.history_expire_days</command> to 0 on the appropriate Tor
1241
+state, which <ulink
1242
+url="http://developer.mozilla.org/en/docs/index.php?title=nsINavHistoryService#Attributes">should
1243
+disable</ulink> all <ulink
1244
+url="http://developer.mozilla.org/en/docs/Places">Places</ulink> database
1245
+writes.
1246
+
1247
+</para>
1248
+<para>
1249
+This setting helps to satisfy the <link
1250
+linkend="state">State Separation</link> and <link
1251
+linkend="disk">Disk Avoidance</link> requirements.
1252
+</para>
1253
+
1254
+</sect2>
1255
+<sect2>
1256
+
1257
+<title>Clear History During Tor Toggle (optional)</title>
1258
+
1259
+<para>Option: <command>extensions.torbutton.clear_history</command></para>
1260
+
1261
+<para>This setting governs if Torbutton calls
1262
+<ulink
1263
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIBrowserHistory.html#method_removeAllPages">nsIBrowserHistory.removeAllPages</ulink>
1264
+and <ulink
1265
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html#method_PurgeHistory">nsISHistory.PurgeHistory</ulink>
1266
+for each tab on Tor toggle.</para>
1267
+<para>
1268
+This setting is an optional way to help satisfy the <link
1269
+linkend="state">State Separation</link> requirement.
1270
+</para>
1271
+
1272
+</sect2>
1273
+<sect2>
1274
+
1275
+<title>Block Password+Form saving during Tor/Non-Tor</title>
1276
+
1277
+<para>Options:
1278
+  <simplelist>
1279
+  <member><command>extensions.torbutton.block_tforms</command></member>
1280
+  <member><command>extensions.torbutton.block_ntforms</command></member>
1281
+  </simplelist>
1282
+  </para>
1283
+
1284
+<para>These settings govern if Torbutton disables
1285
+<command>browser.formfill.enable</command>
1286
+and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
1287
+Since form fields can be read at any time by Javascript, this setting is a lot
1288
+more important than it seems.
1289
+</para>
1290
+
1291
+<para>
1292
+This setting helps to satisfy the <link
1293
+linkend="state">State Separation</link> and <link
1294
+linkend="disk">Disk Avoidance</link> requirements.
1295
+</para>
1296
+
1297
+</sect2>
1298
+<sect2>
1299
+  <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
1300
+
1301
+  <para>Option: <command>extensions.torbutton.clear_cache</command>
1302
+  </para>
1303
+
1304
+<para>This option causes Torbutton to call <ulink
1305
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsICacheService.html#method_evictEntries">nsICacheService.evictEntries(0)</ulink>
1306
+on Tor toggle to remove all entries from the cache. In addition, this setting
1307
+causes Torbutton to set <ulink
1308
+url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
1309
+</para>
1310
+<para>
1311
+This setting helps to satisfy the <link
1312
+linkend="state">State Separation</link> and <link
1313
+linkend="disk">Disk Avoidance</link> requirements.
1314
+</para>
1315
+
1316
+</sect2>
1317
+<sect2>
1318
+  <title>Block disk and memory cache during Tor</title>
1319
+
1320
+<para>Option: <command>extensions.torbutton.block_cache</command></para>
1321
+
1322
+<para>This setting
1323
+causes Torbutton to set <ulink
1324
+url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
1325
+<ulink
1326
+url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
1327
+<ulink
1328
+url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
1329
+</para>
1330
+<para>
1331
+This setting helps to satisfy the <link
1332
+linkend="state">State Separation</link> and <link
1333
+linkend="disk">Disk Avoidance</link> requirements.
1334
+</para>
1335
+
1336
+</sect2>
1337
+<sect2>
1338
+  <title>Clear Cookies on Tor Toggle</title>
1339
+
1340
+<para>Option: <command>extensions.torbutton.clear_cookies</command>
1341
+  </para>
1342
+
1343
+<para>
1344
+
1345
+This setting causes Torbutton to call <ulink
1346
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsICookieManager.html#method_removeAll">nsICookieManager.removeAll()</ulink> on
1347
+every Tor toggle. In addition, this sets <ulink
1348
+url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1349
+to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1350
+which prevents them from being written to disk. 
1351
+
1352
+</para>
1353
+<para>
1354
+This setting helps to satisfy the <link
1355
+linkend="state">State Separation</link> and <link
1356
+linkend="disk">Disk Avoidance</link> requirements.
1357
+</para>
1358
+
1359
+</sect2>
1360
+<sect2>
1361
+  
1362
+  <title>Store Non-Tor cookies in a protected jar</title>
1363
+
1364
+<para>Option: <command>extensions.torbutton.cookie_jars</command>
1365
+  </para>
1366
+
1367
+<para>
1368
+
1369
+This setting causes Torbutton to use <ulink
1370
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2</ulink> to store
1371
+non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
1372
+before restoring the jar.
1373
+</para>
1374
+<para>
1375
+This setting also sets <ulink
1376
+url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1377
+to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1378
+which prevents them from being written to disk. 
1379
+
1380
+</para>
1381
+
1382
+<para>
1383
+This setting helps to satisfy the <link
1384
+linkend="state">State Separation</link> and <link
1385
+linkend="disk">Disk Avoidance</link> requirements.
1386
+</para>
1387
+
1388
+
1389
+</sect2>
1390
+<sect2>
1391
+
1392
+  <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
1393
+
1394
+<para>Option: <command>extensions.torbutton.dual_cookie_jars</command>
1395
+  </para>
1396
+
1397
+<para>
1398
+
1399
+This setting causes Torbutton to use <ulink
1400
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2</ulink> to store
1401
+both Tor and Non-Tor cookies into protected jars.
1402
+</para>
1403
+
1404
+<para>
1405
+This setting helps to satisfy the <link
1406
+linkend="state">State Separation</link> requirement.
1407
+</para>
1408
+
1409
+
1410
+</sect2>
1411
+
1412
+
1413
+<sect2>
1414
+
1415
+  <title>Manage My Own Cookies (dangerous)</title>
1416
+
1417
+<para>Options: None</para>
1418
+<para>This setting disables all Torbutton cookie handling by setting the above
1419
+cookie prefs all to false.</para>
1420
+</sect2>
1421
+<sect2>
1422
+
1423
+<sect2>
1424
+  <title>Do not write Tor/Non-Tor cookies to disk</title>
1425
+  <para>Options:
1426
+  <simplelist>
1427
+  <member><command>extensions.torbutton.tor_memory_jar</command></member>
1428
+  <member><command>extensions.torbutton.nontor_memory_jar</command></member>
1429
+  </simplelist>
1430
+  </para>
1431
+
1432
+<para>
1433
+These settings (contributed by arno) cause Torbutton to set <ulink
1434
+url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1435
+to 2 during the appropriate Tor state, and to store cookies acquired in that
1436
+state into a Javascript
1437
+<ulink
1438
+url="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X">E4X</ulink>
1439
+object as opposed to writing them to disk.
1440
+</para>
1441
+
1442
+<para>
1443
+This allows Torbutton to provide an option to preserve a user's 
1444
+cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
1445
+requirement.
1446
+</para>
1447
+</sect2>
1448
+
1449
+
1450
+  <title>Disable DOM Storage during Tor usage (crucial)</title>
1451
+
1452
+<para>Option: <command>extensions.torbutton.disable_domstorage</command>
1453
+  </para>
1454
+
1455
+<para>
1456
+
1457
+This setting causes Torbutton to toggle <command>dom.storage.enabled</command> during Tor
1458
+usage to prevent 
1459
+<ulink
1460
+  url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink> from
1461
+  being used to store persistent information across Tor states.</para>
1462
+<para>
1463
+This setting helps to satisfy the <link
1464
+linkend="state">State Separation</link> requirement.
1465
+</para>
1466
+
1467
+</sect2>
1468
+
1469
+<sect2>
1470
+  <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
1471
+<para>Option: <command>extensions.torbutton.clear_http_auth</command>
1472
+  </para>
1473
+
1474
+<para>
1475
+This setting causes Torbutton to call <ulink
1476
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIHttpAuthManager.html#method_clearAll">nsIHttpAuthManager.clearAll()</ulink>
1477
+every time Tor is toggled.
1478
+</para>
1479
+
1480
+<para>
1481
+This setting helps to satisfy the <link
1482
+linkend="state">State Separation</link> requirement.
1483
+</para>
1484
+</sect2>
1485
+
1486
+<sect2>
1487
+
1488
+  <title>Clear cookies on Tor/Non-Tor shutdown</title>
1489
+
1490
+<para>Option: <command>extensions.torbutton.shutdown_method</command>
1491
+  </para>
1492
+
1493
+<para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1494
+cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1495
+clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1496
+for the <ulink
1497
+url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
1498
+<function>torbutton_uninstall_observer()</function> and use <ulink
1499
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2</ulink>
1500
+to clear out all cookies and all cookie jars upon shutdown.  </para>
1501
+<para>
1502
+This setting helps to satisfy the <link
1503
+linkend="state">State Separation</link> requirement.
1504
+</para>
1505
+
1506
+
1507
+</sect2>
1508
+<sect2>
1509
+
1510
+  <title>Reload cookie jar/clear cookies on Firefox crash</title>
1511
+  <para>Options:
1512
+  <simplelist>
1513
+    <member><command>extensions.torbutton.reload_crashed_jar</command></member>
1514
+    <member><command>extensions.torbutton.crashed</command></member>
1515
+  </simplelist>
1516
+  </para>
1517
+
1518
+  <para>This is no longer a user visible option, and is enabled by default. In
1519
+the event of a crash, the Torbutton <ulink
1520
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js">components/crash-observer.js</ulink> 
1521
+  component will notify the Chrome (via the
1522
+  <command>extensions.torbutton.crashed</command> pref and a <ulink
1523
+url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver">pref
1524
+observer</ulink> in
1525
+the chrome that listens for this update), and Torbutton will load the
1526
+  correct jar for the current Tor state via the <ulink
1527
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2</ulink>
1528
+  component.</para>
1529
+
1530
+<para>
1531
+This setting helps to satisfy the <link
1532
+linkend="state">State Separation</link> requirement in the event of Firefox
1533
+crashes.
1534
+</para>
1535
+
1536
+</sect2>
1537
+
1538
+
1539
+<sect2>
1540
+  <title>On crash recovery or session restored startup, restore via: Tor, Non-Tor</title>
1541
+  <para>Options:
1542
+  <simplelist>
1543
+   <member><command>extensions.torbutton.restore_tor</command></member>
1544
+  <member><command>extensions.torbutton.crashed</command></member>
1545
+  </simplelist>
1546
+  </para>
1547
+
1548
+  <para>This option works with the Torbutton <ulink
1549
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js">crash-observer.js</ulink> 
1550
+  to set the Tor state after a crash is detected (via the 
1551
+  <command>extensions.torbutton.crashed</command> pref)</para>
1552
+<para>
1553
+
1554
+Since the Tor state after a Firefox crash is unknown/indeterminate, this
1555
+setting helps to satisfy the <link linkend="state">State Separation</link>
1556
+requirement in the event of Firefox crashes by ensuring all cookies,
1557
+settings and saved sessions are reloaded from a fixed Tor state.
1558
+ 
1559
+</para>
1560
+</sect2>
1561
+
1562
+<sect2>
1563
+  <title>On normal startup, set state to: Tor, Non-Tor, Shutdown State</title>
1564
+
1565
+  <para>Options:
1566
+  <simplelist>
1567
+   <member><command>extensions.torbutton.startup_state</command></member>
1568
+  <member><command>extensions.torbutton.noncrashed</command></member>
1569
+  </simplelist>
1570
+  </para>
1571
+
1572
+  <para>This option also works with the Torbutton <ulink
1573
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js">crash-observer.js</ulink> 
1574
+  to set the Tor state after a normal startup is detected (via the 
1575
+  <command>extensions.torbutton.noncrashed</command> pref)</para>
1576
+
1577
+</sect2>
1578
+
1579
+<sect2>
1580
+  <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
1581
+
1582
+  <para>Options: 
1583
+  <simplelist>
1584
+    <member><command>extensions.torbutton.nonontor_sessionstore</command></member>
1585
+    <member><command>extensions.torbutton.notor_sessionstore</command></member>
1586
+  </simplelist>
1587
+  </para>
1588
+
1589
+  <para>If these options are enabled, the <ulink
1590
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.js">replacement nsSessionStore.js</ulink>
1591
+  component checks the <command>__tb_tor_fetched</command> tag of tabs before writing them
1592
+  out. If the tag is from a blocked Tor state, the tab is not written to disk.
1593
+  </para>
1594
+<para>
1595
+This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
1596
+requirement, and also helps to satisfy the <link
1597
+linkend="state">State Separation</link> requirement in the event of Firefox
1598
+crashes.
1599
+
1600
+</para>
1601
+
1602
+</sect2>
1603
+
1604
+<sect2>
1605
+  
1606
+  <title>Set user agent during Tor usage (crucial)</title>
1607
+  <para>Options:
1608
+   <simplelist>
1609
+    <member><command>extensions.torbutton.set_uagent</command></member>
1610
+    <member><command>extensions.torbutton.oscpu_override</command></member>
1611
+    <member><command>extensions.torbutton.platform_override</command></member>
1612
+    <member><command>extensions.torbutton.productsub_override</command></member>
1613
+    <member><command>extensions.torbutton.appname_override</command></member>
1614
+    <member><command>extensions.torbutton.appversion_override</command></member>
1615
+    <member><command>extensions.torbutton.useragent_override</command></member>
1616
+    <member><command>extensions.torbutton.useragent_vendor</command></member>
1617
+    <member><command>extensions.torbutton.useragent_vendorSub</command></member>
1618
+  </simplelist>
1619
+   </para>
1620
+
1621
+<para>On face, user agent switching appears to be straight-forward in Firefox.
1622
+It provides several options for controlling the browser user agent string:
1623
+<command>general.appname.override</command>,
1624
+<command>general.appversion.override</command>,
1625
+<command>general.platform.override</command>,
1626
+<command>general.useragent.override</command>,
1627
+<command>general.useragent.vendor</command>, and
1628
+<command>general.useragent.vendorSub</command>. If
1629
+the Torbutton preference <command>extensions.torbutton.set_uagent</command> is
1630
+true, Torbutton copies all of the other above prefs into their corresponding
1631
+browser preferences during Tor usage.</para>
1632
+
1633
+<para>However, this is not the whole story. Additionally, even with the above
1634
+prefs set, the <command>oscpu</command>, <command>buildID</command>, and <command>productSub</command> fields of the
1635
+<ulink
1636
+url="http://developer.mozilla.org/en/docs/DOM:window.navigator">navigator</ulink> object are not changed appropriately by the above prefs.
1637
+Javascript hooks implemented in <ulink
1638
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/jshooks.js">chrome/content/jshooks.js</ulink> are installed as part of the
1639
+same mechanism that hooks the date object.
1640
+</para>
1641
+
1642
+<para>
1643
+
1644
+It also turns out that it is possible to detect the original Firefox version
1645
+by <ulink url="http://0x000000.com/index.php?i=523&amp;bin=1000001011">inspecting
1646
+certain resource:// files</ulink>. These cases are handled by Torbutton's
1647
+<link linkend="contentpolicy">content policy</link>.
1648
+
1649
+</para>
1650
+
1651
+
1652
+<para>
1653
+This setting helps to satisfy the <link
1654
+linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1655
+</para>
1656
+
1657
+
1658
+</sect2>
1659
+<sect2>
1660
+
1661
+  <title>Spoof US English Browser</title>
1662
+<para>Options:
1663
+<simplelist>
1664
+ <member><command>extensions.torbutton.spoof_english</command></member>
1665
+ <member><command>extensions.torbutton.spoof_charset</command></member>
1666
+ <member><command>extensions.torbutton.spoof_language</command></member>
1667
+</simplelist>
1668
+</para>
1669
+
1670
+<para> This option causes Torbutton to set
1671
+<command>general.useragent.locale</command>,
1672
+<command>intl.accept_charsets</command> and
1673
+<command>intl.accept_languages</command> to the value specified in
1674
+<command>extensions.torbutton.spoof_locale</command>,
1675
+<command>extensions.torbutton.spoof_charset</command> and
1676
+<command>extensions.torbutton.spoof_language</command> during Tor usage.  </para>
1677
+<para>
1678
+This setting helps to satisfy the <link
1679
+linkend="setpreservation">Anonymity Set Preservation</link> and <link
1680
+linkend="location">Location Neutrality</link> requirements.
1681
+</para>
1682
+
1683
+</sect2>
1684
+<sect2>
1685
+
1686
+  <title>Don't send referrer during Tor Usage</title>
1687
+
1688
+<para>Option: <command>extensions.torbutton.disable_referer</command>
1689
+</para>
1690
+
1691
+<para> 
1692
+This option causes Torbutton to set <ulink
1693
+url="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer">network.http.sendSecureXSiteReferrer</ulink> and
1694
+<ulink
1695
+url="http://kb.mozillazine.org/Network.http.sendRefererHeader">network.http.sendRefererHeader</ulink> during Tor usage.</para>
1696
+
1697
+<para>
1698
+This setting also does not directly satisfy any Torbutton requirement, but
1699
+some may desire to mask their referrer for general privacy concerns.
1700
+</para>
1701
+</sect2>
1702
+
1703
+<sect2>
1704
+
1705
+  <title>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</title>
1706
+
1707
+<para>Options:
1708
+<simplelist>
1709
+ <member><command>extensions.torbutton.jar_certs</command></member>
1710
+ <member><command>extensions.torbutton.jar_ca_certs</command></member>
1711
+</simplelist>
1712
+</para>
1713
+<para>
1714
+
1715
+These settings govern if Torbutton attempts to isolate the user's SSL
1716
+certificates into separate jars for each Tor state. This isolation is
1717
+implemented in <function>torbutton_jar_certs()</function> in <ulink
1718
+url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
1719
+which calls <function>torbutton_jar_cert_type()</function> and
1720
+<function>torbutton_unjar_cert_type()</function> for each certificate type in
1721
+the <ulink
1722
+url="http://www.xulplanet.com/references/xpcomref/comps/c_securitynsscertcache1.html">@mozilla.org/security/nsscertcache;1</ulink>.
1723
+Certificates are deleted from and imported to the <ulink
1724
+url="http://www.xulplanet.com/references/xpcomref/comps/c_securityx509certdb1.html">@mozilla.org/security/x509certdb;1</ulink>.
1725
+</para>
1726
+
1727
+<para>
1728
+The first time this pref is used, a backup of the user's certificates is
1729
+created in their profile directory under the name
1730
+<filename>cert8.db.bak</filename>. This file can be copied back to
1731
+<filename>cert8.db</filename> to fully restore the original state of the
1732
+user's certificates in the event of any error.
1733
+</para>
1734
+
1735
+<para>
1736
+Since exit nodes and malicious sites can insert content elements sourced to
1737
+specific SSL sites to query if a user has a certain certificate,
1738
+this setting helps to satisfy the <link linkend="state">State
1739
+Separation</link> requirement of Torbutton. Unfortunately, <ulink
1740
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Firefox Bug
1741
+435159</ulink> prevents it from functioning correctly in the event of rapid Tor toggle, so it
1742
+is currently not exposed via the preferences UI.
1743
+
1744
+</para>
1745
+
1746
+</sect2>
1747
+</sect1>
1748
+
1749
+<sect1 id="FirefoxBugs">
1750
+  <title>Relevant Firefox Bugs</title>
1751
+  <para>
1752
+
1753
+  </para>
1754
+  <sect2 id="FirefoxSecurity">
1755
+   <title>Bugs impacting security</title>
1756
+   <para>
1757
+
1758
+Torbutton has to work around a number of Firefox bugs that impact its
1759
+security. Most of these are mentioned elsewhere in this document, but they
1760
+have also been gathered here for reference. Several of these have fixes in
1761
+Firefox3.0/trunk, but are listed because they still have not been backported
1762
+to FF2.0. In order of decreasing severity, they are:
1763
+
1764
+   </para>
1765
+   <orderedlist>
1766
+
1767
+   <listitem><ulink
1768
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=392274">Bug 392274 - Timezone
1769
+config/chrome API</ulink>
1770
+   <para>
1771
+The lack of a config or API to configure the timezone requires Torbutton to
1772
+<link linkend="jshooks">insert client content window javascript</link> to hook
1773
+the Date object. Additionally, a way to <ulink
1774
+url="http://pseudo-flaw.net/tor/torbutton/unmask-date.html">remove the Date
1775
+hooks</ulink> was discovered by Greg Fleischer. Worse, on Firefox 3,
1776
+javascript sandboxing prevents most of the javascript hooks from being
1777
+installed, including the Date hooks. On Windows and Linux, you can set the TZ
1778
+environment variable to "UTC" as a workaround. Firefox will obey this
1779
+environment variable for your Timezone on those platforms, but on Windows this
1780
+does not take effect until browser restart. 
1781
+   </para>
1782
+   </listitem>
1783
+
1784
+     <listitem><ulink
1785
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Bug 436250 - Livemarks can't be
1786
+disabled at runtime</ulink>
1787
+      <para>
1788
+
1789
+The RSS Feed based "Livemarks"/"Live Bookmarks" update frequency is controlled
1790
+by the pref <command>browser.bookmarks.livemark_refresh_seconds</command>.
1791
+However, changing this preference does not cancel any pending timers, which
1792
+means that at least one livemarks pref fetch will happen over Tor, and once
1793
+this pref is set to disable livemarks for Tor, changing it back will never
1794
+cause the service to start back up again.
1795
+
1796
+      </para>
1797
+     </listitem>
1798
+
1799
+     <listitem><ulink
1800
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Bug 435159 -
1801
+nsNSSCertificateDB::DeleteCertificate has race conditions</ulink>
1802
+      <para>
1803
+
1804
+In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
1805
+the user has installed. Unfortunately, the method call to delete a certificate
1806
+from the current certificate database acts lazily: it only sets a variable
1807
+that marks a cert for deletion later, and it is not cleared if that
1808
+certificate is re-added. This means that if the Tor state is toggled quickly,
1809
+that certificate could remain present until it is re-inserted (causing an
1810
+error dialog), and worse, it would still be deleted after that.  The lack of
1811
+this functionality is considered a Torbutton security bug because cert
1812
+isolation is considered a <link linkend="state">State Separation</link>
1813
+feature.
1814
+
1815
+      </para>
1816
+     </listitem>
1817
+
1818
+     <listitem><ulink
1819
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Bug 409737 -
1820
+javascript.enabled and docShell.allowJavascript do not disable all event
1821
+handlers</ulink>
1822
+     <para>
1823
+
1824
+This bug allows pages to execute javascript via addEventListener and perhaps
1825
+other callbacks. In order to prevent this bug from enabling an attacker to
1826
+break the <link linkend="isolation">Network Isolation</link> requirement,
1827
+Torbutton 1.1.13 began blocking popups and history manipulation from different
1828
+Tor states.  So long as there are no ways to open popups or redirect the user
1829
+to a new page, the <link linkend="contentpolicy">Torbutton content
1830
+policy</link> should block Javascript network access. However, if there are
1831
+ways to open popups or perform redirects such that Torbutton cannot block
1832
+them, pages may still have free reign to break that requirement and reveal a
1833
+user's original IP address.
1834
+
1835
+     </para>
1836
+     </listitem>
1837
+
1838
+
1839
+     <listitem><ulink
1840
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=405652">Bug 405652 - In the
1841
+TLS ClientHello message the gmt_unix_time is incorrect</ulink>
1842
+     <para>
1843
+
1844
+It turns out that Firefox's SSL implementation sends the machine uptime as the
1845
+current time. This essentially is a unique identifier that can be used for
1846
+the duration of your machine uptime. The issue has been fixed in Firefox 3.0,
1847
+but it has as of yet not been backported to 2.0.
1848
+
1849
+     </para>
1850
+     </listitem>
1851
+     <listitem><ulink
1852
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=143220">Bug 143220 - Script can get the value of a file control, including the path</ulink>
1853
+     <para>
1854
+
1855
+Javascript can query the .value field of file input dialogs to retrieve
1856
+username and sometimes hostname/workgroup information. This is obviously very
1857
+dangerous for people who are attempting to submit files anonymously via
1858
+webforms (ie whistleblowers and anonymous publishers). It is also fixed in
1859
+Firefox 3.0, but has not yet been backported to 2.0.
1860
+
1861
+     </para>
1862
+     </listitem>
1863
+     <listitem><ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=418119">Bug 418119 - nsIContentPolicy not called for external DTDs of XML documents</ulink>
1864
+      <para>
1865
+
1866
+XML documents can source chrome and resource URLs in their DTDs without a call
1867
+to nsIContentPolicy::shouldLoad. Enumerating chrome URLs gives websites and
1868
+exit nodes a lot of information. They can use it to probe for vulnerable
1869
+versions of extensions, and can also use it to build an <link
1870
+linkend="fingerprinting">identifier for tracking purposes</link>.  This bug
1871
+makes it impossible for extensions such as Adblock and Torbutton to prevent
1872
+chrome inspection and enumeration.  There is no workaround for this bug as of
1873
+yet.
1874
+
1875
+      </para>
1876
+     </listitem>
1877
+
1878
+    </orderedlist>
1879
+  </sect2>
1880
+  <sect2 id="FirefoxWishlist">
1881
+   <title>Bugs blocking functionality</title>
1882
+   <para>
1883
+The following bugs impact Torbutton and similar extensions' functionality.
1884
+   </para>
1885
+
1886
+    <orderedlist>
1887
+   <listitem><ulink
1888
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=439384">Bug 439384 -
1889
+"profile-do-change" event does not cause cookie table reload</ulink>
1890
+   <para>
1891
+
1892
+In Firefox 3, the change to the new sqlite database for cookie storage has a
1893
+bug that prevents Torbutton's cookie jaring from working properly. The
1894
+"profile-do-change" observer event no longer properly causes either a sync or
1895
+reload of the cookie database from disk after it is copied into place.
1896
+Torbutton currently works around this by issuing the SQLLite queries manually
1897
+to store and rebuild the cookie database.
1898
+
1899
+   </para>
1900
+   </listitem>
1901
+   <listitem><ulink
1902
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=417869">Bug 417869 -
1903
+Browser context is difficult to obtain from many XPCOM callbacks</ulink>
1904
+   <para>
1905
+
1906
+It is difficult to determine which tabbrowser many XPCOM callbacks originate
1907
+from, and in some cases absolutely no context information is provided at all.
1908
+While this doesn't have much of an effect on Torbutton, it does make writing
1909
+extensions that would like to do per-tab settings and content filters (such as
1910
+FoxyProxy) difficult to impossible to implement securely.
1911
+
1912
+   </para>
1913
+   </listitem>
1914
+   <listitem><ulink
1915
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
1916
+Components do not expose disk interfaces</ulink>
1917
+   <para>
1918
+
1919
+Several components currently provide no way of reimplementing their disk
1920
+access to easily satisfy Torbutton's <link linkend="disk">Disk
1921
+Avoidance</link> requirements. Workarounds exist, but they are <link
1922
+linkend="sessionstore">clunky</link>, and
1923
+some of them involve disabling functionality during Tor usage.
1924
+
1925
+   </para>
1926
+   </listitem>
1927
+
1928
+  </orderedlist>
1929
+  </sect2>
1930
+  <sect2 id="FirefoxMiscBugs">
1931
+   <title>Low Priority Bugs</title>
1932
+   <para>
1933
+The following bugs have an effect upon Torbutton, but are superseded by more
1934
+practical and more easily fixable variant bugs above; or have stable, simple
1935
+workarounds.
1936
+  </para>
1937
+
1938
+    <orderedlist>
1939
+    <listitem><ulink
1940
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=435151">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</ulink>
1941
+     <para>
1942
+
1943
+Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
1944
+constructors of classes defined from within the scope of the sandbox, among
1945
+other things. This prevents Torbutton from applying the Timezone hooks under
1946
+Firefox 3, but a better solution for Torbutton's specific date hooking needs 
1947
+would be a fix for the above mentioned Bug 392274. Of course, many more
1948
+extensions may be interested in the sandbox hooking functionality working
1949
+properly though.
1950
+
1951
+     </para>
1952
+     </listitem>
1953
+    <listitem><ulink
1954
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">Bug 437014 -
1955
+nsIContentPolicy::shouldLoad no longer called for favicons</ulink>
1956
+    <para>
1957
+
1958
+Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
1959
+loads. Torbutton had relied on this call to block favicon loads for opposite
1960
+Tor states. The workaround it employs for Firefox 3 is to cancel the request
1961
+when it arrives in the <command>torbutton_http_observer</command> used for
1962
+blocking full page plugin loads. This seems to work just fine, but is a bit
1963
+dirty.
1964
+
1965
+    </para>
1966
+    </listitem>
1967
+    <listitem><ulink
1968
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=437016">Bug 437016 -
1969
+nsIContentPolicy::shouldLoad not called for livemarks</ulink>
1970
+    <para>
1971
+
1972
+An alternative fix for the livemarks bug above would be to block livemarks
1973
+fetches from the content policy. Unfortunately shouldLoad is not called for
1974
+livemarks fetches.
1975
+
1976
+    </para>
1977
+    </listitem>
1978
+   <listitem><ulink
1979
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=418986">Bug 418986 - window.screen
1980
+provides a large amount of identifiable information</ulink>
1981
+   <para>
1982
+
1983
+As <link linkend="fingerprinting">mentioned above</link>, a large amount of
1984
+information is available from <ulink
1985
+url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>.
1986
+Currently, there is no way to obscure this information without Javascript
1987
+hooking. This bug is a feature request to provide some other method to change
1988
+these values.
1989
+
1990
+   </para>
1991
+   </listitem>
1992
+ 
1993
+     <listitem><ulink
1994
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">Bug 309524</ulink>
1995
+and <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">Bug
1996
+380556</ulink> - nsIContentPolicy::shouldProcess is not called.
1997
+     <para>
1998
+
1999
+This is a call that would be useful to develop a better workaround for the
2000
+allowPlugins issue above. If the content policy were called before a URL was
2001
+handed over to a plugin or helper app, it would make the workaround for the
2002
+above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
2003
+the others though, but it might be nice to have this API as a backup.
2004
+
2005
+     </para>
2006
+     </listitem>
2007
+
2008
+     <listitem><ulink
2009
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">Bug 401296 - docShell.allowPlugins
2010
+not honored for direct links</ulink> (Perhaps subset of <ulink
2011
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=282106">Bug 282106</ulink>?)
2012
+     <para>
2013
+
2014
+Similar to the javascript plugin disabling attribute, the plugin disabling
2015
+attribute is also not perfect &mdash; it is ignored for direct links to plugin
2016
+handled content, as well as meta-refreshes to plugin handled content.  This
2017
+requires Torbutton to listen to a number of different http events to intercept
2018
+plugin-related mime type URLs and cancel their requests. Again, since plugins
2019
+are quite horrible about obeying proxy settings, loading a plugin pretty much
2020
+ensures a way to break the <link linkend="isolation">Network Isolation</link>
2021
+requirement and reveal a user's original IP address. Torbutton's code to
2022
+perform this workaround has been subverted at least once already by Kyle
2023
+Williams.
2024
+
2025
+     </para>
2026
+     </listitem>
2027
+
2028
+   <listitem><ulink
2029
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=418983">Bug 41893 - Scoping
2030
+issues with window.__defineGetter__()</ulink>
2031
+   <para>
2032
+
2033
+For some reason, defining getters off of window seems to mess with the
2034
+implicit window scoping in some documents. There is a workaround for this bug,
2035
+so it is barely relevant. It would be far more useful to eliminate the need
2036
+for Javascript hooking in the first place by addressing the above bugs. This
2037
+bug is just listed for completeness.
2038
+
2039
+   </para>
2040
+   </listitem>
2041
+
2042
+
2043
+   <listitem><ulink
2044
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
2045
+Date' is deletable</ulink>
2046
+     <para>
2047
+
2048
+Based on Page 62 of the <ulink
2049
+url="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">ECMA-262
2050
+Javascript spec</ulink>, it seems like it should be possible to do something
2051
+like the following to prevent the Date object from being unmasked:
2052
+<screen>
2053
+with(window) {
2054
+    var Date = fakeDate;
2055
+    var otherVariable = 42;
2056
+}
2057
+
2058
+delete window.Date; // Should fail. Instead succeeds, revealing original Date.
2059
+delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
2060
+</screen>
2061
+
2062
+From the ECMA-262 spec:
2063
+
2064
+<blockquote>
2065
+If the variable statement occurs inside a FunctionDeclaration, the variables
2066
+are defined with function-local scope in that function, as described in
2067
+s10.1.3. Otherwise, they are defined with global scope (that is, they are
2068
+created as members of the global object, as described in 10.1.3) using
2069
+property attributes { DontDelete }. Variables are created when the execution
2070
+scope is entered. A Block does not define a new execution scope. Only Program
2071
+and FunctionDeclaration produce a new scope. Variables are initialized to
2072
+undefined when created. A variable with an Initialiser is assigned the value
2073
+of its AssignmentExpression when the VariableStatement is executed, not when
2074
+the variable is created.
2075
+</blockquote>
2076
+
2077
+In fact, this is exactly how the with statement with a variable declaration
2078
+behaves <emphasis>for all other variables other than ones that shadow system
2079
+variables</emphasis>. Some variables (such as
2080
+<command>window.screen</command>, and <command>window.history</command>) can't
2081
+even be shadowed in this way, and give an error about lacking a setter. If
2082
+such shadowing were possible, it would greatly simplify the Javascript hooking
2083
+code, which currently relies on undocumented semantics of
2084
+<command>__proto__</command> to copy the original values in the event of a
2085
+delete. This <command>__proto__</command> hack unfortunately does not work for
2086
+the Date object though.
2087
+
2088
+     </para>
2089
+    </listitem>
2090
+
2091
+  </orderedlist>
2092
+  </sect2>
2093
+</sect1>
2094
+
2095
+<sect1 id="TestPlan">
2096
+  <title>Testing</title>
2097
+  <para>
2098
+
2099
+The purpose of this section is to cover all the known ways that Tor browser
2100
+security can be subverted from a testing and penetration perspective. The hope
2101
+is that it will be useful both for creating a &quot;Tor Safety Check&quot;
2102
+page, and for developing novel tests and actively attacking Torbutton with the
2103
+goal of finding vulnerabilities in either it or the Mozilla components,
2104
+interfaces and settings upon which it relies.
2105
+ 
2106
+  </para> 
2107
+  <sect2 id="Categories">
2108
+   <title>Single state testing</title>
2109
+   <para>
2110
+The following tests can be run from a single web page in one visit without
2111
+toggling Tor state or requiring user interaction. Currently they exist as their
2112
+own individual tests, but conceivably a single &quot;Tor Safety Check&quot;
2113
+page can be devised that contains all of these attacks. 
2114
+All of these tests are currently known to pass, but that does not mean that
2115
+consolidating them into an easy to run test page is pointless. Torbutton is a
2116
+complicated piece of software. During development, changes to one component
2117
+can affect a whole slough of unrelated features. Having easy-to-verify
2118
+comprehensive test pages would make it much easier to fix other issues as they
2119
+present themselves without introducing regressions.
2120
+
2121
+   </para>
2122
+   <sect3>
2123
+    <title>Java and Plugin Decloaking</title>
2124
+    <para>
2125
+As <link linkend="plugins">mentioned above</link>, Java and plugins <ulink
2126
+url="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html">can query</ulink> the <ulink
2127
+url="http://www.rgagnon.com/javadetails/java-0095.html">local IP
2128
+address</ulink> and report it back to the
2129
+remote site. They can also <ulink url="http://metasploit.com/research/misc/decloak/index.htm">bypass proxy settings</ulink> and directly connect to a
2130
+remote site without Tor. Every browser plugin we have tested with Firefox has
2131
+some form of network capability, and every one ignores proxy settings or worse - only
2132
+partially obeys them. This includes but is not limited to:
2133
+QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
2134
+Flash. In addition, 
2135
+<ulink url="http://www.janusvm.com/goldy/pdf/">issues have been
2136
+discovered</ulink> with the browsers handling of
2137
+<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">direct links to plugin-handled
2138
+content</ulink> as well as meta-refreshes to plugin content. To make matters
2139
+worse, <ulink
2140
+url="http://www.janusvm.com/goldy/side-channels/side-channels.html">externally
2141
+handled mime types and urls</ulink> can also cause direct non-Tor connections
2142
+as well.
2143
+    </para>
2144
+   </sect3>
2145
+   <sect3>
2146
+    <title>History Disclosure attacks</title>
2147
+    <para>
2148
+The browser's history can also be queried by a remote site to inspect for
2149
+Google queries, visits to sites that contain usernames in the URLs, or
2150
+other anonymity set reducing information. This can be done by either
2151
+<ulink url="http://gemal.dk/browserspy/css.html">Javascript</ulink>, or by 
2152
+<ulink url="http://ha.ckers.org/weird/CSS-history.cgi">CSS</ulink> without any scripting involved.
2153
+
2154
+    </para>
2155
+   </sect3>
2156
+   <sect3>
2157
+    <title>User agent, extension, resolution and OS information</title>
2158
+    <para>
2159
+
2160
+As mentioned above, these properties can be combined to greatly reduce
2161
+anonymity set and even build a potentially <link
2162
+linkend="fingerprinting">globally unique identifier</link> for
2163
+users. <ulink
2164
+url="http://0x000000.com/index.php?i=520&amp;bin=1000001000">Examples of this
2165
+in the wild</ulink> rely on <ulink url="http://gemal.dk/browserspy/basic.html">user agent and OS
2166
+information</ulink> as well as <ulink
2167
+url="http://pseudo-flaw.net/content/tor/torbutton/">chrome disclosure
2168
+information</ulink>.
2169
+
2170
+    </para>
2171
+   </sect3>
2172
+   <sect3>
2173
+    <title>Timezone and Location Information</title>
2174
+    <para>
2175
+<ulink url="http://gemal.dk/browserspy/date.html">Time and Timezone</ulink>
2176
+should be obscured to be GMT-only, and by the browser should present itself
2177
+with an US English locale.
2178
+    </para>
2179
+   </sect3>
2180
+  </sect2>
2181
+  <sect2>
2182
+   <title>Multi-state testing</title>
2183
+   <para>
2184
+
2185
+The tests in this section are geared towards a page that would instruct the
2186
+user to toggle their Tor state after the fetch and perform some operations:
2187
+mouseovers, stray clicks, and potentially reloads.
2188
+
2189
+   </para>
2190
+   <sect3>
2191
+    <title>Cookies and Cache Correlation</title>
2192
+    <para>
2193
+The most obvious test is to set a cookie, ask the user to toggle tor, and then
2194
+have them reload the page. The cookie should no longer be set if they are
2195
+using the default Torbutton settings. In addition, it is possible to leverage
2196
+the cache to <ulink
2197
+url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
2198
+identifiers</ulink>. The default settings of Torbutton should also protect
2199
+against these from persisting across Tor Toggle.
2200
+
2201
+    </para>
2202
+   </sect3>
2203
+   <sect3>
2204
+    <title>Javascript timers and event handlers</title>
2205
+    <para>
2206
+
2207
+Javascript can set timers and register event handlers in the hopes of fetching
2208
+URLs after the user has toggled Torbutton. 
2209
+    </para>
2210
+   </sect3>
2211
+   <sect3>
2212
+    <title>CSS Popups and non-script Dynamic Content</title>
2213
+    <para>
2214
+
2215
+Even if Javascript is disabled, CSS is still able to 
2216
+<ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">create popup-like
2217
+windows</ulink>
2218
+via the 'onmouseover' CSS attribute, which can cause arbitrary browser
2219
+activity as soon as the mouse enters into the content window. It is also
2220
+possible for meta-refresh tags to set timers long enough to make it likely
2221
+that the user has toggled Tor before fetching content.
2222
+
2223
+    </para>
2224
+   </sect3>
2225
+  </sect2>
2226
+  <sect2>
2227
+   <title>Active testing (aka How to Hack Torbutton)</title>
2228
+   <para>
2229
+
2230
+The idea behind active testing is to discover vulnerabilities in Torbutton to
2231
+bypass proxy settings, run script in an opposite Tor state, store unique
2232
+identifiers, leak location information, or otherwise violate <link
2233
+linkend="requirements">its requirements</link>. Torbutton has ventured out
2234
+into a strange and new security landscape. It depends on Firefox mechanisms
2235
+that haven't necessarily been audited for security, certainly not for the
2236
+threat model that Torbutton seeks to address. As such, it and the interfaces
2237
+it depends upon still need a 'trial by fire' typical of new technologies. This
2238
+section of the document was written with the intention of making that period
2239
+as fast as possible. Please help us get through this period by considering
2240
+these attacks, playing with them, and reporting what you find (and potentially
2241
+submitting the test cases back to be run in the standard batch of Torbutton
2242
+tests.
2243
+
2244
+   </para>
2245
+   <sect3>
2246
+    <title>Some suggested vectors to investigate</title>
2247
+    <para>
2248
+    <itemizedlist>
2249
+     <listitem>Strange ways to register Javascript <ulink
2250
+url="http://en.wikipedia.org/wiki/DOM_Events">events</ulink> and <ulink
2251
+url="http://www.devshed.com/c/a/JavaScript/Using-Timers-in-JavaScript/">timeouts</ulink> should
2252
+be verified to actually be ineffective after Tor has been toggled.</listitem>
2253
+     <listitem>Other ways to cause Javascript to be executed after
2254
+<command>javascript.enabled</command> has been toggled off.</listitem>
2255
+     <listitem>Odd ways to attempt to load plugins. Kyle Williams has had
2256
+<ulink url="http://www.janusvm.com/goldy/pdf/">some
2257
+success</ulink> with direct loads/meta-refreshes of plugin-handled URLs.</listitem>
2258
+     <listitem>The Date and Timezone hooks should be verified to work with
2259
+crazy combinations of iframes, nested iframes, iframes in frames, frames in
2260
+iframes, and popups being loaded and
2261
+reloaded in rapid succession, and/or from one another. Think race conditions and deep, 
2262
+parallel nesting, involving iframes from both <ulink
2263
+url="http://en.wikipedia.org/wiki/Same_origin_policy">same-origin and
2264
+non-same-origin</ulink> domains.</listitem>
2265
+     <listitem>In addition, there may be alternate ways and other
2266
+methods to query the timezone, or otherwise use some of the Date object's
2267
+methods in combination to deduce the timezone offset. Of course, the author
2268
+tried his best to cover all the methods he could foresee, but it's always good
2269
+to have another set of eyes try it out.</listitem>
2270
+     <listitem>Similarly, is there any way to confuse the <link
2271
+linkend="contentpolicy">content policy</link>
2272
+mentioned above to cause it to allow certain types of page fetches? For
2273
+example, it was recently discovered that favicons are not fetched by the
2274
+content, but the chrome itself, hence the content policy did not look up the
2275
+correct window to determine the current Tor tag for the favicon fetch. Are
2276
+there other things that can do this? Popups? Bookmarklets? Active bookmarks? </listitem>
2277
+     <listitem>Alternate ways to store and fetch unique identifiers. For example, <ulink
2278
+url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink>
2279
+caught us off guard. 
2280
+It was
2281
+also discovered by <ulink url="http://pseudo-flaw.net">Gregory
2282
+Fleischer</ulink> that <ulink
2283
+url="http://pseudo-flaw.net/content/tor/torbutton/">content window access to
2284
+chrome</ulink> can be used to build <link linkend="fingerprinting">unique
2285
+identifiers</link>. 
2286
+Are there any other
2287
+arcane or experimental ways that Firefox provides to create and store unique
2288
+identifiers? Or perhaps unique identifiers can be queried or derived from
2289
+properties of the machine/browser that Javascript has access to? How unique
2290
+can these identifiers be?
2291
+     </listitem>
2292
+     <listitem>Is it possible to get the browser to write some history to disk
2293
+(aside from swap) that can be retrieved later? By default, Torbutton should
2294
+write no history, cookie, or other browsing activity information to the
2295
+harddisk.</listitem>
2296
+     <listitem>Do popup windows make it easier to break any of the above
2297
+behavior? Are javascript events still canceled in popups? What about recursive
2298
+popups from Javascript, data, and other funky URL types? What about CSS
2299
+popups? Are they still blocked after Tor is toggled?</listitem>
2300
+     <listitem>Chrome-escalation attacks. The interaction between the
2301
+Torbutton chrome Javascript and the client content window javascript is pretty
2302
+well-defined and carefully constructed, but perhaps there is a way to smuggle
2303
+javascript back in a return value, or otherwise inject network-loaded
2304
+javascript into the chrome (and thus gain complete control of the browser).
2305
+</listitem>
2306
+</itemizedlist>
2307
+
2308
+    </para>
2309
+   </sect3>
2310
+  </sect2>
2311
+</sect1>
2312
+</article>
... ...
@@ -0,0 +1,1281 @@
1
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Torbutton Design Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>Torbutton Design Documentation</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Perry</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">July 4 2008</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2970568">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2980698">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id3000781">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2988472">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2981568">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#browseroverlay">3.1. Browser Overlay - torbutton.xul</a></span></dt><dt><span class="sect2"><a href="#id2984229">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2988730">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2986171">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2990959">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2984082">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id3001325">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2984248">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2980079">5.1. Test Settings</a></span></dt><dt><span class="sect2"><a href="#plugins">5.2. Disable plugins on Tor Usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2978605">5.3. Isolate Dynamic Content to Tor State (crucial)</a></span></dt><dt><span class="sect2"><a href="#jshooks">5.4. Hook Dangerous Javascript (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2992126">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id3004184">5.6. Disable Updates During Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2997514">5.7. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id3000110">5.8. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2998307">5.9. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2996566">5.10. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2998342">5.11. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2957709">5.12. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2962370">5.13. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2962437">5.14. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2962492">5.15. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2962549">5.16. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2962603">5.17. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2962662">5.18. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2962702">5.19. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2962718">5.20. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2962826">5.21. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id3005721">5.22. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id3005775">5.23. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id3005850">5.24. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id3005910">5.25. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id3005958">5.26. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id3006023">5.27. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id3006210">5.28. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id3006297">5.29. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id3006338">5.30. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#FirefoxSecurity">6.1. Bugs impacting security</a></span></dt><dt><span class="sect2"><a href="#FirefoxWishlist">6.2. Bugs blocking functionality</a></span></dt><dt><span class="sect2"><a href="#FirefoxMiscBugs">6.3. Low Priority Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Categories">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id3007257">7.2. Multi-state testing</a></span></dt><dt><span class="sect2"><a href="#id3007328">7.3. Active testing (aka How to Hack Torbutton)</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2970568"></a>1. Introduction</h2></div></div></div><p>
3
+
4
+This document describes the goals, operation, and testing procedures of the
5
+Torbutton Firefox extension. It is current as of Torbutton 1.2.0rc5.
6
+
7
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="adversary"></a>1.1. Adversary Model</h3></div></div></div><p>
8
+
9
+A Tor web browser adversary has a number of goals, capabilities, and attack
10
+types that can be used to guide us towards a set of requirements for the
11
+Torbutton extension. Let's start with the goals.
12
+
13
+   </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2997298"></a>Adversary Goals</h4></div></div></div><div class="orderedlist"><ol type="1"><li><span class="command"><strong>Bypassing proxy settings</strong></span><p>The adversary's primary goal is direct compromise and bypass of 
14
+Tor, causing the user to directly connect to an IP of the adversary's
15
+choosing.</p></li><li><span class="command"><strong>Correlation of Tor vs Non-Tor Activity</strong></span><p>If direct proxy bypass is not possible, the adversary will likely
16
+happily settle for the ability to correlate something a user did via Tor with
17
+their non-Tor activity. This can be done with cookies, cache identifiers,
18
+javascript events, and even CSS. Sometimes the fact that a user uses Tor may
19
+be enough for some authorities.</p></li><li><span class="command"><strong>History disclosure</strong></span><p>
20
+The adversary may also be interested in history disclosure: the ability to
21
+query a user's history to see if they have issued certain censored search
22
+queries, or visited censored sites.
23
+     </p></li><li><span class="command"><strong>Location information</strong></span><p>
24
+
25
+Location information such as timezone and locality can be useful for the
26
+adversary to determine if a user is in fact originating from one of the
27
+regions they are attempting to control, or to zero-in on the geographical
28
+location of a particular dissident or whistleblower.
29
+
30
+     </p></li><li><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
31
+
32
+Anonymity set reduction is also useful in attempting to zero in on a
33
+particular individual. If the dissident or whistleblower is using a rare build
34
+of Firefox for an obscure operating system, this can be very useful
35
+information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>.
36
+
37
+     </p></li><li><span class="command"><strong>History records and other on-disk
38
+information</strong></span><p>
39
+In some cases, the adversary may opt for a heavy-handed approach, such as
40
+seizing the computers of all Tor users in an area (especially after narrowing
41
+the field by the above two pieces of information). History records and cache
42
+data are the primary goals here.
43
+     </p></li></ol></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2970954"></a>Adversary Capabilities - Positioning</h4></div></div></div><p>
44
+The adversary can position themselves at a number of different locations in
45
+order to execute their attacks.
46
+    </p><div class="orderedlist"><ol type="1"><li><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
47
+The adversary can run exit nodes, or alternatively, they may control routers
48
+upstream of exit nodes. Both of these scenarios have been observed in the
49
+wild.
50
+     </p></li><li><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>
51
+The adversary can also run websites, or more likely, they can contract out
52
+ad space from a number of different adservers and inject content that way. For
53
+some users, the adversary may be the adservers themselves. It is not
54
+inconceivable that adservers may try to subvert or reduce a user's anonymity 
55
+through Tor for marketing purposes.
56
+     </p></li><li><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p>
57
+The adversary can also inject malicious content at the user's upstream router
58
+when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
59
+activity.
60
+     </p></li><li><span class="command"><strong>Physical Access</strong></span><p>
61
+Some users face adversaries with intermittent or constant physical access.
62
+Users in Internet cafes, for example, face such a threat. In addition, in
63
+countries where simply using tools like Tor is illegal, users may face
64
+confiscation of their computer equipment for excessive Tor usage or just
65
+general suspicion.
66
+     </p></li></ol></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2972854"></a>Adversary Capabilities - Attacks</h4></div></div></div><p>
67
+The adversary can perform the following attacks from a number of different 
68
+positions to accomplish various aspects of their goals.
69
+    </p><div class="orderedlist"><ol type="1"><li><span class="command"><strong>Inserting Javascript</strong></span><p>
70
+Javascript allows the adversary the opportunity to accomplish a number of
71
+their goals. If not properly disabled, Javascript event handlers and timers
72
+can cause the browser to perform network activity after Tor has been disabled,
73
+thus allowing the adversary to correlate Tor and Non-Tor activity. Javascript
74
+also allows the adversary to execute <a class="ulink" href="http://gemal.dk/browserspy/css.html" target="_top">history disclosure attacks</a>:
75
+to query the history via the different attributes of 'visited' links. Finally,
76
+Javascript can be used to query the user's timezone via the
77
+<code class="function">Date()</code> object, and to reduce the anonymity set by querying
78
+the <code class="function">navigator</code> object for operating system, CPU, and user
79
+agent information.
80
+     </p></li><li><span class="command"><strong>Inserting Plugins</strong></span><p>
81
+
82
+Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
83
+capable of performing network activity that the author has
84
+investigated is also capable of performing network activity independent of
85
+browser proxy settings - and often independent of its own proxy settings.
86
+In addition, plugins can be used to store unique identifiers that are more
87
+difficult to clear than standard cookies. 
88
+<a class="ulink" href="http://epic.org/privacy/cookies/flash.html" target="_top">Flash-based
89
+cookies</a> fall into this category, but there are likely numerous other
90
+examples.
91
+
92
+     </p></li><li><span class="command"><strong>Inserting CSS</strong></span><p>
93
+
94
+CSS can also be used to correlate Tor and Non-Tor activity, via the usage of
95
+<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">CSS
96
+popups</a> - essentially CSS-based event handlers that fetch content via
97
+CSS's onmouseover attribute. If these popups are allowed to perform network
98
+activity in a different Tor state than they were loaded in, they can easily
99
+correlate Tor and Non-Tor activity and reveal a user's IP address. In
100
+addition, CSS can also be used without Javascript to perform <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only history disclosure
101
+attacks</a>.
102
+     </p></li><li><span class="command"><strong>Read and insert cookies</strong></span><p>
103
+
104
+An adversary in a position to perform MITM content alteration can inject
105
+document content elements to both read and inject cookies for
106
+arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
107
+sort of <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html" target="_top">active
108
+sidejacking</a>.
109
+
110
+     </p></li><li><span class="command"><strong>Create arbitrary cached content</strong></span><p>
111
+
112
+Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
113
+identifiers</a>. Since by default the cache has no same-origin policy,
114
+these identifiers can be read by any domain, making them an ideal target for
115
+adserver-class adversaries.
116
+
117
+     </p></li><li><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser
118
+attributes</strong></span><p>
119
+
120
+There is an absurd amount of information available to websites via attributes
121
+of the browser. This information can be used to reduce anonymity set, or even
122
+<a class="ulink" href="http://0x000000.com/index.php?i=520&amp;bin=1000001000" target="_top">uniquely
123
+fingerprint individual users</a>. </p><p>
124
+For illustration, let's perform a
125
+back-of-the-envelope calculation on the number of anonymity sets for just the
126
+resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and
127
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
128
+objects. Browser window resolution information provides something like
129
+(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
130
+information contributes about another factor of 5 (for about 5 resolutions in
131
+typical use). In addition, the dimensions and position of the desktop taskbar
132
+are available, which can reveal hints on OS information. This boosts the count
133
+by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
134
+and Gnome, and None). Subtracting the browser content window
135
+size from the browser outer window size provide yet more information.
136
+Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
137
+2<sup>3</sup>=8). Interface effects such as titlebar fontsize
138
+and window manager settings gives a factor of about 9 (say 3 common font sizes
139
+for the titlebar and 3 common sizes for browser GUI element fonts).
140
+Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
141
+2<sup>29</sup>, or a 29 bit identifier based on resolution
142
+information alone. </p><p>
143
+
144
+Of course, this space is non-uniform and prone to incremental changes.
145
+However, if a bit vector space consisting of the above extracted attributes
146
+were used instead of the hash approach from <a class="ulink" href="http://0x000000.com/index.php?i=520&amp;bin=1000001000" target="_top">The Hacker
147
+Webzine article above</a>, minor changes in browser window resolution will
148
+no longer generate totally new identifiers. 
149
+
150
+</p><p>
151
+
152
+To add insult to injury, <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">chrome URL disclosure
153
+attacks</a> mean that each and every extension on <a class="ulink" href="https://addons.mozilla.org" target="_top">addons.mozilla.org</a> adds another bit
154
+to that 2<sup>29</sup>. With hundreds of popular extensions
155
+and thousands of extensions total, it is easy to see that this sort of
156
+information is an impressively powerful identifier if used properly by a
157
+competent and determined adversary such as an ad network.  Again, a
158
+nearest-neighbor bit vector space approach here would also gracefully handle
159
+incremental changes to installed extensions.
160
+
161
+</p></li><li><span class="command"><strong>Remotely or locally exploit browser and/or
162
+OS</strong></span><p>
163
+Last, but definitely not least, the adversary can exploit either general 
164
+browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
165
+install malware and surveillance software. An adversary with physical access
166
+can perform similar actions. Regrettably, this last attack capability is
167
+outside of Torbutton's ability to defend against, but it is worth mentioning
168
+for completeness.
169
+     </p></li></ol></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="requirements"></a>1.2. Torbutton Requirements</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
170
+
171
+Since many settings satisfy multiple requirements, this design document is
172
+organized primarily by Torbutton components and settings. However, if you are
173
+the type that would rather read the document from the requirements
174
+perspective, it is in fact possible to search for each of the following
175
+requirement phrases in the text to find the relevant features that help meet
176
+that requirement.
177
+
178
+</div><p>
179
+
180
+From the above Adversary Model, a number of requirements become clear. 
181
+
182
+   </p><div class="orderedlist"><ol type="1"><li><a id="proxy"></a><span class="command"><strong>Proxy Obedience</strong></span><p>The browser
183
+MUST NOT bypass Tor proxy settings for any content.</p></li><li><a id="isolation"></a><span class="command"><strong>Network Isolation</strong></span><p>Pages MUST NOT perform any network activity in a Tor state different
184
+ from the state they were originally loaded in.</p></li><li><a id="state"></a><span class="command"><strong>State Separation</strong></span><p>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
185
+ one Tor state MUST NOT be accessible via the network in
186
+ another Tor state.</p></li><li><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>With
187
+the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
188
+users whose network fingerprint does not obviously betray the fact that they
189
+are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
190
+reveal its presence while Tor is disabled.</p></li><li><a id="disk"></a><span class="command"><strong>Disk Avoidance</strong></span><p>The browser SHOULD NOT write any Tor-related state to disk, or store it
191
+ in memory beyond the duration of one Tor toggle.</p></li><li><a id="location"></a><span class="command"><strong>Location Neutrality</strong></span><p>The browser SHOULD NOT leak location-specific information, such as
192
+ timezone or locale via Tor.</p></li><li><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
193
+Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity set reducing information 
194
+ (such as user agent, extension presence, and resolution information)
195
+automatically via Tor. The assessment of the attacks above should make it clear
196
+that anonymity set reduction is a very powerful method of tracking and
197
+eventually identifying anonymous users.
198
+</p></li><li><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser
199
+SHOULD NOT perform unauthenticated updates or upgrades via Tor.</p></li><li><a id="interoperate"></a><span class="command"><strong>Interoperability</strong></span><p>Torbutton SHOULD interoperate with third-party proxy switchers that
200
+ enable the user to switch between a number of different proxies. It MUST
201
+ provide full Tor protection in the event a third-party proxy switcher has
202
+ enabled the Tor proxy settings.</p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="layout"></a>1.3. Extension Layout</h3></div></div></div><p>Firefox extensions consist of two main categories of code: 'Components' and
203
+'Chrome'. Components are a fancy name for classes that implement a given
204
+interface or interfaces. In Firefox, components <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/creatingcomps.html" target="_top">can be
205
+written</a> in C++,
206
+Javascript, or a mixture of both. Components have two identifiers: their
207
+'<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005" target="_top">Contract
208
+ID</a>' (a human readable path-like string), and their '<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329" target="_top">Class
209
+ID</a>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
210
+'Interface ID'. It is possible to 'hook' system components - to reimplement
211
+their interface members with your own wrappers - but only if the rest of the
212
+browser refers to the component by its Contract ID. If the browser refers to
213
+the component by Class ID, it bypasses your hooks in that use case.
214
+Technically, it may be possible to hook Class IDs by unregistering the
215
+original component, and then re-registering your own, but this relies on
216
+obsolete and deprecated interfaces and has proved to be less than
217
+stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window.
218
+Extensions are allowed to create 'overlays' that are 'bound' to existing XML
219
+window definitions, or they can create their own windows. The DTD for this XML
220
+is called <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XUL</a>.</p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2980698"></a>2. Components</h2></div></div></div><p>
221
+
222
+Torbutton installs components for two purposes: hooking existing components to
223
+reimplement their interfaces; and creating new components that provide
224
+services to other pieces of the extension.
225
+ 
226
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3000781"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some
227
+of its own standalone components as well.  Let's discuss the hooked components
228
+first.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="sessionstore"></a><a class="ulink" href="http://developer.mozilla.org/en/docs/nsISessionStore" target="_top">@mozilla.org/browser/sessionstore;1</a> -
229
+<a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore2.js" target="_top">components/nsSessionStore2.js</a>
230
+and <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.js" target="_top">components/nsSessionStore3.js</a></h4></div></div></div><p>These components address the <a class="link" href="#disk">Disk Avoidance</a>
231
+requirements of Torbutton. As stated in the requirements, Torbutton needs to
232
+prevent Tor tabs from being written to disk by the Firefox session store for a
233
+number of reasons, primary among them is the fact that Firefox can crash at
234
+any time, and a restart can cause you to fetch tabs in the incorrect Tor
235
+state.</p><p>These components illustrate a complication with Firefox hooking: you can
236
+only hook member functions of a class if they are published in an
237
+interface that the class implements. Unfortunately, the sessionstore has no
238
+published interface that is amenable to disabling the writing out of Tor tabs
239
+in specific. As such, Torbutton had to include the <span class="emphasis"><em>entire</em></span>
240
+nsSessionStore from both Firefox 2 and Firefox 3, 
241
+with a couple of modifications to prevent tabs that were loaded with Tor
242
+enabled from being written to disk, and some version detection code to
243
+determine which component to load. The <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.diff" target="_top">diff against the original session
244
+store</a> is included in the SVN repository.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2985696"></a><a class="ulink" href="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js" target="_top">@mozilla.org/browser/sessionstartup;1</a> -
245
+    <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js" target="_top">components/crash-observer.js</a></h4></div></div></div><p>This component wraps the Firefox Session Startup component that is in
246
+charge of <a class="ulink" href="http://developer.mozilla.org/en/docs/Session_store_API" target="_top">restoring saved
247
+sessions</a>. The wrapper's only job is to intercept the
248
+<code class="function">doRestore()</code> function, which is called by Firefox if it is determined that the
249
+browser crashed and the session needs to be restored. The wrapper notifies the
250
+Torbutton chrome that the browser crashed by setting the pref
251
+<span class="command"><strong>extensions.torbutton.crashed</strong></span>, or that it is a normal
252
+startup via the pref <span class="command"><strong>extensions.torbutton.noncrashed</strong></span>. The Torbutton Chrome <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver" target="_top">listens for a
253
+preference change</a> for this value and then does the appropriate cleanup. This
254
+includes setting the Tor state to the one the user selected for crash recovery
255
+in the preferences window (<span class="command"><strong>extensions.torbutton.restore_tor</strong></span>), and
256
+restoring cookies for the corresponding cookie jar, if it exists.</p><p>By performing this notification, this component assists in the 
257
+<a class="link" href="#proxy">Proxy Obedience</a>, and <a class="link" href="#isolation">Network Isolation</a> requirements.
258
+</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2979678"></a><a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html" target="_top">@mozilla.org/browser/global-history;2</a>
259
+- <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js" target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin Jackson</a> as a method for defeating
260
+CSS and Javascript-based methods of history disclosure. The global-history
261
+component is what is used by Firefox to determine if a link was visited or not
262
+(to apply the appropriate style to the link). By hooking the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_isVisited" target="_top">isVisited</a>
263
+and <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_addURI" target="_top">addURI</a>
264
+methods, Torbutton is able to selectively prevent history items from being
265
+added or being displayed as visited, depending on the Tor state and the user's
266
+preferences.
267
+</p><p>
268
+This component helps satisfy the <a class="link" href="#state">State Separation</a>
269
+and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton.
270
+</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2988472"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the
271
+extension. These components do not hook any interfaces, nor are they used
272
+anywhere besides Torbutton itself.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2981164"></a><a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js" target="_top">@stanford.edu/cookie-jar-selector;2
273
+- components/cookie-jar-selector.js</a></h4></div></div></div><p>The cookie jar selector (also based on code from <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin
274
+Jackson</a>) is used by the Torbutton chrome to switch between
275
+Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
276
+move the current cookies.txt file to the appropriate backup location
277
+(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
278
+into place.</p><p>
279
+This component helps to address the <a class="link" href="#state">State
280
+Isolation</a> requirement of Torbutton.
281
+</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2995031"></a><a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1
282
+- components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
283
+logging messages to either Firefox stderr
284
+(<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
285
+(<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if
286
+available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
287
+change the loglevel on the fly by changing
288
+<span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
289
+</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1
290
+- components/window-mapper.js</a></h4></div></div></div><p>Torbutton tags Firefox <a class="ulink" href="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html" target="_top">tabs</a> with a special variable that indicates the Tor
291
+state the tab was most recently used under to fetch a page. The problem is
292
+that for many Firefox events, it is not possible to determine the tab that is
293
+actually receiving the event. The Torbutton window mapper allows the Torbutton
294
+chrome and other components to look up a <a class="ulink" href="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html" target="_top">browser
295
+tab</a> for a given <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDOMWindow.html" target="_top">HTML content
296
+window</a>. It does this by traversing all windows and all browsers, until it
297
+finds the browser with the requested <a class="ulink" href="http://www.xulplanet.com/references/elemref/ref_browser.html#prop_contentWindow" target="_top">contentWindow</a> element. Since the content policy
298
+and page loading in general can generate hundreds of these lookups, this
299
+result is cached inside the component.
300
+</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
301
+- components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is
302
+toggled, Javascript is disabled, and pages are instructed to stop loading.
303
+However, CSS is still able to perform network operations by loading styles for
304
+onmouseover events and other operations. In addition, favicons can still be
305
+loaded by the browser. The cssblocker component prevents this by implementing
306
+and registering an <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html" target="_top">nsIContentPolicy</a>.
307
+When an nsIContentPolicy is registered, Firefox checks every attempted network
308
+request against its <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html#method_shouldLoad" target="_top">shouldLoad</a>
309
+member function to determine if the load should proceed. In Torbutton's case,
310
+the content policy looks up the appropriate browser tab using the <a class="link" href="#windowmapper" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js">window mapper</a>,
311
+and checks that tab's load tag against the current Tor state. If the tab was
312
+loaded in a different state than the current state, the fetch is denied.
313
+Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#isolation">Network
314
+Isolation</a> requirements of Torbutton.
315
+
316
+<p>In addition, the content policy also blocks website javascript from
317
+<a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">querying for
318
+versions and existence of extension chrome</a> while Tor is enabled, and
319
+also masks the presence of Torbutton to website javascript while Tor is
320
+disabled. </p><p>
321
+
322
+Finally, some of the work that logically belongs to the content policy is
323
+instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
324
+<span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of
325
+Firefox 3 favicon loads, popups, and full page plugins, which for whatever
326
+reason are not passed to the Firefox content policy itself (see Firefox Bugs 
327
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 
328
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
329
+
330
+</p><p>
331
+
332
+This helps to fulfill both the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirements of
333
+Torbutton.</p></div></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2981568"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
334
+located. Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XML file</a>, with zero or more Javascript
335
+files attached. The scope of these Javascript files is their containing
336
+window.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="browseroverlay"></a>3.1. Browser Overlay - <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h3></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
337
+bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
338
+It contains event handlers for preference update, shutdown, upgrade, and
339
+location change events.</p><p>The <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_docloaderservice1.html" target="_top">location
340
+change</a> <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html" target="_top">webprogress
341
+listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is perhaps the
342
+most important part of the chrome from a security standpoint. It is a <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html" target="_top">web
343
+progress listener</a> that handles
344
+receiving an event every time a page load or iframe load occurs. This class
345
+eventually calls down to <code class="function">torbutton_update_tags()</code> and 
346
+<code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load state tags, plugin
347
+permissions, and install the Javascript hooks to hook the <a class="ulink" href="http://phrogz.net/objJob/object.asp?id=224" target="_top">Date</a> object and
348
+the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.navigator" target="_top">navigator</a> object (for timezone and platform information,
349
+respectively).</p><p>
350
+The browser overlay helps to satisfy a number of Torbutton requirements. These
351
+are better enumerated in each of the Torbutton preferences below. However,
352
+there are also a number of Firefox preferences set in
353
+<code class="function">torbutton_update_status()</code> that aren't governed by any
354
+Torbutton setting. These are:
355
+</p><div class="orderedlist"><ol type="1"><li><a class="ulink" href="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds" target="_top">browser.bookmarks.livemark_refresh_seconds</a><p>
356
+This pref is set in an attempt to disable the fetching of LiveBookmarks via
357
+Tor. Since users can potentially collect a large amount of live bookmarks to
358
+very personal sites (blogs of friends, wikipedia articles they maintain,
359
+comment feeds of their own blog), it is not possible to cleanly isolate these
360
+fetches and they are simply disabled during Tor usage.
361
+This helps to address the <a class="link" href="#state">State Separation</a> requirement.
362
+Unfortunately <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=436250" target="_top">Firefox Bug
363
+436250</a> prevents this from
364
+functioning completely correctly.
365
+</p></li><li><a class="ulink" href="http://kb.mozillazine.org/Network.security.ports.banned" target="_top">network.security.ports.banned</a><p>
366
+Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
367
+reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) to the list
368
+of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
369
+and the Tor control port, respectively. This is set for both Tor and Non-Tor
370
+usage, and prevents websites from attempting to do http fetches from these
371
+ports to see if they are open, which addresses the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
372
+ </p></li><li><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings" target="_top">browser.send_pings</a><p>
373
+This setting is currently always disabled. If anyone ever complains saying
374
+that they *want* their browser to be able to send ping notifications to a
375
+page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
376
+my breath. I haven't checked if the content policy is called for pings, but if
377
+not, this setting helps with meeting the <a class="link" href="#isolation">Network
378
+Isolation</a> requirement.
379
+ </p></li><li><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups" target="_top">browser.safebrowsing.remoteLookups</a><p>
380
+Likewise for this setting. I find it hard to imagine anyone who wants to ask
381
+Google in real time if each URL they visit is safe, especially when the list
382
+of unsafe URLs is downloaded anyway. This helps fulfill the <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire
383
+browsing history from ending up on Google's disks.
384
+ </p></li><li><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled" target="_top">browser.safebrowsing.enabled</a><p>
385
+Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387" target="_top">unauthenticated
386
+updates under Firefox 2</a>, so it is disabled during Tor usage. 
387
+This helps fulfill the <a class="link" href="#updates">Update
388
+Safety</a> requirement. Firefox 3 has the fix for that bug, and so
389
+safebrowsing updates are enabled during Tor usage.
390
+ </p></li><li><a class="ulink" href="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29" target="_top">network.protocol-handler.warn-external.(protocol)</a><p>
391
+If Tor is enabled, we need to prevent random external applications from
392
+launching without at least warning the user. This group of settings only
393
+partially accomplishes this, however. Applications can still be launched via
394
+plugins. The mechanisms for handling this are described under the "Disable
395
+Plugins During Tor Usage" preference. This helps fulfill the <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external
396
+applications from accessing network resources at the command of Tor-fetched
397
+pages.
398
+ </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2984229"></a>3.2. Preferences Window - <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h3></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
399
+handlers located in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2988730"></a>3.3. Other Windows</h3></div></div></div><p>There are additional windows that describe popups for right clicking on
400
+the status bar, the toolbutton, and the about page.</p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2986171"></a>4. Toggle Code Path</h2></div></div></div><p>
401
+
402
+The act of toggling is connected to <code class="function">torbutton_toggle()</code>
403
+via the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
404
+and <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/popup.xul" target="_top">popup.xul</a>
405
+overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 
406
+
407
+</p><p>
408
+
409
+Toggling is a 3 stage process: Button Click, Proxy Update, and
410
+Settings Update. These stages are reflected in the prefs
411
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
412
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
413
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
414
+three stage preference update is to ensure immediate enforcement of <a class="link" href="#isolation">Network Isolation</a> via the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. Since the content window
415
+javascript runs on a different thread than the chrome javascript, it is
416
+important to properly convey the stages to the content policy to avoid race
417
+conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
418
+409737</a> unfixed. The content policy does not allow any network activity
419
+whatsoever during this three stage transition.
420
+
421
+ </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2990959"></a>4.1. Button Click</h3></div></div></div><p>
422
+
423
+This is the first step in the toggling process. When the user clicks the
424
+toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
425
+called. This function checks the current Tor status by comparing the current
426
+proxy settings to the selected Tor settings, and then sets the proxy settings
427
+to the opposite state, and sets the pref
428
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
429
+It is this proxy pref update that gives notification via the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver" target="_top">pref
430
+observer</a>
431
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
432
+toggle.
433
+
434
+  </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2984082"></a>4.2. Proxy Update</h3></div></div></div><p>
435
+
436
+When Torbutton receives any proxy change notifications via its
437
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
438
+<code class="function">torbutton_set_status()</code> which checks against the Tor
439
+settings to see if the Tor proxy settings match the current settings. If so,
440
+it calls <code class="function">torbutton_update_status()</code>, which determines if
441
+the Tor state has actually changed, and sets
442
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
443
+state value, and ensures that
444
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
445
+value. This is decoupled from the button click functionalty via the pref
446
+observer so that other addons (such as SwitchProxy) can switch the proxy
447
+settings between multiple proxies.
448
+
449
+  </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3001325"></a>4.3. Settings Update</h3></div></div></div><p>
450
+
451
+The next stage is also handled by
452
+<code class="function">torbutton_update_status()</code>. This function sets scores of
453
+Firefox preferences, saving the original values to prefs under
454
+<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the history
455
+clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
456
+end of its work, it sets
457
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
458
+completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
459
+
460
+  </p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2984248"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each
461
+option is presented as the string from the preferences window, a summary, the
462
+preferences it touches, and the effect this has on the components, chrome, and
463
+browser properties.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2980079"></a>5.1. Test Settings</h3></div></div></div><p>
464
+This button under the Proxy Settings tab provides a way to verify that the 
465
+proxy settings are correct, and actually do route through the Tor network. It
466
+performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a>
467
+for <a class="ulink" href="https://check.torproject.org/?TorButton=True" target="_top">https://check.torproject.org/?Torbutton=True</a>.
468
+This is a special page that returns very simple, yet well-formed XHTML that
469
+Torbutton can easily inspect for a hidden link with an id of
470
+<span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
471
+or <span class="command"><strong>failure</strong></span> to indicate if the
472
+user hit the page from a Tor IP, a non-Tor IP. This check is handled in
473
+<code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>.
474
+Presenting the results to the user is handled by the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul" target="_top">preferences
475
+window</a>
476
+callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js" target="_top">preferences.js</a>.  
477
+
478
+  </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="plugins"></a>5.2. Disable plugins on Tor Usage (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Enabling this preference causes the above mentioned Torbutton chrome web progress
479
+ listener <span class="command"><strong>torbutton_weblistener</strong></span> to disable Java via <span class="command"><strong>security.enable_java</strong></span> and to disable
480
+ plugins via the browser <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html" target="_top">docShell</a>
481
+ attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is
482
+ created (<code class="function">torbutton_tag_new_browser()</code>), every time a web
483
+load
484
+event occurs
485
+ (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
486
+ (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
487
+ prevented from loading by the content policy in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is
488
+ enabled and this option is set.
489
+ </p><p>Even all this turns out to be insufficient if the user directly
490
+ clicks on a plugin-handled mime-type. <a class="ulink" href="http://www.janusvm.com/goldy/pdf/" target="_top">In this case</a> (and also <a class="ulink" href="http://www.janusvm.com/goldy/side-channels/frames/" target="_top">this
491
+one</a>), the browser decides that
492
+ maybe it should ignore all these other settings and load the plugin anyways,
493
+ because maybe the user really did want to load it (never mind this same
494
+ load-style could happen automatically  with meta-refresh or any number of
495
+ other ways..). To handle these cases, Torbutton stores a list of plugin-handled
496
+ mime-types, and sets the pref
497
+<span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> to this list.
498
+Additionally, (since nothing can be assumed when relying on Firefox
499
+preferences and internals) if it detects a load of one of them from the web progress
500
+ listener, it cancels the request, tells the associated DOMWindow 
501
+to stop loading, clears the document, AND throws an exception. Anything short 
502
+of all this and
503
+ the plugin managed to find some way to load.
504
+ </p><p>
505
+ All this could be avoided, of course, if Firefox would either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">obey
506
+ allowPlugins</a> for directly visited URLs, or notify its content policy for such
507
+ loads either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">via</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">shouldProcess</a> or shouldLoad. The fact that it does not is
508
+ not very encouraging. 
509
+ </p><p>
510
+
511
+Since most plugins completely ignore browser proxy settings, the actions
512
+performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
513
+
514
+ </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2978605"></a>5.3. Isolate Dynamic Content to Tor State (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> content policy
515
+mentioned above, and causes it to block content load attempts in pages an
516
+opposite Tor state from the current state. Freshly loaded <a class="ulink" href="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html" target="_top">browser
517
+tabs</a> are tagged 
518
+with a <span class="command"><strong>__tb_load_state</strong></span> member in
519
+<code class="function">torbutton_update_tags()</code> and this
520
+value is compared against the current tor state in the content policy.</p><p>It also kills all Javascript in each page loaded under that state by
521
+toggling the <span class="command"><strong>allowJavascript</strong></span> <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html" target="_top">docShell</a> property, and issues a
522
+<a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebNavigation.html#method_stop" target="_top">webNavigation.stop(webNavigation.STOP_ALL)</a> to each browser tab (the
523
+equivalent of hitting the STOP button).</p><p>
524
+
525
+Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox bug
526
+409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing
527
+all event handlers, and event handlers registered with <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:element.addEventListener" target="_top">addEventListener()</a>
528
+are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content
529
+Policy</a> should prevent such code from performing network activity within
530
+the current tab, but activity that happens via a popup window or via a
531
+Javascript redirect can still slip by. For this reason, Torbutton blocks
532
+popups by checking for a valid <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener" target="_top">window.opener</a>
533
+attribute in <code class="function">torbutton_check_progress()</code>. If the window
534
+has an opener from a different Tor state, its load is blocked. The content
535
+policy also takes similar action to prevent Javascript redirects. This also
536
+has the side effect/feature of preventing the user from following any links
537
+from a page loaded in an opposite Tor state.
538
+
539
+</p><p>
540
+This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
541
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="jshooks"></a>5.4. Hook Dangerous Javascript (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/jshooks.js" target="_top">Javascript
542
+hooking code</a>. Javascript is injected into
543
+pages to hook the <a class="ulink" href="http://phrogz.net/objJob/object.asp?id=224" target="_top">Date
544
+class</a> to mask your timezone. This is done in the chrome in
545
+<code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
546
+<a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html" target="_top">webprogress
547
+listener</a> <span class="command"><strong>torbutton_weblistener</strong></span> and the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> (the latter being a hack to handle
548
+javascript: urls). This behavior helps to satisfy the <a class="link" href="#location">Location Neutrality</a> requirement.
549
+
550
+</p><p>
551
+
552
+In addition, this setting also hooks various resolution properties of the
553
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a>,
554
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>,
555
+and <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.navigator" target="_top">window.navigator</a>
556
+to mask window size information and user agent properties not handled by the
557
+standard Firefox user agent override settings. The resolution hooks
558
+effectively make the Firefox browser window appear to websites as if the renderable area
559
+takes up the entire desktop, has no toolbar or other GUI element space, and
560
+the desktop itself has no toolbars.
561
+These hooks drastically reduce the amount of information available to do <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to
562
+meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
563
+requirements.
564
+
565
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2992126"></a>5.5. Resize windows to multiples of 50px during Tor usage (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
566
+
567
+This option drastically cuts down on the number of distinct anonymity sets
568
+that divide the Tor web userbase. Without this setting, the dimensions for a
569
+typical browser window range from 600-1200 horizontal pixels and 400-1000
570
+vertical pixels, or about 600x600 = 360000 different sets. Resizing the
571
+browser window to multiples of 50 on each side reduces the number of sets by
572
+50^2, bringing the total number of sets to 144. Of course, the distribution
573
+among these sets are not uniform, but scaling by 50 will improve the situation
574
+due to this non-uniformity for users in the less common resolutions.
575
+Obviously the ideal situation would be to lie entirely about the browser
576
+window size, but this will likely cause all sorts of rendering issues, and is
577
+also not implementable in a foolproof way from extension land.
578
+
579
+</p><p>
580
+
581
+The implementation of this setting is spread across a couple of different
582
+locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">browser
583
+overlay</a>. Since resizing minimized windows causes them to be restored,
584
+and since maximized windows remember their previous size to the pixel, windows
585
+must be resized before every document load (at the time of browser tagging)
586
+via <code class="function">torbutton_check_round()</code>, called by
587
+<code class="function">torbutton_update_tags()</code>. To prevent drift, the extension
588
+tracks the original values of the windows and uses this to perform the
589
+rounding on document load. In addition, to prevent the user from resizing a
590
+window to a non-50px multiple, a resize listener
591
+(<code class="function">torbutton_do_resize()</code>) is installed on every new browser
592
+window to record the new size and round it to a 50px multiple while Tor is
593
+enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
594
+are set. This ensures that there is no discrepancy between the 50 pixel cutoff
595
+and the actual renderable area of the browser (so that it is not possible to
596
+infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
597
+
598
+</p><p>
599
+This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
600
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3004184"></a>5.6. Disable Updates During Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox
601
+update settings</a> during Tor
602
+  usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
603
+<span class="command"><strong>app.update.enabled</strong></span>,
604
+  <span class="command"><strong>app.update.auto</strong></span>, and
605
+<span class="command"><strong>browser.search.update</strong></span>.  These prevent the
606
+  browser from updating extensions, checking for Firefox upgrades, and
607
+  checking for search plugin updates while Tor is enabled.
608
+  </p><p>
609
+This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
610
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2997514"></a>5.7. Disable Search Suggestions during Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
611
+This setting causes Torbutton to disable <a class="ulink" href="http://kb.mozillazine.org/Browser.search.suggest.enabled" target="_top"><span class="command"><strong>browser.search.suggest.enabled</strong></span></a>
612
+during Tor usage.
613
+This governs if you get Google search suggestions during Tor
614
+usage. Your Google cookie is transmitted with google search suggestions, hence
615
+this is recommended to be disabled.
616
+
617
+</p><p>
618
+While this setting doesn't satisfy any Torbutton requirements, the fact that
619
+cookies are transmitted for partially typed queries does not seem desirable
620
+for Tor usage.
621
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3000110"></a>5.8. Block Tor/Non-Tor access to network from file:// urls (recommended)</h3></div></div></div><p>Option:
622
+   </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.block_tor_file_net</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nontor_file_net</strong></span></td></tr></table><p>
623
+  </p><p>
624
+
625
+These settings prevent file urls from performing network operations during the
626
+respective Tor states. Firefox 2's implementation of same origin policy allows
627
+file urls to read and <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/" target="_top">submit
628
+arbitrary files from the local filesystem</a> to arbitrary websites. To
629
+make matters worse, the 'Content-Disposition' header can be injected
630
+arbitrarily by exit nodes to trick users into running arbitrary html files in
631
+the local context. These preferences cause the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> to block access to any network
632
+resources from File urls during the appropriate Tor state.
633
+
634
+</p><p>
635
+
636
+This preference helps to ensure Tor's <a class="link" href="#isolation">Network
637
+Isolation</a> requirement, by preventing file urls from executing network
638
+operations in opposite Tor states. Also, allowing pages to submit arbitrary
639
+files to arbitrary sites just generally seems like a bad idea.
640
+ 
641
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2998307"></a>5.9. Close all Tor/Non-Tor tabs and windows on toggle (optional)</h3></div></div></div><p>Options: 
642
+   </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.close_nontor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.close_tor</strong></span></td></tr></table><p>
643
+  </p><p>
644
+
645
+These settings cause Torbutton to enumerate through all windows and close all
646
+tabs in each window for the appropriate Tor state. This code can be found in
647
+<code class="function">torbutton_update_status()</code>.  The main reason these settings
648
+exist is as a backup mechanism in the event of any Javascript or content policy
649
+leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
650
+409737</a>.  Torbutton currently tries to block all Javascript network
651
+activity via the content policy, but until that bug is fixed, there is some
652
+risk that there are alternate ways to bypass the policy. This option is
653
+available as an extra assurance of <a class="link" href="#isolation">Network
654
+Isolation</a> for those who would like to be sure that when Tor is toggled
655
+all page activity has ceased. It also serves as a potential future workaround
656
+in the event a content policy failure is discovered, and provides an additional
657
+level of protection for the <a class="link" href="#disk">Disk Avoidance</a>
658
+protection so that browser state is not sitting around waiting to be swapped
659
+out longer than necessary.
660
+
661
+</p><p>
662
+While this setting doesn't satisfy any Torbutton requirements, the fact that
663
+cookies are transmitted for partially typed queries does not seem desirable
664
+for Tor usage.
665
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2996566"></a>5.10. Isolate Access to History navigation to Tor state (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
666
+This setting determines if Torbutton installs an <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistoryListener.html" target="_top">nsISHistoryListener</a>
667
+attached to the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html" target="_top">sessionHistory</a> of 
668
+of each browser's <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_webshell1.html" target="_top">webNavigatator</a>.
669
+The nsIShistoryListener is instantiated with a reference to the containing
670
+browser window and blocks the back, forward, and reload buttons on the browser
671
+navigation bar when Tor is in an opposite state than the one to load the
672
+current tab. In addition, Tor clears the session history during a new document
673
+load if this setting is enabled. 
674
+
675
+  </p><p>
676
+
677
+This is marked as a crucial setting in part
678
+because Javascript access to the history object is indistinguishable from 
679
+user clicks, and because
680
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
681
+409737</a> allows javascript to execute in opposite Tor states, javascript
682
+can issue reloads after Tor toggle to reveal your original IP. Even without
683
+this bug, however, Javascript is still able to access previous pages in your
684
+session history that may have been loaded under a different Tor state, to
685
+attempt to correlate your activity.
686
+
687
+   </p><p>
688
+
689
+This setting helps to fulfill Torbutton's <a class="link" href="#state">State
690
+Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
691
+requirements.
692
+
693
+   </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2998342"></a>5.11. History Access Settings</h3></div></div></div><p>Options:
694
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.block_thread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_thwrite</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthwrite</strong></span></td></tr></table><p>
695
+  </p><p>These four settings govern the behavior of the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js" target="_top">components/ignore-history.js</a>
696
+history blocker component mentioned above. By hooking the browser's view of
697
+the history itself via the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html" target="_top">mozilla.org/browser/global-history;2</a>
698
+component, this mechanism defeats all document-based <a class="ulink" href="http://gemal.dk/browserspy/css.html" target="_top">history disclosure
699
+attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only attacks</a>.
700
+</p><p>
701
+
702
+On Firefox 3, the history write settings also govern if Torbutton sets
703
+<span class="command"><strong>browser.history_expire_days</strong></span> to 0 on the appropriate Tor
704
+state, which <a class="ulink" href="http://developer.mozilla.org/en/docs/index.php?title=nsINavHistoryService#Attributes" target="_top">should
705
+disable</a> all <a class="ulink" href="http://developer.mozilla.org/en/docs/Places" target="_top">Places</a> database
706
+writes.
707
+
708
+</p><p>
709
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
710
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2957709"></a>5.12. Clear History During Tor Toggle (optional)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls
711
+<a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIBrowserHistory.html#method_removeAllPages" target="_top">nsIBrowserHistory.removeAllPages</a>
712
+and <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html#method_PurgeHistory" target="_top">nsISHistory.PurgeHistory</a>
713
+for each tab on Tor toggle.</p><p>
714
+This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.
715
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962370"></a>5.13. Block Password+Form saving during Tor/Non-Tor</h3></div></div></div><p>Options:
716
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.block_tforms</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_ntforms</strong></span></td></tr></table><p>
717
+  </p><p>These settings govern if Torbutton disables
718
+<span class="command"><strong>browser.formfill.enable</strong></span>
719
+and <span class="command"><strong>signon.rememberSignons</strong></span> during Tor and Non-Tor usage.
720
+Since form fields can be read at any time by Javascript, this setting is a lot
721
+more important than it seems.
722
+</p><p>
723
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
724
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962437"></a>5.14. Block Tor disk cache and clear all cache on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
725
+  </p><p>This option causes Torbutton to call <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsICacheService.html#method_evictEntries" target="_top">nsICacheService.evictEntries(0)</a>
726
+on Tor toggle to remove all entries from the cache. In addition, this setting
727
+causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> to false.
728
+</p><p>
729
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
730
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962492"></a>5.15. Block disk and memory cache during Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting
731
+causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>,
732
+<a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and
733
+<a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage.
734
+</p><p>
735
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
736
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962549"></a>5.16. Clear Cookies on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
737
+  </p><p>
738
+
739
+This setting causes Torbutton to call <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsICookieManager.html#method_removeAll" target="_top">nsICookieManager.removeAll()</a> on
740
+every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
741
+to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
742
+which prevents them from being written to disk. 
743
+
744
+</p><p>
745
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
746
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962603"></a>5.17. Store Non-Tor cookies in a protected jar</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
747
+  </p><p>
748
+
749
+This setting causes Torbutton to use <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js" target="_top">@stanford.edu/cookie-jar-selector;2</a> to store
750
+non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
751
+before restoring the jar.
752
+</p><p>
753
+This setting also sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
754
+to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
755
+which prevents them from being written to disk. 
756
+
757
+</p><p>
758
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
759
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962662"></a>5.18. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>
760
+  </p><p>
761
+
762
+This setting causes Torbutton to use <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js" target="_top">@stanford.edu/cookie-jar-selector;2</a> to store
763
+both Tor and Non-Tor cookies into protected jars.
764
+</p><p>
765
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
766
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962702"></a>5.19. Manage My Own Cookies (dangerous)</h3></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
767
+cookie prefs all to false.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962718"></a>5.20. Disable DOM Storage during Tor usage (crucial)</h3></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962720"></a>5.20.1. Do not write Tor/Non-Tor cookies to disk</h3></div></div></div><p>Options:
768
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.tor_memory_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.nontor_memory_jar</strong></span></td></tr></table><p>
769
+  </p><p>
770
+These settings (contributed by arno) cause Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
771
+to 2 during the appropriate Tor state, and to store cookies acquired in that
772
+state into a Javascript
773
+<a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X" target="_top">E4X</a>
774
+object as opposed to writing them to disk.
775
+</p><p>
776
+This allows Torbutton to provide an option to preserve a user's 
777
+cookies while still satisfying the <a class="link" href="#disk">Disk Avoidance</a>
778
+requirement.
779
+</p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span>
780
+  </p><p>
781
+
782
+This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor
783
+usage to prevent 
784
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from
785
+  being used to store persistent information across Tor states.</p><p>
786
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
787
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2962826"></a>5.21. Clear HTTP Auth on Tor Toggle (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
788
+  </p><p>
789
+This setting causes Torbutton to call <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIHttpAuthManager.html#method_clearAll" target="_top">nsIHttpAuthManager.clearAll()</a>
790
+every time Tor is toggled.
791
+</p><p>
792
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
793
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3005721"></a>5.22. Clear cookies on Tor/Non-Tor shutdown</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
794
+  </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
795
+cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
796
+clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
797
+for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
798
+<code class="function">torbutton_uninstall_observer()</code> and use <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js" target="_top">@stanford.edu/cookie-jar-selector;2</a>
799
+to clear out all cookies and all cookie jars upon shutdown.  </p><p>
800
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
801
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3005775"></a>5.23. Reload cookie jar/clear cookies on Firefox crash</h3></div></div></div><p>Options:
802
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.reload_crashed_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr></table><p>
803
+  </p><p>This is no longer a user visible option, and is enabled by default. In
804
+the event of a crash, the Torbutton <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js" target="_top">components/crash-observer.js</a> 
805
+  component will notify the Chrome (via the
806
+  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref and a <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver" target="_top">pref
807
+observer</a> in
808
+the chrome that listens for this update), and Torbutton will load the
809
+  correct jar for the current Tor state via the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js" target="_top">@stanford.edu/cookie-jar-selector;2</a>
810
+  component.</p><p>
811
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
812
+crashes.
813
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3005850"></a>5.24. On crash recovery or session restored startup, restore via: Tor, Non-Tor</h3></div></div></div><p>Options:
814
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.restore_tor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr></table><p>
815
+  </p><p>This option works with the Torbutton <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
816
+  to set the Tor state after a crash is detected (via the 
817
+  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref)</p><p>
818
+
819
+Since the Tor state after a Firefox crash is unknown/indeterminate, this
820
+setting helps to satisfy the <a class="link" href="#state">State Separation</a>
821
+requirement in the event of Firefox crashes by ensuring all cookies,
822
+settings and saved sessions are reloaded from a fixed Tor state.
823
+ 
824
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3005910"></a>5.25. On normal startup, set state to: Tor, Non-Tor, Shutdown State</h3></div></div></div><p>Options:
825
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.startup_state</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.noncrashed</strong></span></td></tr></table><p>
826
+  </p><p>This option also works with the Torbutton <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
827
+  to set the Tor state after a normal startup is detected (via the 
828
+  <span class="command"><strong>extensions.torbutton.noncrashed</strong></span> pref)</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3005958"></a>5.26. Prevent session store from saving Non-Tor/Tor-loaded tabs</h3></div></div></div><p>Options: 
829
+  </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.nonontor_sessionstore</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.notor_sessionstore</strong></span></td></tr></table><p>
830
+  </p><p>If these options are enabled, the <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.js" target="_top">replacement nsSessionStore.js</a>
831
+  component checks the <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tabs before writing them
832
+  out. If the tag is from a blocked Tor state, the tab is not written to disk.
833
+  </p><p>
834
+This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
835
+requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
836
+crashes.
837
+
838
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3006023"></a>5.27. Set user agent during Tor usage (crucial)</h3></div></div></div><p>Options:
839
+   </p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.set_uagent</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.oscpu_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.platform_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.productsub_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appname_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appversion_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendorSub</strong></span></td></tr></table><p>
840
+   </p><p>On face, user agent switching appears to be straight-forward in Firefox.
841
+It provides several options for controlling the browser user agent string:
842
+<span class="command"><strong>general.appname.override</strong></span>,
843
+<span class="command"><strong>general.appversion.override</strong></span>,
844
+<span class="command"><strong>general.platform.override</strong></span>,
845
+<span class="command"><strong>general.useragent.override</strong></span>,
846
+<span class="command"><strong>general.useragent.vendor</strong></span>, and
847
+<span class="command"><strong>general.useragent.vendorSub</strong></span>. If
848
+the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is
849
+true, Torbutton copies all of the other above prefs into their corresponding
850
+browser preferences during Tor usage.</p><p>However, this is not the whole story. Additionally, even with the above
851
+prefs set, the <span class="command"><strong>oscpu</strong></span>, <span class="command"><strong>buildID</strong></span>, and <span class="command"><strong>productSub</strong></span> fields of the
852
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.navigator" target="_top">navigator</a> object are not changed appropriately by the above prefs.
853
+Javascript hooks implemented in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/jshooks.js" target="_top">chrome/content/jshooks.js</a> are installed as part of the
854
+same mechanism that hooks the date object.
855
+</p><p>
856
+
857
+It also turns out that it is possible to detect the original Firefox version
858
+by <a class="ulink" href="http://0x000000.com/index.php?i=523&amp;bin=1000001011" target="_top">inspecting
859
+certain resource:// files</a>. These cases are handled by Torbutton's
860
+<a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
861
+
862
+</p><p>
863
+This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
864
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3006210"></a>5.28. Spoof US English Browser</h3></div></div></div><p>Options:
865
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.spoof_english</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_charset</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_language</strong></span></td></tr></table><p>
866
+</p><p> This option causes Torbutton to set
867
+<span class="command"><strong>general.useragent.locale</strong></span>,
868
+<span class="command"><strong>intl.accept_charsets</strong></span> and
869
+<span class="command"><strong>intl.accept_languages</strong></span> to the value specified in
870
+<span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
871
+<span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
872
+<span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage.  </p><p>
873
+This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and <a class="link" href="#location">Location Neutrality</a> requirements.
874
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3006297"></a>5.29. Don't send referrer during Tor Usage</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_referer</strong></span>
875
+</p><p> 
876
+This option causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer" target="_top">network.http.sendSecureXSiteReferrer</a> and
877
+<a class="ulink" href="http://kb.mozillazine.org/Network.http.sendRefererHeader" target="_top">network.http.sendRefererHeader</a> during Tor usage.</p><p>
878
+This setting also does not directly satisfy any Torbutton requirement, but
879
+some may desire to mask their referrer for general privacy concerns.
880
+</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3006338"></a>5.30. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h3></div></div></div><p>Options:
881
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td><span class="command"><strong>extensions.torbutton.jar_certs</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.jar_ca_certs</strong></span></td></tr></table><p>
882
+</p><p>
883
+
884
+These settings govern if Torbutton attempts to isolate the user's SSL
885
+certificates into separate jars for each Tor state. This isolation is
886
+implemented in <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>,
887
+which calls <code class="function">torbutton_jar_cert_type()</code> and
888
+<code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
889
+the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_securitynsscertcache1.html" target="_top">@mozilla.org/security/nsscertcache;1</a>.
890
+Certificates are deleted from and imported to the <a class="ulink" href="http://www.xulplanet.com/references/xpcomref/comps/c_securityx509certdb1.html" target="_top">@mozilla.org/security/x509certdb;1</a>.
891
+</p><p>
892
+The first time this pref is used, a backup of the user's certificates is
893
+created in their profile directory under the name
894
+<code class="filename">cert8.db.bak</code>. This file can be copied back to
895
+<code class="filename">cert8.db</code> to fully restore the original state of the
896
+user's certificates in the event of any error.
897
+</p><p>
898
+Since exit nodes and malicious sites can insert content elements sourced to
899
+specific SSL sites to query if a user has a certain certificate,
900
+this setting helps to satisfy the <a class="link" href="#state">State
901
+Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Firefox Bug
902
+435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
903
+is currently not exposed via the preferences UI.
904
+
905
+</p></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>
906
+
907
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxSecurity"></a>6.1. Bugs impacting security</h3></div></div></div><p>
908
+
909
+Torbutton has to work around a number of Firefox bugs that impact its
910
+security. Most of these are mentioned elsewhere in this document, but they
911
+have also been gathered here for reference. Several of these have fixes in
912
+Firefox3.0/trunk, but are listed because they still have not been backported
913
+to FF2.0. In order of decreasing severity, they are:
914
+
915
+   </p><div class="orderedlist"><ol type="1"><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=392274" target="_top">Bug 392274 - Timezone
916
+config/chrome API</a><p>
917
+The lack of a config or API to configure the timezone requires Torbutton to
918
+<a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript (crucial)">insert client content window javascript</a> to hook
919
+the Date object. Additionally, a way to <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-date.html" target="_top">remove the Date
920
+hooks</a> was discovered by Greg Fleischer. Worse, on Firefox 3,
921
+javascript sandboxing prevents most of the javascript hooks from being
922
+installed, including the Date hooks. On Windows and Linux, you can set the TZ
923
+environment variable to "UTC" as a workaround. Firefox will obey this
924
+environment variable for your Timezone on those platforms, but on Windows this
925
+does not take effect until browser restart. 
926
+   </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=436250" target="_top">Bug 436250 - Livemarks can't be
927
+disabled at runtime</a><p>
928
+
929
+The RSS Feed based "Livemarks"/"Live Bookmarks" update frequency is controlled
930
+by the pref <span class="command"><strong>browser.bookmarks.livemark_refresh_seconds</strong></span>.
931
+However, changing this preference does not cancel any pending timers, which
932
+means that at least one livemarks pref fetch will happen over Tor, and once
933
+this pref is set to disable livemarks for Tor, changing it back will never
934
+cause the service to start back up again.
935
+
936
+      </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Bug 435159 -
937
+nsNSSCertificateDB::DeleteCertificate has race conditions</a><p>
938
+
939
+In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
940
+the user has installed. Unfortunately, the method call to delete a certificate
941
+from the current certificate database acts lazily: it only sets a variable
942
+that marks a cert for deletion later, and it is not cleared if that
943
+certificate is re-added. This means that if the Tor state is toggled quickly,
944
+that certificate could remain present until it is re-inserted (causing an
945
+error dialog), and worse, it would still be deleted after that.  The lack of
946
+this functionality is considered a Torbutton security bug because cert
947
+isolation is considered a <a class="link" href="#state">State Separation</a>
948
+feature.
949
+
950
+      </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Bug 409737 -
951
+javascript.enabled and docShell.allowJavascript do not disable all event
952
+handlers</a><p>
953
+
954
+This bug allows pages to execute javascript via addEventListener and perhaps
955
+other callbacks. In order to prevent this bug from enabling an attacker to
956
+break the <a class="link" href="#isolation">Network Isolation</a> requirement,
957
+Torbutton 1.1.13 began blocking popups and history manipulation from different
958
+Tor states.  So long as there are no ways to open popups or redirect the user
959
+to a new page, the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content
960
+policy</a> should block Javascript network access. However, if there are
961
+ways to open popups or perform redirects such that Torbutton cannot block
962
+them, pages may still have free reign to break that requirement and reveal a
963
+user's original IP address.
964
+
965
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=405652" target="_top">Bug 405652 - In the
966
+TLS ClientHello message the gmt_unix_time is incorrect</a><p>
967
+
968
+It turns out that Firefox's SSL implementation sends the machine uptime as the
969
+current time. This essentially is a unique identifier that can be used for
970
+the duration of your machine uptime. The issue has been fixed in Firefox 3.0,
971
+but it has as of yet not been backported to 2.0.
972
+
973
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=143220" target="_top">Bug 143220 - Script can get the value of a file control, including the path</a><p>
974
+
975
+Javascript can query the .value field of file input dialogs to retrieve
976
+username and sometimes hostname/workgroup information. This is obviously very
977
+dangerous for people who are attempting to submit files anonymously via
978
+webforms (ie whistleblowers and anonymous publishers). It is also fixed in
979
+Firefox 3.0, but has not yet been backported to 2.0.
980
+
981
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418119" target="_top">Bug 418119 - nsIContentPolicy not called for external DTDs of XML documents</a><p>
982
+
983
+XML documents can source chrome and resource URLs in their DTDs without a call
984
+to nsIContentPolicy::shouldLoad. Enumerating chrome URLs gives websites and
985
+exit nodes a lot of information. They can use it to probe for vulnerable
986
+versions of extensions, and can also use it to build an <a class="link" href="#fingerprinting">identifier for tracking purposes</a>.  This bug
987
+makes it impossible for extensions such as Adblock and Torbutton to prevent
988
+chrome inspection and enumeration.  There is no workaround for this bug as of
989
+yet.
990
+
991
+      </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxWishlist"></a>6.2. Bugs blocking functionality</h3></div></div></div><p>
992
+The following bugs impact Torbutton and similar extensions' functionality.
993
+   </p><div class="orderedlist"><ol type="1"><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=439384" target="_top">Bug 439384 -
994
+"profile-do-change" event does not cause cookie table reload</a><p>
995
+
996
+In Firefox 3, the change to the new sqlite database for cookie storage has a
997
+bug that prevents Torbutton's cookie jaring from working properly. The
998
+"profile-do-change" observer event no longer properly causes either a sync or
999
+reload of the cookie database from disk after it is copied into place.
1000
+Torbutton currently works around this by issuing the SQLLite queries manually
1001
+to store and rebuild the cookie database.
1002
+
1003
+   </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869" target="_top">Bug 417869 -
1004
+Browser context is difficult to obtain from many XPCOM callbacks</a><p>
1005
+
1006
+It is difficult to determine which tabbrowser many XPCOM callbacks originate
1007
+from, and in some cases absolutely no context information is provided at all.
1008
+While this doesn't have much of an effect on Torbutton, it does make writing
1009
+extensions that would like to do per-tab settings and content filters (such as
1010
+FoxyProxy) difficult to impossible to implement securely.
1011
+
1012
+   </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418321" target="_top">Bug 418321 -
1013
+Components do not expose disk interfaces</a><p>
1014
+
1015
+Several components currently provide no way of reimplementing their disk
1016
+access to easily satisfy Torbutton's <a class="link" href="#disk">Disk
1017
+Avoidance</a> requirements. Workarounds exist, but they are <a class="link" href="#sessionstore" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore2.js and components/nsSessionStore3.js">clunky</a>, and
1018
+some of them involve disabling functionality during Tor usage.
1019
+
1020
+   </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxMiscBugs"></a>6.3. Low Priority Bugs</h3></div></div></div><p>
1021
+The following bugs have an effect upon Torbutton, but are superseded by more
1022
+practical and more easily fixable variant bugs above; or have stable, simple
1023
+workarounds.
1024
+  </p><div class="orderedlist"><ol type="1"><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435151" target="_top">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</a><p>
1025
+
1026
+Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
1027
+constructors of classes defined from within the scope of the sandbox, among
1028
+other things. This prevents Torbutton from applying the Timezone hooks under
1029
+Firefox 3, but a better solution for Torbutton's specific date hooking needs 
1030
+would be a fix for the above mentioned Bug 392274. Of course, many more
1031
+extensions may be interested in the sandbox hooking functionality working
1032
+properly though.
1033
+
1034
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">Bug 437014 -
1035
+nsIContentPolicy::shouldLoad no longer called for favicons</a><p>
1036
+
1037
+Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
1038
+loads. Torbutton had relied on this call to block favicon loads for opposite
1039
+Tor states. The workaround it employs for Firefox 3 is to cancel the request
1040
+when it arrives in the <span class="command"><strong>torbutton_http_observer</strong></span> used for
1041
+blocking full page plugin loads. This seems to work just fine, but is a bit
1042
+dirty.
1043
+
1044
+    </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437016" target="_top">Bug 437016 -
1045
+nsIContentPolicy::shouldLoad not called for livemarks</a><p>
1046
+
1047
+An alternative fix for the livemarks bug above would be to block livemarks
1048
+fetches from the content policy. Unfortunately shouldLoad is not called for
1049
+livemarks fetches.
1050
+
1051
+    </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418986" target="_top">Bug 418986 - window.screen
1052
+provides a large amount of identifiable information</a><p>
1053
+
1054
+As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of
1055
+information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>.
1056
+Currently, there is no way to obscure this information without Javascript
1057
+hooking. This bug is a feature request to provide some other method to change
1058
+these values.
1059
+
1060
+   </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">Bug 309524</a>
1061
+and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">Bug
1062
+380556</a> - nsIContentPolicy::shouldProcess is not called.
1063
+     <p>
1064
+
1065
+This is a call that would be useful to develop a better workaround for the
1066
+allowPlugins issue above. If the content policy were called before a URL was
1067
+handed over to a plugin or helper app, it would make the workaround for the
1068
+above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
1069
+the others though, but it might be nice to have this API as a backup.
1070
+
1071
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">Bug 401296 - docShell.allowPlugins
1072
+not honored for direct links</a> (Perhaps subset of <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=282106" target="_top">Bug 282106</a>?)
1073
+     <p>
1074
+
1075
+Similar to the javascript plugin disabling attribute, the plugin disabling
1076
+attribute is also not perfect — it is ignored for direct links to plugin
1077
+handled content, as well as meta-refreshes to plugin handled content.  This
1078
+requires Torbutton to listen to a number of different http events to intercept
1079
+plugin-related mime type URLs and cancel their requests. Again, since plugins
1080
+are quite horrible about obeying proxy settings, loading a plugin pretty much
1081
+ensures a way to break the <a class="link" href="#isolation">Network Isolation</a>
1082
+requirement and reveal a user's original IP address. Torbutton's code to
1083
+perform this workaround has been subverted at least once already by Kyle
1084
+Williams.
1085
+
1086
+     </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418983" target="_top">Bug 41893 - Scoping
1087
+issues with window.__defineGetter__()</a><p>
1088
+
1089
+For some reason, defining getters off of window seems to mess with the
1090
+implicit window scoping in some documents. There is a workaround for this bug,
1091
+so it is barely relevant. It would be far more useful to eliminate the need
1092
+for Javascript hooking in the first place by addressing the above bugs. This
1093
+bug is just listed for completeness.
1094
+
1095
+   </p></li><li><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598" target="_top">Bug 419598 - 'var
1096
+Date' is deletable</a><p>
1097
+
1098
+Based on Page 62 of the <a class="ulink" href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf" target="_top">ECMA-262
1099
+Javascript spec</a>, it seems like it should be possible to do something
1100
+like the following to prevent the Date object from being unmasked:
1101
+</p><pre class="screen">
1102
+with(window) {
1103
+    var Date = fakeDate;
1104
+    var otherVariable = 42;
1105
+}
1106
+
1107
+delete window.Date; // Should fail. Instead succeeds, revealing original Date.
1108
+delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
1109
+</pre><p>
1110
+
1111
+From the ECMA-262 spec:
1112
+
1113
+</p><div class="blockquote"><blockquote class="blockquote">
1114
+If the variable statement occurs inside a FunctionDeclaration, the variables
1115
+are defined with function-local scope in that function, as described in
1116
+s10.1.3. Otherwise, they are defined with global scope (that is, they are
1117
+created as members of the global object, as described in 10.1.3) using
1118
+property attributes { DontDelete }. Variables are created when the execution
1119
+scope is entered. A Block does not define a new execution scope. Only Program
1120
+and FunctionDeclaration produce a new scope. Variables are initialized to
1121
+undefined when created. A variable with an Initialiser is assigned the value
1122
+of its AssignmentExpression when the VariableStatement is executed, not when
1123
+the variable is created.
1124
+</blockquote></div><p>
1125
+
1126
+In fact, this is exactly how the with statement with a variable declaration
1127
+behaves <span class="emphasis"><em>for all other variables other than ones that shadow system
1128
+variables</em></span>. Some variables (such as
1129
+<span class="command"><strong>window.screen</strong></span>, and <span class="command"><strong>window.history</strong></span>) can't
1130
+even be shadowed in this way, and give an error about lacking a setter. If
1131
+such shadowing were possible, it would greatly simplify the Javascript hooking
1132
+code, which currently relies on undocumented semantics of
1133
+<span class="command"><strong>__proto__</strong></span> to copy the original values in the event of a
1134
+delete. This <span class="command"><strong>__proto__</strong></span> hack unfortunately does not work for
1135
+the Date object though.
1136
+
1137
+     </p></li></ol></div></div></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="TestPlan"></a>7. Testing</h2></div></div></div><p>
1138
+
1139
+The purpose of this section is to cover all the known ways that Tor browser
1140
+security can be subverted from a testing and penetration perspective. The hope
1141
+is that it will be useful both for creating a "Tor Safety Check"
1142
+page, and for developing novel tests and actively attacking Torbutton with the
1143
+goal of finding vulnerabilities in either it or the Mozilla components,
1144
+interfaces and settings upon which it relies.
1145
+ 
1146
+  </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="Categories"></a>7.1. Single state testing</h3></div></div></div><p>
1147
+The following tests can be run from a single web page in one visit without
1148
+toggling Tor state or requiring user interaction. Currently they exist as their
1149
+own individual tests, but conceivably a single "Tor Safety Check"
1150
+page can be devised that contains all of these attacks. 
1151
+All of these tests are currently known to pass, but that does not mean that
1152
+consolidating them into an easy to run test page is pointless. Torbutton is a
1153
+complicated piece of software. During development, changes to one component
1154
+can affect a whole slough of unrelated features. Having easy-to-verify
1155
+comprehensive test pages would make it much easier to fix other issues as they
1156
+present themselves without introducing regressions.
1157
+
1158
+   </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007076"></a>Java and Plugin Decloaking</h4></div></div></div><p>
1159
+As <a class="link" href="#plugins" title="5.2. Disable plugins on Tor Usage (crucial)">mentioned above</a>, Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html" target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html" target="_top">local IP
1160
+address</a> and report it back to the
1161
+remote site. They can also <a class="ulink" href="http://metasploit.com/research/misc/decloak/index.htm" target="_top">bypass proxy settings</a> and directly connect to a
1162
+remote site without Tor. Every browser plugin we have tested with Firefox has
1163
+some form of network capability, and every one ignores proxy settings or worse - only
1164
+partially obeys them. This includes but is not limited to:
1165
+QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
1166
+Flash. In addition, 
1167
+<a class="ulink" href="http://www.janusvm.com/goldy/pdf/" target="_top">issues have been
1168
+discovered</a> with the browsers handling of
1169
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">direct links to plugin-handled
1170
+content</a> as well as meta-refreshes to plugin content. To make matters
1171
+worse, <a class="ulink" href="http://www.janusvm.com/goldy/side-channels/side-channels.html" target="_top">externally
1172
+handled mime types and urls</a> can also cause direct non-Tor connections
1173
+as well.
1174
+    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007174"></a>History Disclosure attacks</h4></div></div></div><p>
1175
+The browser's history can also be queried by a remote site to inspect for
1176
+Google queries, visits to sites that contain usernames in the URLs, or
1177
+other anonymity set reducing information. This can be done by either
1178
+<a class="ulink" href="http://gemal.dk/browserspy/css.html" target="_top">Javascript</a>, or by 
1179
+<a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS</a> without any scripting involved.
1180
+
1181
+    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007200"></a>User agent, extension, resolution and OS information</h4></div></div></div><p>
1182
+
1183
+As mentioned above, these properties can be combined to greatly reduce
1184
+anonymity set and even build a potentially <a class="link" href="#fingerprinting">globally unique identifier</a> for
1185
+users. <a class="ulink" href="http://0x000000.com/index.php?i=520&amp;bin=1000001000" target="_top">Examples of this
1186
+in the wild</a> rely on <a class="ulink" href="http://gemal.dk/browserspy/basic.html" target="_top">user agent and OS
1187
+information</a> as well as <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">chrome disclosure
1188
+information</a>.
1189
+
1190
+    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007238"></a>Timezone and Location Information</h4></div></div></div><p>
1191
+<a class="ulink" href="http://gemal.dk/browserspy/date.html" target="_top">Time and Timezone</a>
1192
+should be obscured to be GMT-only, and by the browser should present itself
1193
+with an US English locale.
1194
+    </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3007257"></a>7.2. Multi-state testing</h3></div></div></div><p>
1195
+
1196
+The tests in this section are geared towards a page that would instruct the
1197
+user to toggle their Tor state after the fetch and perform some operations:
1198
+mouseovers, stray clicks, and potentially reloads.
1199
+
1200
+   </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007269"></a>Cookies and Cache Correlation</h4></div></div></div><p>
1201
+The most obvious test is to set a cookie, ask the user to toggle tor, and then
1202
+have them reload the page. The cookie should no longer be set if they are
1203
+using the default Torbutton settings. In addition, it is possible to leverage
1204
+the cache to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
1205
+identifiers</a>. The default settings of Torbutton should also protect
1206
+against these from persisting across Tor Toggle.
1207
+
1208
+    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007292"></a>Javascript timers and event handlers</h4></div></div></div><p>
1209
+
1210
+Javascript can set timers and register event handlers in the hopes of fetching
1211
+URLs after the user has toggled Torbutton. 
1212
+    </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007305"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
1213
+
1214
+Even if Javascript is disabled, CSS is still able to 
1215
+<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like
1216
+windows</a>
1217
+via the 'onmouseover' CSS attribute, which can cause arbitrary browser
1218
+activity as soon as the mouse enters into the content window. It is also
1219
+possible for meta-refresh tags to set timers long enough to make it likely
1220
+that the user has toggled Tor before fetching content.
1221
+
1222
+    </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id3007328"></a>7.3. Active testing (aka How to Hack Torbutton)</h3></div></div></div><p>
1223
+
1224
+The idea behind active testing is to discover vulnerabilities in Torbutton to
1225
+bypass proxy settings, run script in an opposite Tor state, store unique
1226
+identifiers, leak location information, or otherwise violate <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. Torbutton has ventured out
1227
+into a strange and new security landscape. It depends on Firefox mechanisms
1228
+that haven't necessarily been audited for security, certainly not for the
1229
+threat model that Torbutton seeks to address. As such, it and the interfaces
1230
+it depends upon still need a 'trial by fire' typical of new technologies. This
1231
+section of the document was written with the intention of making that period
1232
+as fast as possible. Please help us get through this period by considering
1233
+these attacks, playing with them, and reporting what you find (and potentially
1234
+submitting the test cases back to be run in the standard batch of Torbutton
1235
+tests.
1236
+
1237
+   </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id3007358"></a>Some suggested vectors to investigate</h4></div></div></div><p>
1238
+    </p><div class="itemizedlist"><ul type="disc"><li>Strange ways to register Javascript <a class="ulink" href="http://en.wikipedia.org/wiki/DOM_Events" target="_top">events</a> and <a class="ulink" href="http://www.devshed.com/c/a/JavaScript/Using-Timers-in-JavaScript/" target="_top">timeouts</a> should
1239
+be verified to actually be ineffective after Tor has been toggled.</li><li>Other ways to cause Javascript to be executed after
1240
+<span class="command"><strong>javascript.enabled</strong></span> has been toggled off.</li><li>Odd ways to attempt to load plugins. Kyle Williams has had
1241
+<a class="ulink" href="http://www.janusvm.com/goldy/pdf/" target="_top">some
1242
+success</a> with direct loads/meta-refreshes of plugin-handled URLs.</li><li>The Date and Timezone hooks should be verified to work with
1243
+crazy combinations of iframes, nested iframes, iframes in frames, frames in
1244
+iframes, and popups being loaded and
1245
+reloaded in rapid succession, and/or from one another. Think race conditions and deep, 
1246
+parallel nesting, involving iframes from both <a class="ulink" href="http://en.wikipedia.org/wiki/Same_origin_policy" target="_top">same-origin and
1247
+non-same-origin</a> domains.</li><li>In addition, there may be alternate ways and other
1248
+methods to query the timezone, or otherwise use some of the Date object's
1249
+methods in combination to deduce the timezone offset. Of course, the author
1250
+tried his best to cover all the methods he could foresee, but it's always good
1251
+to have another set of eyes try it out.</li><li>Similarly, is there any way to confuse the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>
1252
+mentioned above to cause it to allow certain types of page fetches? For
1253
+example, it was recently discovered that favicons are not fetched by the
1254
+content, but the chrome itself, hence the content policy did not look up the
1255
+correct window to determine the current Tor tag for the favicon fetch. Are
1256
+there other things that can do this? Popups? Bookmarklets? Active bookmarks? </li><li>Alternate ways to store and fetch unique identifiers. For example, <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a>
1257
+caught us off guard. 
1258
+It was
1259
+also discovered by <a class="ulink" href="http://pseudo-flaw.net" target="_top">Gregory
1260
+Fleischer</a> that <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">content window access to
1261
+chrome</a> can be used to build <a class="link" href="#fingerprinting">unique
1262
+identifiers</a>. 
1263
+Are there any other
1264
+arcane or experimental ways that Firefox provides to create and store unique
1265
+identifiers? Or perhaps unique identifiers can be queried or derived from
1266
+properties of the machine/browser that Javascript has access to? How unique
1267
+can these identifiers be?
1268
+     </li><li>Is it possible to get the browser to write some history to disk
1269
+(aside from swap) that can be retrieved later? By default, Torbutton should
1270
+write no history, cookie, or other browsing activity information to the
1271
+harddisk.</li><li>Do popup windows make it easier to break any of the above
1272
+behavior? Are javascript events still canceled in popups? What about recursive
1273
+popups from Javascript, data, and other funky URL types? What about CSS
1274
+popups? Are they still blocked after Tor is toggled?</li><li>Chrome-escalation attacks. The interaction between the
1275
+Torbutton chrome Javascript and the client content window javascript is pretty
1276
+well-defined and carefully constructed, but perhaps there is a way to smuggle
1277
+javascript back in a return value, or otherwise inject network-loaded
1278
+javascript into the chrome (and thus gain complete control of the browser).
1279
+</li></ul></div><p>
1280
+
1281
+    </p></div></div></div></div></body></html>
... ...
@@ -0,0 +1,3 @@
1
+LI:first-line {
2
+ font-weight: bold
3
+}
... ...
@@ -0,0 +1,532 @@
1
+<html>
2
+<head>
3
+<title>Torbutton - Quickly toggle Firefox's use of the Tor network</title>
4
+<LINK REL="stylesheet" TYPE="text/css" HREF="gimpy.css">
5
+
6
+<link rel="search" type="application/opensearchdescription+xml" title="Google Canada" href="search/google-ca.xml">
7
+<link rel="search" type="application/opensearchdescription+xml" title="Google UK" href="http://torbutton.torproject.org/dev/search/google-uk.xml">
8
+<link rel="search" type="application/opensearchdescription+xml" title="Google USA" href="search/google-us.xml">
9
+<script>
10
+
11
+function addSearchProvider(prov) {
12
+
13
+try {
14
+window.external.AddSearchProvider(prov);
15
+}
16
+
17
+catch (e) {
18
+alert("Search plugins require Firefox 2");
19
+return;
20
+}
21
+}
22
+
23
+function addEngine(name,ext,cat,pid)
24
+{
25
+  if ((typeof window.sidebar == "object") && (typeof window.sidebar.addSearchEngine == "function")) {
26
+    window.sidebar.addSearchEngine(
27
+      "http://mycroft.mozdev.org/install.php/" + pid + "/" + name + ".src",
28
+      "http://mycroft.mozdev.org/install.php/" + pid + "/" + name + "."+ ext, name, cat );
29
+  } else {
30
+    alert("You will need a browser which supports Sherlock to install this plugin.");
31
+  }
32
+}
33
+
34
+function addOpenSearch(name,ext,cat,pid,meth)
35
+{
36
+  if ((typeof window.external == "object") && ((typeof window.external.AddSearchProvider == "unknown") || (typeof window.external.AddSearchProvider == "function"))) {
37
+    if ((typeof window.external.AddSearchProvider == "unknown") && meth == "p") {
38
+      alert("This plugin uses POST which is not currently supported by Internet Explorer's implementation of OpenSearch.");
39
+    } else {
40
+      window.external.AddSearchProvider(
41
+        "http://mycroft.mozdev.org/installos.php/" + pid + "/" + name + ".xml");
42
+    }
43
+  } else {
44
+    alert("You will need a browser which supports OpenSearch to install this plugin.");
45
+  }
46
+}
47
+
48
+function addOpenSearch2(name,ext,cat,pid,meth)
49
+{
50
+  if ((typeof window.external == "object") && ((typeof window.external.AddSearchProvider == "unknown") || (typeof window.external.AddSearchProvider == "function"))) {
51
+    if ((typeof window.external.AddSearchProvider == "unknown") && meth == "p") {
52
+      alert("This plugin uses POST which is not currently supported by Internet Explorer's implementation of OpenSearch.");
53
+    } else {
54
+      window.external.AddSearchProvider(
55
+        "http://torbutton.torproject.org/dev/search/" + name + ".xml");
56
+    }
57
+  } else {
58
+    alert("You will need a browser which supports OpenSearch to install this plugin.");
59
+  }
60
+}
61
+
62
+function install (aEvent)
63
+{
64
+  var params = {
65
+    "Torbutton": { URL: aEvent.target.href,
66
+             Hash: aEvent.target.getAttribute("hash"),
67
+             toString: function () { return this.URL; }
68
+    }
69
+  };
70
+  InstallTrigger.install(params);
71
+
72
+  return false;
73
+}
74
+
75
+
76
+</script>
77
+</head>
78
+<body>
79
+
80
+<h1>Torbutton Development Branch</h1>
81
+<strong>Current version:</strong> 1.2.0rc6 (12 Jul 2008)<br/>
82
+<br/>
83
+<strong>Authors:</strong> Scott Squires &amp; Mike Perry<br>
84
+<strong>Email:</strong> squires at freehaven dot net, mikeperry (o) fscked/org<br/>
85
+<br/>
86
+<strong>Install:</strong> 
87
+<a href="http://torbutton.torproject.org/dev/torbutton-current.xpi"
88
+  hash="sha1:7f01c577641b6222781cd880c9825d6f50ff1cc4"
89
+  onclick="return install(event);">Local (Javascript verified)</a><br/>
90
+<strong>Past Releases:</strong> <a href="releases/">Local (non-https)</a><br/>
91
+<strong>Developer Documentation:</strong> <a href="design/">Torbutton Design Document</a> and <a href="design/MozillaBrownBag.pdf">Slides (Not actively updated)</a><br/>
92
+<strong>Extras:</strong> 
93
+
94
+Google search plugins for
95
+
96
+<a href="/jsreq.html" title="Ref: 14938 (googleCA)"
97
+ onClick="addOpenSearch('GoogleCanada','ico','General','14937','g');return false">Google CA</a>, and 
98
+
99
+<a href="/jsreq.html" title="Ref: 14938 (googleCA)"
100
+ onClick="addOpenSearch('googleuk_web','png','General','14445','g');return false">Google UK</a>.
101
+<br/>
102
+<!--
103
+<strong>Install:</strong> <a href="torbutton-1.0.4.xpi">torbutton-1.0.4.xpi</a><br/>
104
+-->
105
+<strong>Source:</strong> You can <a href="https://tor-svn.freehaven.net/svn/torbutton/trunk/">browse the repository</a> or simply unzip the xpi.
106
+<br/>
107
+<strong>Bug Reports:</strong> <a href="https://bugs.torproject.org/flyspray/index.php?tasks=all&project=5">Torproject flyspray</a><br/>
108
+<strong>Documents:</strong> <b>[</b> <a href="#FAQ">FAQ</a> <b>|</b> <a href="CHANGELOG">changelog</a> <b>|</b> <a href="LICENSE">license</a> <b>|</b> <a href="CREDITS">credits</a> <b>]</b><br/>
109
+<h2>About</h2>
110
+<p>
111
+Torbutton is a 1-click way for Firefox users to enable or disable the browser's use of <a href="https://www.torproject.org/">Tor</a>.  It adds a panel to the statusbar that says "Tor Enabled" (in green) or "Tor Disabled" (in red).  The user may click on the panel to toggle the status.  If the user (or some other extension) changes the proxy settings, the change is automatically reflected in the statusbar.
112
+</p><p>
113
+Some users may prefer a toolbar button instead of a statusbar panel.  Such a button is included, and one adds it to the toolbar by right-clicking on the desired toolbar, selecting "Customize...", and then dragging the Torbutton icon onto the toolbar.  There is an option in the preferences to hide the statusbar panel (Tools-&gt;Extensions, select Torbutton, and click on Preferences).
114
+</p>
115
+<p>
116
+Newer Firefoxes have the ability to send DNS resolves through the socks proxy, and Torbutton will make use of this feature if it is available in your version of Firefox.
117
+</p>
118
+
119
+<a id="FAQ"></a><h2>FAQ</h2>
120
+
121
+<strong>I can't click on links or hit reload after I toggle Tor! Why?</strong>
122
+<p>
123
+
124
+Due to <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox
125
+Bug 409737</a>, pages can still open popups and perform Javascript redirects
126
+and history access after Tor has been toggled. These popups and redirects can
127
+be blocked, but unfortunately they are indistinguishable from normal user
128
+interactions with the page (such as clicking on links, opening them in new
129
+tabs/windows, or using the history buttons), and so those are blocked as a
130
+side effect. Once that Firefox bug is fixed, this degree of isolation will
131
+become optional (for people who do not want to accidentally click on links and
132
+give away information via referrers). A workaround is to right click on the
133
+link, and open it in a new tab or window. The tab or window won't load
134
+automatically, but you can hit enter in the URL bar, and it will begin
135
+loading. Hitting enter in the URL bar will also reload the page without
136
+clicking the reload button.
137
+
138
+</p>
139
+
140
+<strong>My browser is in some weird state where nothing works right!</strong>
141
+<p>
142
+
143
+Try to disable Tor by clicking on the button, and then open a new window. If
144
+that doesn't fix the issue, go to the preferences page and hit 'Restore
145
+Defaults'. This should reset the extension and Firefox to a known good
146
+configuration.  If you can manage to reproduce whatever issue gets your
147
+Firefox wedged, please file details at <a
148
+href="https://bugs.torproject.org/flyspray/index.php?tasks=all&project=5">the
149
+bug tracker</a>.
150
+
151
+</p>
152
+
153
+<strong>When I toggle Tor, my sites that use javascript stop working. Why?</strong>
154
+<p>
155
+
156
+Javascript can do things like wait until you have disabled Tor before trying
157
+to contact its source site, thus revealing your IP address. As such, Torbutton
158
+must disable Javascript, Meta-Refresh tags, and certain CSS behavior when Tor
159
+state changes from the state that was used to load a given page. These features 
160
+are re-enabled when Torbutton goes back into the state that was used to load
161
+the page, but in some cases (particularly with Javascript and CSS) it is
162
+sometimes not possible to fully recover from the resulting errors, and the
163
+page is broken. Unfortunately, the only thing you can do (and still remain
164
+safe from having your IP address leak) is to reload the page when you toggle
165
+Tor, or just ensure you do all your work in a page before switching tor state.
166
+
167
+</p>
168
+
169
+
170
+<strong>When I use Tor, Firefox is no longer filling in logins/search boxes
171
+for me. Why?</strong>
172
+<p>
173
+
174
+Currently, this is tied to the "<b>Block history writes during Tor</b>"
175
+setting. If you have enabled that setting, all formfill functionality (both
176
+saving and reading) is disabled. If this bothers you, you can uncheck that
177
+option, but both history and forms will be saved. To prevent history
178
+disclosure attacks via Non-Tor usage, it is recommended you disable Non-Tor
179
+history reads if you allow history writing during Tor.
180
+
181
+</p>
182
+
183
+
184
+<strong>Which Firefox extensions should I avoid using?</strong>
185
+<p>
186
+
187
+This is a tough one. There are thousands of Firefox extensions: making a
188
+complete list of ones that are bad for anonymity is near impossible. However,
189
+here are a few examples that should get you started as to what sorts of
190
+behavior are dangerous.
191
+
192
+<ol>
193
+ <li>StumbleUpon, et al</li>
194
+ These extensions will send all sorts of information about the websites you
195
+ visit to the stumbleupon servers, and correlate this information with a
196
+ unique identifier. This is obviously terrible for your anonymity.
197
+ More generally, any sort of extension that requires registration, or even
198
+ extensions that provide information about websites you visit should be
199
+ suspect.
200
+
201
+ <li>FoxyProxy</li>
202
+
203
+While FoxyProxy is a nice idea in theory, in practice it is impossible to
204
+configure securely for Tor usage without Torbutton. Like all vanilla third
205
+party proxy plugins, the main risks are <a
206
+href="http://www.metasploit.com/research/projects/decloak/">plugin leakage</a>
207
+and <a href="http://ha.ckers.org/weird/CSS-history.cgi">history
208
+disclosure</a>, followed closely by cookie theft by exit nodes and tracking by
209
+adservers (see the <a href="design/index.html#adversary">Torbutton Adversary
210
+Model</a> for more information). However, even with Torbutton installed in
211
+tandem and always enabled, it is still very difficult (though not impossible)
212
+to configure FoxyProxy securely. Since FoxyProxy's 'Patterns' mode only
213
+applies to specific urls, and not to an entire tab, setting FoxyProxy to only
214
+send specific sites through Tor will still allow adservers to still learn your
215
+real IP. Worse, if those sites use offsite logging services such as Google
216
+Analytics, you may still end up in their logs with your real IP. Malicious
217
+exit nodes can also cooperate with sites to inject images into pages that
218
+bypass your filters. Setting FoxyProxy to only send certain URLs via Non-Tor
219
+is much more viable, but be very careful with the filters you allow. For
220
+example, something as simple as allowing *google* to go via Non-Tor will still
221
+cause you to end up in all the logs of all websites that use Google Analytics!
222
+See <a href="http://foxyproxy.mozdev.org/faq.html#privacy-01">this
223
+question</a> on the FoxyProxy FAQ for more information.
224
+
225
+ <li>NoScript</li>
226
+ Torbutton currently mitigates all known anonymity issues with Javascript.
227
+ While it may be tempting to get better security by disabling Javascript for
228
+ certain sites, you are far better off with an all-or-nothing approach.
229
+ NoScript is exceedingly complicated, and has many subtleties that can surprise
230
+ even advanced users. For example, addons.mozilla.org verifies extension
231
+ integrity via Javascript over https, but downloads them in the clear. Not 
232
+ adding it to your whitelist effectively
233
+ means you are pulling down unverified extensions. Worse still, using NoScript
234
+ can actually disable protections that Torbutton itself provides via
235
+ Javascript, yet still allow malicious exit nodes to compromise your
236
+ anonymity via the default whitelist (which they can spoof to inject any script  they want). 
237
+
238
+</ol>
239
+
240
+</p>
241
+
242
+<strong>Which Firefox extensions do you recommend?</strong>
243
+<p>
244
+<ol>
245
+ <li><a href="https://addons.mozilla.org/en-US/firefox/addon/953">RefControl</a></li>
246
+ Mentioned above, this extension allows more fine-grained referrer spoofing
247
+than Torbutton currently provides. It should break less sites than Torbutton's
248
+referrer spoofing option.
249
+ <li><a href="https://addons.mozilla.org/en-US/firefox/addon/1474">SafeCache</a></li>
250
+ If you use Tor excessively, and rarely disable it, you probably want to
251
+install this extension to minimize the ability of sites to store long term
252
+identifiers in your cache. This extension applies same origin policy to the
253
+cache, so that elements are retrieved from the cache only if they are fetched
254
+from a document in the same origin domain as the cached element. 
255
+</ol>
256
+
257
+</p>
258
+
259
+<strong>Are there any other issues I should be concerned about?</strong>
260
+<p>
261
+
262
+There is currently one known unfixed security issue with Torbutton: it is
263
+possible to unmask the javascript hooks that wrap the Date object to conceal
264
+your timezone in Firefox 2, and the timezone masking code does not work at all
265
+on Firefox 3. We are working with the Firefox team to fix one of <a
266
+href="https://bugzilla.mozilla.org/show_bug.cgi?id=392274">Bug 399274</a> or
267
+<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598</a>
268
+to address this. In the meantime, it is possible to set the <b>TZ</b>
269
+environment variable to <b>UTC</b> to cause the browser to use UTC as your
270
+timezone. Under Linux, you can add an <b>export TZ=UTC</b> to the
271
+/usr/bin/firefox script, or edit your system bashrc to do the same. Under
272
+Windows, you can set either a <a
273
+href="http://support.microsoft.com/kb/310519">User or System Environment
274
+Variable</a> for TZ via My Computer's properties. In MacOS, the situation is
275
+<a
276
+href="http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/EnvironmentVars.html#//apple_ref/doc/uid/20002093-BCIJIJBH">a
277
+lot more complicated</a>, unfortunately.
278
+
279
+</p>
280
+
281
+<p>
282
+
283
+In addition, RSS readers such as Firefox Livemarks can perform
284
+periodic fetches. Due to <a
285
+href="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
286
+436250</a>, there is no way to disable Livemark fetches during Tor. This can
287
+be a problem if you have a lot of custom Livemark urls that can give away
288
+information about your identity.
289
+
290
+</p>
291
+
292
+<h2>Description of Options</h2>
293
+
294
+<p>The development branch of Torbutton adds several new security features to
295
+protect your anonymity from all the major threats the author is aware of. The
296
+defaults should be fine for most people, but in case you are the tweaker type,
297
+or if you prefer to try to outsource some options to more flexible extensions,
298
+here is the complete list. (In an ideal world, these descriptions should all be
299
+tooltips in the extension itself, but Firefox bugs <a
300
+href="https://bugzilla.mozilla.org/show_bug.cgi?id=45375">45375</a> and <a
301
+href="https://bugzilla.mozilla.org/show_bug.cgi?id=218223">218223</a> currently
302
+prevent this).</p>
303
+
304
+<ul>
305
+ <li>Disable plugins on Tor Usage (crucial)</li>
306
+
307
+  This option is key to Tor security. Plugins perform their own networking
308
+independent of the browser, and many plugins only partially obey even their own
309
+proxy settings.
310
+
311
+  <li>Isolate Dynamic Content to Tor State (crucial)</li>
312
+
313
+  Another crucial option, this setting causes the plugin to disable Javascript
314
+  on tabs that are loaded during a Tor state different than the current one,
315
+  to prevent delayed fetches of injected URLs that contain unique identifiers,
316
+  and to prevent meta-refresh tags from revealing your IP when you turn off
317
+  Tor. It also prevents all fetches from tabs loaded with an opposite Tor
318
+  state. This serves to block non-Javascript dynamic content such as CSS
319
+  popups from revealing your IP address if you disable Tor.
320
+
321
+  <li>Hook Dangerous Javascript (crucial)</li>
322
+
323
+This setting enables the Javascript hooking code. Javascript is injected into
324
+pages to hook the Date object to mask your timezone, and to hook the navigator
325
+object to mask OS and user agent properties not handled by the standard
326
+Firefox user agent override settings.
327
+
328
+  <li>Resize window dimensions to multiples of 50px on toggle (recommended)</li>
329
+
330
+To cut down on the amount of state available to fingerprint users uniquely, 
331
+this pref causes windows to be resized to a multiple of 50 pixels on each
332
+side when Tor is enabled and pages are loaded.
333
+
334
+  <li>Disable Updates During Tor (recommended)</li>
335
+
336
+Under Firefox 2, many extension authors did not update their extensions from 
337
+SSL-enabled websites. It is possible for malicious Tor nodes to hijack these extensions and replace them with malicious ones, or add malicious code to 
338
+existing extensions. Since Firefox 3 now enforces encrypted and/or
339
+authenticated updates, this setting is no longer as important as it once
340
+was (though updates do leak information about which extensions you have, it is
341
+fairly infrequent).
342
+
343
+  <li>Disable Search Suggestions during Tor (optional)</li>
344
+
345
+This optional setting governs if you get Google search suggestions during Tor
346
+usage. Since no cookie is transmitted during search suggestions, this is a
347
+relatively benign behavior.
348
+
349
+  <li>Block Tor/Non-Tor access to network from file:// urls (recommended)</li>
350
+
351
+These settings prevent local html documents from transmitting local files to
352
+arbitrary websites <a href="http://www.gnucitizen.org/blog/content-disposition-hacking/">under Firefox 2</a>. Since exit nodes can insert headers that
353
+force the browser to save arbitrary pages locally (and also inject script into
354
+arbitrary html files you save to disk via Tor), it is probably a good idea to
355
+leave this setting on.
356
+
357
+  <li>Close all Non-Tor/Tor windows and tabs on toggle (optional)</li>
358
+
359
+These two settings allow you to obtain a greater degree of assurance that
360
+after you toggle out of Tor, the pages are really gone and can't perform any
361
+extra network activity. Currently, there is no known way that pages can still
362
+perform activity after toggle, but these options exist as a backup measure
363
+just in case a flaw is discovered. They can also serve as a handy 'Boss
364
+Button' feature for clearing all Tor browsing off your screen in a hurry.
365
+
366
+  <li>Isolate access to history navigation to Tor state (crucial)</li>
367
+
368
+This setting prevents both Javascript and accidental user clicks from causing
369
+the session history to load pages that were fetched in a different Tor state
370
+than the current one. Since this can be used to correlate Tor and Non-Tor
371
+activity and thus determine your IP address, it is marked as a crucial 
372
+setting.
373
+
374
+  <li>Block History Reads during Tor (crucial)</li>
375
+
376
+  Based on code contributed by <a href="http://www.collinjackson.com/">Collin
377
+  Jackson</a>, when enabled and Tor is enabled, this setting prevents the
378
+rendering engine from knowing if certain links were visited.  This mechanism
379
+defeats all document-based history disclosure attacks, including CSS-only
380
+attacks.
381
+
382
+  <li>Block History Reads during Non-Tor (recommended)</li>
383
+
384
+  This setting accomplishes the same but for your Non-Tor activity.
385
+
386
+  <li>Block History Writes during Tor (recommended)</li>
387
+
388
+  This setting prevents the rendering engine from recording visited URLs, and
389
+also disables download manager history. Note that if you allow writing of Tor history,
390
+it is recommended that you disable non-Tor history reads, since malicious
391
+websites you visit without Tor can query your history for .onion sites and
392
+other history recorded during Tor usage (such as Google queries).
393
+
394
+  <li>Block History Writes during Non-Tor (optional)</li>
395
+
396
+This setting also disables recording any history information during Non-Tor
397
+usage.
398
+
399
+<li>Clear History During Tor Toggle (optional)</li>
400
+
401
+  This is an alternate setting to use instead of (or in addition to) blocking
402
+history reads or writes.
403
+
404
+  <li>Block Password+Form saving during Tor/Non-Tor</li>
405
+
406
+  These options govern if the browser writes your passwords and search
407
+  submissions to disk for the given state.
408
+
409
+  <li>Block Tor disk cache and clear all cache on Tor Toggle</li>
410
+
411
+  Since the browser cache can be leveraged to store unique identifiers, cache
412
+must not persist across Tor sessions. This option keeps the memory cache active
413
+during Tor usage for performance, but blocks disk access for caching.
414
+
415
+  <li>Block disk and memory cache during Tor</li>
416
+
417
+  This setting entirely blocks the cache during Tor, but preserves it for
418
+Non-Tor usage.
419
+
420
+  <li>Clear Cookies on Tor Toggle</li>
421
+
422
+  Fully clears all cookies on Tor toggle.
423
+  
424
+  <li>Store Non-Tor cookies in a protected jar</li>
425
+
426
+  This option stores your persistent Non-Tor cookies in a special cookie jar
427
+  file, in case you wish to preserve some cookies. Based on code contributed
428
+  by <a href="http://www.collinjackson.com/">Collin Jackson</a>. It is
429
+  compatible with third party extensions that you use to manage your Non-Tor
430
+  cookies. Your Tor cookies will be cleared on toggle, of course.
431
+
432
+  <li>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</li>
433
+
434
+  This option stores your persistent Tor and Non-Tor cookies 
435
+  separate cookie jar files. Note that it is a bad idea to keep Tor
436
+  cookies around for any length of time, as they can be retrieved by exit
437
+  nodes that inject spoofed forms into plaintext pages you fetch.
438
+
439
+  <li>Manage My Own Cookies (dangerous)</li>
440
+
441
+  This setting allows you to manage your own cookies with an alternate
442
+extension, such as <a href="https://addons.mozilla.org/firefox/addon/82">CookieCuller</a>. Note that this is particularly dangerous,
443
+since malicious exit nodes can spoof document elements that appear to be from
444
+sites you have preserved cookies for (and can then do things like fetch your
445
+entire gmail inbox, even if you were not using gmail or visiting any google
446
+pages at the time!).
447
+ 
448
+  <li>Do not write Tor/Non-Tor cookies to disk</li>
449
+
450
+  These settings prevent Firefox from writing any cookies to disk during the
451
+  corresponding Tor state. If cookie jars are enabled, those jars will
452
+  exist in memory only, and will be cleared when Firefox exits.
453
+
454
+  <li>Disable DOM Storage during Tor usage (crucial)</li>
455
+
456
+  Firefox has recently added the ability to store additional state and
457
+  identifiers in persistent tables, called <a
458
+  href="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</a>.
459
+  Obviously this can compromise your anonymity if stored content can be
460
+  fetched across Tor-state.
461
+
462
+  <li>Clear HTTP auth sessions (recommended)</li>
463
+
464
+  HTTP authentication credentials can be probed by exit nodes and used to both confirm that you visit a certain site that uses HTTP auth, and also impersonate you on this site. 
465
+
466
+  <li>Clear cookies on Tor/Non-Tor shutdown</li>
467
+
468
+  These settings install a shutdown handler to clear cookies on Tor
469
+and/or Non-Tor browser shutdown. It is independent of your Clear Private Data
470
+settings, and does in fact clear the corresponding cookie jars.
471
+
472
+  <li>Prevent session store from saving Tor-loaded tabs (recommended)</li>
473
+
474
+  This option augments the session store to prevent it from writing out
475
+  Tor-loaded tabs to disk. Unfortunately, this also disables your ability to 
476
+  undo closed tabs. The reason why this setting is recommended is because
477
+  after a session crash, your browser will be in an undefined Tor state, and
478
+  can potentially load a bunch of Tor tabs without Tor. The following option
479
+  is another alternative to protect against this.
480
+
481
+  <li>On normal startup, set state to: Tor, Non-Tor, Shutdown State</li>
482
+
483
+  This setting allows you to choose which Tor state you want the browser to
484
+  start in normally: Tor, Non-Tor, or whatever state the browser shut down in.
485
+
486
+  <li>On crash recovery or session restored startup, restore via: Tor, Non-Tor</li>
487
+
488
+  When Firefox crashes, the Tor state upon restart usually is completely
489
+  random, and depending on your choice for the above option, may load 
490
+  a bunch of tabs in the wrong state. This setting allows you to choose
491
+  which state the crashed session should always be restored in to.
492
+
493
+  <li>Prevent session store from saving Non-Tor/Tor-loaded tabs</li>
494
+  
495
+  These two settings allow you to control what the Firefox Session Store
496
+  writes to disk. Since the session store state is used to automatically
497
+  load websites after a crash or upgrade, it is advisable not to allow
498
+  Tor tabs to be written to disk, or they may get loaded in Non-Tor
499
+  after a crash (or the reverse, depending upon the crash recovery setting, 
500
+  of course).
501
+  
502
+  <li>Set user agent during Tor usage (crucial)</li>
503
+
504
+  User agent masking is done with the idea of making all Tor users appear
505
+uniform. A recent Firefox 2.0.0.4 Windows build was chosen to mimic for this
506
+string and supporting navigator.* properties, and this version will remain the
507
+same for all TorButton versions until such time as specific incompatibility
508
+issues are demonstrated. Uniformity of this value is obviously very important
509
+to anonymity. Note that for this option to have full effectiveness, the user
510
+must also allow Hook Dangerous Javascript ensure that the navigator.*
511
+properties are reset correctly.  The browser does not set some of them via the
512
+exposed user agent override preferences.
513
+
514
+  <li>Spoof US English Browser</li>
515
+
516
+This option causes Firefox to send http headers as if it were an English
517
+browser. Useful for internationalized users.
518
+
519
+  <li>Don't send referrer during Tor Usage</li>
520
+
521
+This option disables the referrer header, preventing sites from determining
522
+where you came from to visit them. This can break some sites, however. <a
523
+href="http://www.digg.com">Digg</a> in particular seemed to be broken by this.
524
+A more streamlined, less intrusive version of this option should be available
525
+eventually. In the meantime, <a
526
+href="https://addons.mozilla.org/en-US/firefox/addon/953">RefControl</a> can
527
+provide this functionality via a default option of <b>Forge</b>.
528
+</ul>
529
+
530
+
531
+</body>
532
+</html>
... ...
@@ -0,0 +1,173 @@
1
+<?xml version="1.0"?>
2
+
3
+<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
4
+     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
5
+
6
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}">
7
+    <em:updates>
8
+      <Seq>
9
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.14-alpha"/>
10
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.15-alpha"/>
11
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.16-alpha"/>
12
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.17-alpha"/>
13
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.18alpha"/>
14
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc1"/>
15
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc2"/>
16
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc3"/>
17
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc4"/>
18
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc5"/>
19
+        <li resource="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc6"/>
20
+      </Seq>
21
+    </em:updates>
22
+    
23
+
24
+    <!-- following two lines for Firefox 0.9.  Specify the most recent version here -->
25
+    <em:version>1.2.0rc6</em:version>
26
+    <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc6.xpi</em:updateLink>
27
+  </Description>
28
+
29
+  <!-- version 1.1.14 -->
30
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.14-alpha">
31
+    <em:version>1.1.14-alpha</em:version>
32
+    <em:targetApplication>
33
+      <Description>
34
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
35
+         <em:minVersion>0.9</em:minVersion>
36
+         <em:maxVersion>3.0b*</em:maxVersion>
37
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.1.14-alpha.xpi</em:updateLink>
38
+		 <em:updateHash>sha1:b316f9d84930ecf23b0797f93a6433334a4c38d5</em:updateHash>
39
+      </Description>
40
+    </em:targetApplication>
41
+  </Description>
42
+
43
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.15-alpha">
44
+    <em:version>1.1.15-alpha</em:version>
45
+    <em:targetApplication>
46
+      <Description>
47
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
48
+         <em:minVersion>0.9</em:minVersion>
49
+         <em:maxVersion>3.0b*</em:maxVersion>
50
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.1.15-alpha.xpi</em:updateLink>
51
+		 <em:updateHash>sha1:fa0d47c98d258ba904d828bea15b140ab438eb56</em:updateHash>
52
+      </Description>
53
+    </em:targetApplication>
54
+  </Description>
55
+
56
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.16-alpha">
57
+    <em:version>1.1.16-alpha</em:version>
58
+    <em:targetApplication>
59
+      <Description>
60
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
61
+         <em:minVersion>0.9</em:minVersion>
62
+         <em:maxVersion>3.0b*</em:maxVersion>
63
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.1.16-alpha.xpi</em:updateLink>
64
+		 <em:updateHash>sha1:f892dac7e5da8c63005f896c9aa1436e3f77ab4b</em:updateHash>
65
+      </Description>
66
+    </em:targetApplication>
67
+  </Description>
68
+
69
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.17-alpha">
70
+    <em:version>1.1.17-alpha</em:version>
71
+    <em:targetApplication>
72
+      <Description>
73
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
74
+         <em:minVersion>0.9</em:minVersion>
75
+         <em:maxVersion>3.0b*</em:maxVersion>
76
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.1.17-alpha.xpi</em:updateLink>
77
+		 <em:updateHash>sha1:93e17f955655eb31e5a6ff9f71dfde479a5b7a6d</em:updateHash>
78
+      </Description>
79
+    </em:targetApplication>
80
+  </Description>
81
+
82
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.1.18alpha">
83
+    <em:version>1.1.18alpha</em:version>
84
+    <em:targetApplication>
85
+      <Description>
86
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
87
+         <em:minVersion>0.9</em:minVersion>
88
+         <em:maxVersion>3.0b*</em:maxVersion>
89
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.1.18alpha.xpi</em:updateLink>
90
+		 <em:updateHash>sha1:6fdcebcb1e6cc694b45065c2b6df07ffb12ea164</em:updateHash>
91
+      </Description>
92
+    </em:targetApplication>
93
+  </Description>
94
+
95
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc1">
96
+    <em:version>1.2.0rc1</em:version>
97
+    <em:targetApplication>
98
+      <Description>
99
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
100
+         <em:minVersion>0.9</em:minVersion>
101
+         <em:maxVersion>3.1a1pre</em:maxVersion>
102
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc1.xpi</em:updateLink>
103
+		 <em:updateHash>sha1:8c8cb5e7e3844b8310151c5b56fb622134ea67f6</em:updateHash>
104
+      </Description>
105
+    </em:targetApplication>
106
+  </Description>
107
+
108
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc2">
109
+    <em:version>1.2.0rc2</em:version>
110
+    <em:targetApplication>
111
+      <Description>
112
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
113
+         <em:minVersion>0.9</em:minVersion>
114
+         <em:maxVersion>3.1a1pre</em:maxVersion>
115
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc2.xpi</em:updateLink>
116
+		 <em:updateHash>sha1:f0d6e121e2b0fbd4d1db7c3f333b8d7ab5c1d906</em:updateHash>
117
+      </Description>
118
+    </em:targetApplication>
119
+  </Description>
120
+
121
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc3">
122
+    <em:version>1.2.0rc3</em:version>
123
+    <em:targetApplication>
124
+      <Description>
125
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
126
+         <em:minVersion>0.9</em:minVersion>
127
+         <em:maxVersion>3.1a1pre</em:maxVersion>
128
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc3.xpi</em:updateLink>
129
+		 <em:updateHash>sha1:184294b480119bb7b943ede116345c52ee7772fc</em:updateHash>
130
+      </Description>
131
+    </em:targetApplication>
132
+  </Description>
133
+  
134
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc4">
135
+    <em:version>1.2.0rc4</em:version>
136
+    <em:targetApplication>
137
+      <Description>
138
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
139
+         <em:minVersion>0.9</em:minVersion>
140
+         <em:maxVersion>3.1a1pre</em:maxVersion>
141
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc4.xpi</em:updateLink>
142
+		 <em:updateHash>sha1:23df6a12c7140b5817338136da1cd7737412bbbb</em:updateHash>
143
+      </Description>
144
+    </em:targetApplication>
145
+  </Description>
146
+  
147
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc5">
148
+    <em:version>1.2.0rc5</em:version>
149
+    <em:targetApplication>
150
+      <Description>
151
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
152
+         <em:minVersion>0.9</em:minVersion>
153
+         <em:maxVersion>3.1a1pre</em:maxVersion>
154
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc5.xpi</em:updateLink>
155
+		 <em:updateHash>sha1:050925e2c02e61f2f0ceb4683600fc0c58a835bb</em:updateHash>
156
+      </Description>
157
+    </em:targetApplication>
158
+  </Description>
159
+
160
+  <Description about="urn:mozilla:extension:{e0204bd5-9d31-402b-a99d-a6aa8ffebdca}:1.2.0rc6">
161
+    <em:version>1.2.0rc6</em:version>
162
+    <em:targetApplication>
163
+      <Description>
164
+         <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
165
+         <em:minVersion>0.9</em:minVersion>
166
+         <em:maxVersion>3.1a1pre</em:maxVersion>
167
+         <em:updateLink>https://torbutton.torproject.org/dev/releases/torbutton-1.2.0rc6.xpi</em:updateLink>
168
+		 <em:updateHash>sha1:7f01c577641b6222781cd880c9825d6f50ff1cc4</em:updateHash>
169
+      </Description>
170
+    </em:targetApplication>
171
+  </Description>
172
+  
173
+</RDF>
0 174