4da8cf976f49a9bdc501c01e60577d821052e11b
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 html.

Mike Perry authored 13 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">Mar 25 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2940331">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="#id2955313">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2972601">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2974988">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2976801">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#browseroverlay">3.1. Browser Overlay - torbutton.xul</a></span></dt><dt><span class="sect2"><a href="#id2959444">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2952051">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2943135">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2973670">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2975844">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2954530">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2971938">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2967115">5.1. Test Settings</a></span></dt><dt><span class="sect2"><a href="#plugins">5.2. Disable plugins on Tor Usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2951289">5.3. Isolate Dynamic Content to Tor State (crucial)</a></span></dt><dt><span class="sect2"><a href="#jshooks">5.4. Hook Dangerous Javascript</a></span></dt><dt><span class="sect2"><a href="#id2960649">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2952949">5.6. Disable Updates During Tor</a></span></dt><dt><span class="sect2"><a href="#id2936606">5.7. Redirect Torbutton Updates Via Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936650">5.8. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936689">5.9. Disable livemarks updates during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936761">5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936833">5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2936914">5.12. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2936998">5.13. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2937111">5.14. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2978657">5.15. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2978718">5.16. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2978768">5.17. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2978820">5.18. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2978871">5.19. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2978928">5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2978967">5.21. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2978982">5.22. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2979086">5.23. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2979123">5.24. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id2979178">5.25. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id2979253">5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2979325">5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id2979384">5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id2979449">5.29. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2979623">5.30. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id2979716">5.31. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id2979756">5.32. Strip platform and language off of Google Search Box queries</a></span></dt><dt><span class="sect2"><a href="#id2979797">5.33. Automatically use an alternate search engine when presented with a
4) Google Captcha</a></span></dt><dt><span class="sect2"><a href="#id2979878">5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#FirefoxSecurity">6.1. Bugs impacting security</a></span></dt><dt><span class="sect2"><a href="#FirefoxWishlist">6.2. Bugs blocking functionality</a></span></dt><dt><span class="sect2"><a href="#FirefoxMiscBugs">6.3. Low Priority Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id2980994">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="id2940331"></a>1. Introduction</h2></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

5) 
6) This document describes the goals, operation, and testing procedures of the
7) Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
8) 
9)   </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>
10) 
11) A Tor web browser adversary has a number of goals, capabilities, and attack
12) types that can be used to guide us towards a set of requirements for the
13) Torbutton extension. Let's start with the goals.
14) 
15)    </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 
16) Tor, causing the user to directly connect to an IP of the adversary's
17) 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
18) happily settle for the ability to correlate something a user did via Tor with
19) their non-Tor activity. This can be done with cookies, cache identifiers,
20) javascript events, and even CSS. Sometimes the fact that a user uses Tor may
21) be enough for some authorities.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p>
22) The adversary may also be interested in history disclosure: the ability to
23) query a user's history to see if they have issued certain censored search
24) queries, or visited censored sites.
25)      </p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p>
26) 
27) Location information such as timezone and locality can be useful for the
28) adversary to determine if a user is in fact originating from one of the
29) regions they are attempting to control, or to zero-in on the geographical
30) location of a particular dissident or whistleblower.
31) 
32)      </p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
33) 
34) Anonymity set reduction is also useful in attempting to zero in on a
35) particular individual. If the dissident or whistleblower is using a rare build
36) of Firefox for an obscure operating system, this can be very useful
37) information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>.
38) 
39)      </p></li><li class="listitem"><span class="command"><strong>History records and other on-disk
40) information</strong></span><p>
41) In some cases, the adversary may opt for a heavy-handed approach, such as
42) seizing the computers of all Tor users in an area (especially after narrowing
43) the field by the above two pieces of information). History records and cache
44) data are the primary goals here.
45)      </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>
46) The adversary can position themselves at a number of different locations in
47) order to execute their attacks.
48)     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
49) The adversary can run exit nodes, or alternatively, they may control routers
50) upstream of exit nodes. Both of these scenarios have been observed in the
51) wild.
52)      </p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>
53) The adversary can also run websites, or more likely, they can contract out
54) ad space from a number of different adservers and inject content that way. For
55) some users, the adversary may be the adservers themselves. It is not
56) inconceivable that adservers may try to subvert or reduce a user's anonymity 
57) through Tor for marketing purposes.
58)      </p></li><li class="listitem"><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p>
59) The adversary can also inject malicious content at the user's upstream router
60) when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
61) activity.
62)      </p></li><li class="listitem"><span class="command"><strong>Physical Access</strong></span><p>
63) Some users face adversaries with intermittent or constant physical access.
64) Users in Internet cafes, for example, face such a threat. In addition, in
65) countries where simply using tools like Tor is illegal, users may face
66) confiscation of their computer equipment for excessive Tor usage or just
67) general suspicion.
68)      </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>
69) 
70) The adversary can perform the following attacks from a number of different 
71) positions to accomplish various aspects of their goals. It should be noted
72) that many of these attacks (especially those involving IP address leakage) are
73) often performed by accident by websites that simply have Javascript, dynamic 
74) CSS elements, and plugins. Others are performed by adservers seeking to
75) correlate users' activity across different IP addresses, and still others are
76) performed by malicious agents on the Tor network and at national firewalls.
77) 
78)     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Inserting Javascript</strong></span><p>
79) If not properly disabled, Javascript event handlers and timers
80) can cause the browser to perform network activity after Tor has been disabled,
81) thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
82) a user's non-Tor IP address. Javascript
83) also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure attacks</a>:
84) to query the history via the different attributes of 'visited' links to search
85) 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
86) users based on gender and other classifications</a>. Finally,
87) Javascript can be used to query the user's timezone via the
88) <code class="function">Date()</code> object, and to reduce the anonymity set by querying
89) the <code class="function">navigator</code> object for operating system, CPU, locale, 
90) and user agent information.
91)      </p></li><li class="listitem"><span class="command"><strong>Inserting Plugins</strong></span><p>
92) 
93) Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
94) capable of performing network activity that the author has
95) investigated is also capable of performing network activity independent of
96) browser proxy settings - and often independent of its own proxy settings.
97) Sites that have plugin content don't even have to be malicious to obtain a
98) user's
99) Non-Tor IP (it usually leaks by itself), though <a class="ulink" href="http://decloak.net" target="_top">plenty of active
100) exploits</a> are possible as well. In addition, plugins can be used to store unique identifiers that are more
101) difficult to clear than standard cookies. 
102) <a class="ulink" href="http://epic.org/privacy/cookies/flash.html" target="_top">Flash-based
103) cookies</a> fall into this category, but there are likely numerous other
104) examples.
105) 
106)      </p></li><li class="listitem"><span class="command"><strong>Inserting CSS</strong></span><p>
107) 
108) CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
109) Non-Tor IP address, via the usage of
110) <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">CSS
111) popups</a> - essentially CSS-based event handlers that fetch content via
112) CSS's onmouseover attribute. If these popups are allowed to perform network
113) activity in a different Tor state than they were loaded in, they can easily
114) correlate Tor and Non-Tor activity and reveal a user's IP address. In
115) 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
116) attacks</a>.
117)      </p></li><li class="listitem"><span class="command"><strong>Read and insert cookies</strong></span><p>
118) 
119) An adversary in a position to perform MITM content alteration can inject
120) document content elements to both read and inject cookies for
121) arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
122) sort of <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html" target="_top">active
123) sidejacking</a>.
124) 
125)      </p></li><li class="listitem"><span class="command"><strong>Create arbitrary cached content</strong></span><p>
126) 
127) Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
128) identifiers</a>. Since by default the cache has no same-origin policy,
129) these identifiers can be read by any domain, making them an ideal target for
130) adserver-class adversaries.
131) 
132)      </p></li><li class="listitem"><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser
133) attributes</strong></span><p>
134) 
135) There is an absurd amount of information available to websites via attributes
136) of the browser. This information can be used to reduce anonymity set, or even
137) <a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">uniquely
138) fingerprint individual users</a>. </p><p>
139) For illustration, let's perform a
140) back-of-the-envelope calculation on the number of anonymity sets for just the
141) resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and
142) <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
143) objects. Browser window resolution information provides something like
144) (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
145) information contributes about another factor of 5 (for about 5 resolutions in
146) typical use). In addition, the dimensions and position of the desktop taskbar
147) are available, which can reveal hints on OS information. This boosts the count
148) by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
149) and Gnome, and None). Subtracting the browser content window
150) size from the browser outer window size provide yet more information.
151) Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
152) 2<sup>3</sup>=8). Interface effects such as titlebar fontsize
153) and window manager settings gives a factor of about 9 (say 3 common font sizes
154) for the titlebar and 3 common sizes for browser GUI element fonts).
155) Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
156) 2<sup>29</sup>, or a 29 bit identifier based on resolution
157) information alone. </p><p>
158) 
159) Of course, this space is non-uniform and prone to incremental changes.
160) However, if a bit vector space consisting of the above extracted attributes
161) were used instead of the hash approach from <a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">The Hacker
162) Webzine article above</a>, minor changes in browser window resolution will
163) no longer generate totally new identifiers. 
164) 
165) </p><p>
166) 
167) To add insult to injury, <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">chrome URL disclosure
168) attacks</a> mean that each and every extension on <a class="ulink" href="https://addons.mozilla.org" target="_top">addons.mozilla.org</a> adds another bit
169) to that 2<sup>29</sup>. With hundreds of popular extensions
170) and thousands of extensions total, it is easy to see that this sort of
171) information is an impressively powerful identifier if used properly by a
172) competent and determined adversary such as an ad network.  Again, a
173) nearest-neighbor bit vector space approach here would also gracefully handle
174) incremental changes to installed extensions.
175) 
176) </p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or
177) OS</strong></span><p>
178) Last, but definitely not least, the adversary can exploit either general 
179) browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
180) install malware and surveillance software. An adversary with physical access
181) can perform similar actions. Regrettably, this last attack capability is
182) outside of Torbutton's ability to defend against, but it is worth mentioning
183) for completeness.
184)      </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>
185) 
186) Since many settings satisfy multiple requirements, this design document is
187) organized primarily by Torbutton components and settings. However, if you are
188) the type that would rather read the document from the requirements
189) perspective, it is in fact possible to search for each of the following
190) requirement phrases in the text to find the relevant features that help meet
191) that requirement.
192) 
193) </div><p>
194) 
195) From the above Adversary Model, a number of requirements become clear. 
196) 
197)    </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
198) MUST NOT bypass Tor proxy settings for any content.</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
199)  from the state they were originally loaded in.</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
200)  one Tor state MUST NOT be accessible via the network in
201)  another Tor state.</p></li><li class="listitem"><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>With
202) the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
203) users whose network fingerprint does not obviously betray the fact that they
204) are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
205) reveal its presence while Tor is disabled.</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
206)  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
207)  timezone or locale via Tor.</p></li><li class="listitem"><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
208) Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity set reducing information 
209)  (such as user agent, extension presence, and resolution information)
210) automatically via Tor. The assessment of the attacks above should make it clear
211) that anonymity set reduction is a very powerful method of tracking and
212) eventually identifying anonymous users.
213) </p></li><li class="listitem"><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser
214) 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
215)  enable the user to switch between a number of different proxies. It MUST
216)  provide full Tor protection in the event a third-party proxy switcher has
217)  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
218) 'Chrome'. Components are a fancy name for classes that implement a given
219) interface or interfaces. In Firefox, components <a class="ulink" href="https://developer.mozilla.org/en/XPCOM" target="_top">can be
220) written</a> in C++,
221) Javascript, or a mixture of both. Components have two identifiers: their
222) '<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005" target="_top">Contract
223) 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
224) ID</a>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
225) 'Interface ID'. It is possible to 'hook' system components - to reimplement
226) their interface members with your own wrappers - but only if the rest of the
227) browser refers to the component by its Contract ID. If the browser refers to
228) the component by Class ID, it bypasses your hooks in that use case.
229) Technically, it may be possible to hook Class IDs by unregistering the
230) original component, and then re-registering your own, but this relies on
231) obsolete and deprecated interfaces and has proved to be less than
232) stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window.
233) Extensions are allowed to create 'overlays' that are 'bound' to existing XML
234) window definitions, or they can create their own windows. The DTD for this XML
Mike Perry Update design html.

