tor-webwml.git

torbutton/en/design/design.xml         1) <?xml version="1.0" encoding="ISO-8859-1"?>
torbutton/en/design/design.xml         2) <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
torbutton/en/design/design.xml         3)      "file:///usr/share/sgml/docbook/xml-dtd-4.4-1.0-30.1/docbookx.dtd">
torbutton/en/design/design.xml         4) 
torbutton/en/design/design.xml         5) <article id="design">
torbutton/en/design/design.xml         6)  <articleinfo>
torbutton/en/design/design.xml         7)   <title>Torbutton Design Documentation</title>
torbutton/en/design/design.xml         8)    <author>
torbutton/en/design/design.xml         9)     <firstname>Mike</firstname><surname>Perry</surname>
torbutton/en/design/design.xml        10)     <affiliation>
torbutton/en/design/design.xml        11)      <address><email>mikeperry.fscked/org</email></address>
torbutton/en/design/design.xml        12)     </affiliation>
torbutton/en/design/design.xml        13)    </author>

torbutton/en/design/design.xml        14)    <pubdate>Apr 10 2011</pubdate>

torbutton/en/design/design.xml        15)  </articleinfo>
torbutton/en/design/design.xml        16) 
torbutton/en/design/design.xml        17) <sect1>
torbutton/en/design/design.xml        18)   <title>Introduction</title>
torbutton/en/design/design.xml        19)   <para>
torbutton/en/design/design.xml        20) 
torbutton/en/design/design.xml        21) This document describes the goals, operation, and testing procedures of the

torbutton/en/design/design.xml        22) Torbutton Firefox extension. It is current as of Torbutton 1.3.2.

torbutton/en/design/design.xml        23) 
torbutton/en/design/design.xml        24)   </para>
torbutton/en/design/design.xml        25)   <sect2 id="adversary">
torbutton/en/design/design.xml        26)    <title>Adversary Model</title>
torbutton/en/design/design.xml        27)    <para>
torbutton/en/design/design.xml        28) 
torbutton/en/design/design.xml        29) A Tor web browser adversary has a number of goals, capabilities, and attack
torbutton/en/design/design.xml        30) types that can be used to guide us towards a set of requirements for the
torbutton/en/design/design.xml        31) Torbutton extension. Let's start with the goals.
torbutton/en/design/design.xml        32) 
torbutton/en/design/design.xml        33)    </para>
torbutton/en/design/design.xml        34)    <sect3 id="adversarygoals">
torbutton/en/design/design.xml        35)     <title>Adversary Goals</title>
torbutton/en/design/design.xml        36)     <orderedlist>
torbutton/en/design/design.xml        37) <!-- These aren't really commands.. But it's the closest I could find in an
torbutton/en/design/design.xml        38) acceptable style.. Don't really want to make my own stylesheet -->
torbutton/en/design/design.xml        39)      <listitem><command>Bypassing proxy settings</command>
torbutton/en/design/design.xml        40)      <para>The adversary's primary goal is direct compromise and bypass of 
torbutton/en/design/design.xml        41) Tor, causing the user to directly connect to an IP of the adversary's
torbutton/en/design/design.xml        42) choosing.</para>
torbutton/en/design/design.xml        43)      </listitem>
torbutton/en/design/design.xml        44)      <listitem><command>Correlation of Tor vs Non-Tor Activity</command>
torbutton/en/design/design.xml        45)      <para>If direct proxy bypass is not possible, the adversary will likely
torbutton/en/design/design.xml        46) happily settle for the ability to correlate something a user did via Tor with
torbutton/en/design/design.xml        47) their non-Tor activity. This can be done with cookies, cache identifiers,
torbutton/en/design/design.xml        48) javascript events, and even CSS. Sometimes the fact that a user uses Tor may
torbutton/en/design/design.xml        49) be enough for some authorities.</para>
torbutton/en/design/design.xml        50)      </listitem>
torbutton/en/design/design.xml        51)      <listitem><command>History disclosure</command>
torbutton/en/design/design.xml        52)      <para>
torbutton/en/design/design.xml        53) The adversary may also be interested in history disclosure: the ability to
torbutton/en/design/design.xml        54) query a user's history to see if they have issued certain censored search
torbutton/en/design/design.xml        55) queries, or visited censored sites.
torbutton/en/design/design.xml        56)      </para>
torbutton/en/design/design.xml        57)      </listitem>
torbutton/en/design/design.xml        58)      <listitem><command>Location information</command>
torbutton/en/design/design.xml        59)      <para>
torbutton/en/design/design.xml        60) 
torbutton/en/design/design.xml        61) Location information such as timezone and locality can be useful for the
torbutton/en/design/design.xml        62) adversary to determine if a user is in fact originating from one of the
torbutton/en/design/design.xml        63) regions they are attempting to control, or to zero-in on the geographical
torbutton/en/design/design.xml        64) location of a particular dissident or whistleblower.
torbutton/en/design/design.xml        65) 
torbutton/en/design/design.xml        66)      </para>
torbutton/en/design/design.xml        67)      </listitem>
torbutton/en/design/design.xml        68)      <listitem><command>Miscellaneous anonymity set reduction</command>
torbutton/en/design/design.xml        69)      <para>
torbutton/en/design/design.xml        70) 
torbutton/en/design/design.xml        71) Anonymity set reduction is also useful in attempting to zero in on a
torbutton/en/design/design.xml        72) particular individual. If the dissident or whistleblower is using a rare build
torbutton/en/design/design.xml        73) of Firefox for an obscure operating system, this can be very useful
torbutton/en/design/design.xml        74) information for tracking them down, or at least <link
torbutton/en/design/design.xml        75) linkend="fingerprinting">tracking their activities</link>.
torbutton/en/design/design.xml        76) 
torbutton/en/design/design.xml        77)      </para>
torbutton/en/design/design.xml        78)      </listitem>
torbutton/en/design/design.xml        79)      <listitem><command>History records and other on-disk
torbutton/en/design/design.xml        80) information</command>
torbutton/en/design/design.xml        81)      <para>
torbutton/en/design/design.xml        82) In some cases, the adversary may opt for a heavy-handed approach, such as
torbutton/en/design/design.xml        83) seizing the computers of all Tor users in an area (especially after narrowing
torbutton/en/design/design.xml        84) the field by the above two pieces of information). History records and cache
torbutton/en/design/design.xml        85) data are the primary goals here.
torbutton/en/design/design.xml        86)      </para>
torbutton/en/design/design.xml        87)      </listitem>
torbutton/en/design/design.xml        88)     </orderedlist>
torbutton/en/design/design.xml        89)    </sect3>
torbutton/en/design/design.xml        90) 
torbutton/en/design/design.xml        91)    <sect3 id="adversarypositioning">
torbutton/en/design/design.xml        92)     <title>Adversary Capabilities - Positioning</title>
torbutton/en/design/design.xml        93)     <para>
torbutton/en/design/design.xml        94) The adversary can position themselves at a number of different locations in
torbutton/en/design/design.xml        95) order to execute their attacks.
torbutton/en/design/design.xml        96)     </para>
torbutton/en/design/design.xml        97)     <orderedlist>
torbutton/en/design/design.xml        98)      <listitem><command>Exit Node or Upstream Router</command>
torbutton/en/design/design.xml        99)      <para>
torbutton/en/design/design.xml       100) The adversary can run exit nodes, or alternatively, they may control routers
torbutton/en/design/design.xml       101) upstream of exit nodes. Both of these scenarios have been observed in the
torbutton/en/design/design.xml       102) wild.
torbutton/en/design/design.xml       103)      </para>
torbutton/en/design/design.xml       104)      </listitem>
torbutton/en/design/design.xml       105)      <listitem><command>Adservers and/or Malicious Websites</command>
torbutton/en/design/design.xml       106)      <para>
torbutton/en/design/design.xml       107) The adversary can also run websites, or more likely, they can contract out
torbutton/en/design/design.xml       108) ad space from a number of different adservers and inject content that way. For
torbutton/en/design/design.xml       109) some users, the adversary may be the adservers themselves. It is not
torbutton/en/design/design.xml       110) inconceivable that adservers may try to subvert or reduce a user's anonymity 
torbutton/en/design/design.xml       111) through Tor for marketing purposes.
torbutton/en/design/design.xml       112)      </para>
torbutton/en/design/design.xml       113)      </listitem>
torbutton/en/design/design.xml       114)      <listitem><command>Local Network/ISP/Upstream Router</command>
torbutton/en/design/design.xml       115)      <para>
torbutton/en/design/design.xml       116) The adversary can also inject malicious content at the user's upstream router
torbutton/en/design/design.xml       117) when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
torbutton/en/design/design.xml       118) activity.
torbutton/en/design/design.xml       119)      </para>
torbutton/en/design/design.xml       120)      </listitem>
torbutton/en/design/design.xml       121)      <listitem><command>Physical Access</command>
torbutton/en/design/design.xml       122)      <para>
torbutton/en/design/design.xml       123) Some users face adversaries with intermittent or constant physical access.
torbutton/en/design/design.xml       124) Users in Internet cafes, for example, face such a threat. In addition, in
torbutton/en/design/design.xml       125) countries where simply using tools like Tor is illegal, users may face
torbutton/en/design/design.xml       126) confiscation of their computer equipment for excessive Tor usage or just
torbutton/en/design/design.xml       127) general suspicion.
torbutton/en/design/design.xml       128)      </para>
torbutton/en/design/design.xml       129)      </listitem>
torbutton/en/design/design.xml       130)     </orderedlist>
torbutton/en/design/design.xml       131)    </sect3>
torbutton/en/design/design.xml       132) 
torbutton/en/design/design.xml       133)    <sect3 id="attacks">
torbutton/en/design/design.xml       134)     <title>Adversary Capabilities - Attacks</title>
torbutton/en/design/design.xml       135)     <para>
torbutton/en/design/design.xml       136) 
torbutton/en/design/design.xml       137) The adversary can perform the following attacks from a number of different 
torbutton/en/design/design.xml       138) positions to accomplish various aspects of their goals. It should be noted
torbutton/en/design/design.xml       139) that many of these attacks (especially those involving IP address leakage) are
torbutton/en/design/design.xml       140) often performed by accident by websites that simply have Javascript, dynamic 
torbutton/en/design/design.xml       141) CSS elements, and plugins. Others are performed by adservers seeking to
torbutton/en/design/design.xml       142) correlate users' activity across different IP addresses, and still others are
torbutton/en/design/design.xml       143) performed by malicious agents on the Tor network and at national firewalls.
torbutton/en/design/design.xml       144) 
torbutton/en/design/design.xml       145)     </para>
torbutton/en/design/design.xml       146)     <orderedlist>
torbutton/en/design/design.xml       147)      <listitem><command>Inserting Javascript</command>
torbutton/en/design/design.xml       148)      <para>
torbutton/en/design/design.xml       149) If not properly disabled, Javascript event handlers and timers
torbutton/en/design/design.xml       150) can cause the browser to perform network activity after Tor has been disabled,
torbutton/en/design/design.xml       151) thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
torbutton/en/design/design.xml       152) a user's non-Tor IP address. Javascript
torbutton/en/design/design.xml       153) also allows the adversary to execute <ulink
torbutton/en/design/design.xml       154) url="http://whattheinternetknowsaboutyou.com/">history disclosure attacks</ulink>:
torbutton/en/design/design.xml       155) to query the history via the different attributes of 'visited' links to search

torbutton/en/design/design.xml       156) for particular Google queries, sites, or even to <ulink

torbutton/en/design/design.xml       157) url="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/">profile
torbutton/en/design/design.xml       158) users based on gender and other classifications</ulink>. Finally,
torbutton/en/design/design.xml       159) Javascript can be used to query the user's timezone via the
torbutton/en/design/design.xml       160) <function>Date()</function> object, and to reduce the anonymity set by querying
torbutton/en/design/design.xml       161) the <function>navigator</function> object for operating system, CPU, locale, 
torbutton/en/design/design.xml       162) and user agent information.
torbutton/en/design/design.xml       163)      </para>
torbutton/en/design/design.xml       164)      </listitem>
torbutton/en/design/design.xml       165) 
torbutton/en/design/design.xml       166)      <listitem><command>Inserting Plugins</command>
torbutton/en/design/design.xml       167)      <para>
torbutton/en/design/design.xml       168) 
torbutton/en/design/design.xml       169) Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
torbutton/en/design/design.xml       170) capable of performing network activity that the author has
torbutton/en/design/design.xml       171) investigated is also capable of performing network activity independent of
torbutton/en/design/design.xml       172) browser proxy settings - and often independent of its own proxy settings.
torbutton/en/design/design.xml       173) Sites that have plugin content don't even have to be malicious to obtain a
torbutton/en/design/design.xml       174) user's
torbutton/en/design/design.xml       175) Non-Tor IP (it usually leaks by itself), though <ulink
torbutton/en/design/design.xml       176) url="http://decloak.net">plenty of active
torbutton/en/design/design.xml       177) exploits</ulink> are possible as well. In addition, plugins can be used to store unique identifiers that are more
torbutton/en/design/design.xml       178) difficult to clear than standard cookies. 
torbutton/en/design/design.xml       179) <ulink url="http://epic.org/privacy/cookies/flash.html">Flash-based
torbutton/en/design/design.xml       180) cookies</ulink> fall into this category, but there are likely numerous other
torbutton/en/design/design.xml       181) examples.
torbutton/en/design/design.xml       182) 
torbutton/en/design/design.xml       183)      </para>
torbutton/en/design/design.xml       184)      </listitem>
torbutton/en/design/design.xml       185)      <listitem><command>Inserting CSS</command>
torbutton/en/design/design.xml       186)      <para>
torbutton/en/design/design.xml       187) 
torbutton/en/design/design.xml       188) CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
torbutton/en/design/design.xml       189) Non-Tor IP address, via the usage of
torbutton/en/design/design.xml       190) <ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">CSS
torbutton/en/design/design.xml       191) popups</ulink> - essentially CSS-based event handlers that fetch content via
torbutton/en/design/design.xml       192) CSS's onmouseover attribute. If these popups are allowed to perform network
torbutton/en/design/design.xml       193) activity in a different Tor state than they were loaded in, they can easily
torbutton/en/design/design.xml       194) correlate Tor and Non-Tor activity and reveal a user's IP address. In
torbutton/en/design/design.xml       195) addition, CSS can also be used without Javascript to perform <ulink
torbutton/en/design/design.xml       196) url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only history disclosure
torbutton/en/design/design.xml       197) attacks</ulink>.
torbutton/en/design/design.xml       198)      </para>
torbutton/en/design/design.xml       199)      </listitem>
torbutton/en/design/design.xml       200)      <listitem><command>Read and insert cookies</command>
torbutton/en/design/design.xml       201)      <para>
torbutton/en/design/design.xml       202) 
torbutton/en/design/design.xml       203) An adversary in a position to perform MITM content alteration can inject
torbutton/en/design/design.xml       204) document content elements to both read and inject cookies for
torbutton/en/design/design.xml       205) arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
torbutton/en/design/design.xml       206) sort of <ulink url="http://seclists.org/bugtraq/2007/Aug/0070.html">active
torbutton/en/design/design.xml       207) sidejacking</ulink>.
torbutton/en/design/design.xml       208) 
torbutton/en/design/design.xml       209)      </para>
torbutton/en/design/design.xml       210)      </listitem>
torbutton/en/design/design.xml       211)      <listitem><command>Create arbitrary cached content</command>
torbutton/en/design/design.xml       212)      <para>
torbutton/en/design/design.xml       213) 
torbutton/en/design/design.xml       214) Likewise, the browser cache can also be used to <ulink
torbutton/en/design/design.xml       215) url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
torbutton/en/design/design.xml       216) identifiers</ulink>. Since by default the cache has no same-origin policy,
torbutton/en/design/design.xml       217) these identifiers can be read by any domain, making them an ideal target for
torbutton/en/design/design.xml       218) adserver-class adversaries.
torbutton/en/design/design.xml       219) 
torbutton/en/design/design.xml       220)      </para>
torbutton/en/design/design.xml       221)      </listitem>

torbutton/en/design/design.xml       222) 

torbutton/en/design/design.xml       223)      <listitem id="fingerprinting"><command>Fingerprint users based on browser
torbutton/en/design/design.xml       224) attributes</command>
torbutton/en/design/design.xml       225) <para>
torbutton/en/design/design.xml       226) 
torbutton/en/design/design.xml       227) There is an absurd amount of information available to websites via attributes
torbutton/en/design/design.xml       228) of the browser. This information can be used to reduce anonymity set, or even
torbutton/en/design/design.xml       229) <ulink url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">uniquely
torbutton/en/design/design.xml       230) fingerprint individual users</ulink>. </para>
torbutton/en/design/design.xml       231) <para>
torbutton/en/design/design.xml       232) For illustration, let's perform a
torbutton/en/design/design.xml       233) back-of-the-envelope calculation on the number of anonymity sets for just the
torbutton/en/design/design.xml       234) resolution information available in the <ulink
torbutton/en/design/design.xml       235) url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
torbutton/en/design/design.xml       236) <ulink
torbutton/en/design/design.xml       237) url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>

torbutton/en/design/design.xml       238) objects.
torbutton/en/design/design.xml       239) 
torbutton/en/design/design.xml       240) 
torbutton/en/design/design.xml       241) 
torbutton/en/design/design.xml       242) Browser window resolution information provides something like

torbutton/en/design/design.xml       243) (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
torbutton/en/design/design.xml       244) information contributes about another factor of 5 (for about 5 resolutions in
torbutton/en/design/design.xml       245) typical use). In addition, the dimensions and position of the desktop taskbar
torbutton/en/design/design.xml       246) are available, which can reveal hints on OS information. This boosts the count

docs/torbutton/en/design/design.xml  247) by a factor of 5 (for each of the major desktop taskbars - Windows, Mac
docs/torbutton/en/design/design.xml  248) OS X, KDE and Gnome, and None). Subtracting the browser content window

torbutton/en/design/design.xml       249) size from the browser outer window size provide yet more information.
torbutton/en/design/design.xml       250) Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give

torbutton/en/design/design.xml       251) 2<superscript>3</superscript>=8). Interface effects such as title bar font size

torbutton/en/design/design.xml       252) and window manager settings gives a factor of about 9 (say 3 common font sizes

torbutton/en/design/design.xml       253) for the title bar and 3 common sizes for browser GUI element fonts).

torbutton/en/design/design.xml       254) Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
torbutton/en/design/design.xml       255) 2<superscript>29</superscript>, or a 29 bit identifier based on resolution
torbutton/en/design/design.xml       256) information alone. </para>
torbutton/en/design/design.xml       257) 
torbutton/en/design/design.xml       258) <para>
torbutton/en/design/design.xml       259) 

torbutton/en/design/design.xml       260) Of course, this space is non-uniform in user density and prone to incremental
torbutton/en/design/design.xml       261) changes. The <ulink
torbutton/en/design/design.xml       262) url="https://wiki.mozilla.org/Fingerprinting#Data">Panopticlick study
torbutton/en/design/design.xml       263) done</ulink> by the EFF attempts to measure the actual entropy - the number of
torbutton/en/design/design.xml       264) identifying bits of information encoded in browser properties.  Their result
torbutton/en/design/design.xml       265) data is definitely useful, and the metric is probably the appropriate one for
torbutton/en/design/design.xml       266) determining how identifying a particular browser property is. However, some
torbutton/en/design/design.xml       267) quirks of their study means that they do not extract as much information as
torbutton/en/design/design.xml       268) they could from display information: they only use desktop resolution (which
torbutton/en/design/design.xml       269) Torbutton reports as the window resolution) and do not attempt to infer the
torbutton/en/design/design.xml       270) size of toolbars.

torbutton/en/design/design.xml       271) 
torbutton/en/design/design.xml       272) </para>

torbutton/en/design/design.xml       273) <!--
torbutton/en/design/design.xml       274) FIXME: This is no longer true. Only certain addons are now discoverable, and
torbutton/en/design/design.xml       275) only if they want to be:
torbutton/en/design/design.xml       276) http://webdevwonders.com/detecting-firefox-add-ons/
torbutton/en/design/design.xml       277) https://developer.mozilla.org/en/Updating_web_applications_for_Firefox_3#section_7
torbutton/en/design/design.xml       278) 

torbutton/en/design/design.xml       279) <para>
torbutton/en/design/design.xml       280) 
torbutton/en/design/design.xml       281) To add insult to injury, <ulink
torbutton/en/design/design.xml       282) url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
torbutton/en/design/design.xml       283) attacks</ulink> mean that each and every extension on <ulink
torbutton/en/design/design.xml       284) url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
torbutton/en/design/design.xml       285) to that 2<superscript>29</superscript>. With hundreds of popular extensions
torbutton/en/design/design.xml       286) and thousands of extensions total, it is easy to see that this sort of
torbutton/en/design/design.xml       287) information is an impressively powerful identifier if used properly by a
torbutton/en/design/design.xml       288) competent and determined adversary such as an ad network.  Again, a
torbutton/en/design/design.xml       289) nearest-neighbor bit vector space approach here would also gracefully handle
torbutton/en/design/design.xml       290) incremental changes to installed extensions.
torbutton/en/design/design.xml       291) 
torbutton/en/design/design.xml       292) </para>

torbutton/en/design/design.xml       293) -->

torbutton/en/design/design.xml       294)      </listitem>
torbutton/en/design/design.xml       295)      <listitem><command>Remotely or locally exploit browser and/or
torbutton/en/design/design.xml       296) OS</command>
torbutton/en/design/design.xml       297)      <para>
torbutton/en/design/design.xml       298) Last, but definitely not least, the adversary can exploit either general 
torbutton/en/design/design.xml       299) browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
torbutton/en/design/design.xml       300) install malware and surveillance software. An adversary with physical access
torbutton/en/design/design.xml       301) can perform similar actions. Regrettably, this last attack capability is
torbutton/en/design/design.xml       302) outside of Torbutton's ability to defend against, but it is worth mentioning
torbutton/en/design/design.xml       303) for completeness.
torbutton/en/design/design.xml       304)      </para>
torbutton/en/design/design.xml       305)      </listitem>
torbutton/en/design/design.xml       306)     </orderedlist>
torbutton/en/design/design.xml       307)    </sect3>
torbutton/en/design/design.xml       308) 
torbutton/en/design/design.xml       309)   </sect2>
torbutton/en/design/design.xml       310) 
torbutton/en/design/design.xml       311)   <sect2 id="requirements">
torbutton/en/design/design.xml       312)    <title>Torbutton Requirements</title>
torbutton/en/design/design.xml       313) <note>
torbutton/en/design/design.xml       314) 
torbutton/en/design/design.xml       315) Since many settings satisfy multiple requirements, this design document is
torbutton/en/design/design.xml       316) organized primarily by Torbutton components and settings. However, if you are
torbutton/en/design/design.xml       317) the type that would rather read the document from the requirements
torbutton/en/design/design.xml       318) perspective, it is in fact possible to search for each of the following
torbutton/en/design/design.xml       319) requirement phrases in the text to find the relevant features that help meet
torbutton/en/design/design.xml       320) that requirement.
torbutton/en/design/design.xml       321) 
torbutton/en/design/design.xml       322) </note>
torbutton/en/design/design.xml       323)    <para>
torbutton/en/design/design.xml       324) 
torbutton/en/design/design.xml       325) From the above Adversary Model, a number of requirements become clear. 
torbutton/en/design/design.xml       326) 
torbutton/en/design/design.xml       327)    </para>
torbutton/en/design/design.xml       328) 
torbutton/en/design/design.xml       329) <orderedlist> 
torbutton/en/design/design.xml       330) <!-- These aren't really commands.. But it's the closest I could find in an
torbutton/en/design/design.xml       331) acceptable style.. Don't really want to make my own stylesheet -->
torbutton/en/design/design.xml       332)  <listitem id="proxy"><command>Proxy Obedience</command> 
torbutton/en/design/design.xml       333)  <para>The browser
torbutton/en/design/design.xml       334) MUST NOT bypass Tor proxy settings for any content.</para></listitem>
torbutton/en/design/design.xml       335)  <listitem id="state"><command>State Separation</command>
torbutton/en/design/design.xml       336)  <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
torbutton/en/design/design.xml       337)  one Tor state MUST NOT be accessible via the network in
torbutton/en/design/design.xml       338)  another Tor state.</para></listitem>

