[tor-commits] [torbutton/master] Reorganize, document observers, and fix gitweb urls.
mikeperry at torproject.org
mikeperry at torproject.org
Mon Apr 4 19:46:01 UTC 2011
commit 6adaae4b281932e73a923d9d56c72de235dcf8a8
Author: Mike Perry <mikeperry-git at fscked.org>
Date: Sun Apr 3 18:26:07 2011 -0700
Reorganize, document observers, and fix gitweb urls.
I probably should have broken these into separate commits. Too late now.
---
website/design/design.xml | 595 +++++++++++++++++++++++++++------------------
1 files changed, 356 insertions(+), 239 deletions(-)
diff --git a/website/design/design.xml b/website/design/design.xml
index b137caf..e97c07c 100644
--- a/website/design/design.xml
+++ b/website/design/design.xml
@@ -11,7 +11,7 @@
<address><email>mikeperry.fscked/org</email></address>
</affiliation>
</author>
- <pubdate>Mar 25 2011</pubdate>
+ <pubdate>Apr 3 2011</pubdate>
</articleinfo>
<sect1>
@@ -19,7 +19,7 @@
<para>
This document describes the goals, operation, and testing procedures of the
-Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
+Torbutton Firefox extension. It is current as of Torbutton 1.3.2.
</para>
<sect2 id="adversary">
@@ -219,6 +219,7 @@ adserver-class adversaries.
</para>
</listitem>
+
<listitem id="fingerprinting"><command>Fingerprint users based on browser
attributes</command>
<para>
@@ -234,7 +235,11 @@ 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
+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
@@ -252,14 +257,25 @@ 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://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">The Hacker
-Webzine article above</ulink>, minor changes in browser window resolution will
-no longer generate totally new identifiers.
+Of course, this space is non-uniform in user density and prone to incremental
+changes. The <ulink
+url="https://wiki.mozilla.org/Fingerprinting#Data">Panopticlick study
+done</ulink> by the EFF attempts to measure the actual entropy - the number of
+identifying bits of information encoded in browser properties. Their result
+data is definitely useful, and the metric is probably the appropriate one for
+determining how identifying a particular browser property is. However, some
+quirks of their study means that they do not extract as much information as
+they could from display information: they only use desktop resolution (which
+Torbutton reports as the window resolution) and do not attempt to infer the
+size of toolbars.
</para>
+<!--
+FIXME: This is no longer true. Only certain addons are now discoverable, and
+only if they want to be:
+http://webdevwonders.com/detecting-firefox-add-ons/
+https://developer.mozilla.org/en/Updating_web_applications_for_Firefox_3#section_7
+
<para>
To add insult to injury, <ulink
@@ -274,7 +290,7 @@ 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>
@@ -377,7 +393,7 @@ is called <ulink
url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
</sect2>
</sect1>
-<sect1>
+<sect1 id="components">
<title>Components</title>
<para>
@@ -387,38 +403,13 @@ services to other pieces of the extension.
</para>
- <sect2>
+ <sect2 id="hookedxpcom">
<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://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js">components/nsSessionStore36.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.0, 3.0, 3.5 and 3.6
-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://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff">diff against the original session
-store</ulink> is included in the git repository.</para>
-</sect3>
<sect3 id="appblocker">
<title><ulink
url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1">@mozilla.org/uriloader/external-protocol-service;1
@@ -426,7 +417,7 @@ url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/c
url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1">@mozilla.org/uriloader/external-helper-app-service;1</ulink>,
and <ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1">@mozilla.org/mime;1</ulink>
- <ulink
- url="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
+ url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
<para>
Due to <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink> allowing Firefox 3.x to automatically launch some
@@ -440,37 +431,9 @@ Obedience</link> Requirement.
</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://git.torproject.org/checkout/torbutton/master/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="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">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.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
- <ulink
- url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
+ url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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
@@ -486,14 +449,18 @@ preferences.
</para>
<para>
This component helps satisfy the <link linkend="state">State Separation</link>
-and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
+and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton. It
+is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
+of the <ulink
+url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">built-in
+history protections</ulink>.
</para>
</sect3>
<sect3 id="livemarks">
<title><ulink
url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">@mozilla.org/browser/livemark-service;2</ulink>
- <ulink
- url="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
+ url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
<para>
The <ulink
@@ -518,18 +485,19 @@ Preservation</link> requirements.
extension. These components do not hook any interfaces, nor are they used
anywhere besides Torbutton itself.</para>
-<sect3>
+<sect3 id="cookiejar">
<title><ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/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>
+Tor and Non-Tor cookies. It stores an XML representation of the current
+cookie state in memory and/or on disk. When Tor is toggled, it syncs the
+current cookies to this XML store, and then loads the cookies for the other
+state from the XML store.
+</para>
<para>
This component helps to address the <link linkend="state">State
@@ -539,7 +507,7 @@ Isolation</link> requirement of Torbutton.
</sect3>
<sect3>
<title><ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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
@@ -554,7 +522,7 @@ change the loglevel on the fly by changing
<sect3 id="windowmapper">
<title><ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
- components/window-mapper.js</ulink></title>
<para>Torbutton tags Firefox <ulink
@@ -573,9 +541,43 @@ and page loading in general can generate hundreds of these lookups, this
result is cached inside the component.
</para>
</sect3>
+<sect3>
+ <title><ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">@torproject.org/crash-observer;1</ulink></title>
+ <para>
+
+This component detects when Firefox crashes by altering Firefox prefs during
+runtime and checking for the same values at startup. It <ulink
+url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()">synchronizes
+the preference service</ulink> to ensure the altered prefs are written to disk
+immediately.
+
+ </para>
+</sect3>
+<sect3>
+ <title><ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js">@torproject.org/torbutton-ss-blocker;1</ulink></title>
+ <para>
+
+This component subscribes to the Firefox
+<ulink
+url="https://developer.mozilla.org/en/Observer_Notifications#Session_Store">sessionstore-state-write</ulink>
+observer event to filter out URLs from tabs loaded during Tor, to prevent them
+from being written to disk. This is a rather expensive operation that involves
+potentially very large JSON evaluations and object tree traversals, but it
+preferable to replacing the Firefox session store with our own implementation,
+which is what was done in years past.
+
+ </para>
+</sect3>
+
+<!-- FIXME: torrefspoofer, tor-protocol, tors-protocol need documenting, but
+they are disabled by default for now, so no reason to add the
+clutter+confusion. -->
+
<sect3 id="contentpolicy">
<title><ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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
@@ -598,7 +600,8 @@ 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
+<ulink
+url="http://webdevwonders.com/detecting-firefox-add-ons/">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>
@@ -608,7 +611,7 @@ disabled. </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://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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
@@ -674,21 +677,113 @@ Torbutton.</para>
<title>Chrome</title>
<para>The chrome is where all the torbutton graphical elements and windows are
-located. Each window is described as an <ulink
+located. </para>
+<sect2>
+ <title>XUL Windows and Overlays</title>
+<para>
+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>
+window. XUL files that add new elements and script to existing Firefox windows
+are called overlays.</para>
-<sect2 id="browseroverlay">
+<sect3 id="browseroverlay">
<title>Browser Overlay - <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
It contains event handlers for preference update, shutdown, upgrade, and
location change events.</para>
+</sect3>
+<sect3>
+ <title>Preferences Window - <ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
+</sect3>
+<sect3>
+ <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>
+
+</sect3>
+</sect2>
+<sect2>
+ <title>Major Chrome Observers</title>
+ <para>
+In addition to the <link linkend="components">components described
+above</link>, Torbutton also instantiates several observers in the browser
+overlay window. These mostly grew due to scoping convenience, and many should
+probably be relocated into their own components.
+ </para>
+ <orderedlist>
+ <listitem><command>torbutton_window_pref_observer</command>
+ <para>
+This is an observer that listens for Torbutton state changes, for the purposes
+of updating the Torbutton button graphic as the Tor state changes.
+ </para>
+ </listitem>
+
+ <listitem><command>torbutton_unique_pref_observer</command>
+ <para>
+
+This is an observer that only runs in one window, called the main window. It
+listens for changes to all of the Torbutton preferences, as well as Torbutton
+controlled Firefox preferences. It is what carries out the toggle path when
+the proxy settings change. When the main window is closed, the
+torbutton_close_window event handler runs to dub a new window the "main
+window".
+
+ </para>
+ </listitem>
+
+ <listitem><command>tbHistoryListener</command>
+ <para>
+The tbHistoryListener exists to prevent client window Javascript from
+interacting with window.history to forcibly navigate a user to a tab session
+history entry from a different Tor state. It also expunges the window.history
+entries during toggle. This listener helps Torbutton
+satisfy the <link linkend="isolation">Network Isolation</link> requirement as
+well as the <link linkend="state">State Separation</link> requirement.
+
+ </para>
+ </listitem>
+
+ <listitem><command>torbutton_http_observer</command>
+ <para>
+
+The torbutton_http_observer performs some of the work that logically belongs
+to the content policy. This handles blocking of
+Firefox 3 favicon loads, 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>
+ <para>
+The observer is also responsible for redirecting users to alternate
+search engines when Google presents them with a Captcha, as well as copying
+Google Captcha-related cookies between international Google domains.
+ </para>
+ </listitem>
+
+ <listitem><command>torbutton_proxyservice</command>
+ <para>
+The Torbutton proxy service handles redirecting Torbutton-related update
+checks on addons.mozilla.org through Tor. This is done to help satisfy the
+<link linkend="undiscoverability">Tor Undiscoverability</link> requirement.
+ </para>
+ </listitem>
+
+ <listitem><command>torbutton_weblistener</command>
<para>The <ulink
url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
change</ulink> <ulink
@@ -706,11 +801,103 @@ url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
object to obfuscate browser and desktop resolution information.
</para>
+ </listitem>
+
+ </orderedlist>
+ </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://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
+and <ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul">popup.xul</ulink>
+overlay files. Most of the work in the toggling process is present in <ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>
+</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
+
+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="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">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>
+<!-- FIXME: Describe tab tagging and other state clearing hacks? -->
+ <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 <link
+linkend="cookiejar">cookie jaring</link>, state clearing (such as window.name
+and DOM storage), and <link linkend="preferences">preference
+toggling</link><!--, 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>
+<sect2 id="preferences">
+<title>Firefox preferences touched during Toggle</title>
+<para>
+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>
@@ -810,7 +997,8 @@ restoring it to the previous user value upon toggle.
</para>
</listitem>
- <listitem><command>security.enable_ssl2</command>
+ <listitem><command>security.enable_ssl2</command> or <ulink
+url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto">nsIDOMCrypto::logout()</ulink>
<para>
TLS Session IDs can persist for an indefinite duration, providing an
identifier that is sent to TLS sites that can be used to link activity. This
@@ -819,19 +1007,36 @@ in Firefox 3: The OCSP server can use this Session ID to build a history of
TLS sites someone visits, and also correlate their activity as users move from
network to network (such as home to work to coffee shop, etc), inside and
outside of Tor. To handle this and to help satisfy our <link
-linkend="state">State Separation Requirement</link>, we currently
-toggle
+linkend="state">State Separation Requirement</link>, we call the logout()
+function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
+to toggling
<command>security.enable_ssl2</command>, which clears the SSL Session ID
cache via the pref observer at <ulink
-url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
-line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
-better if there were a more standard interface for accomplishing the same
-thing. <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">448747</ulink> has
-been filed for this.
-
+url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
+ </para>
+ </listitem>
+ <listitem><command>security.OCSP.enabled</command>
+ <para>
+Similarly, we toggle <command>security.OCSP.enabled</command>, which clears the OCSP certificate
+validation cache via the pref observer at <ulink
+url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
+In this way, exit nodes will not be able to fingerprint you
+based the fact that non-Tor OCSP lookups were obviously previously cached.
+To handle this and to help satisfy our <link
+linkend="state">State Separation Requirement</link>,
</para>
</listitem>
+ <listitem><command><ulink
+url="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</ulink></command>
+ <para>
+We permanently disable addon usage statistic reporting to the
+addons.mozilla.org statistics engine. These statistics send version
+information about Torbutton users via non-Tor, allowing their Tor use to be
+uncovered. Disabling this reporting helps Torbutton to satisfy its <link
+linkend="undiscoverability">Tor Undiscoverability</link> requirement.
+
+ </para>
+ </listitem>
<listitem><command><ulink url="http://www.mozilla.com/en-US/firefox/geolocation/">geo.enabled</ulink></command>
<para>
@@ -900,112 +1105,12 @@ requirements.
</orderedlist>
</sect2>
-<sect2>
- <title>Preferences Window - <ulink
-url="https://git.torproject.org/checkout/torbutton/master/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://git.torproject.org/checkout/torbutton/master/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://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
-and <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul">popup.xul</ulink>
-overlay files. Most of the work in the toggling process is present in <ulink
-url="https://git.torproject.org/checkout/torbutton/master/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="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">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>
-<!-- FIXME: Review+update these during FF3.5 audit -->
+<!-- XXX: Break these into sections corresponding to panes -->
<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
@@ -1025,12 +1130,12 @@ Torbutton can easily inspect for a hidden link with an id of
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://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>.
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>.
Presenting the results to the user is handled by the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul">preferences
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences
window</ulink>
callback <function>torbutton_prefs_test_settings()</function> in <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js">preferences.js</ulink>.
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">preferences.js</ulink>.
</para>
</sect2>
@@ -1063,7 +1168,7 @@ 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://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
enabled and this option is set.
</para>
@@ -1125,7 +1230,7 @@ linkend="proxy">Proxy Obedience</link> requirement.
<para>Option: <command>extensions.torbutton.isolate_content</command></para>
<para>Enabling this preference is what enables the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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="https://developer.mozilla.org/en/XUL/tabbrowser">browser
@@ -1175,7 +1280,7 @@ linkend="isolation">Network Isolation</link> requirement.
<para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
<para>This setting enables injection of the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js">Javascript
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js">Javascript
hooking code</ulink>. This is done in the chrome in
<function>torbutton_hookdoc()</function>, which is called ultimately by both the
<ulink
@@ -1202,7 +1307,7 @@ to retrieve the original screen values by using <ulink
url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
or <ulink
url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.
-We are still looking for a workaround as of Torbutton 1.2.5.
+We are still looking for a workaround as of Torbutton 1.3.2.
<!-- FIXME: Don't forget to update this -->
@@ -1322,6 +1427,8 @@ for Tor usage.
</para>
<para>
+<!-- XXX: This is done differently -->
+
This option causes Torbutton to prevent Firefox from loading <ulink
url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
Tor usage. Because people often have very personalized Livemarks (such as RSS
@@ -1372,6 +1479,11 @@ files to arbitrary sites just generally seems like a bad idea.
</para>
</sect2>
+
+<!-- XXX: Redirect Torbutton updates through tor -->
+
+<!-- XXX: Disable updates during tor usage -->
+
<sect2>
<title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
@@ -1455,6 +1567,7 @@ requirements.
<title>History Access Settings</title>
<para>Options:
+<!-- XXX: Firefox 4 changes these. We sync them with places.history.enabled -->
<simplelist>
<member><command>extensions.torbutton.block_thread</command></member>
<member><command>extensions.torbutton.block_nthread</command></member>
@@ -1464,7 +1577,7 @@ requirements.
</para>
<para>These four settings govern the behavior of the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
@@ -1604,7 +1717,7 @@ linkend="disk">Disk Avoidance</link> requirements.
<para>
This setting causes Torbutton to use <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
before restoring the jar.
</para>
@@ -1634,7 +1747,7 @@ linkend="disk">Disk Avoidance</link> requirements.
<para>
This setting causes Torbutton to use <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
both Tor and Non-Tor cookies into protected jars.
</para>
@@ -1646,6 +1759,8 @@ linkend="state">State Separation</link> requirement.
</sect2>
+<!-- FIXME: If we decide to keep it, document the cookie protections dialog
+-->
<sect2>
@@ -1720,6 +1835,7 @@ linkend="state">State Separation</link> requirement.
</para>
</sect2>
+<!-- XXX: Move these to shutdown section -->
<sect2>
<title>Clear cookies on Tor/Non-Tor shutdown</title>
@@ -1732,8 +1848,8 @@ cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
for the <ulink
url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
-<function>https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</function> and use <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
+<function>https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js</function> and use <ulink
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
to clear out all cookies and all cookie jars upon shutdown. </para>
<para>
This setting helps to satisfy the <link
@@ -1754,14 +1870,14 @@ linkend="state">State Separation</link> requirement.
<para>This is no longer a user visible option, and is enabled by default. In
the event of a crash, the Torbutton <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">components/crash-observer.js</ulink>
component will notify the Chrome (via the
<command>extensions.torbutton.crashed</command> pref and a <ulink
url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
observer</ulink> in
the chrome that listens for this update), and Torbutton will load the
correct jar for the current Tor state via the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
component.</para>
<para>
@@ -1772,7 +1888,7 @@ crashes.
</sect2>
-
+<!-- XXX: These have all been simplified -->
<sect2>
<title>On crash recovery or session restored startup, restore via: Tor, Non-Tor</title>
<para>Options:
@@ -1784,7 +1900,7 @@ crashes.
</para>
<para>This option works with the Torbutton <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">crash-observer.js</ulink>
to set the Tor state after a crash is detected (via the
<command>extensions.torbutton.crashed</command> pref). To confirm for
false positives (such as session restore failures, upgrade, normal
@@ -1814,7 +1930,7 @@ settings and saved sessions are reloaded from a fixed Tor state.
</para>
<para>This option also works with the Torbutton <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">crash-observer.js</ulink>
to set the Tor state after a normal startup is detected (via the
<command>extensions.torbutton.noncrashed</command> pref). To confirm for
false positives
@@ -1837,7 +1953,7 @@ Firefox exit and checks this value as well during startup.
</para>
<para>If these options are enabled, the <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js">replacement nsSessionStore.js</ulink>
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/nsSessionStore3.js">replacement nsSessionStore.js</ulink>
component checks the <command>__tb_tor_fetched</command> tag of tabs before writing them
out. If the tag is from a blocked Tor state, the tab is not written to disk.
</para>
@@ -1946,6 +2062,9 @@ This setting also does not directly satisfy any Torbutton requirement, but
some may desire to mask their referrer for general privacy concerns.
</para>
</sect2>
+
+<!-- XXX: Smart referer spoofing -->
+
<sect2>
<title>Strip platform and language off of Google Search Box queries</title>
@@ -2023,7 +2142,7 @@ encoded in the preferences
These settings govern if Torbutton attempts to isolate the user's SSL
certificates into separate jars for each Tor state. This isolation is
implemented in <function>torbutton_jar_certs()</function> in <ulink
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
which calls <function>torbutton_jar_cert_type()</function> and
<function>torbutton_unjar_cert_type()</function> for each certificate type in
the <ulink
@@ -2252,6 +2371,22 @@ to resize maximized and minimized windows when it should not.
</para>
</listitem>
<listitem><ulink
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=629820">nsIContentPolicy::shouldLoad not
+called for web request in Firefox Mobile</ulink>
+ <para>
+
+The new <ulink
+url="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis">Electrolysis</ulink>
+multiprocess system appears to have some pretty rough edge cases with respect
+to registering XPCOM category managers such as the nsIContentPolicy, which
+make it difficult to do a straight-forward port of Torbutton or
+HTTPS-Everywhere to Firefox Mobile. It probably also has similar issues with
+wrapping existing <link linkend="hookedxpcom">Firefox XPCOM components</link>,
+which will also cause more problems for porting TOrbutton.
+
+ </para>
+ </listitem>
+ <listitem><ulink
url="https://bugzilla.mozilla.org/show_bug.cgi?id=290456">Bug 290456 -
Block/clear Flash MX "cookies" as well</ulink>
<para>
@@ -2279,6 +2414,8 @@ FoxyProxy) difficult to impossible to implement securely.
</para>
</listitem>
+<!--
+FIXME: This doesn't really apply anymore.
<listitem><ulink
url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
Components do not expose disk interfaces</ulink>
@@ -2292,6 +2429,7 @@ some of them involve disabling functionality during Tor usage.
</para>
</listitem>
+-->
<!--
FIXME: Need to use new observer methods if possible
@@ -2445,27 +2583,6 @@ Williams.
</para>
</listitem>
-<!--
-
-XXX: This is likely fixed with nsICrypto.logout()
-
- <listitem><ulink
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">Bug 448747 -
-Provide Mechanism to clear TLS Session IDs</ulink>
- <para>
-
-As <link linkend="browseroverlay">mentioned above</link>, Torbutton currently
-toggles <command>security.enable_ssl2</command> to clear the SSL
-Session ID cache via the pref observer at <ulink
-url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
-line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
-better if there were a more standard interface for accomplishing the same
-thing.
-
- </para>
- </listitem>
--->
-
<listitem><ulink
url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
Date' is deletable</ulink>
More information about the tor-commits
mailing list