GitList
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
torbutton/en/design/index.html.en
History View file @ 1b97e4b0e
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 
-