torbutton/en/design/design.xml       339)  <listitem id="isolation"><command>Network Isolation</command>
torbutton/en/design/design.xml       340)  <para>Pages MUST NOT perform any network activity in a Tor state different

torbutton/en/design/design.xml       341)  from the state they were originally loaded in.</para>
torbutton/en/design/design.xml       342)  <para>Note that this requirement is
torbutton/en/design/design.xml       343) being de-emphasized due to the coming shift to supporting only the Tor Browser
torbutton/en/design/design.xml       344) Bundles, which do not support a Toggle operation.</para></listitem>

torbutton/en/design/design.xml       345)  <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
torbutton/en/design/design.xml       346) the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
torbutton/en/design/design.xml       347) users whose network fingerprint does not obviously betray the fact that they
torbutton/en/design/design.xml       348) are using Tor. This should extend to the browser as well - Torbutton MUST NOT 

torbutton/en/design/design.xml       349) reveal its presence while Tor is disabled.
torbutton/en/design/design.xml       350) </para>
torbutton/en/design/design.xml       351)  <para>Note that this requirement is
torbutton/en/design/design.xml       352) being de-emphasized due to the coming shift to supporting only the Tor Browser
torbutton/en/design/design.xml       353) Bundles, which do not support a Toggle operation.</para>
torbutton/en/design/design.xml       354) </listitem>

torbutton/en/design/design.xml       355)  <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
torbutton/en/design/design.xml       356)  in memory beyond the duration of one Tor toggle.</para></listitem>
torbutton/en/design/design.xml       357)  <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
torbutton/en/design/design.xml       358)  timezone or locale via Tor.</para></listitem>
torbutton/en/design/design.xml       359)  <listitem id="setpreservation"><command>Anonymity Set

torbutton/en/design/design.xml       360) Preservation</command><para>The browser SHOULD NOT leak any other anonymity
torbutton/en/design/design.xml       361) set reducing or fingerprinting information

torbutton/en/design/design.xml       362)  (such as user agent, extension presence, and resolution information)
torbutton/en/design/design.xml       363) automatically via Tor. The assessment of the attacks above should make it clear
torbutton/en/design/design.xml       364) that anonymity set reduction is a very powerful method of tracking and
torbutton/en/design/design.xml       365) eventually identifying anonymous users.
torbutton/en/design/design.xml       366) </para></listitem>
torbutton/en/design/design.xml       367)  <listitem id="updates"><command>Update Safety</command><para>The browser
torbutton/en/design/design.xml       368) SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
torbutton/en/design/design.xml       369)  <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
torbutton/en/design/design.xml       370)  enable the user to switch between a number of different proxies. It MUST
torbutton/en/design/design.xml       371)  provide full Tor protection in the event a third-party proxy switcher has
torbutton/en/design/design.xml       372)  enabled the Tor proxy settings.</para></listitem>
torbutton/en/design/design.xml       373) </orderedlist>
torbutton/en/design/design.xml       374)   </sect2>
torbutton/en/design/design.xml       375)   <sect2 id="layout">
torbutton/en/design/design.xml       376)    <title>Extension Layout</title>
torbutton/en/design/design.xml       377) 
torbutton/en/design/design.xml       378) <para>Firefox extensions consist of two main categories of code: 'Components' and
torbutton/en/design/design.xml       379) 'Chrome'. Components are a fancy name for classes that implement a given
torbutton/en/design/design.xml       380) interface or interfaces. In Firefox, components <ulink
torbutton/en/design/design.xml       381) url="https://developer.mozilla.org/en/XPCOM">can be
torbutton/en/design/design.xml       382) written</ulink> in C++,
torbutton/en/design/design.xml       383) Javascript, or a mixture of both. Components have two identifiers: their
torbutton/en/design/design.xml       384) '<ulink
torbutton/en/design/design.xml       385) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
torbutton/en/design/design.xml       386) ID</ulink>' (a human readable path-like string), and their '<ulink
torbutton/en/design/design.xml       387) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
torbutton/en/design/design.xml       388) ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
torbutton/en/design/design.xml       389) 'Interface ID'. It is possible to 'hook' system components - to reimplement
torbutton/en/design/design.xml       390) their interface members with your own wrappers - but only if the rest of the
torbutton/en/design/design.xml       391) browser refers to the component by its Contract ID. If the browser refers to
torbutton/en/design/design.xml       392) the component by Class ID, it bypasses your hooks in that use case.
torbutton/en/design/design.xml       393) Technically, it may be possible to hook Class IDs by unregistering the
torbutton/en/design/design.xml       394) original component, and then re-registering your own, but this relies on
torbutton/en/design/design.xml       395) obsolete and deprecated interfaces and has proved to be less than
torbutton/en/design/design.xml       396) stable.</para>
torbutton/en/design/design.xml       397) 
torbutton/en/design/design.xml       398) <para>'Chrome' is a combination of XML and Javascript used to describe a window.
torbutton/en/design/design.xml       399) Extensions are allowed to create 'overlays' that are 'bound' to existing XML
torbutton/en/design/design.xml       400) window definitions, or they can create their own windows. The DTD for this XML
torbutton/en/design/design.xml       401) is called <ulink
torbutton/en/design/design.xml       402) url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
torbutton/en/design/design.xml       403)   </sect2>
torbutton/en/design/design.xml       404) </sect1>

torbutton/en/design/design.xml       405) <sect1 id="components">

torbutton/en/design/design.xml       406)   <title>Components</title>
torbutton/en/design/design.xml       407)   <para>
torbutton/en/design/design.xml       408) 
torbutton/en/design/design.xml       409) Torbutton installs components for two purposes: hooking existing components to
torbutton/en/design/design.xml       410) reimplement their interfaces; and creating new components that provide
torbutton/en/design/design.xml       411) services to other pieces of the extension.
torbutton/en/design/design.xml       412) 
torbutton/en/design/design.xml       413)   </para>
torbutton/en/design/design.xml       414) 

torbutton/en/design/design.xml       415)   <sect2 id="hookedxpcom">

torbutton/en/design/design.xml       416)    <title>Hooked Components</title>
torbutton/en/design/design.xml       417) 
torbutton/en/design/design.xml       418) <para>Torbutton makes extensive use of Contract ID hooking, and implements some
torbutton/en/design/design.xml       419) of its own standalone components as well.  Let's discuss the hooked components
torbutton/en/design/design.xml       420) first.</para>
torbutton/en/design/design.xml       421) 
torbutton/en/design/design.xml       422) <sect3 id="appblocker">
torbutton/en/design/design.xml       423)  <title><ulink
torbutton/en/design/design.xml       424) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1">@mozilla.org/uriloader/external-protocol-service;1
torbutton/en/design/design.xml       425) </ulink>, <ulink
torbutton/en/design/design.xml       426) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1">@mozilla.org/uriloader/external-helper-app-service;1</ulink>,
torbutton/en/design/design.xml       427) and <ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1">@mozilla.org/mime;1</ulink>
torbutton/en/design/design.xml       428) - <ulink

torbutton/en/design/design.xml       429)   url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>

torbutton/en/design/design.xml       430)  <para>
torbutton/en/design/design.xml       431) Due to <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
torbutton/en/design/design.xml       432) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink> allowing Firefox 3.x to automatically launch some
torbutton/en/design/design.xml       433) applications without user intervention, Torbutton had to wrap the three
torbutton/en/design/design.xml       434) components involved in launching external applications to provide user
torbutton/en/design/design.xml       435) confirmation before doing so while Tor is enabled. Since external applications
torbutton/en/design/design.xml       436) do not obey proxy settings, they can be manipulated to automatically connect
torbutton/en/design/design.xml       437) back to arbitrary servers outside of Tor with no user intervention. Fixing
torbutton/en/design/design.xml       438) this issue helps to satisfy Torbutton's <link linkend="proxy">Proxy
torbutton/en/design/design.xml       439) Obedience</link> Requirement.
torbutton/en/design/design.xml       440)  </para>
torbutton/en/design/design.xml       441) </sect3>
torbutton/en/design/design.xml       442) <sect3>
torbutton/en/design/design.xml       443) <title><ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
torbutton/en/design/design.xml       444) - <ulink

torbutton/en/design/design.xml       445)   url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink></title>

torbutton/en/design/design.xml       446) 
torbutton/en/design/design.xml       447) <para>This component was contributed by <ulink
torbutton/en/design/design.xml       448) url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
torbutton/en/design/design.xml       449) CSS and Javascript-based methods of history disclosure. The global-history
torbutton/en/design/design.xml       450) component is what is used by Firefox to determine if a link was visited or not
torbutton/en/design/design.xml       451) (to apply the appropriate style to the link). By hooking the <ulink
torbutton/en/design/design.xml       452) url="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29">isVisited</ulink>
torbutton/en/design/design.xml       453) and <ulink 
torbutton/en/design/design.xml       454) url="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29">addURI</ulink>
torbutton/en/design/design.xml       455) methods, Torbutton is able to selectively prevent history items from being
torbutton/en/design/design.xml       456) added or being displayed as visited, depending on the Tor state and the user's
torbutton/en/design/design.xml       457) preferences.
torbutton/en/design/design.xml       458) </para>
torbutton/en/design/design.xml       459) <para>
torbutton/en/design/design.xml       460) This component helps satisfy the <link linkend="state">State Separation</link>

torbutton/en/design/design.xml       461) and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton. It
torbutton/en/design/design.xml       462) is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
torbutton/en/design/design.xml       463) of the <ulink
torbutton/en/design/design.xml       464) url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">built-in
torbutton/en/design/design.xml       465) history protections</ulink>.

torbutton/en/design/design.xml       466) </para>
torbutton/en/design/design.xml       467) </sect3>
torbutton/en/design/design.xml       468) <sect3 id="livemarks">
torbutton/en/design/design.xml       469) <title><ulink
torbutton/en/design/design.xml       470) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">@mozilla.org/browser/livemark-service;2</ulink>
torbutton/en/design/design.xml       471) - <ulink

torbutton/en/design/design.xml       472)   url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>

torbutton/en/design/design.xml       473) <para>
torbutton/en/design/design.xml       474) 
torbutton/en/design/design.xml       475) The <ulink
torbutton/en/design/design.xml       476) url="http://www.mozilla.com/en-US/firefox/livebookmarks.html">livemark</ulink> service
torbutton/en/design/design.xml       477) is started by a timer that runs 5 seconds after Firefox
torbutton/en/design/design.xml       478) startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
torbutton/en/design/design.xml       479) disable it. We must wrap the component to prevent this start() call from
torbutton/en/design/design.xml       480) firing in the event the browser starts in Tor mode.
torbutton/en/design/design.xml       481) 
torbutton/en/design/design.xml       482) </para>
torbutton/en/design/design.xml       483) <para>
torbutton/en/design/design.xml       484) This component helps satisfy the <link linkend="isolation">Network
torbutton/en/design/design.xml       485) Isolation</link> and <link linkend="setpreservation">Anonymity Set
torbutton/en/design/design.xml       486) Preservation</link> requirements.
torbutton/en/design/design.xml       487) </para>
torbutton/en/design/design.xml       488) </sect3>
torbutton/en/design/design.xml       489) </sect2>
torbutton/en/design/design.xml       490) <sect2>
torbutton/en/design/design.xml       491) <title>New Components</title>
torbutton/en/design/design.xml       492) 
torbutton/en/design/design.xml       493) <para>Torbutton creates four new components that are used throughout the
torbutton/en/design/design.xml       494) extension. These components do not hook any interfaces, nor are they used
torbutton/en/design/design.xml       495) anywhere besides Torbutton itself.</para>
torbutton/en/design/design.xml       496) 

torbutton/en/design/design.xml       497) <sect3 id="cookiejar">

torbutton/en/design/design.xml       498) <title><ulink

torbutton/en/design/design.xml       499) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2

torbutton/en/design/design.xml       500) - components/cookie-jar-selector.js</ulink></title>
torbutton/en/design/design.xml       501) 
torbutton/en/design/design.xml       502) <para>The cookie jar selector (also based on code from <ulink
torbutton/en/design/design.xml       503) url="http://www.collinjackson.com/">Collin
torbutton/en/design/design.xml       504) Jackson</ulink>) is used by the Torbutton chrome to switch between

torbutton/en/design/design.xml       505) Tor and Non-Tor cookies. It stores an XML representation of the current
torbutton/en/design/design.xml       506) cookie state in memory and/or on disk. When Tor is toggled, it syncs the
torbutton/en/design/design.xml       507) current cookies to this XML store, and then loads the cookies for the other
torbutton/en/design/design.xml       508) state from the XML store.
torbutton/en/design/design.xml       509) </para>

torbutton/en/design/design.xml       510) 
torbutton/en/design/design.xml       511) <para>
torbutton/en/design/design.xml       512) This component helps to address the <link linkend="state">State
torbutton/en/design/design.xml       513) Isolation</link> requirement of Torbutton.
torbutton/en/design/design.xml       514) </para>
torbutton/en/design/design.xml       515) 
torbutton/en/design/design.xml       516) </sect3>
torbutton/en/design/design.xml       517) <sect3>
torbutton/en/design/design.xml       518) <title><ulink

torbutton/en/design/design.xml       519) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1

torbutton/en/design/design.xml       520) - components/torbutton-logger.js</ulink></title>
torbutton/en/design/design.xml       521) 
torbutton/en/design/design.xml       522) <para>The torbutton logger component allows on-the-fly redirection of torbutton
torbutton/en/design/design.xml       523) logging messages to either Firefox stderr
torbutton/en/design/design.xml       524) (<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
torbutton/en/design/design.xml       525) (<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
torbutton/en/design/design.xml       526) available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
torbutton/en/design/design.xml       527) change the loglevel on the fly by changing
torbutton/en/design/design.xml       528) <command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
torbutton/en/design/design.xml       529) </para>
torbutton/en/design/design.xml       530) </sect3>
torbutton/en/design/design.xml       531) <sect3 id="windowmapper">
torbutton/en/design/design.xml       532) 
torbutton/en/design/design.xml       533) <title><ulink

torbutton/en/design/design.xml       534) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js">@torproject.org/content-window-mapper;1

torbutton/en/design/design.xml       535) - components/window-mapper.js</ulink></title>
torbutton/en/design/design.xml       536) 
torbutton/en/design/design.xml       537) <para>Torbutton tags Firefox <ulink
torbutton/en/design/design.xml       538) url="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes">tabs</ulink> with a special variable that indicates the Tor
torbutton/en/design/design.xml       539) state the tab was most recently used under to fetch a page. The problem is
torbutton/en/design/design.xml       540) that for many Firefox events, it is not possible to determine the tab that is
torbutton/en/design/design.xml       541) actually receiving the event. The Torbutton window mapper allows the Torbutton
torbutton/en/design/design.xml       542) chrome and other components to look up a <ulink
torbutton/en/design/design.xml       543) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
torbutton/en/design/design.xml       544) tab</ulink> for a given <ulink
torbutton/en/design/design.xml       545) url="https://developer.mozilla.org/en/nsIDOMWindow">HTML content
torbutton/en/design/design.xml       546) window</ulink>. It does this by traversing all windows and all browsers, until it
torbutton/en/design/design.xml       547) finds the browser with the requested <ulink
torbutton/en/design/design.xml       548) url="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow">contentWindow</ulink> element. Since the content policy
torbutton/en/design/design.xml       549) and page loading in general can generate hundreds of these lookups, this
torbutton/en/design/design.xml       550) result is cached inside the component.
torbutton/en/design/design.xml       551) </para>
torbutton/en/design/design.xml       552) </sect3>

torbutton/en/design/design.xml       553) <sect3 id="crashobserver">
torbutton/en/design/design.xml       554)  <title><ulink
torbutton/en/design/design.xml       555) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">@torproject.org/crash-observer;1</ulink></title>
torbutton/en/design/design.xml       556)   <para>
torbutton/en/design/design.xml       557) 
torbutton/en/design/design.xml       558) This component detects when Firefox crashes by altering Firefox prefs during
torbutton/en/design/design.xml       559) runtime and checking for the same values at startup. It <ulink
torbutton/en/design/design.xml       560) url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()">synchronizes
torbutton/en/design/design.xml       561) the preference service</ulink> to ensure the altered prefs are written to disk
torbutton/en/design/design.xml       562) immediately.
torbutton/en/design/design.xml       563) 
torbutton/en/design/design.xml       564)   </para>
torbutton/en/design/design.xml       565) </sect3>
torbutton/en/design/design.xml       566) <sect3 id="tbsessionstore">
torbutton/en/design/design.xml       567)  <title><ulink
torbutton/en/design/design.xml       568) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js">@torproject.org/torbutton-ss-blocker;1</ulink></title>
torbutton/en/design/design.xml       569)   <para>
torbutton/en/design/design.xml       570) 
torbutton/en/design/design.xml       571) This component subscribes to the Firefox <ulink
torbutton/en/design/design.xml       572) url="https://developer.mozilla.org/en/Observer_Notifications#Session_Store">sessionstore-state-write</ulink>
torbutton/en/design/design.xml       573) observer event to filter out URLs from tabs loaded during Tor, to prevent them
torbutton/en/design/design.xml       574) from being written to disk. To do this, it checks the
torbutton/en/design/design.xml       575) <command>__tb_tor_fetched</command> tag of tab objects before writing them out. If
torbutton/en/design/design.xml       576) the tag is from a blocked Tor state, the tab is not written to disk.  This is
torbutton/en/design/design.xml       577) a rather expensive operation that involves potentially very large JSON
torbutton/en/design/design.xml       578) evaluations and object tree traversals, but it preferable to replacing the
torbutton/en/design/design.xml       579) Firefox session store with our own implementation, which is what was done in
torbutton/en/design/design.xml       580) years past.
torbutton/en/design/design.xml       581) 
torbutton/en/design/design.xml       582)   </para>
torbutton/en/design/design.xml       583) </sect3>
torbutton/en/design/design.xml       584) 
torbutton/en/design/design.xml       585) <sect3 id="refspoofer">
torbutton/en/design/design.xml       586)  <title><ulink
torbutton/en/design/design.xml       587) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js">@torproject.org/torRefSpoofer;1</ulink></title>
torbutton/en/design/design.xml       588)  <para>

torbutton/en/design/design.xml       589) This component handles optional referer spoofing for Torbutton. It implements a

torbutton/en/design/design.xml       590) form of "smart" referer spoofing using <ulink
torbutton/en/design/design.xml       591) url="https://developer.mozilla.org/en/Setting_HTTP_request_headers">http-on-modify-request</ulink>

torbutton/en/design/design.xml       592) to modify the Referer header. The code sends the default browser referer

torbutton/en/design/design.xml       593) header only if the destination domain is a suffix of the source, or if the
torbutton/en/design/design.xml       594) source is a suffix of the destination. Otherwise, it sends no referer. This
torbutton/en/design/design.xml       595) strange suffix logic is used as a heuristic: some rare sites on the web block
torbutton/en/design/design.xml       596) requests without proper referer headers, and this logic is an attempt to cater
torbutton/en/design/design.xml       597) to them. Unfortunately, it may not be enough. For example, google.fr will not
torbutton/en/design/design.xml       598) send a referer to google.com using this logic. Hence, it is off by default.
torbutton/en/design/design.xml       599)  </para>
torbutton/en/design/design.xml       600) </sect3>
torbutton/en/design/design.xml       601) 
torbutton/en/design/design.xml       602) <!-- FIXME: tor-protocol, tors-protocol need documenting, but
torbutton/en/design/design.xml       603) they are disabled by default for now, so no reason to add the
torbutton/en/design/design.xml       604) clutter+confusion. -->
torbutton/en/design/design.xml       605) 

torbutton/en/design/design.xml       606) <sect3 id="contentpolicy">
torbutton/en/design/design.xml       607) <title><ulink

torbutton/en/design/design.xml       608) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1

torbutton/en/design/design.xml       609) - components/cssblocker.js</ulink></title>
torbutton/en/design/design.xml       610) 
torbutton/en/design/design.xml       611) <para>This is a key component to Torbutton's security measures. When Tor is
torbutton/en/design/design.xml       612) toggled, Javascript is disabled, and pages are instructed to stop loading.
torbutton/en/design/design.xml       613) However, CSS is still able to perform network operations by loading styles for
torbutton/en/design/design.xml       614) onmouseover events and other operations. In addition, favicons can still be
torbutton/en/design/design.xml       615) loaded by the browser. The cssblocker component prevents this by implementing
torbutton/en/design/design.xml       616) and registering an <ulink
torbutton/en/design/design.xml       617) url="https://developer.mozilla.org/en/nsIContentPolicy">nsIContentPolicy</ulink>.
torbutton/en/design/design.xml       618) When an nsIContentPolicy is registered, Firefox checks every attempted network
torbutton/en/design/design.xml       619) request against its <ulink
torbutton/en/design/design.xml       620) url="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()">shouldLoad</ulink>
torbutton/en/design/design.xml       621) member function to determine if the load should proceed. In Torbutton's case,
torbutton/en/design/design.xml       622) the content policy looks up the appropriate browser tab using the <link
torbutton/en/design/design.xml       623) linkend="windowmapper">window mapper</link>,
torbutton/en/design/design.xml       624) and checks that tab's load tag against the current Tor state. If the tab was
torbutton/en/design/design.xml       625) loaded in a different state than the current state, the fetch is denied.
torbutton/en/design/design.xml       626) Otherwise, it is allowed.</para> This helps to achieve the <link
torbutton/en/design/design.xml       627) linkend="isolation">Network
torbutton/en/design/design.xml       628) Isolation</link> requirements of Torbutton.
torbutton/en/design/design.xml       629) 
torbutton/en/design/design.xml       630) <para>In addition, the content policy also blocks website javascript from

torbutton/en/design/design.xml       631) <ulink
torbutton/en/design/design.xml       632) url="http://webdevwonders.com/detecting-firefox-add-ons/">querying for

torbutton/en/design/design.xml       633) versions and existence of extension chrome</ulink> while Tor is enabled, and
torbutton/en/design/design.xml       634) also masks the presence of Torbutton to website javascript while Tor is
torbutton/en/design/design.xml       635) disabled. </para>
torbutton/en/design/design.xml       636) 
torbutton/en/design/design.xml       637) <para>
torbutton/en/design/design.xml       638) 
torbutton/en/design/design.xml       639) Finally, some of the work that logically belongs to the content policy is
torbutton/en/design/design.xml       640) instead handled by the <command>torbutton_http_observer</command> and
torbutton/en/design/design.xml       641) <command>torbutton_weblistener</command> in <ulink

torbutton/en/design/design.xml       642) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of