Mike Perry authored 13 years ago

235) 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="id2955313"></a>2. Components</h2></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

236) 
237) Torbutton installs components for two purposes: hooking existing components to
238) reimplement their interfaces; and creating new components that provide
239) services to other pieces of the extension.
240) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

241)   </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2972601"></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

242) of its own standalone components as well.  Let's discuss the hooked components
243) first.</p><div class="sect3" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js"><div class="titlepage"><div><div><h4 class="title"><a id="sessionstore"></a><a class="ulink" href="http://developer.mozilla.org/en/docs/nsISessionStore" target="_top">@mozilla.org/browser/sessionstore;1</a> -
244) <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js" target="_top">components/nsSessionStore36.js</a></h4></div></div></div><p>These components address the <a class="link" href="#disk">Disk Avoidance</a>
245) requirements of Torbutton. As stated in the requirements, Torbutton needs to
246) prevent Tor tabs from being written to disk by the Firefox session store for a
247) number of reasons, primary among them is the fact that Firefox can crash at
248) any time, and a restart can cause you to fetch tabs in the incorrect Tor
249) state.</p><p>These components illustrate a complication with Firefox hooking: you can
250) only hook member functions of a class if they are published in an
251) interface that the class implements. Unfortunately, the sessionstore has no
252) published interface that is amenable to disabling the writing out of Tor tabs
253) in specific. As such, Torbutton had to include the <span class="emphasis"><em>entire</em></span>
254) nsSessionStore from both Firefox 2.0, 3.0, 3.5 and 3.6
255) with a couple of modifications to prevent tabs that were loaded with Tor
256) enabled from being written to disk, and some version detection code to
257) determine which component to load. The <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff" target="_top">diff against the original session
258) store</a> is included in the git repository.</p></div><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
259) </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>,
260) 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>
261) - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js" target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>
262) 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
263) applications without user intervention, Torbutton had to wrap the three
264) components involved in launching external applications to provide user
265) confirmation before doing so while Tor is enabled. Since external applications
266) do not obey proxy settings, they can be manipulated to automatically connect
267) back to arbitrary servers outside of Tor with no user intervention. Fixing
268) this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy
269) Obedience</a> Requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

270)  </p></div><div class="sect3" title="@mozilla.org/browser/sessionstartup;1 - components/crash-observer.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2951475"></a><a class="ulink" href="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js" target="_top">@mozilla.org/browser/sessionstartup;1</a> -
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

271)     <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">components/crash-observer.js</a></h4></div></div></div><p>This component wraps the Firefox Session Startup component that is in
272) charge of <a class="ulink" href="http://developer.mozilla.org/en/docs/Session_store_API" target="_top">restoring saved
273) sessions</a>. The wrapper's only job is to intercept the
274) <code class="function">doRestore()</code> function, which is called by Firefox if it is determined that the
275) browser crashed and the session needs to be restored. The wrapper notifies the
276) Torbutton chrome that the browser crashed by setting the pref
277) <span class="command"><strong>extensions.torbutton.crashed</strong></span>, or that it is a normal
278) startup via the pref <span class="command"><strong>extensions.torbutton.noncrashed</strong></span>. The Torbutton Chrome <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">listens for a
279) preference change</a> for this value and then does the appropriate cleanup. This
280) includes setting the Tor state to the one the user selected for crash recovery
281) in the preferences window (<span class="command"><strong>extensions.torbutton.restore_tor</strong></span>), and
282) restoring cookies for the corresponding cookie jar, if it exists.</p><p>By performing this notification, this component assists in the 
283) <a class="link" href="#proxy">Proxy Obedience</a>, and <a class="link" href="#isolation">Network Isolation</a> requirements.
Mike Perry Update design html.

Mike Perry authored 13 years ago

284) </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="id2971802"></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>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

285) - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/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
286) CSS and Javascript-based methods of history disclosure. The global-history
287) component is what is used by Firefox to determine if a link was visited or not
288) (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>
289) and <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29" target="_top">addURI</a>
290) methods, Torbutton is able to selectively prevent history items from being
291) added or being displayed as visited, depending on the Tor state and the user's
292) preferences.
293) </p><p>
294) This component helps satisfy the <a class="link" href="#state">State Separation</a>
295) and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton.
296) </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>
297) - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js" target="_top">components/block-livemarks.js</a></h4></div></div></div><p>
298) 
299) The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html" target="_top">livemark</a> service
300) is started by a timer that runs 5 seconds after Firefox
301) startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
302) disable it. We must wrap the component to prevent this start() call from
303) firing in the event the browser starts in Tor mode.
304) 
305) </p><p>
306) This component helps satisfy the <a class="link" href="#isolation">Network
307) Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
308) Preservation</a> requirements.
Mike Perry Update design html.

Mike Perry authored 13 years ago

309) </p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2974988"></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

310) extension. These components do not hook any interfaces, nor are they used
Mike Perry Update design html.

Mike Perry authored 13 years ago

311) 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="id2951018"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/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

312) - 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
313) Jackson</a>) is used by the Torbutton chrome to switch between
314) Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
315) move the current cookies.txt file to the appropriate backup location
316) (cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
317) into place.</p><p>
318) This component helps to address the <a class="link" href="#state">State
319) Isolation</a> requirement of Torbutton.
Mike Perry Update design html.

Mike Perry authored 13 years ago

320) </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="id2975569"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/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

