Browse code

move manpages to docs, move torbutton to docs, update rewrite rules for new paths.

Andrew Lewman authored on 24/04/2014 16:39:20
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,1456 +0,0 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Torbutton Design Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="Torbutton Design Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>Torbutton Design Documentation</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Perry</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">Apr 10 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2666923">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#components">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#hookedxpcom">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2690319">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2681735">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2702019">3.1. XUL Windows and Overlays</a></span></dt><dt><span class="sect2"><a href="#id2694797">3.2. Major Chrome Observers</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2696524">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2699452">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2697978">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2697015">4.3. Settings Update</a></span></dt><dt><span class="sect2"><a href="#preferences">4.4. Firefox preferences touched during Toggle</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2702702">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2704948">5.1. Proxy Settings</a></span></dt><dt><span class="sect2"><a href="#id2686645">5.2. Dynamic Content Settings</a></span></dt><dt><span class="sect2"><a href="#id2705261">5.3. History and Forms Settings</a></span></dt><dt><span class="sect2"><a href="#id2705577">5.4. Cache Settings</a></span></dt><dt><span class="sect2"><a href="#id2705686">5.5. Cookie and Auth Settings</a></span></dt><dt><span class="sect2"><a href="#id2705999">5.6. Startup Settings</a></span></dt><dt><span class="sect2"><a href="#id2706113">5.7. Shutdown Settings</a></span></dt><dt><span class="sect2"><a href="#id2706173">5.8. Header Settings</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#TorBrowserBugs">6.1. Tor Browser Bugs</a></span></dt><dt><span class="sect2"><a href="#ToggleModelBugs">6.2. Toggle Model Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id2707624">7.2. Multi-state testing</a></span></dt><dt><span class="sect2"><a href="#HackTorbutton">7.3. Active testing (aka How to Hack Torbutton)</a></span></dt></dl></dd></dl></div><div class="sect1" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2666923"></a>1. Introduction</h2></div></div></div><p>
4
-
5
-This document describes the goals, operation, and testing procedures of the
6
-Torbutton Firefox extension. It is current as of Torbutton 1.3.2.
7
-
8
-  </p><div class="sect2" title="1.1. Adversary Model"><div class="titlepage"><div><div><h3 class="title"><a id="adversary"></a>1.1. Adversary Model</h3></div></div></div><p>
9
-
10
-A Tor web browser adversary has a number of goals, capabilities, and attack
11
-types that can be used to guide us towards a set of requirements for the
12
-Torbutton extension. Let's start with the goals.
13
-
14
-   </p><div class="sect3" title="Adversary Goals"><div class="titlepage"><div><div><h4 class="title"><a id="adversarygoals"></a>Adversary Goals</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Bypassing proxy settings</strong></span><p>The adversary's primary goal is direct compromise and bypass of 
15
-Tor, causing the user to directly connect to an IP of the adversary's
16
-choosing.</p></li><li class="listitem"><span class="command"><strong>Correlation of Tor vs Non-Tor Activity</strong></span><p>If direct proxy bypass is not possible, the adversary will likely
17
-happily settle for the ability to correlate something a user did via Tor with
18
-their non-Tor activity. This can be done with cookies, cache identifiers,
19
-javascript events, and even CSS. Sometimes the fact that a user uses Tor may
20
-be enough for some authorities.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p>
21
-The adversary may also be interested in history disclosure: the ability to
22
-query a user's history to see if they have issued certain censored search
23
-queries, or visited censored sites.
24
-     </p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p>
25
-
26
-Location information such as timezone and locality can be useful for the
27
-adversary to determine if a user is in fact originating from one of the
28
-regions they are attempting to control, or to zero-in on the geographical
29
-location of a particular dissident or whistleblower.
30
-
31
-     </p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
32
-
33
-Anonymity set reduction is also useful in attempting to zero in on a
34
-particular individual. If the dissident or whistleblower is using a rare build
35
-of Firefox for an obscure operating system, this can be very useful
36
-information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>.
37
-
38
-     </p></li><li class="listitem"><span class="command"><strong>History records and other on-disk
39
-information</strong></span><p>
40
-In some cases, the adversary may opt for a heavy-handed approach, such as
41
-seizing the computers of all Tor users in an area (especially after narrowing
42
-the field by the above two pieces of information). History records and cache
43
-data are the primary goals here.
44
-     </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Positioning"><div class="titlepage"><div><div><h4 class="title"><a id="adversarypositioning"></a>Adversary Capabilities - Positioning</h4></div></div></div><p>
45
-The adversary can position themselves at a number of different locations in
46
-order to execute their attacks.
47
-    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
48
-The adversary can run exit nodes, or alternatively, they may control routers
49
-upstream of exit nodes. Both of these scenarios have been observed in the
50
-wild.
51
-     </p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>
52
-The adversary can also run websites, or more likely, they can contract out
53
-ad space from a number of different adservers and inject content that way. For
54
-some users, the adversary may be the adservers themselves. It is not
55
-inconceivable that adservers may try to subvert or reduce a user's anonymity 
56
-through Tor for marketing purposes.
57
-     </p></li><li class="listitem"><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p>
58
-The adversary can also inject malicious content at the user's upstream router
59
-when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
60
-activity.
61
-     </p></li><li class="listitem"><span class="command"><strong>Physical Access</strong></span><p>
62
-Some users face adversaries with intermittent or constant physical access.
63
-Users in Internet cafes, for example, face such a threat. In addition, in
64
-countries where simply using tools like Tor is illegal, users may face
65
-confiscation of their computer equipment for excessive Tor usage or just
66
-general suspicion.
67
-     </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Attacks"><div class="titlepage"><div><div><h4 class="title"><a id="attacks"></a>Adversary Capabilities - Attacks</h4></div></div></div><p>
68
-
69
-The adversary can perform the following attacks from a number of different 
70
-positions to accomplish various aspects of their goals. It should be noted
71
-that many of these attacks (especially those involving IP address leakage) are
72
-often performed by accident by websites that simply have Javascript, dynamic 
73
-CSS elements, and plugins. Others are performed by adservers seeking to
74
-correlate users' activity across different IP addresses, and still others are
75
-performed by malicious agents on the Tor network and at national firewalls.
76
-
77
-    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Inserting Javascript</strong></span><p>
78
-If not properly disabled, Javascript event handlers and timers
79
-can cause the browser to perform network activity after Tor has been disabled,
80
-thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
81
-a user's non-Tor IP address. Javascript
82
-also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure attacks</a>:
83
-to query the history via the different attributes of 'visited' links to search
84
-for particular Google queries, sites, or even to <a class="ulink" href="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/" target="_top">profile
85
-users based on gender and other classifications</a>. Finally,
86
-Javascript can be used to query the user's timezone via the
87
-<code class="function">Date()</code> object, and to reduce the anonymity set by querying
88
-the <code class="function">navigator</code> object for operating system, CPU, locale, 
89
-and user agent information.
90
-     </p></li><li class="listitem"><span class="command"><strong>Inserting Plugins</strong></span><p>
91
-
92
-Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
93
-capable of performing network activity that the author has
94
-investigated is also capable of performing network activity independent of
95
-browser proxy settings - and often independent of its own proxy settings.
96
-Sites that have plugin content don't even have to be malicious to obtain a
97
-user's
98
-Non-Tor IP (it usually leaks by itself), though <a class="ulink" href="http://decloak.net" target="_top">plenty of active
99
-exploits</a> are possible as well. In addition, plugins can be used to store unique identifiers that are more
100
-difficult to clear than standard cookies. 
101
-<a class="ulink" href="http://epic.org/privacy/cookies/flash.html" target="_top">Flash-based
102
-cookies</a> fall into this category, but there are likely numerous other
103
-examples.
104
-
105
-     </p></li><li class="listitem"><span class="command"><strong>Inserting CSS</strong></span><p>
106
-
107
-CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
108
-Non-Tor IP address, via the usage of
109
-<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">CSS
110
-popups</a> - essentially CSS-based event handlers that fetch content via
111
-CSS's onmouseover attribute. If these popups are allowed to perform network
112
-activity in a different Tor state than they were loaded in, they can easily
113
-correlate Tor and Non-Tor activity and reveal a user's IP address. In
114
-addition, CSS can also be used without Javascript to perform <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only history disclosure
115
-attacks</a>.
116
-     </p></li><li class="listitem"><span class="command"><strong>Read and insert cookies</strong></span><p>
117
-
118
-An adversary in a position to perform MITM content alteration can inject
119
-document content elements to both read and inject cookies for
120
-arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
121
-sort of <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html" target="_top">active
122
-sidejacking</a>.
123
-
124
-     </p></li><li class="listitem"><span class="command"><strong>Create arbitrary cached content</strong></span><p>
125
-
126
-Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
127
-identifiers</a>. Since by default the cache has no same-origin policy,
128
-these identifiers can be read by any domain, making them an ideal target for
129
-adserver-class adversaries.
130
-
131
-     </p></li><li class="listitem"><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser
132
-attributes</strong></span><p>
133
-
134
-There is an absurd amount of information available to websites via attributes
135
-of the browser. This information can be used to reduce anonymity set, or even
136
-<a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">uniquely
137
-fingerprint individual users</a>. </p><p>
138
-For illustration, let's perform a
139
-back-of-the-envelope calculation on the number of anonymity sets for just the
140
-resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and
141
-<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
142
-objects.
143
-
144
-
145
-
146
-Browser window resolution information provides something like
147
-(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
148
-information contributes about another factor of 5 (for about 5 resolutions in
149
-typical use). In addition, the dimensions and position of the desktop taskbar
150
-are available, which can reveal hints on OS information. This boosts the count
151
-by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
152
-and Gnome, and None). Subtracting the browser content window
153
-size from the browser outer window size provide yet more information.
154
-Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
155
-2<sup>3</sup>=8). Interface effects such as title bar font size
156
-and window manager settings gives a factor of about 9 (say 3 common font sizes
157
-for the title bar and 3 common sizes for browser GUI element fonts).
158
-Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
159
-2<sup>29</sup>, or a 29 bit identifier based on resolution
160
-information alone. </p><p>
161
-
162
-Of course, this space is non-uniform in user density and prone to incremental
163
-changes. The <a class="ulink" href="https://wiki.mozilla.org/Fingerprinting#Data" target="_top">Panopticlick study
164
-done</a> by the EFF attempts to measure the actual entropy - the number of
165
-identifying bits of information encoded in browser properties.  Their result
166
-data is definitely useful, and the metric is probably the appropriate one for
167
-determining how identifying a particular browser property is. However, some
168
-quirks of their study means that they do not extract as much information as
169
-they could from display information: they only use desktop resolution (which
170
-Torbutton reports as the window resolution) and do not attempt to infer the
171
-size of toolbars.
172
-
173
-</p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or
174
-OS</strong></span><p>
175
-Last, but definitely not least, the adversary can exploit either general 
176
-browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
177
-install malware and surveillance software. An adversary with physical access
178
-can perform similar actions. Regrettably, this last attack capability is
179
-outside of Torbutton's ability to defend against, but it is worth mentioning
180
-for completeness.
181
-     </p></li></ol></div></div></div><div class="sect2" title="1.2. Torbutton Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="requirements"></a>1.2. Torbutton Requirements</h3></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
182
-
183
-Since many settings satisfy multiple requirements, this design document is
184
-organized primarily by Torbutton components and settings. However, if you are
185
-the type that would rather read the document from the requirements
186
-perspective, it is in fact possible to search for each of the following
187
-requirement phrases in the text to find the relevant features that help meet
188
-that requirement.
189
-
190
-</div><p>
191
-
192
-From the above Adversary Model, a number of requirements become clear. 
193
-
194
-   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a id="proxy"></a><span class="command"><strong>Proxy Obedience</strong></span><p>The browser
195
-MUST NOT bypass Tor proxy settings for any content.</p></li><li class="listitem"><a id="state"></a><span class="command"><strong>State Separation</strong></span><p>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
196
- one Tor state MUST NOT be accessible via the network in
197
- another Tor state.</p></li><li class="listitem"><a id="isolation"></a><span class="command"><strong>Network Isolation</strong></span><p>Pages MUST NOT perform any network activity in a Tor state different
198
- from the state they were originally loaded in.</p><p>Note that this requirement is
199
-being de-emphasized due to the coming shift to supporting only the Tor Browser
200
-Bundles, which do not support a Toggle operation.</p></li><li class="listitem"><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>With
201
-the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
202
-users whose network fingerprint does not obviously betray the fact that they
203
-are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
204
-reveal its presence while Tor is disabled.
205
-</p><p>Note that this requirement is
206
-being de-emphasized due to the coming shift to supporting only the Tor Browser
207
-Bundles, which do not support a Toggle operation.</p></li><li class="listitem"><a id="disk"></a><span class="command"><strong>Disk Avoidance</strong></span><p>The browser SHOULD NOT write any Tor-related state to disk, or store it
208
- in memory beyond the duration of one Tor toggle.</p></li><li class="listitem"><a id="location"></a><span class="command"><strong>Location Neutrality</strong></span><p>The browser SHOULD NOT leak location-specific information, such as
209
- timezone or locale via Tor.</p></li><li class="listitem"><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
210
-Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity
211
-set reducing or fingerprinting information
212
- (such as user agent, extension presence, and resolution information)
213
-automatically via Tor. The assessment of the attacks above should make it clear
214
-that anonymity set reduction is a very powerful method of tracking and
215
-eventually identifying anonymous users.
216
-</p></li><li class="listitem"><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser
217
-SHOULD NOT perform unauthenticated updates or upgrades via Tor.</p></li><li class="listitem"><a id="interoperate"></a><span class="command"><strong>Interoperability</strong></span><p>Torbutton SHOULD interoperate with third-party proxy switchers that
218
- enable the user to switch between a number of different proxies. It MUST
219
- provide full Tor protection in the event a third-party proxy switcher has
220
- enabled the Tor proxy settings.</p></li></ol></div></div><div class="sect2" title="1.3. Extension Layout"><div class="titlepage"><div><div><h3 class="title"><a id="layout"></a>1.3. Extension Layout</h3></div></div></div><p>Firefox extensions consist of two main categories of code: 'Components' and
221
-'Chrome'. Components are a fancy name for classes that implement a given
222
-interface or interfaces. In Firefox, components <a class="ulink" href="https://developer.mozilla.org/en/XPCOM" target="_top">can be
223
-written</a> in C++,
224
-Javascript, or a mixture of both. Components have two identifiers: their
225
-'<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005" target="_top">Contract
226
-ID</a>' (a human readable path-like string), and their '<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329" target="_top">Class
227
-ID</a>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
228
-'Interface ID'. It is possible to 'hook' system components - to reimplement
229
-their interface members with your own wrappers - but only if the rest of the
230
-browser refers to the component by its Contract ID. If the browser refers to
231
-the component by Class ID, it bypasses your hooks in that use case.
232
-Technically, it may be possible to hook Class IDs by unregistering the
233
-original component, and then re-registering your own, but this relies on
234
-obsolete and deprecated interfaces and has proved to be less than
235
-stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window.
236
-Extensions are allowed to create 'overlays' that are 'bound' to existing XML
237
-window definitions, or they can create their own windows. The DTD for this XML
238
-is called <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XUL</a>.</p></div></div><div class="sect1" title="2. Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="components"></a>2. Components</h2></div></div></div><p>
239
-
240
-Torbutton installs components for two purposes: hooking existing components to
241
-reimplement their interfaces; and creating new components that provide
242
-services to other pieces of the extension.
243
-
244
-  </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="hookedxpcom"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some
245
-of its own standalone components as well.  Let's discuss the hooked components
246
-first.</p><div class="sect3" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="appblocker"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1" target="_top">@mozilla.org/uriloader/external-protocol-service;1
247
-</a>, <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1" target="_top">@mozilla.org/uriloader/external-helper-app-service;1</a>,
248
-and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1" target="_top">@mozilla.org/mime;1</a>
249
-- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js" target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>
250
-Due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a> allowing Firefox 3.x to automatically launch some
251
-applications without user intervention, Torbutton had to wrap the three
252
-components involved in launching external applications to provide user
253
-confirmation before doing so while Tor is enabled. Since external applications
254
-do not obey proxy settings, they can be manipulated to automatically connect
255
-back to arbitrary servers outside of Tor with no user intervention. Fixing
256
-this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy
257
-Obedience</a> Requirement.
258
- </p></div><div class="sect3" title="@mozilla.org/browser/global-history;2 - components/ignore-history.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2696239"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2" target="_top">@mozilla.org/browser/global-history;2</a>
259
-- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js" target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin Jackson</a> as a method for defeating
260
-CSS and Javascript-based methods of history disclosure. The global-history
261
-component is what is used by Firefox to determine if a link was visited or not
262
-(to apply the appropriate style to the link). By hooking the <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29" target="_top">isVisited</a>
263
-and <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29" target="_top">addURI</a>
264
-methods, Torbutton is able to selectively prevent history items from being
265
-added or being displayed as visited, depending on the Tor state and the user's
266
-preferences.
267
-</p><p>
268
-This component helps satisfy the <a class="link" href="#state">State Separation</a>
269
-and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton. It
270
-is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
271
-of the <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">built-in
272
-history protections</a>.
273
-</p></div><div class="sect3" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js"><div class="titlepage"><div><div><h4 class="title"><a id="livemarks"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2" target="_top">@mozilla.org/browser/livemark-service;2</a>
274
-- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js" target="_top">components/block-livemarks.js</a></h4></div></div></div><p>
275
-
276
-The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html" target="_top">livemark</a> service
277
-is started by a timer that runs 5 seconds after Firefox
278
-startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
279
-disable it. We must wrap the component to prevent this start() call from
280
-firing in the event the browser starts in Tor mode.
281
-
282
-</p><p>
283
-This component helps satisfy the <a class="link" href="#isolation">Network
284
-Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
285
-Preservation</a> requirements.
286
-</p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2690319"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the
287
-extension. These components do not hook any interfaces, nor are they used
288
-anywhere besides Torbutton itself.</p><div class="sect3" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js"><div class="titlepage"><div><div><h4 class="title"><a id="cookiejar"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2
289
-- components/cookie-jar-selector.js</a></h4></div></div></div><p>The cookie jar selector (also based on code from <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin
290
-Jackson</a>) is used by the Torbutton chrome to switch between
291
-Tor and Non-Tor cookies. It stores an XML representation of the current
292
-cookie state in memory and/or on disk. When Tor is toggled, it syncs the
293
-current cookies to this XML store, and then loads the cookies for the other
294
-state from the XML store.
295
-</p><p>
296
-This component helps to address the <a class="link" href="#state">State
297
-Isolation</a> requirement of Torbutton.
298
-</p></div><div class="sect3" title="@torproject.org/torbutton-logger;1 - components/torbutton-logger.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2683534"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1
299
-- components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
300
-logging messages to either Firefox stderr
301
-(<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
302
-(<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if
303
-available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
304
-change the loglevel on the fly by changing
305
-<span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
306
-</p></div><div class="sect3" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1
307
-- components/window-mapper.js</a></h4></div></div></div><p>Torbutton tags Firefox <a class="ulink" href="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes" target="_top">tabs</a> with a special variable that indicates the Tor
308
-state the tab was most recently used under to fetch a page. The problem is
309
-that for many Firefox events, it is not possible to determine the tab that is
310
-actually receiving the event. The Torbutton window mapper allows the Torbutton
311
-chrome and other components to look up a <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
312
-tab</a> for a given <a class="ulink" href="https://developer.mozilla.org/en/nsIDOMWindow" target="_top">HTML content
313
-window</a>. It does this by traversing all windows and all browsers, until it
314
-finds the browser with the requested <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow" target="_top">contentWindow</a> element. Since the content policy
315
-and page loading in general can generate hundreds of these lookups, this
316
-result is cached inside the component.
317
-</p></div><div class="sect3" title="@torproject.org/crash-observer;1"><div class="titlepage"><div><div><h4 class="title"><a id="crashobserver"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js" target="_top">@torproject.org/crash-observer;1</a></h4></div></div></div><p>
318
-
319
-This component detects when Firefox crashes by altering Firefox prefs during
320
-runtime and checking for the same values at startup. It <a class="ulink" href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()" target="_top">synchronizes
321
-the preference service</a> to ensure the altered prefs are written to disk
322
-immediately.
323
-
324
-  </p></div><div class="sect3" title="@torproject.org/torbutton-ss-blocker;1"><div class="titlepage"><div><div><h4 class="title"><a id="tbsessionstore"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js" target="_top">@torproject.org/torbutton-ss-blocker;1</a></h4></div></div></div><p>
325
-
326
-This component subscribes to the Firefox <a class="ulink" href="https://developer.mozilla.org/en/Observer_Notifications#Session_Store" target="_top">sessionstore-state-write</a>
327
-observer event to filter out URLs from tabs loaded during Tor, to prevent them
328
-from being written to disk. To do this, it checks the
329
-<span class="command"><strong>__tb_tor_fetched</strong></span> tag of tab objects before writing them out. If
330
-the tag is from a blocked Tor state, the tab is not written to disk.  This is
331
-a rather expensive operation that involves potentially very large JSON
332
-evaluations and object tree traversals, but it preferable to replacing the
333
-Firefox session store with our own implementation, which is what was done in
334
-years past.
335
-
336
-  </p></div><div class="sect3" title="@torproject.org/torRefSpoofer;1"><div class="titlepage"><div><div><h4 class="title"><a id="refspoofer"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js" target="_top">@torproject.org/torRefSpoofer;1</a></h4></div></div></div><p>
337
-This component handles optional referer spoofing for Torbutton. It implements a
338
-form of "smart" referer spoofing using <a class="ulink" href="https://developer.mozilla.org/en/Setting_HTTP_request_headers" target="_top">http-on-modify-request</a>
339
-to modify the Referer header. The code sends the default browser referer
340
-header only if the destination domain is a suffix of the source, or if the
341
-source is a suffix of the destination. Otherwise, it sends no referer. This
342
-strange suffix logic is used as a heuristic: some rare sites on the web block
343
-requests without proper referer headers, and this logic is an attempt to cater
344
-to them. Unfortunately, it may not be enough. For example, google.fr will not
345
-send a referer to google.com using this logic. Hence, it is off by default.
346
- </p></div><div class="sect3" title="@torproject.org/cssblocker;1 - components/cssblocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
347
-- components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is
348
-toggled, Javascript is disabled, and pages are instructed to stop loading.
349
-However, CSS is still able to perform network operations by loading styles for
350
-onmouseover events and other operations. In addition, favicons can still be
351
-loaded by the browser. The cssblocker component prevents this by implementing
352
-and registering an <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy" target="_top">nsIContentPolicy</a>.
353
-When an nsIContentPolicy is registered, Firefox checks every attempted network
354
-request against its <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()" target="_top">shouldLoad</a>
355
-member function to determine if the load should proceed. In Torbutton's case,
356
-the content policy looks up the appropriate browser tab using the <a class="link" href="#windowmapper" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js">window mapper</a>,
357
-and checks that tab's load tag against the current Tor state. If the tab was
358
-loaded in a different state than the current state, the fetch is denied.
359
-Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#isolation">Network
360
-Isolation</a> requirements of Torbutton.
361
-
362
-<p>In addition, the content policy also blocks website javascript from
363
-<a class="ulink" href="http://webdevwonders.com/detecting-firefox-add-ons/" target="_top">querying for
364
-versions and existence of extension chrome</a> while Tor is enabled, and
365
-also masks the presence of Torbutton to website javascript while Tor is
366
-disabled. </p><p>
367
-
368
-Finally, some of the work that logically belongs to the content policy is
369
-instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
370
-<span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of
371
-Firefox 3 favicon loads, popups, and full page plugins, which for whatever
372
-reason are not passed to the Firefox content policy itself (see Firefox Bugs 
373
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 
374
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
375
-
376
-</p><p>
377
-
378
-This helps to fulfill both the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirements of
379
-Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2681735"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
380
-located. </p><div class="sect2" title="3.1. XUL Windows and Overlays"><div class="titlepage"><div><div><h3 class="title"><a id="id2702019"></a>3.1. XUL Windows and Overlays</h3></div></div></div><p>
381
-Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XML file</a>, with zero or more Javascript
382
-files attached. The scope of these Javascript files is their containing
383
-window. XUL files that add new elements and script to existing Firefox windows
384
-are called overlays.</p><div class="sect3" title="Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h4 class="title"><a id="browseroverlay"></a>Browser Overlay - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h4></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
385
-bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
386
-It contains event handlers for preference update, shutdown, upgrade, and
387
-location change events.</p></div><div class="sect3" title="Preferences Window - preferences.xul"><div class="titlepage"><div><div><h4 class="title"><a id="id2704559"></a>Preferences Window - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h4></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
388
-handlers located in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect3" title="Other Windows"><div class="titlepage"><div><div><h4 class="title"><a id="id2669673"></a>Other Windows</h4></div></div></div><p>There are additional windows that describe popups for right clicking on
389
-the status bar, the toolbutton, and the about page.</p></div></div><div class="sect2" title="3.2. Major Chrome Observers"><div class="titlepage"><div><div><h3 class="title"><a id="id2694797"></a>3.2. Major Chrome Observers</h3></div></div></div><p>
390
-In addition to the <a class="link" href="#components" title="2. Components">components described
391
-above</a>, Torbutton also instantiates several observers in the browser
392
-overlay window. These mostly grew due to scoping convenience, and many should
393
-probably be relocated into their own components.
394
- </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>torbutton_window_pref_observer</strong></span><p>
395
-This is an observer that listens for Torbutton state changes, for the purposes
396
-of updating the Torbutton button graphic as the Tor state changes.
397
-    </p></li><li class="listitem"><span class="command"><strong>torbutton_unique_pref_observer</strong></span><p>
398
-
399
-This is an observer that only runs in one window, called the main window. It
400
-listens for changes to all of the Torbutton preferences, as well as Torbutton
401
-controlled Firefox preferences. It is what carries out the toggle path when
402
-the proxy settings change. When the main window is closed, the
403
-torbutton_close_window event handler runs to dub a new window the "main
404
-window".
405
-
406
-    </p></li><li class="listitem"><span class="command"><strong>tbHistoryListener</strong></span><p>
407
-The tbHistoryListener exists to prevent client window Javascript from
408
-interacting with window.history to forcibly navigate a user to a tab session
409
-history entry from a different Tor state. It also expunges the window.history
410
-entries during toggle. This listener helps Torbutton
411
-satisfy the <a class="link" href="#isolation">Network Isolation</a> requirement as
412
-well as the <a class="link" href="#state">State Separation</a> requirement.
413
-
414
-    </p></li><li class="listitem"><span class="command"><strong>torbutton_http_observer</strong></span><p>
415
-
416
-The torbutton_http_observer performs some of the work that logically belongs
417
-to the content policy. This handles blocking of
418
-Firefox 3 favicon loads, which for whatever
419
-reason are not passed to the Firefox content policy itself (see Firefox Bugs
420
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and
421
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
422
-
423
-    </p><p>
424
-The observer is also responsible for redirecting users to alternate
425
-search engines when Google presents them with a Captcha, as well as copying
426
-Google Captcha-related cookies between international Google domains.
427
-    </p></li><li class="listitem"><span class="command"><strong>torbutton_proxyservice</strong></span><p>
428
-The Torbutton proxy service handles redirecting Torbutton-related update
429
-checks on addons.mozilla.org through Tor. This is done to help satisfy the
430
-<a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
431
-    </p></li><li class="listitem"><span class="command"><strong>torbutton_weblistener</strong></span><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
432
-change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress" target="_top">webprogress
433
-listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most
434
-important parts of the chrome from a security standpoint. It is a <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
435
-listener</a> that handles receiving an event every time a page load or
436
-iframe load occurs. This class eventually calls down to
437
-<code class="function">torbutton_update_tags()</code> and
438
-<code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load
439
-state tags, plugin permissions, and install the Javascript hooks to hook the
440
-<a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
441
-object to obfuscate browser and desktop resolution information.
442
-
443
-</p></li></ol></div></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2696524"></a>4. Toggle Code Path</h2></div></div></div><p>
444
-
445
-The act of toggling is connected to <code class="function">torbutton_toggle()</code>
446
-via the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
447
-and <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul" target="_top">popup.xul</a>
448
-overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 
449
-
450
-</p><p>
451
-
452
-Toggling is a 3 stage process: Button Click, Proxy Update, and
453
-Settings Update. These stages are reflected in the prefs
454
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
455
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
456
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
457
-three stage preference update is to ensure immediate enforcement of <a class="link" href="#isolation">Network Isolation</a> via the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. Since the content window
458
-javascript runs on a different thread than the chrome javascript, it is
459
-important to properly convey the stages to the content policy to avoid race
460
-conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
461
-409737</a> unfixed. The content policy does not allow any network activity
462
-whatsoever during this three stage transition.
463
-
464
- </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2699452"></a>4.1. Button Click</h3></div></div></div><p>
465
-
466
-This is the first step in the toggling process. When the user clicks the
467
-toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
468
-called. This function checks the current Tor status by comparing the current
469
-proxy settings to the selected Tor settings, and then sets the proxy settings
470
-to the opposite state, and sets the pref
471
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
472
-It is this proxy pref update that gives notification via the <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">pref
473
-observer</a>
474
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
475
-toggle.
476
-
477
-  </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2697978"></a>4.2. Proxy Update</h3></div></div></div><p>
478
-
479
-When Torbutton receives any proxy change notifications via its
480
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
481
-<code class="function">torbutton_set_status()</code> which checks against the Tor
482
-settings to see if the Tor proxy settings match the current settings. If so,
483
-it calls <code class="function">torbutton_update_status()</code>, which determines if
484
-the Tor state has actually changed, and sets
485
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
486
-state value, and ensures that
487
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
488
-value. This is decoupled from the button click functionality via the pref
489
-observer so that other addons (such as SwitchProxy) can switch the proxy
490
-settings between multiple proxies.
491
-
492
-  </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2697015"></a>4.3. Settings Update</h3></div></div></div><p>
493
-
494
-The next stage is also handled by
495
-<code class="function">torbutton_update_status()</code>. This function sets scores of
496
-Firefox preferences, saving the original values to prefs under
497
-<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the <a class="link" href="#cookiejar" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js">cookie jarring</a>, state clearing (such as window.name
498
-and DOM storage), and <a class="link" href="#preferences" title="4.4. Firefox preferences touched during Toggle">preference
499
-toggling</a>. At the
500
-end of its work, it sets
501
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
502
-completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
503
-
504
-  </p></div><div class="sect2" title="4.4. Firefox preferences touched during Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="preferences"></a>4.4. Firefox preferences touched during Toggle</h3></div></div></div><p>
505
-There are also a number of Firefox preferences set in
506
-<code class="function">torbutton_update_status()</code> that aren't governed by any
507
-Torbutton setting. These are:
508
-</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Network.security.ports.banned" target="_top">network.security.ports.banned</a><p>
509
-Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
510
-reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) to the list
511
-of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
512
-and the Tor control port, respectively. This is set for both Tor and Non-Tor
513
-usage, and prevents websites from attempting to do http fetches from these
514
-ports to see if they are open, which addresses the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
515
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings" target="_top">browser.send_pings</a><p>
516
-This setting is currently always disabled. If anyone ever complains saying
517
-that they *want* their browser to be able to send ping notifications to a
518
-page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
519
-my breath. I haven't checked if the content policy is called for pings, but if
520
-not, this setting helps with meeting the <a class="link" href="#isolation">Network
521
-Isolation</a> requirement.
522
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups" target="_top">browser.safebrowsing.remoteLookups</a><p>
523
-Likewise for this setting. I find it hard to imagine anyone who wants to ask
524
-Google in real time if each URL they visit is safe, especially when the list
525
-of unsafe URLs is downloaded anyway. This helps fulfill the <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire
526
-browsing history from ending up on Google's disks.
527
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled" target="_top">browser.safebrowsing.enabled</a><p>
528
-Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387" target="_top">unauthenticated
529
-updates under Firefox 2</a>, so it is disabled during Tor usage. 
530
-This helps fulfill the <a class="link" href="#updates">Update
531
-Safety</a> requirement. Firefox 3 has the fix for that bug, and so
532
-safebrowsing updates are enabled during Tor usage.
533
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29" target="_top">network.protocol-handler.warn-external.(protocol)</a><p>
534
-If Tor is enabled, we need to prevent random external applications from
535
-launching without at least warning the user. This group of settings only
536
-partially accomplishes this, however. Applications can still be launched via
537
-plugins. The mechanisms for handling this are described under the "Disable
538
-Plugins During Tor Usage" preference. This helps fulfill the <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external
539
-applications from accessing network resources at the command of Tor-fetched
540
-pages. Unfortunately, due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a>
541
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a>,
542
-these prefs are no longer obeyed. They are set still anyway out of respect for
543
-the dead.
544
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo" target="_top">browser.sessionstore.max_tabs_undo</a><p>
545
-
546
-To help satisfy the Torbutton <a class="link" href="#state">State Separation</a>
547
-and <a class="link" href="#isolation">Network Isolation</a> requirements,
548
-Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
549
-"Undo Close" operations from accidentally restoring tabs from a different Tor
550
-State. This purge is accomplished by setting this preference to 0 and then
551
-restoring it to the previous user value upon toggle.
552
-
553
-   </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span> or <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto" target="_top">nsIDOMCrypto::logout()</a><p>
554
-TLS Session IDs can persist for an indefinite duration, providing an
555
-identifier that is sent to TLS sites that can be used to link activity. This
556
-is particularly troublesome now that we have certificate verification in place
557
-in Firefox 3: The OCSP server can use this Session ID to build a history of
558
-TLS sites someone visits, and also correlate their activity as users move from
559
-network to network (such as home to work to coffee shop, etc), inside and
560
-outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we call the logout()
561
-function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
562
-to toggling
563
-<span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
564
-cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>.
565
-   </p></li><li class="listitem"><span class="command"><strong>security.OCSP.enabled</strong></span><p>
566
-Similarly, we toggle <span class="command"><strong>security.OCSP.enabled</strong></span>, which clears the OCSP certificate
567
-validation cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>.
568
-In this way, exit nodes will not be able to fingerprint you
569
-based the fact that non-Tor OCSP lookups were obviously previously cached.
570
-To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>,
571
-   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users" target="_top">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</a></strong></span><p>
572
-We permanently disable addon usage statistic reporting to the
573
-addons.mozilla.org statistics engine. These statistics send version
574
-information about Torbutton users via non-Tor, allowing their Tor use to be
575
-uncovered. Disabling this reporting helps Torbutton to satisfy its <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
576
-
577
-  </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://www.mozilla.com/en-US/firefox/geolocation/" target="_top">geo.enabled</a></strong></span><p>
578
-
579
-Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
580
-is enabled. This helps Torbutton maintain its
581
-<a class="link" href="#location">Location Neutrality</a> requirement.
582
-While Firefox does prompt before divulging geolocational information,
583
-the assumption is that Tor users will never want to give their
584
-location away during Tor usage, and even allowing websites to prompt
585
-them to do so will only cause confusion and accidents to happen. Moreover,
586
-just because users may approve a site to know their location in non-Tor mode
587
-does not mean they want it divulged during Tor mode.
588
-
589
-   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Browser.zoom.siteSpecific" target="_top">browser.zoom.siteSpecific</a></strong></span><p>
590
-
591
-Firefox actually remembers your zoom settings for certain sites. CSS
592
-and Javascript rule can use this to recognize previous visitors to a site.
593
-This helps Torbutton fulfill its <a class="link" href="#state">State Separation</a>
594
-requirement.
595
-
596
-   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="https://developer.mozilla.org/en/controlling_dns_prefetching" target="_top">network.dns.disablePrefetch</a></strong></span><p>
597
-
598
-Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
599
-links on a page to decrease page load latency. While Firefox does typically
600
-disable this behavior when proxies are enabled, we set this pref for added
601
-safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
602
-their links prefetched after a toggle to Non-Tor mode occurs,
603
-we also set the docShell attribute
604
-<a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell" target="_top">
605
-allowDNSPrefetch</a> to false on Tor loaded tabs. This happens in the same
606
-positions in the code as those for disabling plugins via the allowPlugins
607
-docShell attribute. This helps Torbutton fulfill its <a class="link" href="#isolation">Network Isolation</a> requirement.
608
-
609
-   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Browser.cache.offline.enable" target="_top">browser.cache.offline.enable</a></strong></span><p>
610
-
611
-Firefox has the ability to store web applications in a special cache to allow
612
-them to continue to operate while the user is offline. Since this subsystem
613
-is actually different than the normal disk cache, it must be dealt with
614
-separately. Thus, Torbutton sets this preference to false whenever Tor is
615
-enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk
616
-Avoidance</a> and <a class="link" href="#state">State Separation</a>
617
-requirements.
618
-
619
-   </p></li></ol></div></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2702702"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each
620
-option is presented as the string from the preferences window, a summary, the
621
-preferences it touches, and the effect this has on the components, chrome, and
622
-browser properties.</p><div class="sect2" title="5.1. Proxy Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2704948"></a>5.1. Proxy Settings</h3></div></div></div><div class="sect3" title="Test Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2683681"></a>Test Settings</h4></div></div></div><p>
623
-This button under the Proxy Settings tab provides a way to verify that the 
624
-proxy settings are correct, and actually do route through the Tor network. It
625
-performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a>
626
-for <a class="ulink" href="https://check.torproject.org/?TorButton=True" target="_top">https://check.torproject.org/?Torbutton=True</a>.
627
-This is a special page that returns very simple, yet well-formed XHTML that
628
-Torbutton can easily inspect for a hidden link with an id of
629
-<span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
630
-or <span class="command"><strong>failure</strong></span> to indicate if the
631
-user hit the page from a Tor IP, a non-Tor IP. This check is handled in
632
-<code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>.
633
-Presenting the results to the user is handled by the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences
634
-window</a>
635
-callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">preferences.js</a>.  
636
-
637
-  </p></div></div><div class="sect2" title="5.2. Dynamic Content Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2686645"></a>5.2. Dynamic Content Settings</h3></div></div></div><div class="sect3" title="Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="plugins"></a>Disable plugins on Tor Usage (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html" target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html" target="_top">local IP
638
-address</a> and report it back to the
639
-remote site. They can also <a class="ulink" href="http://decloak.net" target="_top">bypass proxy settings</a> and directly connect to a
640
-remote site without Tor. Every browser plugin we have tested with Firefox has
641
-some form of network capability, and every one ignores proxy settings or worse - only
642
-partially obeys them. This includes but is not limited to:
643
-QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
644
-Flash. 
645
-
646
- </p><p>
647
-Enabling this preference causes the above mentioned Torbutton chrome web progress
648
- listener <span class="command"><strong>torbutton_weblistener</strong></span> to disable Java via <span class="command"><strong>security.enable_java</strong></span> and to disable
649
- plugins via the browser <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell" target="_top">docShell</a>
650
- attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is
651
- created (<code class="function">torbutton_tag_new_browser()</code>), every time a web
652
-load
653
-event occurs
654
- (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
655
- (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
656
- prevented from loading by the content policy in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is
657
- enabled and this option is set.
658
- </p><p>All of this turns out to be insufficient if the user directly clicks
659
-on a plugin-handled mime-type. <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">In this case</a>,
660
-the browser decides that maybe it should ignore all these other settings and
661
-load the plugin anyways, because maybe the user really did want to load it
662
-(never mind this same load-style could happen automatically  with meta-refresh
663
-or any number of other ways..). To handle these cases, Torbutton stores a list
664
-of plugin-handled mime-types, and sets the pref
665
-<span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> to this list.
666
-Additionally, (since nothing can be assumed when relying on Firefox
667
-preferences and internals) if it detects a load of one of them from the web
668
-progress listener, it cancels the request, tells the associated DOMWindow to
669
-stop loading, clears the document, AND throws an exception. Anything short of
670
-all this and the plugin managed to find some way to load.
671
- </p><p>
672
- All this could be avoided, of course, if Firefox would either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">obey
673
- allowPlugins</a> for directly visited URLs, or notify its content policy for such
674
- loads either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">via</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">shouldProcess</a> or shouldLoad. The fact that it does not is
675
- not very encouraging.
676
- </p><p>
677
-
678
-Since most plugins completely ignore browser proxy settings, the actions
679
-performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
680
-
681
- </p></div><div class="sect3" title="Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2688604"></a>Isolate Dynamic Content to Tor State (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> content policy
682
-mentioned above, and causes it to block content load attempts in pages an
683
-opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
684
-tabs</a> are tagged
685
-with a <span class="command"><strong>__tb_load_state</strong></span> member in
686
-<code class="function">torbutton_update_tags()</code> and this
687
-value is compared against the current tor state in the content policy.</p><p>It also kills all Javascript in each page loaded under that state by
688
-toggling the <span class="command"><strong>allowJavascript</strong></span> <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell" target="_top">docShell</a> property, and issues a
689
-<a class="ulink" href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()" target="_top">webNavigation.stop(webNavigation.STOP_ALL)</a> to each browser tab (the
690
-equivalent of hitting the STOP button).</p><p>
691
-
692
-Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox bug
693
-409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing
694
-all event handlers, and event handlers registered with <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:element.addEventListener" target="_top">addEventListener()</a>
695
-are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content
696
-Policy</a> should prevent such code from performing network activity within
697
-the current tab, but activity that happens via a popup window or via a
698
-Javascript redirect can still slip by. For this reason, Torbutton blocks
699
-popups by checking for a valid <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener" target="_top">window.opener</a>
700
-attribute in <code class="function">torbutton_check_progress()</code>. If the window
701
-has an opener from a different Tor state, its load is blocked. The content
702
-policy also takes similar action to prevent Javascript redirects. This also
703
-has the side effect/feature of preventing the user from following any links
704
-from a page loaded in an opposite Tor state.
705
-
706
-</p><p>
707
-This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
708
-</p></div><div class="sect3" title="Hook Dangerous Javascript"><div class="titlepage"><div><div><h4 class="title"><a id="jshooks"></a>Hook Dangerous Javascript</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js" target="_top">Javascript
709
-hooking code</a>. This is done in the chrome in
710
-<code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
711
-<a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
712
-listener</a> <span class="command"><strong>torbutton_weblistener</strong></span> and the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> (the latter being a hack to handle
713
-javascript: urls).
714
-
715
-In the Firefox 2 days, this option did a lot more than
716
-it does now. It used to be responsible for timezone and improved useragent
717
-spoofing, and history object cloaking. However, now it only provides
718
-obfuscation of the <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
719
-object to mask your browser and desktop resolution.
720
-The resolution hooks
721
-effectively make the Firefox browser window appear to websites as if the renderable area
722
-takes up the entire desktop, has no toolbar or other GUI element space, and
723
-the desktop itself has no toolbars.
724
-These hooks drastically reduce the amount of information available to do <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to
725
-meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
726
-requirements. Unfortunately, Gregory Fleischer discovered it is still possible
727
-to retrieve the original screen values by using <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html" target="_top">XPCNativeWrapper</a>
728
-or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html" target="_top">Components.lookupMethod</a>.
729
-We are still looking for a workaround as of Torbutton 1.3.2.
730
-
731
-
732
-
733
-
734
-</p></div><div class="sect3" title="Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663307"></a>Resize windows to multiples of 50px during Tor usage (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
735
-
736
-This option drastically cuts down on the number of distinct anonymity sets
737
-that divide the Tor web userbase. Without this setting, the dimensions for a
738
-typical browser window range from 600-1200 horizontal pixels and 400-1000
739
-vertical pixels, or about 600x600 = 360000 different sets. Resizing the
740
-browser window to multiples of 50 on each side reduces the number of sets by
741
-50^2, bringing the total number of sets to 144. Of course, the distribution
742
-among these sets are not uniform, but scaling by 50 will improve the situation
743
-due to this non-uniformity for users in the less common resolutions.
744
-Obviously the ideal situation would be to lie entirely about the browser
745
-window size, but this will likely cause all sorts of rendering issues, and is
746
-also not implementable in a foolproof way from extension land.
747
-
748
-</p><p>
749
-
750
-The implementation of this setting is spread across a couple of different
751
-locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="Browser Overlay - torbutton.xul">browser
752
-overlay</a>. Since resizing minimized windows causes them to be restored,
753
-and since maximized windows remember their previous size to the pixel, windows
754
-must be resized before every document load (at the time of browser tagging)
755
-via <code class="function">torbutton_check_round()</code>, called by
756
-<code class="function">torbutton_update_tags()</code>. To prevent drift, the extension
757
-tracks the original values of the windows and uses this to perform the
758
-rounding on document load. In addition, to prevent the user from resizing a
759
-window to a non-50px multiple, a resize listener
760
-(<code class="function">torbutton_do_resize()</code>) is installed on every new browser
761
-window to record the new size and round it to a 50px multiple while Tor is
762
-enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
763
-are set. This ensures that there is no discrepancy between the 50 pixel cutoff
764
-and the actual renderable area of the browser (so that it is not possible to
765
-infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
766
-
767
-</p><p>
768
-This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
769
-</p></div><div class="sect3" title="Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663391"></a>Disable Search Suggestions during Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
770
-This setting causes Torbutton to disable <a class="ulink" href="http://kb.mozillazine.org/Browser.search.suggest.enabled" target="_top"><span class="command"><strong>browser.search.suggest.enabled</strong></span></a>
771
-during Tor usage.
772
-This governs if you get Google search suggestions during Tor
773
-usage. Your Google cookie is transmitted with google search suggestions, hence
774
-this is recommended to be disabled.
775
-
776
-</p><p>
777
-While this setting doesn't satisfy any Torbutton requirements, the fact that
778
-cookies are transmitted for partially typed queries does not seem desirable
779
-for Tor usage.
780
-</p></div><div class="sect3" title="Disable Updates During Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2663430"></a>Disable Updates During Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox
781
-update settings</a> during Tor
782
-  usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
783
-<span class="command"><strong>app.update.enabled</strong></span>,
784
-  <span class="command"><strong>app.update.auto</strong></span>, and
785
-<span class="command"><strong>browser.search.update</strong></span>.  These prevent the
786
-  browser from updating extensions, checking for Firefox upgrades, and
787
-  checking for search plugin updates while Tor is enabled.
788
-  </p><p>
789
-This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
790
-</p></div><div class="sect3" title="Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663492"></a>Redirect Torbutton Updates Via Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.update_torbutton_via_tor</strong></span></p><p>This setting causes Torbutton to install an
791
-
792
-<a class="ulink" href="https://developer.mozilla.org/en/nsIProtocolProxyFilter" target="_top">nsIProtocolProxyFilter</a>
793
-in order to redirect all version update checks and Torbutton update downloads
794
-via Tor, regardless of if Tor is enabled or not. This was done both to address
795
-concerns about data retention done by <a class="ulink" href="https://www.addons.mozilla.org" target="_top">addons.mozilla.org</a>, as well as to
796
-help censored users meet the <a class="link" href="#undiscoverability">Tor
797
-Undiscoverability</a> requirement.
798
-
799
-  </p></div><div class="sect3" title="Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663536"></a>Disable livemarks updates during Tor usage (recommended)</h4></div></div></div><p>Option:
800
-   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.disable_livemarks</strong></span></td></tr></table><p>
801
-  </p><p>
802
-
803
-This option causes Torbutton to prevent Firefox from loading <a class="ulink" href="http://www.mozilla.com/firefox/livebookmarks.html" target="_top">Livemarks</a> during
804
-Tor usage. Because people often have very personalized Livemarks (such as RSS
805
-feeds of Wikipedia articles they maintain, etc). This is accomplished both by
806
-<a class="link" href="#livemarks" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js">wrapping the livemark-service component</a> and
807
-by calling stopUpdateLivemarks() on the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2" target="_top">Livemark
808
-service</a> when Tor is enabled.
809
-
810
-</p><p>
811
-This helps satisfy the <a class="link" href="#isolation">Network
812
-Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
813
-Preservation</a> requirements.
814
-</p></div><div class="sect3" title="Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663607"></a>Block Tor/Non-Tor access to network from file:// urls (recommended)</h4></div></div></div><p>Options:
815
-   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tor_file_net</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nontor_file_net</strong></span></td></tr></table><p>
816
-  </p><p>
817
-
818
-These settings prevent file urls from performing network operations during the
819
-respective Tor states. Firefox 2's implementation of same origin policy allows
820
-file urls to read and <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/" target="_top">submit
821
-arbitrary files from the local filesystem</a> to arbitrary websites. To
822
-make matters worse, the 'Content-Disposition' header can be injected
823
-arbitrarily by exit nodes to trick users into running arbitrary html files in
824
-the local context. These preferences cause the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> to block access to any network
825
-resources from File urls during the appropriate Tor state.
826
-
827
-</p><p>
828
-
829
-This preference helps to ensure Tor's <a class="link" href="#isolation">Network
830
-Isolation</a> requirement, by preventing file urls from executing network
831
-operations in opposite Tor states. Also, allowing pages to submit arbitrary
832
-files to arbitrary sites just generally seems like a bad idea.
833
-
834
-</p></div><div class="sect3" title="Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2663679"></a>Close all Tor/Non-Tor tabs and windows on toggle (optional)</h4></div></div></div><p>Options:
835
-   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.close_nontor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.close_tor</strong></span></td></tr></table><p>
836
-  </p><p>
837
-