torbutton/en/design/design.xml       643) Firefox 3 favicon loads, popups, and full page plugins, which for whatever
torbutton/en/design/design.xml       644) reason are not passed to the Firefox content policy itself (see Firefox Bugs 
torbutton/en/design/design.xml       645) <ulink
torbutton/en/design/design.xml       646) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and 
torbutton/en/design/design.xml       647) <ulink
torbutton/en/design/design.xml       648) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
torbutton/en/design/design.xml       649) 
torbutton/en/design/design.xml       650) </para>
torbutton/en/design/design.xml       651) 
torbutton/en/design/design.xml       652) <!-- 
torbutton/en/design/design.xml       653) FIXME: Hrmm, the content policy doesn't really lend itself well to display 
torbutton/en/design/design.xml       654) this way.. People looking for this much detail should consult the source.
torbutton/en/design/design.xml       655) 
torbutton/en/design/design.xml       656) <para>
torbutton/en/design/design.xml       657)     <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
torbutton/en/design/design.xml       658)     <tgroup cols='5' align='left' colsep='1' rowsep='1'>
torbutton/en/design/design.xml       659)        <tbody>
torbutton/en/design/design.xml       660)        <row>
torbutton/en/design/design.xml       661)          <entry></entry>
torbutton/en/design/design.xml       662)          <entry>chrome/resource</entry>
torbutton/en/design/design.xml       663)          <entry>a3</entry>
torbutton/en/design/design.xml       664)          <entry>a4</entry>
torbutton/en/design/design.xml       665)          <entry>a5</entry>
torbutton/en/design/design.xml       666)        </row>
torbutton/en/design/design.xml       667)        <row>
torbutton/en/design/design.xml       668)          <entry>file</entry>
torbutton/en/design/design.xml       669)          <entry>b2</entry>
torbutton/en/design/design.xml       670)          <entry>b3</entry>
torbutton/en/design/design.xml       671)          <entry>b4</entry>
torbutton/en/design/design.xml       672)          <entry>b5</entry>
torbutton/en/design/design.xml       673)        </row>
torbutton/en/design/design.xml       674)        <row>
torbutton/en/design/design.xml       675)          <entry>c1</entry>
torbutton/en/design/design.xml       676)          <entry>c2</entry>
torbutton/en/design/design.xml       677)          <entry>c3</entry>
torbutton/en/design/design.xml       678)          <entry>c4</entry>
torbutton/en/design/design.xml       679)          <entry>c5</entry>
torbutton/en/design/design.xml       680)        </row>
torbutton/en/design/design.xml       681)        <row>
torbutton/en/design/design.xml       682)          <entry>d1</entry>
torbutton/en/design/design.xml       683)          <entry>d2</entry>
torbutton/en/design/design.xml       684)          <entry>d3</entry>
torbutton/en/design/design.xml       685)          <entry>d4</entry>
torbutton/en/design/design.xml       686)          <entry>d5</entry>
torbutton/en/design/design.xml       687)        </row>
torbutton/en/design/design.xml       688)        </tbody>
torbutton/en/design/design.xml       689)        </tgroup>
torbutton/en/design/design.xml       690)        </table>
torbutton/en/design/design.xml       691) </para>
torbutton/en/design/design.xml       692) -->
torbutton/en/design/design.xml       693) 
torbutton/en/design/design.xml       694) <para>
torbutton/en/design/design.xml       695) 
torbutton/en/design/design.xml       696) This helps to fulfill both the <link
torbutton/en/design/design.xml       697) linkend="setpreservation">Anonymity Set Preservation</link> and the <link
torbutton/en/design/design.xml       698) linkend="undiscoverability">Tor Undiscoverability</link> requirements of
torbutton/en/design/design.xml       699) Torbutton.</para>
torbutton/en/design/design.xml       700) 
torbutton/en/design/design.xml       701) </sect3>
torbutton/en/design/design.xml       702) </sect2>
torbutton/en/design/design.xml       703) </sect1>
torbutton/en/design/design.xml       704) <sect1>
torbutton/en/design/design.xml       705)  <title>Chrome</title>
torbutton/en/design/design.xml       706) 
torbutton/en/design/design.xml       707) <para>The chrome is where all the torbutton graphical elements and windows are

torbutton/en/design/design.xml       708) located. </para>
torbutton/en/design/design.xml       709) <sect2>
torbutton/en/design/design.xml       710)  <title>XUL Windows and Overlays</title>
torbutton/en/design/design.xml       711) <para>
torbutton/en/design/design.xml       712) Each window is described as an <ulink

torbutton/en/design/design.xml       713) url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
torbutton/en/design/design.xml       714) files attached. The scope of these Javascript files is their containing

torbutton/en/design/design.xml       715) window. XUL files that add new elements and script to existing Firefox windows
torbutton/en/design/design.xml       716) are called overlays.</para>

torbutton/en/design/design.xml       717) 

torbutton/en/design/design.xml       718) <sect3 id="browseroverlay">

torbutton/en/design/design.xml       719) <title>Browser Overlay - <ulink

torbutton/en/design/design.xml       720) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>

torbutton/en/design/design.xml       721) 
torbutton/en/design/design.xml       722) <para>The browser overlay, torbutton.xul, defines the toolbar button, the status
torbutton/en/design/design.xml       723) bar, and events for toggling the button. The overlay code is in <ulink

torbutton/en/design/design.xml       724) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.

torbutton/en/design/design.xml       725) It contains event handlers for preference update, shutdown, upgrade, and
torbutton/en/design/design.xml       726) location change events.</para>
torbutton/en/design/design.xml       727) 

torbutton/en/design/design.xml       728) </sect3>
torbutton/en/design/design.xml       729) <sect3>
torbutton/en/design/design.xml       730)  <title>Preferences Window - <ulink
torbutton/en/design/design.xml       731) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
torbutton/en/design/design.xml       732) 
torbutton/en/design/design.xml       733) <para>The preferences window of course lays out the Torbutton preferences, with
torbutton/en/design/design.xml       734) handlers located in <ulink
torbutton/en/design/design.xml       735) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
torbutton/en/design/design.xml       736) </sect3>
torbutton/en/design/design.xml       737) <sect3>
torbutton/en/design/design.xml       738)  <title>Other Windows</title>
torbutton/en/design/design.xml       739) 
torbutton/en/design/design.xml       740) <para>There are additional windows that describe popups for right clicking on
torbutton/en/design/design.xml       741) the status bar, the toolbutton, and the about page.</para>
torbutton/en/design/design.xml       742) 
torbutton/en/design/design.xml       743) </sect3>
torbutton/en/design/design.xml       744) </sect2>
torbutton/en/design/design.xml       745) <sect2>
torbutton/en/design/design.xml       746)  <title>Major Chrome Observers</title>
torbutton/en/design/design.xml       747)  <para>
torbutton/en/design/design.xml       748) In addition to the <link linkend="components">components described
torbutton/en/design/design.xml       749) above</link>, Torbutton also instantiates several observers in the browser
torbutton/en/design/design.xml       750) overlay window. These mostly grew due to scoping convenience, and many should
torbutton/en/design/design.xml       751) probably be relocated into their own components.
torbutton/en/design/design.xml       752)  </para>
torbutton/en/design/design.xml       753)   <orderedlist>
torbutton/en/design/design.xml       754)    <listitem><command>torbutton_window_pref_observer</command>
torbutton/en/design/design.xml       755)     <para>
torbutton/en/design/design.xml       756) This is an observer that listens for Torbutton state changes, for the purposes
torbutton/en/design/design.xml       757) of updating the Torbutton button graphic as the Tor state changes.
torbutton/en/design/design.xml       758)     </para>
torbutton/en/design/design.xml       759)    </listitem>
torbutton/en/design/design.xml       760) 
torbutton/en/design/design.xml       761)    <listitem><command>torbutton_unique_pref_observer</command>
torbutton/en/design/design.xml       762)     <para>
torbutton/en/design/design.xml       763) 
torbutton/en/design/design.xml       764) This is an observer that only runs in one window, called the main window. It
torbutton/en/design/design.xml       765) listens for changes to all of the Torbutton preferences, as well as Torbutton
torbutton/en/design/design.xml       766) controlled Firefox preferences. It is what carries out the toggle path when
torbutton/en/design/design.xml       767) the proxy settings change. When the main window is closed, the
torbutton/en/design/design.xml       768) torbutton_close_window event handler runs to dub a new window the "main
torbutton/en/design/design.xml       769) window".
torbutton/en/design/design.xml       770) 
torbutton/en/design/design.xml       771)     </para>
torbutton/en/design/design.xml       772)    </listitem>
torbutton/en/design/design.xml       773) 
torbutton/en/design/design.xml       774)    <listitem><command>tbHistoryListener</command>
torbutton/en/design/design.xml       775)     <para>
torbutton/en/design/design.xml       776) The tbHistoryListener exists to prevent client window Javascript from
torbutton/en/design/design.xml       777) interacting with window.history to forcibly navigate a user to a tab session
torbutton/en/design/design.xml       778) history entry from a different Tor state. It also expunges the window.history
torbutton/en/design/design.xml       779) entries during toggle. This listener helps Torbutton
torbutton/en/design/design.xml       780) satisfy the <link linkend="isolation">Network Isolation</link> requirement as
torbutton/en/design/design.xml       781) well as the <link linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml       782) 
torbutton/en/design/design.xml       783)     </para>
torbutton/en/design/design.xml       784)    </listitem>
torbutton/en/design/design.xml       785) 
torbutton/en/design/design.xml       786)    <listitem><command>torbutton_http_observer</command>
torbutton/en/design/design.xml       787)     <para>
torbutton/en/design/design.xml       788) 
torbutton/en/design/design.xml       789) The torbutton_http_observer performs some of the work that logically belongs
torbutton/en/design/design.xml       790) to the content policy. This handles blocking of
torbutton/en/design/design.xml       791) Firefox 3 favicon loads, which for whatever
torbutton/en/design/design.xml       792) reason are not passed to the Firefox content policy itself (see Firefox Bugs
torbutton/en/design/design.xml       793) <ulink
torbutton/en/design/design.xml       794) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and
torbutton/en/design/design.xml       795) <ulink
torbutton/en/design/design.xml       796) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
torbutton/en/design/design.xml       797) 
torbutton/en/design/design.xml       798)     </para>
torbutton/en/design/design.xml       799)     <para>
torbutton/en/design/design.xml       800) The observer is also responsible for redirecting users to alternate
torbutton/en/design/design.xml       801) search engines when Google presents them with a Captcha, as well as copying
torbutton/en/design/design.xml       802) Google Captcha-related cookies between international Google domains.
torbutton/en/design/design.xml       803)     </para>
torbutton/en/design/design.xml       804)    </listitem>
torbutton/en/design/design.xml       805) 
torbutton/en/design/design.xml       806)    <listitem><command>torbutton_proxyservice</command>
torbutton/en/design/design.xml       807)     <para>
torbutton/en/design/design.xml       808) The Torbutton proxy service handles redirecting Torbutton-related update
torbutton/en/design/design.xml       809) checks on addons.mozilla.org through Tor. This is done to help satisfy the
torbutton/en/design/design.xml       810) <link linkend="undiscoverability">Tor Undiscoverability</link> requirement.
torbutton/en/design/design.xml       811)     </para>
torbutton/en/design/design.xml       812)    </listitem>
torbutton/en/design/design.xml       813) 
torbutton/en/design/design.xml       814)    <listitem><command>torbutton_weblistener</command>

torbutton/en/design/design.xml       815) <para>The <ulink
torbutton/en/design/design.xml       816) url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
torbutton/en/design/design.xml       817) change</ulink> <ulink
torbutton/en/design/design.xml       818) url="https://developer.mozilla.org/en/nsIWebProgress">webprogress
torbutton/en/design/design.xml       819) listener</ulink>, <command>torbutton_weblistener</command> is one of the most
torbutton/en/design/design.xml       820) important parts of the chrome from a security standpoint. It is a <ulink
torbutton/en/design/design.xml       821) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
torbutton/en/design/design.xml       822) listener</ulink> that handles receiving an event every time a page load or
torbutton/en/design/design.xml       823) iframe load occurs. This class eventually calls down to
torbutton/en/design/design.xml       824) <function>torbutton_update_tags()</function> and
torbutton/en/design/design.xml       825) <function>torbutton_hookdoc()</function>, which apply the browser Tor load
torbutton/en/design/design.xml       826) state tags, plugin permissions, and install the Javascript hooks to hook the
torbutton/en/design/design.xml       827) <ulink
torbutton/en/design/design.xml       828) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
torbutton/en/design/design.xml       829) object to obfuscate browser and desktop resolution information.
torbutton/en/design/design.xml       830) 
torbutton/en/design/design.xml       831) </para>

torbutton/en/design/design.xml       832)    </listitem>
torbutton/en/design/design.xml       833) 
torbutton/en/design/design.xml       834)   </orderedlist>
torbutton/en/design/design.xml       835)  </sect2>
torbutton/en/design/design.xml       836) </sect1>
torbutton/en/design/design.xml       837) 
torbutton/en/design/design.xml       838) <sect1>
torbutton/en/design/design.xml       839)  <title>Toggle Code Path</title>
torbutton/en/design/design.xml       840)  <para>
torbutton/en/design/design.xml       841) 
torbutton/en/design/design.xml       842) The act of toggling is connected to <function>torbutton_toggle()</function>
torbutton/en/design/design.xml       843) via the <ulink
torbutton/en/design/design.xml       844) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
torbutton/en/design/design.xml       845) and <ulink
torbutton/en/design/design.xml       846) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul">popup.xul</ulink>
torbutton/en/design/design.xml       847) overlay files. Most of the work in the toggling process is present in <ulink
torbutton/en/design/design.xml       848) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink> 

torbutton/en/design/design.xml       849) 

torbutton/en/design/design.xml       850) </para>

torbutton/en/design/design.xml       851) <para>

torbutton/en/design/design.xml       852) 
torbutton/en/design/design.xml       853) Toggling is a 3 stage process: Button Click, Proxy Update, and
torbutton/en/design/design.xml       854) Settings Update. These stages are reflected in the prefs
torbutton/en/design/design.xml       855) <command>extensions.torbutton.tor_enabled</command>,
torbutton/en/design/design.xml       856) <command>extensions.torbutton.proxies_applied</command>, and
torbutton/en/design/design.xml       857) <command>extensions.torbutton.settings_applied</command>. The reason for the
torbutton/en/design/design.xml       858) three stage preference update is to ensure immediate enforcement of <link
torbutton/en/design/design.xml       859) linkend="isolation">Network Isolation</link> via the <link
torbutton/en/design/design.xml       860) linkend="contentpolicy">content policy</link>. Since the content window
torbutton/en/design/design.xml       861) javascript runs on a different thread than the chrome javascript, it is
torbutton/en/design/design.xml       862) important to properly convey the stages to the content policy to avoid race
torbutton/en/design/design.xml       863) conditions and leakage, especially with <ulink
torbutton/en/design/design.xml       864) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
torbutton/en/design/design.xml       865) 409737</ulink> unfixed. The content policy does not allow any network activity
torbutton/en/design/design.xml       866) whatsoever during this three stage transition.
torbutton/en/design/design.xml       867) 
torbutton/en/design/design.xml       868)  </para>
torbutton/en/design/design.xml       869)  <sect2>
torbutton/en/design/design.xml       870)   <title>Button Click</title>
torbutton/en/design/design.xml       871)   <para>
torbutton/en/design/design.xml       872) 
torbutton/en/design/design.xml       873) This is the first step in the toggling process. When the user clicks the
torbutton/en/design/design.xml       874) toggle button or the toolbar, <function>torbutton_toggle()</function> is
torbutton/en/design/design.xml       875) called. This function checks the current Tor status by comparing the current
torbutton/en/design/design.xml       876) proxy settings to the selected Tor settings, and then sets the proxy settings
torbutton/en/design/design.xml       877) to the opposite state, and sets the pref
torbutton/en/design/design.xml       878) <command>extensions.torbutton.tor_enabled</command> to reflect the new state.
torbutton/en/design/design.xml       879) It is this proxy pref update that gives notification via the <ulink
torbutton/en/design/design.xml       880) url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
torbutton/en/design/design.xml       881) observer</ulink>
torbutton/en/design/design.xml       882) <command>torbutton_unique_pref_observer</command> to perform the rest of the
torbutton/en/design/design.xml       883) toggle.
torbutton/en/design/design.xml       884) 
torbutton/en/design/design.xml       885)   </para>
torbutton/en/design/design.xml       886)  </sect2>
torbutton/en/design/design.xml       887)  <sect2>
torbutton/en/design/design.xml       888)   <title>Proxy Update</title>
torbutton/en/design/design.xml       889)   <para>
torbutton/en/design/design.xml       890) 
torbutton/en/design/design.xml       891) When Torbutton receives any proxy change notifications via its
torbutton/en/design/design.xml       892) <command>torbutton_unique_pref_observer</command>, it calls
torbutton/en/design/design.xml       893) <function>torbutton_set_status()</function> which checks against the Tor
torbutton/en/design/design.xml       894) settings to see if the Tor proxy settings match the current settings. If so,
torbutton/en/design/design.xml       895) it calls <function>torbutton_update_status()</function>, which determines if
torbutton/en/design/design.xml       896) the Tor state has actually changed, and sets
torbutton/en/design/design.xml       897) <command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
torbutton/en/design/design.xml       898) state value, and ensures that
torbutton/en/design/design.xml       899) <command>extensions.torbutton.tor_enabled</command> is also set to the correct
torbutton/en/design/design.xml       900) value. This is decoupled from the button click functionality via the pref
torbutton/en/design/design.xml       901) observer so that other addons (such as SwitchProxy) can switch the proxy
torbutton/en/design/design.xml       902) settings between multiple proxies.
torbutton/en/design/design.xml       903) 
torbutton/en/design/design.xml       904)   </para>
torbutton/en/design/design.xml       905)  </sect2>
torbutton/en/design/design.xml       906) <!-- FIXME: Describe tab tagging and other state clearing hacks? -->
torbutton/en/design/design.xml       907)  <sect2>
torbutton/en/design/design.xml       908)   <title>Settings Update</title>
torbutton/en/design/design.xml       909)   <para>
torbutton/en/design/design.xml       910) 
torbutton/en/design/design.xml       911) The next stage is also handled by
torbutton/en/design/design.xml       912) <function>torbutton_update_status()</function>. This function sets scores of
torbutton/en/design/design.xml       913) Firefox preferences, saving the original values to prefs under
torbutton/en/design/design.xml       914) <command>extensions.torbutton.saved.*</command>, and performs the <link
torbutton/en/design/design.xml       915) linkend="cookiejar">cookie jarring</link>, state clearing (such as window.name
torbutton/en/design/design.xml       916) and DOM storage), and <link linkend="preferences">preference
torbutton/en/design/design.xml       917) toggling</link><!--, and ssl certificate jaring work of Torbutton-->. At the
torbutton/en/design/design.xml       918) end of its work, it sets
torbutton/en/design/design.xml       919) <command>extensions.torbutton.settings_applied</command>, which signifies the
torbutton/en/design/design.xml       920) completion of the toggle operation to the <link
torbutton/en/design/design.xml       921) linkend="contentpolicy">content policy</link>.
torbutton/en/design/design.xml       922) 
torbutton/en/design/design.xml       923)   </para>
torbutton/en/design/design.xml       924)  </sect2>
torbutton/en/design/design.xml       925) <sect2 id="preferences">
torbutton/en/design/design.xml       926) <title>Firefox preferences touched during Toggle</title>
torbutton/en/design/design.xml       927) <para>
torbutton/en/design/design.xml       928) There are also a number of Firefox preferences set in

torbutton/en/design/design.xml       929) <function>torbutton_update_status()</function> that aren't governed by any
torbutton/en/design/design.xml       930) Torbutton setting. These are:
torbutton/en/design/design.xml       931) </para>
torbutton/en/design/design.xml       932) <orderedlist>
torbutton/en/design/design.xml       933) 
torbutton/en/design/design.xml       934) <!--
torbutton/en/design/design.xml       935) Not set any more.
torbutton/en/design/design.xml       936)  <listitem><ulink
torbutton/en/design/design.xml       937) url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
torbutton/en/design/design.xml       938) <para>
torbutton/en/design/design.xml       939) This pref is set in an attempt to disable the fetching of LiveBookmarks via
torbutton/en/design/design.xml       940) Tor. Since users can potentially collect a large amount of live bookmarks to
torbutton/en/design/design.xml       941) very personal sites (blogs of friends, wikipedia articles they maintain,
torbutton/en/design/design.xml       942) comment feeds of their own blog), it is not possible to cleanly isolate these
torbutton/en/design/design.xml       943) fetches and they are simply disabled during Tor usage.
torbutton/en/design/design.xml       944) This helps to address the <link
torbutton/en/design/design.xml       945) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml       946) Unfortunately <ulink
torbutton/en/design/design.xml       947) url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
torbutton/en/design/design.xml       948) 436250</ulink> prevents this from
torbutton/en/design/design.xml       949) functioning completely correctly.
torbutton/en/design/design.xml       950) </para>
torbutton/en/design/design.xml       951)   </listitem>
torbutton/en/design/design.xml       952) -->
torbutton/en/design/design.xml       953) 
torbutton/en/design/design.xml       954)  <listitem><ulink
torbutton/en/design/design.xml       955) url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
torbutton/en/design/design.xml       956)  <para>
torbutton/en/design/design.xml       957) Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
torbutton/en/design/design.xml       958) reads from <command>extensions.torbutton.banned_ports</command>) to the list
torbutton/en/design/design.xml       959) of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
torbutton/en/design/design.xml       960) and the Tor control port, respectively. This is set for both Tor and Non-Tor
torbutton/en/design/design.xml       961) usage, and prevents websites from attempting to do http fetches from these
torbutton/en/design/design.xml       962) ports to see if they are open, which addresses the <link
torbutton/en/design/design.xml       963) linkend="undiscoverability">Tor Undiscoverability</link> requirement.
torbutton/en/design/design.xml       964)  </para>
torbutton/en/design/design.xml       965)  </listitem>
torbutton/en/design/design.xml       966)  <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
torbutton/en/design/design.xml       967)  <para>
torbutton/en/design/design.xml       968) This setting is currently always disabled. If anyone ever complains saying
torbutton/en/design/design.xml       969) that they *want* their browser to be able to send ping notifications to a
torbutton/en/design/design.xml       970) page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
torbutton/en/design/design.xml       971) my breath. I haven't checked if the content policy is called for pings, but if
torbutton/en/design/design.xml       972) not, this setting helps with meeting the <link linkend="isolation">Network
torbutton/en/design/design.xml       973) Isolation</link> requirement.
torbutton/en/design/design.xml       974)  </para>
torbutton/en/design/design.xml       975)  </listitem>
torbutton/en/design/design.xml       976)  <listitem><ulink
torbutton/en/design/design.xml       977) url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
torbutton/en/design/design.xml       978)  <para>
torbutton/en/design/design.xml       979) Likewise for this setting. I find it hard to imagine anyone who wants to ask
torbutton/en/design/design.xml       980) Google in real time if each URL they visit is safe, especially when the list
torbutton/en/design/design.xml       981) of unsafe URLs is downloaded anyway. This helps fulfill the <link
torbutton/en/design/design.xml       982) linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
torbutton/en/design/design.xml       983) browsing history from ending up on Google's disks.
torbutton/en/design/design.xml       984)  </para>
torbutton/en/design/design.xml       985)  </listitem>
torbutton/en/design/design.xml       986)  <listitem><ulink
torbutton/en/design/design.xml       987) url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
torbutton/en/design/design.xml       988)  <para>
torbutton/en/design/design.xml       989) Safebrowsing does <ulink
torbutton/en/design/design.xml       990) url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
torbutton/en/design/design.xml       991) updates under Firefox 2</ulink>, so it is disabled during Tor usage. 
torbutton/en/design/design.xml       992) This helps fulfill the <link linkend="updates">Update
torbutton/en/design/design.xml       993) Safety</link> requirement. Firefox 3 has the fix for that bug, and so
torbutton/en/design/design.xml       994) safebrowsing updates are enabled during Tor usage.
torbutton/en/design/design.xml       995)  </para>
torbutton/en/design/design.xml       996)  </listitem>
torbutton/en/design/design.xml       997)  <listitem><ulink
torbutton/en/design/design.xml       998) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
torbutton/en/design/design.xml       999)  <para>
torbutton/en/design/design.xml      1000) If Tor is enabled, we need to prevent random external applications from
torbutton/en/design/design.xml      1001) launching without at least warning the user. This group of settings only
torbutton/en/design/design.xml      1002) partially accomplishes this, however. Applications can still be launched via
torbutton/en/design/design.xml      1003) plugins. The mechanisms for handling this are described under the "Disable
torbutton/en/design/design.xml      1004) Plugins During Tor Usage" preference. This helps fulfill the <link
torbutton/en/design/design.xml      1005) linkend="proxy">Proxy Obedience</link> requirement, by preventing external
torbutton/en/design/design.xml      1006) applications from accessing network resources at the command of Tor-fetched
torbutton/en/design/design.xml      1007) pages. Unfortunately, due to <link linkend="FirefoxBugs">Firefox Bug</link>
torbutton/en/design/design.xml      1008) <ulink
torbutton/en/design/design.xml      1009) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink>,
torbutton/en/design/design.xml      1010) these prefs are no longer obeyed. They are set still anyway out of respect for
torbutton/en/design/design.xml      1011) the dead.
torbutton/en/design/design.xml      1012)  </para>
torbutton/en/design/design.xml      1013) </listitem>
torbutton/en/design/design.xml      1014)   <listitem><ulink
torbutton/en/design/design.xml      1015) url="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo">browser.sessionstore.max_tabs_undo</ulink>
torbutton/en/design/design.xml      1016)    <para>
torbutton/en/design/design.xml      1017) 
torbutton/en/design/design.xml      1018) To help satisfy the Torbutton <link linkend="state">State Separation</link>
torbutton/en/design/design.xml      1019) and <link linkend="isolation">Network Isolation</link> requirements,
torbutton/en/design/design.xml      1020) Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
torbutton/en/design/design.xml      1021) "Undo Close" operations from accidentally restoring tabs from a different Tor
torbutton/en/design/design.xml      1022) State. This purge is accomplished by setting this preference to 0 and then
torbutton/en/design/design.xml      1023) restoring it to the previous user value upon toggle.
torbutton/en/design/design.xml      1024) 
torbutton/en/design/design.xml      1025)    </para>
torbutton/en/design/design.xml      1026)   </listitem>
torbutton/en/design/design.xml      1027) 

