GitList - GitList

                     new file mode 100644
@@ -0,0 +1,2312 @@
                     +<?xml version="1.0" encoding="ISO-8859-1"?>
                     +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                     +     "file:///usr/share/sgml/docbook/xml-dtd-4.4-1.0-30.1/docbookx.dtd">
+                    +
                     +<article id="design">
                     + <articleinfo>
                     +  <title>Torbutton Design Documentation</title>
                     +   <author>
                     +    <firstname>Mike</firstname><surname>Perry</surname>
                     +    <affiliation>
                     +     <address><email>mikeperry.fscked/org</email></address>
                     +    </affiliation>
                     +   </author>
                     +   <pubdate>July 4 2008</pubdate>
                     + </articleinfo>
+                    +
                     +<sect1>
                     +  <title>Introduction</title>
                     +  <para>
+                    +
                     +This document describes the goals, operation, and testing procedures of the
                     +Torbutton Firefox extension. It is current as of Torbutton 1.2.0rc5.
+                    +
                     +  </para>
                     +  <sect2 id="adversary">
                     +   <title>Adversary Model</title>
                     +   <para>
+                    +
                     +A Tor web browser adversary has a number of goals, capabilities, and attack
                     +types that can be used to guide us towards a set of requirements for the
                     +Torbutton extension. Let's start with the goals.
+                    +
                     +   </para>
                     +   <sect3>
                     +    <title>Adversary Goals</title>
                     +    <orderedlist>
                     +<!-- These aren't really commands.. But it's the closest I could find in an
                     +acceptable style.. Don't really want to make my own stylesheet -->
                     +     <listitem><command>Bypassing proxy settings</command>
                     +     <para>The adversary's primary goal is direct compromise and bypass of
                     +Tor, causing the user to directly connect to an IP of the adversary's
                     +choosing.</para>
                     +     </listitem>
                     +     <listitem><command>Correlation of Tor vs Non-Tor Activity</command>
                     +     <para>If direct proxy bypass is not possible, the adversary will likely
                     +happily settle for the ability to correlate something a user did via Tor with
                     +their non-Tor activity. This can be done with cookies, cache identifiers,
                     +javascript events, and even CSS. Sometimes the fact that a user uses Tor may
                     +be enough for some authorities.</para>
                     +     </listitem>
                     +     <listitem><command>History disclosure</command>
                     +     <para>
                     +The adversary may also be interested in history disclosure: the ability to
                     +query a user's history to see if they have issued certain censored search
                     +queries, or visited censored sites.
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Location information</command>
                     +     <para>
+                    +
                     +Location information such as timezone and locality can be useful for the
                     +adversary to determine if a user is in fact originating from one of the
                     +regions they are attempting to control, or to zero-in on the geographical
                     +location of a particular dissident or whistleblower.
+                    +
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Miscellaneous anonymity set reduction</command>
                     +     <para>
+                    +
                     +Anonymity set reduction is also useful in attempting to zero in on a
                     +particular individual. If the dissident or whistleblower is using a rare build
                     +of Firefox for an obscure operating system, this can be very useful
                     +information for tracking them down, or at least <link
                     +linkend="fingerprinting">tracking their activities</link>.
+                    +
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>History records and other on-disk
                     +information</command>
                     +     <para>
                     +In some cases, the adversary may opt for a heavy-handed approach, such as
                     +seizing the computers of all Tor users in an area (especially after narrowing
                     +the field by the above two pieces of information). History records and cache
                     +data are the primary goals here.
                     +     </para>
                     +     </listitem>
                     +    </orderedlist>
                     +   </sect3>
+                    +
                     +   <sect3>
                     +    <title>Adversary Capabilities - Positioning</title>
                     +    <para>
                     +The adversary can position themselves at a number of different locations in
                     +order to execute their attacks.
                     +    </para>
                     +    <orderedlist>
                     +     <listitem><command>Exit Node or Upstream Router</command>
                     +     <para>
                     +The adversary can run exit nodes, or alternatively, they may control routers
                     +upstream of exit nodes. Both of these scenarios have been observed in the
                     +wild.
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Adservers and/or Malicious Websites</command>
                     +     <para>
                     +The adversary can also run websites, or more likely, they can contract out
                     +ad space from a number of different adservers and inject content that way. For
                     +some users, the adversary may be the adservers themselves. It is not
                     +inconceivable that adservers may try to subvert or reduce a user's anonymity
                     +through Tor for marketing purposes.
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Local Network/ISP/Upstream Router</command>
                     +     <para>
                     +The adversary can also inject malicious content at the user's upstream router
                     +when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
                     +activity.
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Physical Access</command>
                     +     <para>
                     +Some users face adversaries with intermittent or constant physical access.
                     +Users in Internet cafes, for example, face such a threat. In addition, in
                     +countries where simply using tools like Tor is illegal, users may face
                     +confiscation of their computer equipment for excessive Tor usage or just
                     +general suspicion.
                     +     </para>
                     +     </listitem>
                     +    </orderedlist>
                     +   </sect3>
+                    +
                     +   <sect3>
                     +    <title>Adversary Capabilities - Attacks</title>
                     +    <para>
                     +The adversary can perform the following attacks from a number of different
                     +positions to accomplish various aspects of their goals.
                     +    </para>
                     +    <orderedlist>
                     +     <listitem><command>Inserting Javascript</command>
                     +     <para>
                     +Javascript allows the adversary the opportunity to accomplish a number of
                     +their goals. If not properly disabled, Javascript event handlers and timers
                     +can cause the browser to perform network activity after Tor has been disabled,
                     +thus allowing the adversary to correlate Tor and Non-Tor activity. Javascript
                     +also allows the adversary to execute <ulink
                     +url="http://gemal.dk/browserspy/css.html">history disclosure attacks</ulink>:
                     +to query the history via the different attributes of 'visited' links. Finally,
                     +Javascript can be used to query the user's timezone via the
                     +<function>Date()</function> object, and to reduce the anonymity set by querying
                     +the <function>navigator</function> object for operating system, CPU, and user
                     +agent information.
                     +     </para>
                     +     </listitem>
+                    +
                     +     <listitem><command>Inserting Plugins</command>
                     +     <para>
+                    +
                     +Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
                     +capable of performing network activity that the author has
                     +investigated is also capable of performing network activity independent of
                     +browser proxy settings - and often independent of its own proxy settings.
                     +In addition, plugins can be used to store unique identifiers that are more
                     +difficult to clear than standard cookies.
                     +<ulink url="http://epic.org/privacy/cookies/flash.html">Flash-based
                     +cookies</ulink> fall into this category, but there are likely numerous other
                     +examples.
+                    +
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Inserting CSS</command>
                     +     <para>
