ad398e1f985d9ff829348c733cd6fbabef3703f7
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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">
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

4) 
5) This document describes the goals, operation, and testing procedures of the
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

6) Torbutton Firefox extension. It is current as of Torbutton 1.3.2.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

142) objects.
143) 
144) 
145) 
146) Browser window resolution information provides something like
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

155) 2<sup>3</sup>=8). Interface effects such as title bar font size
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

156) and window manager settings gives a factor of about 9 (say 3 common font sizes
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

157) for the title bar and 3 common sizes for browser GUI element fonts).
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

196)  one Tor state MUST NOT be accessible via the network in
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

210) Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity
211) set reducing or fingerprinting information
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

245) of its own standalone components as well.  Let's discuss the hooked components
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

287) extension. These components do not hook any interfaces, nor are they used
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

296) This component helps to address the <a class="link" href="#state">State
297) Isolation</a> requirement of Torbutton.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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).
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

337) This component handles optional referer spoofing for Torbutton. It implements a
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

339) to modify the Referer header. The code sends the default browser referer
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

363) <a class="ulink" href="http://webdevwonders.com/detecting-firefox-add-ons/" target="_top">querying for
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

382) files attached. The scope of these Javascript files is their containing
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

386) It contains event handlers for preference update, shutdown, upgrade, and
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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) 
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

450) </p><p>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

563) <span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

634) window</a>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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>.  
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

636) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>.
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

729) We are still looking for a workaround as of Torbutton 1.3.2.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

730) 
731) 
732) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

751) locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="Browser Overlay - torbutton.xul">browser
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

802) 
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

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:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

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) 
838) These settings cause Torbutton to enumerate through all windows and close all
839) tabs in each window for the appropriate Tor state. This code can be found in
840) <code class="function">torbutton_update_status()</code>.  The main reason these settings
841) exist is as a backup mechanism in the event of any Javascript or content policy
842) leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
843) 409737</a>.  Torbutton currently tries to block all Javascript network
844) activity via the content policy, but until that bug is fixed, there is some
845) risk that there are alternate ways to bypass the policy. This option is
846) available as an extra assurance of <a class="link" href="#isolation">Network
847) Isolation</a> for those who would like to be sure that when Tor is toggled
848) all page activity has ceased. It also serves as a potential future workaround
849) in the event a content policy failure is discovered, and provides an additional
850) level of protection for the <a class="link" href="#disk">Disk Avoidance</a>
851) protection so that browser state is not sitting around waiting to be swapped
852) out longer than necessary.
853) 
854) </p><p>
855) While this setting doesn't satisfy any Torbutton requirements, the fact that
856) cookies are transmitted for partially typed queries does not seem desirable
857) for Tor usage.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

858) </p></div></div><div class="sect2" title="5.3. History and Forms Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2705261"></a>5.3. History and Forms Settings</h3></div></div></div><div class="sect3" title="Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705267"></a>Isolate Access to History navigation to Tor state (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

859) This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener" target="_top">nsISHistoryListener</a>
860) attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">sessionHistory</a> of 
861) of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation" target="_top">webNavigatator</a>.
862) The nsIShistoryListener is instantiated with a reference to the containing
863) browser window and blocks the back, forward, and reload buttons on the browser
864) navigation bar when Tor is in an opposite state than the one to load the
865) current tab. In addition, Tor clears the session history during a new document
866) load if this setting is enabled. 
867) 
868)   </p><p>
869) 
870) This is marked as a crucial setting in part
871) because Javascript access to the history object is indistinguishable from 
872) user clicks, and because
873) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
874) 409737</a> allows javascript to execute in opposite Tor states, javascript
875) can issue reloads after Tor toggle to reveal your original IP. Even without
876) this bug, however, Javascript is still able to access previous pages in your
877) session history that may have been loaded under a different Tor state, to
878) attempt to correlate your activity.
879) 
880)    </p><p>
881) 
882) This setting helps to fulfill Torbutton's <a class="link" href="#state">State
883) Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
884) requirements.
885) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

886)    </p></div><div class="sect3" title="History Access Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2705344"></a>History Access Settings</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

887)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_thread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_thwrite</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthwrite</strong></span></td></tr></table><p>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

888)   </p><p>On Firefox 3.x, these four settings govern the behavior of the <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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