torbutton/en/design/design.xml      1028)   <listitem><command>security.enable_ssl2</command> or <ulink
torbutton/en/design/design.xml      1029) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto">nsIDOMCrypto::logout()</ulink>

torbutton/en/design/design.xml      1030)    <para>
torbutton/en/design/design.xml      1031) TLS Session IDs can persist for an indefinite duration, providing an
torbutton/en/design/design.xml      1032) identifier that is sent to TLS sites that can be used to link activity. This
torbutton/en/design/design.xml      1033) is particularly troublesome now that we have certificate verification in place
torbutton/en/design/design.xml      1034) in Firefox 3: The OCSP server can use this Session ID to build a history of
torbutton/en/design/design.xml      1035) TLS sites someone visits, and also correlate their activity as users move from
torbutton/en/design/design.xml      1036) network to network (such as home to work to coffee shop, etc), inside and
torbutton/en/design/design.xml      1037) outside of Tor. To handle this and to help satisfy our <link

torbutton/en/design/design.xml      1038) linkend="state">State Separation Requirement</link>, we call the logout()
torbutton/en/design/design.xml      1039) function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
torbutton/en/design/design.xml      1040) to toggling

torbutton/en/design/design.xml      1041) <command>security.enable_ssl2</command>, which clears the SSL Session ID
torbutton/en/design/design.xml      1042) cache via the pref observer at <ulink

torbutton/en/design/design.xml      1043) url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.

torbutton/en/design/design.xml      1044)    </para>
torbutton/en/design/design.xml      1045)   </listitem>

torbutton/en/design/design.xml      1046)   <listitem><command>security.OCSP.enabled</command>
torbutton/en/design/design.xml      1047)    <para>
torbutton/en/design/design.xml      1048) Similarly, we toggle <command>security.OCSP.enabled</command>, which clears the OCSP certificate
torbutton/en/design/design.xml      1049) validation cache via the pref observer at <ulink
torbutton/en/design/design.xml      1050) url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
torbutton/en/design/design.xml      1051) In this way, exit nodes will not be able to fingerprint you
torbutton/en/design/design.xml      1052) based the fact that non-Tor OCSP lookups were obviously previously cached.
torbutton/en/design/design.xml      1053) To handle this and to help satisfy our <link
torbutton/en/design/design.xml      1054) linkend="state">State Separation Requirement</link>,
torbutton/en/design/design.xml      1055)    </para>
torbutton/en/design/design.xml      1056)   </listitem>
torbutton/en/design/design.xml      1057)   <listitem><command><ulink
torbutton/en/design/design.xml      1058) url="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</ulink></command>
torbutton/en/design/design.xml      1059)   <para>
torbutton/en/design/design.xml      1060) We permanently disable addon usage statistic reporting to the
torbutton/en/design/design.xml      1061) addons.mozilla.org statistics engine. These statistics send version
torbutton/en/design/design.xml      1062) information about Torbutton users via non-Tor, allowing their Tor use to be
torbutton/en/design/design.xml      1063) uncovered. Disabling this reporting helps Torbutton to satisfy its <link
torbutton/en/design/design.xml      1064) linkend="undiscoverability">Tor Undiscoverability</link> requirement.
torbutton/en/design/design.xml      1065) 
torbutton/en/design/design.xml      1066)   </para>
torbutton/en/design/design.xml      1067)   </listitem>

torbutton/en/design/design.xml      1068) 
torbutton/en/design/design.xml      1069)   <listitem><command><ulink url="http://www.mozilla.com/en-US/firefox/geolocation/">geo.enabled</ulink></command>
torbutton/en/design/design.xml      1070)    <para>
torbutton/en/design/design.xml      1071) 
torbutton/en/design/design.xml      1072) Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
torbutton/en/design/design.xml      1073) is enabled. This helps Torbutton maintain its
torbutton/en/design/design.xml      1074) <link linkend="location">Location Neutrality</link> requirement.
torbutton/en/design/design.xml      1075) While Firefox does prompt before divulging geolocational information,
torbutton/en/design/design.xml      1076) the assumption is that Tor users will never want to give their
torbutton/en/design/design.xml      1077) location away during Tor usage, and even allowing websites to prompt
torbutton/en/design/design.xml      1078) them to do so will only cause confusion and accidents to happen. Moreover,
torbutton/en/design/design.xml      1079) just because users may approve a site to know their location in non-Tor mode
torbutton/en/design/design.xml      1080) does not mean they want it divulged during Tor mode.
torbutton/en/design/design.xml      1081) 
torbutton/en/design/design.xml      1082)    </para>
torbutton/en/design/design.xml      1083)   </listitem>
torbutton/en/design/design.xml      1084) 
torbutton/en/design/design.xml      1085)   <listitem><command><ulink
torbutton/en/design/design.xml      1086) url="http://kb.mozillazine.org/Browser.zoom.siteSpecific">browser.zoom.siteSpecific</ulink></command>
torbutton/en/design/design.xml      1087)    <para>
torbutton/en/design/design.xml      1088) 
torbutton/en/design/design.xml      1089) Firefox actually remembers your zoom settings for certain sites. CSS
torbutton/en/design/design.xml      1090) and Javascript rule can use this to recognize previous visitors to a site.
torbutton/en/design/design.xml      1091) This helps Torbutton fulfill its <link linkend="state">State Separation</link>
torbutton/en/design/design.xml      1092) requirement.
torbutton/en/design/design.xml      1093) 
torbutton/en/design/design.xml      1094)    </para>
torbutton/en/design/design.xml      1095)   </listitem>
torbutton/en/design/design.xml      1096) 
torbutton/en/design/design.xml      1097)   <listitem><command><ulink
torbutton/en/design/design.xml      1098) url="https://developer.mozilla.org/en/controlling_dns_prefetching">network.dns.disablePrefetch</ulink></command>
torbutton/en/design/design.xml      1099)    <para>
torbutton/en/design/design.xml      1100) 
torbutton/en/design/design.xml      1101) Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
torbutton/en/design/design.xml      1102) links on a page to decrease page load latency. While Firefox does typically
torbutton/en/design/design.xml      1103) disable this behavior when proxies are enabled, we set this pref for added
torbutton/en/design/design.xml      1104) safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
torbutton/en/design/design.xml      1105) their links prefetched after a toggle to Non-Tor mode occurs,
torbutton/en/design/design.xml      1106) we also set the docShell attribute
torbutton/en/design/design.xml      1107) <ulink
torbutton/en/design/design.xml      1108) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell">
torbutton/en/design/design.xml      1109) allowDNSPrefetch</ulink> to false on Tor loaded tabs. This happens in the same
torbutton/en/design/design.xml      1110) positions in the code as those for disabling plugins via the allowPlugins
torbutton/en/design/design.xml      1111) docShell attribute. This helps Torbutton fulfill its <link
torbutton/en/design/design.xml      1112) linkend="isolation">Network Isolation</link> requirement.
torbutton/en/design/design.xml      1113) 
torbutton/en/design/design.xml      1114)    </para>
torbutton/en/design/design.xml      1115)   </listitem>
torbutton/en/design/design.xml      1116) 
torbutton/en/design/design.xml      1117)   <listitem><command><ulink
torbutton/en/design/design.xml      1118) url="http://kb.mozillazine.org/Browser.cache.offline.enable">browser.cache.offline.enable</ulink></command>
torbutton/en/design/design.xml      1119)    <para>
torbutton/en/design/design.xml      1120) 
torbutton/en/design/design.xml      1121) Firefox has the ability to store web applications in a special cache to allow
torbutton/en/design/design.xml      1122) them to continue to operate while the user is offline. Since this subsystem
torbutton/en/design/design.xml      1123) is actually different than the normal disk cache, it must be dealt with
torbutton/en/design/design.xml      1124) separately. Thus, Torbutton sets this preference to false whenever Tor is
torbutton/en/design/design.xml      1125) enabled. This helps Torbutton fulfill its <link linkend="disk">Disk
torbutton/en/design/design.xml      1126) Avoidance</link> and <link linkend="state">State Separation</link>
torbutton/en/design/design.xml      1127) requirements.
torbutton/en/design/design.xml      1128) 
torbutton/en/design/design.xml      1129)    </para>
torbutton/en/design/design.xml      1130)   </listitem>
torbutton/en/design/design.xml      1131) 
torbutton/en/design/design.xml      1132) <!-- FIXME: We should make it possible to search for ALL modified FF prefs -->
torbutton/en/design/design.xml      1133) 
torbutton/en/design/design.xml      1134) </orderedlist>
torbutton/en/design/design.xml      1135) </sect2>
torbutton/en/design/design.xml      1136) 
torbutton/en/design/design.xml      1137) </sect1>
torbutton/en/design/design.xml      1138) 
torbutton/en/design/design.xml      1139) <sect1>
torbutton/en/design/design.xml      1140)  <title>Description of Options</title>
torbutton/en/design/design.xml      1141) <para>This section provides a detailed description of Torbutton's options. Each
torbutton/en/design/design.xml      1142) option is presented as the string from the preferences window, a summary, the
torbutton/en/design/design.xml      1143) preferences it touches, and the effect this has on the components, chrome, and
torbutton/en/design/design.xml      1144) browser properties.</para>

torbutton/en/design/design.xml      1145) <!-- FIXME: figure out how to give subsections # ids or make this into a
torbutton/en/design/design.xml      1146) listitem -->

torbutton/en/design/design.xml      1147)  <sect2>

torbutton/en/design/design.xml      1148)   <title>Proxy Settings</title>
torbutton/en/design/design.xml      1149)  <sect3>

torbutton/en/design/design.xml      1150)   <title>Test Settings</title>
torbutton/en/design/design.xml      1151)   <para>
torbutton/en/design/design.xml      1152) This button under the Proxy Settings tab provides a way to verify that the 
torbutton/en/design/design.xml      1153) proxy settings are correct, and actually do route through the Tor network. It
torbutton/en/design/design.xml      1154) performs this check by issuing an <ulink
torbutton/en/design/design.xml      1155) url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
torbutton/en/design/design.xml      1156) for <ulink
torbutton/en/design/design.xml      1157) url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
torbutton/en/design/design.xml      1158) This is a special page that returns very simple, yet well-formed XHTML that
torbutton/en/design/design.xml      1159) Torbutton can easily inspect for a hidden link with an id of
torbutton/en/design/design.xml      1160) <command>TorCheckResult</command> and a target of <command>success</command>
torbutton/en/design/design.xml      1161) or <command>failure</command> to indicate if the
torbutton/en/design/design.xml      1162) user hit the page from a Tor IP, a non-Tor IP. This check is handled in
torbutton/en/design/design.xml      1163) <function>torbutton_test_settings()</function> in <ulink

torbutton/en/design/design.xml      1164) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>.

torbutton/en/design/design.xml      1165) Presenting the results to the user is handled by the <ulink

torbutton/en/design/design.xml      1166) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences

torbutton/en/design/design.xml      1167) window</ulink>
torbutton/en/design/design.xml      1168) callback <function>torbutton_prefs_test_settings()</function> in <ulink

torbutton/en/design/design.xml      1169) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">preferences.js</ulink>.  

torbutton/en/design/design.xml      1170) 
torbutton/en/design/design.xml      1171)   </para>

torbutton/en/design/design.xml      1172)  </sect3>

torbutton/en/design/design.xml      1173)  </sect2>

torbutton/en/design/design.xml      1174)  <sect2>
torbutton/en/design/design.xml      1175)   <title>Dynamic Content Settings</title>
torbutton/en/design/design.xml      1176)  <sect3 id="plugins">

torbutton/en/design/design.xml      1177)   <title>Disable plugins on Tor Usage (crucial)</title>
torbutton/en/design/design.xml      1178)  <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
torbutton/en/design/design.xml      1179) 
torbutton/en/design/design.xml      1180)  <para>Java and plugins <ulink
torbutton/en/design/design.xml      1181) url="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html">can query</ulink> the <ulink
torbutton/en/design/design.xml      1182) url="http://www.rgagnon.com/javadetails/java-0095.html">local IP
torbutton/en/design/design.xml      1183) address</ulink> and report it back to the
torbutton/en/design/design.xml      1184) remote site. They can also <ulink
torbutton/en/design/design.xml      1185) url="http://decloak.net">bypass proxy settings</ulink> and directly connect to a
torbutton/en/design/design.xml      1186) remote site without Tor. Every browser plugin we have tested with Firefox has
torbutton/en/design/design.xml      1187) some form of network capability, and every one ignores proxy settings or worse - only
torbutton/en/design/design.xml      1188) partially obeys them. This includes but is not limited to:
torbutton/en/design/design.xml      1189) QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
torbutton/en/design/design.xml      1190) Flash. 
torbutton/en/design/design.xml      1191) 
torbutton/en/design/design.xml      1192)  </para>
torbutton/en/design/design.xml      1193)  <para>
torbutton/en/design/design.xml      1194) Enabling this preference causes the above mentioned Torbutton chrome web progress
torbutton/en/design/design.xml      1195)  listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
torbutton/en/design/design.xml      1196)  plugins via the browser <ulink
torbutton/en/design/design.xml      1197)  url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink>
torbutton/en/design/design.xml      1198)  attribute <command>allowPlugins</command>. These flags are set every time a new window is
torbutton/en/design/design.xml      1199)  created (<function>torbutton_tag_new_browser()</function>), every time a web
torbutton/en/design/design.xml      1200) load
torbutton/en/design/design.xml      1201) event occurs
torbutton/en/design/design.xml      1202)  (<function>torbutton_update_tags()</function>), and every time the tor state is changed
torbutton/en/design/design.xml      1203)  (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
torbutton/en/design/design.xml      1204)  prevented from loading by the content policy in <ulink

torbutton/en/design/design.xml      1205) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is

torbutton/en/design/design.xml      1206)  enabled and this option is set.
torbutton/en/design/design.xml      1207)  </para>
torbutton/en/design/design.xml      1208) 
torbutton/en/design/design.xml      1209)  <para>All of this turns out to be insufficient if the user directly clicks
torbutton/en/design/design.xml      1210) on a plugin-handled mime-type. <ulink
torbutton/en/design/design.xml      1211) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">In this case</ulink>,
torbutton/en/design/design.xml      1212) the browser decides that maybe it should ignore all these other settings and
torbutton/en/design/design.xml      1213) load the plugin anyways, because maybe the user really did want to load it
torbutton/en/design/design.xml      1214) (never mind this same load-style could happen automatically  with meta-refresh
torbutton/en/design/design.xml      1215) or any number of other ways..). To handle these cases, Torbutton stores a list
torbutton/en/design/design.xml      1216) of plugin-handled mime-types, and sets the pref
torbutton/en/design/design.xml      1217) <command>plugin.disable_full_page_plugin_for_types</command> to this list.
torbutton/en/design/design.xml      1218) Additionally, (since nothing can be assumed when relying on Firefox
torbutton/en/design/design.xml      1219) preferences and internals) if it detects a load of one of them from the web
torbutton/en/design/design.xml      1220) progress listener, it cancels the request, tells the associated DOMWindow to
torbutton/en/design/design.xml      1221) stop loading, clears the document, AND throws an exception. Anything short of
torbutton/en/design/design.xml      1222) all this and the plugin managed to find some way to load.
torbutton/en/design/design.xml      1223)  </para>
torbutton/en/design/design.xml      1224) 
torbutton/en/design/design.xml      1225) <!--
torbutton/en/design/design.xml      1226) 
torbutton/en/design/design.xml      1227) FIXME: Hrmm, technically this behavior is not covered by this pref.
torbutton/en/design/design.xml      1228) 
torbutton/en/design/design.xml      1229)  <para>
torbutton/en/design/design.xml      1230) Furthermore, with version 3.0 and above, Firefox
torbutton/en/design/design.xml      1231) <ulink
torbutton/en/design/design.xml      1232) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">began ignoring</ulink>
torbutton/en/design/design.xml      1233) 
torbutton/en/design/design.xml      1234) <ulink
torbutton/en/design/design.xml      1235) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
torbutton/en/design/design.xml      1236) prefs, which caused us to have to <link linkend="appblocker">wrap the external
torbutton/en/design/design.xml      1237) app launcher components</link> to prevent external apps from being loaded to
torbutton/en/design/design.xml      1238) bypass proxy settings.
torbutton/en/design/design.xml      1239)  </para>
torbutton/en/design/design.xml      1240) -->
torbutton/en/design/design.xml      1241) 
torbutton/en/design/design.xml      1242)  <para>
torbutton/en/design/design.xml      1243)  All this could be avoided, of course, if Firefox would either <ulink
torbutton/en/design/design.xml      1244) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
torbutton/en/design/design.xml      1245)  allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
torbutton/en/design/design.xml      1246)  loads either <ulink
torbutton/en/design/design.xml      1247) url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
torbutton/en/design/design.xml      1248) url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
torbutton/en/design/design.xml      1249)  not very encouraging.
torbutton/en/design/design.xml      1250)  </para>
torbutton/en/design/design.xml      1251) 
torbutton/en/design/design.xml      1252) 
torbutton/en/design/design.xml      1253)  <para>
torbutton/en/design/design.xml      1254) 
torbutton/en/design/design.xml      1255) Since most plugins completely ignore browser proxy settings, the actions
torbutton/en/design/design.xml      1256) performed by this setting are crucial to satisfying the <link
torbutton/en/design/design.xml      1257) linkend="proxy">Proxy Obedience</link> requirement.
torbutton/en/design/design.xml      1258) 
torbutton/en/design/design.xml      1259)  </para>

torbutton/en/design/design.xml      1260) </sect3>
torbutton/en/design/design.xml      1261) <sect3>

torbutton/en/design/design.xml      1262)  <title>Isolate Dynamic Content to Tor State (crucial)</title>
torbutton/en/design/design.xml      1263) 
torbutton/en/design/design.xml      1264)  <para>Option: <command>extensions.torbutton.isolate_content</command></para>
torbutton/en/design/design.xml      1265) 
torbutton/en/design/design.xml      1266) <para>Enabling this preference is what enables the <ulink

torbutton/en/design/design.xml      1267) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy

torbutton/en/design/design.xml      1268) mentioned above, and causes it to block content load attempts in pages an
torbutton/en/design/design.xml      1269) opposite Tor state from the current state. Freshly loaded <ulink
torbutton/en/design/design.xml      1270) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
torbutton/en/design/design.xml      1271) tabs</ulink> are tagged
torbutton/en/design/design.xml      1272) with a <command>__tb_load_state</command> member in
torbutton/en/design/design.xml      1273) <function>torbutton_update_tags()</function> and this
torbutton/en/design/design.xml      1274) value is compared against the current tor state in the content policy.</para>
torbutton/en/design/design.xml      1275) 
torbutton/en/design/design.xml      1276) <para>It also kills all Javascript in each page loaded under that state by
torbutton/en/design/design.xml      1277) toggling the <command>allowJavascript</command> <ulink
torbutton/en/design/design.xml      1278) url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink> property, and issues a
torbutton/en/design/design.xml      1279) <ulink
torbutton/en/design/design.xml      1280) url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
torbutton/en/design/design.xml      1281) equivalent of hitting the STOP button).</para>
torbutton/en/design/design.xml      1282) 
torbutton/en/design/design.xml      1283) <para>
torbutton/en/design/design.xml      1284) 
torbutton/en/design/design.xml      1285) Unfortunately, <ulink
torbutton/en/design/design.xml      1286) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
torbutton/en/design/design.xml      1287) 409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
torbutton/en/design/design.xml      1288) all event handlers, and event handlers registered with <ulink
torbutton/en/design/design.xml      1289) url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
torbutton/en/design/design.xml      1290) are still able to execute. The <link linkend="contentpolicy">Torbutton Content
torbutton/en/design/design.xml      1291) Policy</link> should prevent such code from performing network activity within
torbutton/en/design/design.xml      1292) the current tab, but activity that happens via a popup window or via a
torbutton/en/design/design.xml      1293) Javascript redirect can still slip by. For this reason, Torbutton blocks
torbutton/en/design/design.xml      1294) popups by checking for a valid <ulink
torbutton/en/design/design.xml      1295) url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
torbutton/en/design/design.xml      1296) attribute in <function>torbutton_check_progress()</function>. If the window
torbutton/en/design/design.xml      1297) has an opener from a different Tor state, its load is blocked. The content
torbutton/en/design/design.xml      1298) policy also takes similar action to prevent Javascript redirects. This also
torbutton/en/design/design.xml      1299) has the side effect/feature of preventing the user from following any links
torbutton/en/design/design.xml      1300) from a page loaded in an opposite Tor state.
torbutton/en/design/design.xml      1301) 
torbutton/en/design/design.xml      1302) </para>
torbutton/en/design/design.xml      1303) 
torbutton/en/design/design.xml      1304) <para>
torbutton/en/design/design.xml      1305) This setting is responsible for satisfying the <link
torbutton/en/design/design.xml      1306) linkend="isolation">Network Isolation</link> requirement.
torbutton/en/design/design.xml      1307) </para>
torbutton/en/design/design.xml      1308) 

torbutton/en/design/design.xml      1309) </sect3>
torbutton/en/design/design.xml      1310) <sect3 id="jshooks">

torbutton/en/design/design.xml      1311) 
torbutton/en/design/design.xml      1312) <title>Hook Dangerous Javascript</title>
torbutton/en/design/design.xml      1313) 
torbutton/en/design/design.xml      1314)  <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
torbutton/en/design/design.xml      1315) 
torbutton/en/design/design.xml      1316) <para>This setting enables injection of the <ulink

torbutton/en/design/design.xml      1317) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js">Javascript

torbutton/en/design/design.xml      1318) hooking code</ulink>. This is done in the chrome in
torbutton/en/design/design.xml      1319) <function>torbutton_hookdoc()</function>, which is called ultimately by both the 
torbutton/en/design/design.xml      1320) <ulink
torbutton/en/design/design.xml      1321) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
torbutton/en/design/design.xml      1322) listener</ulink> <command>torbutton_weblistener</command> and the <link
torbutton/en/design/design.xml      1323) linkend="contentpolicy">content policy</link> (the latter being a hack to handle
torbutton/en/design/design.xml      1324) javascript: urls).
torbutton/en/design/design.xml      1325) 
torbutton/en/design/design.xml      1326) In the Firefox 2 days, this option did a lot more than
torbutton/en/design/design.xml      1327) it does now. It used to be responsible for timezone and improved useragent
torbutton/en/design/design.xml      1328) spoofing, and history object cloaking. However, now it only provides
torbutton/en/design/design.xml      1329) obfuscation of the <ulink
torbutton/en/design/design.xml      1330) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
torbutton/en/design/design.xml      1331) object to mask your browser and desktop resolution.
torbutton/en/design/design.xml      1332) The resolution hooks
torbutton/en/design/design.xml      1333) effectively make the Firefox browser window appear to websites as if the renderable area
torbutton/en/design/design.xml      1334) takes up the entire desktop, has no toolbar or other GUI element space, and
torbutton/en/design/design.xml      1335) the desktop itself has no toolbars.
torbutton/en/design/design.xml      1336) These hooks drastically reduce the amount of information available to do <link
torbutton/en/design/design.xml      1337) linkend="fingerprinting">anonymity set reduction attacks</link> and help to
torbutton/en/design/design.xml      1338) meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
torbutton/en/design/design.xml      1339) requirements. Unfortunately, Gregory Fleischer discovered it is still possible
torbutton/en/design/design.xml      1340) to retrieve the original screen values by using <ulink
torbutton/en/design/design.xml      1341) url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
torbutton/en/design/design.xml      1342) or <ulink
torbutton/en/design/design.xml      1343) url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.