321) - components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
322) logging messages to either Firefox stderr
323) (<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
324) (<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if
325) available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
326) change the loglevel on the fly by changing
327) <span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
328) </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://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1
329) - 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
330) state the tab was most recently used under to fetch a page. The problem is
331) that for many Firefox events, it is not possible to determine the tab that is
332) actually receiving the event. The Torbutton window mapper allows the Torbutton
333) chrome and other components to look up a <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
334) tab</a> for a given <a class="ulink" href="https://developer.mozilla.org/en/nsIDOMWindow" target="_top">HTML content
335) window</a>. It does this by traversing all windows and all browsers, until it
336) 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
337) and page loading in general can generate hundreds of these lookups, this
338) result is cached inside the component.
339) </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://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
340) - components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is
341) toggled, Javascript is disabled, and pages are instructed to stop loading.
342) However, CSS is still able to perform network operations by loading styles for
343) onmouseover events and other operations. In addition, favicons can still be
344) loaded by the browser. The cssblocker component prevents this by implementing
345) and registering an <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy" target="_top">nsIContentPolicy</a>.
346) When an nsIContentPolicy is registered, Firefox checks every attempted network
347) request against its <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()" target="_top">shouldLoad</a>
348) member function to determine if the load should proceed. In Torbutton's case,
349) 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>,
350) and checks that tab's load tag against the current Tor state. If the tab was
351) loaded in a different state than the current state, the fetch is denied.
352) Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#isolation">Network
353) Isolation</a> requirements of Torbutton.
354) 
355) <p>In addition, the content policy also blocks website javascript from
356) <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">querying for
357) versions and existence of extension chrome</a> while Tor is enabled, and
358) also masks the presence of Torbutton to website javascript while Tor is
359) disabled. </p><p>
360) 
361) Finally, some of the work that logically belongs to the content policy is
362) instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
363) <span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of
364) Firefox 3 favicon loads, popups, and full page plugins, which for whatever
365) reason are not passed to the Firefox content policy itself (see Firefox Bugs 
366) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 
367) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
368) 
369) </p><p>
370) 
371) 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 html.

Mike Perry authored 13 years ago

372) Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2976801"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

373) located. Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XML file</a>, with zero or more Javascript
374) files attached. The scope of these Javascript files is their containing
375) window.</p><div class="sect2" title="3.1. Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h3 class="title"><a id="browseroverlay"></a>3.1. Browser Overlay - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h3></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
376) bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
377) It contains event handlers for preference update, shutdown, upgrade, and
378) location change events.</p><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
379) change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress" target="_top">webprogress
380) listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most
381) 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
382) listener</a> that handles receiving an event every time a page load or
383) iframe load occurs. This class eventually calls down to
384) <code class="function">torbutton_update_tags()</code> and
385) <code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load
386) state tags, plugin permissions, and install the Javascript hooks to hook the
387) <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
388) object to obfuscate browser and desktop resolution information.
389) 
390) </p><p>
391) The browser overlay helps to satisfy a number of Torbutton requirements. These
392) are better enumerated in each of the Torbutton preferences below. However,
393) there are also a number of Firefox preferences set in
394) <code class="function">torbutton_update_status()</code> that aren't governed by any
395) Torbutton setting. These are:
396) </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>
397) Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
398) reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) to the list
399) of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
400) and the Tor control port, respectively. This is set for both Tor and Non-Tor
401) usage, and prevents websites from attempting to do http fetches from these
402) ports to see if they are open, which addresses the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
403)  </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings" target="_top">browser.send_pings</a><p>
404) This setting is currently always disabled. If anyone ever complains saying
405) that they *want* their browser to be able to send ping notifications to a
406) page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
407) my breath. I haven't checked if the content policy is called for pings, but if
408) not, this setting helps with meeting the <a class="link" href="#isolation">Network
409) Isolation</a> requirement.
410)  </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups" target="_top">browser.safebrowsing.remoteLookups</a><p>
411) Likewise for this setting. I find it hard to imagine anyone who wants to ask
412) Google in real time if each URL they visit is safe, especially when the list
413) of unsafe URLs is downloaded anyway. This helps fulfill the <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire
414) browsing history from ending up on Google's disks.
415)  </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled" target="_top">browser.safebrowsing.enabled</a><p>
416) Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387" target="_top">unauthenticated
417) updates under Firefox 2</a>, so it is disabled during Tor usage. 
418) This helps fulfill the <a class="link" href="#updates">Update
419) Safety</a> requirement. Firefox 3 has the fix for that bug, and so
420) safebrowsing updates are enabled during Tor usage.
421)  </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>
422) If Tor is enabled, we need to prevent random external applications from
423) launching without at least warning the user. This group of settings only
424) partially accomplishes this, however. Applications can still be launched via
425) plugins. The mechanisms for handling this are described under the "Disable
426) Plugins During Tor Usage" preference. This helps fulfill the <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external
427) applications from accessing network resources at the command of Tor-fetched
428) pages. Unfortunately, due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a>
429) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a>,
430) these prefs are no longer obeyed. They are set still anyway out of respect for
431) the dead.
432)  </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>
433) 
434) To help satisfy the Torbutton <a class="link" href="#state">State Separation</a>
435) and <a class="link" href="#isolation">Network Isolation</a> requirements,
436) Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
437) "Undo Close" operations from accidentally restoring tabs from a different Tor
438) State. This purge is accomplished by setting this preference to 0 and then
439) restoring it to the previous user value upon toggle.
440) 
441)    </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span><p>
442) TLS Session IDs can persist for an indefinite duration, providing an
443) identifier that is sent to TLS sites that can be used to link activity. This
444) is particularly troublesome now that we have certificate verification in place
445) in Firefox 3: The OCSP server can use this Session ID to build a history of
446) TLS sites someone visits, and also correlate their activity as users move from
447) network to network (such as home to work to coffee shop, etc), inside and
448) outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we currently 
449) toggle
450) <span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
451) cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134" target="_top">nsNSSComponent.cpp
452) line 2134</a>. This is an arcane and potentially fragile fix. It would be
453) better if there were a more standard interface for accomplishing the same
454) thing. <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=448747" target="_top">448747</a> has
455) been filed for this.
456) 
457)    </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>
458) 
459) Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
460) is enabled. This helps Torbutton maintain its
461) <a class="link" href="#location">Location Neutrality</a> requirement.
462) While Firefox does prompt before divulging geolocational information,
463) the assumption is that Tor users will never want to give their
464) location away during Tor usage, and even allowing websites to prompt
465) them to do so will only cause confusion and accidents to happen. Moreover,
466) just because users may approve a site to know their location in non-Tor mode
467) does not mean they want it divulged during Tor mode.
468) 
469)    </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>
470) 
471) Firefox actually remembers your zoom settings for certain sites. CSS
472) and Javascript rule can use this to recognize previous visitors to a site.
473) This helps Torbutton fulfill its <a class="link" href="#state">State Separation</a>
474) requirement.
475) 
476)    </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>
477) 
478) Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
479) links on a page to decrease page load latency. While Firefox does typically
480) disable this behavior when proxies are enabled, we set this pref for added
481) safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
482) their links prefetched after a toggle to Non-Tor mode occurs,
483) we also set the docShell attribute
484) <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell" target="_top">
485) allowDNSPrefetch</a> to false on Tor loaded tabs. This happens in the same
486) positions in the code as those for disabling plugins via the allowPlugins
487) docShell attribute. This helps Torbutton fulfill its <a class="link" href="#isolation">Network Isolation</a> requirement.
488) 
489)    </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>
490) 
491) Firefox has the ability to store web applications in a special cache to allow
492) them to continue to operate while the user is offline. Since this subsystem
493) is actually different than the normal disk cache, it must be dealt with
494) separately. Thus, Torbutton sets this preference to false whenever Tor is
495) enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk
496) Avoidance</a> and <a class="link" href="#state">State Separation</a>
497) requirements.
498) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

499)    </p></li></ol></div></div><div class="sect2" title="3.2. Preferences Window - preferences.xul"><div class="titlepage"><div><div><h3 class="title"><a id="id2959444"></a>3.2. Preferences Window - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h3></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
500) handlers located in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect2" title="3.3. Other Windows"><div class="titlepage"><div><div><h3 class="title"><a id="id2952051"></a>3.3. Other Windows</h3></div></div></div><p>There are additional windows that describe popups for right clicking on
501) the status bar, the toolbutton, and the about page.</p></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2943135"></a>4. Toggle Code Path</h2></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

502) 
503) The act of toggling is connected to <code class="function">torbutton_toggle()</code>
504) via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
505) and <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul" target="_top">popup.xul</a>
506) overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 
507) 
508) </p><p>
509) 
510) Toggling is a 3 stage process: Button Click, Proxy Update, and
511) Settings Update. These stages are reflected in the prefs
512) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
513) <span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
514) <span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
515) 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
516) javascript runs on a different thread than the chrome javascript, it is
517) important to properly convey the stages to the content policy to avoid race
518) conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
519) 409737</a> unfixed. The content policy does not allow any network activity
520) whatsoever during this three stage transition.
521) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

522)  </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2973670"></a>4.1. Button Click</h3></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

523) 
524) This is the first step in the toggling process. When the user clicks the
525) toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
526) called. This function checks the current Tor status by comparing the current
527) proxy settings to the selected Tor settings, and then sets the proxy settings
528) to the opposite state, and sets the pref
529) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
530) 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
531) observer</a>
532) <span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
533) toggle.
534) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

535)   </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2975844"></a>4.2. Proxy Update</h3></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

