Browse code

Inital move of torbutton website into website trunk.

Jacob Appelbaum authored on15/07/2008 05:48:33
Showing8 changed files
1 1
new file mode 100644
2 2
Binary files /dev/null and b/torbutton/design/MozillaBrownBag.odp differ
3 3
new file mode 100644
4 4
Binary files /dev/null and b/torbutton/design/MozillaBrownBag.pdf differ
5 5
new file mode 100644
... ...
@@ -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 2
new file mode 100644
... ...
@@ -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>