torbutton/en/design/design.xml      1344) We are still looking for a workaround as of Torbutton 1.3.2.

torbutton/en/design/design.xml      1345) 
torbutton/en/design/design.xml      1346) <!-- FIXME: Don't forget to update this -->

torbutton/en/design/design.xml      1347) <!-- XXX: Date() issue now fixed by TZ variable! -->

torbutton/en/design/design.xml      1348) 
torbutton/en/design/design.xml      1349) </para>

torbutton/en/design/design.xml      1350) </sect3>
torbutton/en/design/design.xml      1351) <sect3>

torbutton/en/design/design.xml      1352) <title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
torbutton/en/design/design.xml      1353) 
torbutton/en/design/design.xml      1354)  <para>Option: <command>extensions.torbutton.resize_windows</command></para>
torbutton/en/design/design.xml      1355) 
torbutton/en/design/design.xml      1356) <para>
torbutton/en/design/design.xml      1357) 
torbutton/en/design/design.xml      1358) This option drastically cuts down on the number of distinct anonymity sets
torbutton/en/design/design.xml      1359) that divide the Tor web userbase. Without this setting, the dimensions for a
torbutton/en/design/design.xml      1360) typical browser window range from 600-1200 horizontal pixels and 400-1000
torbutton/en/design/design.xml      1361) vertical pixels, or about 600x600 = 360000 different sets. Resizing the
torbutton/en/design/design.xml      1362) browser window to multiples of 50 on each side reduces the number of sets by
torbutton/en/design/design.xml      1363) 50^2, bringing the total number of sets to 144. Of course, the distribution
torbutton/en/design/design.xml      1364) among these sets are not uniform, but scaling by 50 will improve the situation
torbutton/en/design/design.xml      1365) due to this non-uniformity for users in the less common resolutions.
torbutton/en/design/design.xml      1366) Obviously the ideal situation would be to lie entirely about the browser
torbutton/en/design/design.xml      1367) window size, but this will likely cause all sorts of rendering issues, and is
torbutton/en/design/design.xml      1368) also not implementable in a foolproof way from extension land.
torbutton/en/design/design.xml      1369) 
torbutton/en/design/design.xml      1370) </para>
torbutton/en/design/design.xml      1371) <para>
torbutton/en/design/design.xml      1372) 
torbutton/en/design/design.xml      1373) The implementation of this setting is spread across a couple of different
torbutton/en/design/design.xml      1374) locations in the Torbutton javascript <link linkend="browseroverlay">browser
torbutton/en/design/design.xml      1375) overlay</link>. Since resizing minimized windows causes them to be restored,
torbutton/en/design/design.xml      1376) and since maximized windows remember their previous size to the pixel, windows
torbutton/en/design/design.xml      1377) must be resized before every document load (at the time of browser tagging)
torbutton/en/design/design.xml      1378) via <function>torbutton_check_round()</function>, called by
torbutton/en/design/design.xml      1379) <function>torbutton_update_tags()</function>. To prevent drift, the extension
torbutton/en/design/design.xml      1380) tracks the original values of the windows and uses this to perform the
torbutton/en/design/design.xml      1381) rounding on document load. In addition, to prevent the user from resizing a
torbutton/en/design/design.xml      1382) window to a non-50px multiple, a resize listener
torbutton/en/design/design.xml      1383) (<function>torbutton_do_resize()</function>) is installed on every new browser
torbutton/en/design/design.xml      1384) window to record the new size and round it to a 50px multiple while Tor is
torbutton/en/design/design.xml      1385) enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
torbutton/en/design/design.xml      1386) are set. This ensures that there is no discrepancy between the 50 pixel cutoff
torbutton/en/design/design.xml      1387) and the actual renderable area of the browser (so that it is not possible to
torbutton/en/design/design.xml      1388) infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
torbutton/en/design/design.xml      1389) 
torbutton/en/design/design.xml      1390) </para>
torbutton/en/design/design.xml      1391) <para>
torbutton/en/design/design.xml      1392) This setting helps to meet the <link
torbutton/en/design/design.xml      1393) linkend="setpreservation">Anonymity Set Preservation</link> requirements.
torbutton/en/design/design.xml      1394) </para>

torbutton/en/design/design.xml      1395) </sect3>
torbutton/en/design/design.xml      1396) <sect3>
torbutton/en/design/design.xml      1397) 
torbutton/en/design/design.xml      1398) <title>Disable Search Suggestions during Tor (recommended)</title>
torbutton/en/design/design.xml      1399) 
torbutton/en/design/design.xml      1400)   <para>Option: <command>extensions.torbutton.no_search</command></para>
torbutton/en/design/design.xml      1401) 
torbutton/en/design/design.xml      1402) <para>
torbutton/en/design/design.xml      1403) This setting causes Torbutton to disable <ulink
torbutton/en/design/design.xml      1404) url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
torbutton/en/design/design.xml      1405) during Tor usage.
torbutton/en/design/design.xml      1406) This governs if you get Google search suggestions during Tor
torbutton/en/design/design.xml      1407) usage. Your Google cookie is transmitted with google search suggestions, hence
torbutton/en/design/design.xml      1408) this is recommended to be disabled.
torbutton/en/design/design.xml      1409) 
torbutton/en/design/design.xml      1410) </para>
torbutton/en/design/design.xml      1411) <para>
torbutton/en/design/design.xml      1412) While this setting doesn't satisfy any Torbutton requirements, the fact that
torbutton/en/design/design.xml      1413) cookies are transmitted for partially typed queries does not seem desirable
torbutton/en/design/design.xml      1414) for Tor usage.
torbutton/en/design/design.xml      1415) </para>
torbutton/en/design/design.xml      1416) </sect3>
torbutton/en/design/design.xml      1417) 
torbutton/en/design/design.xml      1418) 
torbutton/en/design/design.xml      1419) <sect3>

torbutton/en/design/design.xml      1420) <title>Disable Updates During Tor</title>
torbutton/en/design/design.xml      1421) 
torbutton/en/design/design.xml      1422)   <para>Option: <command>extensions.torbutton.no_updates</command></para>
torbutton/en/design/design.xml      1423) 
torbutton/en/design/design.xml      1424)   <para>This setting causes Torbutton to disable the four <ulink
torbutton/en/design/design.xml      1425) url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
torbutton/en/design/design.xml      1426) update settings</ulink> during Tor
torbutton/en/design/design.xml      1427)   usage: <command>extensions.update.enabled</command>,
torbutton/en/design/design.xml      1428) <command>app.update.enabled</command>,
torbutton/en/design/design.xml      1429)   <command>app.update.auto</command>, and
torbutton/en/design/design.xml      1430) <command>browser.search.update</command>.  These prevent the
torbutton/en/design/design.xml      1431)   browser from updating extensions, checking for Firefox upgrades, and
torbutton/en/design/design.xml      1432)   checking for search plugin updates while Tor is enabled.
torbutton/en/design/design.xml      1433)   </para>
torbutton/en/design/design.xml      1434) <para>
torbutton/en/design/design.xml      1435) This setting satisfies the <link
torbutton/en/design/design.xml      1436) linkend="updates">Update Safety</link> requirement.
torbutton/en/design/design.xml      1437) </para>

torbutton/en/design/design.xml      1438) </sect3>
torbutton/en/design/design.xml      1439) <sect3>

torbutton/en/design/design.xml      1440) <title>Redirect Torbutton Updates Via Tor (recommended)</title>
torbutton/en/design/design.xml      1441) 
torbutton/en/design/design.xml      1442)   <para>Option: <command>extensions.torbutton.update_torbutton_via_tor</command></para>
torbutton/en/design/design.xml      1443) 
torbutton/en/design/design.xml      1444)   <para>This setting causes Torbutton to install an
torbutton/en/design/design.xml      1445) 
torbutton/en/design/design.xml      1446) <ulink
torbutton/en/design/design.xml      1447) url="https://developer.mozilla.org/en/nsIProtocolProxyFilter">nsIProtocolProxyFilter</ulink>
torbutton/en/design/design.xml      1448) in order to redirect all version update checks and Torbutton update downloads
torbutton/en/design/design.xml      1449) via Tor, regardless of if Tor is enabled or not. This was done both to address
torbutton/en/design/design.xml      1450) concerns about data retention done by <ulink
torbutton/en/design/design.xml      1451) url="https://www.addons.mozilla.org">addons.mozilla.org</ulink>, as well as to
torbutton/en/design/design.xml      1452) help censored users meet the <link linkend="undiscoverability">Tor
torbutton/en/design/design.xml      1453) Undiscoverability</link> requirement.
torbutton/en/design/design.xml      1454) 
torbutton/en/design/design.xml      1455)   </para>

torbutton/en/design/design.xml      1456) </sect3>

torbutton/en/design/design.xml      1457) 

torbutton/en/design/design.xml      1458) <sect3>

torbutton/en/design/design.xml      1459) <title>Disable livemarks updates during Tor usage (recommended)</title>
torbutton/en/design/design.xml      1460)   <para>Option:
torbutton/en/design/design.xml      1461)    <simplelist>
torbutton/en/design/design.xml      1462)    <member><command>extensions.torbutton.disable_livemarks</command></member>
torbutton/en/design/design.xml      1463)    </simplelist>
torbutton/en/design/design.xml      1464)   </para>
torbutton/en/design/design.xml      1465) 
torbutton/en/design/design.xml      1466) <para>

torbutton/en/design/design.xml      1467) 

torbutton/en/design/design.xml      1468) This option causes Torbutton to prevent Firefox from loading <ulink
torbutton/en/design/design.xml      1469) url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
torbutton/en/design/design.xml      1470) Tor usage. Because people often have very personalized Livemarks (such as RSS
torbutton/en/design/design.xml      1471) feeds of Wikipedia articles they maintain, etc). This is accomplished both by
torbutton/en/design/design.xml      1472) <link linkend="livemarks">wrapping the livemark-service component</link> and
torbutton/en/design/design.xml      1473) by calling stopUpdateLivemarks() on the <ulink
torbutton/en/design/design.xml      1474) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">Livemark
torbutton/en/design/design.xml      1475) service</ulink> when Tor is enabled.
torbutton/en/design/design.xml      1476) 
torbutton/en/design/design.xml      1477) </para>
torbutton/en/design/design.xml      1478) 
torbutton/en/design/design.xml      1479) <para>
torbutton/en/design/design.xml      1480) This helps satisfy the <link linkend="isolation">Network
torbutton/en/design/design.xml      1481) Isolation</link> and <link linkend="setpreservation">Anonymity Set
torbutton/en/design/design.xml      1482) Preservation</link> requirements.
torbutton/en/design/design.xml      1483) </para>
torbutton/en/design/design.xml      1484) 

torbutton/en/design/design.xml      1485) </sect3>
torbutton/en/design/design.xml      1486) <sect3>

torbutton/en/design/design.xml      1487) <title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
torbutton/en/design/design.xml      1488)   <para>Options:
torbutton/en/design/design.xml      1489)    <simplelist>
torbutton/en/design/design.xml      1490)    <member><command>extensions.torbutton.block_tor_file_net</command></member>
torbutton/en/design/design.xml      1491)    <member><command>extensions.torbutton.block_nontor_file_net</command></member>
torbutton/en/design/design.xml      1492)    </simplelist>
torbutton/en/design/design.xml      1493)   </para>
torbutton/en/design/design.xml      1494) 
torbutton/en/design/design.xml      1495) <para>
torbutton/en/design/design.xml      1496) 
torbutton/en/design/design.xml      1497) These settings prevent file urls from performing network operations during the
torbutton/en/design/design.xml      1498) respective Tor states. Firefox 2's implementation of same origin policy allows
torbutton/en/design/design.xml      1499) file urls to read and <ulink
torbutton/en/design/design.xml      1500) url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
torbutton/en/design/design.xml      1501) arbitrary files from the local filesystem</ulink> to arbitrary websites. To
torbutton/en/design/design.xml      1502) make matters worse, the 'Content-Disposition' header can be injected
torbutton/en/design/design.xml      1503) arbitrarily by exit nodes to trick users into running arbitrary html files in
torbutton/en/design/design.xml      1504) the local context. These preferences cause the <link
torbutton/en/design/design.xml      1505) linkend="contentpolicy">content policy</link> to block access to any network
torbutton/en/design/design.xml      1506) resources from File urls during the appropriate Tor state.
torbutton/en/design/design.xml      1507) 
torbutton/en/design/design.xml      1508) </para>
torbutton/en/design/design.xml      1509) <para>
torbutton/en/design/design.xml      1510) 
torbutton/en/design/design.xml      1511) This preference helps to ensure Tor's <link linkend="isolation">Network
torbutton/en/design/design.xml      1512) Isolation</link> requirement, by preventing file urls from executing network
torbutton/en/design/design.xml      1513) operations in opposite Tor states. Also, allowing pages to submit arbitrary
torbutton/en/design/design.xml      1514) files to arbitrary sites just generally seems like a bad idea.
torbutton/en/design/design.xml      1515) 
torbutton/en/design/design.xml      1516) </para>

torbutton/en/design/design.xml      1517) </sect3>
torbutton/en/design/design.xml      1518) 
torbutton/en/design/design.xml      1519) <sect3>

torbutton/en/design/design.xml      1520) 
torbutton/en/design/design.xml      1521) <title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
torbutton/en/design/design.xml      1522) 
torbutton/en/design/design.xml      1523)   <para>Options:
torbutton/en/design/design.xml      1524)    <simplelist>
torbutton/en/design/design.xml      1525)    <member><command>extensions.torbutton.close_nontor</command></member>
torbutton/en/design/design.xml      1526)    <member><command>extensions.torbutton.close_tor</command></member>
torbutton/en/design/design.xml      1527)    </simplelist>
torbutton/en/design/design.xml      1528)   </para>
torbutton/en/design/design.xml      1529) 
torbutton/en/design/design.xml      1530) <para>
torbutton/en/design/design.xml      1531) 
torbutton/en/design/design.xml      1532) These settings cause Torbutton to enumerate through all windows and close all
torbutton/en/design/design.xml      1533) tabs in each window for the appropriate Tor state. This code can be found in
torbutton/en/design/design.xml      1534) <function>torbutton_update_status()</function>.  The main reason these settings
torbutton/en/design/design.xml      1535) exist is as a backup mechanism in the event of any Javascript or content policy
torbutton/en/design/design.xml      1536) leaks due to <ulink
torbutton/en/design/design.xml      1537) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
torbutton/en/design/design.xml      1538) 409737</ulink>.  Torbutton currently tries to block all Javascript network
torbutton/en/design/design.xml      1539) activity via the content policy, but until that bug is fixed, there is some
torbutton/en/design/design.xml      1540) risk that there are alternate ways to bypass the policy. This option is
torbutton/en/design/design.xml      1541) available as an extra assurance of <link linkend="isolation">Network
torbutton/en/design/design.xml      1542) Isolation</link> for those who would like to be sure that when Tor is toggled
torbutton/en/design/design.xml      1543) all page activity has ceased. It also serves as a potential future workaround
torbutton/en/design/design.xml      1544) in the event a content policy failure is discovered, and provides an additional
torbutton/en/design/design.xml      1545) level of protection for the <link linkend="disk">Disk Avoidance</link>
torbutton/en/design/design.xml      1546) protection so that browser state is not sitting around waiting to be swapped
torbutton/en/design/design.xml      1547) out longer than necessary.
torbutton/en/design/design.xml      1548) 
torbutton/en/design/design.xml      1549) </para>
torbutton/en/design/design.xml      1550) <para>
torbutton/en/design/design.xml      1551) While this setting doesn't satisfy any Torbutton requirements, the fact that
torbutton/en/design/design.xml      1552) cookies are transmitted for partially typed queries does not seem desirable
torbutton/en/design/design.xml      1553) for Tor usage.
torbutton/en/design/design.xml      1554) </para>

torbutton/en/design/design.xml      1555) </sect3>
torbutton/en/design/design.xml      1556)  </sect2>
torbutton/en/design/design.xml      1557)  <sect2>
torbutton/en/design/design.xml      1558)   <title>History and Forms Settings</title>
torbutton/en/design/design.xml      1559) <sect3>

torbutton/en/design/design.xml      1560) <title>Isolate Access to History navigation to Tor state (crucial)</title>
torbutton/en/design/design.xml      1561)   <para>Option: <command>extensions.torbutton.block_js_history</command></para>
torbutton/en/design/design.xml      1562)   <para>
torbutton/en/design/design.xml      1563) This setting determines if Torbutton installs an <ulink
torbutton/en/design/design.xml      1564) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener">nsISHistoryListener</ulink>
torbutton/en/design/design.xml      1565) attached to the <ulink
torbutton/en/design/design.xml      1566) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">sessionHistory</ulink> of 
torbutton/en/design/design.xml      1567) of each browser's <ulink
torbutton/en/design/design.xml      1568) url="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation">webNavigatator</ulink>.
torbutton/en/design/design.xml      1569) The nsIShistoryListener is instantiated with a reference to the containing
torbutton/en/design/design.xml      1570) browser window and blocks the back, forward, and reload buttons on the browser
torbutton/en/design/design.xml      1571) navigation bar when Tor is in an opposite state than the one to load the
torbutton/en/design/design.xml      1572) current tab. In addition, Tor clears the session history during a new document
torbutton/en/design/design.xml      1573) load if this setting is enabled. 
torbutton/en/design/design.xml      1574) 
torbutton/en/design/design.xml      1575)   </para>
torbutton/en/design/design.xml      1576)   <para>
torbutton/en/design/design.xml      1577) 
torbutton/en/design/design.xml      1578) This is marked as a crucial setting in part
torbutton/en/design/design.xml      1579) because Javascript access to the history object is indistinguishable from 
torbutton/en/design/design.xml      1580) user clicks, and because
torbutton/en/design/design.xml      1581) <ulink
torbutton/en/design/design.xml      1582) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
torbutton/en/design/design.xml      1583) 409737</ulink> allows javascript to execute in opposite Tor states, javascript
torbutton/en/design/design.xml      1584) can issue reloads after Tor toggle to reveal your original IP. Even without
torbutton/en/design/design.xml      1585) this bug, however, Javascript is still able to access previous pages in your
torbutton/en/design/design.xml      1586) session history that may have been loaded under a different Tor state, to
torbutton/en/design/design.xml      1587) attempt to correlate your activity.
torbutton/en/design/design.xml      1588) 
torbutton/en/design/design.xml      1589)    </para>
torbutton/en/design/design.xml      1590)    <para>
torbutton/en/design/design.xml      1591) 
torbutton/en/design/design.xml      1592) This setting helps to fulfill Torbutton's <link linkend="state">State
torbutton/en/design/design.xml      1593) Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
torbutton/en/design/design.xml      1594) requirements.
torbutton/en/design/design.xml      1595) 
torbutton/en/design/design.xml      1596)    </para>

torbutton/en/design/design.xml      1597) </sect3>

torbutton/en/design/design.xml      1598) 
torbutton/en/design/design.xml      1599) 

torbutton/en/design/design.xml      1600) <sect3>

torbutton/en/design/design.xml      1601) <title>History Access Settings</title>
torbutton/en/design/design.xml      1602) 
torbutton/en/design/design.xml      1603)   <para>Options:
torbutton/en/design/design.xml      1604)   <simplelist>
torbutton/en/design/design.xml      1605)    <member><command>extensions.torbutton.block_thread</command></member>
torbutton/en/design/design.xml      1606)    <member><command>extensions.torbutton.block_nthread</command></member>
torbutton/en/design/design.xml      1607)    <member><command>extensions.torbutton.block_thwrite</command></member>
torbutton/en/design/design.xml      1608)    <member><command>extensions.torbutton.block_nthwrite</command></member>
torbutton/en/design/design.xml      1609)   </simplelist>
torbutton/en/design/design.xml      1610)   </para>
torbutton/en/design/design.xml      1611) 

torbutton/en/design/design.xml      1612) <para>On Firefox 3.x, these four settings govern the behavior of the <ulink
torbutton/en/design/design.xml      1613) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink>

torbutton/en/design/design.xml      1614) history blocker component mentioned above. By hooking the browser's view of
torbutton/en/design/design.xml      1615) the history itself via the <ulink
torbutton/en/design/design.xml      1616) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
torbutton/en/design/design.xml      1617) and <ulink
torbutton/en/design/design.xml      1618) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1">@mozilla.org/browser/nav-history-service;1</ulink>
torbutton/en/design/design.xml      1619) components, this mechanism defeats all document-based <ulink
torbutton/en/design/design.xml      1620) url="http://whattheinternetknowsaboutyou.com/">history disclosure
torbutton/en/design/design.xml      1621) attacks</ulink>, including <ulink
torbutton/en/design/design.xml      1622) url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
torbutton/en/design/design.xml      1623) 
torbutton/en/design/design.xml      1624) The component also hooks functions involved in writing history to disk via
torbutton/en/design/design.xml      1625) both the <ulink
torbutton/en/design/design.xml      1626) url="http://developer.mozilla.org/en/docs/Places_migration_guide#History">Places
torbutton/en/design/design.xml      1627) Database</ulink> and the older Firefox 2 mechanisms.
torbutton/en/design/design.xml      1628) 
torbutton/en/design/design.xml      1629) </para>
torbutton/en/design/design.xml      1630) 

torbutton/en/design/design.xml      1631) <para>
torbutton/en/design/design.xml      1632) On Firefox 4, Mozilla finally <ulink
torbutton/en/design/design.xml      1633) url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">addressed
torbutton/en/design/design.xml      1634) these issues</ulink>, so we can effectively ignore the "read" pair of the
torbutton/en/design/design.xml      1635) above prefs. We then only need to link the write prefs to
torbutton/en/design/design.xml      1636) <command>places.history.enabled</command>, which disabled writing to the
torbutton/en/design/design.xml      1637) history store while set.
torbutton/en/design/design.xml      1638) </para>
torbutton/en/design/design.xml      1639) 

torbutton/en/design/design.xml      1640) <para>
torbutton/en/design/design.xml      1641) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1642) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1643) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1644) </para>
torbutton/en/design/design.xml      1645) 

torbutton/en/design/design.xml      1646) </sect3>
torbutton/en/design/design.xml      1647) <sect3>

torbutton/en/design/design.xml      1648) 
torbutton/en/design/design.xml      1649) <title>Clear History During Tor Toggle (optional)</title>
torbutton/en/design/design.xml      1650) 
torbutton/en/design/design.xml      1651) <para>Option: <command>extensions.torbutton.clear_history</command></para>
torbutton/en/design/design.xml      1652) 
torbutton/en/design/design.xml      1653) <para>This setting governs if Torbutton calls
torbutton/en/design/design.xml      1654) <ulink
torbutton/en/design/design.xml      1655) url="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29">nsIBrowserHistory.removeAllPages</ulink>
torbutton/en/design/design.xml      1656) and <ulink
torbutton/en/design/design.xml      1657) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">nsISHistory.PurgeHistory</ulink>
torbutton/en/design/design.xml      1658) for each tab on Tor toggle.</para>
torbutton/en/design/design.xml      1659) <para>
torbutton/en/design/design.xml      1660) This setting is an optional way to help satisfy the <link
torbutton/en/design/design.xml      1661) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml      1662) </para>
torbutton/en/design/design.xml      1663) 

torbutton/en/design/design.xml      1664) </sect3>
torbutton/en/design/design.xml      1665) <sect3>