536) 
537) When Torbutton receives any proxy change notifications via its
538) <span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
539) <code class="function">torbutton_set_status()</code> which checks against the Tor
540) settings to see if the Tor proxy settings match the current settings. If so,
541) it calls <code class="function">torbutton_update_status()</code>, which determines if
542) the Tor state has actually changed, and sets
543) <span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
544) state value, and ensures that
545) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
546) value. This is decoupled from the button click functionalty via the pref
547) observer so that other addons (such as SwitchProxy) can switch the proxy
548) settings between multiple proxies.
549) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

550)   </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2954530"></a>4.3. Settings Update</h3></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

551) 
552) The next stage is also handled by
553) <code class="function">torbutton_update_status()</code>. This function sets scores of
554) Firefox preferences, saving the original values to prefs under
555) <span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the history
556) clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
557) end of its work, it sets
558) <span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
559) completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
560) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

561)   </p></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2971938"></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

562) option is presented as the string from the preferences window, a summary, the
563) preferences it touches, and the effect this has on the components, chrome, and
Mike Perry Update design html.

Mike Perry authored 13 years ago

564) browser properties.</p><div class="sect2" title="5.1. Test Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2967115"></a>5.1. Test Settings</h3></div></div></div><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

565) This button under the Proxy Settings tab provides a way to verify that the 
566) proxy settings are correct, and actually do route through the Tor network. It
567) performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a>
568) for <a class="ulink" href="https://check.torproject.org/?TorButton=True" target="_top">https://check.torproject.org/?Torbutton=True</a>.
569) This is a special page that returns very simple, yet well-formed XHTML that
570) Torbutton can easily inspect for a hidden link with an id of
571) <span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
572) or <span class="command"><strong>failure</strong></span> to indicate if the
573) user hit the page from a Tor IP, a non-Tor IP. This check is handled in
574) <code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>.
575) Presenting the results to the user is handled by the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul" target="_top">preferences
576) window</a>
577) callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js" target="_top">preferences.js</a>.  
578) 
579)   </p></div><div class="sect2" title="5.2. Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="plugins"></a>5.2. Disable plugins on Tor Usage (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>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
580) address</a> and report it back to the
581) remote site. They can also <a class="ulink" href="http://decloak.net" target="_top">bypass proxy settings</a> and directly connect to a
582) remote site without Tor. Every browser plugin we have tested with Firefox has
583) some form of network capability, and every one ignores proxy settings or worse - only
584) partially obeys them. This includes but is not limited to:
585) QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
586) Flash. 
587) 
588)  </p><p>
589) Enabling this preference causes the above mentioned Torbutton chrome web progress
590)  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
591)  plugins via the browser <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell" target="_top">docShell</a>
592)  attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is
593)  created (<code class="function">torbutton_tag_new_browser()</code>), every time a web
594) load
595) event occurs
596)  (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
597)  (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
598)  prevented from loading by the content policy in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is
599)  enabled and this option is set.
600)  </p><p>All of this turns out to be insufficient if the user directly clicks
601) 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>,
602) the browser decides that maybe it should ignore all these other settings and
603) load the plugin anyways, because maybe the user really did want to load it
604) (never mind this same load-style could happen automatically  with meta-refresh
605) or any number of other ways..). To handle these cases, Torbutton stores a list
606) of plugin-handled mime-types, and sets the pref
607) <span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> to this list.
608) Additionally, (since nothing can be assumed when relying on Firefox
609) preferences and internals) if it detects a load of one of them from the web
610) progress listener, it cancels the request, tells the associated DOMWindow to
611) stop loading, clears the document, AND throws an exception. Anything short of
612) all this and the plugin managed to find some way to load.
613)  </p><p>
614)  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
615)  allowPlugins</a> for directly visited URLs, or notify its content policy for such
616)  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
617)  not very encouraging.
618)  </p><p>
619) 
620) Since most plugins completely ignore browser proxy settings, the actions
621) performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
622) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

623)  </p></div><div class="sect2" title="5.3. Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2951289"></a>5.3. Isolate Dynamic Content to Tor State (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/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

624) mentioned above, and causes it to block content load attempts in pages an
625) opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
626) tabs</a> are tagged
627) with a <span class="command"><strong>__tb_load_state</strong></span> member in
628) <code class="function">torbutton_update_tags()</code> and this
629) 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
630) 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
631) <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
632) equivalent of hitting the STOP button).</p><p>
633) 
634) Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox bug
635) 409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing
636) 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>
637) are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content
638) Policy</a> should prevent such code from performing network activity within
639) the current tab, but activity that happens via a popup window or via a
640) Javascript redirect can still slip by. For this reason, Torbutton blocks
641) popups by checking for a valid <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener" target="_top">window.opener</a>
642) attribute in <code class="function">torbutton_check_progress()</code>. If the window
643) has an opener from a different Tor state, its load is blocked. The content
644) policy also takes similar action to prevent Javascript redirects. This also
645) has the side effect/feature of preventing the user from following any links
646) from a page loaded in an opposite Tor state.
647) 
648) </p><p>
649) This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
650) </p></div><div class="sect2" title="5.4. Hook Dangerous Javascript"><div class="titlepage"><div><div><h3 class="title"><a id="jshooks"></a>5.4. Hook Dangerous Javascript</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js" target="_top">Javascript
651) hooking code</a>. This is done in the chrome in
652) <code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
653) <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
654) 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
655) javascript: urls).
656) 
657) In the Firefox 2 days, this option did a lot more than
658) it does now. It used to be responsible for timezone and improved useragent
659) spoofing, and history object cloaking. However, now it only provides
660) obfuscation of the <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
661) object to mask your browser and desktop resolution.
662) The resolution hooks
663) effectively make the Firefox browser window appear to websites as if the renderable area
664) takes up the entire desktop, has no toolbar or other GUI element space, and
665) the desktop itself has no toolbars.
666) These hooks drastically reduce the amount of information available to do <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to
667) meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
668) requirements. Unfortunately, Gregory Fleischer discovered it is still possible
669) 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>
670) or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html" target="_top">Components.lookupMethod</a>.
671) We are still looking for a workaround as of Torbutton 1.2.5.
672) 
673) 
674) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

675) </p></div><div class="sect2" title="5.5. Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2960649"></a>5.5. Resize windows to multiples of 50px during Tor usage (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

676) 
677) This option drastically cuts down on the number of distinct anonymity sets
678) that divide the Tor web userbase. Without this setting, the dimensions for a
679) typical browser window range from 600-1200 horizontal pixels and 400-1000
680) vertical pixels, or about 600x600 = 360000 different sets. Resizing the
681) browser window to multiples of 50 on each side reduces the number of sets by
682) 50^2, bringing the total number of sets to 144. Of course, the distribution
683) among these sets are not uniform, but scaling by 50 will improve the situation
684) due to this non-uniformity for users in the less common resolutions.
685) Obviously the ideal situation would be to lie entirely about the browser
686) window size, but this will likely cause all sorts of rendering issues, and is
687) also not implementable in a foolproof way from extension land.
688) 
689) </p><p>
690) 
691) The implementation of this setting is spread across a couple of different
692) locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">browser
693) overlay</a>. Since resizing minimized windows causes them to be restored,
694) and since maximized windows remember their previous size to the pixel, windows
695) must be resized before every document load (at the time of browser tagging)
696) via <code class="function">torbutton_check_round()</code>, called by
697) <code class="function">torbutton_update_tags()</code>. To prevent drift, the extension
698) tracks the original values of the windows and uses this to perform the
699) rounding on document load. In addition, to prevent the user from resizing a
700) window to a non-50px multiple, a resize listener
701) (<code class="function">torbutton_do_resize()</code>) is installed on every new browser
702) window to record the new size and round it to a 50px multiple while Tor is
703) enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
704) are set. This ensures that there is no discrepancy between the 50 pixel cutoff
705) and the actual renderable area of the browser (so that it is not possible to
706) infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
707) 
708) </p><p>
709) This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
Mike Perry Update design html.

Mike Perry authored 13 years ago

710) </p></div><div class="sect2" title="5.6. Disable Updates During Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2952949"></a>5.6. Disable Updates During Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

711) update settings</a> during Tor
712)   usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
713) <span class="command"><strong>app.update.enabled</strong></span>,
714)   <span class="command"><strong>app.update.auto</strong></span>, and
715) <span class="command"><strong>browser.search.update</strong></span>.  These prevent the
716)   browser from updating extensions, checking for Firefox upgrades, and
717)   checking for search plugin updates while Tor is enabled.
718)   </p><p>
719) This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

720) </p></div><div class="sect2" title="5.7. Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936606"></a>5.7. Redirect Torbutton Updates Via Tor (recommended)</h3></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

721) 
722) <a class="ulink" href="https://developer.mozilla.org/en/nsIProtocolProxyFilter" target="_top">nsIProtocolProxyFilter</a>
723) in order to redirect all version update checks and Torbutton update downloads
724) via Tor, regardless of if Tor is enabled or not. This was done both to address
725) 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
726) help censored users meet the <a class="link" href="#undiscoverability">Tor
727) Undiscoverability</a> requirement.
728) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

729)   </p></div><div class="sect2" title="5.8. Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936650"></a>5.8. Disable Search Suggestions during Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