889) history blocker component mentioned above. By hooking the browser's view of
890) the history itself via the <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>
891) and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1" target="_top">@mozilla.org/browser/nav-history-service;1</a>
892) components, this mechanism defeats all document-based <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure
893) attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only attacks</a>.
894) 
895) The component also hooks functions involved in writing history to disk via
896) both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History" target="_top">Places
897) Database</a> and the older Firefox 2 mechanisms.
898) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

899) </p><p>
900) On Firefox 4, Mozilla finally <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">addressed
901) these issues</a>, so we can effectively ignore the "read" pair of the
902) above prefs. We then only need to link the write prefs to
903) <span class="command"><strong>places.history.enabled</strong></span>, which disabled writing to the
904) history store while set.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

905) </p><p>
906) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

907) </p></div><div class="sect3" title="Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705472"></a>Clear History During Tor Toggle (optional)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

908) <a class="ulink" href="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29" target="_top">nsIBrowserHistory.removeAllPages</a>
909) and <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">nsISHistory.PurgeHistory</a>
910) for each tab on Tor toggle.</p><p>
911) This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

912) </p></div><div class="sect3" title="Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2705515"></a>Block Password+Form saving during Tor/Non-Tor</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

913)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tforms</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_ntforms</strong></span></td></tr></table><p>
914)   </p><p>These settings govern if Torbutton disables
915) <span class="command"><strong>browser.formfill.enable</strong></span>
916) and <span class="command"><strong>signon.rememberSignons</strong></span> during Tor and Non-Tor usage.
917) Since form fields can be read at any time by Javascript, this setting is a lot
918) more important than it seems.
919) </p><p>
920) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

921) </p></div></div><div class="sect2" title="5.4. Cache Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2705577"></a>5.4. Cache Settings</h3></div></div></div><div class="sect3" title="Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2705582"></a>Block Tor disk cache and clear all cache on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

922)   </p><p>This option causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29" target="_top">nsICacheService.evictEntries(0)</a>
923) on Tor toggle to remove all entries from the cache. In addition, this setting
924) causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> to false.
925) </p><p>
926) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

927) </p></div><div class="sect3" title="Block disk and memory cache during Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2705632"></a>Block disk and memory cache during Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

928) causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>,
929) <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and
930) <a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage.
931) </p><p>
932) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

933) </p></div></div><div class="sect2" title="5.5. Cookie and Auth Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2705686"></a>5.5. Cookie and Auth Settings</h3></div></div></div><div class="sect3" title="Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2705691"></a>Clear Cookies on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

934)   </p><p>
935) 
936) This setting causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29" target="_top">nsICookieManager.removeAll()</a> on
937) every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
938) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
939) which prevents them from being written to disk. 
940) 
941) </p><p>
942) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

943) </p></div><div class="sect3" title="Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h4 class="title"><a id="id2705742"></a>Store Non-Tor cookies in a protected jar</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

944)   </p><p>
945) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

946) This setting causes Torbutton to use <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</a> to store
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

947) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
948) before restoring the jar.
949) </p><p>
950) This setting also sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
951) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
952) which prevents them from being written to disk. 
953) 
954) </p><p>
955) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

956) </p></div><div class="sect3" title="Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705799"></a>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

957)   </p><p>
958) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

959) This setting causes Torbutton to use <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</a> to store
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

960) both Tor and Non-Tor cookies into protected jars.
961) </p><p>
962) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

963) </p></div><div class="sect3" title="Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705841"></a>Manage My Own Cookies (dangerous)</h4></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
964) cookie prefs all to false.</p></div><div class="sect3" title="Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705856"></a>Disable DOM Storage during Tor usage (crucial)</h4></div></div></div><div class="sect3" title="Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h4 class="title"><a id="id2705859"></a>Do not write Tor/Non-Tor cookies to disk</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

965)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.tor_memory_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.nontor_memory_jar</strong></span></td></tr></table><p>
966)   </p><p>
967) These settings (contributed by arno) cause Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
968) to 2 during the appropriate Tor state, and to store cookies acquired in that
969) state into a Javascript
970) <a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X" target="_top">E4X</a>
971) object as opposed to writing them to disk.
972) </p><p>
973) This allows Torbutton to provide an option to preserve a user's 
974) cookies while still satisfying the <a class="link" href="#disk">Disk Avoidance</a>
975) requirement.
976) </p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span>
977)   </p><p>
978) 
979) This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor
980) usage to prevent 
981) <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from
982)   being used to store persistent information across Tor states.</p><p>
983) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