+                    +
                     +CSS can also be used to correlate Tor and Non-Tor activity, via the usage of
                     +<ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">CSS
                     +popups</ulink> - essentially CSS-based event handlers that fetch content via
                     +CSS's onmouseover attribute. If these popups are allowed to perform network
                     +activity in a different Tor state than they were loaded in, they can easily
                     +correlate Tor and Non-Tor activity and reveal a user's IP address. In
                     +addition, CSS can also be used without Javascript to perform <ulink
                     +url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only history disclosure
                     +attacks</ulink>.
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Read and insert cookies</command>
                     +     <para>
+                    +
                     +An adversary in a position to perform MITM content alteration can inject
                     +document content elements to both read and inject cookies for
                     +arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
                     +sort of <ulink url="http://seclists.org/bugtraq/2007/Aug/0070.html">active
                     +sidejacking</ulink>.
+                    +
                     +     </para>
                     +     </listitem>
                     +     <listitem><command>Create arbitrary cached content</command>
                     +     <para>
+                    +
                     +Likewise, the browser cache can also be used to <ulink
                     +url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
                     +identifiers</ulink>. Since by default the cache has no same-origin policy,
                     +these identifiers can be read by any domain, making them an ideal target for
                     +adserver-class adversaries.
+                    +
                     +     </para>
                     +     </listitem>
                     +     <listitem id="fingerprinting"><command>Fingerprint users based on browser
                     +attributes</command>
                     +<para>
+                    +
                     +There is an absurd amount of information available to websites via attributes
                     +of the browser. This information can be used to reduce anonymity set, or even
                     +<ulink url="http://0x000000.com/index.php?i=520&amp;bin=1000001000">uniquely
                     +fingerprint individual users</ulink>. </para>
                     +<para>
                     +For illustration, let's perform a
                     +back-of-the-envelope calculation on the number of anonymity sets for just the
                     +resolution information available in the <ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
                     +<ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>
                     +objects. Browser window resolution information provides something like
                     +(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
                     +information contributes about another factor of 5 (for about 5 resolutions in
                     +typical use). In addition, the dimensions and position of the desktop taskbar
                     +are available, which can reveal hints on OS information. This boosts the count
                     +by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
                     +and Gnome, and None). Subtracting the browser content window
                     +size from the browser outer window size provide yet more information.
                     +Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
                     +2<superscript>3</superscript>=8). Interface effects such as titlebar fontsize
                     +and window manager settings gives a factor of about 9 (say 3 common font sizes
                     +for the titlebar and 3 common sizes for browser GUI element fonts).
                     +Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
                     +2<superscript>29</superscript>, or a 29 bit identifier based on resolution
                     +information alone. </para>
+                    +
                     +<para>
+                    +
                     +Of course, this space is non-uniform and prone to incremental changes.
                     +However, if a bit vector space consisting of the above extracted attributes
                     +were used instead of the hash approach from <ulink
                     +url="http://0x000000.com/index.php?i=520&amp;bin=1000001000">The Hacker
                     +Webzine article above</ulink>, minor changes in browser window resolution will
                     +no longer generate totally new identifiers.
+                    +
                     +</para>
                     +<para>
+                    +
                     +To add insult to injury, <ulink
                     +url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
                     +attacks</ulink> mean that each and every extension on <ulink
                     +url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
                     +to that 2<superscript>29</superscript>. With hundreds of popular extensions
                     +and thousands of extensions total, it is easy to see that this sort of
                     +information is an impressively powerful identifier if used properly by a
                     +competent and determined adversary such as an ad network.  Again, a
                     +nearest-neighbor bit vector space approach here would also gracefully handle
                     +incremental changes to installed extensions.
+                    +
                     +</para>
+                    +
                     +     </listitem>
                     +     <listitem><command>Remotely or locally exploit browser and/or
                     +OS</command>
                     +     <para>
                     +Last, but definitely not least, the adversary can exploit either general
                     +browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
                     +install malware and surveillance software. An adversary with physical access
                     +can perform similar actions. Regrettably, this last attack capability is
                     +outside of Torbutton's ability to defend against, but it is worth mentioning
                     +for completeness.
                     +     </para>
                     +     </listitem>
                     +    </orderedlist>
                     +   </sect3>
+                    +
                     +  </sect2>
+                    +
                     +  <sect2 id="requirements">
                     +   <title>Torbutton Requirements</title>
                     +<note>
+                    +
                     +Since many settings satisfy multiple requirements, this design document is
                     +organized primarily by Torbutton components and settings. However, if you are
                     +the type that would rather read the document from the requirements
                     +perspective, it is in fact possible to search for each of the following
                     +requirement phrases in the text to find the relevant features that help meet
                     +that requirement.
+                    +
                     +</note>
                     +   <para>
+                    +
                     +From the above Adversary Model, a number of requirements become clear.
+                    +
                     +   </para>
+                    +
                     +<orderedlist>
                     +<!-- These aren't really commands.. But it's the closest I could find in an
                     +acceptable style.. Don't really want to make my own stylesheet -->
                     + <listitem id="proxy"><command>Proxy Obedience</command>
                     + <para>The browser
                     +MUST NOT bypass Tor proxy settings for any content.</para></listitem>
                     + <listitem id="isolation"><command>Network Isolation</command>
                     + <para>Pages MUST NOT perform any network activity in a Tor state different
                     + from the state they were originally loaded in.</para></listitem>
                     + <listitem id="state"><command>State Separation</command>
                     + <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
                     + one Tor state MUST NOT be accessible via the network in
                     + another Tor state.</para></listitem>
                     + <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
                     +the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
                     +users whose network fingerprint does not obviously betray the fact that they
                     +are using Tor. This should extend to the browser as well - Torbutton MUST NOT
                     +reveal its presence while Tor is disabled.</para></listitem>
                     + <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
                     + in memory beyond the duration of one Tor toggle.</para></listitem>
                     + <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
                     + timezone or locale via Tor.</para></listitem>
                     + <listitem id="setpreservation"><command>Anonymity Set
                     +Preservation</command><para>The browser SHOULD NOT leak any other anonymity set reducing information
                     + (such as user agent, extension presence, and resolution information)
                     +automatically via Tor. The assessment of the attacks above should make it clear
                     +that anonymity set reduction is a very powerful method of tracking and
                     +eventually identifying anonymous users.
                     +</para></listitem>
                     + <listitem id="updates"><command>Update Safety</command><para>The browser
                     +SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
                     + <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
                     + enable the user to switch between a number of different proxies. It MUST
                     + provide full Tor protection in the event a third-party proxy switcher has
                     + enabled the Tor proxy settings.</para></listitem>
                     +</orderedlist>
                     +  </sect2>
                     +  <sect2 id="layout">
                     +   <title>Extension Layout</title>
