tor-webwml.git

@@ -0,0 +1 @@

+xsltproc  --output index.html.en  --stringparam section.autolabel.max.depth 2 --stringparam  section.autolabel 1 /usr/share/sgml/docbook/xsl-stylesheets--1.73.2/xhtml/docbook.xsl design.xml 

@@ -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&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