730) 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>
731) during Tor usage.
732) This governs if you get Google search suggestions during Tor
733) usage. Your Google cookie is transmitted with google search suggestions, hence
734) this is recommended to be disabled.
735) 
736) </p><p>
737) While this setting doesn't satisfy any Torbutton requirements, the fact that
738) cookies are transmitted for partially typed queries does not seem desirable
739) for Tor usage.
Mike Perry Update design html.

Mike Perry authored 13 years ago

740) </p></div><div class="sect2" title="5.9. Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936689"></a>5.9. Disable livemarks updates during Tor usage (recommended)</h3></div></div></div><p>Option:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

741)    </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>
742)   </p><p>
743) 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
744) Tor usage. Because people often have very personalized Livemarks (such as RSS
745) feeds of Wikipedia articles they maintain, etc). This is accomplished both by
746) <a class="link" href="#livemarks" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js">wrapping the livemark-service component</a> and
747) 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
748) service</a> when Tor is enabled.
749) 
750) </p><p>
751) This helps satisfy the <a class="link" href="#isolation">Network
752) Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
753) Preservation</a> requirements.
Mike Perry Update design html.

Mike Perry authored 13 years ago

754) </p></div><div class="sect2" title="5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936761"></a>5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

755)    </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>
756)   </p><p>
757) 
758) These settings prevent file urls from performing network operations during the
759) respective Tor states. Firefox 2's implementation of same origin policy allows
760) file urls to read and <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/" target="_top">submit
761) arbitrary files from the local filesystem</a> to arbitrary websites. To
762) make matters worse, the 'Content-Disposition' header can be injected
763) arbitrarily by exit nodes to trick users into running arbitrary html files in
764) 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
765) resources from File urls during the appropriate Tor state.
766) 
767) </p><p>
768) 
769) This preference helps to ensure Tor's <a class="link" href="#isolation">Network
770) Isolation</a> requirement, by preventing file urls from executing network
771) operations in opposite Tor states. Also, allowing pages to submit arbitrary
772) files to arbitrary sites just generally seems like a bad idea.
773) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

774) </p></div><div class="sect2" title="5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936833"></a>5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

775)    </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>
776)   </p><p>
777) 
778) These settings cause Torbutton to enumerate through all windows and close all
779) tabs in each window for the appropriate Tor state. This code can be found in
780) <code class="function">torbutton_update_status()</code>.  The main reason these settings
781) exist is as a backup mechanism in the event of any Javascript or content policy
782) leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
783) 409737</a>.  Torbutton currently tries to block all Javascript network
784) activity via the content policy, but until that bug is fixed, there is some
785) risk that there are alternate ways to bypass the policy. This option is
786) available as an extra assurance of <a class="link" href="#isolation">Network
787) Isolation</a> for those who would like to be sure that when Tor is toggled
788) all page activity has ceased. It also serves as a potential future workaround
789) in the event a content policy failure is discovered, and provides an additional
790) level of protection for the <a class="link" href="#disk">Disk Avoidance</a>
791) protection so that browser state is not sitting around waiting to be swapped
792) out longer than necessary.
793) 
794) </p><p>
795) While this setting doesn't satisfy any Torbutton requirements, the fact that
796) cookies are transmitted for partially typed queries does not seem desirable
797) for Tor usage.
Mike Perry Update design html.

Mike Perry authored 13 years ago

798) </p></div><div class="sect2" title="5.12. Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936914"></a>5.12. Isolate Access to History navigation to Tor state (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

799) This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener" target="_top">nsISHistoryListener</a>
800) attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">sessionHistory</a> of 
801) of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation" target="_top">webNavigatator</a>.
802) The nsIShistoryListener is instantiated with a reference to the containing
803) browser window and blocks the back, forward, and reload buttons on the browser
804) navigation bar when Tor is in an opposite state than the one to load the
805) current tab. In addition, Tor clears the session history during a new document
806) load if this setting is enabled. 
807) 
808)   </p><p>
809) 
810) This is marked as a crucial setting in part
811) because Javascript access to the history object is indistinguishable from 
812) user clicks, and because
813) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
814) 409737</a> allows javascript to execute in opposite Tor states, javascript
815) can issue reloads after Tor toggle to reveal your original IP. Even without
816) this bug, however, Javascript is still able to access previous pages in your
817) session history that may have been loaded under a different Tor state, to
818) attempt to correlate your activity.
819) 
820)    </p><p>
821) 
822) This setting helps to fulfill Torbutton's <a class="link" href="#state">State
823) Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
824) requirements.
825) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

826)    </p></div><div class="sect2" title="5.13. History Access Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2936998"></a>5.13. History Access Settings</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

827)   </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>
828)   </p><p>These four settings govern the behavior of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js" target="_top">components/ignore-history.js</a>
829) history blocker component mentioned above. By hooking the browser's view of
830) 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>
831) 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>
832) components, this mechanism defeats all document-based <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure
833) attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only attacks</a>.
834) 
835) The component also hooks functions involved in writing history to disk via
836) both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History" target="_top">Places
837) Database</a> and the older Firefox 2 mechanisms.
838) 
839) </p><p>
840) 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 html.

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

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

Mike Perry authored 13 years ago

846) </p></div><div class="sect2" title="5.15. Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2978657"></a>5.15. Block Password+Form saving during Tor/Non-Tor</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

847)   </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>
848)   </p><p>These settings govern if Torbutton disables
849) <span class="command"><strong>browser.formfill.enable</strong></span>
850) and <span class="command"><strong>signon.rememberSignons</strong></span> during Tor and Non-Tor usage.
851) Since form fields can be read at any time by Javascript, this setting is a lot
852) more important than it seems.
853) </p><p>
854) 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 html.

Mike Perry authored 13 years ago

855) </p></div><div class="sect2" title="5.16. Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2978718"></a>5.16. Block Tor disk cache and clear all cache on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

856)   </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>
857) on Tor toggle to remove all entries from the cache. In addition, this setting
858) 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.
859) </p><p>
860) 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 html.

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

862) causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>,
863) <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and
864) <a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage.
865) </p><p>
866) 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 html.

Mike Perry authored 13 years ago

867) </p></div><div class="sect2" title="5.18. Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2978820"></a>5.18. Clear Cookies on Tor Toggle</h3></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

868)   </p><p>
869) 
870) 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
871) every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
872) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
873) which prevents them from being written to disk. 
874) 
875) </p><p>
876) 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 html.

Mike Perry authored 13 years ago

877) </p></div><div class="sect2" title="5.19. Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h3 class="title"><a id="id2978871"></a>5.19. Store Non-Tor cookies in a protected jar</h3></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

878)   </p><p>
879) 
880) This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
881) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
882) before restoring the jar.
883) </p><p>
884) This setting also sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
885) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
886) which prevents them from being written to disk. 
887) 
888) </p><p>
889) 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 html.

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

891)   </p><p>
892) 
893) This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
894) both Tor and Non-Tor cookies into protected jars.
895) </p><p>
896) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

897) </p></div><div class="sect2" title="5.21. Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2978967"></a>5.21. Manage My Own Cookies (dangerous)</h3></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
898) cookie prefs all to false.</p></div><div class="sect2" title="5.22. Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2978982"></a>5.22. Disable DOM Storage during Tor usage (crucial)</h3></div></div></div><div class="sect2" title="5.22.1. Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h3 class="title"><a id="id2978984"></a>5.22.1. Do not write Tor/Non-Tor cookies to disk</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

899)   </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>
900)   </p><p>
901) 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>
902) to 2 during the appropriate Tor state, and to store cookies acquired in that
903) state into a Javascript
904) <a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X" target="_top">E4X</a>
905) object as opposed to writing them to disk.
906) </p><p>
907) This allows Torbutton to provide an option to preserve a user's 
908) cookies while still satisfying the <a class="link" href="#disk">Disk Avoidance</a>
909) requirement.
910) </p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span>
911)   </p><p>
912) 
913) This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor
914) usage to prevent 
915) <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from
916)   being used to store persistent information across Tor states.</p><p>
917) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

918) </p></div><div class="sect2" title="5.23. Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979086"></a>5.23. Clear HTTP Auth on Tor Toggle (recommended)</h3></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

919)   </p><p>
920) This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager" target="_top">nsIHttpAuthManager.clearAll()</a>
921) every time Tor is toggled.
922) </p><p>
923) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

924) </p></div><div class="sect2" title="5.24. Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h3 class="title"><a id="id2979123"></a>5.24. Clear cookies on Tor/Non-Tor shutdown</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

925)   </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
926) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
927) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
928) for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
929) <code class="function">https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</code> and use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a>
930) to clear out all cookies and all cookie jars upon shutdown.  </p><p>
931) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

932) </p></div><div class="sect2" title="5.25. Reload cookie jar/clear cookies on Firefox crash"><div class="titlepage"><div><div><h3 class="title"><a id="id2979178"></a>5.25. Reload cookie jar/clear cookies on Firefox crash</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

933)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.reload_crashed_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr></table><p>
934)   </p><p>This is no longer a user visible option, and is enabled by default. In
935) the event of a crash, the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">components/crash-observer.js</a> 
936)   component will notify the Chrome (via the
937)   <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref and a <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">pref
938) observer</a> in
939) the chrome that listens for this update), and Torbutton will load the
940)   correct jar for the current Tor state via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a>
941)   component.</p><p>
942) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
943) crashes.
Mike Perry Update design html.