+                    +
                     +<para>Firefox extensions consist of two main categories of code: 'Components' and
                     +'Chrome'. Components are a fancy name for classes that implement a given
                     +interface or interfaces. In Firefox, components <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/creatingcomps.html">can be
                     +written</ulink> in C++,
                     +Javascript, or a mixture of both. Components have two identifiers: their
                     +'<ulink
                     +url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
                     +ID</ulink>' (a human readable path-like string), and their '<ulink
                     +url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
                     +ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
                     +'Interface ID'. It is possible to 'hook' system components - to reimplement
                     +their interface members with your own wrappers - but only if the rest of the
                     +browser refers to the component by its Contract ID. If the browser refers to
                     +the component by Class ID, it bypasses your hooks in that use case.
                     +Technically, it may be possible to hook Class IDs by unregistering the
                     +original component, and then re-registering your own, but this relies on
                     +obsolete and deprecated interfaces and has proved to be less than
                     +stable.</para>
+                    +
                     +<para>'Chrome' is a combination of XML and Javascript used to describe a window.
                     +Extensions are allowed to create 'overlays' that are 'bound' to existing XML
                     +window definitions, or they can create their own windows. The DTD for this XML
                     +is called <ulink
                     +url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
                     +  </sect2>
                     +</sect1>
                     +<sect1>
                     +  <title>Components</title>
                     +  <para>
+                    +
                     +Torbutton installs components for two purposes: hooking existing components to
                     +reimplement their interfaces; and creating new components that provide
                     +services to other pieces of the extension.
+                    +
                     +  </para>
+                    +
                     +  <sect2>
                     +   <title>Hooked Components</title>
+                    +
                     +<para>Torbutton makes extensive use of Contract ID hooking, and implements some
                     +of its own standalone components as well.  Let's discuss the hooked components
                     +first.</para>
+                    +
                     +<sect3 id="sessionstore">
                     + <title><ulink
                     +url="http://developer.mozilla.org/en/docs/nsISessionStore">@mozilla.org/browser/sessionstore;1</ulink> -
                     +<ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore2.js">components/nsSessionStore2.js</ulink>
                     +and <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.js">components/nsSessionStore3.js</ulink></title>
+                    +
                     +<para>These components address the <link linkend="disk">Disk Avoidance</link>
                     +requirements of Torbutton. As stated in the requirements, Torbutton needs to
                     +prevent Tor tabs from being written to disk by the Firefox session store for a
                     +number of reasons, primary among them is the fact that Firefox can crash at
                     +any time, and a restart can cause you to fetch tabs in the incorrect Tor
                     +state.</para>
+                    +
                     +<para>These components illustrate a complication with Firefox hooking: you can
                     +only hook member functions of a class if they are published in an
                     +interface that the class implements. Unfortunately, the sessionstore has no
                     +published interface that is amenable to disabling the writing out of Tor tabs
                     +in specific. As such, Torbutton had to include the <emphasis>entire</emphasis>
                     +nsSessionStore from both Firefox 2 and Firefox 3,
                     +with a couple of modifications to prevent tabs that were loaded with Tor
                     +enabled from being written to disk, and some version detection code to
                     +determine which component to load. The <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/nsSessionStore3.diff">diff against the original session
                     +store</ulink> is included in the SVN repository.</para>
                     +</sect3>
                     +<sect3>
                     +<title><ulink
                     +url="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js">@mozilla.org/browser/sessionstartup;1</ulink> -
                     +    <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/crash-observer.js">components/crash-observer.js</ulink></title>
+                    +
                     +<para>This component wraps the Firefox Session Startup component that is in
                     +charge of <ulink
                     +url="http://developer.mozilla.org/en/docs/Session_store_API">restoring saved
                     +sessions</ulink>. The wrapper's only job is to intercept the
                     +<function>doRestore()</function> function, which is called by Firefox if it is determined that the
                     +browser crashed and the session needs to be restored. The wrapper notifies the
                     +Torbutton chrome that the browser crashed by setting the pref
                     +<command>extensions.torbutton.crashed</command>, or that it is a normal
                     +startup via the pref <command>extensions.torbutton.noncrashed</command>. The Torbutton Chrome <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver">listens for a
                     +preference change</ulink> for this value and then does the appropriate cleanup. This
                     +includes setting the Tor state to the one the user selected for crash recovery
                     +in the preferences window (<command>extensions.torbutton.restore_tor</command>), and
                     +restoring cookies for the corresponding cookie jar, if it exists.</para>
+                    +
                     +<para>By performing this notification, this component assists in the
                     +<link linkend="proxy">Proxy Obedience</link>, and <link
                     +linkend="isolation">Network Isolation</link> requirements.
                     +</para>
+                    +
+                    +
                     +</sect3>
                     +<sect3>
                     +<title><ulink
                     +url="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html">@mozilla.org/browser/global-history;2</ulink>
                     +- <ulink
                     +  url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
+                    +
                     +<para>This component was contributed by <ulink
                     +url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
                     +CSS and Javascript-based methods of history disclosure. The global-history
                     +component is what is used by Firefox to determine if a link was visited or not
                     +(to apply the appropriate style to the link). By hooking the <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_isVisited">isVisited</ulink>
                     +and <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIGlobalHistory2.html#method_addURI">addURI</ulink>
                     +methods, Torbutton is able to selectively prevent history items from being
                     +added or being displayed as visited, depending on the Tor state and the user's
                     +preferences.
                     +</para>
                     +<para>
                     +This component helps satisfy the <link linkend="state">State Separation</link>
                     +and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
                     +</para>
                     +</sect3>
                     +</sect2>
                     +<sect2>
                     +<title>New Components</title>
+                    +
                     +<para>Torbutton creates four new components that are used throughout the
                     +extension. These components do not hook any interfaces, nor are they used
                     +anywhere besides Torbutton itself.</para>
+                    +
                     +<sect3>
                     +<title><ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cookie-jar-selector.js">@stanford.edu/cookie-jar-selector;2
                     +- components/cookie-jar-selector.js</ulink></title>