torbutton/en/design/design.xml      1666) <title>Block Password+Form saving during Tor/Non-Tor</title>
torbutton/en/design/design.xml      1667) 
torbutton/en/design/design.xml      1668) <para>Options:
torbutton/en/design/design.xml      1669)   <simplelist>
torbutton/en/design/design.xml      1670)   <member><command>extensions.torbutton.block_tforms</command></member>
torbutton/en/design/design.xml      1671)   <member><command>extensions.torbutton.block_ntforms</command></member>
torbutton/en/design/design.xml      1672)   </simplelist>
torbutton/en/design/design.xml      1673)   </para>
torbutton/en/design/design.xml      1674) 
torbutton/en/design/design.xml      1675) <para>These settings govern if Torbutton disables
torbutton/en/design/design.xml      1676) <command>browser.formfill.enable</command>
torbutton/en/design/design.xml      1677) and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
torbutton/en/design/design.xml      1678) Since form fields can be read at any time by Javascript, this setting is a lot
torbutton/en/design/design.xml      1679) more important than it seems.
torbutton/en/design/design.xml      1680) </para>
torbutton/en/design/design.xml      1681) 
torbutton/en/design/design.xml      1682) <para>
torbutton/en/design/design.xml      1683) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1684) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1685) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1686) </para>
torbutton/en/design/design.xml      1687) 

torbutton/en/design/design.xml      1688) </sect3>
torbutton/en/design/design.xml      1689)  </sect2>
torbutton/en/design/design.xml      1690)  <sect2>
torbutton/en/design/design.xml      1691)   <title>Cache Settings</title>
torbutton/en/design/design.xml      1692) <sect3>

torbutton/en/design/design.xml      1693)   <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
torbutton/en/design/design.xml      1694) 
torbutton/en/design/design.xml      1695)   <para>Option: <command>extensions.torbutton.clear_cache</command>
torbutton/en/design/design.xml      1696)   </para>
torbutton/en/design/design.xml      1697) 
torbutton/en/design/design.xml      1698) <para>This option causes Torbutton to call <ulink
torbutton/en/design/design.xml      1699) url="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29">nsICacheService.evictEntries(0)</ulink>
torbutton/en/design/design.xml      1700) on Tor toggle to remove all entries from the cache. In addition, this setting
torbutton/en/design/design.xml      1701) causes Torbutton to set <ulink
torbutton/en/design/design.xml      1702) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
torbutton/en/design/design.xml      1703) </para>
torbutton/en/design/design.xml      1704) <para>
torbutton/en/design/design.xml      1705) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1706) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1707) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1708) </para>
torbutton/en/design/design.xml      1709) 

torbutton/en/design/design.xml      1710) </sect3>
torbutton/en/design/design.xml      1711) <sect3>

torbutton/en/design/design.xml      1712)   <title>Block disk and memory cache during Tor</title>
torbutton/en/design/design.xml      1713) 
torbutton/en/design/design.xml      1714) <para>Option: <command>extensions.torbutton.block_cache</command></para>
torbutton/en/design/design.xml      1715) 
torbutton/en/design/design.xml      1716) <para>This setting
torbutton/en/design/design.xml      1717) causes Torbutton to set <ulink
torbutton/en/design/design.xml      1718) url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
torbutton/en/design/design.xml      1719) <ulink
torbutton/en/design/design.xml      1720) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
torbutton/en/design/design.xml      1721) <ulink
torbutton/en/design/design.xml      1722) url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
torbutton/en/design/design.xml      1723) </para>
torbutton/en/design/design.xml      1724) <para>
torbutton/en/design/design.xml      1725) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1726) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1727) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1728) </para>
torbutton/en/design/design.xml      1729) 

torbutton/en/design/design.xml      1730) </sect3>
torbutton/en/design/design.xml      1731)  </sect2>
torbutton/en/design/design.xml      1732)  <sect2>
torbutton/en/design/design.xml      1733)   <title>Cookie and Auth Settings</title>
torbutton/en/design/design.xml      1734) <sect3>

torbutton/en/design/design.xml      1735)   <title>Clear Cookies on Tor Toggle</title>
torbutton/en/design/design.xml      1736) 
torbutton/en/design/design.xml      1737) <para>Option: <command>extensions.torbutton.clear_cookies</command>
torbutton/en/design/design.xml      1738)   </para>
torbutton/en/design/design.xml      1739) 
torbutton/en/design/design.xml      1740) <para>
torbutton/en/design/design.xml      1741) 
torbutton/en/design/design.xml      1742) This setting causes Torbutton to call <ulink
torbutton/en/design/design.xml      1743) url="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29">nsICookieManager.removeAll()</ulink> on
torbutton/en/design/design.xml      1744) every Tor toggle. In addition, this sets <ulink
torbutton/en/design/design.xml      1745) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
torbutton/en/design/design.xml      1746) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
torbutton/en/design/design.xml      1747) which prevents them from being written to disk. 
torbutton/en/design/design.xml      1748) 
torbutton/en/design/design.xml      1749) </para>
torbutton/en/design/design.xml      1750) <para>
torbutton/en/design/design.xml      1751) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1752) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1753) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1754) </para>
torbutton/en/design/design.xml      1755) 

torbutton/en/design/design.xml      1756) </sect3>
torbutton/en/design/design.xml      1757) <sect3>

torbutton/en/design/design.xml      1758)   
torbutton/en/design/design.xml      1759)   <title>Store Non-Tor cookies in a protected jar</title>
torbutton/en/design/design.xml      1760) 
torbutton/en/design/design.xml      1761) <para>Option: <command>extensions.torbutton.cookie_jars</command>
torbutton/en/design/design.xml      1762)   </para>
torbutton/en/design/design.xml      1763) 
torbutton/en/design/design.xml      1764) <para>
torbutton/en/design/design.xml      1765) 
torbutton/en/design/design.xml      1766) This setting causes Torbutton to use <ulink

torbutton/en/design/design.xml      1767) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store

torbutton/en/design/design.xml      1768) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
torbutton/en/design/design.xml      1769) before restoring the jar.
torbutton/en/design/design.xml      1770) </para>
torbutton/en/design/design.xml      1771) <para>
torbutton/en/design/design.xml      1772) This setting also sets <ulink
torbutton/en/design/design.xml      1773) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
torbutton/en/design/design.xml      1774) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
torbutton/en/design/design.xml      1775) which prevents them from being written to disk. 
torbutton/en/design/design.xml      1776) 
torbutton/en/design/design.xml      1777) </para>
torbutton/en/design/design.xml      1778) 
torbutton/en/design/design.xml      1779) <para>
torbutton/en/design/design.xml      1780) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1781) linkend="state">State Separation</link> and <link
torbutton/en/design/design.xml      1782) linkend="disk">Disk Avoidance</link> requirements.
torbutton/en/design/design.xml      1783) </para>
torbutton/en/design/design.xml      1784) 
torbutton/en/design/design.xml      1785) 

torbutton/en/design/design.xml      1786) </sect3>
torbutton/en/design/design.xml      1787) <sect3>

torbutton/en/design/design.xml      1788) 
torbutton/en/design/design.xml      1789)   <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
torbutton/en/design/design.xml      1790) 
torbutton/en/design/design.xml      1791) <para>Option: <command>extensions.torbutton.dual_cookie_jars</command>
torbutton/en/design/design.xml      1792)   </para>
torbutton/en/design/design.xml      1793) 
torbutton/en/design/design.xml      1794) <para>
torbutton/en/design/design.xml      1795) 
torbutton/en/design/design.xml      1796) This setting causes Torbutton to use <ulink

torbutton/en/design/design.xml      1797) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store

torbutton/en/design/design.xml      1798) both Tor and Non-Tor cookies into protected jars.
torbutton/en/design/design.xml      1799) </para>
torbutton/en/design/design.xml      1800) 
torbutton/en/design/design.xml      1801) <para>
torbutton/en/design/design.xml      1802) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1803) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml      1804) </para>
torbutton/en/design/design.xml      1805) 
torbutton/en/design/design.xml      1806) 

torbutton/en/design/design.xml      1807) </sect3>

torbutton/en/design/design.xml      1808) 

torbutton/en/design/design.xml      1809) <!-- FIXME: If we decide to keep it, document the cookie protections dialog
torbutton/en/design/design.xml      1810) -->

torbutton/en/design/design.xml      1811) 

torbutton/en/design/design.xml      1812) <sect3>

torbutton/en/design/design.xml      1813) 
torbutton/en/design/design.xml      1814)   <title>Manage My Own Cookies (dangerous)</title>
torbutton/en/design/design.xml      1815) 
torbutton/en/design/design.xml      1816) <para>Options: None</para>
torbutton/en/design/design.xml      1817) <para>This setting disables all Torbutton cookie handling by setting the above
torbutton/en/design/design.xml      1818) cookie prefs all to false.</para>

torbutton/en/design/design.xml      1819) </sect3>
torbutton/en/design/design.xml      1820) <sect3>

torbutton/en/design/design.xml      1821) 

torbutton/en/design/design.xml      1822) <sect3>

torbutton/en/design/design.xml      1823)   <title>Do not write Tor/Non-Tor cookies to disk</title>
torbutton/en/design/design.xml      1824)   <para>Options:
torbutton/en/design/design.xml      1825)   <simplelist>
torbutton/en/design/design.xml      1826)   <member><command>extensions.torbutton.tor_memory_jar</command></member>
torbutton/en/design/design.xml      1827)   <member><command>extensions.torbutton.nontor_memory_jar</command></member>
torbutton/en/design/design.xml      1828)   </simplelist>
torbutton/en/design/design.xml      1829)   </para>
torbutton/en/design/design.xml      1830) 
torbutton/en/design/design.xml      1831) <para>
torbutton/en/design/design.xml      1832) These settings (contributed by arno) cause Torbutton to set <ulink
torbutton/en/design/design.xml      1833) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
torbutton/en/design/design.xml      1834) to 2 during the appropriate Tor state, and to store cookies acquired in that
torbutton/en/design/design.xml      1835) state into a Javascript
torbutton/en/design/design.xml      1836) <ulink
torbutton/en/design/design.xml      1837) url="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X">E4X</ulink>
torbutton/en/design/design.xml      1838) object as opposed to writing them to disk.
torbutton/en/design/design.xml      1839) </para>
torbutton/en/design/design.xml      1840) 
torbutton/en/design/design.xml      1841) <para>
torbutton/en/design/design.xml      1842) This allows Torbutton to provide an option to preserve a user's 
torbutton/en/design/design.xml      1843) cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
torbutton/en/design/design.xml      1844) requirement.
torbutton/en/design/design.xml      1845) </para>

torbutton/en/design/design.xml      1846) </sect3>

torbutton/en/design/design.xml      1847) 
torbutton/en/design/design.xml      1848) 
torbutton/en/design/design.xml      1849)   <title>Disable DOM Storage during Tor usage (crucial)</title>
torbutton/en/design/design.xml      1850) 
torbutton/en/design/design.xml      1851) <para>Option: <command>extensions.torbutton.disable_domstorage</command>
torbutton/en/design/design.xml      1852)   </para>
torbutton/en/design/design.xml      1853) 
torbutton/en/design/design.xml      1854) <para>
torbutton/en/design/design.xml      1855) 
torbutton/en/design/design.xml      1856) This setting causes Torbutton to toggle <command>dom.storage.enabled</command> during Tor
torbutton/en/design/design.xml      1857) usage to prevent 
torbutton/en/design/design.xml      1858) <ulink
torbutton/en/design/design.xml      1859)   url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink> from
torbutton/en/design/design.xml      1860)   being used to store persistent information across Tor states.</para>
torbutton/en/design/design.xml      1861) <para>
torbutton/en/design/design.xml      1862) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1863) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml      1864) </para>
torbutton/en/design/design.xml      1865) 

torbutton/en/design/design.xml      1866) </sect3>

torbutton/en/design/design.xml      1867) 

torbutton/en/design/design.xml      1868) <sect3>

torbutton/en/design/design.xml      1869)   <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
torbutton/en/design/design.xml      1870) <para>Option: <command>extensions.torbutton.clear_http_auth</command>
torbutton/en/design/design.xml      1871)   </para>
torbutton/en/design/design.xml      1872) 
torbutton/en/design/design.xml      1873) <para>
torbutton/en/design/design.xml      1874) This setting causes Torbutton to call <ulink
torbutton/en/design/design.xml      1875) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager">nsIHttpAuthManager.clearAll()</ulink>
torbutton/en/design/design.xml      1876) every time Tor is toggled.
torbutton/en/design/design.xml      1877) </para>
torbutton/en/design/design.xml      1878) 
torbutton/en/design/design.xml      1879) <para>
torbutton/en/design/design.xml      1880) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1881) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml      1882) </para>

torbutton/en/design/design.xml      1883) </sect3>
torbutton/en/design/design.xml      1884)  </sect2>
torbutton/en/design/design.xml      1885)  <sect2>
torbutton/en/design/design.xml      1886)   <title>Startup Settings</title>
torbutton/en/design/design.xml      1887) <sect3>
torbutton/en/design/design.xml      1888)   <title>On Browser Startup, set Tor state to: Tor, Non-Tor</title>

torbutton/en/design/design.xml      1889)   <para>Options:

torbutton/en/design/design.xml      1890)    <command>extensions.torbutton.restore_tor</command>

torbutton/en/design/design.xml      1891)   </para>
torbutton/en/design/design.xml      1892) 

torbutton/en/design/design.xml      1893)   <para>This option governs what Tor state tor is loaded in to.
torbutton/en/design/design.xml      1894) <function>torbutton_set_initial_state()</function> covers the case where the
torbutton/en/design/design.xml      1895) browser did not crash, and <function>torbutton_crash_recover()</function>
torbutton/en/design/design.xml      1896) covers the case where the <link linkend="crashobserver">crash observer</link>
torbutton/en/design/design.xml      1897) detected a crash.

torbutton/en/design/design.xml      1898) </para>
torbutton/en/design/design.xml      1899) <para>
torbutton/en/design/design.xml      1900) 
torbutton/en/design/design.xml      1901) Since the Tor state after a Firefox crash is unknown/indeterminate, this
torbutton/en/design/design.xml      1902) setting helps to satisfy the <link linkend="state">State Separation</link>
torbutton/en/design/design.xml      1903) requirement in the event of Firefox crashes by ensuring all cookies,
torbutton/en/design/design.xml      1904) settings and saved sessions are reloaded from a fixed Tor state.
torbutton/en/design/design.xml      1905)  
torbutton/en/design/design.xml      1906) </para>

torbutton/en/design/design.xml      1907) </sect3>

torbutton/en/design/design.xml      1908) 
torbutton/en/design/design.xml      1909) 

torbutton/en/design/design.xml      1910) <sect3>

torbutton/en/design/design.xml      1911)   <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
torbutton/en/design/design.xml      1912) 
torbutton/en/design/design.xml      1913)   <para>Options: 
torbutton/en/design/design.xml      1914)   <simplelist>
torbutton/en/design/design.xml      1915)     <member><command>extensions.torbutton.nonontor_sessionstore</command></member>
torbutton/en/design/design.xml      1916)     <member><command>extensions.torbutton.notor_sessionstore</command></member>
torbutton/en/design/design.xml      1917)   </simplelist>
torbutton/en/design/design.xml      1918)   </para>
torbutton/en/design/design.xml      1919) 

torbutton/en/design/design.xml      1920)   <para>If these options are enabled, the <link
torbutton/en/design/design.xml      1921) linkend="tbsessionstore">tbSessionStore.js</link> component uses the session
torbutton/en/design/design.xml      1922) store listeners to filter out the appropriate tabs before writing the session
torbutton/en/design/design.xml      1923) store data to disk.
torbutton/en/design/design.xml      1924) </para>

torbutton/en/design/design.xml      1925) <para>
torbutton/en/design/design.xml      1926) This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
torbutton/en/design/design.xml      1927) requirement, and also helps to satisfy the <link
torbutton/en/design/design.xml      1928) linkend="state">State Separation</link> requirement in the event of Firefox
torbutton/en/design/design.xml      1929) crashes.
torbutton/en/design/design.xml      1930) 
torbutton/en/design/design.xml      1931) </para>
torbutton/en/design/design.xml      1932) 

torbutton/en/design/design.xml      1933) </sect3>
torbutton/en/design/design.xml      1934)  </sect2>
torbutton/en/design/design.xml      1935)  <sect2>
torbutton/en/design/design.xml      1936)   <title>Shutdown Settings</title>
torbutton/en/design/design.xml      1937) <sect3>
torbutton/en/design/design.xml      1938) 
torbutton/en/design/design.xml      1939)   <title>Clear cookies on Tor/Non-Tor shutdown</title>
torbutton/en/design/design.xml      1940) 
torbutton/en/design/design.xml      1941) <para>Option: <command>extensions.torbutton.shutdown_method</command>
torbutton/en/design/design.xml      1942)   </para>
torbutton/en/design/design.xml      1943) 
torbutton/en/design/design.xml      1944) <para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
torbutton/en/design/design.xml      1945) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
torbutton/en/design/design.xml      1946) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
torbutton/en/design/design.xml      1947) for the <ulink
torbutton/en/design/design.xml      1948) url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
torbutton/en/design/design.xml      1949) <link linkend="crashobserver">crash-observer.js</link> and use <ulink
torbutton/en/design/design.xml      1950) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
torbutton/en/design/design.xml      1951) to clear out all cookies and all cookie jars upon shutdown.
torbutton/en/design/design.xml      1952) </para>
torbutton/en/design/design.xml      1953) <para>
torbutton/en/design/design.xml      1954) This setting helps to satisfy the <link
torbutton/en/design/design.xml      1955) linkend="state">State Separation</link> requirement.
torbutton/en/design/design.xml      1956) </para>

torbutton/en/design/design.xml      1957) 

torbutton/en/design/design.xml      1958) 
torbutton/en/design/design.xml      1959) </sect3>
torbutton/en/design/design.xml      1960)  </sect2>
torbutton/en/design/design.xml      1961)  <sect2>
torbutton/en/design/design.xml      1962)   <title>Header Settings</title>
torbutton/en/design/design.xml      1963) <sect3>

torbutton/en/design/design.xml      1964) 
torbutton/en/design/design.xml      1965)   <title>Set user agent during Tor usage (crucial)</title>
torbutton/en/design/design.xml      1966)   <para>Options:
torbutton/en/design/design.xml      1967)    <simplelist>
torbutton/en/design/design.xml      1968)     <member><command>extensions.torbutton.set_uagent</command></member>
torbutton/en/design/design.xml      1969)     <member><command>extensions.torbutton.platform_override</command></member>
torbutton/en/design/design.xml      1970)     <member><command>extensions.torbutton.oscpu_override</command></member>
torbutton/en/design/design.xml      1971)     <member><command>extensions.torbutton.buildID_override</command></member>
torbutton/en/design/design.xml      1972)     <member><command>extensions.torbutton.productsub_override</command></member>
torbutton/en/design/design.xml      1973)     <member><command>extensions.torbutton.appname_override</command></member>
torbutton/en/design/design.xml      1974)     <member><command>extensions.torbutton.appversion_override</command></member>
torbutton/en/design/design.xml      1975)     <member><command>extensions.torbutton.useragent_override</command></member>
torbutton/en/design/design.xml      1976)     <member><command>extensions.torbutton.useragent_vendor</command></member>
torbutton/en/design/design.xml      1977)     <member><command>extensions.torbutton.useragent_vendorSub</command></member>
torbutton/en/design/design.xml      1978)   </simplelist>
torbutton/en/design/design.xml      1979)    </para>
torbutton/en/design/design.xml      1980) 
torbutton/en/design/design.xml      1981) <para>On face, user agent switching appears to be straight-forward in Firefox.
torbutton/en/design/design.xml      1982) It provides several options for controlling the browser user agent string:
torbutton/en/design/design.xml      1983) <command>general.appname.override</command>,
torbutton/en/design/design.xml      1984) <command>general.appversion.override</command>,
torbutton/en/design/design.xml      1985) <command>general.platform.override</command>,
torbutton/en/design/design.xml      1986) <command>general.oscpu.override</command>,
torbutton/en/design/design.xml      1987) <command>general.productSub.override</command>,
torbutton/en/design/design.xml      1988) <command>general.buildID.override</command>,
torbutton/en/design/design.xml      1989) <command>general.useragent.override</command>,
torbutton/en/design/design.xml      1990) <command>general.useragent.vendor</command>, and
torbutton/en/design/design.xml      1991) <command>general.useragent.vendorSub</command>. If
torbutton/en/design/design.xml      1992) the Torbutton preference <command>extensions.torbutton.set_uagent</command> is
torbutton/en/design/design.xml      1993) true, Torbutton copies all of the other above prefs into their corresponding
torbutton/en/design/design.xml      1994) browser preferences during Tor usage.</para>
torbutton/en/design/design.xml      1995) 
torbutton/en/design/design.xml      1996) 
torbutton/en/design/design.xml      1997) <para>
torbutton/en/design/design.xml      1998) 
torbutton/en/design/design.xml      1999) It also turns out that it is possible to detect the original Firefox version
torbutton/en/design/design.xml      2000) by <ulink url="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/">inspecting
torbutton/en/design/design.xml      2001) certain resource:// files</ulink>. These cases are handled by Torbutton's
torbutton/en/design/design.xml      2002) <link linkend="contentpolicy">content policy</link>.
torbutton/en/design/design.xml      2003) 
torbutton/en/design/design.xml      2004) </para>
torbutton/en/design/design.xml      2005) 
torbutton/en/design/design.xml      2006) <para>
torbutton/en/design/design.xml      2007) This setting helps to satisfy the <link
torbutton/en/design/design.xml      2008) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
torbutton/en/design/design.xml      2009) </para>
torbutton/en/design/design.xml      2010) 
torbutton/en/design/design.xml      2011) 

torbutton/en/design/design.xml      2012) </sect3>
torbutton/en/design/design.xml      2013) <sect3>

torbutton/en/design/design.xml      2014) 
torbutton/en/design/design.xml      2015)   <title>Spoof US English Browser</title>
torbutton/en/design/design.xml      2016) <para>Options:
torbutton/en/design/design.xml      2017) <simplelist>
torbutton/en/design/design.xml      2018)  <member><command>extensions.torbutton.spoof_english</command></member>
torbutton/en/design/design.xml      2019)  <member><command>extensions.torbutton.spoof_charset</command></member>
torbutton/en/design/design.xml      2020)  <member><command>extensions.torbutton.spoof_language</command></member>
torbutton/en/design/design.xml      2021) </simplelist>
torbutton/en/design/design.xml      2022) </para>
torbutton/en/design/design.xml      2023) 
torbutton/en/design/design.xml      2024) <para> This option causes Torbutton to set
torbutton/en/design/design.xml      2025) <command>general.useragent.locale</command>
torbutton/en/design/design.xml      2026) <command>intl.accept_languages</command> to the value specified in
torbutton/en/design/design.xml      2027) <command>extensions.torbutton.spoof_locale</command>,
torbutton/en/design/design.xml      2028) <command>extensions.torbutton.spoof_charset</command> and
torbutton/en/design/design.xml      2029) <command>extensions.torbutton.spoof_language</command> during Tor usage, as
torbutton/en/design/design.xml      2030) well as hooking <command>navigator.language</command> via its <link
torbutton/en/design/design.xml      2031) linkend="jshooks">javascript hooks</link>.
torbutton/en/design/design.xml      2032)  </para>
torbutton/en/design/design.xml      2033) <para>
torbutton/en/design/design.xml      2034) This setting helps to satisfy the <link
torbutton/en/design/design.xml      2035) linkend="setpreservation">Anonymity Set Preservation</link> and <link
torbutton/en/design/design.xml      2036) linkend="location">Location Neutrality</link> requirements.
torbutton/en/design/design.xml      2037) </para>
torbutton/en/design/design.xml      2038) 

torbutton/en/design/design.xml      2039) </sect3>

torbutton/en/design/design.xml      2040) 

torbutton/en/design/design.xml      2041) <sect3>
torbutton/en/design/design.xml      2042)   <title>Referer Spoofing Options</title>