984) </p></div><div class="sect3" title="Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2705960"></a>Clear HTTP Auth on Tor Toggle (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

985)   </p><p>
986) This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager" target="_top">nsIHttpAuthManager.clearAll()</a>
987) every time Tor is toggled.
988) </p><p>
989) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

990) </p></div></div><div class="sect2" title="5.6. Startup Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2705999"></a>5.6. Startup Settings</h3></div></div></div><div class="sect3" title="On Browser Startup, set Tor state to: Tor, Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2706004"></a>On Browser Startup, set Tor state to: Tor, Non-Tor</h4></div></div></div><p>Options:
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

991)    <span class="command"><strong>extensions.torbutton.restore_tor</strong></span>
992)   </p><p>This option governs what Tor state tor is loaded in to.
993) <code class="function">torbutton_set_initial_state()</code> covers the case where the
994) browser did not crash, and <code class="function">torbutton_crash_recover()</code>
995) covers the case where the <a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash observer</a>
996) detected a crash.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

997) </p><p>
998) 
999) Since the Tor state after a Firefox crash is unknown/indeterminate, this
1000) setting helps to satisfy the <a class="link" href="#state">State Separation</a>
1001) requirement in the event of Firefox crashes by ensuring all cookies,
1002) settings and saved sessions are reloaded from a fixed Tor state.
1003)  
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1004) </p></div><div class="sect3" title="Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h4 class="title"><a id="id2706055"></a>Prevent session store from saving Non-Tor/Tor-loaded tabs</h4></div></div></div><p>Options: 
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1005)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.nonontor_sessionstore</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.notor_sessionstore</strong></span></td></tr></table><p>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1006)   </p><p>If these options are enabled, the <a class="link" href="#tbsessionstore" title="@torproject.org/torbutton-ss-blocker;1">tbSessionStore.js</a> component uses the session
1007) store listeners to filter out the appropriate tabs before writing the session
1008) store data to disk.
1009) </p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1010) This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
1011) requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
1012) crashes.
1013) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1014) </p></div></div><div class="sect2" title="5.7. Shutdown Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2706113"></a>5.7. Shutdown Settings</h3></div></div></div><div class="sect3" title="Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h4 class="title"><a id="id2706119"></a>Clear cookies on Tor/Non-Tor shutdown</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1015)   </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1016) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1017) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1018) for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
1019) <a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash-observer.js</a> and use <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</a>
1020) to clear out all cookies and all cookie jars upon shutdown.
1021) </p><p>
1022) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1023) </p></div></div><div class="sect2" title="5.8. Header Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2706173"></a>5.8. Header Settings</h3></div></div></div><div class="sect3" title="Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2706179"></a>Set user agent during Tor usage (crucial)</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1024)    </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.set_uagent</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.platform_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.oscpu_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.buildID_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.productsub_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appname_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appversion_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendorSub</strong></span></td></tr></table><p>
1025)    </p><p>On face, user agent switching appears to be straight-forward in Firefox.
1026) It provides several options for controlling the browser user agent string:
1027) <span class="command"><strong>general.appname.override</strong></span>,
1028) <span class="command"><strong>general.appversion.override</strong></span>,
1029) <span class="command"><strong>general.platform.override</strong></span>,
1030) <span class="command"><strong>general.oscpu.override</strong></span>,
1031) <span class="command"><strong>general.productSub.override</strong></span>,
1032) <span class="command"><strong>general.buildID.override</strong></span>,
1033) <span class="command"><strong>general.useragent.override</strong></span>,
1034) <span class="command"><strong>general.useragent.vendor</strong></span>, and
1035) <span class="command"><strong>general.useragent.vendorSub</strong></span>. If
1036) the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is
1037) true, Torbutton copies all of the other above prefs into their corresponding
1038) browser preferences during Tor usage.</p><p>
1039) 
1040) It also turns out that it is possible to detect the original Firefox version
1041) by <a class="ulink" href="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/" target="_top">inspecting
1042) certain resource:// files</a>. These cases are handled by Torbutton's
1043) <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
1044) 
1045) </p><p>
1046) This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1047) </p></div><div class="sect3" title="Spoof US English Browser"><div class="titlepage"><div><div><h4 class="title"><a id="id2706353"></a>Spoof US English Browser</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1048) </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.spoof_english</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_charset</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_language</strong></span></td></tr></table><p>
1049) </p><p> This option causes Torbutton to set
1050) <span class="command"><strong>general.useragent.locale</strong></span>
1051) <span class="command"><strong>intl.accept_languages</strong></span> to the value specified in
1052) <span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
1053) <span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
1054) <span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1055) well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="Hook Dangerous Javascript">javascript hooks</a>.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1056)  </p><p>
1057) This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and <a class="link" href="#location">Location Neutrality</a> requirements.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1058) </p></div><div class="sect3" title="Referer Spoofing Options"><div class="titlepage"><div><div><h4 class="title"><a id="id2706446"></a>Referer Spoofing Options</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.refererspoof</strong></span>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1059) </p><p>
1060) This option variable has three values. If it is 0, "smart" referer spoofing is
1061) enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is
1062) sent. The default value is 1. The smart referer spoofing is implemented by the
1063) <a class="link" href="#refspoofer" title="@torproject.org/torRefSpoofer;1">torRefSpoofer</a> component.
1064) 
1065) </p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1066) This setting also does not directly satisfy any Torbutton requirement, but
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1067) some may desire to mask their referer for general privacy concerns.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1068) </p></div><div class="sect3" title="Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h4 class="title"><a id="id2706480"></a>Strip platform and language off of Google Search Box queries</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.fix_google_srch</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1069) </p><p> 
1070) 
1071) This option causes Torbutton to use the <a class="ulink" href="https://wiki.mozilla.org/Search_Service:API" target="_top">@mozilla.org/browser/search-service;1</a>
1072) component to wrap the Google search plugin. On many platforms, notably Debian
1073) and Ubuntu, the Google search plugin is set to reveal a lot of language and
1074) platform information. This setting strips off that info while Tor is enabled.
1075) 
1076) </p><p>
1077) This setting helps Torbutton to fulfill its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1078) </p></div><div class="sect3" title="Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h4 class="title"><a id="id2706521"></a>Automatically use an alternate search engine when presented with a
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1079) Google Captcha</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1080) </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.asked_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.dodge_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.google_redir_url</strong></span></td></tr></table><p>
1081) </p><p>
1082) 
1083) Google's search engine has rate limiting features that cause it to
1084) <a class="ulink" href="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html" target="_top">present
1085) captchas</a> and sometimes even outright ban IPs that issue large numbers
1086) of search queries, especially if a lot of these queries appear to be searching
1087) for software vulnerabilities or unprotected comment areas.
1088) 
1089) </p><p>
1090) 
1091) Despite multiple discussions with Google, we were unable to come to a solution
1092) or any form of compromise that would reduce the number of captchas and
1093) outright bans seen by Tor users issuing regular queries.
1094) 
1095) </p><p>
1096) As a result, we've implemented this option as an <a class="ulink" href="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers" target="_top">'http-on-modify-request'</a>
1097) http observer to optionally redirect banned or captcha-triggering Google
1098) queries to search engines that do not rate limit Tor users. The current
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1099) options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. These are
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1100) encoded in the preferences
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1101) <span class="command"><strong>extensions.torbutton.redir_url.[1-5]</strong></span>.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1102) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1103) </p></div><div class="sect3" title="Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2706601"></a>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h4></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1104) </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.jar_certs</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.jar_ca_certs</strong></span></td></tr></table><p>
1105) </p><p>
1106) 
1107) These settings govern if Torbutton attempts to isolate the user's SSL
1108) certificates into separate jars for each Tor state. This isolation is
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1109) implemented in <code class="function">torbutton_jar_certs()</code> 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>,
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1110) which calls <code class="function">torbutton_jar_cert_type()</code> and
1111) <code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
1112) the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1" target="_top">@mozilla.org/security/nsscertcache;1</a>.
1113) Certificates are deleted from and imported to the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/x509certdb;1" target="_top">@mozilla.org/security/x509certdb;1</a>.
1114) </p><p>
1115) The first time this pref is used, a backup of the user's certificates is
1116) created in their profile directory under the name
1117) <code class="filename">cert8.db.bak</code>. This file can be copied back to
1118) <code class="filename">cert8.db</code> to fully restore the original state of the
1119) user's certificates in the event of any error.
1120) </p><p>
1121) Since exit nodes and malicious sites can insert content elements sourced to
1122) specific SSL sites to query if a user has a certain certificate,
1123) this setting helps to satisfy the <a class="link" href="#state">State
1124) Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Firefox Bug
1125) 435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
1126) is currently not exposed via the preferences UI.
1127) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1128) </p></div></div></div><div class="sect1" title="6. Relevant Firefox Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1129) Future releases of Torbutton are going to be designed around supporting only
1130) <a class="ulink" href="https://www.torproject.org/projects/torbrowser.html.en" target="_top">Tor
1131) Browser Bundle</a>, which greatly simplifies the number and nature of Firefox
1132) bugs we must fix. This allows us to abandon the complexities of <a class="link" href="#state">State
1133) Separation</a> and <a class="link" href="#isolation">Network Isolation</a> requirements
1134) associated with the Toggle Model.
1135)   </p><div class="sect2" title="6.1. Tor Browser Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="TorBrowserBugs"></a>6.1. Tor Browser Bugs</h3></div></div></div><p>
1136) The list of Firefox patches we must create to improve privacy on the
1137) Tor Browser Bundle are collected in the Tor Bug Tracker under <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/2871" target="_top">ticket
1138) #2871</a>. These bugs are also applicable to the Toggle Model, and
1139) should be considered higher priority than all Toggle Model specific bugs
1140) below.
1141)    </p></div><div class="sect2" title="6.2. Toggle Model Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="ToggleModelBugs"></a>6.2. Toggle Model Bugs</h3></div></div></div><p>
1142) In addition to the Tor Browser bugs, the Torbutton Toggle Model suffers from
1143) additional bugs specific to the need to isolate state across the toggle.
1144) Toggle model bugs are considered a lower priority than the bugs against the
1145) Tor Browser model.
1146)    </p><div class="sect3" title="Bugs impacting security"><div class="titlepage"><div><div><h4 class="title"><a id="FirefoxSecurity"></a>Bugs impacting security</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1147) 
1148) Torbutton has to work around a number of Firefox bugs that impact its
1149) security. Most of these are mentioned elsewhere in this document, but they
1150) have also been gathered here for reference. In order of decreasing severity,
1151) they are:
1152) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1153)    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Bug 435159 -
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1154) nsNSSCertificateDB::DeleteCertificate has race conditions</a><p>
1155) 
1156) In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
1157) the user has installed. Unfortunately, the method call to delete a certificate
1158) from the current certificate database acts lazily: it only sets a variable
1159) that marks a cert for deletion later, and it is not cleared if that
1160) certificate is re-added. This means that if the Tor state is toggled quickly,
1161) that certificate could remain present until it is re-inserted (causing an
1162) error dialog), and worse, it would still be deleted after that.  The lack of
1163) this functionality is considered a Torbutton security bug because cert
1164) isolation is considered a <a class="link" href="#state">State Separation</a>
1165) feature.
1166) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