+                    +
                     +<para>The cookie jar selector (also based on code from <ulink
                     +url="http://www.collinjackson.com/">Collin
                     +Jackson</ulink>) is used by the Torbutton chrome to switch between
                     +Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
                     +move the current cookies.txt file to the appropriate backup location
                     +(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
                     +into place.</para>
+                    +
                     +<para>
                     +This component helps to address the <link linkend="state">State
                     +Isolation</link> requirement of Torbutton.
                     +</para>
+                    +
                     +</sect3>
                     +<sect3>
                     +<title><ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
                     +- components/torbutton-logger.js</ulink></title>
+                    +
                     +<para>The torbutton logger component allows on-the-fly redirection of torbutton
                     +logging messages to either Firefox stderr
                     +(<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
                     +(<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
                     +available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
                     +change the loglevel on the fly by changing
                     +<command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
                     +</para>
                     +</sect3>
                     +<sect3 id="windowmapper">
+                    +
                     +<title><ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
                     +- components/window-mapper.js</ulink></title>
+                    +
                     +<para>Torbutton tags Firefox <ulink
                     +url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">tabs</ulink> with a special variable that indicates the Tor
                     +state the tab was most recently used under to fetch a page. The problem is
                     +that for many Firefox events, it is not possible to determine the tab that is
                     +actually receiving the event. The Torbutton window mapper allows the Torbutton
                     +chrome and other components to look up a <ulink
                     +url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">browser
                     +tab</ulink> for a given <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDOMWindow.html">HTML content
                     +window</ulink>. It does this by traversing all windows and all browsers, until it
                     +finds the browser with the requested <ulink
                     +url="http://www.xulplanet.com/references/elemref/ref_browser.html#prop_contentWindow">contentWindow</ulink> element. Since the content policy
                     +and page loading in general can generate hundreds of these lookups, this
                     +result is cached inside the component.
                     +</para>
                     +</sect3>
                     +<sect3 id="contentpolicy">
                     +<title><ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1
                     +- components/cssblocker.js</ulink></title>
+                    +
                     +<para>This is a key component to Torbutton's security measures. When Tor is
                     +toggled, Javascript is disabled, and pages are instructed to stop loading.
                     +However, CSS is still able to perform network operations by loading styles for
                     +onmouseover events and other operations. In addition, favicons can still be
                     +loaded by the browser. The cssblocker component prevents this by implementing
                     +and registering an <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html">nsIContentPolicy</ulink>.
                     +When an nsIContentPolicy is registered, Firefox checks every attempted network
                     +request against its <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIContentPolicy.html#method_shouldLoad">shouldLoad</ulink>
                     +member function to determine if the load should proceed. In Torbutton's case,
                     +the content policy looks up the appropriate browser tab using the <link
                     +linkend="windowmapper">window mapper</link>,
                     +and checks that tab's load tag against the current Tor state. If the tab was
                     +loaded in a different state than the current state, the fetch is denied.
                     +Otherwise, it is allowed.</para> This helps to achieve the <link
                     +linkend="isolation">Network
                     +Isolation</link> requirements of Torbutton.
+                    +
                     +<para>In addition, the content policy also blocks website javascript from
                     +<ulink url="http://pseudo-flaw.net/content/tor/torbutton/">querying for
                     +versions and existence of extension chrome</ulink> while Tor is enabled, and
                     +also masks the presence of Torbutton to website javascript while Tor is
                     +disabled. </para>
+                    +
                     +<para>
+                    +
                     +Finally, some of the work that logically belongs to the content policy is
                     +instead handled by the <command>torbutton_http_observer</command> and
                     +<command>torbutton_weblistener</command> in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
                     +Firefox 3 favicon loads, popups, and full page plugins, which for whatever
                     +reason are not passed to the Firefox content policy itself (see Firefox Bugs
                     +<ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and
                     +<ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
+                    +
                     +</para>
+                    +
                     +<!--
                     +FIXME: Hrmm, the content policy doesn't really lend itself well to display
                     +this way.. People looking for this much detail should consult the source.
+                    +
                     +<para>
                     +    <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
                     +    <tgroup cols='5' align='left' colsep='1' rowsep='1'>
                     +       <tbody>
                     +       <row>
                     +         <entry></entry>
                     +         <entry>chrome/resource</entry>
                     +         <entry>a3</entry>
                     +         <entry>a4</entry>
                     +         <entry>a5</entry>
                     +       </row>
                     +       <row>
                     +         <entry>file</entry>
                     +         <entry>b2</entry>
                     +         <entry>b3</entry>
                     +         <entry>b4</entry>
                     +         <entry>b5</entry>
                     +       </row>
                     +       <row>
                     +         <entry>c1</entry>
                     +         <entry>c2</entry>
                     +         <entry>c3</entry>
                     +         <entry>c4</entry>
                     +         <entry>c5</entry>
                     +       </row>
                     +       <row>
                     +         <entry>d1</entry>
                     +         <entry>d2</entry>
                     +         <entry>d3</entry>
                     +         <entry>d4</entry>
                     +         <entry>d5</entry>
                     +       </row>
                     +       </tbody>
                     +       </tgroup>
                     +       </table>
                     +</para>
                     +-->
+                    +
                     +<para>
+                    +
                     +This helps to fulfill both the <link
                     +linkend="setpreservation">Anonymity Set Preservation</link> and the <link
                     +linkend="undiscoverability">Tor Undiscoverability</link> requirements of
                     +Torbutton.</para>
+                    +
                     +</sect3>
                     +</sect2>
                     +</sect1>
                     +<sect1>
                     + <title>Chrome</title>
+                    +
                     +<para>The chrome is where all the torbutton graphical elements and windows are
                     +located. Each window is described as an <ulink
                     +url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
                     +files attached. The scope of these Javascript files is their containing
                     +window.</para>
+                    +
                     +<sect2 id="browseroverlay">
                     +<title>Browser Overlay - <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
+                    +
                     +<para>The browser overlay, torbutton.xul, defines the toolbar button, the status
                     +bar, and events for toggling the button. The overlay code is in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
                     +It contains event handlers for preference update, shutdown, upgrade, and
                     +location change events.</para>
+                    +
                     +<para>The <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/comps/c_docloaderservice1.html">location
                     +change</ulink> <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">webprogress
                     +listener</ulink>, <command>torbutton_weblistener</command> is perhaps the
                     +most important part of the chrome from a security standpoint. It is a <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">web
                     +progress listener</ulink> that handles
                     +receiving an event every time a page load or iframe load occurs. This class
                     +eventually calls down to <function>torbutton_update_tags()</function> and
                     +<function>torbutton_hookdoc()</function>, which apply the browser Tor load state tags, plugin
                     +permissions, and install the Javascript hooks to hook the <ulink
                     +url="http://phrogz.net/objJob/object.asp?id=224">Date</ulink> object and
                     +the <ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window.navigator">navigator</ulink> object (for timezone and platform information,
                     +respectively).</para>
                     +<para>
                     +The browser overlay helps to satisfy a number of Torbutton requirements. These
                     +are better enumerated in each of the Torbutton preferences below. However,
                     +there are also a number of Firefox preferences set in
                     +<function>torbutton_update_status()</function> that aren't governed by any
                     +Torbutton setting. These are:
                     +</para>
                     +<orderedlist>
+                    +
                     + <listitem><ulink
                     +url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
                     +<para>
                     +This pref is set in an attempt to disable the fetching of LiveBookmarks via
                     +Tor. Since users can potentially collect a large amount of live bookmarks to
                     +very personal sites (blogs of friends, wikipedia articles they maintain,
                     +comment feeds of their own blog), it is not possible to cleanly isolate these
                     +fetches and they are simply disabled during Tor usage.
                     +This helps to address the <link
                     +linkend="state">State Separation</link> requirement.
                     +Unfortunately <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
                     +436250</ulink> prevents this from
                     +functioning completely correctly.
                     +</para>
                     +  </listitem>
+                    +
                     + <listitem><ulink
                     +url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
                     + <para>
                     +Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
                     +reads from <command>extensions.torbutton.banned_ports</command>) to the list
                     +of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
                     +and the Tor control port, respectively. This is set for both Tor and Non-Tor
                     +usage, and prevents websites from attempting to do http fetches from these
                     +ports to see if they are open, which addresses the <link
                     +linkend="undiscoverability">Tor Undiscoverability</link> requirement.
                     + </para>
                     + </listitem>
                     + <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
                     + <para>
                     +This setting is currently always disabled. If anyone ever complains saying
                     +that they *want* their browser to be able to send ping notifications to a
                     +page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
                     +my breath. I haven't checked if the content policy is called for pings, but if
                     +not, this setting helps with meeting the <link linkend="isolation">Network
                     +Isolation</link> requirement.
                     + </para>
                     + </listitem>
                     + <listitem><ulink
                     +url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
                     + <para>
                     +Likewise for this setting. I find it hard to imagine anyone who wants to ask
                     +Google in real time if each URL they visit is safe, especially when the list
                     +of unsafe URLs is downloaded anyway. This helps fulfill the <link
                     +linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
                     +browsing history from ending up on Google's disks.
                     + </para>
                     + </listitem>
                     + <listitem><ulink
                     +url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
                     + <para>
                     +Safebrowsing does <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
                     +updates under Firefox 2</ulink>, so it is disabled during Tor usage.
                     +This helps fulfill the <link linkend="updates">Update
                     +Safety</link> requirement. Firefox 3 has the fix for that bug, and so
                     +safebrowsing updates are enabled during Tor usage.
                     + </para>
                     + </listitem>
                     + <listitem><ulink
                     +url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
                     + <para>
                     +If Tor is enabled, we need to prevent random external applications from
                     +launching without at least warning the user. This group of settings only
                     +partially accomplishes this, however. Applications can still be launched via
                     +plugins. The mechanisms for handling this are described under the "Disable
                     +Plugins During Tor Usage" preference. This helps fulfill the <link
                     +linkend="proxy">Proxy Obedience</link> requirement, by preventing external
                     +applications from accessing network resources at the command of Tor-fetched
                     +pages.
                     + </para>
                     +</listitem>
                     +</orderedlist>
                     +</sect2>
                     +<sect2>
                     + <title>Preferences Window - <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
+                    +
                     +<para>The preferences window of course lays out the Torbutton preferences, with
                     +handlers located in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
                     +</sect2>
                     +<sect2>
                     + <title>Other Windows</title>
+                    +
                     +<para>There are additional windows that describe popups for right clicking on
                     +the status bar, the toolbutton, and the about page.</para>
+                    +
                     +</sect2>
                     +</sect1>
+                    +
                     +<sect1>
                     + <title>Toggle Code Path</title>
                     + <para>
+                    +
                     +The act of toggling is connected to <function>torbutton_toggle()</function>
                     +via the <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
                     +and <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/popup.xul">popup.xul</ulink>
                     +overlay files. Most of the work in the toggling process is present in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink>
+                    +
                     +</para>
                     +<para>
+                    +
                     +Toggling is a 3 stage process: Button Click, Proxy Update, and
                     +Settings Update. These stages are reflected in the prefs
                     +<command>extensions.torbutton.tor_enabled</command>,
                     +<command>extensions.torbutton.proxies_applied</command>, and
                     +<command>extensions.torbutton.settings_applied</command>. The reason for the
                     +three stage preference update is to ensure immediate enforcement of <link
                     +linkend="isolation">Network Isolation</link> via the <link
                     +linkend="contentpolicy">content policy</link>. Since the content window
                     +javascript runs on a different thread than the chrome javascript, it is
                     +important to properly convey the stages to the content policy to avoid race
                     +conditions and leakage, especially with <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
                     +409737</ulink> unfixed. The content policy does not allow any network activity
                     +whatsoever during this three stage transition.
+                    +
                     + </para>
                     + <sect2>
                     +  <title>Button Click</title>
                     +  <para>
+                    +
                     +This is the first step in the toggling process. When the user clicks the
                     +toggle button or the toolbar, <function>torbutton_toggle()</function> is
                     +called. This function checks the current Tor status by comparing the current
                     +proxy settings to the selected Tor settings, and then sets the proxy settings
                     +to the opposite state, and sets the pref
                     +<command>extensions.torbutton.tor_enabled</command> to reflect the new state.
                     +It is this proxy pref update that gives notification via the <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIPrefBranch2.html#method_addObserver">pref
                     +observer</ulink>
                     +<command>torbutton_unique_pref_observer</command> to perform the rest of the
                     +toggle.
+                    +
                     +  </para>
                     + </sect2>
                     + <sect2>
                     +  <title>Proxy Update</title>
                     +  <para>
+                    +
                     +When Torbutton receives any proxy change notifications via its
                     +<command>torbutton_unique_pref_observer</command>, it calls
                     +<function>torbutton_set_status()</function> which checks against the Tor
                     +settings to see if the Tor proxy settings match the current settings. If so,
                     +it calls <function>torbutton_update_status()</function>, which determines if
                     +the Tor state has actually changed, and sets
                     +<command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
                     +state value, and ensures that
                     +<command>extensions.torbutton.tor_enabled</command> is also set to the correct
                     +value. This is decoupled from the button click functionalty via the pref
                     +observer so that other addons (such as SwitchProxy) can switch the proxy
                     +settings between multiple proxies.
+                    +
                     +  </para>
                     + </sect2>
                     + <sect2>
                     +  <title>Settings Update</title>
                     +  <para>
+                    +
                     +The next stage is also handled by
                     +<function>torbutton_update_status()</function>. This function sets scores of
                     +Firefox preferences, saving the original values to prefs under
                     +<command>extensions.torbutton.saved.*</command>, and performs the history
                     +clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
                     +end of its work, it sets
                     +<command>extensions.torbutton.settings_applied</command>, which signifies the
                     +completion of the toggle operation to the <link
                     +linkend="contentpolicy">content policy</link>.
+                    +
                     +  </para>
                     + </sect2>
                     +</sect1>
+                    +
                     +<sect1>
                     + <title>Description of Options</title>
+                    +
                     +<para>This section provides a detailed description of Torbutton's options. Each
                     +option is presented as the string from the preferences window, a summary, the
                     +preferences it touches, and the effect this has on the components, chrome, and
                     +browser properties.</para>
                     + <sect2>
                     +  <title>Test Settings</title>
                     +  <para>
                     +This button under the Proxy Settings tab provides a way to verify that the
                     +proxy settings are correct, and actually do route through the Tor network. It
                     +performs this check by issuing an <ulink
                     +url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
                     +for <ulink
                     +url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
                     +This is a special page that returns very simple, yet well-formed XHTML that
                     +Torbutton can easily inspect for a hidden link with an id of
                     +<command>TorCheckResult</command> and a target of <command>success</command>
                     +or <command>failure</command> to indicate if the
                     +user hit the page from a Tor IP, a non-Tor IP. This check is handled in
                     +<function>torbutton_test_settings()</function> in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/torbutton.js">torbutton.js</ulink>.
                     +Presenting the results to the user is handled by the <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.xul">preferences
                     +window</ulink>
                     +callback <function>torbutton_prefs_test_settings()</function> in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/preferences.js">preferences.js</ulink>.
+                    +
                     +  </para>
                     + </sect2>
                     + <sect2 id="plugins">
                     +  <title>Disable plugins on Tor Usage (crucial)</title>
+                    +
                     + <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
+                    +
                     + <para>Enabling this preference causes the above mentioned Torbutton chrome web progress
                     + listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
                     + plugins via the browser <ulink
                     + url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html">docShell</ulink>
                     + attribute <command>allowPlugins</command>. These flags are set every time a new window is
                     + created (<function>torbutton_tag_new_browser()</function>), every time a web
                     +load
                     +event occurs
                     + (<function>torbutton_update_tags()</function>), and every time the tor state is changed
                     + (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
                     + prevented from loading by the content policy in <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
                     + enabled and this option is set.
                     + </para>
+                    +
                     + <para>Even all this turns out to be insufficient if the user directly
                     + clicks on a plugin-handled mime-type. <ulink
                     +url="http://www.janusvm.com/goldy/pdf/">In this case</ulink> (and also <ulink
                     +url="http://www.janusvm.com/goldy/side-channels/frames/">this
                     +one</ulink>), the browser decides that
                     + maybe it should ignore all these other settings and load the plugin anyways,
                     + because maybe the user really did want to load it (never mind this same
                     + load-style could happen automatically  with meta-refresh or any number of
                     + other ways..). To handle these cases, Torbutton stores a list of plugin-handled
                     + mime-types, and sets the pref
                     +<command>plugin.disable_full_page_plugin_for_types</command> to this list.
                     +Additionally, (since nothing can be assumed when relying on Firefox
                     +preferences and internals) if it detects a load of one of them from the web progress
                     + listener, it cancels the request, tells the associated DOMWindow
                     +to stop loading, clears the document, AND throws an exception. Anything short
                     +of all this and
                     + the plugin managed to find some way to load.
                     + </para>
+                    +
                     + <para>
                     + All this could be avoided, of course, if Firefox would either <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
                     + allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
                     + loads either <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
                     + not very encouraging.
                     + </para>
                     + <para>
+                    +
                     +Since most plugins completely ignore browser proxy settings, the actions
                     +performed by this setting are crucial to satisfying the <link
                     +linkend="proxy">Proxy Obedience</link> requirement.
+                    +
                     + </para>
                     +</sect2>
                     +<sect2>
                     + <title>Isolate Dynamic Content to Tor State (crucial)</title>
+                    +
                     + <para>Option: <command>extensions.torbutton.isolate_content</command></para>
+                    +
                     +<para>Enabling this preference is what enables the <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
                     +mentioned above, and causes it to block content load attempts in pages an
                     +opposite Tor state from the current state. Freshly loaded <ulink
                     +url="http://www.xulplanet.com/references/elemref/ref_tabbrowser.html">browser
                     +tabs</ulink> are tagged
                     +with a <command>__tb_load_state</command> member in
                     +<function>torbutton_update_tags()</function> and this
                     +value is compared against the current tor state in the content policy.</para>
+                    +
                     +<para>It also kills all Javascript in each page loaded under that state by
                     +toggling the <command>allowJavascript</command> <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIDocShell.html">docShell</ulink> property, and issues a
                     +<ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebNavigation.html#method_stop">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
                     +equivalent of hitting the STOP button).</para>
+                    +
                     +<para>
+                    +
                     +Unfortunately, <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
                     +409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
                     +all event handlers, and event handlers registered with <ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
                     +are still able to execute. The <link linkend="contentpolicy">Torbutton Content
                     +Policy</link> should prevent such code from performing network activity within
                     +the current tab, but activity that happens via a popup window or via a
                     +Javascript redirect can still slip by. For this reason, Torbutton blocks
                     +popups by checking for a valid <ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
                     +attribute in <function>torbutton_check_progress()</function>. If the window
                     +has an opener from a different Tor state, its load is blocked. The content
                     +policy also takes similar action to prevent Javascript redirects. This also
                     +has the side effect/feature of preventing the user from following any links
                     +from a page loaded in an opposite Tor state.
+                    +
                     +</para>
+                    +
                     +<para>
                     +This setting is responsible for satisfying the <link
                     +linkend="isolation">Network Isolation</link> requirement.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2 id="jshooks">
+                    +
                     +<title>Hook Dangerous Javascript (crucial)</title>
+                    +
                     + <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
+                    +
                     +<para>This setting enables injection of the <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/chrome/content/jshooks.js">Javascript
                     +hooking code</ulink>. Javascript is injected into
                     +pages to hook the <ulink url="http://phrogz.net/objJob/object.asp?id=224">Date
                     +class</ulink> to mask your timezone. This is done in the chrome in
                     +<function>torbutton_hookdoc()</function>, which is called ultimately by both the
                     +<ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIWebProgressListener.html">webprogress
                     +listener</ulink> <command>torbutton_weblistener</command> and the <link
                     +linkend="contentpolicy">content policy</link> (the latter being a hack to handle
                     +javascript: urls). This behavior helps to satisfy the <link
                     +linkend="location">Location Neutrality</link> requirement.
+                    +
                     +</para>
                     +<para>
+                    +
                     +In addition, this setting also hooks various resolution properties of the
                     +<ulink url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink>,
                     +<ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>,
                     +and <ulink
                     +url="http://developer.mozilla.org/en/docs/DOM:window.navigator">window.navigator</ulink>
                     +to mask window size information and user agent properties not handled by the
                     +standard Firefox user agent override settings. The resolution hooks
                     +effectively make the Firefox browser window appear to websites as if the renderable area
                     +takes up the entire desktop, has no toolbar or other GUI element space, and
                     +the desktop itself has no toolbars.
                     +These hooks drastically reduce the amount of information available to do <link
                     +linkend="fingerprinting">anonymity set reduction attacks</link> and help to
                     +meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
                     +requirements.
+                    +
                     +</para>
                     +</sect2>
                     +<sect2>
                     +<title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
+                    +
                     + <para>Option: <command>extensions.torbutton.resize_windows</command></para>
+                    +
                     +<para>
+                    +
                     +This option drastically cuts down on the number of distinct anonymity sets
                     +that divide the Tor web userbase. Without this setting, the dimensions for a
                     +typical browser window range from 600-1200 horizontal pixels and 400-1000
                     +vertical pixels, or about 600x600 = 360000 different sets. Resizing the
                     +browser window to multiples of 50 on each side reduces the number of sets by
                     +50^2, bringing the total number of sets to 144. Of course, the distribution
                     +among these sets are not uniform, but scaling by 50 will improve the situation
                     +due to this non-uniformity for users in the less common resolutions.
                     +Obviously the ideal situation would be to lie entirely about the browser
                     +window size, but this will likely cause all sorts of rendering issues, and is
                     +also not implementable in a foolproof way from extension land.
+                    +
                     +</para>
                     +<para>
+                    +
                     +The implementation of this setting is spread across a couple of different
                     +locations in the Torbutton javascript <link linkend="browseroverlay">browser
                     +overlay</link>. Since resizing minimized windows causes them to be restored,
                     +and since maximized windows remember their previous size to the pixel, windows
                     +must be resized before every document load (at the time of browser tagging)
                     +via <function>torbutton_check_round()</function>, called by
                     +<function>torbutton_update_tags()</function>. To prevent drift, the extension
                     +tracks the original values of the windows and uses this to perform the
                     +rounding on document load. In addition, to prevent the user from resizing a
                     +window to a non-50px multiple, a resize listener
                     +(<function>torbutton_do_resize()</function>) is installed on every new browser
                     +window to record the new size and round it to a 50px multiple while Tor is
                     +enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
                     +are set. This ensures that there is no discrepancy between the 50 pixel cutoff
                     +and the actual renderable area of the browser (so that it is not possible to
                     +infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
+                    +
                     +</para>
                     +<para>
                     +This setting helps to meet the <link
                     +linkend="setpreservation">Anonymity Set Preservation</link> requirements.
                     +</para>
                     +</sect2>
                     +<sect2>
                     +<title>Disable Updates During Tor (recommended)</title>
+                    +
                     +  <para>Option: <command>extensions.torbutton.no_updates</command></para>
+                    +
                     +  <para>This setting causes Torbutton to disable the four <ulink
                     +url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
                     +update settings</ulink> during Tor
                     +  usage: <command>extensions.update.enabled</command>,
                     +<command>app.update.enabled</command>,
                     +  <command>app.update.auto</command>, and
                     +<command>browser.search.update</command>.  These prevent the
                     +  browser from updating extensions, checking for Firefox upgrades, and
                     +  checking for search plugin updates while Tor is enabled.
                     +  </para>
                     +<para>
                     +This setting satisfies the <link
                     +linkend="updates">Update Safety</link> requirement.
                     +</para>
                     +</sect2>
                     +<sect2>
+                    +
                     +<title>Disable Search Suggestions during Tor (recommended)</title>
+                    +
                     +  <para>Option: <command>extensions.torbutton.no_search</command></para>
+                    +
                     +<para>
                     +This setting causes Torbutton to disable <ulink
                     +url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
                     +during Tor usage.
                     +This governs if you get Google search suggestions during Tor
                     +usage. Your Google cookie is transmitted with google search suggestions, hence
                     +this is recommended to be disabled.
+                    +
                     +</para>
                     +<para>
                     +While this setting doesn't satisfy any Torbutton requirements, the fact that
                     +cookies are transmitted for partially typed queries does not seem desirable
                     +for Tor usage.
                     +</para>
                     +</sect2>
                     +<sect2>
                     +<title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
                     +  <para>Option:
                     +   <simplelist>
                     +   <member><command>extensions.torbutton.block_tor_file_net</command></member>
                     +   <member><command>extensions.torbutton.block_nontor_file_net</command></member>
                     +   </simplelist>
                     +  </para>
+                    +
                     +<para>
+                    +
                     +These settings prevent file urls from performing network operations during the
                     +respective Tor states. Firefox 2's implementation of same origin policy allows
                     +file urls to read and <ulink
                     +url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
                     +arbitrary files from the local filesystem</ulink> to arbitrary websites. To
                     +make matters worse, the 'Content-Disposition' header can be injected
                     +arbitrarily by exit nodes to trick users into running arbitrary html files in
                     +the local context. These preferences cause the <link
                     +linkend="contentpolicy">content policy</link> to block access to any network
                     +resources from File urls during the appropriate Tor state.
+                    +
                     +</para>
                     +<para>
+                    +
                     +This preference helps to ensure Tor's <link linkend="isolation">Network
                     +Isolation</link> requirement, by preventing file urls from executing network
                     +operations in opposite Tor states. Also, allowing pages to submit arbitrary
                     +files to arbitrary sites just generally seems like a bad idea.
+                    +
                     +</para>
                     +</sect2>
                     +<sect2>
+                    +
                     +<title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
+                    +
                     +  <para>Options:
                     +   <simplelist>
                     +   <member><command>extensions.torbutton.close_nontor</command></member>
                     +   <member><command>extensions.torbutton.close_tor</command></member>
                     +   </simplelist>
                     +  </para>
+                    +
                     +<para>
+                    +
                     +These settings cause Torbutton to enumerate through all windows and close all
                     +tabs in each window for the appropriate Tor state. This code can be found in
                     +<function>torbutton_update_status()</function>.  The main reason these settings
                     +exist is as a backup mechanism in the event of any Javascript or content policy
                     +leaks due to <ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
                     +409737</ulink>.  Torbutton currently tries to block all Javascript network
                     +activity via the content policy, but until that bug is fixed, there is some
                     +risk that there are alternate ways to bypass the policy. This option is
                     +available as an extra assurance of <link linkend="isolation">Network
                     +Isolation</link> for those who would like to be sure that when Tor is toggled
                     +all page activity has ceased. It also serves as a potential future workaround
                     +in the event a content policy failure is discovered, and provides an additional
                     +level of protection for the <link linkend="disk">Disk Avoidance</link>
                     +protection so that browser state is not sitting around waiting to be swapped
                     +out longer than necessary.
+                    +
                     +</para>
                     +<para>
                     +While this setting doesn't satisfy any Torbutton requirements, the fact that
                     +cookies are transmitted for partially typed queries does not seem desirable
                     +for Tor usage.
                     +</para>
                     +</sect2>
+                    +
                     +<sect2>
                     +<title>Isolate Access to History navigation to Tor state (crucial)</title>
                     +  <para>Option: <command>extensions.torbutton.block_js_history</command></para>
                     +  <para>
                     +This setting determines if Torbutton installs an <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistoryListener.html">nsISHistoryListener</ulink>
                     +attached to the <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html">sessionHistory</ulink> of
                     +of each browser's <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/comps/c_webshell1.html">webNavigatator</ulink>.
                     +The nsIShistoryListener is instantiated with a reference to the containing
                     +browser window and blocks the back, forward, and reload buttons on the browser
                     +navigation bar when Tor is in an opposite state than the one to load the
                     +current tab. In addition, Tor clears the session history during a new document
                     +load if this setting is enabled.
+                    +
                     +  </para>
                     +  <para>
+                    +
                     +This is marked as a crucial setting in part
                     +because Javascript access to the history object is indistinguishable from
                     +user clicks, and because
                     +<ulink
                     +url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
                     +409737</ulink> allows javascript to execute in opposite Tor states, javascript
                     +can issue reloads after Tor toggle to reveal your original IP. Even without
                     +this bug, however, Javascript is still able to access previous pages in your
                     +session history that may have been loaded under a different Tor state, to
                     +attempt to correlate your activity.
+                    +
                     +   </para>
                     +   <para>
+                    +
                     +This setting helps to fulfill Torbutton's <link linkend="state">State
                     +Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
                     +requirements.
+                    +
                     +   </para>
                     +</sect2>
+                    +
+                    +
                     +<sect2>
                     +<title>History Access Settings</title>
+                    +
                     +  <para>Options:
                     +  <simplelist>
                     +   <member><command>extensions.torbutton.block_thread</command></member>
                     +   <member><command>extensions.torbutton.block_nthread</command></member>
                     +   <member><command>extensions.torbutton.block_thwrite</command></member>
                     +   <member><command>extensions.torbutton.block_nthwrite</command></member>
                     +  </simplelist>
                     +  </para>
+                    +
                     +<para>These four settings govern the behavior of the <ulink
                     +url="https://tor-svn.freehaven.net/svn/torbutton/trunk/src/components/ignore-history.js">components/ignore-history.js</ulink>
                     +history blocker component mentioned above. By hooking the browser's view of
                     +the history itself via the <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/comps/c_browserglobalhistory2.html">mozilla.org/browser/global-history;2</ulink>
                     +component, this mechanism defeats all document-based <ulink
                     +url="http://gemal.dk/browserspy/css.html">history disclosure
                     +attacks</ulink>, including <ulink
                     +url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
                     +</para>
                     +<para>
+                    +
                     +On Firefox 3, the history write settings also govern if Torbutton sets
                     +<command>browser.history_expire_days</command> to 0 on the appropriate Tor
                     +state, which <ulink
                     +url="http://developer.mozilla.org/en/docs/index.php?title=nsINavHistoryService#Attributes">should
                     +disable</ulink> all <ulink
                     +url="http://developer.mozilla.org/en/docs/Places">Places</ulink> database
                     +writes.
+                    +
                     +</para>
                     +<para>
                     +This setting helps to satisfy the <link
                     +linkend="state">State Separation</link> and <link
                     +linkend="disk">Disk Avoidance</link> requirements.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2>
+                    +
                     +<title>Clear History During Tor Toggle (optional)</title>
+                    +
                     +<para>Option: <command>extensions.torbutton.clear_history</command></para>
+                    +
                     +<para>This setting governs if Torbutton calls
                     +<ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsIBrowserHistory.html#method_removeAllPages">nsIBrowserHistory.removeAllPages</ulink>
                     +and <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsISHistory.html#method_PurgeHistory">nsISHistory.PurgeHistory</ulink>
                     +for each tab on Tor toggle.</para>
                     +<para>
                     +This setting is an optional way to help satisfy the <link
                     +linkend="state">State Separation</link> requirement.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2>
+                    +
                     +<title>Block Password+Form saving during Tor/Non-Tor</title>
+                    +
                     +<para>Options:
                     +  <simplelist>
                     +  <member><command>extensions.torbutton.block_tforms</command></member>
                     +  <member><command>extensions.torbutton.block_ntforms</command></member>
                     +  </simplelist>
                     +  </para>
+                    +
                     +<para>These settings govern if Torbutton disables
                     +<command>browser.formfill.enable</command>
                     +and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
                     +Since form fields can be read at any time by Javascript, this setting is a lot
                     +more important than it seems.
                     +</para>
+                    +
                     +<para>
                     +This setting helps to satisfy the <link
                     +linkend="state">State Separation</link> and <link
                     +linkend="disk">Disk Avoidance</link> requirements.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2>
                     +  <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
+                    +
                     +  <para>Option: <command>extensions.torbutton.clear_cache</command>
                     +  </para>
+                    +
                     +<para>This option causes Torbutton to call <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsICacheService.html#method_evictEntries">nsICacheService.evictEntries(0)</ulink>
                     +on Tor toggle to remove all entries from the cache. In addition, this setting
                     +causes Torbutton to set <ulink
                     +url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
                     +</para>
                     +<para>
                     +This setting helps to satisfy the <link
                     +linkend="state">State Separation</link> and <link
                     +linkend="disk">Disk Avoidance</link> requirements.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2>
                     +  <title>Block disk and memory cache during Tor</title>
+                    +
                     +<para>Option: <command>extensions.torbutton.block_cache</command></para>
+                    +
                     +<para>This setting
                     +causes Torbutton to set <ulink
                     +url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
                     +<ulink
                     +url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
                     +<ulink
                     +url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
                     +</para>
                     +<para>
                     +This setting helps to satisfy the <link
                     +linkend="state">State Separation</link> and <link
                     +linkend="disk">Disk Avoidance</link> requirements.
                     +</para>
+                    +
                     +</sect2>
                     +<sect2>
                     +  <title>Clear Cookies on Tor Toggle</title>
+                    +
                     +<para>Option: <command>extensions.torbutton.clear_cookies</command>
                     +  </para>
+                    +
                     +<para>
+                    +
                     +This setting causes Torbutton to call <ulink
                     +url="http://www.xulplanet.com/references/xpcomref/ifaces/nsICookieManager.html#method_removeAll">nsICookieManager.removeAll()</ulink> on
                     +every Tor toggle. In addition, this sets <ulink
                     +url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
                     +to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
                     +which prevents them from being written to disk.
+                    +
                     +</para>
                     +<para>
                     +This setting helps to satisfy the <link
                     +linkend="state">State Separation</link> and <link
                     +linkend="disk">Disk Avoidance</link> requirements.
                     +</para>
+                    +

1	1	new file mode 100644
2	2	Binary files /dev/null and b/torbutton/design/MozillaBrownBag.odp differ

Inital move of torbutton website into website trunk.