Table of Contents
This document describes the goals, operation, and testing procedures of the Torbutton Firefox extension. It is current as of Torbutton 1.2.0rc5.
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.
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.
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.
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.
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.
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 tracking their activities.
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.
The adversary can position themselves at a number of different locations in order to execute their attacks.
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.
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.
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.
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.
The adversary can perform the following attacks from a number of different positions to accomplish various aspects of their goals.
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 history disclosure attacks:
to query the history via the different attributes of 'visited' links. Finally,
Javascript can be used to query the user's timezone via the
Date() object, and to reduce the anonymity set by querying
the navigator object for operating system, CPU, and user
agent information.
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. Flash-based cookies fall into this category, but there are likely numerous other examples.
CSS can also be used to correlate Tor and Non-Tor activity, via the usage of CSS popups - 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 CSS-only history disclosure attacks.
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 active sidejacking.
Likewise, the browser cache can also be used to store unique identifiers. 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.
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 uniquely fingerprint individual users.
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 window and window.screen 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 23=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 ~= 229, or a 29 bit identifier based on resolution information alone.
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 The Hacker Webzine article above, minor changes in browser window resolution will no longer generate totally new identifiers.
To add insult to injury, chrome URL disclosure attacks mean that each and every extension on addons.mozilla.org adds another bit to that 229. 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.
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.
From the above Adversary Model, a number of requirements become clear.
The browser MUST NOT bypass Tor proxy settings for any content.
Pages MUST NOT perform any network activity in a Tor state different from the state they were originally loaded in.
Browser state (cookies, cache, history, 'DOM storage'), accumulated in one Tor state MUST NOT be accessible via the network in another Tor state.
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.
The browser SHOULD NOT write any Tor-related state to disk, or store it in memory beyond the duration of one Tor toggle.
The browser SHOULD NOT leak location-specific information, such as timezone or locale via Tor.
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.
The browser SHOULD NOT perform unauthenticated updates or upgrades via Tor.
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.
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 can be written in C++, Javascript, or a mixture of both. Components have two identifiers: their 'Contract ID' (a human readable path-like string), and their 'Class ID' (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.
'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 XUL.
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.
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.
These components address the Disk Avoidance 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.
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 entire 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 diff against the original session store is included in the SVN repository.
This component wraps the Firefox Session Startup component that is in
charge of restoring saved
sessions. The wrapper's only job is to intercept the
doRestore() 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
extensions.torbutton.crashed, or that it is a normal
startup via the pref extensions.torbutton.noncrashed. The Torbutton Chrome listens for a
preference change 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 (extensions.torbutton.restore_tor), and
restoring cookies for the corresponding cookie jar, if it exists.
By performing this notification, this component assists in the Proxy Obedience, and Network Isolation requirements.
This component was contributed by Collin Jackson 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 isVisited and addURI 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.
This component helps satisfy the State Separation and Disk Avoidance requirements of Torbutton.
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.
The cookie jar selector (also based on code from Collin Jackson) 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.
This component helps to address the State Isolation requirement of Torbutton.
The torbutton logger component allows on-the-fly redirection of torbutton logging messages to either Firefox stderr (extensions.torbutton.logmethod=0), the Javascript error console (extensions.torbutton.logmethod=1), or the DebugLogger extension (if available - extensions.torbutton.logmethod=2). It also allows you to change the loglevel on the fly by changing extensions.torbutton.loglevel (1-5, 1 is most verbose).
Torbutton tags Firefox tabs 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 browser tab for a given HTML content window. It does this by traversing all windows and all browsers, until it finds the browser with the requested contentWindow element. Since the content policy and page loading in general can generate hundreds of these lookups, this result is cached inside the component.
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 nsIContentPolicy. When an nsIContentPolicy is registered, Firefox checks every attempted network request against its shouldLoad member function to determine if the load should proceed. In Torbutton's case, the content policy looks up the appropriate browser tab using the window mapper, 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.
This helps to achieve the Network Isolation requirements of Torbutton.In addition, the content policy also blocks website javascript from querying for versions and existence of extension chrome while Tor is enabled, and also masks the presence of Torbutton to website javascript while Tor is disabled.
Finally, some of the work that logically belongs to the content policy is instead handled by the torbutton_http_observer and torbutton_weblistener in torbutton.js. 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 437014 and 401296).
This helps to fulfill both the Anonymity Set Preservation and the Tor Undiscoverability requirements of Torbutton.
The chrome is where all the torbutton graphical elements and windows are located. Each window is described as an XML file, with zero or more Javascript files attached. The scope of these Javascript files is their containing window.
The browser overlay, torbutton.xul, defines the toolbar button, the status bar, and events for toggling the button. The overlay code is in chrome/content/torbutton.js. It contains event handlers for preference update, shutdown, upgrade, and location change events.
The location
change webprogress
listener, torbutton_weblistener is perhaps the
most important part of the chrome from a security standpoint. It is a web
progress listener that handles
receiving an event every time a page load or iframe load occurs. This class
eventually calls down to torbutton_update_tags() and
torbutton_hookdoc(), which apply the browser Tor load state tags, plugin
permissions, and install the Javascript hooks to hook the Date object and
the navigator object (for timezone and platform information,
respectively).
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
torbutton_update_status() that aren't governed by any
Torbutton setting. These are:
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 State Separation requirement. Unfortunately Firefox Bug 436250 prevents this from functioning completely correctly.
Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it reads from extensions.torbutton.banned_ports) 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 Tor Undiscoverability requirement.
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 Network Isolation requirement.
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 Disk Avoidance requirement, by preventing your entire browsing history from ending up on Google's disks.
Safebrowsing does unauthenticated updates under Firefox 2, so it is disabled during Tor usage. This helps fulfill the Update Safety requirement. Firefox 3 has the fix for that bug, and so safebrowsing updates are enabled during Tor usage.
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 Proxy Obedience requirement, by preventing external applications from accessing network resources at the command of Tor-fetched pages.
The preferences window of course lays out the Torbutton preferences, with handlers located in chrome/content/preferences.js.
The act of toggling is connected to torbutton_toggle()
via the torbutton.xul
and popup.xul
overlay files. Most of the work in the toggling process is present in torbutton.js
Toggling is a 3 stage process: Button Click, Proxy Update, and Settings Update. These stages are reflected in the prefs extensions.torbutton.tor_enabled, extensions.torbutton.proxies_applied, and extensions.torbutton.settings_applied. The reason for the three stage preference update is to ensure immediate enforcement of Network Isolation via the content policy. 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 Firefox Bug 409737 unfixed. The content policy does not allow any network activity whatsoever during this three stage transition.
This is the first step in the toggling process. When the user clicks the
toggle button or the toolbar, torbutton_toggle() 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
extensions.torbutton.tor_enabled to reflect the new state.
It is this proxy pref update that gives notification via the pref
observer
torbutton_unique_pref_observer to perform the rest of the
toggle.
When Torbutton receives any proxy change notifications via its
torbutton_unique_pref_observer, it calls
torbutton_set_status() which checks against the Tor
settings to see if the Tor proxy settings match the current settings. If so,
it calls torbutton_update_status(), which determines if
the Tor state has actually changed, and sets
extensions.torbutton.proxies_applied to the appropriate Tor
state value, and ensures that
extensions.torbutton.tor_enabled 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.
The next stage is also handled by
torbutton_update_status(). This function sets scores of
Firefox preferences, saving the original values to prefs under
extensions.torbutton.saved.*, and performs the history
clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
end of its work, it sets
extensions.torbutton.settings_applied, which signifies the
completion of the toggle operation to the content policy.
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.
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 XMLHTTPRequest
for https://check.torproject.org/?Torbutton=True.
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
TorCheckResult and a target of success
or failure to indicate if the
user hit the page from a Tor IP, a non-Tor IP. This check is handled in
torbutton_test_settings() in torbutton.js.
Presenting the results to the user is handled by the preferences
window
callback torbutton_prefs_test_settings() in preferences.js.
Option: extensions.torbutton.no_tor_plugins
Enabling this preference causes the above mentioned Torbutton chrome web progress
listener torbutton_weblistener to disable Java via security.enable_java and to disable
plugins via the browser docShell
attribute allowPlugins. These flags are set every time a new window is
created (torbutton_tag_new_browser()), every time a web
load
event occurs
(torbutton_update_tags()), and every time the tor state is changed
(torbutton_update_status()). As a backup measure, plugins are also
prevented from loading by the content policy in @torproject.org/cssblocker;1 if Tor is
enabled and this option is set.
Even all this turns out to be insufficient if the user directly clicks on a plugin-handled mime-type. In this case (and also this one), 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 plugin.disable_full_page_plugin_for_types 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.
All this could be avoided, of course, if Firefox would either obey allowPlugins for directly visited URLs, or notify its content policy for such loads either via shouldProcess or shouldLoad. The fact that it does not is not very encouraging.
Since most plugins completely ignore browser proxy settings, the actions performed by this setting are crucial to satisfying the Proxy Obedience requirement.
Option: extensions.torbutton.isolate_content
Enabling this preference is what enables the @torproject.org/cssblocker;1 content policy
mentioned above, and causes it to block content load attempts in pages an
opposite Tor state from the current state. Freshly loaded browser
tabs are tagged
with a __tb_load_state member in
torbutton_update_tags() and this
value is compared against the current tor state in the content policy.
It also kills all Javascript in each page loaded under that state by toggling the allowJavascript docShell property, and issues a webNavigation.stop(webNavigation.STOP_ALL) to each browser tab (the equivalent of hitting the STOP button).
Unfortunately, Firefox bug
409737 prevents docShell.allowJavascript from killing
all event handlers, and event handlers registered with addEventListener()
are still able to execute. The Torbutton Content
Policy 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 window.opener
attribute in torbutton_check_progress(). 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.
This setting is responsible for satisfying the Network Isolation requirement.
Option: extensions.torbutton.kill_bad_js
This setting enables injection of the Javascript
hooking code. Javascript is injected into
pages to hook the Date
class to mask your timezone. This is done in the chrome in
torbutton_hookdoc(), which is called ultimately by both the
webprogress
listener torbutton_weblistener and the content policy (the latter being a hack to handle
javascript: urls). This behavior helps to satisfy the Location Neutrality requirement.
In addition, this setting also hooks various resolution properties of the window, window.screen, and window.navigator 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 anonymity set reduction attacks and help to meet the Anonymity Set Preservation requirements.
Option: extensions.torbutton.resize_windows
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.
The implementation of this setting is spread across a couple of different
locations in the Torbutton javascript browser
overlay. 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 torbutton_check_round(), called by
torbutton_update_tags(). 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
(torbutton_do_resize()) 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).
This setting helps to meet the Anonymity Set Preservation requirements.
Option: extensions.torbutton.no_updates
This setting causes Torbutton to disable the four Firefox update settings during Tor usage: extensions.update.enabled, app.update.enabled, app.update.auto, and browser.search.update. These prevent the browser from updating extensions, checking for Firefox upgrades, and checking for search plugin updates while Tor is enabled.
This setting satisfies the Update Safety requirement.
Option: extensions.torbutton.no_search
This setting causes Torbutton to disable browser.search.suggest.enabled 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.
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.
Option:
| extensions.torbutton.block_tor_file_net |
| extensions.torbutton.block_nontor_file_net |
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 submit arbitrary files from the local filesystem 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 content policy to block access to any network resources from File urls during the appropriate Tor state.
This preference helps to ensure Tor's Network Isolation requirement, by preventing file urls from executing network operations in opposite Tor states. Also, allowing pages to submit arbitrary files to arbitrary sites just generally seems like a bad idea.
Options:
| extensions.torbutton.close_nontor |
| extensions.torbutton.close_tor |
These settings cause Torbutton to enumerate through all windows and close all
tabs in each window for the appropriate Tor state. This code can be found in
torbutton_update_status(). The main reason these settings
exist is as a backup mechanism in the event of any Javascript or content policy
leaks due to Firefox Bug
409737. Torbutton currently tries to block all Javascript network
activity via the content policy, but until that bug is fixed, there is some
risk that there are alternate ways to bypass the policy. This option is
available as an extra assurance of Network
Isolation for those who would like to be sure that when Tor is toggled
all page activity has ceased. It also serves as a potential future workaround
in the event a content policy failure is discovered, and provides an additional
level of protection for the Disk Avoidance
protection so that browser state is not sitting around waiting to be swapped
out longer than necessary.
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.
Option: extensions.torbutton.block_js_history
This setting determines if Torbutton installs an nsISHistoryListener attached to the sessionHistory of of each browser's webNavigatator. The nsIShistoryListener is instantiated with a reference to the containing browser window and blocks the back, forward, and reload buttons on the browser navigation bar when Tor is in an opposite state than the one to load the current tab. In addition, Tor clears the session history during a new document load if this setting is enabled.
This is marked as a crucial setting in part because Javascript access to the history object is indistinguishable from user clicks, and because Firefox Bug 409737 allows javascript to execute in opposite Tor states, javascript can issue reloads after Tor toggle to reveal your original IP. Even without this bug, however, Javascript is still able to access previous pages in your session history that may have been loaded under a different Tor state, to attempt to correlate your activity.
This setting helps to fulfill Torbutton's State Separation and (until Bug 409737 is fixed) Network Isolation requirements.
Options:
| extensions.torbutton.block_thread |
| extensions.torbutton.block_nthread |
| extensions.torbutton.block_thwrite |
| extensions.torbutton.block_nthwrite |
These four settings govern the behavior of the components/ignore-history.js history blocker component mentioned above. By hooking the browser's view of the history itself via the mozilla.org/browser/global-history;2 component, this mechanism defeats all document-based history disclosure attacks, including CSS-only attacks.
On Firefox 3, the history write settings also govern if Torbutton sets browser.history_expire_days to 0 on the appropriate Tor state, which should disable all Places database writes.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.clear_history
This setting governs if Torbutton calls nsIBrowserHistory.removeAllPages and nsISHistory.PurgeHistory for each tab on Tor toggle.
This setting is an optional way to help satisfy the State Separation requirement.
Options:
| extensions.torbutton.block_tforms |
| extensions.torbutton.block_ntforms |
These settings govern if Torbutton disables browser.formfill.enable and signon.rememberSignons during Tor and Non-Tor usage. Since form fields can be read at any time by Javascript, this setting is a lot more important than it seems.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.clear_cache
This option causes Torbutton to call nsICacheService.evictEntries(0) on Tor toggle to remove all entries from the cache. In addition, this setting causes Torbutton to set browser.cache.disk.enable to false.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.block_cache
This setting causes Torbutton to set browser.cache.memory.enable, browser.cache.disk.enable and network.http.use-cache to false during tor usage.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.clear_cookies
This setting causes Torbutton to call nsICookieManager.removeAll() on every Tor toggle. In addition, this sets network.cookie.lifetimePolicy to 2 for Tor usage, which causes all cookies to be demoted to session cookies, which prevents them from being written to disk.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.cookie_jars
This setting causes Torbutton to use @stanford.edu/cookie-jar-selector;2 to store non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies before restoring the jar.
This setting also sets network.cookie.lifetimePolicy to 2 for Tor usage, which causes all cookies to be demoted to session cookies, which prevents them from being written to disk.
This setting helps to satisfy the State Separation and Disk Avoidance requirements.
Option: extensions.torbutton.dual_cookie_jars
This setting causes Torbutton to use @stanford.edu/cookie-jar-selector;2 to store both Tor and Non-Tor cookies into protected jars.
This setting helps to satisfy the State Separation requirement.
Options: None
This setting disables all Torbutton cookie handling by setting the above cookie prefs all to false.
Options:
| extensions.torbutton.tor_memory_jar |
| extensions.torbutton.nontor_memory_jar |
These settings (contributed by arno) cause Torbutton to set network.cookie.lifetimePolicy to 2 during the appropriate Tor state, and to store cookies acquired in that state into a Javascript E4X object as opposed to writing them to disk.
This allows Torbutton to provide an option to preserve a user's cookies while still satisfying the Disk Avoidance requirement.
Option: extensions.torbutton.disable_domstorage
This setting causes Torbutton to toggle dom.storage.enabled during Tor usage to prevent DOM Storage from being used to store persistent information across Tor states.
This setting helps to satisfy the State Separation requirement.
Option: extensions.torbutton.clear_http_auth
This setting causes Torbutton to call nsIHttpAuthManager.clearAll() every time Tor is toggled.
This setting helps to satisfy the State Separation requirement.
Option: extensions.torbutton.shutdown_method
This option variable can actually take 3 values: 0, 1, and 2. 0 means no
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 quit-application-granted event in
torbutton_uninstall_observer() and use @stanford.edu/cookie-jar-selector;2
to clear out all cookies and all cookie jars upon shutdown.
This setting helps to satisfy the State Separation requirement.
Options:
| extensions.torbutton.reload_crashed_jar |
| extensions.torbutton.crashed |
This is no longer a user visible option, and is enabled by default. In the event of a crash, the Torbutton components/crash-observer.js component will notify the Chrome (via the extensions.torbutton.crashed pref and a pref observer in the chrome that listens for this update), and Torbutton will load the correct jar for the current Tor state via the @stanford.edu/cookie-jar-selector;2 component.
This setting helps to satisfy the State Separation requirement in the event of Firefox crashes.
Options:
| extensions.torbutton.restore_tor |
| extensions.torbutton.crashed |
This option works with the Torbutton crash-observer.js to set the Tor state after a crash is detected (via the extensions.torbutton.crashed pref)
Since the Tor state after a Firefox crash is unknown/indeterminate, this setting helps to satisfy the State Separation requirement in the event of Firefox crashes by ensuring all cookies, settings and saved sessions are reloaded from a fixed Tor state.
Options:
| extensions.torbutton.startup_state |
| extensions.torbutton.noncrashed |
This option also works with the Torbutton crash-observer.js to set the Tor state after a normal startup is detected (via the extensions.torbutton.noncrashed pref)
Options:
| extensions.torbutton.nonontor_sessionstore |
| extensions.torbutton.notor_sessionstore |
If these options are enabled, the replacement nsSessionStore.js component checks the __tb_tor_fetched tag of tabs before writing them out. If the tag is from a blocked Tor state, the tab is not written to disk.
This setting helps to satisfy the Disk Avoidance requirement, and also helps to satisfy the State Separation requirement in the event of Firefox crashes.
Options:
| extensions.torbutton.set_uagent |
| extensions.torbutton.oscpu_override |
| extensions.torbutton.platform_override |
| extensions.torbutton.productsub_override |
| extensions.torbutton.appname_override |
| extensions.torbutton.appversion_override |
| extensions.torbutton.useragent_override |
| extensions.torbutton.useragent_vendor |
| extensions.torbutton.useragent_vendorSub |
On face, user agent switching appears to be straight-forward in Firefox. It provides several options for controlling the browser user agent string: general.appname.override, general.appversion.override, general.platform.override, general.useragent.override, general.useragent.vendor, and general.useragent.vendorSub. If the Torbutton preference extensions.torbutton.set_uagent is true, Torbutton copies all of the other above prefs into their corresponding browser preferences during Tor usage.
However, this is not the whole story. Additionally, even with the above prefs set, the oscpu, buildID, and productSub fields of the navigator object are not changed appropriately by the above prefs. Javascript hooks implemented in chrome/content/jshooks.js are installed as part of the same mechanism that hooks the date object.
It also turns out that it is possible to detect the original Firefox version by inspecting certain resource:// files. These cases are handled by Torbutton's content policy.
This setting helps to satisfy the Anonymity Set Preservation requirement.
Options:
| extensions.torbutton.spoof_english |
| extensions.torbutton.spoof_charset |
| extensions.torbutton.spoof_language |
This option causes Torbutton to set general.useragent.locale, intl.accept_charsets and intl.accept_languages to the value specified in extensions.torbutton.spoof_locale, extensions.torbutton.spoof_charset and extensions.torbutton.spoof_language during Tor usage.
This setting helps to satisfy the Anonymity Set Preservation and Location Neutrality requirements.
Option: extensions.torbutton.disable_referer
This option causes Torbutton to set network.http.sendSecureXSiteReferrer and network.http.sendRefererHeader during Tor usage.
This setting also does not directly satisfy any Torbutton requirement, but some may desire to mask their referrer for general privacy concerns.
Options:
| extensions.torbutton.jar_certs |
| extensions.torbutton.jar_ca_certs |
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 torbutton_jar_certs() in chrome/content/torbutton.js,
which calls torbutton_jar_cert_type() and
torbutton_unjar_cert_type() for each certificate type in
the @mozilla.org/security/nsscertcache;1.
Certificates are deleted from and imported to the @mozilla.org/security/x509certdb;1.
The first time this pref is used, a backup of the user's certificates is
created in their profile directory under the name
cert8.db.bak. This file can be copied back to
cert8.db to fully restore the original state of the
user's certificates in the event of any error.
Since exit nodes and malicious sites can insert content elements sourced to specific SSL sites to query if a user has a certain certificate, this setting helps to satisfy the State Separation requirement of Torbutton. Unfortunately, Firefox Bug 435159 prevents it from functioning correctly in the event of rapid Tor toggle, so it is currently not exposed via the preferences UI.
Torbutton has to work around a number of Firefox bugs that impact its security. Most of these are mentioned elsewhere in this document, but they have also been gathered here for reference. Several of these have fixes in Firefox3.0/trunk, but are listed because they still have not been backported to FF2.0. In order of decreasing severity, they are:
The lack of a config or API to configure the timezone requires Torbutton to insert client content window javascript to hook the Date object. Additionally, a way to remove the Date hooks was discovered by Greg Fleischer. Worse, on Firefox 3, javascript sandboxing prevents most of the javascript hooks from being installed, including the Date hooks. On Windows and Linux, you can set the TZ environment variable to "UTC" as a workaround. Firefox will obey this environment variable for your Timezone on those platforms, but on Windows this does not take effect until browser restart.
The RSS Feed based "Livemarks"/"Live Bookmarks" update frequency is controlled by the pref browser.bookmarks.livemark_refresh_seconds. However, changing this preference does not cancel any pending timers, which means that at least one livemarks pref fetch will happen over Tor, and once this pref is set to disable livemarks for Tor, changing it back will never cause the service to start back up again.
In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates the user has installed. Unfortunately, the method call to delete a certificate from the current certificate database acts lazily: it only sets a variable that marks a cert for deletion later, and it is not cleared if that certificate is re-added. This means that if the Tor state is toggled quickly, that certificate could remain present until it is re-inserted (causing an error dialog), and worse, it would still be deleted after that. The lack of this functionality is considered a Torbutton security bug because cert isolation is considered a State Separation feature.
This bug allows pages to execute javascript via addEventListener and perhaps other callbacks. In order to prevent this bug from enabling an attacker to break the Network Isolation requirement, Torbutton 1.1.13 began blocking popups and history manipulation from different Tor states. So long as there are no ways to open popups or redirect the user to a new page, the Torbutton content policy should block Javascript network access. However, if there are ways to open popups or perform redirects such that Torbutton cannot block them, pages may still have free reign to break that requirement and reveal a user's original IP address.
It turns out that Firefox's SSL implementation sends the machine uptime as the current time. This essentially is a unique identifier that can be used for the duration of your machine uptime. The issue has been fixed in Firefox 3.0, but it has as of yet not been backported to 2.0.
Javascript can query the .value field of file input dialogs to retrieve username and sometimes hostname/workgroup information. This is obviously very dangerous for people who are attempting to submit files anonymously via webforms (ie whistleblowers and anonymous publishers). It is also fixed in Firefox 3.0, but has not yet been backported to 2.0.
XML documents can source chrome and resource URLs in their DTDs without a call to nsIContentPolicy::shouldLoad. Enumerating chrome URLs gives websites and exit nodes a lot of information. They can use it to probe for vulnerable versions of extensions, and can also use it to build an identifier for tracking purposes. This bug makes it impossible for extensions such as Adblock and Torbutton to prevent chrome inspection and enumeration. There is no workaround for this bug as of yet.
The following bugs impact Torbutton and similar extensions' functionality.
In Firefox 3, the change to the new sqlite database for cookie storage has a bug that prevents Torbutton's cookie jaring from working properly. The "profile-do-change" observer event no longer properly causes either a sync or reload of the cookie database from disk after it is copied into place. Torbutton currently works around this by issuing the SQLLite queries manually to store and rebuild the cookie database.
It is difficult to determine which tabbrowser many XPCOM callbacks originate from, and in some cases absolutely no context information is provided at all. While this doesn't have much of an effect on Torbutton, it does make writing extensions that would like to do per-tab settings and content filters (such as FoxyProxy) difficult to impossible to implement securely.
Several components currently provide no way of reimplementing their disk access to easily satisfy Torbutton's Disk Avoidance requirements. Workarounds exist, but they are clunky, and some of them involve disabling functionality during Tor usage.
The following bugs have an effect upon Torbutton, but are superseded by more practical and more easily fixable variant bugs above; or have stable, simple workarounds.
Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use constructors of classes defined from within the scope of the sandbox, among other things. This prevents Torbutton from applying the Timezone hooks under Firefox 3, but a better solution for Torbutton's specific date hooking needs would be a fix for the above mentioned Bug 392274. Of course, many more extensions may be interested in the sandbox hooking functionality working properly though.
Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon loads. Torbutton had relied on this call to block favicon loads for opposite Tor states. The workaround it employs for Firefox 3 is to cancel the request when it arrives in the torbutton_http_observer used for blocking full page plugin loads. This seems to work just fine, but is a bit dirty.
An alternative fix for the livemarks bug above would be to block livemarks fetches from the content policy. Unfortunately shouldLoad is not called for livemarks fetches.
As mentioned above, a large amount of information is available from window.screen. Currently, there is no way to obscure this information without Javascript hooking. This bug is a feature request to provide some other method to change these values.
This is a call that would be useful to develop a better workaround for the allowPlugins issue above. If the content policy were called before a URL was handed over to a plugin or helper app, it would make the workaround for the above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as the others though, but it might be nice to have this API as a backup.
Similar to the javascript plugin disabling attribute, the plugin disabling attribute is also not perfect — it is ignored for direct links to plugin handled content, as well as meta-refreshes to plugin handled content. This requires Torbutton to listen to a number of different http events to intercept plugin-related mime type URLs and cancel their requests. Again, since plugins are quite horrible about obeying proxy settings, loading a plugin pretty much ensures a way to break the Network Isolation requirement and reveal a user's original IP address. Torbutton's code to perform this workaround has been subverted at least once already by Kyle Williams.
For some reason, defining getters off of window seems to mess with the implicit window scoping in some documents. There is a workaround for this bug, so it is barely relevant. It would be far more useful to eliminate the need for Javascript hooking in the first place by addressing the above bugs. This bug is just listed for completeness.
Based on Page 62 of the ECMA-262 Javascript spec, it seems like it should be possible to do something like the following to prevent the Date object from being unmasked:
with(window) {
var Date = fakeDate;
var otherVariable = 42;
}
delete window.Date; // Should fail. Instead succeeds, revealing original Date.
delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
From the ECMA-262 spec:
If the variable statement occurs inside a FunctionDeclaration, the variables are defined with function-local scope in that function, as described in s10.1.3. Otherwise, they are defined with global scope (that is, they are created as members of the global object, as described in 10.1.3) using property attributes { DontDelete }. Variables are created when the execution scope is entered. A Block does not define a new execution scope. Only Program and FunctionDeclaration produce a new scope. Variables are initialized to undefined when created. A variable with an Initialiser is assigned the value of its AssignmentExpression when the VariableStatement is executed, not when the variable is created.
In fact, this is exactly how the with statement with a variable declaration behaves for all other variables other than ones that shadow system variables. Some variables (such as window.screen, and window.history) can't even be shadowed in this way, and give an error about lacking a setter. If such shadowing were possible, it would greatly simplify the Javascript hooking code, which currently relies on undocumented semantics of __proto__ to copy the original values in the event of a delete. This __proto__ hack unfortunately does not work for the Date object though.
The purpose of this section is to cover all the known ways that Tor browser security can be subverted from a testing and penetration perspective. The hope is that it will be useful both for creating a "Tor Safety Check" page, and for developing novel tests and actively attacking Torbutton with the goal of finding vulnerabilities in either it or the Mozilla components, interfaces and settings upon which it relies.
The following tests can be run from a single web page in one visit without toggling Tor state or requiring user interaction. Currently they exist as their own individual tests, but conceivably a single "Tor Safety Check" page can be devised that contains all of these attacks. All of these tests are currently known to pass, but that does not mean that consolidating them into an easy to run test page is pointless. Torbutton is a complicated piece of software. During development, changes to one component can affect a whole slough of unrelated features. Having easy-to-verify comprehensive test pages would make it much easier to fix other issues as they present themselves without introducing regressions.
As mentioned above, Java and plugins can query the local IP address and report it back to the remote site. They can also bypass proxy settings and directly connect to a remote site without Tor. Every browser plugin we have tested with Firefox has some form of network capability, and every one ignores proxy settings or worse - only partially obeys them. This includes but is not limited to: QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and Flash. In addition, issues have been discovered with the browsers handling of direct links to plugin-handled content as well as meta-refreshes to plugin content. To make matters worse, externally handled mime types and urls can also cause direct non-Tor connections as well.
The browser's history can also be queried by a remote site to inspect for Google queries, visits to sites that contain usernames in the URLs, or other anonymity set reducing information. This can be done by either Javascript, or by CSS without any scripting involved.
As mentioned above, these properties can be combined to greatly reduce anonymity set and even build a potentially globally unique identifier for users. Examples of this in the wild rely on user agent and OS information as well as chrome disclosure information.
Time and Timezone should be obscured to be GMT-only, and by the browser should present itself with an US English locale.
The tests in this section are geared towards a page that would instruct the user to toggle their Tor state after the fetch and perform some operations: mouseovers, stray clicks, and potentially reloads.
The most obvious test is to set a cookie, ask the user to toggle tor, and then have them reload the page. The cookie should no longer be set if they are using the default Torbutton settings. In addition, it is possible to leverage the cache to store unique identifiers. The default settings of Torbutton should also protect against these from persisting across Tor Toggle.
Javascript can set timers and register event handlers in the hopes of fetching URLs after the user has toggled Torbutton.
Even if Javascript is disabled, CSS is still able to create popup-like windows via the 'onmouseover' CSS attribute, which can cause arbitrary browser activity as soon as the mouse enters into the content window. It is also possible for meta-refresh tags to set timers long enough to make it likely that the user has toggled Tor before fetching content.
The idea behind active testing is to discover vulnerabilities in Torbutton to bypass proxy settings, run script in an opposite Tor state, store unique identifiers, leak location information, or otherwise violate its requirements. Torbutton has ventured out into a strange and new security landscape. It depends on Firefox mechanisms that haven't necessarily been audited for security, certainly not for the threat model that Torbutton seeks to address. As such, it and the interfaces it depends upon still need a 'trial by fire' typical of new technologies. This section of the document was written with the intention of making that period as fast as possible. Please help us get through this period by considering these attacks, playing with them, and reporting what you find (and potentially submitting the test cases back to be run in the standard batch of Torbutton tests.