1167)       </p></li><li class="listitem">Give more visibility into and control over TLS
1168) negotiation
1169)      <p>
1170) 
1171) There are several <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/2482" target="_top">TLS issues
1172) impacting Torbutton security</a>. It is not clear if these should be one
1173) Firefox bug or several, but in particular we need better control over various
1174) aspects of TLS connections. Firefox currently provides no observer capable of
1175) extracting TLS parameters or certificates early enough to cancel a TLS
1176) request. We would like to be able to provide <a class="ulink" href="https://www.eff.org/https-everywhere" target="_top">HTTPS-Everywhere</a> users with
1177) the ability to <a class="ulink" href="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission" target="_top">have
1178) their certificates audited</a> by a <a class="ulink" href="http://www.networknotary.org/" target="_top">Perspectives</a>-style set of
1179) notaries. The problem with this is that the API observer points do not exist
1180) for any Firefox addon to actually block authentication token submission over a
1181) TLS channel, so every addon to date (including Perspectives) is actually
1182) providing users with notification *after* their authentication tokens have
1183) already been compromised. This obviously needs to be fixed.
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1184)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=122752" target="_top">Bug 122752 - SOCKS
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1185) Username/Password Support</a><p>
1186) We need <a class="ulink" href="https://developer.mozilla.org/en/nsIProxyInfo" target="_top">Firefox
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1187) APIs</a> or about:config settings to control the SOCKS Username and
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1188) Password fields. The reason why we need this support is to utilize an (as yet
1189) unimplemented) scheme to separate Tor traffic based <a class="ulink" href="https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/171-separate-streams.txt" target="_top">on
1190) SOCKS username/password</a>.
1191)     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Bug 409737 -
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1192) javascript.enabled and docShell.allowJavascript do not disable all event
1193) handlers</a><p>
1194) 
1195) This bug allows pages to execute javascript via addEventListener and perhaps
1196) other callbacks. In order to prevent this bug from enabling an attacker to
1197) break the <a class="link" href="#isolation">Network Isolation</a> requirement,
1198) Torbutton 1.1.13 began blocking popups and history manipulation from different
1199) Tor states.  So long as there are no ways to open popups or redirect the user
1200) to a new page, the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content
1201) policy</a> should block Javascript network access. However, if there are
1202) ways to open popups or perform redirects such that Torbutton cannot block
1203) them, pages may still have free reign to break that requirement and reveal a
1204) user's original IP address.
1205) 
1206)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448743" target="_top">Bug 448743 -
1207) Decouple general.useragent.locale from spoofing of navigator.language</a><p>
1208) 
1209) Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1210) attribute via <a class="link" href="#jshooks" title="Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1211) these do not work on Firefox 3. It would be ideal to have
1212) a pref to set this value (something like a
1213) <span class="command"><strong>general.useragent.override.locale</strong></span>),
1214) to avoid fragmenting the anonymity set of users of foreign locales. This issue
1215) impedes Torbutton from fully meeting its <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
1216) requirement on Firefox 3.
1217) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1218)      </p></li></ol></div></div><div class="sect3" title="Bugs blocking functionality"><div class="titlepage"><div><div><h4 class="title"><a id="FirefoxWishlist"></a>Bugs blocking functionality</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1219) The following bugs impact Torbutton and similar extensions' functionality.
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1220)    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=629820" target="_top">Bug 629820 - nsIContentPolicy::shouldLoad not
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1221) called for web request in Firefox Mobile</a><p>
1222) 
1223) The new <a class="ulink" href="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis" target="_top">Electrolysis</a>
1224) multiprocess system appears to have some pretty rough edge cases with respect
1225) to registering XPCOM category managers such as the nsIContentPolicy, which
1226) make it difficult to do a straight-forward port of Torbutton or
1227) HTTPS-Everywhere to Firefox Mobile.  It probably also has similar issues with
1228) wrapping existing <a class="link" href="#hookedxpcom" title="2.1. Hooked Components">Firefox XPCOM components</a>,
1229) which will also cause more problems for porting Torbutton.
1230) 
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1231)     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869" target="_top">Bug 417869 -
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1232) Browser context is difficult to obtain from many XPCOM callbacks</a><p>
1233) 
1234) It is difficult to determine which tabbrowser many XPCOM callbacks originate
1235) from, and in some cases absolutely no context information is provided at all.
1236) While this doesn't have much of an effect on Torbutton, it does make writing
1237) extensions that would like to do per-tab settings and content filters (such as
1238) FoxyProxy) difficult to impossible to implement securely.
1239) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1240)    </p></li></ol></div></div><div class="sect3" title="Low Priority Bugs"><div class="titlepage"><div><div><h4 class="title"><a id="FirefoxMiscBugs"></a>Low Priority Bugs</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1241) The following bugs have an effect upon Torbutton, but are superseded by more
1242) practical and more easily fixable variant bugs above; or have stable, simple
1243) workarounds.
Mike Perry Update Torbutton design doc.