torbutton/en/design/design.xml      2043) 

torbutton/en/design/design.xml      2044) <para>Option: <command>extensions.torbutton.refererspoof</command>

torbutton/en/design/design.xml      2045) </para>
torbutton/en/design/design.xml      2046) 

torbutton/en/design/design.xml      2047) <para>
torbutton/en/design/design.xml      2048) This option variable has three values. If it is 0, "smart" referer spoofing is
torbutton/en/design/design.xml      2049) enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is
torbutton/en/design/design.xml      2050) sent. The default value is 1. The smart referer spoofing is implemented by the
torbutton/en/design/design.xml      2051) <link linkend="refspoofer">torRefSpoofer</link> component.

torbutton/en/design/design.xml      2052) 

torbutton/en/design/design.xml      2053) </para>

torbutton/en/design/design.xml      2054) <para>
torbutton/en/design/design.xml      2055) This setting also does not directly satisfy any Torbutton requirement, but

torbutton/en/design/design.xml      2056) some may desire to mask their referer for general privacy concerns.

torbutton/en/design/design.xml      2057) </para>

torbutton/en/design/design.xml      2058) </sect3>
torbutton/en/design/design.xml      2059) 
torbutton/en/design/design.xml      2060) <sect3>

torbutton/en/design/design.xml      2061)   <title>Strip platform and language off of Google Search Box queries</title>
torbutton/en/design/design.xml      2062) 
torbutton/en/design/design.xml      2063) <para>Option: <command>extensions.torbutton.fix_google_srch</command>
torbutton/en/design/design.xml      2064) </para>
torbutton/en/design/design.xml      2065) 
torbutton/en/design/design.xml      2066) <para> 
torbutton/en/design/design.xml      2067) 
torbutton/en/design/design.xml      2068) This option causes Torbutton to use the <ulink
torbutton/en/design/design.xml      2069) url="https://wiki.mozilla.org/Search_Service:API">@mozilla.org/browser/search-service;1</ulink>
torbutton/en/design/design.xml      2070) component to wrap the Google search plugin. On many platforms, notably Debian
torbutton/en/design/design.xml      2071) and Ubuntu, the Google search plugin is set to reveal a lot of language and
torbutton/en/design/design.xml      2072) platform information. This setting strips off that info while Tor is enabled.
torbutton/en/design/design.xml      2073) 
torbutton/en/design/design.xml      2074) </para>
torbutton/en/design/design.xml      2075) <para>
torbutton/en/design/design.xml      2076) This setting helps Torbutton to fulfill its <link
torbutton/en/design/design.xml      2077) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
torbutton/en/design/design.xml      2078) </para>

torbutton/en/design/design.xml      2079) </sect3>

torbutton/en/design/design.xml      2080) 

torbutton/en/design/design.xml      2081) <sect3>

torbutton/en/design/design.xml      2082)   <title>Automatically use an alternate search engine when presented with a
torbutton/en/design/design.xml      2083) Google Captcha</title>
torbutton/en/design/design.xml      2084) 
torbutton/en/design/design.xml      2085) <para>Options:
torbutton/en/design/design.xml      2086) <simplelist>
torbutton/en/design/design.xml      2087)  <member><command>extensions.torbutton.asked_google_captcha</command></member>
torbutton/en/design/design.xml      2088)  <member><command>extensions.torbutton.dodge_google_captcha</command></member>
torbutton/en/design/design.xml      2089)  <member><command>extensions.torbutton.google_redir_url</command></member>
torbutton/en/design/design.xml      2090) </simplelist>
torbutton/en/design/design.xml      2091) </para>
torbutton/en/design/design.xml      2092) 
torbutton/en/design/design.xml      2093) <para>
torbutton/en/design/design.xml      2094) 
torbutton/en/design/design.xml      2095) Google's search engine has rate limiting features that cause it to
torbutton/en/design/design.xml      2096) <ulink
torbutton/en/design/design.xml      2097) url="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html">present
torbutton/en/design/design.xml      2098) captchas</ulink> and sometimes even outright ban IPs that issue large numbers
torbutton/en/design/design.xml      2099) of search queries, especially if a lot of these queries appear to be searching
torbutton/en/design/design.xml      2100) for software vulnerabilities or unprotected comment areas.
torbutton/en/design/design.xml      2101) 
torbutton/en/design/design.xml      2102) </para>
torbutton/en/design/design.xml      2103) <para>
torbutton/en/design/design.xml      2104) 
torbutton/en/design/design.xml      2105) Despite multiple discussions with Google, we were unable to come to a solution
torbutton/en/design/design.xml      2106) or any form of compromise that would reduce the number of captchas and
torbutton/en/design/design.xml      2107) outright bans seen by Tor users issuing regular queries.
torbutton/en/design/design.xml      2108) 
torbutton/en/design/design.xml      2109) </para>
torbutton/en/design/design.xml      2110) <para>
torbutton/en/design/design.xml      2111) As a result, we've implemented this option as an <ulink
torbutton/en/design/design.xml      2112) url="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">'http-on-modify-request'</ulink>
torbutton/en/design/design.xml      2113) http observer to optionally redirect banned or captcha-triggering Google
torbutton/en/design/design.xml      2114) queries to search engines that do not rate limit Tor users. The current

torbutton/en/design/design.xml      2115) options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. These are

torbutton/en/design/design.xml      2116) encoded in the preferences

torbutton/en/design/design.xml      2117) <command>extensions.torbutton.redir_url.[1-5]</command>.

torbutton/en/design/design.xml      2118) 
torbutton/en/design/design.xml      2119) </para>

torbutton/en/design/design.xml      2120) </sect3>

torbutton/en/design/design.xml      2121) 

torbutton/en/design/design.xml      2122) <sect3>

torbutton/en/design/design.xml      2123) 
torbutton/en/design/design.xml      2124)   <title>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</title>
torbutton/en/design/design.xml      2125) 
torbutton/en/design/design.xml      2126) <para>Options:
torbutton/en/design/design.xml      2127) <simplelist>
torbutton/en/design/design.xml      2128)  <member><command>extensions.torbutton.jar_certs</command></member>
torbutton/en/design/design.xml      2129)  <member><command>extensions.torbutton.jar_ca_certs</command></member>
torbutton/en/design/design.xml      2130) </simplelist>
torbutton/en/design/design.xml      2131) </para>
torbutton/en/design/design.xml      2132) <para>
torbutton/en/design/design.xml      2133) 
torbutton/en/design/design.xml      2134) These settings govern if Torbutton attempts to isolate the user's SSL
torbutton/en/design/design.xml      2135) certificates into separate jars for each Tor state. This isolation is
torbutton/en/design/design.xml      2136) implemented in <function>torbutton_jar_certs()</function> in <ulink

torbutton/en/design/design.xml      2137) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,

torbutton/en/design/design.xml      2138) which calls <function>torbutton_jar_cert_type()</function> and
torbutton/en/design/design.xml      2139) <function>torbutton_unjar_cert_type()</function> for each certificate type in
torbutton/en/design/design.xml      2140) the <ulink
torbutton/en/design/design.xml      2141) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1">@mozilla.org/security/nsscertcache;1</ulink>.
torbutton/en/design/design.xml      2142) Certificates are deleted from and imported to the <ulink
torbutton/en/design/design.xml      2143) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/x509certdb;1">@mozilla.org/security/x509certdb;1</ulink>.
torbutton/en/design/design.xml      2144) </para>
torbutton/en/design/design.xml      2145) 
torbutton/en/design/design.xml      2146) <para>
torbutton/en/design/design.xml      2147) The first time this pref is used, a backup of the user's certificates is
torbutton/en/design/design.xml      2148) created in their profile directory under the name
torbutton/en/design/design.xml      2149) <filename>cert8.db.bak</filename>. This file can be copied back to
torbutton/en/design/design.xml      2150) <filename>cert8.db</filename> to fully restore the original state of the
torbutton/en/design/design.xml      2151) user's certificates in the event of any error.
torbutton/en/design/design.xml      2152) </para>
torbutton/en/design/design.xml      2153) 
torbutton/en/design/design.xml      2154) <para>
torbutton/en/design/design.xml      2155) Since exit nodes and malicious sites can insert content elements sourced to
torbutton/en/design/design.xml      2156) specific SSL sites to query if a user has a certain certificate,
torbutton/en/design/design.xml      2157) this setting helps to satisfy the <link linkend="state">State
torbutton/en/design/design.xml      2158) Separation</link> requirement of Torbutton. Unfortunately, <ulink
torbutton/en/design/design.xml      2159) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Firefox Bug
torbutton/en/design/design.xml      2160) 435159</ulink> prevents it from functioning correctly in the event of rapid Tor toggle, so it
torbutton/en/design/design.xml      2161) is currently not exposed via the preferences UI.
torbutton/en/design/design.xml      2162) 
torbutton/en/design/design.xml      2163) </para>
torbutton/en/design/design.xml      2164) 

torbutton/en/design/design.xml      2165) </sect3>
torbutton/en/design/design.xml      2166) 
torbutton/en/design/design.xml      2167) 

torbutton/en/design/design.xml      2168) </sect2>
torbutton/en/design/design.xml      2169) </sect1>
torbutton/en/design/design.xml      2170) 
torbutton/en/design/design.xml      2171) <sect1 id="FirefoxBugs">
torbutton/en/design/design.xml      2172)   <title>Relevant Firefox Bugs</title>
torbutton/en/design/design.xml      2173)   <para>

torbutton/en/design/design.xml      2174) Future releases of Torbutton are going to be designed around supporting only
torbutton/en/design/design.xml      2175) <ulink url="https://www.torproject.org/projects/torbrowser.html.en">Tor
torbutton/en/design/design.xml      2176) Browser Bundle</ulink>, which greatly simplifies the number and nature of Firefox
torbutton/en/design/design.xml      2177) bugs we must fix. This allows us to abandon the complexities of <link
torbutton/en/design/design.xml      2178) linkend="state">State
torbutton/en/design/design.xml      2179) Separation</link> and <link linkend="isolation">Network Isolation</link> requirements
torbutton/en/design/design.xml      2180) associated with the Toggle Model.

torbutton/en/design/design.xml      2181)   </para>

torbutton/en/design/design.xml      2182)   <sect2 id="TorBrowserBugs">
torbutton/en/design/design.xml      2183)    <title>Tor Browser Bugs</title>
torbutton/en/design/design.xml      2184)    <para>
torbutton/en/design/design.xml      2185) The list of Firefox patches we must create to improve privacy on the
torbutton/en/design/design.xml      2186) Tor Browser Bundle are collected in the Tor Bug Tracker under <ulink
torbutton/en/design/design.xml      2187) url="https://trac.torproject.org/projects/tor/ticket/2871">ticket
torbutton/en/design/design.xml      2188) #2871</ulink>. These bugs are also applicable to the Toggle Model, and
torbutton/en/design/design.xml      2189) should be considered higher priority than all Toggle Model specific bugs
torbutton/en/design/design.xml      2190) below.
torbutton/en/design/design.xml      2191)    </para>
torbutton/en/design/design.xml      2192)   </sect2>
torbutton/en/design/design.xml      2193)   <sect2 id="ToggleModelBugs">
torbutton/en/design/design.xml      2194)    <title>Toggle Model Bugs</title>
torbutton/en/design/design.xml      2195)    <para>
torbutton/en/design/design.xml      2196) In addition to the Tor Browser bugs, the Torbutton Toggle Model suffers from
torbutton/en/design/design.xml      2197) additional bugs specific to the need to isolate state across the toggle.
torbutton/en/design/design.xml      2198) Toggle model bugs are considered a lower priority than the bugs against the
torbutton/en/design/design.xml      2199) Tor Browser model.
torbutton/en/design/design.xml      2200)    </para>
torbutton/en/design/design.xml      2201)   <sect3 id="FirefoxSecurity">

torbutton/en/design/design.xml      2202)    <title>Bugs impacting security</title>
torbutton/en/design/design.xml      2203)    <para>
torbutton/en/design/design.xml      2204) 
torbutton/en/design/design.xml      2205) Torbutton has to work around a number of Firefox bugs that impact its
torbutton/en/design/design.xml      2206) security. Most of these are mentioned elsewhere in this document, but they
torbutton/en/design/design.xml      2207) have also been gathered here for reference. In order of decreasing severity,
torbutton/en/design/design.xml      2208) they are:
torbutton/en/design/design.xml      2209) 
torbutton/en/design/design.xml      2210)    </para>
torbutton/en/design/design.xml      2211)    <orderedlist>

torbutton/en/design/design.xml      2212) <!--
torbutton/en/design/design.xml      2213) Duplicated in toggle model.

torbutton/en/design/design.xml      2214)     <listitem><ulink
torbutton/en/design/design.xml      2215) url="https://bugzilla.mozilla.org/show_bug.cgi?id=429070">Bug 429070 - exposing
torbutton/en/design/design.xml      2216) Components.interfaces to untrusted content leaks information about installed
torbutton/en/design/design.xml      2217) extensions</ulink>
torbutton/en/design/design.xml      2218)      <para>
torbutton/en/design/design.xml      2219) <ulink url="http://pseudo-flaw.net/">Gregory Fleischer</ulink> demonstrated at Defcon 17 that these interfaces can
torbutton/en/design/design.xml      2220) also be used to <ulink
torbutton/en/design/design.xml      2221) url="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html">fingerprint
torbutton/en/design/design.xml      2222) Firefox down the to the minor version</ulink>. Note that his test has not been
torbutton/en/design/design.xml      2223) updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This
torbutton/en/design/design.xml      2224) bug interferes with Torbutton's ability to satisfy its <link
torbutton/en/design/design.xml      2225) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
torbutton/en/design/design.xml      2226)      </para>
torbutton/en/design/design.xml      2227)     </listitem>
torbutton/en/design/design.xml      2228)    <listitem><ulink
torbutton/en/design/design.xml      2229) url="https://bugzilla.mozilla.org/show_bug.cgi?id=280661">Bug 280661 - SOCKS proxy server
torbutton/en/design/design.xml      2230) connection timeout hard-coded</ulink>
torbutton/en/design/design.xml      2231)     <para>
torbutton/en/design/design.xml      2232) 
torbutton/en/design/design.xml      2233) This bug prevents us from using the Firefox SOCKS layer directly, and
torbutton/en/design/design.xml      2234) currently requires us to ship an auxiliary HTTP proxy called <ulink
torbutton/en/design/design.xml      2235) url="http://www.pps.jussieu.fr/~jch/software/polipo/">Polipo</ulink>. If this
torbutton/en/design/design.xml      2236) patch were landed, we would no longer need to ship Polipo, which has a number
torbutton/en/design/design.xml      2237) of privacy and security issues of its own (in addition to being unmaintained).
torbutton/en/design/design.xml      2238) 
torbutton/en/design/design.xml      2239)     </para>
torbutton/en/design/design.xml      2240)    </listitem>
torbutton/en/design/design.xml      2241)    <listitem><ulink
torbutton/en/design/design.xml      2242) url="https://bugzilla.mozilla.org/show_bug.cgi?id=418986">Bug 418986 - window.screen
torbutton/en/design/design.xml      2243) provides a large amount of identifiable information</ulink>
torbutton/en/design/design.xml      2244)    <para>
torbutton/en/design/design.xml      2245) 
torbutton/en/design/design.xml      2246) As <link linkend="fingerprinting">mentioned above</link>, a large amount of
torbutton/en/design/design.xml      2247) information is available from <ulink
torbutton/en/design/design.xml      2248) url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>.

torbutton/en/design/design.xml      2249) The most sensitive data to anonymity is actually that which is not used in
torbutton/en/design/design.xml      2250) rendering - such as desktop resolution, and window decoration size.

torbutton/en/design/design.xml      2251) Currently, there is no way to obscure this information without Javascript

torbutton/en/design/design.xml      2252) hooking. In addition, many of this same desktop and window decoration
torbutton/en/design/design.xml      2253) resolution information is available via <ulink
torbutton/en/design/design.xml      2254) url="https://developer.mozilla.org/En/CSS/Media_queries">CSS Media
torbutton/en/design/design.xml      2255) Queries</ulink>, so perhaps some more lower-level rendering controls or
torbutton/en/design/design.xml      2256) preferences need to be provided. These issues interfere with Torbutton's
torbutton/en/design/design.xml      2257) ability to fulfill its <link linkend="setpreservation">Anonymity Set
torbutton/en/design/design.xml      2258) Preservation</link> requirement.

torbutton/en/design/design.xml      2259) 
torbutton/en/design/design.xml      2260)    </para>
torbutton/en/design/design.xml      2261)    </listitem>

torbutton/en/design/design.xml      2262) -->

torbutton/en/design/design.xml      2263)    <listitem><ulink
torbutton/en/design/design.xml      2264) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Bug 435159 -
torbutton/en/design/design.xml      2265) nsNSSCertificateDB::DeleteCertificate has race conditions</ulink>
torbutton/en/design/design.xml      2266)       <para>
torbutton/en/design/design.xml      2267) 
torbutton/en/design/design.xml      2268) In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
torbutton/en/design/design.xml      2269) the user has installed. Unfortunately, the method call to delete a certificate
torbutton/en/design/design.xml      2270) from the current certificate database acts lazily: it only sets a variable
torbutton/en/design/design.xml      2271) that marks a cert for deletion later, and it is not cleared if that
torbutton/en/design/design.xml      2272) certificate is re-added. This means that if the Tor state is toggled quickly,
torbutton/en/design/design.xml      2273) that certificate could remain present until it is re-inserted (causing an
torbutton/en/design/design.xml      2274) error dialog), and worse, it would still be deleted after that.  The lack of
torbutton/en/design/design.xml      2275) this functionality is considered a Torbutton security bug because cert
torbutton/en/design/design.xml      2276) isolation is considered a <link linkend="state">State Separation</link>
torbutton/en/design/design.xml      2277) feature.
torbutton/en/design/design.xml      2278) 
torbutton/en/design/design.xml      2279)       </para>
torbutton/en/design/design.xml      2280)      </listitem>

torbutton/en/design/design.xml      2281)      <listitem>Give more visibility into and control over TLS
torbutton/en/design/design.xml      2282) negotiation
torbutton/en/design/design.xml      2283)      <para>

torbutton/en/design/design.xml      2284) 

torbutton/en/design/design.xml      2285) There are several <ulink
torbutton/en/design/design.xml      2286) url="https://trac.torproject.org/projects/tor/ticket/2482">TLS issues
torbutton/en/design/design.xml      2287) impacting Torbutton security</ulink>. It is not clear if these should be one
torbutton/en/design/design.xml      2288) Firefox bug or several, but in particular we need better control over various
torbutton/en/design/design.xml      2289) aspects of TLS connections. Firefox currently provides no observer capable of
torbutton/en/design/design.xml      2290) extracting TLS parameters or certificates early enough to cancel a TLS
torbutton/en/design/design.xml      2291) request. We would like to be able to provide <ulink
torbutton/en/design/design.xml      2292) url="https://www.eff.org/https-everywhere">HTTPS-Everywhere</ulink> users with
torbutton/en/design/design.xml      2293) the ability to <ulink
torbutton/en/design/design.xml      2294) url="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission">have
torbutton/en/design/design.xml      2295) their certificates audited</ulink> by a <ulink
torbutton/en/design/design.xml      2296) url="http://www.networknotary.org/">Perspectives</ulink>-style set of
torbutton/en/design/design.xml      2297) notaries. The problem with this is that the API observer points do not exist
torbutton/en/design/design.xml      2298) for any Firefox addon to actually block authentication token submission over a
torbutton/en/design/design.xml      2299) TLS channel, so every addon to date (including Perspectives) is actually
torbutton/en/design/design.xml      2300) providing users with notification *after* their authentication tokens have
torbutton/en/design/design.xml      2301) already been compromised. This obviously needs to be fixed.
torbutton/en/design/design.xml      2302)      </para>
torbutton/en/design/design.xml      2303)      </listitem>

torbutton/en/design/design.xml      2304) <!--
torbutton/en/design/design.xml      2305) This is under the Tor Browser model.

torbutton/en/design/design.xml      2306)      <listitem><ulink
torbutton/en/design/design.xml      2307) url="https://bugzilla.mozilla.org/show_bug.cgi?id=575230">Bug 575230 - Provide option to
torbutton/en/design/design.xml      2308) reduce precision of Date()</ulink>
torbutton/en/design/design.xml      2309)       <para>
torbutton/en/design/design.xml      2310) 
torbutton/en/design/design.xml      2311) Currently it is possible to <ulink
torbutton/en/design/design.xml      2312) url="http://arstechnica.com/tech-policy/news/2010/02/firm-uses-typing-cadence-to-finger-unauthorized-users.ars">fingerprint
torbutton/en/design/design.xml      2313) users based on their typing cadence</ulink> using the high precision timer
torbutton/en/design/design.xml      2314) available to javascript. Using this same precision, it is possible to compute
torbutton/en/design/design.xml      2315) an identifier based upon the clock drift of the client from some nominal
torbutton/en/design/design.xml      2316) source. The latter is not much of a concern for Tor users, as the variable
torbutton/en/design/design.xml      2317) delay to load and run a page is measured on the order of seconds, but the high
torbutton/en/design/design.xml      2318) precision timer can still be used to fingerprint aspects of a browser's
torbutton/en/design/design.xml      2319) javascript engine and processor, and apparently also a user's typing cadence.
torbutton/en/design/design.xml      2320) This bug hinders Torbutton's ability to satisfy its <link
torbutton/en/design/design.xml      2321) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
torbutton/en/design/design.xml      2322) 
torbutton/en/design/design.xml      2323)       </para>
torbutton/en/design/design.xml      2324)      </listitem>

torbutton/en/design/design.xml      2325) -->

torbutton/en/design/design.xml      2326)     <listitem><ulink

torbutton/en/design/design.xml      2327) url="https://bugzilla.mozilla.org/show_bug.cgi?id=122752">Bug 122752 - SOCKS

torbutton/en/design/design.xml      2328) Username/Password Support</ulink>
torbutton/en/design/design.xml      2329)     <para>
torbutton/en/design/design.xml      2330) We need <ulink url="https://developer.mozilla.org/en/nsIProxyInfo">Firefox
torbutton/en/design/design.xml      2331) APIs</ulink> or about:config settings to control the SOCKS Username and
torbutton/en/design/design.xml      2332) Password fields. The reason why we need this support is to utilize an (as yet
torbutton/en/design/design.xml      2333) unimplemented) scheme to separate Tor traffic based <ulink
torbutton/en/design/design.xml      2334) url="https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/171-separate-streams.txt">on
torbutton/en/design/design.xml      2335) SOCKS username/password</ulink>.
torbutton/en/design/design.xml      2336)     </para>
torbutton/en/design/design.xml      2337)     </listitem>

