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
torbutton/en/design/design.xml  247) by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
torbutton/en/design/design.xml  248) 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>