Mike Perry authored 13 years ago

944) </p></div><div class="sect2" title="5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2979253"></a>5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

945)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.restore_tor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
946)   </p><p>This option works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
947)   to set the Tor state after a crash is detected (via the 
948)   <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref). To confirm for
949) false positives (such as session restore failures, upgrade, normal
950) session restore, etc), Torbutton also sets the pref
951) extensions.torbutton.normal_exit during
952) Firefox exit and checks this value as well during startup.  
953) </p><p>
954) 
955) Since the Tor state after a Firefox crash is unknown/indeterminate, this
956) setting helps to satisfy the <a class="link" href="#state">State Separation</a>
957) requirement in the event of Firefox crashes by ensuring all cookies,
958) settings and saved sessions are reloaded from a fixed Tor state.
959)  
Mike Perry Update design html.

Mike Perry authored 13 years ago

960) </p></div><div class="sect2" title="5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State"><div class="titlepage"><div><div><h3 class="title"><a id="id2979325"></a>5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

961)   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.startup_state</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.noncrashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
962)   </p><p>This option also works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
963)   to set the Tor state after a normal startup is detected (via the 
964)   <span class="command"><strong>extensions.torbutton.noncrashed</strong></span> pref). To confirm for
965) false positives
966) (such as session restore failures, etc), Torbutton also sets the pref
967) extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
968) Firefox exit and checks this value as well during startup.
969)   
Mike Perry Update design html.

Mike Perry authored 13 years ago

970) </p></div><div class="sect2" title="5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h3 class="title"><a id="id2979384"></a>5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</h3></div></div></div><p>Options: 
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

971)   </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>
972)   </p><p>If these options are enabled, the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js" target="_top">replacement nsSessionStore.js</a>
973)   component checks the <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tabs before writing them
974)   out. If the tag is from a blocked Tor state, the tab is not written to disk.
975)   </p><p>
976) This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
977) requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
978) crashes.
979) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

980) </p></div><div class="sect2" title="5.29. Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979449"></a>5.29. Set user agent during Tor usage (crucial)</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

981)    </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>
982)    </p><p>On face, user agent switching appears to be straight-forward in Firefox.
983) It provides several options for controlling the browser user agent string:
984) <span class="command"><strong>general.appname.override</strong></span>,
985) <span class="command"><strong>general.appversion.override</strong></span>,
986) <span class="command"><strong>general.platform.override</strong></span>,
987) <span class="command"><strong>general.oscpu.override</strong></span>,
988) <span class="command"><strong>general.productSub.override</strong></span>,
989) <span class="command"><strong>general.buildID.override</strong></span>,
990) <span class="command"><strong>general.useragent.override</strong></span>,
991) <span class="command"><strong>general.useragent.vendor</strong></span>, and
992) <span class="command"><strong>general.useragent.vendorSub</strong></span>. If
993) the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is
994) true, Torbutton copies all of the other above prefs into their corresponding
995) browser preferences during Tor usage.</p><p>
996) 
997) It also turns out that it is possible to detect the original Firefox version
998) by <a class="ulink" href="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/" target="_top">inspecting
999) certain resource:// files</a>. These cases are handled by Torbutton's
1000) <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
1001) 
1002) </p><p>
1003) This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

1004) </p></div><div class="sect2" title="5.30. Spoof US English Browser"><div class="titlepage"><div><div><h3 class="title"><a id="id2979623"></a>5.30. Spoof US English Browser</h3></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.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>
1006) </p><p> This option causes Torbutton to set
1007) <span class="command"><strong>general.useragent.locale</strong></span>
1008) <span class="command"><strong>intl.accept_languages</strong></span> to the value specified in
1009) <span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
1010) <span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
1011) <span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
1012) well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">javascript hooks</a>.
1013)  </p><p>
1014) 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 html.

Mike Perry authored 13 years ago

1015) </p></div><div class="sect2" title="5.31. Don't send referrer during Tor Usage"><div class="titlepage"><div><div><h3 class="title"><a id="id2979716"></a>5.31. Don't send referrer during Tor Usage</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_referer</strong></span>
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1016) </p><p> 
1017) This option causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer" target="_top">network.http.sendSecureXSiteReferrer</a> and
1018) <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendRefererHeader" target="_top">network.http.sendRefererHeader</a> during Tor usage.</p><p>
1019) This setting also does not directly satisfy any Torbutton requirement, but
1020) some may desire to mask their referrer for general privacy concerns.
Mike Perry Update design html.

Mike Perry authored 13 years ago

1021) </p></div><div class="sect2" title="5.32. Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h3 class="title"><a id="id2979756"></a>5.32. Strip platform and language off of Google Search Box queries</h3></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

1022) </p><p> 
1023) 
1024) 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>
1025) component to wrap the Google search plugin. On many platforms, notably Debian
1026) and Ubuntu, the Google search plugin is set to reveal a lot of language and
1027) platform information. This setting strips off that info while Tor is enabled.
1028) 
1029) </p><p>
1030) This setting helps Torbutton to fulfill its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Mike Perry Update design html.

Mike Perry authored 13 years ago

1031) </p></div><div class="sect2" title="5.33. Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h3 class="title"><a id="id2979797"></a>5.33. Automatically use an alternate search engine when presented with a
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1032) Google Captcha</h3></div></div></div><p>Options:
1033) </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>
1034) </p><p>
1035) 
1036) Google's search engine has rate limiting features that cause it to
1037) <a class="ulink" href="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html" target="_top">present
1038) captchas</a> and sometimes even outright ban IPs that issue large numbers
1039) of search queries, especially if a lot of these queries appear to be searching
1040) for software vulnerabilities or unprotected comment areas.
1041) 
1042) </p><p>
1043) 
1044) Despite multiple discussions with Google, we were unable to come to a solution
1045) or any form of compromise that would reduce the number of captchas and
1046) outright bans seen by Tor users issuing regular queries.
1047) 
1048) </p><p>
1049) 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>
1050) http observer to optionally redirect banned or captcha-triggering Google
1051) 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

1052) 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

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

Mike Perry authored 13 years ago

1054) <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

1055) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

1056) </p></div><div class="sect2" title="5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979878"></a>5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h3></div></div></div><p>Options:
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1057) </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>
1058) </p><p>
1059) 
1060) These settings govern if Torbutton attempts to isolate the user's SSL
1061) certificates into separate jars for each Tor state. This isolation is
1062) implemented in <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>,
1063) which calls <code class="function">torbutton_jar_cert_type()</code> and
1064) <code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
1065) 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>.
1066) 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>.
1067) </p><p>
1068) The first time this pref is used, a backup of the user's certificates is
1069) created in their profile directory under the name
1070) <code class="filename">cert8.db.bak</code>. This file can be copied back to
1071) <code class="filename">cert8.db</code> to fully restore the original state of the
1072) user's certificates in the event of any error.
1073) </p><p>
1074) Since exit nodes and malicious sites can insert content elements sourced to
1075) specific SSL sites to query if a user has a certain certificate,
1076) this setting helps to satisfy the <a class="link" href="#state">State
1077) Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Firefox Bug
1078) 435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
1079) is currently not exposed via the preferences UI.
1080) 
1081) </p></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>
1082) 
1083)   </p><div class="sect2" title="6.1. Bugs impacting security"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxSecurity"></a>6.1. Bugs impacting security</h3></div></div></div><p>
1084) 
1085) Torbutton has to work around a number of Firefox bugs that impact its
1086) security. Most of these are mentioned elsewhere in this document, but they
1087) have also been gathered here for reference. In order of decreasing severity,
1088) they are:
1089) 
1090)    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=429070" target="_top">Bug 429070 - exposing
1091) Components.interfaces to untrusted content leaks information about installed
1092) extensions</a><p>
1093) <a class="ulink" href="http://pseudo-flaw.net/" target="_top">Gregory Fleischer</a> demonstrated at Defcon 17 that these interfaces can
1094) also be used to <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html" target="_top">fingerprint
1095) Firefox down the to the minor version</a>. Note that his test has not been
1096) updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This
1097) bug interferes with Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1098)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=280661" target="_top">Bug 280661 - SOCKS proxy server
1099) connection timeout hard-coded</a><p>
1100) 
1101) This bug prevents us from using the Firefox SOCKS layer directly, and
1102) currently requires us to ship an auxiliary HTTP proxy called <a class="ulink" href="http://www.pps.jussieu.fr/~jch/software/polipo/" target="_top">Polipo</a>. If this
1103) patch were landed, we would no longer need to ship Polipo, which has a number
1104) of privacy and security issues of its own (in addition to being unmaintained).
1105) 
1106)     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418986" target="_top">Bug 418986 - window.screen
1107) provides a large amount of identifiable information</a><p>
1108) 
1109) As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of
1110) information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>.
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1111) The most sensative data to anonymity is actually that which is not used in
1112) rendering - such as desktop resolution, and window decoration size.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1113) Currently, there is no way to obscure this information without Javascript
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1114) hooking. In addition, many of this same desktop and window decoration
1115) resolution information is available via <a class="ulink" href="https://developer.mozilla.org/En/CSS/Media_queries" target="_top">CSS Media
1116) Queries</a>, so perhaps some more lower-level rendering controls or
1117) preferences need to be provided. These issues interfere with Torbutton's
1118) ability to fulfill its <a class="link" href="#setpreservation">Anonymity Set
1119) Preservation</a> requirement.
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1120) 
1121)    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Bug 435159 -
1122) nsNSSCertificateDB::DeleteCertificate has race conditions</a><p>
1123) 
1124) In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
1125) the user has installed. Unfortunately, the method call to delete a certificate
1126) from the current certificate database acts lazily: it only sets a variable
1127) that marks a cert for deletion later, and it is not cleared if that
1128) certificate is re-added. This means that if the Tor state is toggled quickly,
1129) that certificate could remain present until it is re-inserted (causing an
1130) error dialog), and worse, it would still be deleted after that.  The lack of
1131) this functionality is considered a Torbutton security bug because cert
1132) isolation is considered a <a class="link" href="#state">State Separation</a>
1133) feature.
1134) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