torbutton/en/design/design.xml      2338) 
torbutton/en/design/design.xml      2339)      <listitem><ulink
torbutton/en/design/design.xml      2340) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Bug 409737 -
torbutton/en/design/design.xml      2341) javascript.enabled and docShell.allowJavascript do not disable all event
torbutton/en/design/design.xml      2342) handlers</ulink>
torbutton/en/design/design.xml      2343)      <para>
torbutton/en/design/design.xml      2344) 
torbutton/en/design/design.xml      2345) This bug allows pages to execute javascript via addEventListener and perhaps
torbutton/en/design/design.xml      2346) other callbacks. In order to prevent this bug from enabling an attacker to
torbutton/en/design/design.xml      2347) break the <link linkend="isolation">Network Isolation</link> requirement,
torbutton/en/design/design.xml      2348) Torbutton 1.1.13 began blocking popups and history manipulation from different
torbutton/en/design/design.xml      2349) Tor states.  So long as there are no ways to open popups or redirect the user
torbutton/en/design/design.xml      2350) to a new page, the <link linkend="contentpolicy">Torbutton content
torbutton/en/design/design.xml      2351) policy</link> should block Javascript network access. However, if there are
torbutton/en/design/design.xml      2352) ways to open popups or perform redirects such that Torbutton cannot block
torbutton/en/design/design.xml      2353) them, pages may still have free reign to break that requirement and reveal a
torbutton/en/design/design.xml      2354) user's original IP address.
torbutton/en/design/design.xml      2355) 
torbutton/en/design/design.xml      2356)      </para>
torbutton/en/design/design.xml      2357)      </listitem>
torbutton/en/design/design.xml      2358)      <listitem><ulink
torbutton/en/design/design.xml      2359) url="https://bugzilla.mozilla.org/show_bug.cgi?id=448743">Bug 448743 -
torbutton/en/design/design.xml      2360) Decouple general.useragent.locale from spoofing of navigator.language</ulink>
torbutton/en/design/design.xml      2361)      <para>
torbutton/en/design/design.xml      2362) 
torbutton/en/design/design.xml      2363) Currently, Torbutton spoofs the <command>navigator.language</command>
torbutton/en/design/design.xml      2364) attribute via <link linkend="jshooks">Javascript hooks</link>. Unfortunately,
torbutton/en/design/design.xml      2365) these do not work on Firefox 3. It would be ideal to have
torbutton/en/design/design.xml      2366) a pref to set this value (something like a
torbutton/en/design/design.xml      2367) <command>general.useragent.override.locale</command>),
torbutton/en/design/design.xml      2368) to avoid fragmenting the anonymity set of users of foreign locales. This issue
torbutton/en/design/design.xml      2369) impedes Torbutton from fully meeting its <link
torbutton/en/design/design.xml      2370) linkend="setpreservation">Anonymity Set Preservation</link>
torbutton/en/design/design.xml      2371) requirement on Firefox 3.
torbutton/en/design/design.xml      2372) 
torbutton/en/design/design.xml      2373)      </para>
torbutton/en/design/design.xml      2374)      </listitem>
torbutton/en/design/design.xml      2375)     </orderedlist>

torbutton/en/design/design.xml      2376)   </sect3>

torbutton/en/design/design.xml      2377) <!-- XXX: Need to create a bug for DOM storage APIs at some point -->

torbutton/en/design/design.xml      2378)   <sect3 id="FirefoxWishlist">

torbutton/en/design/design.xml      2379)    <title>Bugs blocking functionality</title>
torbutton/en/design/design.xml      2380)    <para>
torbutton/en/design/design.xml      2381) The following bugs impact Torbutton and similar extensions' functionality.
torbutton/en/design/design.xml      2382)    </para>
torbutton/en/design/design.xml      2383) 
torbutton/en/design/design.xml      2384)     <orderedlist>
torbutton/en/design/design.xml      2385) 

torbutton/en/design/design.xml      2386) <!--

torbutton/en/design/design.xml      2387)    <listitem><ulink
torbutton/en/design/design.xml      2388) url="https://bugzilla.mozilla.org/show_bug.cgi?id=445696">Bug 445696 -

torbutton/en/design/design.xml      2389) Extensions cannot determine if Firefox is full screen</ulink>

torbutton/en/design/design.xml      2390)    <para>
torbutton/en/design/design.xml      2391) 
torbutton/en/design/design.xml      2392) The windowState property of <ulink
torbutton/en/design/design.xml      2393) url="https://developer.mozilla.org/en/XUL/window">ChromeWindows</ulink> does not accurately reflect the true
torbutton/en/design/design.xml      2394) state of the window in some cases on Linux. This causes Torbutton to attempt
torbutton/en/design/design.xml      2395) to resize maximized and minimized windows when it should not.
torbutton/en/design/design.xml      2396) 
torbutton/en/design/design.xml      2397)    </para>
torbutton/en/design/design.xml      2398)    </listitem>

torbutton/en/design/design.xml      2399) -->

torbutton/en/design/design.xml      2400)    <listitem><ulink

torbutton/en/design/design.xml      2401) url="https://bugzilla.mozilla.org/show_bug.cgi?id=629820">Bug 629820 - nsIContentPolicy::shouldLoad not

torbutton/en/design/design.xml      2402) called for web request in Firefox Mobile</ulink>
torbutton/en/design/design.xml      2403)     <para>
torbutton/en/design/design.xml      2404) 
torbutton/en/design/design.xml      2405) The new <ulink
torbutton/en/design/design.xml      2406) url="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis">Electrolysis</ulink>
torbutton/en/design/design.xml      2407) multiprocess system appears to have some pretty rough edge cases with respect
torbutton/en/design/design.xml      2408) to registering XPCOM category managers such as the nsIContentPolicy, which
torbutton/en/design/design.xml      2409) make it difficult to do a straight-forward port of Torbutton or
torbutton/en/design/design.xml      2410) HTTPS-Everywhere to Firefox Mobile.  It probably also has similar issues with
torbutton/en/design/design.xml      2411) wrapping existing <link linkend="hookedxpcom">Firefox XPCOM components</link>,
torbutton/en/design/design.xml      2412) which will also cause more problems for porting Torbutton.
torbutton/en/design/design.xml      2413) 
torbutton/en/design/design.xml      2414)     </para>
torbutton/en/design/design.xml      2415)    </listitem>

torbutton/en/design/design.xml      2416) <!--

torbutton/en/design/design.xml      2417)    <listitem><ulink

torbutton/en/design/design.xml      2418) url="https://bugzilla.mozilla.org/show_bug.cgi?id=290456">Bug 290456 -
torbutton/en/design/design.xml      2419) Block/clear Flash MX "cookies" as well</ulink>
torbutton/en/design/design.xml      2420)    <para>
torbutton/en/design/design.xml      2421) 
torbutton/en/design/design.xml      2422) Today, it is possible to allow plugins if you have a transparent proxy such as
torbutton/en/design/design.xml      2423) <ulink url="http://anonymityanywhere.com/incognito/">Incognito</ulink> to prevent proxy bypass. However, flash cookies can still be used to
torbutton/en/design/design.xml      2424) link your Tor and Non-Tor activity, and this reveal your IP to an adversary
torbutton/en/design/design.xml      2425) that does so. This can be solved by manually removing your flash cookies (like
torbutton/en/design/design.xml      2426) <ulink
torbutton/en/design/design.xml      2427) url="https://addons.mozilla.org/en-US/firefox/addon/6623">BetterPrivacy</ulink> does), but
torbutton/en/design/design.xml      2428) it would be nice if there was a standard way to do this from a Firefox API.
torbutton/en/design/design.xml      2429) 
torbutton/en/design/design.xml      2430)    </para>
torbutton/en/design/design.xml      2431)    </listitem>

torbutton/en/design/design.xml      2432) -->

torbutton/en/design/design.xml      2433)    <listitem><ulink
torbutton/en/design/design.xml      2434) url="https://bugzilla.mozilla.org/show_bug.cgi?id=417869">Bug 417869 -
torbutton/en/design/design.xml      2435) Browser context is difficult to obtain from many XPCOM callbacks</ulink>
torbutton/en/design/design.xml      2436)    <para>
torbutton/en/design/design.xml      2437) 
torbutton/en/design/design.xml      2438) It is difficult to determine which tabbrowser many XPCOM callbacks originate
torbutton/en/design/design.xml      2439) from, and in some cases absolutely no context information is provided at all.
torbutton/en/design/design.xml      2440) While this doesn't have much of an effect on Torbutton, it does make writing
torbutton/en/design/design.xml      2441) extensions that would like to do per-tab settings and content filters (such as
torbutton/en/design/design.xml      2442) FoxyProxy) difficult to impossible to implement securely.
torbutton/en/design/design.xml      2443) 
torbutton/en/design/design.xml      2444)    </para>
torbutton/en/design/design.xml      2445)    </listitem>

torbutton/en/design/design.xml      2446) <!--
torbutton/en/design/design.xml      2447) FIXME: This doesn't really apply anymore.

torbutton/en/design/design.xml      2448)    <listitem><ulink
torbutton/en/design/design.xml      2449) url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
torbutton/en/design/design.xml      2450) Components do not expose disk interfaces</ulink>
torbutton/en/design/design.xml      2451)    <para>
torbutton/en/design/design.xml      2452) 
torbutton/en/design/design.xml      2453) Several components currently provide no way of reimplementing their disk
torbutton/en/design/design.xml      2454) access to easily satisfy Torbutton's <link linkend="disk">Disk
torbutton/en/design/design.xml      2455) Avoidance</link> requirements. Workarounds exist, but they are <link
torbutton/en/design/design.xml      2456) linkend="sessionstore">clunky</link>, and
torbutton/en/design/design.xml      2457) some of them involve disabling functionality during Tor usage.
torbutton/en/design/design.xml      2458) 
torbutton/en/design/design.xml      2459)    </para>
torbutton/en/design/design.xml      2460)    </listitem>

torbutton/en/design/design.xml      2461) -->

torbutton/en/design/design.xml      2462) 
torbutton/en/design/design.xml      2463) <!--
torbutton/en/design/design.xml      2464) FIXME: Need to use new observer methods if possible
torbutton/en/design/design.xml      2465)    <listitem><ulink
torbutton/en/design/design.xml      2466) url="https://bugzilla.mozilla.org/show_bug.cgi?id=448741">Bug 448741 -
torbutton/en/design/design.xml      2467) nsISessionStore uses private methods and is not extensible</ulink>
torbutton/en/design/design.xml      2468)    <para>
torbutton/en/design/design.xml      2469) 
torbutton/en/design/design.xml      2470) Similar to the above bug, in the specific case of the sessionstore component,
torbutton/en/design/design.xml      2471) the API is not amenable to Contract ID hooking, and this requires that
torbutton/en/design/design.xml      2472) Torbutton include modified copies of this component for Firefox 2 and 3, which
torbutton/en/design/design.xml      2473) has <ulink
torbutton/en/design/design.xml      2474) url="https://bugs.torproject.org/flyspray/index.php?do=details&amp;id=722">raised
torbutton/en/design/design.xml      2475) objections</ulink> from some developers.
torbutton/en/design/design.xml      2476) 
torbutton/en/design/design.xml      2477)    </para>
torbutton/en/design/design.xml      2478)    </listitem>
torbutton/en/design/design.xml      2479)    <listitem><ulink
torbutton/en/design/design.xml      2480) url="https://bugzilla.mozilla.org/show_bug.cgi?id=439384">Bug 439384 -
torbutton/en/design/design.xml      2481) "profile-do-change" event does not cause cookie table reload</ulink>
torbutton/en/design/design.xml      2482)    <para>
torbutton/en/design/design.xml      2483) 
torbutton/en/design/design.xml      2484) In Firefox 3, the change to the new SQLlite database for cookie storage has a
torbutton/en/design/design.xml      2485) bug that prevents Torbutton's cookie jaring from working properly. The
torbutton/en/design/design.xml      2486) "profile-do-change" observer event no longer properly causes either a sync or
torbutton/en/design/design.xml      2487) reload of the cookie database from disk after it is copied into place.
torbutton/en/design/design.xml      2488) Torbutton currently works around this by issuing the SQLLite queries manually
torbutton/en/design/design.xml      2489) to store and rebuild the cookie database.
torbutton/en/design/design.xml      2490) 
torbutton/en/design/design.xml      2491)    </para>
torbutton/en/design/design.xml      2492)    </listitem>
torbutton/en/design/design.xml      2493) 
torbutton/en/design/design.xml      2494)    <listitem><ulink
torbutton/en/design/design.xml      2495) url="https://bugzilla.mozilla.org/show_bug.cgi?id=248970">Bug 248970 (PrivateBrowsing) - Private Browsing mode (global toggle for
torbutton/en/design/design.xml      2496) saving/caching everything)</ulink>
torbutton/en/design/design.xml      2497)    <para>
torbutton/en/design/design.xml      2498) 
torbutton/en/design/design.xml      2499) This bug catalogs the discussion of a 'Private Mode' in Firefox that would
torbutton/en/design/design.xml      2500) perform many, but not all, of the activities of Torbutton. It would be useful
torbutton/en/design/design.xml      2501) to leverage the resulting setting to simplify Torbutton. This bug is listed so
torbutton/en/design/design.xml      2502) we can track this progress and ensure that it doesn't end up defining
torbutton/en/design/design.xml      2503) behaviors contrary to and incompatible with Torbutton's requirements (though a
torbutton/en/design/design.xml      2504) subset of the <link linkend="requirements">requirements</link> is of course fine).
torbutton/en/design/design.xml      2505) 
torbutton/en/design/design.xml      2506)    </para>
torbutton/en/design/design.xml      2507)    </listitem>
torbutton/en/design/design.xml      2508) -->
torbutton/en/design/design.xml      2509) 
torbutton/en/design/design.xml      2510) 
torbutton/en/design/design.xml      2511) 
torbutton/en/design/design.xml      2512)   </orderedlist>

torbutton/en/design/design.xml      2513)   </sect3>
torbutton/en/design/design.xml      2514)   <sect3 id="FirefoxMiscBugs">

torbutton/en/design/design.xml      2515)    <title>Low Priority Bugs</title>
torbutton/en/design/design.xml      2516)    <para>
torbutton/en/design/design.xml      2517) The following bugs have an effect upon Torbutton, but are superseded by more
torbutton/en/design/design.xml      2518) practical and more easily fixable variant bugs above; or have stable, simple
torbutton/en/design/design.xml      2519) workarounds.
torbutton/en/design/design.xml      2520)   </para>
torbutton/en/design/design.xml      2521) 
torbutton/en/design/design.xml      2522)     <orderedlist>

torbutton/en/design/design.xml      2523) <!--

torbutton/en/design/design.xml      2524)     <listitem><ulink
torbutton/en/design/design.xml      2525) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435151">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</ulink>
torbutton/en/design/design.xml      2526)      <para>
torbutton/en/design/design.xml      2527) 
torbutton/en/design/design.xml      2528) Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
torbutton/en/design/design.xml      2529) constructors of classes defined from within the scope of the sandbox, among
torbutton/en/design/design.xml      2530) other things. This prevents Torbutton from applying the Timezone hooks under
torbutton/en/design/design.xml      2531) Firefox 3, but a better solution for Torbutton's specific date hooking needs 
torbutton/en/design/design.xml      2532) would be a fix for the above mentioned Bug 392274. Of course, many more
torbutton/en/design/design.xml      2533) extensions may be interested in the sandbox hooking functionality working
torbutton/en/design/design.xml      2534) properly though.
torbutton/en/design/design.xml      2535) 
torbutton/en/design/design.xml      2536)      </para>
torbutton/en/design/design.xml      2537)      </listitem>

torbutton/en/design/design.xml      2538) -->

torbutton/en/design/design.xml      2539)      <listitem><ulink
torbutton/en/design/design.xml      2540) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">Bug 440892 -
torbutton/en/design/design.xml      2541) network.protocol-handler.warn-external are ignored</ulink>
torbutton/en/design/design.xml      2542)      <para>
torbutton/en/design/design.xml      2543) 
torbutton/en/design/design.xml      2544) Sometime in the Firefox 3 development cycle, the preferences that governed
torbutton/en/design/design.xml      2545) warning a user when external apps were launched got disconnected from the code
torbutton/en/design/design.xml      2546) that does the launching. Torbutton depended on these prefs to prevent websites
torbutton/en/design/design.xml      2547) from launching specially crafted documents and application arguments that
torbutton/en/design/design.xml      2548) caused Proxy Bypass. We currently work around this issue by <link
torbutton/en/design/design.xml      2549) linkend="appblocker">wrapping the app launching components</link> to present a
torbutton/en/design/design.xml      2550) popup before launching external apps while Tor is enabled. While this works,
torbutton/en/design/design.xml      2551) it would be nice if these prefs were either fixed or removed.
torbutton/en/design/design.xml      2552) 
torbutton/en/design/design.xml      2553)      </para>
torbutton/en/design/design.xml      2554)      </listitem>
torbutton/en/design/design.xml      2555)     <listitem><ulink
torbutton/en/design/design.xml      2556) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">Bug 437014 -
torbutton/en/design/design.xml      2557) nsIContentPolicy::shouldLoad no longer called for favicons</ulink>
torbutton/en/design/design.xml      2558)     <para>
torbutton/en/design/design.xml      2559) 
torbutton/en/design/design.xml      2560) Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
torbutton/en/design/design.xml      2561) loads. Torbutton had relied on this call to block favicon loads for opposite
torbutton/en/design/design.xml      2562) Tor states. The workaround it employs for Firefox 3 is to cancel the request
torbutton/en/design/design.xml      2563) when it arrives in the <command>torbutton_http_observer</command> used for
torbutton/en/design/design.xml      2564) blocking full page plugin loads. This seems to work just fine, but is a bit
torbutton/en/design/design.xml      2565) dirty.
torbutton/en/design/design.xml      2566) 
torbutton/en/design/design.xml      2567)     </para>
torbutton/en/design/design.xml      2568)     </listitem>
torbutton/en/design/design.xml      2569) <!--
torbutton/en/design/design.xml      2570)     <listitem><ulink
torbutton/en/design/design.xml      2571) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437016">Bug 437016 -
torbutton/en/design/design.xml      2572) nsIContentPolicy::shouldLoad not called for livemarks</ulink>
torbutton/en/design/design.xml      2573)     <para>
torbutton/en/design/design.xml      2574) 
torbutton/en/design/design.xml      2575) An alternative fix for the livemarks bug above would be to block livemarks
torbutton/en/design/design.xml      2576) fetches from the content policy. Unfortunately shouldLoad is not called for
torbutton/en/design/design.xml      2577) livemarks fetches.
torbutton/en/design/design.xml      2578) 
torbutton/en/design/design.xml      2579)     </para>
torbutton/en/design/design.xml      2580)     </listitem>
torbutton/en/design/design.xml      2581) -->
torbutton/en/design/design.xml      2582)  
torbutton/en/design/design.xml      2583)      <listitem><ulink
torbutton/en/design/design.xml      2584) url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">Bug 309524</ulink>
torbutton/en/design/design.xml      2585) and <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">Bug
torbutton/en/design/design.xml      2586) 380556</ulink> - nsIContentPolicy::shouldProcess is not called.
torbutton/en/design/design.xml      2587)      <para>
torbutton/en/design/design.xml      2588) 
torbutton/en/design/design.xml      2589) This is a call that would be useful to develop a better workaround for the
torbutton/en/design/design.xml      2590) allowPlugins issue above. If the content policy were called before a URL was
torbutton/en/design/design.xml      2591) handed over to a plugin or helper app, it would make the workaround for the
torbutton/en/design/design.xml      2592) above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
torbutton/en/design/design.xml      2593) the others though, but it might be nice to have this API as a backup.
torbutton/en/design/design.xml      2594) 
torbutton/en/design/design.xml      2595)      </para>
torbutton/en/design/design.xml      2596)      </listitem>
torbutton/en/design/design.xml      2597) 
torbutton/en/design/design.xml      2598)      <listitem><ulink
torbutton/en/design/design.xml      2599) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">Bug 401296 - docShell.allowPlugins
torbutton/en/design/design.xml      2600) not honored for direct links</ulink> (Perhaps subset of <ulink
torbutton/en/design/design.xml      2601) url="https://bugzilla.mozilla.org/show_bug.cgi?id=282106">Bug 282106</ulink>?)
torbutton/en/design/design.xml      2602)      <para>
torbutton/en/design/design.xml      2603) 
torbutton/en/design/design.xml      2604) Similar to the javascript plugin disabling attribute, the plugin disabling
torbutton/en/design/design.xml      2605) attribute is also not perfect &mdash; it is ignored for direct links to plugin
torbutton/en/design/design.xml      2606) handled content, as well as meta-refreshes to plugin handled content.  This
torbutton/en/design/design.xml      2607) requires Torbutton to listen to a number of different http events to intercept
torbutton/en/design/design.xml      2608) plugin-related mime type URLs and cancel their requests. Again, since plugins
torbutton/en/design/design.xml      2609) are quite horrible about obeying proxy settings, loading a plugin pretty much
torbutton/en/design/design.xml      2610) ensures a way to break the <link linkend="isolation">Network Isolation</link>
torbutton/en/design/design.xml      2611) requirement and reveal a user's original IP address. Torbutton's code to
torbutton/en/design/design.xml      2612) perform this workaround has been subverted at least once already by Kyle
torbutton/en/design/design.xml      2613) Williams.
torbutton/en/design/design.xml      2614) 
torbutton/en/design/design.xml      2615)      </para>
torbutton/en/design/design.xml      2616)      </listitem>

torbutton/en/design/design.xml      2617) <!--
torbutton/en/design/design.xml      2618) Actually, ECMAScript 5 handles this correctly now.

torbutton/en/design/design.xml      2619)    <listitem><ulink
torbutton/en/design/design.xml      2620) url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
torbutton/en/design/design.xml      2621) Date' is deletable</ulink>
torbutton/en/design/design.xml      2622)      <para>
torbutton/en/design/design.xml      2623) 
torbutton/en/design/design.xml      2624) Based on Page 62 of the <ulink
torbutton/en/design/design.xml      2625) url="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">ECMA-262
torbutton/en/design/design.xml      2626) Javascript spec</ulink>, it seems like it should be possible to do something
torbutton/en/design/design.xml      2627) like the following to prevent the Date object from being unmasked:
torbutton/en/design/design.xml      2628) <screen>
torbutton/en/design/design.xml      2629) with(window) {
torbutton/en/design/design.xml      2630)     var Date = fakeDate;
torbutton/en/design/design.xml      2631)     var otherVariable = 42;
torbutton/en/design/design.xml      2632) }
torbutton/en/design/design.xml      2633) 
torbutton/en/design/design.xml      2634) delete window.Date; // Should fail. Instead succeeds, revealing original Date.
torbutton/en/design/design.xml      2635) delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
torbutton/en/design/design.xml      2636) </screen>
torbutton/en/design/design.xml      2637) 
torbutton/en/design/design.xml      2638) From the ECMA-262 spec:
torbutton/en/design/design.xml      2639) 
torbutton/en/design/design.xml      2640) <blockquote>
torbutton/en/design/design.xml      2641) If the variable statement occurs inside a FunctionDeclaration, the variables
torbutton/en/design/design.xml      2642) are defined with function-local scope in that function, as described in
torbutton/en/design/design.xml      2643) s10.1.3. Otherwise, they are defined with global scope (that is, they are
torbutton/en/design/design.xml      2644) created as members of the global object, as described in 10.1.3) using
torbutton/en/design/design.xml      2645) property attributes { DontDelete }. Variables are created when the execution
torbutton/en/design/design.xml      2646) scope is entered. A Block does not define a new execution scope. Only Program
torbutton/en/design/design.xml      2647) and FunctionDeclaration produce a new scope. Variables are initialized to
torbutton/en/design/design.xml      2648) undefined when created. A variable with an Initialiser is assigned the value
torbutton/en/design/design.xml      2649) of its AssignmentExpression when the VariableStatement is executed, not when
torbutton/en/design/design.xml      2650) the variable is created.
torbutton/en/design/design.xml      2651) </blockquote>
torbutton/en/design/design.xml      2652) 
torbutton/en/design/design.xml      2653) In fact, this is exactly how the with statement with a variable declaration
torbutton/en/design/design.xml      2654) behaves <emphasis>for all other variables other than ones that shadow system
torbutton/en/design/design.xml      2655) variables</emphasis>. Some variables (such as
torbutton/en/design/design.xml      2656) <command>window.screen</command>, and <command>window.history</command>) can't
torbutton/en/design/design.xml      2657) even be shadowed in this way, and give an error about lacking a setter. If
torbutton/en/design/design.xml      2658) such shadowing were possible, it would greatly simplify the Javascript hooking
torbutton/en/design/design.xml      2659) code, which currently relies on undocumented semantics of
torbutton/en/design/design.xml      2660) <command>__proto__</command> to copy the original values in the event of a
torbutton/en/design/design.xml      2661) delete. This <command>__proto__</command> hack unfortunately does not work for
torbutton/en/design/design.xml      2662) the Date object though.
torbutton/en/design/design.xml      2663) 
torbutton/en/design/design.xml      2664)      </para>
torbutton/en/design/design.xml      2665)     </listitem>

torbutton/en/design/design.xml      2666) -->

torbutton/en/design/design.xml      2667)   </orderedlist>

torbutton/en/design/design.xml      2668)   </sect3>
torbutton/en/design/design.xml      2669)  </sect2>