Mike Perry authored 12 years ago

1244)   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">Bug 440892 -
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1245) network.protocol-handler.warn-external are ignored</a><p>
1246) 
1247) Sometime in the Firefox 3 development cycle, the preferences that governed
1248) warning a user when external apps were launched got disconnected from the code
1249) that does the launching. Torbutton depended on these prefs to prevent websites
1250) from launching specially crafted documents and application arguments that
1251) caused Proxy Bypass. We currently work around this issue by <a class="link" href="#appblocker" 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">wrapping the app launching components</a> to present a
1252) popup before launching external apps while Tor is enabled. While this works,
1253) it would be nice if these prefs were either fixed or removed.
1254) 
1255)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">Bug 437014 -
1256) nsIContentPolicy::shouldLoad no longer called for favicons</a><p>
1257) 
1258) Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
1259) loads. Torbutton had relied on this call to block favicon loads for opposite
1260) Tor states. The workaround it employs for Firefox 3 is to cancel the request
1261) when it arrives in the <span class="command"><strong>torbutton_http_observer</strong></span> used for
1262) blocking full page plugin loads. This seems to work just fine, but is a bit
1263) dirty.
1264) 
1265)     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">Bug 309524</a>
1266) and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">Bug
1267) 380556</a> - nsIContentPolicy::shouldProcess is not called.
1268)      <p>
1269) 
1270) This is a call that would be useful to develop a better workaround for the
1271) allowPlugins issue above. If the content policy were called before a URL was
1272) handed over to a plugin or helper app, it would make the workaround for the
1273) above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
1274) the others though, but it might be nice to have this API as a backup.
1275) 
1276)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">Bug 401296 - docShell.allowPlugins
1277) not honored for direct links</a> (Perhaps subset of <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=282106" target="_top">Bug 282106</a>?)
1278)      <p>
1279) 
1280) Similar to the javascript plugin disabling attribute, the plugin disabling
1281) attribute is also not perfect — it is ignored for direct links to plugin
1282) handled content, as well as meta-refreshes to plugin handled content.  This
1283) requires Torbutton to listen to a number of different http events to intercept
1284) plugin-related mime type URLs and cancel their requests. Again, since plugins
1285) are quite horrible about obeying proxy settings, loading a plugin pretty much
1286) ensures a way to break the <a class="link" href="#isolation">Network Isolation</a>
1287) requirement and reveal a user's original IP address. Torbutton's code to
1288) perform this workaround has been subverted at least once already by Kyle
1289) Williams.
1290) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1291)      </p></li></ol></div></div></div></div><div class="sect1" title="7. Testing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="TestPlan"></a>7. Testing</h2></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1292) 
1293) The purpose of this section is to cover all the known ways that Tor browser
1294) security can be subverted from a penetration testing perspective. The hope
1295) is that it will be useful both for creating a "Tor Safety Check"
1296) page, and for developing novel tests and actively attacking Torbutton with the
1297) goal of finding vulnerabilities in either it or the Mozilla components,
1298) interfaces and settings upon which it relies.
1299) 
1300)   </p><div class="sect2" title="7.1. Single state testing"><div class="titlepage"><div><div><h3 class="title"><a id="SingleStateTesting"></a>7.1. Single state testing</h3></div></div></div><p>
1301) 
1302) Torbutton is a complicated piece of software. During development, changes to
1303) one component can affect a whole slough of unrelated features.  A number of
1304) aggregated test suites exist that can be used to test for regressions in
1305) Torbutton and to help aid in the development of Torbutton-like addons and
1306) other privacy modifications of other browsers. Some of these test suites exist
1307) as a single automated page, while others are a series of pages you must visit
1308) individually. They are provided here for reference and future regression
1309) testing, and also in the hope that some brave soul will one day decide to
1310) combine them into a comprehensive automated test suite.
1311) 
1312)      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="http://decloak.net/" target="_top">Decloak.net</a><p>
1313) 
1314) Decloak.net is the canonical source of plugin and external-application based
1315) proxy-bypass exploits. It is a fully automated test suite maintained by <a class="ulink" href="http://digitaloffense.net/" target="_top">HD Moore</a> as a service for people to
1316) use to test their anonymity systems.
1317) 
1318)        </p></li><li class="listitem"><a class="ulink" href="http://deanonymizer.com/" target="_top">Deanonymizer.com</a><p>
1319) 
1320) Deanonymizer.com is another automated test suite that tests for proxy bypass
1321) and other information disclosure vulnerabilities. It is maintained by Kyle
1322) Williams, the author of <a class="ulink" href="http://www.janusvm.com/" target="_top">JanusVM</a>
1323) and <a class="ulink" href="http://www.januspa.com/" target="_top">JanusPA</a>.
1324) 
1325)        </p></li><li class="listitem"><a class="ulink" href="https://www.jondos.de/en/anontest" target="_top">JonDos
1326) AnonTest</a><p>
1327) 
1328) The <a class="ulink" href="https://www.jondos.de" target="_top">JonDos people</a> also provide an
1329) anonymity tester. It is more focused on HTTP headers than plugin bypass, and
1330) points out a couple of headers Torbutton could do a better job with
1331) obfuscating.
1332) 
1333)        </p></li><li class="listitem"><a class="ulink" href="http://browserspy.dk" target="_top">Browserspy.dk</a><p>
1334) 
1335) Browserspy.dk provides a tremendous collection of browser fingerprinting and
1336) general privacy tests. Unfortunately they are only available one page at a
1337) time, and there is not really solid feedback on good vs bad behavior in
1338) the test results.
1339) 
1340)        </p></li><li class="listitem"><a class="ulink" href="http://analyze.privacy.net/" target="_top">Privacy
1341) Analyzer</a><p>
1342) 
1343) The Privacy Analyzer provides a dump of all sorts of browser attributes and
1344) settings that it detects, including some information on your origin IP
1345) address. Its page layout and lack of good vs bad test result feedback makes it
1346) not as useful as a user-facing testing tool, but it does provide some
1347) interesting checks in a single page.
1348) 
1349)        </p></li><li class="listitem"><a class="ulink" href="http://ha.ckers.org/mr-t/" target="_top">Mr. T</a><p>
1350) 
1351) Mr. T is a collection of browser fingerprinting and deanonymization exploits
1352) discovered by the <a class="ulink" href="http://ha.ckers.org" target="_top">ha.ckers.org</a> crew
1353) and others. It is also not as user friendly as some of the above tests, but it
1354) is a useful collection.
1355) 
1356)        </p></li><li class="listitem">Gregory Fleischer's <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">Torbutton</a> and
1357) <a class="ulink" href="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html" target="_top">Defcon
1358) 17</a> Test Cases
1359)        <p>
1360) 
1361) Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy
1362) issues for the past 2 years. He has an excellent collection of all his test
1363) cases that can be used for regression testing. In his Defcon work, he
1364) demonstrates ways to infer Firefox version based on arcane browser properties.
1365) We are still trying to determine the best way to address some of those test
1366) cases.
1367) 
1368)        </p></li><li class="listitem"><a class="ulink" href="https://torcheck.xenobite.eu/index.php" target="_top">Xenobite's
1369) TorCheck Page</a><p>
1370) 
1371) This page checks to ensure you are using a valid Tor exit node and checks for
1372) some basic browser properties related to privacy. It is not very fine-grained
1373) or complete, but it is automated and could be turned into something useful
1374) with a bit of work.
1375) 
1376)        </p></li></ol></div><p>
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1377)     </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2707624"></a>7.2. Multi-state testing</h3></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1378) 
1379) The tests in this section are geared towards a page that would instruct the
1380) user to toggle their Tor state after the fetch and perform some operations:
1381) mouseovers, stray clicks, and potentially reloads.
1382) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1383)    </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2707636"></a>Cookies and Cache Correlation</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1384) The most obvious test is to set a cookie, ask the user to toggle tor, and then
1385) have them reload the page. The cookie should no longer be set if they are
1386) using the default Torbutton settings. In addition, it is possible to leverage
1387) the cache to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
1388) identifiers</a>. The default settings of Torbutton should also protect
1389) against these from persisting across Tor Toggle.
1390) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1391)     </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2707658"></a>Javascript timers and event handlers</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1392) 
1393) Javascript can set timers and register event handlers in the hopes of fetching
1394) URLs after the user has toggled Torbutton. 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1395)     </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2707671"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1396) 
1397) Even if Javascript is disabled, CSS is still able to 
1398) <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like
1399) windows</a>
1400) via the 'onmouseover' CSS attribute, which can cause arbitrary browser
1401) activity as soon as the mouse enters into the content window. It is also
1402) possible for meta-refresh tags to set timers long enough to make it likely
1403) that the user has toggled Tor before fetching content.
1404) 
1405)     </p></div></div><div class="sect2" title="7.3. Active testing (aka How to Hack Torbutton)"><div class="titlepage"><div><div><h3 class="title"><a id="HackTorbutton"></a>7.3. Active testing (aka How to Hack Torbutton)</h3></div></div></div><p>
1406) 
1407) The idea behind active testing is to discover vulnerabilities in Torbutton to
1408) bypass proxy settings, run script in an opposite Tor state, store unique
1409) identifiers, leak location information, or otherwise violate <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. Torbutton has ventured out
1410) into a strange and new security landscape. It depends on Firefox mechanisms
1411) that haven't necessarily been audited for security, certainly not for the
1412) threat model that Torbutton seeks to address. As such, it and the interfaces
1413) it depends upon still need a 'trial by fire' typical of new technologies. This
1414) section of the document was written with the intention of making that period
1415) as fast as possible. Please help us get through this period by considering
1416) these attacks, playing with them, and reporting what you find (and potentially
1417) submitting the test cases back to be run in the standard batch of Torbutton
1418) tests.
1419) 
Mike Perry Update design doc to reflec...

Mike Perry authored 12 years ago

1420)    </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2707726"></a>Some suggested vectors to investigate</h4></div></div></div><p>