1135)       </p></li><li class="listitem">Give more visibility into and control over TLS
1136) negotiation
1137)      <p>
1138) 
1139) There are several <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/2482" target="_top">TLS issues
1140) impacting Torbutton security</a>. It is not clear if these should be one
1141) Firefox bug or several, but in particular we need better control over various
1142) aspects of TLS connections. Firefox currently provides no observer capable of
1143) extracting TLS parameters or certificates early enough to cancel a TLS
1144) 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
1145) the ability to <a class="ulink" href="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission" target="_top">have
1146) their certificates audited</a> by a <a class="ulink" href="http://www.networknotary.org/" target="_top">Perspectives</a>-style set of
1147) notaries. The problem with this is that the API observer points do not exist
1148) for any Firefox addon to actually block authentication token submission over a
1149) TLS channel, so every addon to date (including Perspectives) is actually
1150) providing users with notification *after* their authentication tokens have
1151) already been compromised. This obviously needs to be fixed.
1152)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=575230" target="_top">Bug 575230 - Provide option to
Andrew Lewman add in the torbutton design...

Andrew Lewman authored 13 years ago

1153) reduce precision of Date()</a><p>
1154) 
1155) Currently it is possible to <a class="ulink" href="http://arstechnica.com/tech-policy/news/2010/02/firm-uses-typing-cadence-to-finger-unauthorized-users.ars" target="_top">fingerprint
1156) users based on their typing cadence</a> using the high precision timer
1157) available to javascript. Using this same precision, it is possible to compute
1158) an identifier based upon the clock drift of the client from some nominal
1159) source. The latter is not much of a concern for Tor users, as the variable
1160) delay to load and run a page is measured on the order of seconds, but the high
1161) precision timer can still be used to fingerprint aspects of a browser's
1162) javascript engine and processor, and apparently also a user's typing cadence.
1163) This bug hinders Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1164) 
Mike Perry Update FF bugs in design do...

Mike Perry authored 13 years ago

1165)       </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=122752" target="_top">SOCKS
1166) Username/Password Support</a><p>
1167) We need <a class="ulink" href="https://developer.mozilla.org/en/nsIProxyInfo" target="_top">Firefox
1168) APIs</a> or about:config settings to conrol the SOCKS Username and
1169) Password fields. The reason why we need this support is to utilize an (as yet
1170) 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
1171) SOCKS username/password</a>.
1172)     </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

