[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[or-cvs] r21369: {} add torbutton design dir from git. (in website/trunk/torbutton: . design)

Author: phobos
Date: 2009-12-30 21:42:43 -0500 (Wed, 30 Dec 2009)
New Revision: 21369

add torbutton design dir from git.

Added: website/trunk/torbutton/design/CHROME_NOTES
--- website/trunk/torbutton/design/CHROME_NOTES	                        (rev 0)
+++ website/trunk/torbutton/design/CHROME_NOTES	2009-12-31 02:42:43 UTC (rev 21369)
@@ -0,0 +1,120 @@
+- Investigation of Privacy Mode:
+  - Good:
+    - Cookies Cleared+memory only
+    - Cache cleared and memory-only
+    - History not available via javascript or CSS
+    - Safe because currently unsupported:
+      - Geolocation not supported in browser
+      - DOM Storage not supported
+      - HTML5 Storage not supported
+    - Http auth is cleared
+    - Do they have a session store?
+      - Yes. It is disabled.
+    - Form history disabled
+      - But non-private entries still available
+    - Malware and phishing protection
+      - Per-url check?
+        - Doesn't seem like it..
+  - Bad:
+    - RLZ Identifier sent with all queries even in Incognito mode
+      - http://www.google.com/support/chrome/bin/answer.py?hl=en&answer=107684
+    - Flash cookies not cleared
+    - Google gears are still available
+      - Do they have their own storage?
+        - Yes. Completely ignores private mode.
+    - Safebrowsing API key not cleared?
+      - but updates may not happen "under" the incognito window
+    - Desktop resolution available
+    - Browser resolution is available
+    - SSL session keys
+      - Not cleared!
+      - They clear trusted certs tho
+    - Timezone not spoofed
+- Misc Features we definitely need:
+  - Incognito-specific proxy settings
+    - Browser proxy settings currently do not apply immediately
+  - Plugin enable/disable controls
+  - Spoof user agent
+  - Referer alteration API
+  - Autolaunching of remote apps needs to be disabled
+  - API to opt-out of all the opt-in tracking for incognito mode
+  - Cookie API would be nice
+  - Need network.security.ports.banned
+    - http://www.remote.org/jochen/sec/hfpa/hfpa.pdf
+  - Resize windows (content-window side possibly ok)
+- Future investigation
+  - Non-private form history still available
+    - Forms seem to not be auto-filled, but this may be different
+      for some fields?
+  - How evil is google update? will it happen over incognito?
+    - http://en.wikipedia.org/wiki/Google_Updater#Google_Updater
+    - http://en.wikipedia.org/wiki/SRWare_Iron#Differences_from_Chrome
+    - http://foliovision.com/2008/12/09/adwords-ppc-organic-rlz/
+  - Test in more detail with sysinternals for disk writes
+  - What about safebrowsing requests? Can they bypass proxy?
+  - Video tag supports H264 and ogg via ffmpeg
+    - Hrmm.. proxy bypass ability?
+- Test results. Used Incognito Mode with the test suites from:
+  https://www.torproject.org/torbutton/design/#SingleStateTesting
+  - Decloak.net:
+    - Recovers IP and DNS via Java
+    - Recovers IP via flash
+  - Deanonymizer.com
+    - Failed NNTP and FTP quicktime
+  - JohnDo's hated some headers
+  - Mr. T got a lot of shit wrong...
+  - http://labs.isecpartners.com/breadcrumbs/breadcrumbs.html
+- Comparison with Torora
+  - http://github.com/mwenge/torora/tree/master/doc/DESIGN.torora
+  - Good ideas for both chrome and torbutton:
+    - Cache/Cookie expiry every 24hrs
+    - Random preturbation on Date() object..
+      - No longer possible without js hooks :/
+      - Possible if Chrome allows non-delatable shadowing of window.Date()
+        from user scripts. ECMA says it should
+- Incognito Issues:
+  - SSL session keys
+    - Not cleared!
+  - Flash cookies not cleared
+    - Better Privacy? Permissions?
+  - Google gears are still available
+    - Do they have their own storage?
+      - Yes. Completely ignores private mode.
+  - RLZ override/disable for incognito
+  - Opt out of opt-in tracking?
+  - Source code:
+    http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/profile.cc
+- Privacy Enhancing API Wishlist (remove existing items):
+  - http://code.google.com/chrome/extensions/devguide.html
+  - Prefs (copy-on-write for incognito mode)
+    - Incognito-specific proxy settings
+      - Should not be used for safebrowsing or app/addon update
+    - pref to disable autolaunch of apps/warn user
+    - network.security.ports.banned
+    - User agent (that also govern navigator.*)
+      - could be done (better) via http headers and good hook support
+  - Core APIs:
+    - Per-Plugin enable/disable controls
+    - Cookie API
+    - Cache control
+    - HTTP header alteration ("on-modify-request")
+      - Referrer, accept, user agent
+  - Javascript hooks:
+    - http://code.google.com/chrome/extensions/content_scripts.html
+      - Bleh, these suck... Too limited.
+    - ECMA compliance
+    - desktop+screen resolution
+    - Date hooking
+    - navigator.* hooking
+- Posted at:
+  - http://groups.google.com/group/chromium-extensions/t/ceba26ca9e2f6a78

Added: website/trunk/torbutton/design/FF35_AUDIT
--- website/trunk/torbutton/design/FF35_AUDIT	                        (rev 0)
+++ website/trunk/torbutton/design/FF35_AUDIT	2009-12-31 02:42:43 UTC (rev 21369)
@@ -0,0 +1,195 @@
+First pass: Quick Review of Firefox Features
+- Video Tag
+  - Docs:
+    - https://developer.mozilla.org/En/HTML/Element/Audio
+    - https://developer.mozilla.org/En/HTML/Element/Video
+    - https://developer.mozilla.org/En/HTML/Element/Source
+    - https://developer.mozilla.org/En/Manipulating_video_using_canvas
+    - https://developer.mozilla.org/En/nsIDOMHTMLMediaElement
+    - https://developer.mozilla.org/En/Media_formats_supported_by_the_audio_and_video_elements
+    - http://en.flossmanuals.net/TheoraCookbook
+  - nsIContentPolicy is checked on load
+  - Uses NSIChannels for initial load
+  - Wrapped in nsHTMLMediaElement::mDecoder
+    - is nsOggDecoder() or nsWaveDecoder()
+    - liboggplay
+  - Governed by media.* prefs
+  - Preliminary audit shows they do not use the liboggplay tcp functions
+- Geolocation
+  - Wifi:
+    - https://developer.mozilla.org/En/Monitoring_WiFi_access_points
+    - Requires security policy to allow. Then still prompted
+  - navigator.geolocation
+    - Governed by geo.enabled
+    - "2 week access token" is set
+      - geo.wifi.access_token.. Clearing is prob a good idea
+    - http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js
+    - https://developer.mozilla.org/En/Using_geolocation
+- DNS prefetching after toggle
+  - prefetch pref? Always disable for now?
+    - network.dns.disablePrefetch
+    - Also disabled in netwerk/dns/src/nsDNSService2.cpp when manual proxies
+      are set..
+    - This should prevent prefetching of non-tor urls in tor mode..
+    - But the reverse is unclear.
+    - DocShell attribute!!1 YAY
+      - http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell
+      - "Takes effect for the NEXT document loaded...."
+        - Do we win this race? hrmm.. If we do, the tor->nontor direction
+          should also be safe.
+  - Content policy called?
+    - No. See content/html/content/src/nsHTMLDNSPrefetch.cpp
+- Storage
+  - https://developer.mozilla.org/en/Storage
+  - "It is available to trusted callers, meaning extensions and Firefox
+    components only."
+- New content policy
+  - Content Security Policy. Addon-only
+- "Offline resources"
+  - https://developer.mozilla.org/en/Offline_resources_in_Firefox
+  - https://developer.mozilla.org/en/nsIApplicationCache
+  - browser.cache.offline.enable toggles
+  - browser.cache.disk.enable does not apply. Seperate "device".
+  - Does our normal cache clearing mechanism apply?
+    - We call nsICacheService.evictEntries()
+    - May need: nsOfflineCacheDevice::EvictEntries(NULL)
+  - Code is smart enough to behave cleanly if we simply set
+    browser.cache.offline.enable or enable private browsing.
+- Mouse gesture and other new DOM events
+- Fonts
+  - Remote fonts obey content policy. Good.
+  - XXX: Are they cached independent of regular cache? Prob not.
+  - Hrmm can probe for installed fonts:
+    http://remysharp.com/2008/07/08/how-to-detect-if-a-font-is-installed-only-using-javascript/
+    http://www.lalit.org/lab/javascript-css-font-detect
+    http://www.ajaxupdates.com/cssjavascript-font-detector/
+    http://code.google.com/p/jquery-fontavailable/
+- Drag and drop
+  - https://developer.mozilla.org/En/DragDrop/Drag_and_Drop
+  - https://developer.mozilla.org/En/DragDrop/Drag_Operations
+  - https://developer.mozilla.org/En/DragDrop/Dragging_and_Dropping_Multiple_Items
+  - https://developer.mozilla.org/En/DragDrop/Recommended_Drag_Types
+  - https://developer.mozilla.org/En/DragDrop/DataTransfer
+  - Should be no different than normal url handling..
+- Local Storage
+  - https://developer.mozilla.org/en/DOM/Storage#localStorage
+  - Disabled by dom storage pref..
+  - Private browsing mode has its own DB
+    - Memory only?
+  - Disk Avoidance of gStorage and local storage:
+    - mSessionOnly set via nsDOMStorage::CanUseStorage()
+      - Seems to be set to true if cookies are session-only or private
+        browsing mode
+        - Our cookies are NOT session-only with dual cookie jars
+          - but this is ok if we clear the session storage..
+            - XXX: Technically clearing session storage may break
+              sites if cookies remain though
+      - nsDOMStoragePersistentDB not used if mSessionOnly
+  - Can clear with nsDOMStorage::ClearAll() or nsIDOMStorage2::clear()?
+    - These only work for a particular storage. There's both global now
+      and per-origin storage instances
+    - Each docshell has tons of storages for each origin contained in it
+    - Toggling dom.storage.enabled does not clear existing storage
+    - Oh HOT! cookie-changed to clear cookies clears all storages!
+      - happens for both ff3.0 and 3.5 in dom/src/storage/nsDOMStorage.cpp
+  - Conclusion:
+    - can safely enable dom storage
+      - May have minor buggy usability issues unless we preserve it
+        when user is preserving cookies..
+Second Pass: Verification of all Torbutton Assumptions
+- "Better privacy controls"
+  - Basically UI stuff for prefs we set already
+  - address bar search disable option is interesting, but not
+    torbutton's job to toggle. Users will hate us.
+- Private browsing
+  - https://developer.mozilla.org/En/Supporting_private_browsing_mode
+    - We should consider an option (off by default) to enable PBM during
+      toggle
+      - It is a good idea because it will let our users use DOM storage
+        safely and also may cause their plugins and other addons to be
+        safe
+      - Doing it always will cause the user to lose fine-grained control
+        of many settings
+        - Also we'll need to prevent them from leaving without toggling tor
+        - Stuff the emit does (grep for NS_PRIVATE_BROWSING_SWITCH_TOPIC and
+          "private-browsing")
+          - XXX:  clear mozilla.org/security/sdr;1. We should too! Wtf is it??
+            - Neg. Best to let them handle this. Users will be annoyed
+              at having to re-enter their passwords..
+          - They also clear the console service..
+          - Recommend watching private-browsing-cancel-vote and blocking if
+            we are performing a db operation
+            - Maybe we want to block transitions during our toggle for safety
+          - XXX: They also clear general.open_location.last_url
+          - XXX: mozilla.org/permissionmanager
+          - XXX: mozilla.org/content-pref/service
+          - XXX: Sets browser.zoom.siteSpecific to false
+          - Interesting.. They clear their titles.. I wonder if some
+            window managers log titles.. But that level of surveillance is
+            unbeatable..
+            - XXX: Unless there is some way for flash or script to read titles?
+          - They empty the clipboard..
+            - Can js access the clipboard?? ...
+            - Yes, but needs special pref+confirmation box
+              - http://www.dynamic-tools.net/toolbox/copyToClipboard/
+          - They clear cache..
+          - Cookies:
+            - Use in-memory table that is different than their default
+              - This could fuck up our cookie storage options
+              - We could maybe prevent them from getting this
+                event by wrapping nsCookieService::Observe(). Lullz..
+          - NavHistory:
+            - XXX: nsNavHistory::AutoCompleteFeedback() doesn't track
+              awesomebar choices for feedback.. Is this done on disk?
+            - Don't add history entries
+            - We should block this observe event too if we can..
+          - The session store stops storing tabs
+            - We could block this observe
+          - XXX: They expunge private temporary files on exit from PMB
+            - This is not done normally until browser exit or
+              "on-profile-change"
+            - emits browser:purge-domain-data.. Mostly just for session
+              editing it appears
+            - Direct component query for pbs.privateBrowsingEnabled
+              - This is where we have no ability to provide certain option
+                control
+              - browser.js seems to prevent user from allowing blocked
+                popups?
+              - Some items in some places context menu get blocked:
+                - Can't delete items from history? placesContext_deleteHost
+              - nsCookiePermission::InPrivateBrowsing() calls direct
+                - but is irellevant
+              - Form history cannot be saved while in PBM.. :(
+              - User won't be prompted for adding login passwords..
+              - Can't remember prefs on content types
+              - Many components read this value upon init:
+                - This fucks up our observer game if tor starts enabled
+                - NavHistory and cookie and dl manager
+                - We could just wrap the bool on startup and lie
+                  and emit later... :/
+                  - Or! emit an exit and an enter always at startup if tor is
+                    enabled.
+  - Read iSec report
+  - Compare to Chrome
+    - API use cases
+- SessionStore
+  - Has been reworked with observers and write methods. Should use those.
+- security.enable_ssl2 to clear session id
+  - Still cleared
+- browser.sessionstore.max_tabs_undo
+  - Yep.
+- SafeBrowsing Update Key removed on cookie clear still?
+  - Yep.
+- Livemark updates have kill events now
+- Test if nsICertStore is still buggy...
+Third Pass: Exploit Auditing
+- Remote fonts
+- SVG with HTML
+- Javascript threads+locking
+- Ogg theora and vorbis codecs
+- SQLite
+- https://developer.mozilla.org/en/Firefox_3_for_developers

Added: website/trunk/torbutton/design/MozillaBrownBag.odp
(Binary files differ)

Property changes on: website/trunk/torbutton/design/MozillaBrownBag.odp
Added: svn:mime-type
   + application/octet-stream

Added: website/trunk/torbutton/design/MozillaBrownBag.pdf
(Binary files differ)

Property changes on: website/trunk/torbutton/design/MozillaBrownBag.pdf
Added: svn:mime-type
   + application/octet-stream

Added: website/trunk/torbutton/design/build.sh
--- website/trunk/torbutton/design/build.sh	                        (rev 0)
+++ website/trunk/torbutton/design/build.sh	2009-12-31 02:42:43 UTC (rev 21369)
@@ -0,0 +1 @@
+xsltproc  --output index.html.en  --stringparam section.autolabel.max.depth 2 --stringparam  section.autolabel 1 /usr/share/sgml/docbook/xsl-stylesheets-1.75.2/xhtml/docbook.xsl design.xml 

Property changes on: website/trunk/torbutton/design/build.sh
Added: svn:mime-type
   + text/x-sh

Added: website/trunk/torbutton/design/design.xml
(Binary files differ)

Property changes on: website/trunk/torbutton/design/design.xml
Added: svn:mime-type
   + application/xml

Added: website/trunk/torbutton/design/index.html.en
--- website/trunk/torbutton/design/index.html.en	                        (rev 0)
+++ website/trunk/torbutton/design/index.html.en	2009-12-31 02:42:43 UTC (rev 21369)
@@ -0,0 +1,1434 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Torbutton Design Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="Torbutton Design Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>Torbutton Design Documentation</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Perry</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:mikeperry.fscked/org";>mikeperry.fscked/org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">Dec 15 2009</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2510984">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2541734">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2509118">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2513073">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2511168">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#browseroverlay">3.1. Browser Overlay - torbutton.xul</a></span></dt><dt><span class="sect2"><a href="#id2521151">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2524897">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2538737">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2519814">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2519526">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2504564">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2519462">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2542642">5.1. Test Settings</a></span></dt><dt><span class="sect2"><a href="#plugins">5.2. Disable plugins on Tor Usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2536168">5.3. Isolate Dynamic Content to Tor State (crucial)</a></span></dt><dt><span class="sect2"><a href="#jshooks">5.4. Hook Dangerous Javascript</a></span></dt><dt><span class="sect2"><a href="#id2530601">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2513266">5.6. Disable Updates During Tor</a></span></dt><dt><span class="sect2"><a href="#id2505201">5.7. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2505239">5.8. Disable livemarks updates during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2505311">5.9. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2505383">5.10. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2505464">5.11. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2505548">5.12. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2505661">5.13. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2505706">5.14. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2547259">5.15. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2547309">5.16. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2547362">5.17. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2547413">5.18. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2547469">5.19. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2547508">5.20. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2547523">5.21. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2547627">5.22. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2547664">5.23. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id2547718">5.24. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id2547794">5.25. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2547866">5.26. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id2547925">5.27. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id2547990">5.28. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2548164">5.29. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id2548257">5.30. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id2548297">5.31. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#FirefoxSecurity">6.1. Bugs impacting security</a></span></dt><dt><span class="sect2"><a href="#FirefoxWishlist">6.2. Bugs blocking functionality</a></span></dt><dt><span class="sect2"><a href="#FirefoxMiscBugs">6.3. Low Priority Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id2549304">7.2. Multi-state testing</a></span></dt><dt><span class="sect2"><a href="#HackTorbutton">7.3. Active testing (aka How to Hack Torbutton)</a></span></dt></dl></dd></dl></div><div class="sect1" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2510984"></a>1. Introduction</h2></div></div></div><p>
+This document describes the goals, operation, and testing procedures of the
+Torbutton Firefox extension. It is current as of Torbutton 1.2.4.
+  </p><div class="sect2" title="1.1. Adversary Model"><div class="titlepage"><div><div><h3 class="title"><a id="adversary"></a>1.1. Adversary Model</h3></div></div></div><p>
+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.
+   </p><div class="sect3" title="Adversary Goals"><div class="titlepage"><div><div><h4 class="title"><a id="adversarygoals"></a>Adversary Goals</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Bypassing proxy settings</strong></span><p>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.</p></li><li class="listitem"><span class="command"><strong>Correlation of Tor vs Non-Tor Activity</strong></span><p>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.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p>
+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.
+     </p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p>
+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.
+     </p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
+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 <a class="link" href="#fingerprinting">tracking their activities</a>.
+     </p></li><li class="listitem"><span class="command"><strong>History records and other on-disk
+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.
+     </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Positioning"><div class="titlepage"><div><div><h4 class="title"><a id="adversarypositioning"></a>Adversary Capabilities - Positioning</h4></div></div></div><p>
+The adversary can position themselves at a number of different locations in
+order to execute their attacks.
+    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
+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
+     </p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>
+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.
+     </p></li><li class="listitem"><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p>
+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
+     </p></li><li class="listitem"><span class="command"><strong>Physical Access</strong></span><p>
+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.
+     </p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Attacks"><div class="titlepage"><div><div><h4 class="title"><a id="attacks"></a>Adversary Capabilities - Attacks</h4></div></div></div><p>
+The adversary can perform the following attacks from a number of different 
+positions to accomplish various aspects of their goals. It should be noted
+that many of these attacks (especially those involving IP address leakage) are
+often performed by accident by websites that simply have Javascript, dynamic 
+CSS elements, and plugins. Others are performed by adservers seeking to
+correlate users' activity across different IP addresses, and still others are
+performed by malicious agents on the Tor network and at national firewalls.
+    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Inserting Javascript</strong></span><p>
+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 and reveal
+a user's non-Tor IP address. Javascript
+also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/"; target="_top">history disclosure attacks</a>:
+to query the history via the different attributes of 'visited' links to search
+for particular google queries, sites, or even to <a class="ulink" href="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/"; target="_top">profile
+users based on gender and other classifications</a>. Finally,
+Javascript can be used to query the user's timezone via the
+<code class="function">Date()</code> object, and to reduce the anonymity set by querying
+the <code class="function">navigator</code> object for operating system, CPU, locale, 
+and user agent information.
+     </p></li><li class="listitem"><span class="command"><strong>Inserting Plugins</strong></span><p>
+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.
+Sites that have plugin content don't even have to be malicious to obtain a
+Non-Tor IP (it usually leaks by itself), though <a class="ulink" href="http://decloak.net"; target="_top">plenty of active
+exploits</a> are possible as well. In addition, plugins can be used to store unique identifiers that are more
+difficult to clear than standard cookies. 
+<a class="ulink" href="http://epic.org/privacy/cookies/flash.html"; target="_top">Flash-based
+cookies</a> fall into this category, but there are likely numerous other
+     </p></li><li class="listitem"><span class="command"><strong>Inserting CSS</strong></span><p>
+CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
+Non-Tor IP address, via the usage of
+<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/"; target="_top">CSS
+popups</a> - 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 <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi"; target="_top">CSS-only history disclosure
+     </p></li><li class="listitem"><span class="command"><strong>Read and insert cookies</strong></span><p>
+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 <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html"; target="_top">active
+     </p></li><li class="listitem"><span class="command"><strong>Create arbitrary cached content</strong></span><p>
+Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html"; target="_top">store unique
+identifiers</a>. 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.
+     </p></li><li class="listitem"><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser
+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
+<a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html"; target="_top">uniquely
+fingerprint individual users</a>. </p><p>
+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 <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window"; target="_top">window</a> and
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen"; target="_top">window.screen</a>
+objects. Browser window resolution information provides something like
+(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
+information contributes about another factor of 5 (for about 5 resolutions in
+typical use). In addition, the dimensions and position of the desktop taskbar
+are available, which can reveal hints on OS information. This boosts the count
+by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
+and Gnome, and None). Subtracting the browser content window
+size from the browser outer window size provide yet more information.
+Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
+2<sup>3</sup>=8). Interface effects such as titlebar fontsize
+and window manager settings gives a factor of about 9 (say 3 common font sizes
+for the titlebar and 3 common sizes for browser GUI element fonts).
+Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
+2<sup>29</sup>, or a 29 bit identifier based on resolution
+information alone. </p><p>
+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 <a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html"; target="_top">The Hacker
+Webzine article above</a>, minor changes in browser window resolution will
+no longer generate totally new identifiers. 
+To add insult to injury, <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/"; target="_top">chrome URL disclosure
+attacks</a> mean that each and every extension on <a class="ulink" href="https://addons.mozilla.org"; target="_top">addons.mozilla.org</a> adds another bit
+to that 2<sup>29</sup>. 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.
+</p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or
+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.
+     </p></li></ol></div></div></div><div class="sect2" title="1.2. Torbutton Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="requirements"></a>1.2. Torbutton Requirements</h3></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+Since many settings satisfy multiple requirements, this design document is
+organized primarily by Torbutton components and settings. However, if you are
+the type that would rather read the document from the requirements
+perspective, it is in fact possible to search for each of the following
+requirement phrases in the text to find the relevant features that help meet
+that requirement.
+From the above Adversary Model, a number of requirements become clear. 
+   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a id="proxy"></a><span class="command"><strong>Proxy Obedience</strong></span><p>The browser
+MUST NOT bypass Tor proxy settings for any content.</p></li><li class="listitem"><a id="isolation"></a><span class="command"><strong>Network Isolation</strong></span><p>Pages MUST NOT perform any network activity in a Tor state different
+ from the state they were originally loaded in.</p></li><li class="listitem"><a id="state"></a><span class="command"><strong>State Separation</strong></span><p>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
+ one Tor state MUST NOT be accessible via the network in
+ another Tor state.</p></li><li class="listitem"><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>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.</p></li><li class="listitem"><a id="disk"></a><span class="command"><strong>Disk Avoidance</strong></span><p>The browser SHOULD NOT write any Tor-related state to disk, or store it
+ in memory beyond the duration of one Tor toggle.</p></li><li class="listitem"><a id="location"></a><span class="command"><strong>Location Neutrality</strong></span><p>The browser SHOULD NOT leak location-specific information, such as
+ timezone or locale via Tor.</p></li><li class="listitem"><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
+Preservation</strong></span><p>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.
+</p></li><li class="listitem"><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser
+SHOULD NOT perform unauthenticated updates or upgrades via Tor.</p></li><li class="listitem"><a id="interoperate"></a><span class="command"><strong>Interoperability</strong></span><p>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.</p></li></ol></div></div><div class="sect2" title="1.3. Extension Layout"><div class="titlepage"><div><div><h3 class="title"><a id="layout"></a>1.3. Extension Layout</h3></div></div></div><p>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 <a class="ulink" href="https://developer.mozilla.org/en/XPCOM"; target="_top">can be
+written</a> in C++,
+Javascript, or a mixture of both. Components have two identifiers: their
+'<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005"; target="_top">Contract
+ID</a>' (a human readable path-like string), and their '<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329"; target="_top">Class
+ID</a>' (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.</p><p>'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 <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference"; target="_top">XUL</a>.</p></div></div><div class="sect1" title="2. Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2541734"></a>2. Components</h2></div></div></div><p>
+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.
+  </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2509118"></a>2.1. Hooked Components</h3></div></div></div><p>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.</p><div class="sect3" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js"><div class="titlepage"><div><div><h4 class="title"><a id="sessionstore"></a><a class="ulink" href="http://developer.mozilla.org/en/docs/nsISessionStore"; target="_top">@mozilla.org/browser/sessionstore;1</a> -
+<a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js"; target="_top">components/nsSessionStore36.js</a></h4></div></div></div><p>These components address the <a class="link" href="#disk">Disk Avoidance</a>
+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.</p><p>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 <span class="emphasis"><em>entire</em></span>
+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 <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff"; target="_top">diff against the original session
+store</a> is included in the git repository.</p></div><div class="sect3" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="appblocker"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1"; target="_top">@mozilla.org/uriloader/external-protocol-service;1
+</a>, <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1"; target="_top">@mozilla.org/uriloader/external-helper-app-service;1</a>,
+and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1"; target="_top">@mozilla.org/mime;1</a>
+- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js"; target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>
+Due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892"; target="_top">440892</a> allowing Firefox 3.x to automatically launch some
+applications without user intervention, Torbutton had to wrap the three
+components involved in launching external applications to provide user
+confirmation before doing so while Tor is enabled. Since external applications
+do not obey proxy settings, they can be manipulated to automatically connect
+back to arbitrary servers outside of Tor with no user intervention. Fixing
+this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy
+Obedience</a> Requirement.
+ </p></div><div class="sect3" title="@mozilla.org/browser/sessionstartup;1 - components/crash-observer.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2523615"></a><a class="ulink" href="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js"; target="_top">@mozilla.org/browser/sessionstartup;1</a> -
+    <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js"; target="_top">components/crash-observer.js</a></h4></div></div></div><p>This component wraps the Firefox Session Startup component that is in
+charge of <a class="ulink" href="http://developer.mozilla.org/en/docs/Session_store_API"; target="_top">restoring saved
+sessions</a>. The wrapper's only job is to intercept the
+<code class="function">doRestore()</code> 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
+<span class="command"><strong>extensions.torbutton.crashed</strong></span>, or that it is a normal
+startup via the pref <span class="command"><strong>extensions.torbutton.noncrashed</strong></span>. The Torbutton Chrome <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29"; target="_top">listens for a
+preference change</a> 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 (<span class="command"><strong>extensions.torbutton.restore_tor</strong></span>), and
+restoring cookies for the corresponding cookie jar, if it exists.</p><p>By performing this notification, this component assists in the 
+<a class="link" href="#proxy">Proxy Obedience</a>, and <a class="link" href="#isolation">Network Isolation</a> requirements.
+</p></div><div class="sect3" title="@mozilla.org/browser/global-history;2 - components/ignore-history.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2535078"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2"; target="_top">@mozilla.org/browser/global-history;2</a>
+- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js"; target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/"; target="_top">Collin Jackson</a> 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 <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29"; target="_top">isVisited</a>
+and <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29"; target="_top">addURI</a>
+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
+This component helps satisfy the <a class="link" href="#state">State Separation</a>
+and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton.
+</p></div><div class="sect3" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js"><div class="titlepage"><div><div><h4 class="title"><a id="livemarks"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2"; target="_top">@mozilla.org/browser/livemark-service;2</a>
+- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js"; target="_top">components/block-livemarks.js</a></h4></div></div></div><p>
+The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html"; target="_top">livemark</a> service
+is started by a timer that runs 5 seconds after Firefox
+startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
+disable it. We must wrap the component to prevent this start() call from
+firing in the event the browser starts in Tor mode.
+This component helps satisfy the <a class="link" href="#isolation">Network
+Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
+Preservation</a> requirements.
+</p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2513073"></a>2.2. New Components</h3></div></div></div><p>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.</p><div class="sect3" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2541606"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js"; target="_top">@torproject.org/cookie-jar-selector;2
+- components/cookie-jar-selector.js</a></h4></div></div></div><p>The cookie jar selector (also based on code from <a class="ulink" href="http://www.collinjackson.com/"; target="_top">Collin
+Jackson</a>) 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.</p><p>
+This component helps to address the <a class="link" href="#state">State
+Isolation</a> requirement of Torbutton.
+</p></div><div class="sect3" title="@torproject.org/torbutton-logger;1 - components/torbutton-logger.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2528340"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js"; target="_top">@torproject.org/torbutton-logger;1
+- components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
+logging messages to either Firefox stderr
+(<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
+(<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if
+available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
+change the loglevel on the fly by changing
+<span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
+</p></div><div class="sect3" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js"; target="_top">@torproject.org/content-window-mapper;1
+- components/window-mapper.js</a></h4></div></div></div><p>Torbutton tags Firefox <a class="ulink" href="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes"; target="_top">tabs</a> 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 <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser"; target="_top">browser
+tab</a> for a given <a class="ulink" href="https://developer.mozilla.org/en/nsIDOMWindow"; target="_top">HTML content
+window</a>. It does this by traversing all windows and all browsers, until it
+finds the browser with the requested <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow"; target="_top">contentWindow</a> element. Since the content policy
+and page loading in general can generate hundreds of these lookups, this
+result is cached inside the component.
+</p></div><div class="sect3" title="@torproject.org/cssblocker;1 - components/cssblocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js"; target="_top">@torproject.org/cssblocker;1
+- components/cssblocker.js</a></h4></div></div></div><p>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 <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy"; target="_top">nsIContentPolicy</a>.
+When an nsIContentPolicy is registered, Firefox checks every attempted network
+request against its <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()" target="_top">shouldLoad</a>
+member function to determine if the load should proceed. In Torbutton's case,
+the content policy looks up the appropriate browser tab using the <a class="link" href="#windowmapper" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js">window mapper</a>,
+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.</p> This helps to achieve the <a class="link" href="#isolation">Network
+Isolation</a> requirements of Torbutton.
+<p>In addition, the content policy also blocks website javascript from
+<a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/"; target="_top">querying for
+versions and existence of extension chrome</a> while Tor is enabled, and
+also masks the presence of Torbutton to website javascript while Tor is
+disabled. </p><p>
+Finally, some of the work that logically belongs to the content policy is
+instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
+<span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js"; target="_top">torbutton.js</a>. 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 
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014"; target="_top">437014</a> and 
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296"; target="_top">401296</a>).
+This helps to fulfill both the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirements of
+Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2511168"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
+located. Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference"; target="_top">XML file</a>, with zero or more Javascript
+files attached. The scope of these Javascript files is their containing
+window.</p><div class="sect2" title="3.1. Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h3 class="title"><a id="browseroverlay"></a>3.1. Browser Overlay - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul"; target="_top">torbutton.xul</a></h3></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
+bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js"; target="_top">chrome/content/torbutton.js</a>.
+It contains event handlers for preference update, shutdown, upgrade, and
+location change events.</p><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange"; target="_top">location
+change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress"; target="_top">webprogress
+listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most
+important parts of the chrome from a security standpoint. It is a <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener"; target="_top">webprogress
+listener</a> that handles receiving an event every time a page load or
+iframe load occurs. This class eventually calls down to
+<code class="function">torbutton_update_tags()</code> and
+<code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load
+state tags, plugin permissions, and install the Javascript hooks to hook the
+<a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen"; target="_top">window.screen</a>
+object to obfuscate browser and desktop resolution information.
+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
+<code class="function">torbutton_update_status()</code> that aren't governed by any
+Torbutton setting. These are:
+</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Network.security.ports.banned"; target="_top">network.security.ports.banned</a><p>
+Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
+reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) 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 <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
+ </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings"; target="_top">browser.send_pings</a><p>
+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 <a class="link" href="#isolation">Network
+Isolation</a> requirement.
+ </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups"; target="_top">browser.safebrowsing.remoteLookups</a><p>
+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 <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire
+browsing history from ending up on Google's disks.
+ </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled"; target="_top">browser.safebrowsing.enabled</a><p>
+Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387"; target="_top">unauthenticated
+updates under Firefox 2</a>, so it is disabled during Tor usage. 
+This helps fulfill the <a class="link" href="#updates">Update
+Safety</a> requirement. Firefox 3 has the fix for that bug, and so
+safebrowsing updates are enabled during Tor usage.
+ </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29"; target="_top">network.protocol-handler.warn-external.(protocol)</a><p>
+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 <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external
+applications from accessing network resources at the command of Tor-fetched
+pages. Unfortunately, due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a>
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892"; target="_top">440892</a>,
+these prefs are no longer obeyed. They are set still anyway out of respect for
+the dead.
+ </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo"; target="_top">browser.sessionstore.max_tabs_undo</a><p>
+To help satisfy the Torbutton <a class="link" href="#state">State Separation</a>
+and <a class="link" href="#isolation">Network Isolation</a> requirements,
+Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
+"Undo Close" operations from accidentally restoring tabs from a different Tor
+State. This purge is accomplished by setting this preference to 0 and then
+restoring it to the previous user value upon toggle.
+   </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span><p>
+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
+is particularly troublesome now that we have certificate verification in place
+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 <a class="link" href="#state">State Separation Requirement</a>, we currently 
+<span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
+cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134"; target="_top">nsNSSComponent.cpp
+line 2134</a>. This is an arcane and potentially fragile fix. It would be
+better if there were a more standard interface for accomplishing the same
+thing. <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448747"; target="_top">448747</a> has
+been filed for this.
+   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://www.mozilla.com/en-US/firefox/geolocation/"; target="_top">geo.enabled</a></strong></span><p>
+Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
+is enabled. This helps Torbutton maintain its
+<a class="link" href="#location">Location Neutrality</a> requirement.
+While Firefox does prompt before divulging geolocational information,
+the assumption is that Tor users will never want to give their
+location away during Tor usage, and even allowing websites to prompt
+them to do so will only cause confusion and accidents to happen. Moreover,
+just because users may approve a site to know their location in non-Tor mode
+does not mean they want it divulged during Tor mode.
+   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Browser.zoom.siteSpecific"; target="_top">browser.zoom.siteSpecific</a></strong></span><p>
+Firefox actually remembers your zoom settings for certain sites. CSS
+and Javascript rule can use this to recognize previous visitors to a site.
+This helps Torbutton fulfill its <a class="link" href="#state">State Separation</a>
+   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="https://developer.mozilla.org/en/controlling_dns_prefetching"; target="_top">network.dns.disablePrefetch</a></strong></span><p>
+Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
+links on a page to decrease page load latency. While Firefox does typically
+disable this behavior when proxies are enabled, we set this pref for added
+safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
+their links prefetched after a toggle to Non-Tor mode occurs,
+we also set the docShell attribute
+<a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell"; target="_top">
+allowDNSPrefetch</a> to false on Tor loaded tabs. This happens in the same
+positions in the code as those for disabling plugins via the allowPlugins
+docShell attribute. This helps Torbutton fulfill its <a class="link" href="#isolation">Network Isolation</a> requirement.
+   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Browser.cache.offline.enable"; target="_top">browser.cache.offline.enable</a></strong></span><p>
+Firefox has the ability to store web applications in a special cache to allow
+them to continue to operate while the user is offline. Since this subsystem
+is actually different than the normal disk cache, it must be dealt with
+separately. Thus, Torbutton sets this preference to false whenever Tor is
+enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk
+Avoidance</a> and <a class="link" href="#state">State Separation</a>
+   </p></li></ol></div></div><div class="sect2" title="3.2. Preferences Window - preferences.xul"><div class="titlepage"><div><div><h3 class="title"><a id="id2521151"></a>3.2. Preferences Window - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul"; target="_top">preferences.xul</a></h3></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
+handlers located in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js"; target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect2" title="3.3. Other Windows"><div class="titlepage"><div><div><h3 class="title"><a id="id2524897"></a>3.3. Other Windows</h3></div></div></div><p>There are additional windows that describe popups for right clicking on
+the status bar, the toolbutton, and the about page.</p></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2538737"></a>4. Toggle Code Path</h2></div></div></div><p>
+The act of toggling is connected to <code class="function">torbutton_toggle()</code>
+via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul"; target="_top">torbutton.xul</a>
+and <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul"; target="_top">popup.xul</a>
+overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js"; target="_top">torbutton.js</a> 
+Toggling is a 3 stage process: Button Click, Proxy Update, and
+Settings Update. These stages are reflected in the prefs
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
+three stage preference update is to ensure immediate enforcement of <a class="link" href="#isolation">Network Isolation</a> via the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. 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 <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737"; target="_top">Firefox Bug 
+409737</a> unfixed. The content policy does not allow any network activity
+whatsoever during this three stage transition.
+ </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2519814"></a>4.1. Button Click</h3></div></div></div><p>
+This is the first step in the toggling process. When the user clicks the
+toggle button or the toolbar, <code class="function">torbutton_toggle()</code> 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
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
+It is this proxy pref update that gives notification via the <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29"; target="_top">pref
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
+  </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2519526"></a>4.2. Proxy Update</h3></div></div></div><p>
+When Torbutton receives any proxy change notifications via its
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
+<code class="function">torbutton_set_status()</code> which checks against the Tor
+settings to see if the Tor proxy settings match the current settings. If so,
+it calls <code class="function">torbutton_update_status()</code>, which determines if
+the Tor state has actually changed, and sets
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
+state value, and ensures that
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> 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.
+  </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2504564"></a>4.3. Settings Update</h3></div></div></div><p>
+The next stage is also handled by
+<code class="function">torbutton_update_status()</code>. This function sets scores of
+Firefox preferences, saving the original values to prefs under
+<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the history
+clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
+end of its work, it sets
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
+completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
+  </p></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2519462"></a>5. Description of Options</h2></div></div></div><p>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.</p><div class="sect2" title="5.1. Test Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2542642"></a>5.1. Test Settings</h3></div></div></div><p>
+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 <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest"; target="_top">XMLHTTPRequest</a>
+for <a class="ulink" href="https://check.torproject.org/?TorButton=True"; target="_top">https://check.torproject.org/?Torbutton=True</a>.
+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
+<span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
+or <span class="command"><strong>failure</strong></span> to indicate if the
+user hit the page from a Tor IP, a non-Tor IP. This check is handled in
+<code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js"; target="_top">torbutton.js</a>.
+Presenting the results to the user is handled by the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul"; target="_top">preferences
+callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js"; target="_top">preferences.js</a>.  
+  </p></div><div class="sect2" title="5.2. Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="plugins"></a>5.2. Disable plugins on Tor Usage (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html"; target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html"; target="_top">local IP
+address</a> and report it back to the
+remote site. They can also <a class="ulink" href="http://decloak.net"; target="_top">bypass proxy settings</a> 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
+ </p><p>
+Enabling this preference causes the above mentioned Torbutton chrome web progress
+ listener <span class="command"><strong>torbutton_weblistener</strong></span> to disable Java via <span class="command"><strong>security.enable_java</strong></span> and to disable
+ plugins via the browser <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell"; target="_top">docShell</a>
+ attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is
+ created (<code class="function">torbutton_tag_new_browser()</code>), every time a web
+event occurs
+ (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
+ (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
+ prevented from loading by the content policy in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js"; target="_top">@torproject.org/cssblocker;1</a> if Tor is
+ enabled and this option is set.
+ </p><p>All of this turns out to be insufficient if the user directly clicks
+on a plugin-handled mime-type. <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296"; target="_top">In this case</a>,
+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
+<span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> 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.
+ </p><p>
+ All this could be avoided, of course, if Firefox would either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296"; target="_top">obey
+ allowPlugins</a> for directly visited URLs, or notify its content policy for such
+ loads either <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524"; target="_top">via</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556"; target="_top">shouldProcess</a> or shouldLoad. The fact that it does not is
+ not very encouraging.
+ </p><p>
+Since most plugins completely ignore browser proxy settings, the actions
+performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
+ </p></div><div class="sect2" title="5.3. Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2536168"></a>5.3. Isolate Dynamic Content to Tor State (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js"; target="_top">@torproject.org/cssblocker;1</a> content policy
+mentioned above, and causes it to block content load attempts in pages an
+opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser"; target="_top">browser
+tabs</a> are tagged
+with a <span class="command"><strong>__tb_load_state</strong></span> member in
+<code class="function">torbutton_update_tags()</code> and this
+value is compared against the current tor state in the content policy.</p><p>It also kills all Javascript in each page loaded under that state by
+toggling the <span class="command"><strong>allowJavascript</strong></span> <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell"; target="_top">docShell</a> property, and issues a
+<a class="ulink" href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()" target="_top">webNavigation.stop(webNavigation.STOP_ALL)</a> to each browser tab (the
+equivalent of hitting the STOP button).</p><p>
+Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737"; target="_top">Firefox bug
+409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing
+all event handlers, and event handlers registered with <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:element.addEventListener"; target="_top">addEventListener()</a>
+are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content
+Policy</a> 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 <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener"; target="_top">window.opener</a>
+attribute in <code class="function">torbutton_check_progress()</code>. 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 <a class="link" href="#isolation">Network Isolation</a> requirement.
+</p></div><div class="sect2" title="5.4. Hook Dangerous Javascript"><div class="titlepage"><div><div><h3 class="title"><a id="jshooks"></a>5.4. Hook Dangerous Javascript</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js"; target="_top">Javascript
+hooking code</a>. This is done in the chrome in
+<code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
+<a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener"; target="_top">webprogress
+listener</a> <span class="command"><strong>torbutton_weblistener</strong></span> and the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> (the latter being a hack to handle
+javascript: urls).
+In the Firefox 2 days, this option did a lot more than
+it does now. It used to be responsible for timezone and improved useragent
+spoofing, and history object cloaking. However, now it only provides
+obfuscation of the <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen"; target="_top">window.screen</a>
+object to mask your browser and desktop resolution.
+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 <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to
+meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
+requirements. Unfortunately, Gregory Fleischer discovered it is still possible
+to retrieve the original screen values by using <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html"; target="_top">XPCNativeWrapper</a>
+or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html"; target="_top">Components.lookupMethod</a>.
+We are still looking for a workaround as of Torbutton 1.2.4.
+</p></div><div class="sect2" title="5.5. Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2530601"></a>5.5. Resize windows to multiples of 50px during Tor usage (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
+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 <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">browser
+overlay</a>. 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 <code class="function">torbutton_check_round()</code>, called by
+<code class="function">torbutton_update_tags()</code>. 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
+(<code class="function">torbutton_do_resize()</code>) 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 <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
+</p></div><div class="sect2" title="5.6. Disable Updates During Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2513266"></a>5.6. Disable Updates During Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State"; target="_top">Firefox
+update settings</a> during Tor
+  usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
+<span class="command"><strong>app.update.enabled</strong></span>,
+  <span class="command"><strong>app.update.auto</strong></span>, and
+<span class="command"><strong>browser.search.update</strong></span>.  These prevent the
+  browser from updating extensions, checking for Firefox upgrades, and
+  checking for search plugin updates while Tor is enabled.
+  </p><p>
+This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
+</p></div><div class="sect2" title="5.7. Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505201"></a>5.7. Disable Search Suggestions during Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
+This setting causes Torbutton to disable <a class="ulink" href="http://kb.mozillazine.org/Browser.search.suggest.enabled"; target="_top"><span class="command"><strong>browser.search.suggest.enabled</strong></span></a>
+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.
+</p></div><div class="sect2" title="5.8. Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505239"></a>5.8. Disable livemarks updates during Tor usage (recommended)</h3></div></div></div><p>Option:
+   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.disable_livemarks</strong></span></td></tr></table><p>
+  </p><p>
+This option causes Torbutton to prevent Firefox from loading <a class="ulink" href="http://www.mozilla.com/firefox/livebookmarks.html"; target="_top">Livemarks</a> during
+Tor usage. Because people often have very personalized Livemarks (such as RSS
+feeds of Wikipedia articles they maintain, etc). This is accomplished both by
+<a class="link" href="#livemarks" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js">wrapping the livemark-service component</a> and
+by calling stopUpdateLivemarks() on the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2"; target="_top">Livemark
+service</a> when Tor is enabled.
+This helps satisfy the <a class="link" href="#isolation">Network
+Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
+Preservation</a> requirements.
+</p></div><div class="sect2" title="5.9. Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505311"></a>5.9. Block Tor/Non-Tor access to network from file:// urls (recommended)</h3></div></div></div><p>Options:
+   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tor_file_net</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nontor_file_net</strong></span></td></tr></table><p>
+  </p><p>
+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 <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/"; target="_top">submit
+arbitrary files from the local filesystem</a> 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 <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a> to block access to any network
+resources from File urls during the appropriate Tor state.
+This preference helps to ensure Tor's <a class="link" href="#isolation">Network
+Isolation</a> 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.
+</p></div><div class="sect2" title="5.10. Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505383"></a>5.10. Close all Tor/Non-Tor tabs and windows on toggle (optional)</h3></div></div></div><p>Options:
+   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.close_nontor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.close_tor</strong></span></td></tr></table><p>
+  </p><p>
+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
+<code class="function">torbutton_update_status()</code>.  The main reason these settings
+exist is as a backup mechanism in the event of any Javascript or content policy
+leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737"; target="_top">Firefox Bug
+409737</a>.  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 <a class="link" href="#isolation">Network
+Isolation</a> 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 <a class="link" href="#disk">Disk Avoidance</a>
+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.
+</p></div><div class="sect2" title="5.11. Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505464"></a>5.11. Isolate Access to History navigation to Tor state (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
+This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener"; target="_top">nsISHistoryListener</a>
+attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory"; target="_top">sessionHistory</a> of 
+of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation"; target="_top">webNavigatator</a>.
+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. 
+  </p><p>
+This is marked as a crucial setting in part
+because Javascript access to the history object is indistinguishable from 
+user clicks, and because
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737"; target="_top">Firefox Bug
+409737</a> 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.
+   </p><p>
+This setting helps to fulfill Torbutton's <a class="link" href="#state">State
+Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
+   </p></div><div class="sect2" title="5.12. History Access Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2505548"></a>5.12. History Access Settings</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_thread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_thwrite</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthwrite</strong></span></td></tr></table><p>
+  </p><p>These four settings govern the behavior of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js"; target="_top">components/ignore-history.js</a>
+history blocker component mentioned above. By hooking the browser's view of
+the history itself via the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2"; target="_top">@mozilla.org/browser/global-history;2</a>
+and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1"; target="_top">@mozilla.org/browser/nav-history-service;1</a>
+components, this mechanism defeats all document-based <a class="ulink" href="http://whattheinternetknowsaboutyou.com/"; target="_top">history disclosure
+attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi"; target="_top">CSS-only attacks</a>.
+The component also hooks functions involved in writing history to disk via
+both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History"; target="_top">Places
+Database</a> and the older Firefox 2 mechanisms.
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.13. Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2505661"></a>5.13. Clear History During Tor Toggle (optional)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls
+<a class="ulink" href="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29"; target="_top">nsIBrowserHistory.removeAllPages</a>
+and <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory"; target="_top">nsISHistory.PurgeHistory</a>
+for each tab on Tor toggle.</p><p>
+This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.
+</p></div><div class="sect2" title="5.14. Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2505706"></a>5.14. Block Password+Form saving during Tor/Non-Tor</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tforms</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_ntforms</strong></span></td></tr></table><p>
+  </p><p>These settings govern if Torbutton disables
+<span class="command"><strong>browser.formfill.enable</strong></span>
+and <span class="command"><strong>signon.rememberSignons</strong></span> 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 <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.15. Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2547259"></a>5.15. Block Tor disk cache and clear all cache on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
+  </p><p>This option causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29"; target="_top">nsICacheService.evictEntries(0)</a>
+on Tor toggle to remove all entries from the cache. In addition, this setting
+causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable"; target="_top">browser.cache.disk.enable</a> to false.
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.16. Block disk and memory cache during Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2547309"></a>5.16. Block disk and memory cache during Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting
+causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable"; target="_top">browser.cache.memory.enable</a>,
+<a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable"; target="_top">browser.cache.disk.enable</a> and
+<a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache"; target="_top">network.http.use-cache</a> to false during tor usage.
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.17. Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2547362"></a>5.17. Clear Cookies on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
+  </p><p>
+This setting causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29"; target="_top">nsICookieManager.removeAll()</a> on
+every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy"; target="_top">network.cookie.lifetimePolicy</a>
+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 <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.18. Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h3 class="title"><a id="id2547413"></a>5.18. Store Non-Tor cookies in a protected jar</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
+  </p><p>
+This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js"; target="_top">@torproject.org/cookie-jar-selector;2</a> 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 <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy"; target="_top">network.cookie.lifetimePolicy</a>
+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 <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
+</p></div><div class="sect2" title="5.19. Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2547469"></a>5.19. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>
+  </p><p>
+This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js"; target="_top">@torproject.org/cookie-jar-selector;2</a> to store
+both Tor and Non-Tor cookies into protected jars.
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
+</p></div><div class="sect2" title="5.20. Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2547508"></a>5.20. Manage My Own Cookies (dangerous)</h3></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
+cookie prefs all to false.</p></div><div class="sect2" title="5.21. Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2547523"></a>5.21. Disable DOM Storage during Tor usage (crucial)</h3></div></div></div><div class="sect2" title="5.21.1. Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h3 class="title"><a id="id2547525"></a>5.21.1. Do not write Tor/Non-Tor cookies to disk</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.tor_memory_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.nontor_memory_jar</strong></span></td></tr></table><p>
+  </p><p>
+These settings (contributed by arno) cause Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy"; target="_top">network.cookie.lifetimePolicy</a>
+to 2 during the appropriate Tor state, and to store cookies acquired in that
+state into a Javascript
+<a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X"; target="_top">E4X</a>
+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 <a class="link" href="#disk">Disk Avoidance</a>
+</p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span>
+  </p><p>
+This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor
+usage to prevent 
+<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage"; target="_top">DOM Storage</a> from
+  being used to store persistent information across Tor states.</p><p>
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
+</p></div><div class="sect2" title="5.22. Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2547627"></a>5.22. Clear HTTP Auth on Tor Toggle (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
+  </p><p>
+This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager"; target="_top">nsIHttpAuthManager.clearAll()</a>
+every time Tor is toggled.
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
+</p></div><div class="sect2" title="5.23. Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h3 class="title"><a id="id2547664"></a>5.23. Clear cookies on Tor/Non-Tor shutdown</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
+  </p><p> 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 <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown"; target="_top">quit-application-granted</a> event in
+<code class="function">torbutton_uninstall_observer()</code> and use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js"; target="_top">@torproject.org/cookie-jar-selector;2</a>
+to clear out all cookies and all cookie jars upon shutdown.  </p><p>
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
+</p></div><div class="sect2" title="5.24. Reload cookie jar/clear cookies on Firefox crash"><div class="titlepage"><div><div><h3 class="title"><a id="id2547718"></a>5.24. Reload cookie jar/clear cookies on Firefox crash</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.reload_crashed_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr></table><p>
+  </p><p>This is no longer a user visible option, and is enabled by default. In
+the event of a crash, the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js"; target="_top">components/crash-observer.js</a> 
+  component will notify the Chrome (via the
+  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref and a <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29"; target="_top">pref
+observer</a> in
+the chrome that listens for this update), and Torbutton will load the
+  correct jar for the current Tor state via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js"; target="_top">@torproject.org/cookie-jar-selector;2</a>
+  component.</p><p>
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
+</p></div><div class="sect2" title="5.25. On crash recovery or session restored startup, restore via: Tor, Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2547794"></a>5.25. On crash recovery or session restored startup, restore via: Tor, Non-Tor</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.restore_tor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
+  </p><p>This option works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js"; target="_top">crash-observer.js</a> 
+  to set the Tor state after a crash is detected (via the 
+  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref). To confirm for
+false positives (such as session restore failures, upgrade, normal
+session restore, etc), Torbutton also sets the pref
+extensions.torbutton.normal_exit in torbutton_uninstall_observer() during 
+Firefox exit and checks this value as well during startup.  
+Since the Tor state after a Firefox crash is unknown/indeterminate, this
+setting helps to satisfy the <a class="link" href="#state">State Separation</a>
+requirement in the event of Firefox crashes by ensuring all cookies,
+settings and saved sessions are reloaded from a fixed Tor state.
+</p></div><div class="sect2" title="5.26. On normal startup, set state to: Tor, Non-Tor, Shutdown State"><div class="titlepage"><div><div><h3 class="title"><a id="id2547866"></a>5.26. On normal startup, set state to: Tor, Non-Tor, Shutdown State</h3></div></div></div><p>Options:
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.startup_state</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.noncrashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
+  </p><p>This option also works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js"; target="_top">crash-observer.js</a> 
+  to set the Tor state after a normal startup is detected (via the 
+  <span class="command"><strong>extensions.torbutton.noncrashed</strong></span> pref). To confirm for
+false positives
+(such as session restore failures, etc), Torbutton also sets the pref
+extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
+Firefox exit and checks this value as well during startup.
+</p></div><div class="sect2" title="5.27. Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h3 class="title"><a id="id2547925"></a>5.27. Prevent session store from saving Non-Tor/Tor-loaded tabs</h3></div></div></div><p>Options: 
+  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.nonontor_sessionstore</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.notor_sessionstore</strong></span></td></tr></table><p>
+  </p><p>If these options are enabled, the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js"; target="_top">replacement nsSessionStore.js</a>
+  component checks the <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tabs before writing them
+  out. If the tag is from a blocked Tor state, the tab is not written to disk.
+  </p><p>
+This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
+requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
+</p></div><div class="sect2" title="5.28. Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2547990"></a>5.28. Set user agent during Tor usage (crucial)</h3></div></div></div><p>Options:
+   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.set_uagent</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.platform_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.oscpu_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.buildID_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.productsub_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appname_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appversion_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendorSub</strong></span></td></tr></table><p>
+   </p><p>On face, user agent switching appears to be straight-forward in Firefox.
+It provides several options for controlling the browser user agent string:
+<span class="command"><strong>general.appname.override</strong></span>,
+<span class="command"><strong>general.appversion.override</strong></span>,
+<span class="command"><strong>general.platform.override</strong></span>,
+<span class="command"><strong>general.oscpu.override</strong></span>,
+<span class="command"><strong>general.productSub.override</strong></span>,
+<span class="command"><strong>general.buildID.override</strong></span>,
+<span class="command"><strong>general.useragent.override</strong></span>,
+<span class="command"><strong>general.useragent.vendor</strong></span>, and
+<span class="command"><strong>general.useragent.vendorSub</strong></span>. If
+the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is
+true, Torbutton copies all of the other above prefs into their corresponding
+browser preferences during Tor usage.</p><p>
+It also turns out that it is possible to detect the original Firefox version
+by <a class="ulink" href="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/"; target="_top">inspecting
+certain resource:// files</a>. These cases are handled by Torbutton's
+<a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
+This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
+</p></div><div class="sect2" title="5.29. Spoof US English Browser"><div class="titlepage"><div><div><h3 class="title"><a id="id2548164"></a>5.29. Spoof US English Browser</h3></div></div></div><p>Options:
+</p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.spoof_english</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_charset</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_language</strong></span></td></tr></table><p>
+</p><p> This option causes Torbutton to set
+<span class="command"><strong>general.useragent.locale</strong></span>
+<span class="command"><strong>intl.accept_languages</strong></span> to the value specified in
+<span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
+<span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
+<span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
+well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">javascript hooks</a>.
+ </p><p>
+This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and <a class="link" href="#location">Location Neutrality</a> requirements.
+</p></div><div class="sect2" title="5.30. Don't send referrer during Tor Usage"><div class="titlepage"><div><div><h3 class="title"><a id="id2548257"></a>5.30. Don't send referrer during Tor Usage</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_referer</strong></span>
+This option causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer"; target="_top">network.http.sendSecureXSiteReferrer</a> and
+<a class="ulink" href="http://kb.mozillazine.org/Network.http.sendRefererHeader"; target="_top">network.http.sendRefererHeader</a> during Tor usage.</p><p>
+This setting also does not directly satisfy any Torbutton requirement, but
+some may desire to mask their referrer for general privacy concerns.
+</p></div><div class="sect2" title="5.31. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2548297"></a>5.31. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h3></div></div></div><p>Options:
+</p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.jar_certs</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.jar_ca_certs</strong></span></td></tr></table><p>
+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 <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js"; target="_top">chrome/content/torbutton.js</a>,
+which calls <code class="function">torbutton_jar_cert_type()</code> and
+<code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
+the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1"; target="_top">@mozilla.org/security/nsscertcache;1</a>.
+Certificates are deleted from and imported to the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/x509certdb;1"; target="_top">@mozilla.org/security/x509certdb;1</a>.
+The first time this pref is used, a backup of the user's certificates is
+created in their profile directory under the name
+<code class="filename">cert8.db.bak</code>. This file can be copied back to
+<code class="filename">cert8.db</code> 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 <a class="link" href="#state">State
+Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159"; target="_top">Firefox Bug
+435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
+is currently not exposed via the preferences UI.
+</p></div></div><div class="sect1" title="6. Relevant Firefox Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>
+  </p><div class="sect2" title="6.1. Bugs impacting security"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxSecurity"></a>6.1. Bugs impacting security</h3></div></div></div><p>
+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:
+   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=392274"; target="_top">Bug 392274 - Timezone
+config/chrome API</a><p>
+The lack of a config or API to configure the timezone requires Torbutton to
+<a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">insert client content window javascript</a> to hook
+the Date object. Additionally, a way to <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-date.html"; target="_top">remove the Date
+hooks</a> 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. A fix for this has landed in
+Firefox 3.5, but still has not been backported to Firefox 3.0. The lack of an
+easy way to reliably spoof the timezone interferes with Torbutton's ability to
+fulfill its <a class="link" href="#location">Location Neutrality</a> requirement.
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159"; target="_top">Bug 435159 -
+nsNSSCertificateDB::DeleteCertificate has race conditions</a><p>
+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 <a class="link" href="#state">State Separation</a>
+      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737"; target="_top">Bug 409737 -
+javascript.enabled and docShell.allowJavascript do not disable all event
+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 <a class="link" href="#isolation">Network Isolation</a> 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 <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content
+policy</a> 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.
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448743"; target="_top">Bug 448743 -
+Decouple general.useragent.locale from spoofing of navigator.language</a><p>
+Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
+attribute via <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
+these do not work on Firefox 3. It would be ideal to have
+a pref to set this value (something like a
+<span class="command"><strong>general.useragent.override.locale</strong></span>),
+to avoid fragmenting the anonymity set of users of foreign locales. This issue
+impedes Torbutton from fully meeting its <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
+requirement on Firefox 3.
+     </p></li></ol></div></div><div class="sect2" title="6.2. Bugs blocking functionality"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxWishlist"></a>6.2. Bugs blocking functionality</h3></div></div></div><p>
+The following bugs impact Torbutton and similar extensions' functionality.
+   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=445696"; target="_top">Bug 445696 -
+Extensions cannot determine if firefox is fullScreen</a><p>
+The windowState property of <a class="ulink" href="https://developer.mozilla.org/en/XUL/window"; target="_top">ChromeWindows</a> does not accurately reflect the true
+state of the window in some cases on Linux. This causes Torbutton to attempt
+to resize maximized and minimized windows when it should not.
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=290456"; target="_top">Bug 290456 -
+Block/clear Flash MX "cookies" as well</a><p>
+Today, it is possible to allow plugins if you have a transparent proxy such as
+<a class="ulink" href="http://anonymityanywhere.com/incognito/"; target="_top">Incognito</a> to prevent proxy bypass. However, flash cookies can still be used to
+link your Tor and Non-Tor activity, and this reveal your IP to an adversary
+that does so. This can be solved by manually removing your flash cookies (like
+<a class="ulink" href="https://addons.mozilla.org/en-US/firefox/addon/6623"; target="_top">BetterPrivacy</a> does), but
+it would be nice if there was a standard way to do this from a Firefox API.
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869"; target="_top">Bug 417869 -
+Browser context is difficult to obtain from many XPCOM callbacks</a><p>
+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.
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418321"; target="_top">Bug 418321 -
+Components do not expose disk interfaces</a><p>
+Several components currently provide no way of reimplementing their disk
+access to easily satisfy Torbutton's <a class="link" href="#disk">Disk
+Avoidance</a> requirements. Workarounds exist, but they are <a class="link" href="#sessionstore" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js">clunky</a>, and
+some of them involve disabling functionality during Tor usage.
+   </p></li></ol></div></div><div class="sect2" title="6.3. Low Priority Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxMiscBugs"></a>6.3. Low Priority Bugs</h3></div></div></div><p>
+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
+  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435151"; target="_top">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</a><p>
+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.
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892"; target="_top">Bug 440892 -
+network.protocol-handler.warn-external are ignored</a><p>
+Sometime in the Firefox 3 development cycle, the preferences that governed
+warning a user when external apps were launched got disconnected from the code
+that does the launching. Torbutton depended on these prefs to prevent websites
+from launching specially crafted documents and application arguments that
+caused Proxy Bypass. We currently work around this issue by <a class="link" href="#appblocker" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js">wrapping the app launching components</a> to present a
+popup before launching external apps while Tor is enabled. While this works,
+it would be nice if these prefs were either fixed or removed.
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014"; target="_top">Bug 437014 -
+nsIContentPolicy::shouldLoad no longer called for favicons</a><p>
+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 <span class="command"><strong>torbutton_http_observer</strong></span> used for
+blocking full page plugin loads. This seems to work just fine, but is a bit
+    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418986"; target="_top">Bug 418986 - window.screen
+provides a large amount of identifiable information</a><p>
+As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of
+information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen"; target="_top">window.screen</a>.
+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.
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524"; target="_top">Bug 309524</a>
+and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556"; target="_top">Bug
+380556</a> - nsIContentPolicy::shouldProcess is not called.
+     <p>
+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.
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296"; target="_top">Bug 401296 - docShell.allowPlugins
+not honored for direct links</a> (Perhaps subset of <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=282106"; target="_top">Bug 282106</a>?)
+     <p>
+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 <a class="link" href="#isolation">Network Isolation</a>
+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
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448747"; target="_top">Bug 448747 -
+Provide Mechanism to clear TLS Session IDs</a><p>
+As <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">mentioned above</a>, Torbutton currently
+toggles <span class="command"><strong>security.enable_ssl2</strong></span> to clear the SSL
+Session ID cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134"; target="_top">nsNSSComponent.cpp
+line 2134</a>. This is an arcane and potentially fragile fix. It would be
+better if there were a more standard interface for accomplishing the same
+     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598"; target="_top">Bug 419598 - 'var
+Date' is deletable</a><p>
+Based on Page 62 of the <a class="ulink" href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf"; target="_top">ECMA-262
+Javascript spec</a>, it seems like it should be possible to do something
+like the following to prevent the Date object from being unmasked:
+</p><pre class="screen">
+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:
+</p><div class="blockquote"><blockquote class="blockquote">
+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 <span class="emphasis"><em>for all other variables other than ones that shadow system
+variables</em></span>. Some variables (such as
+<span class="command"><strong>window.screen</strong></span>, and <span class="command"><strong>window.history</strong></span>) 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
+<span class="command"><strong>__proto__</strong></span> to copy the original values in the event of a
+delete. This <span class="command"><strong>__proto__</strong></span> hack unfortunately does not work for
+the Date object though.
+     </p></li></ol></div></div></div><div class="sect1" title="7. Testing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="TestPlan"></a>7. Testing</h2></div></div></div><p>
+The purpose of this section is to cover all the known ways that Tor browser
+security can be subverted from a penetration testing 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.
+  </p><div class="sect2" title="7.1. Single state testing"><div class="titlepage"><div><div><h3 class="title"><a id="SingleStateTesting"></a>7.1. Single state testing</h3></div></div></div><p>
+Torbutton is a complicated piece of software. During development, changes to
+one component can affect a whole slough of unrelated features.  A number of
+aggregated test suites exist that can be used to test for regressions in
+Torbutton and to help aid in the development of Torbutton-like addons and
+other privacy modifications of other browsers. Some of these test suites exist
+as a single automated page, while others are a series of pages you must visit
+individually. They are provided here for reference and future regression
+testing, and also in the hope that some brave soul will one day decide to
+combine them into a comprehensive automated test suite.
+     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="http://decloak.net/"; target="_top">Decloak.net</a><p>
+Decloak.net is the canonical source of plugin and external-application based
+proxy-bypass exploits. It is a fully automated test suite maintained by <a class="ulink" href="http://digitaloffense.net/"; target="_top">HD Moore</a> as a service for people to
+use to test their anonymity systems.
+       </p></li><li class="listitem"><a class="ulink" href="http://deanonymizer.com/"; target="_top">Deanonymizer.com</a><p>
+Deanonymizer.com is another automated test suite that tests for proxy bypass
+and other information disclosure vulnerabilities. It is maintained by Kyle
+Williams, the author of <a class="ulink" href="http://www.janusvm.com/"; target="_top">JanusVM</a>
+and <a class="ulink" href="http://www.januspa.com/"; target="_top">JanusPA</a>.
+       </p></li><li class="listitem"><a class="ulink" href="https://www.jondos.de/en/anontest"; target="_top">JonDos
+The <a class="ulink" href="https://www.jondos.de"; target="_top">JonDos people</a> also provide an
+anonymity tester. It is more focused on HTTP headers than plugin bypass, and
+points out a couple of headers Torbutton could do a better job with
+       </p></li><li class="listitem"><a class="ulink" href="http://browserspy.dk"; target="_top">Browserspy.dk</a><p>
+Browserspy.dk provides a tremendous collection of browser fingerprinting and
+general privacy tests. Unfortunately they are only available one page at a
+time, and there is not really solid feedback on good vs bad behavior in
+the test results.
+       </p></li><li class="listitem"><a class="ulink" href="http://analyze.privacy.net/"; target="_top">Privacy
+The Privacy Analyzer provides a dump of all sorts of browser attributes and
+settings that it detects, including some information on your origin IP
+address. Its page layout and lack of good vs bad test result feedback makes it
+not as useful as a user-facing testing tool, but it does provide some
+interesting checks in a single page.
+       </p></li><li class="listitem"><a class="ulink" href="http://ha.ckers.org/mr-t/"; target="_top">Mr. T</a><p>
+Mr. T is a collection of browser fingerprinting and deanonymization exploits
+discovered by the <a class="ulink" href="http://ha.ckers.org"; target="_top">ha.ckers.org</a> crew
+and others. It is also not as user friendly as some of the above tests, but it
+is a useful collection.
+       </p></li><li class="listitem">Gregory Fleischer's <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/"; target="_top">Torbutton</a> and
+<a class="ulink" href="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html"; target="_top">Defcon
+17</a> Test Cases
+       <p>
+Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy
+issues for the past 2 years. He has an excellent collection of all his test
+cases that can be used for regression testing. In his Defcon work, he
+demonstrates ways to infer Firefox version based on arcane browser properties.
+We are still trying to determine the best way to address some of those test
+       </p></li><li class="listitem"><a class="ulink" href="https://torcheck.xenobite.eu/index.php"; target="_top">Xenobite's
+TorCheck Page</a><p>
+This page checks to ensure you are using a valid Tor exit node and checks for
+some basic browser properties related to privacy. It is not very fine-grained
+or complete, but it is automated and could be turned into something useful
+with a bit of work.
+       </p></li></ol></div><p>
+    </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2549304"></a>7.2. Multi-state testing</h3></div></div></div><p>
+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.
+   </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2549316"></a>Cookies and Cache Correlation</h4></div></div></div><p>
+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 <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html"; target="_top">store unique
+identifiers</a>. The default settings of Torbutton should also protect
+against these from persisting across Tor Toggle.
+    </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2549339"></a>Javascript timers and event handlers</h4></div></div></div><p>
+Javascript can set timers and register event handlers in the hopes of fetching
+URLs after the user has toggled Torbutton. 
+    </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2549351"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
+Even if Javascript is disabled, CSS is still able to 
+<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/"; target="_top">create popup-like
+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.
+    </p></div></div><div class="sect2" title="7.3. Active testing (aka How to Hack Torbutton)"><div class="titlepage"><div><div><h3 class="title"><a id="HackTorbutton"></a>7.3. Active testing (aka How to Hack Torbutton)</h3></div></div></div><p>
+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 <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. 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
+   </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2549406"></a>Some suggested vectors to investigate</h4></div></div></div><p>
+    </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Strange ways to register Javascript <a class="ulink" href="http://en.wikipedia.org/wiki/DOM_Events"; target="_top">events</a> and <a class="ulink" href="http://www.devshed.com/c/a/JavaScript/Using-Timers-in-JavaScript/"; target="_top">timeouts</a> should
+be verified to actually be ineffective after Tor has been toggled.</li><li class="listitem">Other ways to cause Javascript to be executed after
+<span class="command"><strong>javascript.enabled</strong></span> has been toggled off.</li><li class="listitem">Odd ways to attempt to load plugins. Kyle Williams has had
+some success with direct loads/meta-refreshes of plugin-handled URLs.</li><li class="listitem">The Date and Timezone hooks should be verified to work with
+crazy combinations of iframes, nested iframes, iframes in frames, frames in
+iframes, and popups being loaded and
+reloaded in rapid succession, and/or from one another. Think race conditions and deep, 
+parallel nesting, involving iframes from both <a class="ulink" href="http://en.wikipedia.org/wiki/Same_origin_policy"; target="_top">same-origin and
+non-same-origin</a> domains.</li><li class="listitem">In addition, there may be alternate ways and other
+methods to query the timezone, or otherwise use some of the Date object's
+methods in combination to deduce the timezone offset. Of course, the author
+tried his best to cover all the methods he could foresee, but it's always good
+to have another set of eyes try it out.</li><li class="listitem">Similarly, is there any way to confuse the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>
+mentioned above to cause it to allow certain types of page fetches? For
+example, it was recently discovered that favicons are not fetched by the
+content, but the chrome itself, hence the content policy did not look up the
+correct window to determine the current Tor tag for the favicon fetch. Are
+there other things that can do this? Popups? Bookmarklets? Active bookmarks? </li><li class="listitem">Alternate ways to store and fetch unique identifiers. For example, <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage"; target="_top">DOM Storage</a>
+caught us off guard. 
+It was
+also discovered by <a class="ulink" href="http://pseudo-flaw.net"; target="_top">Gregory
+Fleischer</a> that <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/"; target="_top">content window access to
+chrome</a> can be used to build <a class="link" href="#fingerprinting">unique
+Are there any other
+arcane or experimental ways that Firefox provides to create and store unique
+identifiers? Or perhaps unique identifiers can be queried or derived from
+properties of the machine/browser that Javascript has access to? How unique
+can these identifiers be?
+     </li><li class="listitem">Is it possible to get the browser to write some history to disk
+(aside from swap) that can be retrieved later? By default, Torbutton should
+write no history, cookie, or other browsing activity information to the
+harddisk.</li><li class="listitem">Do popup windows make it easier to break any of the above
+behavior? Are javascript events still canceled in popups? What about recursive
+popups from Javascript, data, and other funky URL types? What about CSS
+popups? Are they still blocked after Tor is toggled?</li><li class="listitem">Chrome-escalation attacks. The interaction between the
+Torbutton chrome Javascript and the client content window javascript is pretty
+well-defined and carefully constructed, but perhaps there is a way to smuggle
+javascript back in a return value, or otherwise inject network-loaded
+javascript into the chrome (and thus gain complete control of the browser).
+    </p></div></div></div></div></body></html>