torbutton/en/design/index.html.en (480ad41c9) - tor-webwml.git

480ad41c9b6f145a66443330ba48bff9342600f4

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">`
Update Torbutton design doc. 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"><<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>></code></p></div></div></div></div><div><p class="pubdate">Apr 4 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2657298">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#components">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#hookedxpcom">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2682565">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2661538">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2683477">3.1. XUL Windows and Overlays</a></span></dt><dt><span class="sect2"><a href="#id2679782">3.2. Major Chrome Observers</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2682210">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2678571">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2677555">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2671739">4.3. Settings Update</a></span></dt><dt><span class="sect2"><a href="#preferences">4.4. Firefox preferences touched during Toggle</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2684076">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2686457">5.1. Proxy Settings</a></span></dt><dt><span class="sect2"><a href="#id2685583">5.2. Dynamic Content Settings</a></span></dt><dt><span class="sect2"><a href="#id2695607">5.3. History and Forms Settings</a></span></dt><dt><span class="sect2"><a href="#id2695921">5.4. Cache Settings</a></span></dt><dt><span class="sect2"><a href="#id2696030">5.5. Cookie and Auth Settings</a></span></dt><dt><span class="sect2"><a href="#id2696343">5.6. Startup Settings</a></span></dt><dt><span class="sect2"><a href="#id2696457">5.7. Shutdown Settings</a></span></dt><dt><span class="sect2"><a href="#id2696517">5.8. Header Settings</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#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="#id2698010">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="id2657298"></a>1. Introduction</h2></div></div></div><p>
add in the torbutton design... Andrew Lewman authored 13 years ago	`4) 5) This document describes the goals, operation, and testing procedures of the`
Update Torbutton design doc. Mike Perry authored 13 years ago	`6) Torbutton Firefox extension. It is current as of Torbutton 1.3.2.`
add in the torbutton design... Andrew Lewman authored 13 years ago	7) 8) </p><div class="sect2" title="1.1. Adversary Model"><div class="titlepage"><div><div><h3 class="title"><a id="adversary"></a>1.1. Adversary Model</h3></div></div></div><p> 9) 10) A Tor web browser adversary has a number of goals, capabilities, and attack 11) types that can be used to guide us towards a set of requirements for the 12) Torbutton extension. Let's start with the goals. 13) 14) </p><div class="sect3" title="Adversary Goals"><div class="titlepage"><div><div><h4 class="title"><a id="adversarygoals"></a>Adversary Goals</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Bypassing proxy settings</strong></span><p>The adversary's primary goal is direct compromise and bypass of 15) Tor, causing the user to directly connect to an IP of the adversary's 16) choosing.</p></li><li class="listitem"><span class="command"><strong>Correlation of Tor vs Non-Tor Activity</strong></span><p>If direct proxy bypass is not possible, the adversary will likely 17) happily settle for the ability to correlate something a user did via Tor with 18) their non-Tor activity. This can be done with cookies, cache identifiers, 19) javascript events, and even CSS. Sometimes the fact that a user uses Tor may 20) be enough for some authorities.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p> 21) The adversary may also be interested in history disclosure: the ability to 22) query a user's history to see if they have issued certain censored search 23) queries, or visited censored sites. 24) </p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p> 25) 26) Location information such as timezone and locality can be useful for the 27) adversary to determine if a user is in fact originating from one of the 28) regions they are attempting to control, or to zero-in on the geographical 29) location of a particular dissident or whistleblower. 30) 31) </p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p> 32) 33) Anonymity set reduction is also useful in attempting to zero in on a 34) particular individual. If the dissident or whistleblower is using a rare build 35) of Firefox for an obscure operating system, this can be very useful 36) information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>. 37) 38) </p></li><li class="listitem"><span class="command"><strong>History records and other on-disk 39) information</strong></span><p> 40) In some cases, the adversary may opt for a heavy-handed approach, such as 41) seizing the computers of all Tor users in an area (especially after narrowing 42) the field by the above two pieces of information). History records and cache 43) data are the primary goals here. 44) </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Positioning"><div class="titlepage"><div><div><h4 class="title"><a id="adversarypositioning"></a>Adversary Capabilities - Positioning</h4></div></div></div><p> 45) The adversary can position themselves at a number of different locations in 46) order to execute their attacks. 47) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p> 48) The adversary can run exit nodes, or alternatively, they may control routers 49) upstream of exit nodes. Both of these scenarios have been observed in the 50) wild. 51) </p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p> 52) The adversary can also run websites, or more likely, they can contract out 53) ad space from a number of different adservers and inject content that way. For 54) some users, the adversary may be the adservers themselves. It is not 55) inconceivable that adservers may try to subvert or reduce a user's anonymity 56) through Tor for marketing purposes. 57) </p></li><li class="listitem"><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p> 58) The adversary can also inject malicious content at the user's upstream router 59) when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor 60) activity. 61) </p></li><li class="listitem"><span class="command"><strong>Physical Access</strong></span><p> 62) Some users face adversaries with intermittent or constant physical access. 63) Users in Internet cafes, for example, face such a threat. In addition, in 64) countries where simply using tools like Tor is illegal, users may face 65) confiscation of their computer equipment for excessive Tor usage or just 66) general suspicion. 67) </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Attacks"><div class="titlepage"><div><div><h4 class="title"><a id="attacks"></a>Adversary Capabilities - Attacks</h4></div></div></div><p> 68) 69) The adversary can perform the following attacks from a number of different 70) positions to accomplish various aspects of their goals. It should be noted 71) that many of these attacks (especially those involving IP address leakage) are 72) often performed by accident by websites that simply have Javascript, dynamic 73) CSS elements, and plugins. Others are performed by adservers seeking to 74) correlate users' activity across different IP addresses, and still others are 75) performed by malicious agents on the Tor network and at national firewalls. 76) 77) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Inserting Javascript</strong></span><p> 78) If not properly disabled, Javascript event handlers and timers 79) can cause the browser to perform network activity after Tor has been disabled, 80) thus allowing the adversary to correlate Tor and Non-Tor activity and reveal 81) a user's non-Tor IP address. Javascript 82) also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure attacks</a>: 83) to query the history via the different attributes of 'visited' links to search
Update Torbutton design doc. Mike Perry authored 13 years ago	`84) for particular Google queries, sites, or even to <a class="ulink" href="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/" target="_top">profile`
add in the torbutton design... Andrew Lewman authored 13 years ago	85) users based on gender and other classifications</a>. Finally, 86) Javascript can be used to query the user's timezone via the 87) <code class="function">Date()</code> object, and to reduce the anonymity set by querying 88) the <code class="function">navigator</code> object for operating system, CPU, locale, 89) and user agent information. 90) </p></li><li class="listitem"><span class="command"><strong>Inserting Plugins</strong></span><p> 91) 92) Plugins are abysmal at obeying the proxy settings of the browser. Every plugin 93) capable of performing network activity that the author has 94) investigated is also capable of performing network activity independent of 95) browser proxy settings - and often independent of its own proxy settings. 96) Sites that have plugin content don't even have to be malicious to obtain a 97) user's 98) Non-Tor IP (it usually leaks by itself), though <a class="ulink" href="http://decloak.net" target="_top">plenty of active 99) exploits</a> are possible as well. In addition, plugins can be used to store unique identifiers that are more 100) difficult to clear than standard cookies. 101) <a class="ulink" href="http://epic.org/privacy/cookies/flash.html" target="_top">Flash-based 102) cookies</a> fall into this category, but there are likely numerous other 103) examples. 104) 105) </p></li><li class="listitem"><span class="command"><strong>Inserting CSS</strong></span><p> 106) 107) CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's 108) Non-Tor IP address, via the usage of 109) <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">CSS 110) popups</a> - essentially CSS-based event handlers that fetch content via 111) CSS's onmouseover attribute. If these popups are allowed to perform network 112) activity in a different Tor state than they were loaded in, they can easily 113) correlate Tor and Non-Tor activity and reveal a user's IP address. In 114) addition, CSS can also be used without Javascript to perform <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only history disclosure 115) attacks</a>. 116) </p></li><li class="listitem"><span class="command"><strong>Read and insert cookies</strong></span><p> 117) 118) An adversary in a position to perform MITM content alteration can inject 119) document content elements to both read and inject cookies for 120) arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this 121) sort of <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html" target="_top">active 122) sidejacking</a>. 123) 124) </p></li><li class="listitem"><span class="command"><strong>Create arbitrary cached content</strong></span><p> 125) 126) Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique 127) identifiers</a>. Since by default the cache has no same-origin policy, 128) these identifiers can be read by any domain, making them an ideal target for 129) adserver-class adversaries. 130) 131) </p></li><li class="listitem"><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser 132) attributes</strong></span><p> 133) 134) There is an absurd amount of information available to websites via attributes 135) of the browser. This information can be used to reduce anonymity set, or even 136) <a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">uniquely 137) fingerprint individual users</a>. </p><p> 138) For illustration, let's perform a 139) back-of-the-envelope calculation on the number of anonymity sets for just the 140) resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and 141) <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
Update Torbutton design doc. Mike Perry authored 13 years ago	`142) objects. 143) 144) 145) 146) Browser window resolution information provides something like`
add in the torbutton design... Andrew Lewman authored 13 years ago	147) (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution 148) information contributes about another factor of 5 (for about 5 resolutions in 149) typical use). In addition, the dimensions and position of the desktop taskbar 150) are available, which can reveal hints on OS information. This boosts the count 151) by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE 152) and Gnome, and None). Subtracting the browser content window 153) size from the browser outer window size provide yet more information. 154) Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
Update Torbutton design doc. Mike Perry authored 13 years ago	`155) 2<sup>3</sup>=8). Interface effects such as title bar font size`
add in the torbutton design... Andrew Lewman authored 13 years ago	`156) and window manager settings gives a factor of about 9 (say 3 common font sizes`
Update Torbutton design doc. Mike Perry authored 13 years ago	`157) for the title bar and 3 common sizes for browser GUI element fonts).`
add in the torbutton design... Andrew Lewman authored 13 years ago	`158) Multiply this all out, and you have (1280-640)(1024-480)558*9 ~= 159) 2<sup>29</sup>, or a 29 bit identifier based on resolution 160) information alone. </p><p> 161)`
Update Torbutton design doc. Mike Perry authored 13 years ago	162) Of course, this space is non-uniform in user density and prone to incremental 163) changes. The <a class="ulink" href="https://wiki.mozilla.org/Fingerprinting#Data" target="_top">Panopticlick study 164) done</a> by the EFF attempts to measure the actual entropy - the number of 165) identifying bits of information encoded in browser properties. Their result 166) data is definitely useful, and the metric is probably the appropriate one for 167) determining how identifying a particular browser property is. However, some 168) quirks of their study means that they do not extract as much information as 169) they could from display information: they only use desktop resolution (which 170) Torbutton reports as the window resolution) and do not attempt to infer the 171) size of toolbars.
add in the torbutton design... Andrew Lewman authored 13 years ago	172) 173) </p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or 174) OS</strong></span><p> 175) Last, but definitely not least, the adversary can exploit either general 176) browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to 177) install malware and surveillance software. An adversary with physical access 178) can perform similar actions. Regrettably, this last attack capability is 179) outside of Torbutton's ability to defend against, but it is worth mentioning 180) for completeness. 181) </p></li></ol></div></div></div><div class="sect2" title="1.2. Torbutton Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="requirements"></a>1.2. Torbutton Requirements</h3></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> 182) 183) Since many settings satisfy multiple requirements, this design document is 184) organized primarily by Torbutton components and settings. However, if you are 185) the type that would rather read the document from the requirements 186) perspective, it is in fact possible to search for each of the following 187) requirement phrases in the text to find the relevant features that help meet 188) that requirement. 189) 190) </div><p> 191) 192) From the above Adversary Model, a number of requirements become clear. 193) 194) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a id="proxy"></a><span class="command"><strong>Proxy Obedience</strong></span><p>The browser
Update Torbutton design doc. Mike Perry authored 13 years ago	`195) MUST NOT bypass Tor proxy settings for any content.</p></li><li class="listitem"><a id="state"></a><span class="command"><strong>State Separation</strong></span><p>Browser state (cookies, cache, history, 'DOM storage'), accumulated in`
add in the torbutton design... Andrew Lewman authored 13 years ago	`196) one Tor state MUST NOT be accessible via the network in`
Update Torbutton design doc. Mike Perry authored 13 years ago	`197) another Tor state.</p></li><li class="listitem"><a id="isolation"></a><span class="command"><strong>Network Isolation</strong></span><p>Pages MUST NOT perform any network activity in a Tor state different 198) from the state they were originally loaded in.</p></li><li class="listitem"><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>With`
add in the torbutton design... Andrew Lewman authored 13 years ago	199) the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor 200) users whose network fingerprint does not obviously betray the fact that they 201) are using Tor. This should extend to the browser as well - Torbutton MUST NOT 202) 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 203) 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 204) timezone or locale via Tor.</p></li><li class="listitem"><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
Update Torbutton design doc. Mike Perry authored 13 years ago	`205) Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity 206) set reducing or fingerprinting information`
add in the torbutton design... Andrew Lewman authored 13 years ago	207) (such as user agent, extension presence, and resolution information) 208) automatically via Tor. The assessment of the attacks above should make it clear 209) that anonymity set reduction is a very powerful method of tracking and 210) eventually identifying anonymous users. 211) </p></li><li class="listitem"><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser 212) 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 213) enable the user to switch between a number of different proxies. It MUST 214) provide full Tor protection in the event a third-party proxy switcher has 215) 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 216) 'Chrome'. Components are a fancy name for classes that implement a given 217) interface or interfaces. In Firefox, components <a class="ulink" href="https://developer.mozilla.org/en/XPCOM" target="_top">can be 218) written</a> in C++, 219) Javascript, or a mixture of both. Components have two identifiers: their 220) '<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005" target="_top">Contract 221) 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 222) ID</a>' (a GUID hex-string). In addition, the interfaces they implement each have a hex 223) 'Interface ID'. It is possible to 'hook' system components - to reimplement 224) their interface members with your own wrappers - but only if the rest of the 225) browser refers to the component by its Contract ID. If the browser refers to 226) the component by Class ID, it bypasses your hooks in that use case. 227) Technically, it may be possible to hook Class IDs by unregistering the 228) original component, and then re-registering your own, but this relies on 229) obsolete and deprecated interfaces and has proved to be less than 230) stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window. 231) Extensions are allowed to create 'overlays' that are 'bound' to existing XML 232) window definitions, or they can create their own windows. The DTD for this XML
Update Torbutton design doc. Mike Perry authored 13 years ago	`233) is called <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XUL</a>.</p></div></div><div class="sect1" title="2. Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="components"></a>2. Components</h2></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`234) 235) Torbutton installs components for two purposes: hooking existing components to 236) reimplement their interfaces; and creating new components that provide 237) services to other pieces of the extension. 238)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`239) </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="hookedxpcom"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some`
add in the torbutton design... Andrew Lewman authored 13 years ago	`240) of its own standalone components as well. Let's discuss the hooked components`
Update Torbutton design doc. Mike Perry authored 13 years ago	241) first.</p><div class="sect3" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="appblocker"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1" target="_top">@mozilla.org/uriloader/external-protocol-service;1
add in the torbutton design... Andrew Lewman authored 13 years ago	`242) </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>, 243) 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>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`244) - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js" target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	245) 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 246) applications without user intervention, Torbutton had to wrap the three 247) components involved in launching external applications to provide user 248) confirmation before doing so while Tor is enabled. Since external applications 249) do not obey proxy settings, they can be manipulated to automatically connect 250) back to arbitrary servers outside of Tor with no user intervention. Fixing 251) this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy 252) Obedience</a> Requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`253) </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="id2669566"></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>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`254) - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js" target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin Jackson</a> as a method for defeating`
add in the torbutton design... Andrew Lewman authored 13 years ago	255) CSS and Javascript-based methods of history disclosure. The global-history 256) component is what is used by Firefox to determine if a link was visited or not 257) (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> 258) and <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29" target="_top">addURI</a> 259) methods, Torbutton is able to selectively prevent history items from being 260) added or being displayed as visited, depending on the Tor state and the user's 261) preferences. 262) </p><p> 263) This component helps satisfy the <a class="link" href="#state">State Separation</a>
Update Torbutton design doc. Mike Perry authored 13 years ago	`264) and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton. It 265) is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor 266) of the <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">built-in 267) history protections</a>.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`268) </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>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`269) - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js" target="_top">components/block-livemarks.js</a></h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	270) 271) The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html" target="_top">livemark</a> service 272) is started by a timer that runs 5 seconds after Firefox 273) startup. As a result, we cannot simply call the stopUpdateLivemarks() method to 274) disable it. We must wrap the component to prevent this start() call from 275) firing in the event the browser starts in Tor mode. 276) 277) </p><p> 278) This component helps satisfy the <a class="link" href="#isolation">Network 279) Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set 280) Preservation</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`281) </p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2682565"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the`
add in the torbutton design... Andrew Lewman authored 13 years ago	`282) extension. These components do not hook any interfaces, nor are they used`
Update Torbutton design doc. Mike Perry authored 13 years ago	`283) anywhere besides Torbutton itself.</p><div class="sect3" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js"><div class="titlepage"><div><div><h4 class="title"><a id="cookiejar"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2`
add in the torbutton design... Andrew Lewman authored 13 years ago	`284) - 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 285) Jackson</a>) is used by the Torbutton chrome to switch between`
Update Torbutton design doc. Mike Perry authored 13 years ago	`286) Tor and Non-Tor cookies. It stores an XML representation of the current 287) cookie state in memory and/or on disk. When Tor is toggled, it syncs the 288) current cookies to this XML store, and then loads the cookies for the other 289) state from the XML store. 290) </p><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`291) This component helps to address the <a class="link" href="#state">State 292) Isolation</a> requirement of Torbutton.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`293) </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="id2694914"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1`
add in the torbutton design... Andrew Lewman authored 13 years ago	294) - components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton 295) logging messages to either Firefox stderr 296) (<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console 297) (<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if 298) available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to 299) change the loglevel on the fly by changing 300) <span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
Update Torbutton design doc. Mike Perry authored 13 years ago	`301) </p></div><div class="sect3" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1`
add in the torbutton design... Andrew Lewman authored 13 years ago	302) - 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 303) state the tab was most recently used under to fetch a page. The problem is 304) that for many Firefox events, it is not possible to determine the tab that is 305) actually receiving the event. The Torbutton window mapper allows the Torbutton 306) chrome and other components to look up a <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser 307) tab</a> for a given <a class="ulink" href="https://developer.mozilla.org/en/nsIDOMWindow" target="_top">HTML content 308) window</a>. It does this by traversing all windows and all browsers, until it 309) 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 310) and page loading in general can generate hundreds of these lookups, this 311) result is cached inside the component.
Update Torbutton design doc. Mike Perry authored 13 years ago	312) </p></div><div class="sect3" title="@torproject.org/crash-observer;1"><div class="titlepage"><div><div><h4 class="title"><a id="crashobserver"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js" target="_top">@torproject.org/crash-observer;1</a></h4></div></div></div><p> 313) 314) This component detects when Firefox crashes by altering Firefox prefs during 315) runtime and checking for the same values at startup. It <a class="ulink" href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()" target="_top">synchronizes 316) the preference service</a> to ensure the altered prefs are written to disk 317) immediately. 318) 319) </p></div><div class="sect3" title="@torproject.org/torbutton-ss-blocker;1"><div class="titlepage"><div><div><h4 class="title"><a id="tbsessionstore"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js" target="_top">@torproject.org/torbutton-ss-blocker;1</a></h4></div></div></div><p> 320) 321) This component subscribes to the Firefox <a class="ulink" href="https://developer.mozilla.org/en/Observer_Notifications#Session_Store" target="_top">sessionstore-state-write</a> 322) observer event to filter out URLs from tabs loaded during Tor, to prevent them 323) from being written to disk. To do this, it checks the 324) <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tab objects before writing them out. If 325) the tag is from a blocked Tor state, the tab is not written to disk. This is 326) a rather expensive operation that involves potentially very large JSON 327) evaluations and object tree traversals, but it preferable to replacing the 328) Firefox session store with our own implementation, which is what was done in 329) years past. 330) 331) </p></div><div class="sect3" title="@torproject.org/torRefSpoofer;1"><div class="titlepage"><div><div><h4 class="title"><a id="refspoofer"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js" target="_top">@torproject.org/torRefSpoofer;1</a></h4></div></div></div><p>
Update Torbutton design doc. Mike Perry authored 13 years ago	`332) This component handles optional referer spoofing for Torbutton. It implements a`
Update Torbutton design doc. Mike Perry authored 13 years ago	`333) form of "smart" referer spoofing using <a class="ulink" href="https://developer.mozilla.org/en/Setting_HTTP_request_headers" target="_top">http-on-modify-request</a>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`334) to modify the Referer header. The code sends the default browser referer`
Update Torbutton design doc. Mike Perry authored 13 years ago	335) header only if the destination domain is a suffix of the source, or if the 336) source is a suffix of the destination. Otherwise, it sends no referer. This 337) strange suffix logic is used as a heuristic: some rare sites on the web block 338) requests without proper referer headers, and this logic is an attempt to cater 339) to them. Unfortunately, it may not be enough. For example, google.fr will not 340) send a referer to google.com using this logic. Hence, it is off by default. 341) </p></div><div class="sect3" title="@torproject.org/cssblocker;1 - components/cssblocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
add in the torbutton design... Andrew Lewman authored 13 years ago	342) - components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is 343) toggled, Javascript is disabled, and pages are instructed to stop loading. 344) However, CSS is still able to perform network operations by loading styles for 345) onmouseover events and other operations. In addition, favicons can still be 346) loaded by the browser. The cssblocker component prevents this by implementing 347) and registering an <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy" target="_top">nsIContentPolicy</a>. 348) When an nsIContentPolicy is registered, Firefox checks every attempted network 349) request against its <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()" target="_top">shouldLoad</a> 350) member function to determine if the load should proceed. In Torbutton's case, 351) 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>, 352) and checks that tab's load tag against the current Tor state. If the tab was 353) loaded in a different state than the current state, the fetch is denied. 354) Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#isolation">Network 355) Isolation</a> requirements of Torbutton. 356) 357) <p>In addition, the content policy also blocks website javascript from
Update Torbutton design doc. Mike Perry authored 13 years ago	`358) <a class="ulink" href="http://webdevwonders.com/detecting-firefox-add-ons/" target="_top">querying for`
add in the torbutton design... Andrew Lewman authored 13 years ago	`359) versions and existence of extension chrome</a> while Tor is enabled, and 360) also masks the presence of Torbutton to website javascript while Tor is 361) disabled. </p><p> 362) 363) Finally, some of the work that logically belongs to the content policy is 364) instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and`
Update Torbutton design doc. Mike Perry authored 13 years ago	`365) <span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of`
add in the torbutton design... Andrew Lewman authored 13 years ago	366) Firefox 3 favicon loads, popups, and full page plugins, which for whatever 367) reason are not passed to the Firefox content policy itself (see Firefox Bugs 368) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 369) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>). 370) 371) </p><p> 372) 373) 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
Update Torbutton design doc. Mike Perry authored 13 years ago	`374) Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2661538"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are 375) located. </p><div class="sect2" title="3.1. XUL Windows and Overlays"><div class="titlepage"><div><div><h3 class="title"><a id="id2683477"></a>3.1. XUL Windows and Overlays</h3></div></div></div><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`376) 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`
add in the torbutton design... Andrew Lewman authored 13 years ago	`377) files attached. The scope of these Javascript files is their containing`
Update Torbutton design doc. Mike Perry authored 13 years ago	378) window. XUL files that add new elements and script to existing Firefox windows 379) are called overlays.</p><div class="sect3" title="Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h4 class="title"><a id="browseroverlay"></a>Browser Overlay - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h4></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status 380) bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
add in the torbutton design... Andrew Lewman authored 13 years ago	`381) It contains event handlers for preference update, shutdown, upgrade, and`
Update Torbutton design doc. Mike Perry authored 13 years ago	382) location change events.</p></div><div class="sect3" title="Preferences Window - preferences.xul"><div class="titlepage"><div><div><h4 class="title"><a id="id2672297"></a>Preferences Window - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h4></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with 383) handlers located in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect3" title="Other Windows"><div class="titlepage"><div><div><h4 class="title"><a id="id2689726"></a>Other Windows</h4></div></div></div><p>There are additional windows that describe popups for right clicking on 384) the status bar, the toolbutton, and the about page.</p></div></div><div class="sect2" title="3.2. Major Chrome Observers"><div class="titlepage"><div><div><h3 class="title"><a id="id2679782"></a>3.2. Major Chrome Observers</h3></div></div></div><p>
Update Torbutton design doc. Mike Perry authored 13 years ago	385) In addition to the <a class="link" href="#components" title="2. Components">components described 386) above</a>, Torbutton also instantiates several observers in the browser 387) overlay window. These mostly grew due to scoping convenience, and many should 388) probably be relocated into their own components. 389) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>torbutton_window_pref_observer</strong></span><p> 390) This is an observer that listens for Torbutton state changes, for the purposes 391) of updating the Torbutton button graphic as the Tor state changes. 392) </p></li><li class="listitem"><span class="command"><strong>torbutton_unique_pref_observer</strong></span><p> 393) 394) This is an observer that only runs in one window, called the main window. It 395) listens for changes to all of the Torbutton preferences, as well as Torbutton 396) controlled Firefox preferences. It is what carries out the toggle path when 397) the proxy settings change. When the main window is closed, the 398) torbutton_close_window event handler runs to dub a new window the "main 399) window". 400) 401) </p></li><li class="listitem"><span class="command"><strong>tbHistoryListener</strong></span><p> 402) The tbHistoryListener exists to prevent client window Javascript from 403) interacting with window.history to forcibly navigate a user to a tab session 404) history entry from a different Tor state. It also expunges the window.history 405) entries during toggle. This listener helps Torbutton 406) satisfy the <a class="link" href="#isolation">Network Isolation</a> requirement as 407) well as the <a class="link" href="#state">State Separation</a> requirement. 408) 409) </p></li><li class="listitem"><span class="command"><strong>torbutton_http_observer</strong></span><p> 410) 411) The torbutton_http_observer performs some of the work that logically belongs 412) to the content policy. This handles blocking of 413) Firefox 3 favicon loads, which for whatever 414) reason are not passed to the Firefox content policy itself (see Firefox Bugs 415) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 416) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>). 417) 418) </p><p> 419) The observer is also responsible for redirecting users to alternate 420) search engines when Google presents them with a Captcha, as well as copying 421) Google Captcha-related cookies between international Google domains. 422) </p></li><li class="listitem"><span class="command"><strong>torbutton_proxyservice</strong></span><p> 423) The Torbutton proxy service handles redirecting Torbutton-related update 424) checks on addons.mozilla.org through Tor. This is done to help satisfy the 425) <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement. 426) </p></li><li class="listitem"><span class="command"><strong>torbutton_weblistener</strong></span><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
add in the torbutton design... Andrew Lewman authored 13 years ago	427) change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress" target="_top">webprogress 428) listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most 429) 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 430) listener</a> that handles receiving an event every time a page load or 431) iframe load occurs. This class eventually calls down to 432) <code class="function">torbutton_update_tags()</code> and 433) <code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load 434) state tags, plugin permissions, and install the Javascript hooks to hook the 435) <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a> 436) object to obfuscate browser and desktop resolution information. 437)
Update Torbutton design doc. Mike Perry authored 13 years ago	`438) </p></li></ol></div></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2682210"></a>4. Toggle Code Path</h2></div></div></div><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	439) 440) The act of toggling is connected to <code class="function">torbutton_toggle()</code> 441) via the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a> 442) and <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul" target="_top">popup.xul</a> 443) overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 444)
add in the torbutton design... Andrew Lewman authored 13 years ago	`445) </p><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	446) 447) Toggling is a 3 stage process: Button Click, Proxy Update, and 448) Settings Update. These stages are reflected in the prefs 449) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>, 450) <span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and 451) <span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the 452) 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 453) javascript runs on a different thread than the chrome javascript, it is 454) important to properly convey the stages to the content policy to avoid race 455) conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 456) 409737</a> unfixed. The content policy does not allow any network activity 457) whatsoever during this three stage transition. 458)
Update Torbutton design doc. Mike Perry authored 13 years ago	`459) </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2678571"></a>4.1. Button Click</h3></div></div></div><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	460) 461) This is the first step in the toggling process. When the user clicks the 462) toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is 463) called. This function checks the current Tor status by comparing the current 464) proxy settings to the selected Tor settings, and then sets the proxy settings 465) to the opposite state, and sets the pref 466) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state. 467) 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 468) observer</a> 469) <span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the 470) toggle. 471)
Update Torbutton design doc. Mike Perry authored 13 years ago	`472) </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2677555"></a>4.2. Proxy Update</h3></div></div></div><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	473) 474) When Torbutton receives any proxy change notifications via its 475) <span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls 476) <code class="function">torbutton_set_status()</code> which checks against the Tor 477) settings to see if the Tor proxy settings match the current settings. If so, 478) it calls <code class="function">torbutton_update_status()</code>, which determines if 479) the Tor state has actually changed, and sets 480) <span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor 481) state value, and ensures that 482) <span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct 483) value. This is decoupled from the button click functionality via the pref 484) observer so that other addons (such as SwitchProxy) can switch the proxy 485) settings between multiple proxies. 486)
Update Torbutton design doc. Mike Perry authored 13 years ago	`487) </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2671739"></a>4.3. Settings Update</h3></div></div></div><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	488) 489) The next stage is also handled by 490) <code class="function">torbutton_update_status()</code>. This function sets scores of 491) Firefox preferences, saving the original values to prefs under 492) <span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the <a class="link" href="#cookiejar" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js">cookie jarring</a>, state clearing (such as window.name 493) and DOM storage), and <a class="link" href="#preferences" title="4.4. Firefox preferences touched during Toggle">preference 494) toggling</a>. At the 495) end of its work, it sets 496) <span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the 497) completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. 498) 499) </p></div><div class="sect2" title="4.4. Firefox preferences touched during Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="preferences"></a>4.4. Firefox preferences touched during Toggle</h3></div></div></div><p> 500) There are also a number of Firefox preferences set in
add in the torbutton design... Andrew Lewman authored 13 years ago	501) <code class="function">torbutton_update_status()</code> that aren't governed by any 502) Torbutton setting. These are: 503) </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> 504) Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it 505) reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) to the list 506) of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor, 507) and the Tor control port, respectively. This is set for both Tor and Non-Tor 508) usage, and prevents websites from attempting to do http fetches from these 509) ports to see if they are open, which addresses the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement. 510) </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings" target="_top">browser.send_pings</a><p> 511) This setting is currently always disabled. If anyone ever complains saying 512) that they want their browser to be able to send ping notifications to a 513) page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding 514) my breath. I haven't checked if the content policy is called for pings, but if 515) not, this setting helps with meeting the <a class="link" href="#isolation">Network 516) Isolation</a> requirement. 517) </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups" target="_top">browser.safebrowsing.remoteLookups</a><p> 518) Likewise for this setting. I find it hard to imagine anyone who wants to ask 519) Google in real time if each URL they visit is safe, especially when the list 520) of unsafe URLs is downloaded anyway. This helps fulfill the <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire 521) browsing history from ending up on Google's disks. 522) </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled" target="_top">browser.safebrowsing.enabled</a><p> 523) Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387" target="_top">unauthenticated 524) updates under Firefox 2</a>, so it is disabled during Tor usage. 525) This helps fulfill the <a class="link" href="#updates">Update 526) Safety</a> requirement. Firefox 3 has the fix for that bug, and so 527) safebrowsing updates are enabled during Tor usage. 528) </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> 529) If Tor is enabled, we need to prevent random external applications from 530) launching without at least warning the user. This group of settings only 531) partially accomplishes this, however. Applications can still be launched via 532) plugins. The mechanisms for handling this are described under the "Disable 533) Plugins During Tor Usage" preference. This helps fulfill the <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external 534) applications from accessing network resources at the command of Tor-fetched 535) pages. Unfortunately, due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> 536) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a>, 537) these prefs are no longer obeyed. They are set still anyway out of respect for 538) the dead. 539) </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> 540) 541) To help satisfy the Torbutton <a class="link" href="#state">State Separation</a> 542) and <a class="link" href="#isolation">Network Isolation</a> requirements, 543) Torbutton needs to purge the Undo Tab history on toggle to prevent repeat 544) "Undo Close" operations from accidentally restoring tabs from a different Tor 545) State. This purge is accomplished by setting this preference to 0 and then 546) restoring it to the previous user value upon toggle. 547)
Update Torbutton design doc. Mike Perry authored 13 years ago	`548) </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span> or <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto" target="_top">nsIDOMCrypto::logout()</a><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`549) TLS Session IDs can persist for an indefinite duration, providing an 550) identifier that is sent to TLS sites that can be used to link activity. This 551) is particularly troublesome now that we have certificate verification in place 552) in Firefox 3: The OCSP server can use this Session ID to build a history of 553) TLS sites someone visits, and also correlate their activity as users move from 554) network to network (such as home to work to coffee shop, etc), inside and`
Update Torbutton design doc. Mike Perry authored 13 years ago	`555) outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we call the logout() 556) function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back 557) to toggling`
add in the torbutton design... Andrew Lewman authored 13 years ago	`558) <span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID`
Update Torbutton design doc. Mike Perry authored 13 years ago	559) cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>. 560) </p></li><li class="listitem"><span class="command"><strong>security.OCSP.enabled</strong></span><p> 561) Similarly, we toggle <span class="command"><strong>security.OCSP.enabled</strong></span>, which clears the OCSP certificate 562) validation cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>. 563) In this way, exit nodes will not be able to fingerprint you 564) based the fact that non-Tor OCSP lookups were obviously previously cached. 565) To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, 566) </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users" target="_top">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</a></strong></span><p> 567) We permanently disable addon usage statistic reporting to the 568) addons.mozilla.org statistics engine. These statistics send version 569) information about Torbutton users via non-Tor, allowing their Tor use to be 570) uncovered. Disabling this reporting helps Torbutton to satisfy its <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement. 571) 572) </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>
add in the torbutton design... Andrew Lewman authored 13 years ago	573) 574) Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor 575) is enabled. This helps Torbutton maintain its 576) <a class="link" href="#location">Location Neutrality</a> requirement. 577) While Firefox does prompt before divulging geolocational information, 578) the assumption is that Tor users will never want to give their 579) location away during Tor usage, and even allowing websites to prompt 580) them to do so will only cause confusion and accidents to happen. Moreover, 581) just because users may approve a site to know their location in non-Tor mode 582) does not mean they want it divulged during Tor mode. 583) 584) </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> 585) 586) Firefox actually remembers your zoom settings for certain sites. CSS 587) and Javascript rule can use this to recognize previous visitors to a site. 588) This helps Torbutton fulfill its <a class="link" href="#state">State Separation</a> 589) requirement. 590) 591) </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> 592) 593) Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in 594) links on a page to decrease page load latency. While Firefox does typically 595) disable this behavior when proxies are enabled, we set this pref for added 596) safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having 597) their links prefetched after a toggle to Non-Tor mode occurs, 598) we also set the docShell attribute 599) <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell" target="_top"> 600) allowDNSPrefetch</a> to false on Tor loaded tabs. This happens in the same 601) positions in the code as those for disabling plugins via the allowPlugins 602) docShell attribute. This helps Torbutton fulfill its <a class="link" href="#isolation">Network Isolation</a> requirement. 603) 604) </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> 605) 606) Firefox has the ability to store web applications in a special cache to allow 607) them to continue to operate while the user is offline. Since this subsystem 608) is actually different than the normal disk cache, it must be dealt with 609) separately. Thus, Torbutton sets this preference to false whenever Tor is 610) enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk 611) Avoidance</a> and <a class="link" href="#state">State Separation</a> 612) requirements. 613)
Update Torbutton design doc. Mike Perry authored 13 years ago	`614) </p></li></ol></div></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2684076"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each`
add in the torbutton design... Andrew Lewman authored 13 years ago	`615) option is presented as the string from the preferences window, a summary, the 616) preferences it touches, and the effect this has on the components, chrome, and`
Update Torbutton design doc. Mike Perry authored 13 years ago	`617) browser properties.</p><div class="sect2" title="5.1. Proxy Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2686457"></a>5.1. Proxy Settings</h3></div></div></div><div class="sect3" title="Test Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2688146"></a>Test Settings</h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	618) This button under the Proxy Settings tab provides a way to verify that the 619) proxy settings are correct, and actually do route through the Tor network. It 620) performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a> 621) for <a class="ulink" href="https://check.torproject.org/?TorButton=True" target="_top">https://check.torproject.org/?Torbutton=True</a>. 622) This is a special page that returns very simple, yet well-formed XHTML that 623) Torbutton can easily inspect for a hidden link with an id of 624) <span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span> 625) or <span class="command"><strong>failure</strong></span> to indicate if the 626) user hit the page from a Tor IP, a non-Tor IP. This check is handled in
Update Torbutton design doc. Mike Perry authored 13 years ago	`627) <code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. 628) Presenting the results to the user is handled by the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences`
add in the torbutton design... Andrew Lewman authored 13 years ago	`629) window</a>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`630) callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">preferences.js</a>.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`631)`
Update Torbutton design doc. Mike Perry authored 13 years ago	632) </p></div></div><div class="sect2" title="5.2. Dynamic Content Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2685583"></a>5.2. Dynamic Content Settings</h3></div></div></div><div class="sect3" title="Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="plugins"></a>Disable plugins on Tor Usage (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html" target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html" target="_top">local IP
add in the torbutton design... Andrew Lewman authored 13 years ago	633) address</a> and report it back to the 634) remote site. They can also <a class="ulink" href="http://decloak.net" target="_top">bypass proxy settings</a> and directly connect to a 635) remote site without Tor. Every browser plugin we have tested with Firefox has 636) some form of network capability, and every one ignores proxy settings or worse - only 637) partially obeys them. This includes but is not limited to: 638) QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and 639) Flash. 640) 641) </p><p> 642) Enabling this preference causes the above mentioned Torbutton chrome web progress 643) 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 644) plugins via the browser <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell" target="_top">docShell</a> 645) attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is 646) created (<code class="function">torbutton_tag_new_browser()</code>), every time a web 647) load 648) event occurs 649) (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed 650) (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
Update Torbutton design doc. Mike Perry authored 13 years ago	`651) prevented from loading by the content policy in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is`
add in the torbutton design... Andrew Lewman authored 13 years ago	652) enabled and this option is set. 653) </p><p>All of this turns out to be insufficient if the user directly clicks 654) 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>, 655) the browser decides that maybe it should ignore all these other settings and 656) load the plugin anyways, because maybe the user really did want to load it 657) (never mind this same load-style could happen automatically with meta-refresh 658) or any number of other ways..). To handle these cases, Torbutton stores a list 659) of plugin-handled mime-types, and sets the pref 660) <span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> to this list. 661) Additionally, (since nothing can be assumed when relying on Firefox 662) preferences and internals) if it detects a load of one of them from the web 663) progress listener, it cancels the request, tells the associated DOMWindow to 664) stop loading, clears the document, AND throws an exception. Anything short of 665) all this and the plugin managed to find some way to load. 666) </p><p> 667) 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 668) allowPlugins</a> for directly visited URLs, or notify its content policy for such 669) 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 670) not very encouraging. 671) </p><p> 672) 673) Since most plugins completely ignore browser proxy settings, the actions 674) performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement. 675)
Update Torbutton design doc. Mike Perry authored 13 years ago	676) </p></div><div class="sect3" title="Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2684833"></a>Isolate Dynamic Content to Tor State (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> content policy
add in the torbutton design... Andrew Lewman authored 13 years ago	677) mentioned above, and causes it to block content load attempts in pages an 678) opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser 679) tabs</a> are tagged 680) with a <span class="command"><strong>__tb_load_state</strong></span> member in 681) <code class="function">torbutton_update_tags()</code> and this 682) 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 683) 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 684) <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 685) equivalent of hitting the STOP button).</p><p> 686) 687) Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox bug 688) 409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing 689) 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> 690) are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content 691) Policy</a> should prevent such code from performing network activity within 692) the current tab, but activity that happens via a popup window or via a 693) Javascript redirect can still slip by. For this reason, Torbutton blocks 694) popups by checking for a valid <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener" target="_top">window.opener</a> 695) attribute in <code class="function">torbutton_check_progress()</code>. If the window 696) has an opener from a different Tor state, its load is blocked. The content 697) policy also takes similar action to prevent Javascript redirects. This also 698) has the side effect/feature of preventing the user from following any links 699) from a page loaded in an opposite Tor state. 700) 701) </p><p> 702) This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`703) </p></div><div class="sect3" title="Hook Dangerous Javascript"><div class="titlepage"><div><div><h4 class="title"><a id="jshooks"></a>Hook Dangerous Javascript</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js" target="_top">Javascript`
add in the torbutton design... Andrew Lewman authored 13 years ago	704) hooking code</a>. This is done in the chrome in 705) <code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 706) <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress 707) 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 708) javascript: urls). 709) 710) In the Firefox 2 days, this option did a lot more than 711) it does now. It used to be responsible for timezone and improved useragent 712) spoofing, and history object cloaking. However, now it only provides 713) obfuscation of the <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a> 714) object to mask your browser and desktop resolution. 715) The resolution hooks 716) effectively make the Firefox browser window appear to websites as if the renderable area 717) takes up the entire desktop, has no toolbar or other GUI element space, and 718) the desktop itself has no toolbars. 719) These hooks drastically reduce the amount of information available to do <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to 720) meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> 721) requirements. Unfortunately, Gregory Fleischer discovered it is still possible 722) 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> 723) or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html" target="_top">Components.lookupMethod</a>.
Update Torbutton design doc. Mike Perry authored 13 years ago	`724) We are still looking for a workaround as of Torbutton 1.3.2.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`725) 726) 727)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`728) </p></div><div class="sect3" title="Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2653668"></a>Resize windows to multiples of 50px during Tor usage (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	729) 730) This option drastically cuts down on the number of distinct anonymity sets 731) that divide the Tor web userbase. Without this setting, the dimensions for a 732) typical browser window range from 600-1200 horizontal pixels and 400-1000 733) vertical pixels, or about 600x600 = 360000 different sets. Resizing the 734) browser window to multiples of 50 on each side reduces the number of sets by 735) 50^2, bringing the total number of sets to 144. Of course, the distribution 736) among these sets are not uniform, but scaling by 50 will improve the situation 737) due to this non-uniformity for users in the less common resolutions. 738) Obviously the ideal situation would be to lie entirely about the browser 739) window size, but this will likely cause all sorts of rendering issues, and is 740) also not implementable in a foolproof way from extension land. 741) 742) </p><p> 743) 744) The implementation of this setting is spread across a couple of different
Update Torbutton design doc. Mike Perry authored 13 years ago	`745) locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="Browser Overlay - torbutton.xul">browser`
add in the torbutton design... Andrew Lewman authored 13 years ago	746) overlay</a>. Since resizing minimized windows causes them to be restored, 747) and since maximized windows remember their previous size to the pixel, windows 748) must be resized before every document load (at the time of browser tagging) 749) via <code class="function">torbutton_check_round()</code>, called by 750) <code class="function">torbutton_update_tags()</code>. To prevent drift, the extension 751) tracks the original values of the windows and uses this to perform the 752) rounding on document load. In addition, to prevent the user from resizing a 753) window to a non-50px multiple, a resize listener 754) (<code class="function">torbutton_do_resize()</code>) is installed on every new browser 755) window to record the new size and round it to a 50px multiple while Tor is 756) enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight 757) are set. This ensures that there is no discrepancy between the 50 pixel cutoff 758) and the actual renderable area of the browser (so that it is not possible to 759) infer toolbar size/presence by the distance to the nearest 50 pixel roundoff). 760) 761) </p><p> 762) This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`763) </p></div><div class="sect3" title="Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2653753"></a>Disable Search Suggestions during Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	764) 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> 765) during Tor usage. 766) This governs if you get Google search suggestions during Tor 767) usage. Your Google cookie is transmitted with google search suggestions, hence 768) this is recommended to be disabled. 769) 770) </p><p> 771) While this setting doesn't satisfy any Torbutton requirements, the fact that 772) cookies are transmitted for partially typed queries does not seem desirable 773) for Tor usage.
Update Torbutton design doc. Mike Perry authored 13 years ago	`774) </p></div><div class="sect3" title="Disable Updates During Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2653792"></a>Disable Updates During Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox`
add in the torbutton design... Andrew Lewman authored 13 years ago	775) update settings</a> during Tor 776) usage: <span class="command"><strong>extensions.update.enabled</strong></span>, 777) <span class="command"><strong>app.update.enabled</strong></span>, 778) <span class="command"><strong>app.update.auto</strong></span>, and 779) <span class="command"><strong>browser.search.update</strong></span>. These prevent the 780) browser from updating extensions, checking for Firefox upgrades, and 781) checking for search plugin updates while Tor is enabled. 782) </p><p> 783) This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`784) </p></div><div class="sect3" title="Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2653854"></a>Redirect Torbutton Updates Via Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.update_torbutton_via_tor</strong></span></p><p>This setting causes Torbutton to install an`
add in the torbutton design... Andrew Lewman authored 13 years ago	785) 786) <a class="ulink" href="https://developer.mozilla.org/en/nsIProtocolProxyFilter" target="_top">nsIProtocolProxyFilter</a> 787) in order to redirect all version update checks and Torbutton update downloads 788) via Tor, regardless of if Tor is enabled or not. This was done both to address 789) 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 790) help censored users meet the <a class="link" href="#undiscoverability">Tor 791) Undiscoverability</a> requirement. 792)
Update Torbutton design doc. Mike Perry authored 13 years ago	`793) </p></div><div class="sect3" title="Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2653898"></a>Disable livemarks updates during Tor usage (recommended)</h4></div></div></div><p>Option:`
add in the torbutton design... Andrew Lewman authored 13 years ago	`794) </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> 795) </p><p>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`796)`
add in the torbutton design... Andrew Lewman authored 13 years ago	797) 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 798) Tor usage. Because people often have very personalized Livemarks (such as RSS 799) feeds of Wikipedia articles they maintain, etc). This is accomplished both by 800) <a class="link" href="#livemarks" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js">wrapping the livemark-service component</a> and 801) 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 802) service</a> when Tor is enabled. 803) 804) </p><p> 805) This helps satisfy the <a class="link" href="#isolation">Network 806) Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set 807) Preservation</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`808) </p></div><div class="sect3" title="Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2653969"></a>Block Tor/Non-Tor access to network from file:// urls (recommended)</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	809) </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> 810) </p><p> 811) 812) These settings prevent file urls from performing network operations during the 813) respective Tor states. Firefox 2's implementation of same origin policy allows 814) file urls to read and <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/" target="_top">submit 815) arbitrary files from the local filesystem</a> to arbitrary websites. To 816) make matters worse, the 'Content-Disposition' header can be injected 817) arbitrarily by exit nodes to trick users into running arbitrary html files in 818) 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 819) resources from File urls during the appropriate Tor state. 820) 821) </p><p> 822) 823) This preference helps to ensure Tor's <a class="link" href="#isolation">Network 824) Isolation</a> requirement, by preventing file urls from executing network 825) operations in opposite Tor states. Also, allowing pages to submit arbitrary 826) files to arbitrary sites just generally seems like a bad idea. 827)
Update Torbutton design doc. Mike Perry authored 13 years ago	`828) </p></div><div class="sect3" title="Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2654041"></a>Close all Tor/Non-Tor tabs and windows on toggle (optional)</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	829) </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> 830) </p><p> 831) 832) These settings cause Torbutton to enumerate through all windows and close all 833) tabs in each window for the appropriate Tor state. This code can be found in 834) <code class="function">torbutton_update_status()</code>. The main reason these settings 835) exist is as a backup mechanism in the event of any Javascript or content policy 836) leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 837) 409737</a>. Torbutton currently tries to block all Javascript network 838) activity via the content policy, but until that bug is fixed, there is some 839) risk that there are alternate ways to bypass the policy. This option is 840) available as an extra assurance of <a class="link" href="#isolation">Network 841) Isolation</a> for those who would like to be sure that when Tor is toggled 842) all page activity has ceased. It also serves as a potential future workaround 843) in the event a content policy failure is discovered, and provides an additional 844) level of protection for the <a class="link" href="#disk">Disk Avoidance</a> 845) protection so that browser state is not sitting around waiting to be swapped 846) out longer than necessary. 847) 848) </p><p> 849) While this setting doesn't satisfy any Torbutton requirements, the fact that 850) cookies are transmitted for partially typed queries does not seem desirable 851) for Tor usage.
Update Torbutton design doc. Mike Perry authored 13 years ago	852) </p></div></div><div class="sect2" title="5.3. History and Forms Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2695607"></a>5.3. History and Forms Settings</h3></div></div></div><div class="sect3" title="Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2695612"></a>Isolate Access to History navigation to Tor state (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
add in the torbutton design... Andrew Lewman authored 13 years ago	853) This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener" target="_top">nsISHistoryListener</a> 854) attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">sessionHistory</a> of 855) of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation" target="_top">webNavigatator</a>. 856) The nsIShistoryListener is instantiated with a reference to the containing 857) browser window and blocks the back, forward, and reload buttons on the browser 858) navigation bar when Tor is in an opposite state than the one to load the 859) current tab. In addition, Tor clears the session history during a new document 860) load if this setting is enabled. 861) 862) </p><p> 863) 864) This is marked as a crucial setting in part 865) because Javascript access to the history object is indistinguishable from 866) user clicks, and because 867) <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 868) 409737</a> allows javascript to execute in opposite Tor states, javascript 869) can issue reloads after Tor toggle to reveal your original IP. Even without 870) this bug, however, Javascript is still able to access previous pages in your 871) session history that may have been loaded under a different Tor state, to 872) attempt to correlate your activity. 873) 874) </p><p> 875) 876) This setting helps to fulfill Torbutton's <a class="link" href="#state">State 877) Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a> 878) requirements. 879)
Update Torbutton design doc. Mike Perry authored 13 years ago	`880) </p></div><div class="sect3" title="History Access Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2695690"></a>History Access Settings</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	`881) </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>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`882) </p><p>On Firefox 3.x, these four settings govern the behavior of the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js" target="_top">components/ignore-history.js</a>`
add in the torbutton design... Andrew Lewman authored 13 years ago	883) history blocker component mentioned above. By hooking the browser's view of 884) 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> 885) 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> 886) components, this mechanism defeats all document-based <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure 887) attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only attacks</a>. 888) 889) The component also hooks functions involved in writing history to disk via 890) both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History" target="_top">Places 891) Database</a> and the older Firefox 2 mechanisms. 892)
Update Torbutton design doc. Mike Perry authored 13 years ago	`893) </p><p> 894) On Firefox 4, Mozilla finally <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">addressed 895) these issues</a>, so we can effectively ignore the "read" pair of the 896) above prefs. We then only need to link the write prefs to 897) <span class="command"><strong>places.history.enabled</strong></span>, which disabled writing to the 898) history store while set.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`899) </p><p> 900) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`901) </p></div><div class="sect3" title="Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2695816"></a>Clear History During Tor Toggle (optional)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls`
add in the torbutton design... Andrew Lewman authored 13 years ago	`902) <a class="ulink" href="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29" target="_top">nsIBrowserHistory.removeAllPages</a> 903) and <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">nsISHistory.PurgeHistory</a> 904) for each tab on Tor toggle.</p><p> 905) This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`906) </p></div><div class="sect3" title="Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2695859"></a>Block Password+Form saving during Tor/Non-Tor</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	907) </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> 908) </p><p>These settings govern if Torbutton disables 909) <span class="command"><strong>browser.formfill.enable</strong></span> 910) and <span class="command"><strong>signon.rememberSignons</strong></span> during Tor and Non-Tor usage. 911) Since form fields can be read at any time by Javascript, this setting is a lot 912) more important than it seems. 913) </p><p> 914) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	915) </p></div></div><div class="sect2" title="5.4. Cache Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2695921"></a>5.4. Cache Settings</h3></div></div></div><div class="sect3" title="Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2695926"></a>Block Tor disk cache and clear all cache on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
add in the torbutton design... Andrew Lewman authored 13 years ago	916) </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> 917) on Tor toggle to remove all entries from the cache. In addition, this setting 918) 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. 919) </p><p> 920) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`921) </p></div><div class="sect3" title="Block disk and memory cache during Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2695976"></a>Block disk and memory cache during Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting`
add in the torbutton design... Andrew Lewman authored 13 years ago	922) causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>, 923) <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and 924) <a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage. 925) </p><p> 926) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`927) </p></div></div><div class="sect2" title="5.5. Cookie and Auth Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2696030"></a>5.5. Cookie and Auth Settings</h3></div></div></div><div class="sect3" title="Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2696035"></a>Clear Cookies on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>`
add in the torbutton design... Andrew Lewman authored 13 years ago	928) </p><p> 929) 930) 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 931) every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a> 932) to 2 for Tor usage, which causes all cookies to be demoted to session cookies, 933) which prevents them from being written to disk. 934) 935) </p><p> 936) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`937) </p></div><div class="sect3" title="Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h4 class="title"><a id="id2696086"></a>Store Non-Tor cookies in a protected jar</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`938) </p><p> 939)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`940) This setting causes Torbutton to use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store`
add in the torbutton design... Andrew Lewman authored 13 years ago	941) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies 942) before restoring the jar. 943) </p><p> 944) This setting also sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a> 945) to 2 for Tor usage, which causes all cookies to be demoted to session cookies, 946) which prevents them from being written to disk. 947) 948) </p><p> 949) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
Update Torbutton design doc. Mike Perry authored 13 years ago	`950) </p></div><div class="sect3" title="Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696143"></a>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`951) </p><p> 952)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`953) This setting causes Torbutton to use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store`
add in the torbutton design... Andrew Lewman authored 13 years ago	`954) both Tor and Non-Tor cookies into protected jars. 955) </p><p> 956) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.`
Update Torbutton design doc. Mike Perry authored 13 years ago	957) </p></div><div class="sect3" title="Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696185"></a>Manage My Own Cookies (dangerous)</h4></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above 958) cookie prefs all to false.</p></div><div class="sect3" title="Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696201"></a>Disable DOM Storage during Tor usage (crucial)</h4></div></div></div><div class="sect3" title="Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h4 class="title"><a id="id2696203"></a>Do not write Tor/Non-Tor cookies to disk</h4></div></div></div><p>Options:
add in the torbutton design... Andrew Lewman authored 13 years ago	959) </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> 960) </p><p> 961) 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> 962) to 2 during the appropriate Tor state, and to store cookies acquired in that 963) state into a Javascript 964) <a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X" target="_top">E4X</a> 965) object as opposed to writing them to disk. 966) </p><p> 967) This allows Torbutton to provide an option to preserve a user's 968) cookies while still satisfying the <a class="link" href="#disk">Disk Avoidance</a> 969) requirement. 970) </p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span> 971) </p><p> 972) 973) This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor 974) usage to prevent 975) <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from 976) being used to store persistent information across Tor states.</p><p> 977) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`978) </p></div><div class="sect3" title="Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696304"></a>Clear HTTP Auth on Tor Toggle (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`979) </p><p> 980) This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager" target="_top">nsIHttpAuthManager.clearAll()</a> 981) every time Tor is toggled. 982) </p><p> 983) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`984) </p></div></div><div class="sect2" title="5.6. Startup Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2696343"></a>5.6. Startup Settings</h3></div></div></div><div class="sect3" title="On Browser Startup, set Tor state to: Tor, Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2696348"></a>On Browser Startup, set Tor state to: Tor, Non-Tor</h4></div></div></div><p>Options:`
Update Torbutton design doc. Mike Perry authored 13 years ago	`985) <span class="command"><strong>extensions.torbutton.restore_tor</strong></span> 986) </p><p>This option governs what Tor state tor is loaded in to. 987) <code class="function">torbutton_set_initial_state()</code> covers the case where the 988) browser did not crash, and <code class="function">torbutton_crash_recover()</code> 989) covers the case where the <a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash observer</a> 990) detected a crash.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`991) </p><p> 992) 993) Since the Tor state after a Firefox crash is unknown/indeterminate, this 994) setting helps to satisfy the <a class="link" href="#state">State Separation</a> 995) requirement in the event of Firefox crashes by ensuring all cookies, 996) settings and saved sessions are reloaded from a fixed Tor state. 997)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`998) </p></div><div class="sect3" title="Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h4 class="title"><a id="id2696399"></a>Prevent session store from saving Non-Tor/Tor-loaded tabs</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	`999) </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>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1000) </p><p>If these options are enabled, the <a class="link" href="#tbsessionstore" title="@torproject.org/torbutton-ss-blocker;1">tbSessionStore.js</a> component uses the session 1001) store listeners to filter out the appropriate tabs before writing the session 1002) store data to disk. 1003) </p><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1004) This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a> 1005) requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox 1006) crashes. 1007)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1008) </p></div></div><div class="sect2" title="5.7. Shutdown Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2696457"></a>5.7. Shutdown Settings</h3></div></div></div><div class="sect3" title="Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h4 class="title"><a id="id2696463"></a>Clear cookies on Tor/Non-Tor shutdown</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>`
Update Torbutton design doc. Mike Perry authored 13 years ago	1009) </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no 1010) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means 1011) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens 1012) for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in 1013) <a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash-observer.js</a> and use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> 1014) to clear out all cookies and all cookie jars upon shutdown. 1015) </p><p> 1016) This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1017) </p></div></div><div class="sect2" title="5.8. Header Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2696517"></a>5.8. Header Settings</h3></div></div></div><div class="sect3" title="Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696523"></a>Set user agent during Tor usage (crucial)</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	1018) </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> 1019) </p><p>On face, user agent switching appears to be straight-forward in Firefox. 1020) It provides several options for controlling the browser user agent string: 1021) <span class="command"><strong>general.appname.override</strong></span>, 1022) <span class="command"><strong>general.appversion.override</strong></span>, 1023) <span class="command"><strong>general.platform.override</strong></span>, 1024) <span class="command"><strong>general.oscpu.override</strong></span>, 1025) <span class="command"><strong>general.productSub.override</strong></span>, 1026) <span class="command"><strong>general.buildID.override</strong></span>, 1027) <span class="command"><strong>general.useragent.override</strong></span>, 1028) <span class="command"><strong>general.useragent.vendor</strong></span>, and 1029) <span class="command"><strong>general.useragent.vendorSub</strong></span>. If 1030) the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is 1031) true, Torbutton copies all of the other above prefs into their corresponding 1032) browser preferences during Tor usage.</p><p> 1033) 1034) It also turns out that it is possible to detect the original Firefox version 1035) by <a class="ulink" href="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/" target="_top">inspecting 1036) certain resource:// files</a>. These cases are handled by Torbutton's 1037) <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. 1038) 1039) </p><p> 1040) This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1041) </p></div><div class="sect3" title="Spoof US English Browser"><div class="titlepage"><div><div><h4 class="title"><a id="id2696697"></a>Spoof US English Browser</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	1042) </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> 1043) </p><p> This option causes Torbutton to set 1044) <span class="command"><strong>general.useragent.locale</strong></span> 1045) <span class="command"><strong>intl.accept_languages</strong></span> to the value specified in 1046) <span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>, 1047) <span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and 1048) <span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
Update Torbutton design doc. Mike Perry authored 13 years ago	`1049) well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="Hook Dangerous Javascript">javascript hooks</a>.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1050) </p><p> 1051) 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.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1052) </p></div><div class="sect3" title="Referer Spoofing Options"><div class="titlepage"><div><div><h4 class="title"><a id="id2696790"></a>Referer Spoofing Options</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.refererspoof</strong></span>`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1053) </p><p> 1054) This option variable has three values. If it is 0, "smart" referer spoofing is 1055) enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is 1056) sent. The default value is 1. The smart referer spoofing is implemented by the 1057) <a class="link" href="#refspoofer" title="@torproject.org/torRefSpoofer;1">torRefSpoofer</a> component. 1058) 1059) </p><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1060) This setting also does not directly satisfy any Torbutton requirement, but`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1061) some may desire to mask their referer for general privacy concerns. 1062) </p></div><div class="sect3" title="Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h4 class="title"><a id="id2696824"></a>Strip platform and language off of Google Search Box queries</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.fix_google_srch</strong></span>`
add in the torbutton design... Andrew Lewman authored 13 years ago	1063) </p><p> 1064) 1065) 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> 1066) component to wrap the Google search plugin. On many platforms, notably Debian 1067) and Ubuntu, the Google search plugin is set to reveal a lot of language and 1068) platform information. This setting strips off that info while Tor is enabled. 1069) 1070) </p><p> 1071) This setting helps Torbutton to fulfill its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1072) </p></div><div class="sect3" title="Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h4 class="title"><a id="id2696865"></a>Automatically use an alternate search engine when presented with a`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1073) Google Captcha</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	1074) </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> 1075) </p><p> 1076) 1077) Google's search engine has rate limiting features that cause it to 1078) <a class="ulink" href="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html" target="_top">present 1079) captchas</a> and sometimes even outright ban IPs that issue large numbers 1080) of search queries, especially if a lot of these queries appear to be searching 1081) for software vulnerabilities or unprotected comment areas. 1082) 1083) </p><p> 1084) 1085) Despite multiple discussions with Google, we were unable to come to a solution 1086) or any form of compromise that would reduce the number of captchas and 1087) outright bans seen by Tor users issuing regular queries. 1088) 1089) </p><p> 1090) 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> 1091) http observer to optionally redirect banned or captcha-triggering Google 1092) queries to search engines that do not rate limit Tor users. The current
Update FF bugs in design do... Mike Perry authored 13 years ago	`1093) options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. These are`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1094) encoded in the preferences`
Update FF bugs in design do... Mike Perry authored 13 years ago	`1095) <span class="command"><strong>extensions.torbutton.redir_url.[1-5]</strong></span>.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1096)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1097) </p></div><div class="sect3" title="Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2696945"></a>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h4></div></div></div><p>Options:`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1098) </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> 1099) </p><p> 1100) 1101) These settings govern if Torbutton attempts to isolate the user's SSL 1102) certificates into separate jars for each Tor state. This isolation is`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1103) implemented in <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>,`
add in the torbutton design... Andrew Lewman authored 13 years ago	1104) which calls <code class="function">torbutton_jar_cert_type()</code> and 1105) <code class="function">torbutton_unjar_cert_type()</code> for each certificate type in 1106) 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>. 1107) 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>. 1108) </p><p> 1109) The first time this pref is used, a backup of the user's certificates is 1110) created in their profile directory under the name 1111) <code class="filename">cert8.db.bak</code>. This file can be copied back to 1112) <code class="filename">cert8.db</code> to fully restore the original state of the 1113) user's certificates in the event of any error. 1114) </p><p> 1115) Since exit nodes and malicious sites can insert content elements sourced to 1116) specific SSL sites to query if a user has a certain certificate, 1117) this setting helps to satisfy the <a class="link" href="#state">State 1118) Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Firefox Bug 1119) 435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it 1120) is currently not exposed via the preferences UI. 1121)
Update Torbutton design doc. Mike Perry authored 13 years ago	`1122) </p></div></div></div><div class="sect1" title="6. Relevant Firefox Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	1123) 1124) </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> 1125) 1126) Torbutton has to work around a number of Firefox bugs that impact its 1127) security. Most of these are mentioned elsewhere in this document, but they 1128) have also been gathered here for reference. In order of decreasing severity, 1129) they are: 1130) 1131) </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 1132) Components.interfaces to untrusted content leaks information about installed 1133) extensions</a><p> 1134) <a class="ulink" href="http://pseudo-flaw.net/" target="_top">Gregory Fleischer</a> demonstrated at Defcon 17 that these interfaces can 1135) also be used to <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html" target="_top">fingerprint 1136) Firefox down the to the minor version</a>. Note that his test has not been 1137) updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This 1138) bug interferes with Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1139) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418986" target="_top">Bug 418986 - window.screen`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1140) provides a large amount of identifiable information</a><p> 1141) 1142) As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of 1143) information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1144) The most sensitive data to anonymity is actually that which is not used in`
Update FF bugs in design do... Mike Perry authored 13 years ago	`1145) rendering - such as desktop resolution, and window decoration size.`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1146) Currently, there is no way to obscure this information without Javascript`
Update FF bugs in design do... Mike Perry authored 13 years ago	`1147) hooking. In addition, many of this same desktop and window decoration 1148) resolution information is available via <a class="ulink" href="https://developer.mozilla.org/En/CSS/Media_queries" target="_top">CSS Media 1149) Queries</a>, so perhaps some more lower-level rendering controls or 1150) preferences need to be provided. These issues interfere with Torbutton's 1151) ability to fulfill its <a class="link" href="#setpreservation">Anonymity Set 1152) Preservation</a> requirement.`
add in the torbutton design... Andrew Lewman authored 13 years ago	1153) 1154) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Bug 435159 - 1155) nsNSSCertificateDB::DeleteCertificate has race conditions</a><p> 1156) 1157) In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates 1158) the user has installed. Unfortunately, the method call to delete a certificate 1159) from the current certificate database acts lazily: it only sets a variable 1160) that marks a cert for deletion later, and it is not cleared if that 1161) certificate is re-added. This means that if the Tor state is toggled quickly, 1162) that certificate could remain present until it is re-inserted (causing an 1163) error dialog), and worse, it would still be deleted after that. The lack of 1164) this functionality is considered a Torbutton security bug because cert 1165) isolation is considered a <a class="link" href="#state">State Separation</a> 1166) feature. 1167)
Update design html. Mike Perry authored 13 years ago	1168) </p></li><li class="listitem">Give more visibility into and control over TLS 1169) negotiation 1170) <p> 1171) 1172) There are several <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/2482" target="_top">TLS issues 1173) impacting Torbutton security</a>. It is not clear if these should be one 1174) Firefox bug or several, but in particular we need better control over various 1175) aspects of TLS connections. Firefox currently provides no observer capable of 1176) extracting TLS parameters or certificates early enough to cancel a TLS 1177) 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 1178) the ability to <a class="ulink" href="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission" target="_top">have 1179) their certificates audited</a> by a <a class="ulink" href="http://www.networknotary.org/" target="_top">Perspectives</a>-style set of 1180) notaries. The problem with this is that the API observer points do not exist 1181) for any Firefox addon to actually block authentication token submission over a 1182) TLS channel, so every addon to date (including Perspectives) is actually 1183) providing users with notification after their authentication tokens have 1184) already been compromised. This obviously needs to be fixed. 1185) </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
add in the torbutton design... Andrew Lewman authored 13 years ago	1186) reduce precision of Date()</a><p> 1187) 1188) 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 1189) users based on their typing cadence</a> using the high precision timer 1190) available to javascript. Using this same precision, it is possible to compute 1191) an identifier based upon the clock drift of the client from some nominal 1192) source. The latter is not much of a concern for Tor users, as the variable 1193) delay to load and run a page is measured on the order of seconds, but the high 1194) precision timer can still be used to fingerprint aspects of a browser's 1195) javascript engine and processor, and apparently also a user's typing cadence. 1196) This bug hinders Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement. 1197)
Update Torbutton design doc. Mike Perry authored 13 years ago	`1198) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=122752" target="_top">Bug 122752 - SOCKS`
Update FF bugs in design do... Mike Perry authored 13 years ago	`1199) Username/Password Support</a><p> 1200) We need <a class="ulink" href="https://developer.mozilla.org/en/nsIProxyInfo" target="_top">Firefox`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1201) APIs</a> or about:config settings to control the SOCKS Username and`
Update FF bugs in design do... Mike Perry authored 13 years ago	`1202) Password fields. The reason why we need this support is to utilize an (as yet 1203) 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 1204) SOCKS username/password</a>. 1205) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Bug 409737 -`
add in the torbutton design... Andrew Lewman authored 13 years ago	1206) javascript.enabled and docShell.allowJavascript do not disable all event 1207) handlers</a><p> 1208) 1209) This bug allows pages to execute javascript via addEventListener and perhaps 1210) other callbacks. In order to prevent this bug from enabling an attacker to 1211) break the <a class="link" href="#isolation">Network Isolation</a> requirement, 1212) Torbutton 1.1.13 began blocking popups and history manipulation from different 1213) Tor states. So long as there are no ways to open popups or redirect the user 1214) to a new page, the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content 1215) policy</a> should block Javascript network access. However, if there are 1216) ways to open popups or perform redirects such that Torbutton cannot block 1217) them, pages may still have free reign to break that requirement and reveal a 1218) user's original IP address. 1219) 1220) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448743" target="_top">Bug 448743 - 1221) Decouple general.useragent.locale from spoofing of navigator.language</a><p> 1222) 1223) Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
Update Torbutton design doc. Mike Perry authored 13 years ago	`1224) attribute via <a class="link" href="#jshooks" title="Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,`
add in the torbutton design... Andrew Lewman authored 13 years ago	1225) these do not work on Firefox 3. It would be ideal to have 1226) a pref to set this value (something like a 1227) <span class="command"><strong>general.useragent.override.locale</strong></span>), 1228) to avoid fragmenting the anonymity set of users of foreign locales. This issue 1229) impedes Torbutton from fully meeting its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> 1230) requirement on Firefox 3. 1231) 1232) </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> 1233) The following bugs impact Torbutton and similar extensions' functionality.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1234) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=629820" target="_top">Bug 629820 - nsIContentPolicy::shouldLoad not`
Update Torbutton design doc. Mike Perry authored 13 years ago	1235) called for web request in Firefox Mobile</a><p> 1236) 1237) The new <a class="ulink" href="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis" target="_top">Electrolysis</a> 1238) multiprocess system appears to have some pretty rough edge cases with respect 1239) to registering XPCOM category managers such as the nsIContentPolicy, which 1240) make it difficult to do a straight-forward port of Torbutton or 1241) HTTPS-Everywhere to Firefox Mobile. It probably also has similar issues with 1242) wrapping existing <a class="link" href="#hookedxpcom" title="2.1. Hooked Components">Firefox XPCOM components</a>, 1243) which will also cause more problems for porting Torbutton. 1244)
Update Torbutton design doc. Mike Perry authored 13 years ago	`1245) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869" target="_top">Bug 417869 -`
add in the torbutton design... Andrew Lewman authored 13 years ago	1246) Browser context is difficult to obtain from many XPCOM callbacks</a><p> 1247) 1248) It is difficult to determine which tabbrowser many XPCOM callbacks originate 1249) from, and in some cases absolutely no context information is provided at all. 1250) While this doesn't have much of an effect on Torbutton, it does make writing 1251) extensions that would like to do per-tab settings and content filters (such as 1252) FoxyProxy) difficult to impossible to implement securely. 1253) 1254) </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> 1255) The following bugs have an effect upon Torbutton, but are superseded by more 1256) practical and more easily fixable variant bugs above; or have stable, simple 1257) workarounds.
Update Torbutton design doc. Mike Perry authored 13 years ago	`1258) </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">Bug 440892 -`
add in the torbutton design... Andrew Lewman authored 13 years ago	1259) network.protocol-handler.warn-external are ignored</a><p> 1260) 1261) Sometime in the Firefox 3 development cycle, the preferences that governed 1262) warning a user when external apps were launched got disconnected from the code 1263) that does the launching. Torbutton depended on these prefs to prevent websites 1264) from launching specially crafted documents and application arguments that 1265) 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 1266) popup before launching external apps while Tor is enabled. While this works, 1267) it would be nice if these prefs were either fixed or removed. 1268) 1269) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">Bug 437014 - 1270) nsIContentPolicy::shouldLoad no longer called for favicons</a><p> 1271) 1272) Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon 1273) loads. Torbutton had relied on this call to block favicon loads for opposite 1274) Tor states. The workaround it employs for Firefox 3 is to cancel the request 1275) when it arrives in the <span class="command"><strong>torbutton_http_observer</strong></span> used for 1276) blocking full page plugin loads. This seems to work just fine, but is a bit 1277) dirty. 1278) 1279) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">Bug 309524</a> 1280) and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">Bug 1281) 380556</a> - nsIContentPolicy::shouldProcess is not called. 1282) <p> 1283) 1284) This is a call that would be useful to develop a better workaround for the 1285) allowPlugins issue above. If the content policy were called before a URL was 1286) handed over to a plugin or helper app, it would make the workaround for the 1287) above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as 1288) the others though, but it might be nice to have this API as a backup. 1289) 1290) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">Bug 401296 - docShell.allowPlugins 1291) 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>?) 1292) <p> 1293) 1294) Similar to the javascript plugin disabling attribute, the plugin disabling 1295) attribute is also not perfect — it is ignored for direct links to plugin 1296) handled content, as well as meta-refreshes to plugin handled content. This 1297) requires Torbutton to listen to a number of different http events to intercept 1298) plugin-related mime type URLs and cancel their requests. Again, since plugins 1299) are quite horrible about obeying proxy settings, loading a plugin pretty much 1300) ensures a way to break the <a class="link" href="#isolation">Network Isolation</a> 1301) requirement and reveal a user's original IP address. Torbutton's code to 1302) perform this workaround has been subverted at least once already by Kyle 1303) Williams. 1304) 1305) </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598" target="_top">Bug 419598 - 'var 1306) Date' is deletable</a><p> 1307) 1308) 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 1309) Javascript spec</a>, it seems like it should be possible to do something 1310) like the following to prevent the Date object from being unmasked: 1311) </p><pre class="screen"> 1312) with(window) { 1313) var Date = fakeDate; 1314) var otherVariable = 42; 1315) } 1316) 1317) delete window.Date; // Should fail. Instead succeeds, revealing original Date. 1318) delete window.otherVariable; // Fails, leaving window.otherVariable set to 42. 1319) </pre><p> 1320) 1321) From the ECMA-262 spec: 1322) 1323) </p><div class="blockquote"><blockquote class="blockquote"> 1324) If the variable statement occurs inside a FunctionDeclaration, the variables 1325) are defined with function-local scope in that function, as described in 1326) s10.1.3. Otherwise, they are defined with global scope (that is, they are 1327) created as members of the global object, as described in 10.1.3) using 1328) property attributes { DontDelete }. Variables are created when the execution 1329) scope is entered. A Block does not define a new execution scope. Only Program 1330) and FunctionDeclaration produce a new scope. Variables are initialized to 1331) undefined when created. A variable with an Initialiser is assigned the value 1332) of its AssignmentExpression when the VariableStatement is executed, not when 1333) the variable is created. 1334) </blockquote></div><p> 1335) 1336) In fact, this is exactly how the with statement with a variable declaration 1337) behaves <span class="emphasis"><em>for all other variables other than ones that shadow system 1338) variables</em></span>. Some variables (such as 1339) <span class="command"><strong>window.screen</strong></span>, and <span class="command"><strong>window.history</strong></span>) can't 1340) even be shadowed in this way, and give an error about lacking a setter. If 1341) such shadowing were possible, it would greatly simplify the Javascript hooking 1342) code, which currently relies on undocumented semantics of 1343) <span class="command"><strong>__proto__</strong></span> to copy the original values in the event of a 1344) delete. This <span class="command"><strong>__proto__</strong></span> hack unfortunately does not work for 1345) the Date object though. 1346) 1347) </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> 1348) 1349) The purpose of this section is to cover all the known ways that Tor browser 1350) security can be subverted from a penetration testing perspective. The hope 1351) is that it will be useful both for creating a "Tor Safety Check" 1352) page, and for developing novel tests and actively attacking Torbutton with the 1353) goal of finding vulnerabilities in either it or the Mozilla components, 1354) interfaces and settings upon which it relies. 1355) 1356) </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> 1357) 1358) Torbutton is a complicated piece of software. During development, changes to 1359) one component can affect a whole slough of unrelated features. A number of 1360) aggregated test suites exist that can be used to test for regressions in 1361) Torbutton and to help aid in the development of Torbutton-like addons and 1362) other privacy modifications of other browsers. Some of these test suites exist 1363) as a single automated page, while others are a series of pages you must visit 1364) individually. They are provided here for reference and future regression 1365) testing, and also in the hope that some brave soul will one day decide to 1366) combine them into a comprehensive automated test suite. 1367) 1368) </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> 1369) 1370) Decloak.net is the canonical source of plugin and external-application based 1371) 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 1372) use to test their anonymity systems. 1373) 1374) </p></li><li class="listitem"><a class="ulink" href="http://deanonymizer.com/" target="_top">Deanonymizer.com</a><p> 1375) 1376) Deanonymizer.com is another automated test suite that tests for proxy bypass 1377) and other information disclosure vulnerabilities. It is maintained by Kyle 1378) Williams, the author of <a class="ulink" href="http://www.janusvm.com/" target="_top">JanusVM</a> 1379) and <a class="ulink" href="http://www.januspa.com/" target="_top">JanusPA</a>. 1380) 1381) </p></li><li class="listitem"><a class="ulink" href="https://www.jondos.de/en/anontest" target="_top">JonDos 1382) AnonTest</a><p> 1383) 1384) The <a class="ulink" href="https://www.jondos.de" target="_top">JonDos people</a> also provide an 1385) anonymity tester. It is more focused on HTTP headers than plugin bypass, and 1386) points out a couple of headers Torbutton could do a better job with 1387) obfuscating. 1388) 1389) </p></li><li class="listitem"><a class="ulink" href="http://browserspy.dk" target="_top">Browserspy.dk</a><p> 1390) 1391) Browserspy.dk provides a tremendous collection of browser fingerprinting and 1392) general privacy tests. Unfortunately they are only available one page at a 1393) time, and there is not really solid feedback on good vs bad behavior in 1394) the test results. 1395) 1396) </p></li><li class="listitem"><a class="ulink" href="http://analyze.privacy.net/" target="_top">Privacy 1397) Analyzer</a><p> 1398) 1399) The Privacy Analyzer provides a dump of all sorts of browser attributes and 1400) settings that it detects, including some information on your origin IP 1401) address. Its page layout and lack of good vs bad test result feedback makes it 1402) not as useful as a user-facing testing tool, but it does provide some 1403) interesting checks in a single page. 1404) 1405) </p></li><li class="listitem"><a class="ulink" href="http://ha.ckers.org/mr-t/" target="_top">Mr. T</a><p> 1406) 1407) Mr. T is a collection of browser fingerprinting and deanonymization exploits 1408) discovered by the <a class="ulink" href="http://ha.ckers.org" target="_top">ha.ckers.org</a> crew 1409) and others. It is also not as user friendly as some of the above tests, but it 1410) is a useful collection. 1411) 1412) </p></li><li class="listitem">Gregory Fleischer's <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">Torbutton</a> and 1413) <a class="ulink" href="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html" target="_top">Defcon 1414) 17</a> Test Cases 1415) <p> 1416) 1417) Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy 1418) issues for the past 2 years. He has an excellent collection of all his test 1419) cases that can be used for regression testing. In his Defcon work, he 1420) demonstrates ways to infer Firefox version based on arcane browser properties. 1421) We are still trying to determine the best way to address some of those test 1422) cases. 1423) 1424) </p></li><li class="listitem"><a class="ulink" href="https://torcheck.xenobite.eu/index.php" target="_top">Xenobite's 1425) TorCheck Page</a><p> 1426) 1427) This page checks to ensure you are using a valid Tor exit node and checks for 1428) some basic browser properties related to privacy. It is not very fine-grained 1429) or complete, but it is automated and could be turned into something useful 1430) with a bit of work. 1431) 1432) </p></li></ol></div><p>
Update Torbutton design doc. Mike Perry authored 13 years ago	`1433) </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2698010"></a>7.2. Multi-state testing</h3></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1434) 1435) The tests in this section are geared towards a page that would instruct the 1436) user to toggle their Tor state after the fetch and perform some operations: 1437) mouseovers, stray clicks, and potentially reloads. 1438)`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1439) </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2698022"></a>Cookies and Cache Correlation</h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	1440) The most obvious test is to set a cookie, ask the user to toggle tor, and then 1441) have them reload the page. The cookie should no longer be set if they are 1442) using the default Torbutton settings. In addition, it is possible to leverage 1443) the cache to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique 1444) identifiers</a>. The default settings of Torbutton should also protect 1445) against these from persisting across Tor Toggle. 1446)
Update Torbutton design doc. Mike Perry authored 13 years ago	`1447) </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2698045"></a>Javascript timers and event handlers</h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	`1448) 1449) Javascript can set timers and register event handlers in the hopes of fetching 1450) URLs after the user has toggled Torbutton.`
Update Torbutton design doc. Mike Perry authored 13 years ago	`1451) </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2698058"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>`
add in the torbutton design... Andrew Lewman authored 13 years ago	1452) 1453) Even if Javascript is disabled, CSS is still able to 1454) <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like 1455) windows</a> 1456) via the 'onmouseover' CSS attribute, which can cause arbitrary browser 1457) activity as soon as the mouse enters into the content window. It is also 1458) possible for meta-refresh tags to set timers long enough to make it likely 1459) that the user has toggled Tor before fetching content. 1460) 1461) </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> 1462) 1463) The idea behind active testing is to discover vulnerabilities in Torbutton to 1464) bypass proxy settings, run script in an opposite Tor state, store unique 1465) identifiers, leak location information, or otherwise violate <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. Torbutton has ventured out 1466) into a strange and new security landscape. It depends on Firefox mechanisms 1467) that haven't necessarily been audited for security, certainly not for the 1468) threat model that Torbutton seeks to address. As such, it and the interfaces 1469) it depends upon still need a 'trial by fire' typical of new technologies. This 1470) section of the document was written with the intention of making that period 1471) as fast as possible. Please help us get through this period by considering 1472) these attacks, playing with them, and reporting what you find (and potentially 1473) submitting the test cases back to be run in the standard batch of Torbutton 1474) tests. 1475)
Update Torbutton design doc. Mike Perry authored 13 years ago	`1476) </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2698112"></a>Some suggested vectors to investigate</h4></div></div></div><p>`