1173) javascript.enabled and docShell.allowJavascript do not disable all event
1174) handlers</a><p>
1175) 
1176) This bug allows pages to execute javascript via addEventListener and perhaps
1177) other callbacks. In order to prevent this bug from enabling an attacker to
1178) break the <a class="link" href="#isolation">Network Isolation</a> requirement,
1179) Torbutton 1.1.13 began blocking popups and history manipulation from different
1180) Tor states.  So long as there are no ways to open popups or redirect the user
1181) to a new page, the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content
1182) policy</a> should block Javascript network access. However, if there are
1183) ways to open popups or perform redirects such that Torbutton cannot block
1184) them, pages may still have free reign to break that requirement and reveal a
1185) user's original IP address.
1186) 
1187)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448743" target="_top">Bug 448743 -
1188) Decouple general.useragent.locale from spoofing of navigator.language</a><p>
1189) 
1190) Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
1191) attribute via <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
1192) these do not work on Firefox 3. It would be ideal to have
1193) a pref to set this value (something like a
1194) <span class="command"><strong>general.useragent.override.locale</strong></span>),
1195) to avoid fragmenting the anonymity set of users of foreign locales. This issue
1196) impedes Torbutton from fully meeting its <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
1197) requirement on Firefox 3.
1198) 
1199)      </p></li></ol></div></div><div class="sect2" title="6.2. Bugs blocking functionality"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxWishlist"></a>6.2. Bugs blocking functionality</h3></div></div></div><p>
1200) The following bugs impact Torbutton and similar extensions' functionality.
1201)    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=445696" target="_top">Bug 445696 -
1202) Extensions cannot determine if firefox is fullScreen</a><p>
1203) 
1204) The windowState property of <a class="ulink" href="https://developer.mozilla.org/en/XUL/window" target="_top">ChromeWindows</a> does not accurately reflect the true
1205) state of the window in some cases on Linux. This causes Torbutton to attempt
1206) to resize maximized and minimized windows when it should not.
1207) 
1208)    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=290456" target="_top">Bug 290456 -
1209) Block/clear Flash MX "cookies" as well</a><p>
1210) 
1211) Today, it is possible to allow plugins if you have a transparent proxy such as
1212) <a class="ulink" href="http://anonymityanywhere.com/incognito/" target="_top">Incognito</a> to prevent proxy bypass. However, flash cookies can still be used to
1213) link your Tor and Non-Tor activity, and this reveal your IP to an adversary
1214) that does so. This can be solved by manually removing your flash cookies (like
1215) <a class="ulink" href="https://addons.mozilla.org/en-US/firefox/addon/6623" target="_top">BetterPrivacy</a> does), but
1216) it would be nice if there was a standard way to do this from a Firefox API.
1217) 
1218)    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869" target="_top">Bug 417869 -
1219) Browser context is difficult to obtain from many XPCOM callbacks</a><p>
1220) 
1221) It is difficult to determine which tabbrowser many XPCOM callbacks originate
1222) from, and in some cases absolutely no context information is provided at all.
1223) While this doesn't have much of an effect on Torbutton, it does make writing
1224) extensions that would like to do per-tab settings and content filters (such as
1225) FoxyProxy) difficult to impossible to implement securely.
1226) 
1227)    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418321" target="_top">Bug 418321 -
1228) Components do not expose disk interfaces</a><p>
1229) 
1230) Several components currently provide no way of reimplementing their disk
1231) access to easily satisfy Torbutton's <a class="link" href="#disk">Disk
1232) Avoidance</a> requirements. Workarounds exist, but they are <a class="link" href="#sessionstore" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js">clunky</a>, and
1233) some of them involve disabling functionality during Tor usage.
1234) 
1235)    </p></li></ol></div></div><div class="sect2" title="6.3. Low Priority Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxMiscBugs"></a>6.3. Low Priority Bugs</h3></div></div></div><p>
1236) The following bugs have an effect upon Torbutton, but are superseded by more
1237) practical and more easily fixable variant bugs above; or have stable, simple
1238) workarounds.
1239)   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435151" target="_top">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</a><p>
1240) 
1241) Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
1242) constructors of classes defined from within the scope of the sandbox, among
1243) other things. This prevents Torbutton from applying the Timezone hooks under
1244) Firefox 3, but a better solution for Torbutton's specific date hooking needs 
1245) would be a fix for the above mentioned Bug 392274. Of course, many more
1246) extensions may be interested in the sandbox hooking functionality working
1247) properly though.
1248) 
1249)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">Bug 440892 -
1250) network.protocol-handler.warn-external are ignored</a><p>
1251) 
1252) Sometime in the Firefox 3 development cycle, the preferences that governed
1253) warning a user when external apps were launched got disconnected from the code
1254) that does the launching. Torbutton depended on these prefs to prevent websites
1255) from launching specially crafted documents and application arguments that
1256) 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
1257) popup before launching external apps while Tor is enabled. While this works,
1258) it would be nice if these prefs were either fixed or removed.
1259) 
1260)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">Bug 437014 -
1261) nsIContentPolicy::shouldLoad no longer called for favicons</a><p>
1262) 
1263) Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
1264) loads. Torbutton had relied on this call to block favicon loads for opposite
1265) Tor states. The workaround it employs for Firefox 3 is to cancel the request
1266) when it arrives in the <span class="command"><strong>torbutton_http_observer</strong></span> used for
1267) blocking full page plugin loads. This seems to work just fine, but is a bit
1268) dirty.
1269) 
1270)     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">Bug 309524</a>
1271) and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">Bug
1272) 380556</a> - nsIContentPolicy::shouldProcess is not called.
1273)      <p>
1274) 
1275) This is a call that would be useful to develop a better workaround for the
1276) allowPlugins issue above. If the content policy were called before a URL was
1277) handed over to a plugin or helper app, it would make the workaround for the
1278) above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
1279) the others though, but it might be nice to have this API as a backup.
1280) 
1281)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">Bug 401296 - docShell.allowPlugins
1282) 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>?)
1283)      <p>
1284) 
1285) Similar to the javascript plugin disabling attribute, the plugin disabling
1286) attribute is also not perfect — it is ignored for direct links to plugin
1287) handled content, as well as meta-refreshes to plugin handled content.  This
1288) requires Torbutton to listen to a number of different http events to intercept
1289) plugin-related mime type URLs and cancel their requests. Again, since plugins
1290) are quite horrible about obeying proxy settings, loading a plugin pretty much
1291) ensures a way to break the <a class="link" href="#isolation">Network Isolation</a>
1292) requirement and reveal a user's original IP address. Torbutton's code to
1293) perform this workaround has been subverted at least once already by Kyle
1294) Williams.
1295) 
1296)      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598" target="_top">Bug 419598 - 'var
1297) Date' is deletable</a><p>
1298) 
1299) Based on Page 62 of the <a class="ulink" href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf" target="_top">ECMA-262
1300) Javascript spec</a>, it seems like it should be possible to do something
1301) like the following to prevent the Date object from being unmasked:
1302) </p><pre class="screen">
1303) with(window) {
1304)     var Date = fakeDate;
1305)     var otherVariable = 42;
1306) }
1307) 
1308) delete window.Date; // Should fail. Instead succeeds, revealing original Date.
1309) delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
1310) </pre><p>
1311) 
1312) From the ECMA-262 spec:
1313) 
1314) </p><div class="blockquote"><blockquote class="blockquote">
1315) If the variable statement occurs inside a FunctionDeclaration, the variables
1316) are defined with function-local scope in that function, as described in
1317) s10.1.3. Otherwise, they are defined with global scope (that is, they are
1318) created as members of the global object, as described in 10.1.3) using
1319) property attributes { DontDelete }. Variables are created when the execution
1320) scope is entered. A Block does not define a new execution scope. Only Program
1321) and FunctionDeclaration produce a new scope. Variables are initialized to
1322) undefined when created. A variable with an Initialiser is assigned the value
1323) of its AssignmentExpression when the VariableStatement is executed, not when
1324) the variable is created.
1325) </blockquote></div><p>
1326) 
1327) In fact, this is exactly how the with statement with a variable declaration
1328) behaves <span class="emphasis"><em>for all other variables other than ones that shadow system
1329) variables</em></span>. Some variables (such as
1330) <span class="command"><strong>window.screen</strong></span>, and <span class="command"><strong>window.history</strong></span>) can't
1331) even be shadowed in this way, and give an error about lacking a setter. If
1332) such shadowing were possible, it would greatly simplify the Javascript hooking
1333) code, which currently relies on undocumented semantics of
1334) <span class="command"><strong>__proto__</strong></span> to copy the original values in the event of a
1335) delete. This <span class="command"><strong>__proto__</strong></span> hack unfortunately does not work for
1336) the Date object though.
1337) 
1338)      </p></li></ol></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>
1339) 
1340) The purpose of this section is to cover all the known ways that Tor browser
1341) security can be subverted from a penetration testing perspective. The hope
1342) is that it will be useful both for creating a "Tor Safety Check"
1343) page, and for developing novel tests and actively attacking Torbutton with the
1344) goal of finding vulnerabilities in either it or the Mozilla components,
1345) interfaces and settings upon which it relies.
1346) 
1347)   </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>
1348) 
1349) Torbutton is a complicated piece of software. During development, changes to
1350) one component can affect a whole slough of unrelated features.  A number of
1351) aggregated test suites exist that can be used to test for regressions in
1352) Torbutton and to help aid in the development of Torbutton-like addons and
1353) other privacy modifications of other browsers. Some of these test suites exist
1354) as a single automated page, while others are a series of pages you must visit
1355) individually. They are provided here for reference and future regression
1356) testing, and also in the hope that some brave soul will one day decide to
1357) combine them into a comprehensive automated test suite.
1358) 
1359)      </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>
1360) 
1361) Decloak.net is the canonical source of plugin and external-application based
1362) 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
1363) use to test their anonymity systems.
1364) 
1365)        </p></li><li class="listitem"><a class="ulink" href="http://deanonymizer.com/" target="_top">Deanonymizer.com</a><p>
1366) 
1367) Deanonymizer.com is another automated test suite that tests for proxy bypass
1368) and other information disclosure vulnerabilities. It is maintained by Kyle
1369) Williams, the author of <a class="ulink" href="http://www.janusvm.com/" target="_top">JanusVM</a>
1370) and <a class="ulink" href="http://www.januspa.com/" target="_top">JanusPA</a>.
1371) 
1372)        </p></li><li class="listitem"><a class="ulink" href="https://www.jondos.de/en/anontest" target="_top">JonDos
1373) AnonTest</a><p>
1374) 
1375) The <a class="ulink" href="https://www.jondos.de" target="_top">JonDos people</a> also provide an
1376) anonymity tester. It is more focused on HTTP headers than plugin bypass, and
1377) points out a couple of headers Torbutton could do a better job with
1378) obfuscating.
1379) 
1380)        </p></li><li class="listitem"><a class="ulink" href="http://browserspy.dk" target="_top">Browserspy.dk</a><p>
1381) 
1382) Browserspy.dk provides a tremendous collection of browser fingerprinting and
1383) general privacy tests. Unfortunately they are only available one page at a
1384) time, and there is not really solid feedback on good vs bad behavior in
1385) the test results.
1386) 
1387)        </p></li><li class="listitem"><a class="ulink" href="http://analyze.privacy.net/" target="_top">Privacy
1388) Analyzer</a><p>
1389) 
1390) The Privacy Analyzer provides a dump of all sorts of browser attributes and
1391) settings that it detects, including some information on your origin IP
1392) address. Its page layout and lack of good vs bad test result feedback makes it
1393) not as useful as a user-facing testing tool, but it does provide some
1394) interesting checks in a single page.
1395) 
1396)        </p></li><li class="listitem"><a class="ulink" href="http://ha.ckers.org/mr-t/" target="_top">Mr. T</a><p>
1397) 
1398) Mr. T is a collection of browser fingerprinting and deanonymization exploits
1399) discovered by the <a class="ulink" href="http://ha.ckers.org" target="_top">ha.ckers.org</a> crew
1400) and others. It is also not as user friendly as some of the above tests, but it
1401) is a useful collection.
1402) 
1403)        </p></li><li class="listitem">Gregory Fleischer's <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">Torbutton</a> and
1404) <a class="ulink" href="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html" target="_top">Defcon
1405) 17</a> Test Cases
1406)        <p>
1407) 
1408) Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy
1409) issues for the past 2 years. He has an excellent collection of all his test
1410) cases that can be used for regression testing. In his Defcon work, he
1411) demonstrates ways to infer Firefox version based on arcane browser properties.
1412) We are still trying to determine the best way to address some of those test
1413) cases.
1414) 
1415)        </p></li><li class="listitem"><a class="ulink" href="https://torcheck.xenobite.eu/index.php" target="_top">Xenobite's
1416) TorCheck Page</a><p>
1417) 
1418) This page checks to ensure you are using a valid Tor exit node and checks for
1419) some basic browser properties related to privacy. It is not very fine-grained
1420) or complete, but it is automated and could be turned into something useful
1421) with a bit of work.
1422) 
1423)        </p></li></ol></div><p>
Mike Perry Update design html.

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

1425) 
1426) The tests in this section are geared towards a page that would instruct the
1427) user to toggle their Tor state after the fetch and perform some operations:
1428) mouseovers, stray clicks, and potentially reloads.
1429) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

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

Mike Perry authored 13 years ago

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

Andrew Lewman authored 13 years ago

1439) 
1440) Javascript can set timers and register event handlers in the hopes of fetching
1441) URLs after the user has toggled Torbutton. 
Mike Perry Update design html.

Mike Perry authored 13 years ago

1442)     </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2981042"></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

1443) 
1444) Even if Javascript is disabled, CSS is still able to 
1445) <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like
1446) windows</a>
1447) via the 'onmouseover' CSS attribute, which can cause arbitrary browser
1448) activity as soon as the mouse enters into the content window. It is also
1449) possible for meta-refresh tags to set timers long enough to make it likely
1450) that the user has toggled Tor before fetching content.
1451) 
1452)     </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>
1453) 
1454) The idea behind active testing is to discover vulnerabilities in Torbutton to
1455) bypass proxy settings, run script in an opposite Tor state, store unique
1456) identifiers, leak location information, or otherwise violate <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. Torbutton has ventured out
1457) into a strange and new security landscape. It depends on Firefox mechanisms
1458) that haven't necessarily been audited for security, certainly not for the
1459) threat model that Torbutton seeks to address. As such, it and the interfaces
1460) it depends upon still need a 'trial by fire' typical of new technologies. This
1461) section of the document was written with the intention of making that period
1462) as fast as possible. Please help us get through this period by considering
1463) these attacks, playing with them, and reporting what you find (and potentially
1464) submitting the test cases back to be run in the standard batch of Torbutton
1465) tests.
1466) 
Mike Perry Update design html.

Mike Perry authored 13 years ago

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