remove the dupe design docs for torbutton.
Andrew Lewman

Andrew Lewman commited on 2010-10-18 06:44:36
Zeige 7 geänderte Dateien mit 0 Einfügungen und 4558 Löschungen.

... ...
@@ -1,120 +0,0 @@
1
-- Investigation of Privacy Mode:
2
-  - Good:
3
-    - Cookies Cleared+memory only
4
-    - Cache cleared and memory-only
5
-    - History not available via javascript or CSS
6
-    - Safe because currently unsupported:
7
-      - Geolocation not supported in browser
8
-      - DOM Storage not supported
9
-      - HTML5 Storage not supported
10
-    - Http auth is cleared
11
-    - Do they have a session store?
12
-      - Yes. It is disabled.
13
-    - Form history disabled
14
-      - But non-private entries still available
15
-    - Malware and phishing protection
16
-      - Per-url check?
17
-        - Doesn't seem like it..
18
-  - Bad:
19
-    - RLZ Identifier sent with all queries even in Incognito mode
20
-      - http://www.google.com/support/chrome/bin/answer.py?hl=en&answer=107684
21
-    - Flash cookies not cleared
22
-    - Google gears are still available
23
-      - Do they have their own storage?
24
-        - Yes. Completely ignores private mode.
25
-    - Safebrowsing API key not cleared?
26
-      - but updates may not happen "under" the incognito window
27
-    - Desktop resolution available
28
-    - Browser resolution is available
29
-    - SSL session keys
30
-      - Not cleared!
31
-      - They clear trusted certs tho
32
-    - Timezone not spoofed
33
-
34
-- Misc Features we definitely need:
35
-  - Incognito-specific proxy settings
36
-    - Browser proxy settings currently do not apply immediately
37
-  - Plugin enable/disable controls
38
-  - Spoof user agent
39
-  - Referer alteration API
40
-  - Autolaunching of remote apps needs to be disabled
41
-  - API to opt-out of all the opt-in tracking for incognito mode
42
-  - Cookie API would be nice
43
-  - Need network.security.ports.banned
44
-    - http://www.remote.org/jochen/sec/hfpa/hfpa.pdf
45
-  - Resize windows (content-window side possibly ok)
46
-
47
-- Future investigation
48
-  - Non-private form history still available
49
-    - Forms seem to not be auto-filled, but this may be different
50
-      for some fields?
51
-  - How evil is google update? will it happen over incognito?
52
-    - http://en.wikipedia.org/wiki/Google_Updater#Google_Updater
53
-    - http://en.wikipedia.org/wiki/SRWare_Iron#Differences_from_Chrome
54
-    - http://foliovision.com/2008/12/09/adwords-ppc-organic-rlz/
55
-  - Test in more detail with sysinternals for disk writes
56
-  - What about safebrowsing requests? Can they bypass proxy?
57
-  - Video tag supports H264 and ogg via ffmpeg
58
-    - Hrmm.. proxy bypass ability?
59
-
60
-- Test results. Used Incognito Mode with the test suites from:
61
-  https://www.torproject.org/torbutton/design/#SingleStateTesting
62
-  - Decloak.net:
63
-    - Recovers IP and DNS via Java
64
-    - Recovers IP via flash
65
-  - Deanonymizer.com
66
-    - Failed NNTP and FTP quicktime
67
-  - JohnDo's hated some headers
68
-  - Mr. T got a lot of shit wrong...
69
-  - http://labs.isecpartners.com/breadcrumbs/breadcrumbs.html
70
-
71
-- Comparison with Torora
72
-  - http://github.com/mwenge/torora/tree/master/doc/DESIGN.torora
73
-  - Good ideas for both chrome and torbutton:
74
-    - Cache/Cookie expiry every 24hrs
75
-    - Random preturbation on Date() object..
76
-      - No longer possible without js hooks :/
77
-      - Possible if Chrome allows non-delatable shadowing of window.Date()
78
-        from user scripts. ECMA says it should
79
-
80
-==========================================
81
-
82
-- Incognito Issues:
83
-  - SSL session keys
84
-    - Not cleared!
85
-  - Flash cookies not cleared
86
-    - Better Privacy? Permissions?
87
-  - Google gears are still available
88
-    - Do they have their own storage?
89
-      - Yes. Completely ignores private mode.
90
-  - RLZ override/disable for incognito
91
-  - Opt out of opt-in tracking?
92
-  - Source code:
93
-    http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/profile.cc
94
-
95
-- Privacy Enhancing API Wishlist (remove existing items):
96
-  - http://code.google.com/chrome/extensions/devguide.html
97
-  - Prefs (copy-on-write for incognito mode)
98
-    - Incognito-specific proxy settings
99
-      - Should not be used for safebrowsing or app/addon update
100
-    - pref to disable autolaunch of apps/warn user
101
-    - network.security.ports.banned
102
-    - User agent (that also govern navigator.*)
103
-      - could be done (better) via http headers and good hook support
104
-  - Core APIs:
105
-    - Per-Plugin enable/disable controls
106
-    - Cookie API
107
-    - Cache control
108
-    - HTTP header alteration ("on-modify-request")
109
-      - Referrer, accept, user agent
110
-  - Javascript hooks:
111
-    - http://code.google.com/chrome/extensions/content_scripts.html
112
-      - Bleh, these suck... Too limited.
113
-    - ECMA compliance
114
-    - desktop+screen resolution
115
-    - Date hooking
116
-    - navigator.* hooking
117
-
118
-- Posted at:
119
-  - http://groups.google.com/group/chromium-extensions/t/ceba26ca9e2f6a78
120
-
... ...
@@ -1,195 +0,0 @@
1
-First pass: Quick Review of Firefox Features
2
-- Video Tag
3
-  - Docs:
4
-    - https://developer.mozilla.org/En/HTML/Element/Audio
5
-    - https://developer.mozilla.org/En/HTML/Element/Video
6
-    - https://developer.mozilla.org/En/HTML/Element/Source
7
-    - https://developer.mozilla.org/En/Manipulating_video_using_canvas
8
-    - https://developer.mozilla.org/En/nsIDOMHTMLMediaElement
9
-    - https://developer.mozilla.org/En/Media_formats_supported_by_the_audio_and_video_elements
10
-    - http://en.flossmanuals.net/TheoraCookbook
11
-  - nsIContentPolicy is checked on load
12
-  - Uses NSIChannels for initial load
13
-  - Wrapped in nsHTMLMediaElement::mDecoder
14
-    - is nsOggDecoder() or nsWaveDecoder()
15
-    - liboggplay
16
-  - Governed by media.* prefs
17
-  - Preliminary audit shows they do not use the liboggplay tcp functions
18
-- Geolocation
19
-  - Wifi:
20
-    - https://developer.mozilla.org/En/Monitoring_WiFi_access_points
21
-    - Requires security policy to allow. Then still prompted
22
-  - navigator.geolocation
23
-    - Governed by geo.enabled
24
-    - "2 week access token" is set
25
-      - geo.wifi.access_token.. Clearing is prob a good idea
26
-    - http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js
27
-    - https://developer.mozilla.org/En/Using_geolocation
28
-- DNS prefetching after toggle
29
-  - prefetch pref? Always disable for now?
30
-    - network.dns.disablePrefetch
31
-    - Also disabled in netwerk/dns/src/nsDNSService2.cpp when manual proxies
32
-      are set..
33
-    - This should prevent prefetching of non-tor urls in tor mode..
34
-    - But the reverse is unclear.
35
-    - DocShell attribute!!1 YAY
36
-      - http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell
37
-      - "Takes effect for the NEXT document loaded...."
38
-        - Do we win this race? hrmm.. If we do, the tor->nontor direction
39
-          should also be safe.
40
-  - Content policy called?
41
-    - No. See content/html/content/src/nsHTMLDNSPrefetch.cpp
42
-- Storage
43
-  - https://developer.mozilla.org/en/Storage
44
-  - "It is available to trusted callers, meaning extensions and Firefox
45
-    components only."
46
-- New content policy
47
-  - Content Security Policy. Addon-only
48
-- "Offline resources"
49
-  - https://developer.mozilla.org/en/Offline_resources_in_Firefox
50
-  - https://developer.mozilla.org/en/nsIApplicationCache
51
-  - browser.cache.offline.enable toggles
52
-  - browser.cache.disk.enable does not apply. Seperate "device".
53
-  - Does our normal cache clearing mechanism apply?
54
-    - We call nsICacheService.evictEntries()
55
-    - May need: nsOfflineCacheDevice::EvictEntries(NULL)
56
-  - Code is smart enough to behave cleanly if we simply set
57
-    browser.cache.offline.enable or enable private browsing.
58
-- Mouse gesture and other new DOM events
59
-- Fonts
60
-  - Remote fonts obey content policy. Good.
61
-  - XXX: Are they cached independent of regular cache? Prob not.
62
-  - Hrmm can probe for installed fonts:
63
-    http://remysharp.com/2008/07/08/how-to-detect-if-a-font-is-installed-only-using-javascript/
64
-    http://www.lalit.org/lab/javascript-css-font-detect
65
-    http://www.ajaxupdates.com/cssjavascript-font-detector/
66
-    http://code.google.com/p/jquery-fontavailable/
67
-- Drag and drop
68
-  - https://developer.mozilla.org/En/DragDrop/Drag_and_Drop
69
-  - https://developer.mozilla.org/En/DragDrop/Drag_Operations
70
-  - https://developer.mozilla.org/En/DragDrop/Dragging_and_Dropping_Multiple_Items
71
-  - https://developer.mozilla.org/En/DragDrop/Recommended_Drag_Types
72
-  - https://developer.mozilla.org/En/DragDrop/DataTransfer
73
-  - Should be no different than normal url handling..
74
-- Local Storage
75
-  - https://developer.mozilla.org/en/DOM/Storage#localStorage
76
-  - Disabled by dom storage pref..
77
-  - Private browsing mode has its own DB
78
-    - Memory only?
79
-  - Disk Avoidance of gStorage and local storage:
80
-    - mSessionOnly set via nsDOMStorage::CanUseStorage()
81
-      - Seems to be set to true if cookies are session-only or private
82
-        browsing mode
83
-        - Our cookies are NOT session-only with dual cookie jars
84
-          - but this is ok if we clear the session storage..
85
-            - XXX: Technically clearing session storage may break
86
-              sites if cookies remain though
87
-      - nsDOMStoragePersistentDB not used if mSessionOnly
88
-  - Can clear with nsDOMStorage::ClearAll() or nsIDOMStorage2::clear()?
89
-    - These only work for a particular storage. There's both global now
90
-      and per-origin storage instances
91
-    - Each docshell has tons of storages for each origin contained in it
92
-    - Toggling dom.storage.enabled does not clear existing storage
93
-    - Oh HOT! cookie-changed to clear cookies clears all storages!
94
-      - happens for both ff3.0 and 3.5 in dom/src/storage/nsDOMStorage.cpp
95
-  - Conclusion:
96
-    - can safely enable dom storage
97
-      - May have minor buggy usability issues unless we preserve it
98
-        when user is preserving cookies..
99
-
100
-Second Pass: Verification of all Torbutton Assumptions
101
-- "Better privacy controls"
102
-  - Basically UI stuff for prefs we set already
103
-  - address bar search disable option is interesting, but not
104
-    torbutton's job to toggle. Users will hate us.
105
-- Private browsing
106
-  - https://developer.mozilla.org/En/Supporting_private_browsing_mode
107
-    - We should consider an option (off by default) to enable PBM during
108
-      toggle
109
-      - It is a good idea because it will let our users use DOM storage
110
-        safely and also may cause their plugins and other addons to be
111
-        safe
112
-      - Doing it always will cause the user to lose fine-grained control
113
-        of many settings
114
-        - Also we'll need to prevent them from leaving without toggling tor
115
-        - Stuff the emit does (grep for NS_PRIVATE_BROWSING_SWITCH_TOPIC and
116
-          "private-browsing")
117
-          - XXX:  clear mozilla.org/security/sdr;1. We should too! Wtf is it??
118
-            - Neg. Best to let them handle this. Users will be annoyed
119
-              at having to re-enter their passwords..
120
-          - They also clear the console service..
121
-          - Recommend watching private-browsing-cancel-vote and blocking if
122
-            we are performing a db operation
123
-            - Maybe we want to block transitions during our toggle for safety
124
-          - XXX: They also clear general.open_location.last_url
125
-          - XXX: mozilla.org/permissionmanager
126
-          - XXX: mozilla.org/content-pref/service
127
-          - XXX: Sets browser.zoom.siteSpecific to false
128
-          - Interesting.. They clear their titles.. I wonder if some
129
-            window managers log titles.. But that level of surveillance is
130
-            unbeatable..
131
-            - XXX: Unless there is some way for flash or script to read titles?
132
-          - They empty the clipboard..
133
-            - Can js access the clipboard?? ...
134
-            - Yes, but needs special pref+confirmation box
135
-              - http://www.dynamic-tools.net/toolbox/copyToClipboard/
136
-          - They clear cache..
137
-          - Cookies:
138
-            - Use in-memory table that is different than their default
139
-              - This could fuck up our cookie storage options
140
-              - We could maybe prevent them from getting this
141
-                event by wrapping nsCookieService::Observe(). Lullz..
142
-          - NavHistory:
143
-            - XXX: nsNavHistory::AutoCompleteFeedback() doesn't track
144
-              awesomebar choices for feedback.. Is this done on disk?
145
-            - Don't add history entries
146
-            - We should block this observe event too if we can..
147
-          - The session store stops storing tabs
148
-            - We could block this observe
149
-          - XXX: They expunge private temporary files on exit from PMB
150
-            - This is not done normally until browser exit or
151
-              "on-profile-change"
152
-            - emits browser:purge-domain-data.. Mostly just for session
153
-              editing it appears
154
-            - Direct component query for pbs.privateBrowsingEnabled
155
-              - This is where we have no ability to provide certain option
156
-                control
157
-              - browser.js seems to prevent user from allowing blocked
158
-                popups?
159
-              - Some items in some places context menu get blocked:
160
-                - Can't delete items from history? placesContext_deleteHost
161
-              - nsCookiePermission::InPrivateBrowsing() calls direct
162
-                - but is irellevant
163
-              - Form history cannot be saved while in PBM.. :(
164
-              - User won't be prompted for adding login passwords..
165
-              - Can't remember prefs on content types
166
-              - Many components read this value upon init:
167
-                - This fucks up our observer game if tor starts enabled
168
-                - NavHistory and cookie and dl manager
169
-                - We could just wrap the bool on startup and lie
170
-                  and emit later... :/
171
-                  - Or! emit an exit and an enter always at startup if tor is
172
-                    enabled.
173
-  - Read iSec report
174
-  - Compare to Chrome
175
-    - API use cases
176
-- SessionStore
177
-  - Has been reworked with observers and write methods. Should use those.
178
-- security.enable_ssl2 to clear session id
179
-  - Still cleared
180
-- browser.sessionstore.max_tabs_undo
181
-  - Yep.
182
-- SafeBrowsing Update Key removed on cookie clear still?
183
-  - Yep.
184
-- Livemark updates have kill events now
185
-- Test if nsICertStore is still buggy...
186
-
187
-Third Pass: Exploit Auditing
188
-- Remote fonts
189
-- SVG with HTML
190
-- Javascript threads+locking
191
-- Ogg theora and vorbis codecs
192
-- SQLite
193
-
194
-
195
-- https://developer.mozilla.org/en/Firefox_3_for_developers
... ...
@@ -1 +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 
... ...
@@ -1,2760 +0,0 @@
1
-<?xml version="1.0" encoding="ISO-8859-1"?>
2
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
-     "file:///usr/share/sgml/docbook/xml-dtd-4.4-1.0-30.1/docbookx.dtd">
4
-
5
-<article id="design">
6
- <articleinfo>
7
-  <title>Torbutton Design Documentation</title>
8
-   <author>
9
-    <firstname>Mike</firstname><surname>Perry</surname>
10
-    <affiliation>
11
-     <address><email>mikeperry.fscked/org</email></address>
12
-    </affiliation>
13
-   </author>
14
-   <pubdate>Jun 28 2010</pubdate>
15
- </articleinfo>
16
-
17
-<sect1>
18
-  <title>Introduction</title>
19
-  <para>
20
-
21
-This document describes the goals, operation, and testing procedures of the
22
-Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
23
-
24
-  </para>
25
-  <sect2 id="adversary">
26
-   <title>Adversary Model</title>
27
-   <para>
28
-
29
-A Tor web browser adversary has a number of goals, capabilities, and attack
30
-types that can be used to guide us towards a set of requirements for the
31
-Torbutton extension. Let's start with the goals.
32
-
33
-   </para>
34
-   <sect3 id="adversarygoals">
35
-    <title>Adversary Goals</title>
36
-    <orderedlist>
37
-<!-- These aren't really commands.. But it's the closest I could find in an
38
-acceptable style.. Don't really want to make my own stylesheet -->
39
-     <listitem><command>Bypassing proxy settings</command>
40
-     <para>The adversary's primary goal is direct compromise and bypass of 
41
-Tor, causing the user to directly connect to an IP of the adversary's
42
-choosing.</para>
43
-     </listitem>
44
-     <listitem><command>Correlation of Tor vs Non-Tor Activity</command>
45
-     <para>If direct proxy bypass is not possible, the adversary will likely
46
-happily settle for the ability to correlate something a user did via Tor with
47
-their non-Tor activity. This can be done with cookies, cache identifiers,
48
-javascript events, and even CSS. Sometimes the fact that a user uses Tor may
49
-be enough for some authorities.</para>
50
-     </listitem>
51
-     <listitem><command>History disclosure</command>
52
-     <para>
53
-The adversary may also be interested in history disclosure: the ability to
54
-query a user's history to see if they have issued certain censored search
55
-queries, or visited censored sites.
56
-     </para>
57
-     </listitem>
58
-     <listitem><command>Location information</command>
59
-     <para>
60
-
61
-Location information such as timezone and locality can be useful for the
62
-adversary to determine if a user is in fact originating from one of the
63
-regions they are attempting to control, or to zero-in on the geographical
64
-location of a particular dissident or whistleblower.
65
-
66
-     </para>
67
-     </listitem>
68
-     <listitem><command>Miscellaneous anonymity set reduction</command>
69
-     <para>
70
-
71
-Anonymity set reduction is also useful in attempting to zero in on a
72
-particular individual. If the dissident or whistleblower is using a rare build
73
-of Firefox for an obscure operating system, this can be very useful
74
-information for tracking them down, or at least <link
75
-linkend="fingerprinting">tracking their activities</link>.
76
-
77
-     </para>
78
-     </listitem>
79
-     <listitem><command>History records and other on-disk
80
-information</command>
81
-     <para>
82
-In some cases, the adversary may opt for a heavy-handed approach, such as
83
-seizing the computers of all Tor users in an area (especially after narrowing
84
-the field by the above two pieces of information). History records and cache
85
-data are the primary goals here.
86
-     </para>
87
-     </listitem>
88
-    </orderedlist>
89
-   </sect3>
90
-
91
-   <sect3 id="adversarypositioning">
92
-    <title>Adversary Capabilities - Positioning</title>
93
-    <para>
94
-The adversary can position themselves at a number of different locations in
95
-order to execute their attacks.
96
-    </para>
97
-    <orderedlist>
98
-     <listitem><command>Exit Node or Upstream Router</command>
99
-     <para>
100
-The adversary can run exit nodes, or alternatively, they may control routers
101
-upstream of exit nodes. Both of these scenarios have been observed in the
102
-wild.
103
-     </para>
104
-     </listitem>
105
-     <listitem><command>Adservers and/or Malicious Websites</command>
106
-     <para>
107
-The adversary can also run websites, or more likely, they can contract out
108
-ad space from a number of different adservers and inject content that way. For
109
-some users, the adversary may be the adservers themselves. It is not
110
-inconceivable that adservers may try to subvert or reduce a user's anonymity 
111
-through Tor for marketing purposes.
112
-     </para>
113
-     </listitem>
114
-     <listitem><command>Local Network/ISP/Upstream Router</command>
115
-     <para>
116
-The adversary can also inject malicious content at the user's upstream router
117
-when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
118
-activity.
119
-     </para>
120
-     </listitem>
121
-     <listitem><command>Physical Access</command>
122
-     <para>
123
-Some users face adversaries with intermittent or constant physical access.
124
-Users in Internet cafes, for example, face such a threat. In addition, in
125
-countries where simply using tools like Tor is illegal, users may face
126
-confiscation of their computer equipment for excessive Tor usage or just
127
-general suspicion.
128
-     </para>
129
-     </listitem>
130
-    </orderedlist>
131
-   </sect3>
132
-
133
-   <sect3 id="attacks">
134
-    <title>Adversary Capabilities - Attacks</title>
135
-    <para>
136
-
137
-The adversary can perform the following attacks from a number of different 
138
-positions to accomplish various aspects of their goals. It should be noted
139
-that many of these attacks (especially those involving IP address leakage) are
140
-often performed by accident by websites that simply have Javascript, dynamic 
141
-CSS elements, and plugins. Others are performed by adservers seeking to
142
-correlate users' activity across different IP addresses, and still others are
143
-performed by malicious agents on the Tor network and at national firewalls.
144
-
145
-    </para>
146
-    <orderedlist>
147
-     <listitem><command>Inserting Javascript</command>
148
-     <para>
149
-If not properly disabled, Javascript event handlers and timers
150
-can cause the browser to perform network activity after Tor has been disabled,
151
-thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
152
-a user's non-Tor IP address. Javascript
153
-also allows the adversary to execute <ulink
154
-url="http://whattheinternetknowsaboutyou.com/">history disclosure attacks</ulink>:
155
-to query the history via the different attributes of 'visited' links to search
156
-for particular google queries, sites, or even to <ulink
157
-url="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/">profile
158
-users based on gender and other classifications</ulink>. Finally,
159
-Javascript can be used to query the user's timezone via the
160
-<function>Date()</function> object, and to reduce the anonymity set by querying
161
-the <function>navigator</function> object for operating system, CPU, locale, 
162
-and user agent information.
163
-     </para>
164
-     </listitem>
165
-
166
-     <listitem><command>Inserting Plugins</command>
167
-     <para>
168
-
169
-Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
170
-capable of performing network activity that the author has
171
-investigated is also capable of performing network activity independent of
172
-browser proxy settings - and often independent of its own proxy settings.
173
-Sites that have plugin content don't even have to be malicious to obtain a
174
-user's
175
-Non-Tor IP (it usually leaks by itself), though <ulink
176
-url="http://decloak.net">plenty of active
177
-exploits</ulink> are possible as well. In addition, plugins can be used to store unique identifiers that are more
178
-difficult to clear than standard cookies. 
179
-<ulink url="http://epic.org/privacy/cookies/flash.html">Flash-based
180
-cookies</ulink> fall into this category, but there are likely numerous other
181
-examples.
182
-
183
-     </para>
184
-     </listitem>
185
-     <listitem><command>Inserting CSS</command>
186
-     <para>
187
-
188
-CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
189
-Non-Tor IP address, via the usage of
190
-<ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">CSS
191
-popups</ulink> - essentially CSS-based event handlers that fetch content via
192
-CSS's onmouseover attribute. If these popups are allowed to perform network
193
-activity in a different Tor state than they were loaded in, they can easily
194
-correlate Tor and Non-Tor activity and reveal a user's IP address. In
195
-addition, CSS can also be used without Javascript to perform <ulink
196
-url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only history disclosure
197
-attacks</ulink>.
198
-     </para>
199
-     </listitem>
200
-     <listitem><command>Read and insert cookies</command>
201
-     <para>
202
-
203
-An adversary in a position to perform MITM content alteration can inject
204
-document content elements to both read and inject cookies for
205
-arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
206
-sort of <ulink url="http://seclists.org/bugtraq/2007/Aug/0070.html">active
207
-sidejacking</ulink>.
208
-
209
-     </para>
210
-     </listitem>
211
-     <listitem><command>Create arbitrary cached content</command>
212
-     <para>
213
-
214
-Likewise, the browser cache can also be used to <ulink
215
-url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
216
-identifiers</ulink>. Since by default the cache has no same-origin policy,
217
-these identifiers can be read by any domain, making them an ideal target for
218
-adserver-class adversaries.
219
-
220
-     </para>
221
-     </listitem>
222
-     <listitem id="fingerprinting"><command>Fingerprint users based on browser
223
-attributes</command>
224
-<para>
225
-
226
-There is an absurd amount of information available to websites via attributes
227
-of the browser. This information can be used to reduce anonymity set, or even
228
-<ulink url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">uniquely
229
-fingerprint individual users</ulink>. </para>
230
-<para>
231
-For illustration, let's perform a
232
-back-of-the-envelope calculation on the number of anonymity sets for just the
233
-resolution information available in the <ulink
234
-url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
235
-<ulink
236
-url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>
237
-objects. Browser window resolution information provides something like
238
-(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
239
-information contributes about another factor of 5 (for about 5 resolutions in
240
-typical use). In addition, the dimensions and position of the desktop taskbar
241
-are available, which can reveal hints on OS information. This boosts the count
242
-by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
243
-and Gnome, and None). Subtracting the browser content window
244
-size from the browser outer window size provide yet more information.
245
-Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
246
-2<superscript>3</superscript>=8). Interface effects such as titlebar fontsize
247
-and window manager settings gives a factor of about 9 (say 3 common font sizes
248
-for the titlebar and 3 common sizes for browser GUI element fonts).
249
-Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
250
-2<superscript>29</superscript>, or a 29 bit identifier based on resolution
251
-information alone. </para>
252
-
253
-<para>
254
-
255
-Of course, this space is non-uniform and prone to incremental changes.
256
-However, if a bit vector space consisting of the above extracted attributes
257
-were used instead of the hash approach from <ulink
258
-url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">The Hacker
259
-Webzine article above</ulink>, minor changes in browser window resolution will
260
-no longer generate totally new identifiers. 
261
-
262
-</para>
263
-<para>
264
-
265
-To add insult to injury, <ulink
266
-url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
267
-attacks</ulink> mean that each and every extension on <ulink
268
-url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
269
-to that 2<superscript>29</superscript>. With hundreds of popular extensions
270
-and thousands of extensions total, it is easy to see that this sort of
271
-information is an impressively powerful identifier if used properly by a
272
-competent and determined adversary such as an ad network.  Again, a
273
-nearest-neighbor bit vector space approach here would also gracefully handle
274
-incremental changes to installed extensions.
275
-
276
-</para>
277
-
278
-     </listitem>
279
-     <listitem><command>Remotely or locally exploit browser and/or
280
-OS</command>
281
-     <para>
282
-Last, but definitely not least, the adversary can exploit either general 
283
-browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
284
-install malware and surveillance software. An adversary with physical access
285
-can perform similar actions. Regrettably, this last attack capability is
286
-outside of Torbutton's ability to defend against, but it is worth mentioning
287
-for completeness.
288
-     </para>
289
-     </listitem>
290
-    </orderedlist>
291
-   </sect3>
292
-
293
-  </sect2>
294
-
295
-  <sect2 id="requirements">
296
-   <title>Torbutton Requirements</title>
297
-<note>
298
-
299
-Since many settings satisfy multiple requirements, this design document is
300
-organized primarily by Torbutton components and settings. However, if you are
301
-the type that would rather read the document from the requirements
302
-perspective, it is in fact possible to search for each of the following
303
-requirement phrases in the text to find the relevant features that help meet
304
-that requirement.
305
-
306
-</note>
307
-   <para>
308
-
309
-From the above Adversary Model, a number of requirements become clear. 
310
-
311
-   </para>
312
-
313
-<orderedlist> 
314
-<!-- These aren't really commands.. But it's the closest I could find in an
315
-acceptable style.. Don't really want to make my own stylesheet -->
316
- <listitem id="proxy"><command>Proxy Obedience</command> 
317
- <para>The browser
318
-MUST NOT bypass Tor proxy settings for any content.</para></listitem>
319
- <listitem id="isolation"><command>Network Isolation</command>
320
- <para>Pages MUST NOT perform any network activity in a Tor state different
321
- from the state they were originally loaded in.</para></listitem>
322
- <listitem id="state"><command>State Separation</command>
323
- <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
324
- one Tor state MUST NOT be accessible via the network in
325
- another Tor state.</para></listitem>
326
- <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
327
-the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
328
-users whose network fingerprint does not obviously betray the fact that they
329
-are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
330
-reveal its presence while Tor is disabled.</para></listitem>
331
- <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
332
- in memory beyond the duration of one Tor toggle.</para></listitem>
333
- <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
334
- timezone or locale via Tor.</para></listitem>
335
- <listitem id="setpreservation"><command>Anonymity Set
336
-Preservation</command><para>The browser SHOULD NOT leak any other anonymity set reducing information 
337
- (such as user agent, extension presence, and resolution information)
338
-automatically via Tor. The assessment of the attacks above should make it clear
339
-that anonymity set reduction is a very powerful method of tracking and
340
-eventually identifying anonymous users.
341
-</para></listitem>
342
- <listitem id="updates"><command>Update Safety</command><para>The browser
343
-SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
344
- <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
345
- enable the user to switch between a number of different proxies. It MUST
346
- provide full Tor protection in the event a third-party proxy switcher has
347
- enabled the Tor proxy settings.</para></listitem>
348
-</orderedlist>
349
-  </sect2>
350
-  <sect2 id="layout">
351
-   <title>Extension Layout</title>
352
-
353
-<para>Firefox extensions consist of two main categories of code: 'Components' and
354
-'Chrome'. Components are a fancy name for classes that implement a given
355
-interface or interfaces. In Firefox, components <ulink
356
-url="https://developer.mozilla.org/en/XPCOM">can be
357
-written</ulink> in C++,
358
-Javascript, or a mixture of both. Components have two identifiers: their
359
-'<ulink
360
-url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
361
-ID</ulink>' (a human readable path-like string), and their '<ulink
362
-url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
363
-ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
364
-'Interface ID'. It is possible to 'hook' system components - to reimplement
365
-their interface members with your own wrappers - but only if the rest of the
366
-browser refers to the component by its Contract ID. If the browser refers to
367
-the component by Class ID, it bypasses your hooks in that use case.
368
-Technically, it may be possible to hook Class IDs by unregistering the
369
-original component, and then re-registering your own, but this relies on
370
-obsolete and deprecated interfaces and has proved to be less than
371
-stable.</para>
372
-
373
-<para>'Chrome' is a combination of XML and Javascript used to describe a window.
374
-Extensions are allowed to create 'overlays' that are 'bound' to existing XML
375
-window definitions, or they can create their own windows. The DTD for this XML
376
-is called <ulink
377
-url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
378
-  </sect2>
379
-</sect1>
380
-<sect1>
381
-  <title>Components</title>
382
-  <para>
383
-
384
-Torbutton installs components for two purposes: hooking existing components to
385
-reimplement their interfaces; and creating new components that provide
386
-services to other pieces of the extension.
387
-
388
-  </para>
389
-
390
-  <sect2>
391
-   <title>Hooked Components</title>
392
-
393
-<para>Torbutton makes extensive use of Contract ID hooking, and implements some
394
-of its own standalone components as well.  Let's discuss the hooked components
395
-first.</para>
396
-
397
-<sect3 id="sessionstore">
398
- <title><ulink
399
-url="http://developer.mozilla.org/en/docs/nsISessionStore">@mozilla.org/browser/sessionstore;1</ulink> -
400
-<ulink
401
-url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js">components/nsSessionStore36.js</ulink></title>
402
-
403
-<para>These components address the <link linkend="disk">Disk Avoidance</link>
404
-requirements of Torbutton. As stated in the requirements, Torbutton needs to
405
-prevent Tor tabs from being written to disk by the Firefox session store for a
406
-number of reasons, primary among them is the fact that Firefox can crash at
407
-any time, and a restart can cause you to fetch tabs in the incorrect Tor
408
-state.</para>
409
-
410
-<para>These components illustrate a complication with Firefox hooking: you can
411
-only hook member functions of a class if they are published in an
412
-interface that the class implements. Unfortunately, the sessionstore has no
413
-published interface that is amenable to disabling the writing out of Tor tabs
414
-in specific. As such, Torbutton had to include the <emphasis>entire</emphasis>
415
-nsSessionStore from both Firefox 2.0, 3.0, 3.5 and 3.6
416
-with a couple of modifications to prevent tabs that were loaded with Tor
417
-enabled from being written to disk, and some version detection code to
418
-determine which component to load. The <ulink
419
-url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff">diff against the original session
420
-store</ulink> is included in the git repository.</para>
421
-</sect3>
422
-<sect3 id="appblocker">
423
- <title><ulink
424
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1">@mozilla.org/uriloader/external-protocol-service;1
425
-</ulink>, <ulink
426
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1">@mozilla.org/uriloader/external-helper-app-service;1</ulink>,
427
-and <ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1">@mozilla.org/mime;1</ulink>
428
-- <ulink
429
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
430
- <para>
431
-Due to <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
432
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink> allowing Firefox 3.x to automatically launch some
433
-applications without user intervention, Torbutton had to wrap the three
434
-components involved in launching external applications to provide user
435
-confirmation before doing so while Tor is enabled. Since external applications
436
-do not obey proxy settings, they can be manipulated to automatically connect
437
-back to arbitrary servers outside of Tor with no user intervention. Fixing
438
-this issue helps to satisfy Torbutton's <link linkend="proxy">Proxy
439
-Obedience</link> Requirement.
440
- </para>
441
-</sect3>
442
-<sect3>
443
-<title><ulink
444
-url="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js">@mozilla.org/browser/sessionstartup;1</ulink> -
445
-    <ulink
446
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink></title>
447
-
448
-<para>This component wraps the Firefox Session Startup component that is in
449
-charge of <ulink
450
-url="http://developer.mozilla.org/en/docs/Session_store_API">restoring saved
451
-sessions</ulink>. The wrapper's only job is to intercept the
452
-<function>doRestore()</function> function, which is called by Firefox if it is determined that the
453
-browser crashed and the session needs to be restored. The wrapper notifies the
454
-Torbutton chrome that the browser crashed by setting the pref
455
-<command>extensions.torbutton.crashed</command>, or that it is a normal
456
-startup via the pref <command>extensions.torbutton.noncrashed</command>. The Torbutton Chrome <ulink
457
-url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">listens for a
458
-preference change</ulink> for this value and then does the appropriate cleanup. This
459
-includes setting the Tor state to the one the user selected for crash recovery
460
-in the preferences window (<command>extensions.torbutton.restore_tor</command>), and
461
-restoring cookies for the corresponding cookie jar, if it exists.</para>
462
-
463
-<para>By performing this notification, this component assists in the 
464
-<link linkend="proxy">Proxy Obedience</link>, and <link
465
-linkend="isolation">Network Isolation</link> requirements.
466
-</para>
467
-
468
-
469
-</sect3>
470
-<sect3>
471
-<title><ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
472
-- <ulink
473
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
474
-
475
-<para>This component was contributed by <ulink
476
-url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
477
-CSS and Javascript-based methods of history disclosure. The global-history
478
-component is what is used by Firefox to determine if a link was visited or not
479
-(to apply the appropriate style to the link). By hooking the <ulink
480
-url="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29">isVisited</ulink>
481
-and <ulink 
482
-url="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29">addURI</ulink>
483
-methods, Torbutton is able to selectively prevent history items from being
484
-added or being displayed as visited, depending on the Tor state and the user's
485
-preferences.
486
-</para>
487
-<para>
488
-This component helps satisfy the <link linkend="state">State Separation</link>
489
-and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
490
-</para>
491
-</sect3>
492
-<sect3 id="livemarks">
493
-<title><ulink
494
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">@mozilla.org/browser/livemark-service;2</ulink>
495
-- <ulink
496
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
497
-<para>
498
-
499
-The <ulink
500
-url="http://www.mozilla.com/en-US/firefox/livebookmarks.html">livemark</ulink> service
501
-is started by a timer that runs 5 seconds after Firefox
502
-startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
503
-disable it. We must wrap the component to prevent this start() call from
504
-firing in the event the browser starts in Tor mode.
505
-
506
-</para>
507
-<para>
508
-This component helps satisfy the <link linkend="isolation">Network
509
-Isolation</link> and <link linkend="setpreservation">Anonymity Set
510
-Preservation</link> requirements.
511
-</para>
512
-</sect3>
513
-</sect2>
514
-<sect2>
515
-<title>New Components</title>
516
-
517
-<para>Torbutton creates four new components that are used throughout the
518
-extension. These components do not hook any interfaces, nor are they used
519
-anywhere besides Torbutton itself.</para>
520
-
521
-<sect3>
522
-<title><ulink
523
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2
524
-- components/cookie-jar-selector.js</ulink></title>
525
-
526
-<para>The cookie jar selector (also based on code from <ulink
527
-url="http://www.collinjackson.com/">Collin
528
-Jackson</ulink>) is used by the Torbutton chrome to switch between
529
-Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
530
-move the current cookies.txt file to the appropriate backup location
531
-(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
532
-into place.</para>
533
-
534
-<para>
535
-This component helps to address the <link linkend="state">State
536
-Isolation</link> requirement of Torbutton.
537
-</para>
538
-
539
-</sect3>
540
-<sect3>
541
-<title><ulink
542
-url="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
543
-- components/torbutton-logger.js</ulink></title>
544
-
545
-<para>The torbutton logger component allows on-the-fly redirection of torbutton
546
-logging messages to either Firefox stderr
547
-(<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
548
-(<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
549
-available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
550
-change the loglevel on the fly by changing
551
-<command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
552
-</para>
553
-</sect3>
554
-<sect3 id="windowmapper">
555
-
556
-<title><ulink
557
-url="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
558
-- components/window-mapper.js</ulink></title>
559
-
560
-<para>Torbutton tags Firefox <ulink
561
-url="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes">tabs</ulink> with a special variable that indicates the Tor
562
-state the tab was most recently used under to fetch a page. The problem is
563
-that for many Firefox events, it is not possible to determine the tab that is
564
-actually receiving the event. The Torbutton window mapper allows the Torbutton
565
-chrome and other components to look up a <ulink
566
-url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
567
-tab</ulink> for a given <ulink
568
-url="https://developer.mozilla.org/en/nsIDOMWindow">HTML content
569
-window</ulink>. It does this by traversing all windows and all browsers, until it
570
-finds the browser with the requested <ulink
571
-url="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow">contentWindow</ulink> element. Since the content policy
572
-and page loading in general can generate hundreds of these lookups, this
573
-result is cached inside the component.
574
-</para>
575
-</sect3>
576
-<sect3 id="contentpolicy">
577
-<title><ulink
578
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1
579
-- components/cssblocker.js</ulink></title>
580
-
581
-<para>This is a key component to Torbutton's security measures. When Tor is
582
-toggled, Javascript is disabled, and pages are instructed to stop loading.
583
-However, CSS is still able to perform network operations by loading styles for
584
-onmouseover events and other operations. In addition, favicons can still be
585
-loaded by the browser. The cssblocker component prevents this by implementing
586
-and registering an <ulink
587
-url="https://developer.mozilla.org/en/nsIContentPolicy">nsIContentPolicy</ulink>.
588
-When an nsIContentPolicy is registered, Firefox checks every attempted network
589
-request against its <ulink
590
-url="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()">shouldLoad</ulink>
591
-member function to determine if the load should proceed. In Torbutton's case,
592
-the content policy looks up the appropriate browser tab using the <link
593
-linkend="windowmapper">window mapper</link>,
594
-and checks that tab's load tag against the current Tor state. If the tab was
595
-loaded in a different state than the current state, the fetch is denied.
596
-Otherwise, it is allowed.</para> This helps to achieve the <link
597
-linkend="isolation">Network
598
-Isolation</link> requirements of Torbutton.
599
-
600
-<para>In addition, the content policy also blocks website javascript from
601
-<ulink url="http://pseudo-flaw.net/content/tor/torbutton/">querying for
602
-versions and existence of extension chrome</ulink> while Tor is enabled, and
603
-also masks the presence of Torbutton to website javascript while Tor is
604
-disabled. </para>
605
-
606
-<para>
607
-
608
-Finally, some of the work that logically belongs to the content policy is
609
-instead handled by the <command>torbutton_http_observer</command> and
610
-<command>torbutton_weblistener</command> in <ulink
611
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
612
-Firefox 3 favicon loads, popups, and full page plugins, which for whatever
613
-reason are not passed to the Firefox content policy itself (see Firefox Bugs 
614
-<ulink
615
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and 
616
-<ulink
617
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
618
-
619
-</para>
620
-
621
-<!-- 
622
-FIXME: Hrmm, the content policy doesn't really lend itself well to display 
623
-this way.. People looking for this much detail should consult the source.
624
-
625
-<para>
626
-    <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
627
-    <tgroup cols='5' align='left' colsep='1' rowsep='1'>
628
-       <tbody>
629
-       <row>
630
-         <entry></entry>
631
-         <entry>chrome/resource</entry>
632
-         <entry>a3</entry>
633
-         <entry>a4</entry>
634
-         <entry>a5</entry>
635
-       </row>
636
-       <row>
637
-         <entry>file</entry>
638
-         <entry>b2</entry>
639
-         <entry>b3</entry>
640
-         <entry>b4</entry>
641
-         <entry>b5</entry>
642
-       </row>
643
-       <row>
644
-         <entry>c1</entry>
645
-         <entry>c2</entry>
646
-         <entry>c3</entry>
647
-         <entry>c4</entry>
648
-         <entry>c5</entry>
649
-       </row>
650
-       <row>
651
-         <entry>d1</entry>
652
-         <entry>d2</entry>
653
-         <entry>d3</entry>
654
-         <entry>d4</entry>
655
-         <entry>d5</entry>
656
-       </row>
657
-       </tbody>
658
-       </tgroup>
659
-       </table>
660
-</para>
661
--->
662
-
663
-<para>
664
-
665
-This helps to fulfill both the <link
666
-linkend="setpreservation">Anonymity Set Preservation</link> and the <link
667
-linkend="undiscoverability">Tor Undiscoverability</link> requirements of
668
-Torbutton.</para>
669
-
670
-</sect3>
671
-</sect2>
672
-</sect1>
673
-<sect1>
674
- <title>Chrome</title>
675
-
676
-<para>The chrome is where all the torbutton graphical elements and windows are
677
-located. Each window is described as an <ulink
678
-url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
679
-files attached. The scope of these Javascript files is their containing
680
-window.</para>
681
-
682
-<sect2 id="browseroverlay">
683
-<title>Browser Overlay - <ulink
684
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
685
-
686
-<para>The browser overlay, torbutton.xul, defines the toolbar button, the status
687
-bar, and events for toggling the button. The overlay code is in <ulink
688
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
689
-It contains event handlers for preference update, shutdown, upgrade, and
690
-location change events.</para>
691
-
692
-<para>The <ulink
693
-url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
694
-change</ulink> <ulink
695
-url="https://developer.mozilla.org/en/nsIWebProgress">webprogress
696
-listener</ulink>, <command>torbutton_weblistener</command> is one of the most
697
-important parts of the chrome from a security standpoint. It is a <ulink
698
-url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
699
-listener</ulink> that handles receiving an event every time a page load or
700
-iframe load occurs. This class eventually calls down to
701
-<function>torbutton_update_tags()</function> and
702
-<function>torbutton_hookdoc()</function>, which apply the browser Tor load
703
-state tags, plugin permissions, and install the Javascript hooks to hook the
704
-<ulink
705
-url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
706
-object to obfuscate browser and desktop resolution information.
707
-
708
-</para>
709
-
710
-<para>
711
-The browser overlay helps to satisfy a number of Torbutton requirements. These
712
-are better enumerated in each of the Torbutton preferences below. However,
713
-there are also a number of Firefox preferences set in
714
-<function>torbutton_update_status()</function> that aren't governed by any
715
-Torbutton setting. These are:
716
-</para>
717
-<orderedlist>
718
-
719
-<!--
720
-Not set any more.
721
- <listitem><ulink
722
-url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
723
-<para>
724
-This pref is set in an attempt to disable the fetching of LiveBookmarks via
725
-Tor. Since users can potentially collect a large amount of live bookmarks to
726
-very personal sites (blogs of friends, wikipedia articles they maintain,
727
-comment feeds of their own blog), it is not possible to cleanly isolate these
728
-fetches and they are simply disabled during Tor usage.
729
-This helps to address the <link
730
-linkend="state">State Separation</link> requirement.
731
-Unfortunately <ulink
732
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
733
-436250</ulink> prevents this from
734
-functioning completely correctly.
735
-</para>
736
-  </listitem>
737
--->
738
-
739
- <listitem><ulink
740
-url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
741
- <para>
742
-Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
743
-reads from <command>extensions.torbutton.banned_ports</command>) to the list
744
-of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
745
-and the Tor control port, respectively. This is set for both Tor and Non-Tor
746
-usage, and prevents websites from attempting to do http fetches from these
747
-ports to see if they are open, which addresses the <link
748
-linkend="undiscoverability">Tor Undiscoverability</link> requirement.
749
- </para>
750
- </listitem>
751
- <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
752
- <para>
753
-This setting is currently always disabled. If anyone ever complains saying
754
-that they *want* their browser to be able to send ping notifications to a
755
-page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
756
-my breath. I haven't checked if the content policy is called for pings, but if
757
-not, this setting helps with meeting the <link linkend="isolation">Network
758
-Isolation</link> requirement.
759
- </para>
760
- </listitem>
761
- <listitem><ulink
762
-url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
763
- <para>
764
-Likewise for this setting. I find it hard to imagine anyone who wants to ask
765
-Google in real time if each URL they visit is safe, especially when the list
766
-of unsafe URLs is downloaded anyway. This helps fulfill the <link
767
-linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
768
-browsing history from ending up on Google's disks.
769
- </para>
770
- </listitem>
771
- <listitem><ulink
772
-url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
773
- <para>
774
-Safebrowsing does <ulink
775
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
776
-updates under Firefox 2</ulink>, so it is disabled during Tor usage. 
777
-This helps fulfill the <link linkend="updates">Update
778
-Safety</link> requirement. Firefox 3 has the fix for that bug, and so
779
-safebrowsing updates are enabled during Tor usage.
780
- </para>
781
- </listitem>
782
- <listitem><ulink
783
-url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
784
- <para>
785
-If Tor is enabled, we need to prevent random external applications from
786
-launching without at least warning the user. This group of settings only
787
-partially accomplishes this, however. Applications can still be launched via
788
-plugins. The mechanisms for handling this are described under the "Disable
789
-Plugins During Tor Usage" preference. This helps fulfill the <link
790
-linkend="proxy">Proxy Obedience</link> requirement, by preventing external
791
-applications from accessing network resources at the command of Tor-fetched
792
-pages. Unfortunately, due to <link linkend="FirefoxBugs">Firefox Bug</link>
793
-<ulink
794
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink>,
795
-these prefs are no longer obeyed. They are set still anyway out of respect for
796
-the dead.
797
- </para>
798
-</listitem>
799
-  <listitem><ulink
800
-url="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo">browser.sessionstore.max_tabs_undo</ulink>
801
-   <para>
802
-
803
-To help satisfy the Torbutton <link linkend="state">State Separation</link>
804
-and <link linkend="isolation">Network Isolation</link> requirements,
805
-Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
806
-"Undo Close" operations from accidentally restoring tabs from a different Tor
807
-State. This purge is accomplished by setting this preference to 0 and then
808
-restoring it to the previous user value upon toggle.
809
-
810
-   </para>
811
-  </listitem>
812
-
813
-  <listitem><command>security.enable_ssl2</command>
814
-   <para>
815
-TLS Session IDs can persist for an indefinite duration, providing an
816
-identifier that is sent to TLS sites that can be used to link activity. This
817
-is particularly troublesome now that we have certificate verification in place
818
-in Firefox 3: The OCSP server can use this Session ID to build a history of
819
-TLS sites someone visits, and also correlate their activity as users move from
820
-network to network (such as home to work to coffee shop, etc), inside and
821
-outside of Tor. To handle this and to help satisfy our <link
822
-linkend="state">State Separation Requirement</link>, we currently 
823
-toggle
824
-<command>security.enable_ssl2</command>, which clears the SSL Session ID
825
-cache via the pref observer at <ulink
826
-url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
827
-line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
828
-better if there were a more standard interface for accomplishing the same
829
-thing. <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
830
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">448747</ulink> has
831
-been filed for this.
832
-
833
-   </para>
834
-  </listitem>
835
-
836
-  <listitem><command><ulink url="http://www.mozilla.com/en-US/firefox/geolocation/">geo.enabled</ulink></command>
837
-   <para>
838
-
839
-Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
840
-is enabled. This helps Torbutton maintain its
841
-<link linkend="location">Location Neutrality</link> requirement.
842
-While Firefox does prompt before divulging geolocational information,
843
-the assumption is that Tor users will never want to give their
844
-location away during Tor usage, and even allowing websites to prompt
845
-them to do so will only cause confusion and accidents to happen. Moreover,
846
-just because users may approve a site to know their location in non-Tor mode
847
-does not mean they want it divulged during Tor mode.
848
-
849
-   </para>
850
-  </listitem>
851
-
852
-  <listitem><command><ulink
853
-url="http://kb.mozillazine.org/Browser.zoom.siteSpecific">browser.zoom.siteSpecific</ulink></command>
854
-   <para>
855
-
856
-Firefox actually remembers your zoom settings for certain sites. CSS
857
-and Javascript rule can use this to recognize previous visitors to a site.
858
-This helps Torbutton fulfill its <link linkend="state">State Separation</link>
859
-requirement.
860
-
861
-   </para>
862
-  </listitem>
863
-
864
-  <listitem><command><ulink
865
-url="https://developer.mozilla.org/en/controlling_dns_prefetching">network.dns.disablePrefetch</ulink></command>
866
-   <para>
867
-
868
-Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
869
-links on a page to decrease page load latency. While Firefox does typically
870
-disable this behavior when proxies are enabled, we set this pref for added
871
-safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
872
-their links prefetched after a toggle to Non-Tor mode occurs,
873
-we also set the docShell attribute
874
-<ulink
875
-url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell">
876
-allowDNSPrefetch</ulink> to false on Tor loaded tabs. This happens in the same
877
-positions in the code as those for disabling plugins via the allowPlugins
878
-docShell attribute. This helps Torbutton fulfill its <link
879
-linkend="isolation">Network Isolation</link> requirement.
880
-
881
-   </para>
882
-  </listitem>
883
-
884
-  <listitem><command><ulink
885
-url="http://kb.mozillazine.org/Browser.cache.offline.enable">browser.cache.offline.enable</ulink></command>
886
-   <para>
887
-
888
-Firefox has the ability to store web applications in a special cache to allow
889
-them to continue to operate while the user is offline. Since this subsystem
890
-is actually different than the normal disk cache, it must be dealt with
891
-separately. Thus, Torbutton sets this preference to false whenever Tor is
892
-enabled. This helps Torbutton fulfill its <link linkend="disk">Disk
893
-Avoidance</link> and <link linkend="state">State Separation</link>
894
-requirements.
895
-
896
-   </para>
897
-  </listitem>
898
-
899
-<!-- FIXME: We should make it possible to search for ALL modified FF prefs -->
900
-
901
-</orderedlist>
902
-</sect2>
903
-<sect2>
904
- <title>Preferences Window - <ulink
905
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
906
-
907
-<para>The preferences window of course lays out the Torbutton preferences, with
908
-handlers located in <ulink
909
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
910
-</sect2>
911
-<sect2>
912
- <title>Other Windows</title>
913
-
914
-<para>There are additional windows that describe popups for right clicking on
915
-the status bar, the toolbutton, and the about page.</para>
916
-
917
-</sect2>
918
-</sect1>
919
-
920
-<sect1>
921
- <title>Toggle Code Path</title>
922
- <para>
923
-
924
-The act of toggling is connected to <function>torbutton_toggle()</function>
925
-via the <ulink
926
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
927
-and <ulink
928
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul">popup.xul</ulink>
929
-overlay files. Most of the work in the toggling process is present in <ulink
930
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink> 
931
-
932
-</para>
933
-<para>
934
-
935
-Toggling is a 3 stage process: Button Click, Proxy Update, and
936
-Settings Update. These stages are reflected in the prefs
937
-<command>extensions.torbutton.tor_enabled</command>,
938
-<command>extensions.torbutton.proxies_applied</command>, and
939
-<command>extensions.torbutton.settings_applied</command>. The reason for the
940
-three stage preference update is to ensure immediate enforcement of <link
941
-linkend="isolation">Network Isolation</link> via the <link
942
-linkend="contentpolicy">content policy</link>. Since the content window
943
-javascript runs on a different thread than the chrome javascript, it is
944
-important to properly convey the stages to the content policy to avoid race
945
-conditions and leakage, especially with <ulink
946
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
947
-409737</ulink> unfixed. The content policy does not allow any network activity
948
-whatsoever during this three stage transition.
949
-
950
- </para>
951
- <sect2>
952
-  <title>Button Click</title>
953
-  <para>
954
-
955
-This is the first step in the toggling process. When the user clicks the
956
-toggle button or the toolbar, <function>torbutton_toggle()</function> is
957
-called. This function checks the current Tor status by comparing the current
958
-proxy settings to the selected Tor settings, and then sets the proxy settings
959
-to the opposite state, and sets the pref
960
-<command>extensions.torbutton.tor_enabled</command> to reflect the new state.
961
-It is this proxy pref update that gives notification via the <ulink
962
-url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
963
-observer</ulink>
964
-<command>torbutton_unique_pref_observer</command> to perform the rest of the
965
-toggle.
966
-
967
-  </para>
968
- </sect2>
969
- <sect2>
970
-  <title>Proxy Update</title>
971
-  <para>
972
-
973
-When Torbutton receives any proxy change notifications via its
974
-<command>torbutton_unique_pref_observer</command>, it calls
975
-<function>torbutton_set_status()</function> which checks against the Tor
976
-settings to see if the Tor proxy settings match the current settings. If so,
977
-it calls <function>torbutton_update_status()</function>, which determines if
978
-the Tor state has actually changed, and sets
979
-<command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
980
-state value, and ensures that
981
-<command>extensions.torbutton.tor_enabled</command> is also set to the correct
982
-value. This is decoupled from the button click functionalty via the pref
983
-observer so that other addons (such as SwitchProxy) can switch the proxy
984
-settings between multiple proxies.
985
-
986
-  </para>
987
- </sect2>
988
- <sect2>
989
-  <title>Settings Update</title>
990
-  <para>
991
-
992
-The next stage is also handled by
993
-<function>torbutton_update_status()</function>. This function sets scores of
994
-Firefox preferences, saving the original values to prefs under
995
-<command>extensions.torbutton.saved.*</command>, and performs the history
996
-clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
997
-end of its work, it sets
998
-<command>extensions.torbutton.settings_applied</command>, which signifies the
999
-completion of the toggle operation to the <link
1000
-linkend="contentpolicy">content policy</link>.
1001
-
1002
-  </para>
1003
- </sect2>
1004
-</sect1>
1005
-
1006
-<sect1>
1007
- <title>Description of Options</title>
1008
-<!-- FIXME: Review+update these during FF3.5 audit -->
1009
-<para>This section provides a detailed description of Torbutton's options. Each
1010
-option is presented as the string from the preferences window, a summary, the
1011
-preferences it touches, and the effect this has on the components, chrome, and
1012
-browser properties.</para>
1013
- <sect2>
1014
-  <title>Test Settings</title>
1015
-  <para>
1016
-This button under the Proxy Settings tab provides a way to verify that the 
1017
-proxy settings are correct, and actually do route through the Tor network. It
1018
-performs this check by issuing an <ulink
1019
-url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
1020
-for <ulink
1021
-url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
1022
-This is a special page that returns very simple, yet well-formed XHTML that
1023
-Torbutton can easily inspect for a hidden link with an id of
1024
-<command>TorCheckResult</command> and a target of <command>success</command>
1025
-or <command>failure</command> to indicate if the
1026
-user hit the page from a Tor IP, a non-Tor IP. This check is handled in
1027
-<function>torbutton_test_settings()</function> in <ulink
1028
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>.
1029
-Presenting the results to the user is handled by the <ulink
1030
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul">preferences
1031
-window</ulink>
1032
-callback <function>torbutton_prefs_test_settings()</function> in <ulink
1033
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js">preferences.js</ulink>.  
1034
-
1035
-  </para>
1036
- </sect2>
1037
- <sect2 id="plugins">
1038
-  <title>Disable plugins on Tor Usage (crucial)</title>
1039
- <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
1040
-
1041
- <para>Java and plugins <ulink
1042
-url="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html">can query</ulink> the <ulink
1043
-url="http://www.rgagnon.com/javadetails/java-0095.html">local IP
1044
-address</ulink> and report it back to the
1045
-remote site. They can also <ulink
1046
-url="http://decloak.net">bypass proxy settings</ulink> and directly connect to a
1047
-remote site without Tor. Every browser plugin we have tested with Firefox has
1048
-some form of network capability, and every one ignores proxy settings or worse - only
1049
-partially obeys them. This includes but is not limited to:
1050
-QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
1051
-Flash. 
1052
-
1053
- </para>
1054
- <para>
1055
-Enabling this preference causes the above mentioned Torbutton chrome web progress
1056
- listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
1057
- plugins via the browser <ulink
1058
- url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink>
1059
- attribute <command>allowPlugins</command>. These flags are set every time a new window is
1060
- created (<function>torbutton_tag_new_browser()</function>), every time a web
1061
-load
1062
-event occurs
1063
- (<function>torbutton_update_tags()</function>), and every time the tor state is changed
1064
- (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
1065
- prevented from loading by the content policy in <ulink
1066
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
1067
- enabled and this option is set.
1068
- </para>
1069
-
1070
- <para>All of this turns out to be insufficient if the user directly clicks
1071
-on a plugin-handled mime-type. <ulink
1072
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">In this case</ulink>,
1073
-the browser decides that maybe it should ignore all these other settings and
1074
-load the plugin anyways, because maybe the user really did want to load it
1075
-(never mind this same load-style could happen automatically  with meta-refresh
1076
-or any number of other ways..). To handle these cases, Torbutton stores a list
1077
-of plugin-handled mime-types, and sets the pref
1078
-<command>plugin.disable_full_page_plugin_for_types</command> to this list.
1079
-Additionally, (since nothing can be assumed when relying on Firefox
1080
-preferences and internals) if it detects a load of one of them from the web
1081
-progress listener, it cancels the request, tells the associated DOMWindow to
1082
-stop loading, clears the document, AND throws an exception. Anything short of
1083
-all this and the plugin managed to find some way to load.
1084
- </para>
1085
-
1086
-<!--
1087
-
1088
-FIXME: Hrmm, technically this behavior is not covered by this pref.
1089
-
1090
- <para>
1091
-Furthermore, with version 3.0 and above, Firefox
1092
-<ulink
1093
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">began ignoring</ulink>
1094
-
1095
-<ulink
1096
-url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
1097
-prefs, which caused us to have to <link linkend="appblocker">wrap the external
1098
-app launcher components</link> to prevent external apps from being loaded to
1099
-bypass proxy settings.
1100
- </para>
1101
--->
1102
-
1103
- <para>
1104
- All this could be avoided, of course, if Firefox would either <ulink
1105
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
1106
- allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
1107
- loads either <ulink
1108
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
1109
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
1110
- not very encouraging.
1111
- </para>
1112
-
1113
-
1114
- <para>
1115
-
1116
-Since most plugins completely ignore browser proxy settings, the actions
1117
-performed by this setting are crucial to satisfying the <link
1118
-linkend="proxy">Proxy Obedience</link> requirement.
1119
-
1120
- </para>
1121
-</sect2>
1122
-<sect2>
1123
- <title>Isolate Dynamic Content to Tor State (crucial)</title>
1124
-
1125
- <para>Option: <command>extensions.torbutton.isolate_content</command></para>
1126
-
1127
-<para>Enabling this preference is what enables the <ulink
1128
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
1129
-mentioned above, and causes it to block content load attempts in pages an
1130
-opposite Tor state from the current state. Freshly loaded <ulink
1131
-url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
1132
-tabs</ulink> are tagged
1133
-with a <command>__tb_load_state</command> member in
1134
-<function>torbutton_update_tags()</function> and this
1135
-value is compared against the current tor state in the content policy.</para>
1136
-
1137
-<para>It also kills all Javascript in each page loaded under that state by
1138
-toggling the <command>allowJavascript</command> <ulink
1139
-url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink> property, and issues a
1140
-<ulink
1141
-url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
1142
-equivalent of hitting the STOP button).</para>
1143
-
1144
-<para>
1145
-
1146
-Unfortunately, <ulink
1147
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
1148
-409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
1149
-all event handlers, and event handlers registered with <ulink
1150
-url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
1151
-are still able to execute. The <link linkend="contentpolicy">Torbutton Content
1152
-Policy</link> should prevent such code from performing network activity within
1153
-the current tab, but activity that happens via a popup window or via a
1154
-Javascript redirect can still slip by. For this reason, Torbutton blocks
1155
-popups by checking for a valid <ulink
1156
-url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
1157
-attribute in <function>torbutton_check_progress()</function>. If the window
1158
-has an opener from a different Tor state, its load is blocked. The content
1159
-policy also takes similar action to prevent Javascript redirects. This also
1160
-has the side effect/feature of preventing the user from following any links
1161
-from a page loaded in an opposite Tor state.
1162
-
1163
-</para>
1164
-
1165
-<para>
1166
-This setting is responsible for satisfying the <link
1167
-linkend="isolation">Network Isolation</link> requirement.
1168
-</para>
1169
-
1170
-</sect2>
1171
-<sect2 id="jshooks">
1172
-
1173
-<title>Hook Dangerous Javascript</title>
1174
-
1175
- <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
1176
-
1177
-<para>This setting enables injection of the <ulink
1178
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js">Javascript
1179
-hooking code</ulink>. This is done in the chrome in
1180
-<function>torbutton_hookdoc()</function>, which is called ultimately by both the 
1181
-<ulink
1182
-url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
1183
-listener</ulink> <command>torbutton_weblistener</command> and the <link
1184
-linkend="contentpolicy">content policy</link> (the latter being a hack to handle
1185
-javascript: urls).
1186
-
1187
-In the Firefox 2 days, this option did a lot more than
1188
-it does now. It used to be responsible for timezone and improved useragent
1189
-spoofing, and history object cloaking. However, now it only provides
1190
-obfuscation of the <ulink
1191
-url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
1192
-object to mask your browser and desktop resolution.
1193
-The resolution hooks
1194
-effectively make the Firefox browser window appear to websites as if the renderable area
1195
-takes up the entire desktop, has no toolbar or other GUI element space, and
1196
-the desktop itself has no toolbars.
1197
-These hooks drastically reduce the amount of information available to do <link
1198
-linkend="fingerprinting">anonymity set reduction attacks</link> and help to
1199
-meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
1200
-requirements. Unfortunately, Gregory Fleischer discovered it is still possible
1201
-to retrieve the original screen values by using <ulink
1202
-url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
1203
-or <ulink
1204
-url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.
1205
-We are still looking for a workaround as of Torbutton 1.2.5.
1206
-
1207
-<!-- FIXME: Don't forget to update this -->
1208
-
1209
-</para>
1210
-</sect2>
1211
-<sect2>
1212
-<title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
1213
-
1214
- <para>Option: <command>extensions.torbutton.resize_windows</command></para>
1215
-
1216
-<para>
1217
-
1218
-This option drastically cuts down on the number of distinct anonymity sets
1219
-that divide the Tor web userbase. Without this setting, the dimensions for a
1220
-typical browser window range from 600-1200 horizontal pixels and 400-1000
1221
-vertical pixels, or about 600x600 = 360000 different sets. Resizing the
1222
-browser window to multiples of 50 on each side reduces the number of sets by
1223
-50^2, bringing the total number of sets to 144. Of course, the distribution
1224
-among these sets are not uniform, but scaling by 50 will improve the situation
1225
-due to this non-uniformity for users in the less common resolutions.
1226
-Obviously the ideal situation would be to lie entirely about the browser
1227
-window size, but this will likely cause all sorts of rendering issues, and is
1228
-also not implementable in a foolproof way from extension land.
1229
-
1230
-</para>
1231
-<para>
1232
-
1233
-The implementation of this setting is spread across a couple of different
1234
-locations in the Torbutton javascript <link linkend="browseroverlay">browser
1235
-overlay</link>. Since resizing minimized windows causes them to be restored,
1236
-and since maximized windows remember their previous size to the pixel, windows
1237
-must be resized before every document load (at the time of browser tagging)
1238
-via <function>torbutton_check_round()</function>, called by
1239
-<function>torbutton_update_tags()</function>. To prevent drift, the extension
1240
-tracks the original values of the windows and uses this to perform the
1241
-rounding on document load. In addition, to prevent the user from resizing a
1242
-window to a non-50px multiple, a resize listener
1243
-(<function>torbutton_do_resize()</function>) is installed on every new browser
1244
-window to record the new size and round it to a 50px multiple while Tor is
1245
-enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
1246
-are set. This ensures that there is no discrepancy between the 50 pixel cutoff
1247
-and the actual renderable area of the browser (so that it is not possible to
1248
-infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
1249
-
1250
-</para>
1251
-<para>
1252
-This setting helps to meet the <link
1253
-linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1254
-</para>
1255
-</sect2>
1256
-<sect2>
1257
-<title>Disable Updates During Tor</title>
1258
-
1259
-  <para>Option: <command>extensions.torbutton.no_updates</command></para>
1260
-
1261
-  <para>This setting causes Torbutton to disable the four <ulink
1262
-url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
1263
-update settings</ulink> during Tor
1264
-  usage: <command>extensions.update.enabled</command>,
1265
-<command>app.update.enabled</command>,
1266
-  <command>app.update.auto</command>, and
1267
-<command>browser.search.update</command>.  These prevent the
1268
-  browser from updating extensions, checking for Firefox upgrades, and
1269
-  checking for search plugin updates while Tor is enabled.
1270
-  </para>
1271
-<para>
1272
-This setting satisfies the <link
1273
-linkend="updates">Update Safety</link> requirement.
1274
-</para>
1275
-</sect2>
1276
-<sect2>
1277
-<title>Redirect Torbutton Updates Via Tor (recommended)</title>
1278
-
1279
-  <para>Option: <command>extensions.torbutton.update_torbutton_via_tor</command></para>
1280
-
1281
-  <para>This setting causes Torbutton to install an
1282
-
1283
-<ulink
1284
-url="https://developer.mozilla.org/en/nsIProtocolProxyFilter">nsIProtocolProxyFilter</ulink>
1285
-in order to redirect all version update checks and Torbutton update downloads
1286
-via Tor, regardless of if Tor is enabled or not. This was done both to address
1287
-concerns about data retention done by <ulink
1288
-url="https://www.addons.mozilla.org">addons.mozilla.org</ulink>, as well as to
1289
-help censored users meet the <link linkend="undiscoverability">Tor
1290
-Undiscoverability</link> requirement.
1291
-
1292
-  </para>
1293
-</sect2>
1294
-
1295
-<sect2>
1296
-
1297
-<title>Disable Search Suggestions during Tor (recommended)</title>
1298
-
1299
-  <para>Option: <command>extensions.torbutton.no_search</command></para>
1300
-
1301
-<para>
1302
-This setting causes Torbutton to disable <ulink
1303
-url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1304
-during Tor usage.
1305
-This governs if you get Google search suggestions during Tor
1306
-usage. Your Google cookie is transmitted with google search suggestions, hence
1307
-this is recommended to be disabled.
1308
-
1309
-</para>
1310
-<para>
1311
-While this setting doesn't satisfy any Torbutton requirements, the fact that
1312
-cookies are transmitted for partially typed queries does not seem desirable
1313
-for Tor usage.
1314
-</para>
1315
-</sect2>
1316
-<sect2>
1317
-<title>Disable livemarks updates during Tor usage (recommended)</title>
1318
-  <para>Option:
1319
-   <simplelist>
1320
-   <member><command>extensions.torbutton.disable_livemarks</command></member>
1321
-   </simplelist>
1322
-  </para>
1323
-
1324
-<para>
1325
-This option causes Torbutton to prevent Firefox from loading <ulink
1326
-url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
1327
-Tor usage. Because people often have very personalized Livemarks (such as RSS
1328
-feeds of Wikipedia articles they maintain, etc). This is accomplished both by
1329
-<link linkend="livemarks">wrapping the livemark-service component</link> and
1330
-by calling stopUpdateLivemarks() on the <ulink
1331
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">Livemark
1332
-service</ulink> when Tor is enabled.
1333
-
1334
-</para>
1335
-
1336
-<para>
1337
-This helps satisfy the <link linkend="isolation">Network
1338
-Isolation</link> and <link linkend="setpreservation">Anonymity Set
1339
-Preservation</link> requirements.
1340
-</para>
1341
-
1342
-</sect2>
1343
-<sect2>
1344
-<title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1345
-  <para>Options:
1346
-   <simplelist>
1347
-   <member><command>extensions.torbutton.block_tor_file_net</command></member>
1348
-   <member><command>extensions.torbutton.block_nontor_file_net</command></member>
1349
-   </simplelist>
1350
-  </para>
1351
-
1352
-<para>
1353
-
1354
-These settings prevent file urls from performing network operations during the
1355
-respective Tor states. Firefox 2's implementation of same origin policy allows
1356
-file urls to read and <ulink
1357
-url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
1358
-arbitrary files from the local filesystem</ulink> to arbitrary websites. To
1359
-make matters worse, the 'Content-Disposition' header can be injected
1360
-arbitrarily by exit nodes to trick users into running arbitrary html files in
1361
-the local context. These preferences cause the <link
1362
-linkend="contentpolicy">content policy</link> to block access to any network
1363
-resources from File urls during the appropriate Tor state.
1364
-
1365
-</para>
1366
-<para>
1367
-
1368
-This preference helps to ensure Tor's <link linkend="isolation">Network
1369
-Isolation</link> requirement, by preventing file urls from executing network
1370
-operations in opposite Tor states. Also, allowing pages to submit arbitrary
1371
-files to arbitrary sites just generally seems like a bad idea.
1372
-
1373
-</para>
1374
-</sect2>
1375
-<sect2>
1376
-
1377
-<title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1378
-
1379
-  <para>Options:
1380
-   <simplelist>
1381
-   <member><command>extensions.torbutton.close_nontor</command></member>
1382
-   <member><command>extensions.torbutton.close_tor</command></member>
1383
-   </simplelist>
1384
-  </para>
1385
-
1386
-<para>
1387
-
1388
-These settings cause Torbutton to enumerate through all windows and close all
1389
-tabs in each window for the appropriate Tor state. This code can be found in
1390
-<function>torbutton_update_status()</function>.  The main reason these settings
1391
-exist is as a backup mechanism in the event of any Javascript or content policy
1392
-leaks due to <ulink
1393
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1394
-409737</ulink>.  Torbutton currently tries to block all Javascript network
1395
-activity via the content policy, but until that bug is fixed, there is some
1396
-risk that there are alternate ways to bypass the policy. This option is
1397
-available as an extra assurance of <link linkend="isolation">Network
1398
-Isolation</link> for those who would like to be sure that when Tor is toggled
1399
-all page activity has ceased. It also serves as a potential future workaround
1400
-in the event a content policy failure is discovered, and provides an additional
1401
-level of protection for the <link linkend="disk">Disk Avoidance</link>
1402
-protection so that browser state is not sitting around waiting to be swapped
1403
-out longer than necessary.
1404
-
1405
-</para>
1406
-<para>
1407
-While this setting doesn't satisfy any Torbutton requirements, the fact that
1408
-cookies are transmitted for partially typed queries does not seem desirable
1409
-for Tor usage.
1410
-</para>
1411
-</sect2>
1412
-
1413
-<sect2>
1414
-<title>Isolate Access to History navigation to Tor state (crucial)</title>
1415
-  <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1416
-  <para>
1417
-This setting determines if Torbutton installs an <ulink
1418
-url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener">nsISHistoryListener</ulink>
1419
-attached to the <ulink
1420
-url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">sessionHistory</ulink> of 
1421
-of each browser's <ulink
1422
-url="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation">webNavigatator</ulink>.
1423
-The nsIShistoryListener is instantiated with a reference to the containing
1424
-browser window and blocks the back, forward, and reload buttons on the browser
1425
-navigation bar when Tor is in an opposite state than the one to load the
1426
-current tab. In addition, Tor clears the session history during a new document
1427
-load if this setting is enabled. 
1428
-
1429
-  </para>
1430
-  <para>
1431
-
1432
-This is marked as a crucial setting in part
1433
-because Javascript access to the history object is indistinguishable from 
1434
-user clicks, and because
1435
-<ulink
1436
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1437
-409737</ulink> allows javascript to execute in opposite Tor states, javascript
1438
-can issue reloads after Tor toggle to reveal your original IP. Even without
1439
-this bug, however, Javascript is still able to access previous pages in your
1440
-session history that may have been loaded under a different Tor state, to
1441
-attempt to correlate your activity.
1442
-
1443
-   </para>
1444
-   <para>
1445
-
1446
-This setting helps to fulfill Torbutton's <link linkend="state">State
1447
-Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
1448
-requirements.
1449
-
1450
-   </para>
1451
-</sect2>
1452
-
1453
-
1454
-<sect2>
1455
-<title>History Access Settings</title>
1456
-
1457
-  <para>Options:
1458
-  <simplelist>
1459
-   <member><command>extensions.torbutton.block_thread</command></member>
1460
-   <member><command>extensions.torbutton.block_nthread</command></member>
1461
-   <member><command>extensions.torbutton.block_thwrite</command></member>
1462
-   <member><command>extensions.torbutton.block_nthwrite</command></member>
1463
-  </simplelist>
1464
-  </para>
1465
-
1466
-<para>These four settings govern the behavior of the <ulink
1467
-url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink>
1468
-history blocker component mentioned above. By hooking the browser's view of
1469
-the history itself via the <ulink
1470
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
1471
-and <ulink
1472
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1">@mozilla.org/browser/nav-history-service;1</ulink>
1473
-components, this mechanism defeats all document-based <ulink
1474
-url="http://whattheinternetknowsaboutyou.com/">history disclosure
1475
-attacks</ulink>, including <ulink
1476
-url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
1477
-
1478
-The component also hooks functions involved in writing history to disk via
1479
-both the <ulink
1480
-url="http://developer.mozilla.org/en/docs/Places_migration_guide#History">Places
1481
-Database</ulink> and the older Firefox 2 mechanisms.
1482
-
1483
-</para>
1484
-
1485
-<para>
1486
-This setting helps to satisfy the <link
1487
-linkend="state">State Separation</link> and <link
1488
-linkend="disk">Disk Avoidance</link> requirements.
1489
-</para>
1490
-
1491
-</sect2>
1492
-<sect2>
1493
-
1494
-<title>Clear History During Tor Toggle (optional)</title>
1495
-
1496
-<para>Option: <command>extensions.torbutton.clear_history</command></para>
1497
-
1498
-<para>This setting governs if Torbutton calls
1499
-<ulink
1500
-url="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29">nsIBrowserHistory.removeAllPages</ulink>
1501
-and <ulink
1502
-url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">nsISHistory.PurgeHistory</ulink>
1503
-for each tab on Tor toggle.</para>
1504
-<para>
1505
-This setting is an optional way to help satisfy the <link
1506
-linkend="state">State Separation</link> requirement.
1507
-</para>
1508
-
1509
-</sect2>
1510
-<sect2>
1511
-
1512
-<title>Block Password+Form saving during Tor/Non-Tor</title>
1513
-
1514
-<para>Options:
1515
-  <simplelist>
1516
-  <member><command>extensions.torbutton.block_tforms</command></member>
1517
-  <member><command>extensions.torbutton.block_ntforms</command></member>
1518
-  </simplelist>
1519
-  </para>
1520
-
1521
-<para>These settings govern if Torbutton disables
1522
-<command>browser.formfill.enable</command>
1523
-and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
1524
-Since form fields can be read at any time by Javascript, this setting is a lot
1525
-more important than it seems.
1526
-</para>
1527
-
1528
-<para>
1529
-This setting helps to satisfy the <link
1530
-linkend="state">State Separation</link> and <link
1531
-linkend="disk">Disk Avoidance</link> requirements.
1532
-</para>
1533
-
1534
-</sect2>
1535
-<sect2>
1536
-  <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
1537
-
1538
-  <para>Option: <command>extensions.torbutton.clear_cache</command>
1539
-  </para>
1540
-
1541
-<para>This option causes Torbutton to call <ulink
1542
-url="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29">nsICacheService.evictEntries(0)</ulink>
1543
-on Tor toggle to remove all entries from the cache. In addition, this setting
1544
-causes Torbutton to set <ulink
1545
-url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
1546
-</para>
1547
-<para>
1548
-This setting helps to satisfy the <link
1549
-linkend="state">State Separation</link> and <link
1550
-linkend="disk">Disk Avoidance</link> requirements.
1551
-</para>
1552
-
1553
-</sect2>
1554
-<sect2>
1555
-  <title>Block disk and memory cache during Tor</title>
1556
-
1557
-<para>Option: <command>extensions.torbutton.block_cache</command></para>
1558
-
1559
-<para>This setting
1560
-causes Torbutton to set <ulink
1561
-url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
1562
-<ulink
1563
-url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
1564
-<ulink
1565
-url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
1566
-</para>
1567
-<para>
1568
-This setting helps to satisfy the <link
1569
-linkend="state">State Separation</link> and <link
1570
-linkend="disk">Disk Avoidance</link> requirements.
1571
-</para>
1572
-
1573
-</sect2>
1574
-<sect2>
1575
-  <title>Clear Cookies on Tor Toggle</title>
1576
-
1577
-<para>Option: <command>extensions.torbutton.clear_cookies</command>
1578
-  </para>
1579
-
1580
-<para>
1581
-
1582
-This setting causes Torbutton to call <ulink
1583
-url="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29">nsICookieManager.removeAll()</ulink> on
1584
-every Tor toggle. In addition, this sets <ulink
1585
-url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1586
-to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1587
-which prevents them from being written to disk. 
1588
-
1589
-</para>
1590
-<para>
1591
-This setting helps to satisfy the <link
1592
-linkend="state">State Separation</link> and <link
1593
-linkend="disk">Disk Avoidance</link> requirements.
1594
-</para>
1595
-
1596
-</sect2>
1597
-<sect2>
1598
-  
1599
-  <title>Store Non-Tor cookies in a protected jar</title>
1600
-
1601
-<para>Option: <command>extensions.torbutton.cookie_jars</command>
1602
-  </para>
1603
-
1604
-<para>
1605
-
1606
-This setting causes Torbutton to use <ulink
1607
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1608
-non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
1609
-before restoring the jar.
1610
-</para>
1611
-<para>
1612
-This setting also sets <ulink
1613
-url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1614
-to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1615
-which prevents them from being written to disk. 
1616
-
1617
-</para>
1618
-
1619
-<para>
1620
-This setting helps to satisfy the <link
1621
-linkend="state">State Separation</link> and <link
1622
-linkend="disk">Disk Avoidance</link> requirements.
1623
-</para>
1624
-
1625
-
1626
-</sect2>
1627
-<sect2>
1628
-
1629
-  <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
1630
-
1631
-<para>Option: <command>extensions.torbutton.dual_cookie_jars</command>
1632
-  </para>
1633
-
1634
-<para>
1635
-
1636
-This setting causes Torbutton to use <ulink
1637
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1638
-both Tor and Non-Tor cookies into protected jars.
1639
-</para>
1640
-
1641
-<para>
1642
-This setting helps to satisfy the <link
1643
-linkend="state">State Separation</link> requirement.
1644
-</para>
1645
-
1646
-
1647
-</sect2>
1648
-
1649
-
1650
-<sect2>
1651
-
1652
-  <title>Manage My Own Cookies (dangerous)</title>
1653
-
1654
-<para>Options: None</para>
1655
-<para>This setting disables all Torbutton cookie handling by setting the above
1656
-cookie prefs all to false.</para>
1657
-</sect2>
1658
-<sect2>
1659
-
1660
-<sect2>
1661
-  <title>Do not write Tor/Non-Tor cookies to disk</title>
1662
-  <para>Options:
1663
-  <simplelist>
1664
-  <member><command>extensions.torbutton.tor_memory_jar</command></member>
1665
-  <member><command>extensions.torbutton.nontor_memory_jar</command></member>
1666
-  </simplelist>
1667
-  </para>
1668
-
1669
-<para>
1670
-These settings (contributed by arno) cause Torbutton to set <ulink
1671
-url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1672
-to 2 during the appropriate Tor state, and to store cookies acquired in that
1673
-state into a Javascript
1674
-<ulink
1675
-url="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X">E4X</ulink>
1676
-object as opposed to writing them to disk.
1677
-</para>
1678
-
1679
-<para>
1680
-This allows Torbutton to provide an option to preserve a user's 
1681
-cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
1682
-requirement.
1683
-</para>
1684
-</sect2>
1685
-
1686
-
1687
-  <title>Disable DOM Storage during Tor usage (crucial)</title>
1688
-
1689
-<para>Option: <command>extensions.torbutton.disable_domstorage</command>
1690
-  </para>
1691
-
1692
-<para>
1693
-
1694
-This setting causes Torbutton to toggle <command>dom.storage.enabled</command> during Tor
1695
-usage to prevent 
1696
-<ulink
1697
-  url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink> from
1698
-  being used to store persistent information across Tor states.</para>
1699
-<para>
1700
-This setting helps to satisfy the <link
1701
-linkend="state">State Separation</link> requirement.
1702
-</para>
1703
-
1704
-</sect2>
1705
-
1706
-<sect2>
1707
-  <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
1708
-<para>Option: <command>extensions.torbutton.clear_http_auth</command>
1709
-  </para>
1710
-
1711
-<para>
1712
-This setting causes Torbutton to call <ulink
1713
-url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager">nsIHttpAuthManager.clearAll()</ulink>
1714
-every time Tor is toggled.
1715
-</para>
1716
-
1717
-<para>
1718
-This setting helps to satisfy the <link
1719
-linkend="state">State Separation</link> requirement.
1720
-</para>
1721
-</sect2>
1722
-
1723
-<sect2>
1724
-
1725
-  <title>Clear cookies on Tor/Non-Tor shutdown</title>
1726
-
1727
-<para>Option: <command>extensions.torbutton.shutdown_method</command>
1728
-  </para>
1729
-
1730
-<para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1731
-cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1732
-clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1733
-for the <ulink
1734
-url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
1735
-<function>https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</function> and use <ulink
1736
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1737
-to clear out all cookies and all cookie jars upon shutdown.  </para>
1738
-<para>
1739
-This setting helps to satisfy the <link
1740
-linkend="state">State Separation</link> requirement.
1741
-</para>
1742
-
1743
-
1744
-</sect2>
1745
-<sect2>
1746
-
1747
-  <title>Reload cookie jar/clear cookies on Firefox crash</title>
1748
-  <para>Options:
1749
-  <simplelist>
1750
-    <member><command>extensions.torbutton.reload_crashed_jar</command></member>
1751
-    <member><command>extensions.torbutton.crashed</command></member>
1752
-  </simplelist>
1753
-  </para>
1754
-
1755
-  <para>This is no longer a user visible option, and is enabled by default. In
1756
-the event of a crash, the Torbutton <ulink
1757
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink> 
1758
-  component will notify the Chrome (via the
1759
-  <command>extensions.torbutton.crashed</command> pref and a <ulink
1760
-url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
1761
-observer</ulink> in
1762
-the chrome that listens for this update), and Torbutton will load the
1763
-  correct jar for the current Tor state via the <ulink
1764
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1765
-  component.</para>
1766
-
1767
-<para>
1768
-This setting helps to satisfy the <link
1769
-linkend="state">State Separation</link> requirement in the event of Firefox
1770
-crashes.
1771
-</para>
1772
-
1773
-</sect2>
1774
-
1775
-
1776
-<sect2>
1777
-  <title>On crash recovery or session restored startup, restore via: Tor, Non-Tor</title>
1778
-  <para>Options:
1779
-  <simplelist>
1780
-   <member><command>extensions.torbutton.restore_tor</command></member>
1781
-   <member><command>extensions.torbutton.crashed</command></member>
1782
-   <member><command>extensions.torbutton.normal_exit</command></member>
1783
-  </simplelist>
1784
-  </para>
1785
-
1786
-  <para>This option works with the Torbutton <ulink
1787
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink> 
1788
-  to set the Tor state after a crash is detected (via the 
1789
-  <command>extensions.torbutton.crashed</command> pref). To confirm for
1790
-false positives (such as session restore failures, upgrade, normal
1791
-session restore, etc), Torbutton also sets the pref
1792
-extensions.torbutton.normal_exit during
1793
-Firefox exit and checks this value as well during startup.  
1794
-</para>
1795
-<para>
1796
-
1797
-Since the Tor state after a Firefox crash is unknown/indeterminate, this
1798
-setting helps to satisfy the <link linkend="state">State Separation</link>
1799
-requirement in the event of Firefox crashes by ensuring all cookies,
1800
-settings and saved sessions are reloaded from a fixed Tor state.
1801
- 
1802
-</para>
1803
-</sect2>
1804
-
1805
-<sect2>
1806
-  <title>On normal startup, set state to: Tor, Non-Tor, Shutdown State</title>
1807
-
1808
-  <para>Options:
1809
-  <simplelist>
1810
-   <member><command>extensions.torbutton.startup_state</command></member>
1811
-  <member><command>extensions.torbutton.noncrashed</command></member>
1812
-   <member><command>extensions.torbutton.normal_exit</command></member>
1813
-  </simplelist>
1814
-  </para>
1815
-
1816
-  <para>This option also works with the Torbutton <ulink
1817
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink> 
1818
-  to set the Tor state after a normal startup is detected (via the 
1819
-  <command>extensions.torbutton.noncrashed</command> pref). To confirm for
1820
-false positives
1821
-(such as session restore failures, etc), Torbutton also sets the pref
1822
-extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
1823
-Firefox exit and checks this value as well during startup.
1824
-  
1825
-</para>
1826
-
1827
-</sect2>
1828
-
1829
-<sect2>
1830
-  <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
1831
-
1832
-  <para>Options: 
1833
-  <simplelist>
1834
-    <member><command>extensions.torbutton.nonontor_sessionstore</command></member>
1835
-    <member><command>extensions.torbutton.notor_sessionstore</command></member>
1836
-  </simplelist>
1837
-  </para>
1838
-
1839
-  <para>If these options are enabled, the <ulink
1840
-url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js">replacement nsSessionStore.js</ulink>
1841
-  component checks the <command>__tb_tor_fetched</command> tag of tabs before writing them
1842
-  out. If the tag is from a blocked Tor state, the tab is not written to disk.
1843
-  </para>
1844
-<para>
1845
-This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
1846
-requirement, and also helps to satisfy the <link
1847
-linkend="state">State Separation</link> requirement in the event of Firefox
1848
-crashes.
1849
-
1850
-</para>
1851
-
1852
-</sect2>
1853
-
1854
-<sect2>
1855
-
1856
-  <title>Set user agent during Tor usage (crucial)</title>
1857
-  <para>Options:
1858
-   <simplelist>
1859
-    <member><command>extensions.torbutton.set_uagent</command></member>
1860
-    <member><command>extensions.torbutton.platform_override</command></member>
1861
-    <member><command>extensions.torbutton.oscpu_override</command></member>
1862
-    <member><command>extensions.torbutton.buildID_override</command></member>
1863
-    <member><command>extensions.torbutton.productsub_override</command></member>
1864
-    <member><command>extensions.torbutton.appname_override</command></member>
1865
-    <member><command>extensions.torbutton.appversion_override</command></member>
1866
-    <member><command>extensions.torbutton.useragent_override</command></member>
1867
-    <member><command>extensions.torbutton.useragent_vendor</command></member>
1868
-    <member><command>extensions.torbutton.useragent_vendorSub</command></member>
1869
-  </simplelist>
1870
-   </para>
1871
-
1872
-<para>On face, user agent switching appears to be straight-forward in Firefox.
1873
-It provides several options for controlling the browser user agent string:
1874
-<command>general.appname.override</command>,
1875
-<command>general.appversion.override</command>,
1876
-<command>general.platform.override</command>,
1877
-<command>general.oscpu.override</command>,
1878
-<command>general.productSub.override</command>,
1879
-<command>general.buildID.override</command>,
1880
-<command>general.useragent.override</command>,
1881
-<command>general.useragent.vendor</command>, and
1882
-<command>general.useragent.vendorSub</command>. If
1883
-the Torbutton preference <command>extensions.torbutton.set_uagent</command> is
1884
-true, Torbutton copies all of the other above prefs into their corresponding
1885
-browser preferences during Tor usage.</para>
1886
-
1887
-
1888
-<para>
1889
-
1890
-It also turns out that it is possible to detect the original Firefox version
1891
-by <ulink url="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/">inspecting
1892
-certain resource:// files</ulink>. These cases are handled by Torbutton's
1893
-<link linkend="contentpolicy">content policy</link>.
1894
-
1895
-</para>
1896
-
1897
-<para>
1898
-This setting helps to satisfy the <link
1899
-linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1900
-</para>
1901
-
1902
-
1903
-</sect2>
1904
-<sect2>
1905
-
1906
-  <title>Spoof US English Browser</title>
1907
-<para>Options:
1908
-<simplelist>
1909
- <member><command>extensions.torbutton.spoof_english</command></member>
1910
- <member><command>extensions.torbutton.spoof_charset</command></member>
1911
- <member><command>extensions.torbutton.spoof_language</command></member>
1912
-</simplelist>
1913
-</para>
1914
-
1915
-<para> This option causes Torbutton to set
1916
-<command>general.useragent.locale</command>
1917
-<command>intl.accept_languages</command> to the value specified in
1918
-<command>extensions.torbutton.spoof_locale</command>,
1919
-<command>extensions.torbutton.spoof_charset</command> and
1920
-<command>extensions.torbutton.spoof_language</command> during Tor usage, as
1921
-well as hooking <command>navigator.language</command> via its <link
1922
-linkend="jshooks">javascript hooks</link>.
1923
- </para>
1924
-<para>
1925
-This setting helps to satisfy the <link
1926
-linkend="setpreservation">Anonymity Set Preservation</link> and <link
1927
-linkend="location">Location Neutrality</link> requirements.
1928
-</para>
1929
-
1930
-</sect2>
1931
-<sect2>
1932
-
1933
-  <title>Don't send referrer during Tor Usage</title>
1934
-
1935
-<para>Option: <command>extensions.torbutton.disable_referer</command>
1936
-</para>
1937
-
1938
-<para> 
1939
-This option causes Torbutton to set <ulink
1940
-url="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer">network.http.sendSecureXSiteReferrer</ulink> and
1941
-<ulink
1942
-url="http://kb.mozillazine.org/Network.http.sendRefererHeader">network.http.sendRefererHeader</ulink> during Tor usage.</para>
1943
-
1944
-<para>
1945
-This setting also does not directly satisfy any Torbutton requirement, but
1946
-some may desire to mask their referrer for general privacy concerns.
1947
-</para>
1948
-</sect2>
1949
-<sect2>
1950
-  <title>Strip platform and language off of Google Search Box queries</title>
1951
-
1952
-<para>Option: <command>extensions.torbutton.fix_google_srch</command>
1953
-</para>
1954
-
1955
-<para> 
1956
-
1957
-This option causes Torbutton to use the <ulink
1958
-url="https://wiki.mozilla.org/Search_Service:API">@mozilla.org/browser/search-service;1</ulink>
1959
-component to wrap the Google search plugin. On many platforms, notably Debian
1960
-and Ubuntu, the Google search plugin is set to reveal a lot of language and
1961
-platform information. This setting strips off that info while Tor is enabled.
1962
-
1963
-</para>
1964
-<para>
1965
-This setting helps Torbutton to fulfill its <link
1966
-linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1967
-</para>
1968
-</sect2>
1969
-
1970
-<sect2>
1971
-  <title>Automatically use an alternate search engine when presented with a
1972
-Google Captcha</title>
1973
-
1974
-<para>Options:
1975
-<simplelist>
1976
- <member><command>extensions.torbutton.asked_google_captcha</command></member>
1977
- <member><command>extensions.torbutton.dodge_google_captcha</command></member>
1978
- <member><command>extensions.torbutton.google_redir_url</command></member>
1979
-</simplelist>
1980
-</para>
1981
-
1982
-<para>
1983
-
1984
-Google's search engine has rate limiting features that cause it to
1985
-<ulink
1986
-url="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html">present
1987
-captchas</ulink> and sometimes even outright ban IPs that issue large numbers
1988
-of search queries, especially if a lot of these queries appear to be searching
1989
-for software vulnerabilities or unprotected comment areas.
1990
-
1991
-</para>
1992
-<para>
1993
-
1994
-Despite multiple discussions with Google, we were unable to come to a solution
1995
-or any form of compromise that would reduce the number of captchas and
1996
-outright bans seen by Tor users issuing regular queries.
1997
-
1998
-</para>
1999
-<para>
2000
-As a result, we've implemented this option as an <ulink
2001
-url="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">'http-on-modify-request'</ulink>
2002
-http observer to optionally redirect banned or captcha-triggering Google
2003
-queries to search engines that do not rate limit Tor users. The current
2004
-options are ixquick.com, bing.com, yahoo.com and scroogle.org. These are
2005
-encoded in the preferences
2006
-<command>extensions.torbutton.redir_url.[1-4]</command>.
2007
-
2008
-</para>
2009
-</sect2>
2010
-
2011
-<sect2>
2012
-
2013
-  <title>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</title>
2014
-
2015
-<para>Options:
2016
-<simplelist>
2017
- <member><command>extensions.torbutton.jar_certs</command></member>
2018
- <member><command>extensions.torbutton.jar_ca_certs</command></member>
2019
-</simplelist>
2020
-</para>
2021
-<para>
2022
-
2023
-These settings govern if Torbutton attempts to isolate the user's SSL
2024
-certificates into separate jars for each Tor state. This isolation is
2025
-implemented in <function>torbutton_jar_certs()</function> in <ulink
2026
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
2027
-which calls <function>torbutton_jar_cert_type()</function> and
2028
-<function>torbutton_unjar_cert_type()</function> for each certificate type in
2029
-the <ulink
2030
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1">@mozilla.org/security/nsscertcache;1</ulink>.
2031
-Certificates are deleted from and imported to the <ulink
2032
-url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/x509certdb;1">@mozilla.org/security/x509certdb;1</ulink>.
2033
-</para>
2034
-
2035
-<para>
2036
-The first time this pref is used, a backup of the user's certificates is
2037
-created in their profile directory under the name
2038
-<filename>cert8.db.bak</filename>. This file can be copied back to
2039
-<filename>cert8.db</filename> to fully restore the original state of the
2040
-user's certificates in the event of any error.
2041
-</para>
2042
-
2043
-<para>
2044
-Since exit nodes and malicious sites can insert content elements sourced to
2045
-specific SSL sites to query if a user has a certain certificate,
2046
-this setting helps to satisfy the <link linkend="state">State
2047
-Separation</link> requirement of Torbutton. Unfortunately, <ulink
2048
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Firefox Bug
2049
-435159</ulink> prevents it from functioning correctly in the event of rapid Tor toggle, so it
2050
-is currently not exposed via the preferences UI.
2051
-
2052
-</para>
2053
-
2054
-</sect2>
2055
-</sect1>
2056
-
2057
-<sect1 id="FirefoxBugs">
2058
-  <title>Relevant Firefox Bugs</title>
2059
-  <para>
2060
-
2061
-  </para>
2062
-  <sect2 id="FirefoxSecurity">
2063
-   <title>Bugs impacting security</title>
2064
-   <para>
2065
-
2066
-Torbutton has to work around a number of Firefox bugs that impact its
2067
-security. Most of these are mentioned elsewhere in this document, but they
2068
-have also been gathered here for reference. In order of decreasing severity,
2069
-they are:
2070
-
2071
-   </para>
2072
-   <orderedlist>
2073
-
2074
-<!--
2075
-
2076
-XXX: We should just consider this one fixed. FF3.0 is pretty much at EOL.
2077
-
2078
-   <listitem><ulink
2079
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=392274">Bug 392274 - Timezone
2080
-config/chrome API</ulink>
2081
-   <para>
2082
-
2083
-The lack of a config or API to configure the timezone requires Torbutton to
2084
-<link linkend="jshooks">insert client content window javascript</link> to hook
2085
-the Date object. Additionally, a way to <ulink
2086
-url="http://pseudo-flaw.net/tor/torbutton/unmask-date.html">remove the Date
2087
-hooks</ulink> was discovered by Greg Fleischer. Worse, on Firefox 3,
2088
-javascript sandboxing prevents most of the javascript hooks from being
2089
-installed, including the Date hooks. On Windows and Linux, you can set the TZ
2090
-environment variable to "UTC" as a workaround. Firefox will obey this
2091
-environment variable for your Timezone on those platforms, but on Windows this
2092
-does not take effect until browser restart. A fix for this has landed in
2093
-Firefox 3.5, but still has not been backported to Firefox 3.0. The lack of an
2094
-easy way to reliably spoof the timezone interferes with Torbutton's ability to
2095
-fulfill its <link linkend="location">Location Neutrality</link> requirement.
2096
-
2097
-
2098
-   </para>
2099
-   </listitem>
2100
--->
2101
-    <listitem><ulink
2102
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=429070">Bug 429070 - exposing
2103
-Components.interfaces to untrusted content leaks information about installed
2104
-extensions</ulink>
2105
-     <para>
2106
-<ulink url="http://pseudo-flaw.net/">Gregory Fleischer</ulink> demonstrated at Defcon 17 that these interfaces can
2107
-also be used to <ulink
2108
-url="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html">fingerprint
2109
-Firefox down the to the minor version</ulink>. Note that his test has not been
2110
-updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This
2111
-bug interferes with Torbutton's ability to satisfy its <link
2112
-linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2113
-     </para>
2114
-    </listitem>
2115
-
2116
-   <listitem><ulink
2117
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=280661">Bug 280661 - SOCKS proxy server
2118
-connection timeout hard-coded</ulink>
2119
-    <para>
2120
-
2121
-This bug prevents us from using the Firefox SOCKS layer directly, and
2122
-currently requires us to ship an auxiliary HTTP proxy called <ulink
2123
-url="http://www.pps.jussieu.fr/~jch/software/polipo/">Polipo</ulink>. If this
2124
-patch were landed, we would no longer need to ship Polipo, which has a number
2125
-of privacy and security issues of its own (in addition to being unmaintained).
2126
-
2127
-    </para>
2128
-   </listitem>
2129
-   <listitem><ulink
2130
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=418986">Bug 418986 - window.screen
2131
-provides a large amount of identifiable information</ulink>
2132
-   <para>
2133
-
2134
-As <link linkend="fingerprinting">mentioned above</link>, a large amount of
2135
-information is available from <ulink
2136
-url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>.
2137
-Currently, there is no way to obscure this information without Javascript
2138
-hooking. This bug is a feature request to provide some other method to change
2139
-these values. This bug interferes with Torbutton's ability to fulfill its
2140
-<link linkend="setpreservation">Anonymity Set Preservation</link>
2141
-requirement.
2142
-
2143
-   </para>
2144
-   </listitem>
2145
-   <listitem><ulink
2146
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Bug 435159 -
2147
-nsNSSCertificateDB::DeleteCertificate has race conditions</ulink>
2148
-      <para>
2149
-
2150
-In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
2151
-the user has installed. Unfortunately, the method call to delete a certificate
2152
-from the current certificate database acts lazily: it only sets a variable
2153
-that marks a cert for deletion later, and it is not cleared if that
2154
-certificate is re-added. This means that if the Tor state is toggled quickly,
2155
-that certificate could remain present until it is re-inserted (causing an
2156
-error dialog), and worse, it would still be deleted after that.  The lack of
2157
-this functionality is considered a Torbutton security bug because cert
2158
-isolation is considered a <link linkend="state">State Separation</link>
2159
-feature.
2160
-
2161
-      </para>
2162
-     </listitem>
2163
-
2164
-     <listitem><ulink
2165
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=575230">Bug 575230 - Provide option to
2166
-reduce precision of Date()</ulink>
2167
-      <para>
2168
-
2169
-Currently it is possible to <ulink
2170
-url="http://arstechnica.com/tech-policy/news/2010/02/firm-uses-typing-cadence-to-finger-unauthorized-users.ars">fingerprint
2171
-users based on their typing cadence</ulink> using the high precision timer
2172
-available to javascript. Using this same precision, it is possible to compute
2173
-an identifier based upon the clock drift of the client from some nominal
2174
-source. The latter is not much of a concern for Tor users, as the variable
2175
-delay to load and run a page is measured on the order of seconds, but the high
2176
-precision timer can still be used to fingerprint aspects of a browser's
2177
-javascript engine and processor, and apparently also a user's typing cadence.
2178
-This bug hinders Torbutton's ability to satisfy its <link
2179
-linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2180
-
2181
-      </para>
2182
-     </listitem>
2183
-
2184
-     <listitem><ulink
2185
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Bug 409737 -
2186
-javascript.enabled and docShell.allowJavascript do not disable all event
2187
-handlers</ulink>
2188
-     <para>
2189
-
2190
-This bug allows pages to execute javascript via addEventListener and perhaps
2191
-other callbacks. In order to prevent this bug from enabling an attacker to
2192
-break the <link linkend="isolation">Network Isolation</link> requirement,
2193
-Torbutton 1.1.13 began blocking popups and history manipulation from different
2194
-Tor states.  So long as there are no ways to open popups or redirect the user
2195
-to a new page, the <link linkend="contentpolicy">Torbutton content
2196
-policy</link> should block Javascript network access. However, if there are
2197
-ways to open popups or perform redirects such that Torbutton cannot block
2198
-them, pages may still have free reign to break that requirement and reveal a
2199
-user's original IP address.
2200
-
2201
-     </para>
2202
-     </listitem>
2203
-     <listitem><ulink
2204
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448743">Bug 448743 -
2205
-Decouple general.useragent.locale from spoofing of navigator.language</ulink>
2206
-     <para>
2207
-
2208
-Currently, Torbutton spoofs the <command>navigator.language</command>
2209
-attribute via <link linkend="jshooks">Javascript hooks</link>. Unfortunately,
2210
-these do not work on Firefox 3. It would be ideal to have
2211
-a pref to set this value (something like a
2212
-<command>general.useragent.override.locale</command>),
2213
-to avoid fragmenting the anonymity set of users of foreign locales. This issue
2214
-impedes Torbutton from fully meeting its <link
2215
-linkend="setpreservation">Anonymity Set Preservation</link>
2216
-requirement on Firefox 3.
2217
-
2218
-     </para>
2219
-     </listitem>
2220
-    </orderedlist>
2221
-  </sect2>
2222
-  <sect2 id="FirefoxWishlist">
2223
-   <title>Bugs blocking functionality</title>
2224
-   <para>
2225
-The following bugs impact Torbutton and similar extensions' functionality.
2226
-   </para>
2227
-
2228
-    <orderedlist>
2229
-
2230
-
2231
-   <listitem><ulink
2232
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=445696">Bug 445696 -
2233
-Extensions cannot determine if firefox is fullScreen</ulink>
2234
-   <para>
2235
-
2236
-The windowState property of <ulink
2237
-url="https://developer.mozilla.org/en/XUL/window">ChromeWindows</ulink> does not accurately reflect the true
2238
-state of the window in some cases on Linux. This causes Torbutton to attempt
2239
-to resize maximized and minimized windows when it should not.
2240
-
2241
-   </para>
2242
-   </listitem>
2243
-   <listitem><ulink
2244
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=290456">Bug 290456 -
2245
-Block/clear Flash MX "cookies" as well</ulink>
2246
-   <para>
2247
-
2248
-Today, it is possible to allow plugins if you have a transparent proxy such as
2249
-<ulink url="http://anonymityanywhere.com/incognito/">Incognito</ulink> to prevent proxy bypass. However, flash cookies can still be used to
2250
-link your Tor and Non-Tor activity, and this reveal your IP to an adversary
2251
-that does so. This can be solved by manually removing your flash cookies (like
2252
-<ulink
2253
-url="https://addons.mozilla.org/en-US/firefox/addon/6623">BetterPrivacy</ulink> does), but
2254
-it would be nice if there was a standard way to do this from a Firefox API.
2255
-
2256
-   </para>
2257
-   </listitem>
2258
-   <listitem><ulink
2259
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=417869">Bug 417869 -
2260
-Browser context is difficult to obtain from many XPCOM callbacks</ulink>
2261
-   <para>
2262
-
2263
-It is difficult to determine which tabbrowser many XPCOM callbacks originate
2264
-from, and in some cases absolutely no context information is provided at all.
2265
-While this doesn't have much of an effect on Torbutton, it does make writing
2266
-extensions that would like to do per-tab settings and content filters (such as
2267
-FoxyProxy) difficult to impossible to implement securely.
2268
-
2269
-   </para>
2270
-   </listitem>
2271
-   <listitem><ulink
2272
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
2273
-Components do not expose disk interfaces</ulink>
2274
-   <para>
2275
-
2276
-Several components currently provide no way of reimplementing their disk
2277
-access to easily satisfy Torbutton's <link linkend="disk">Disk
2278
-Avoidance</link> requirements. Workarounds exist, but they are <link
2279
-linkend="sessionstore">clunky</link>, and
2280
-some of them involve disabling functionality during Tor usage.
2281
-
2282
-   </para>
2283
-   </listitem>
2284
-
2285
-<!--
2286
-FIXME: Need to use new observer methods if possible
2287
-   <listitem><ulink
2288
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448741">Bug 448741 -
2289
-nsISessionStore uses private methods and is not extensible</ulink>
2290
-   <para>
2291
-
2292
-Similar to the above bug, in the specific case of the sessionstore component,
2293
-the API is not amenable to Contract ID hooking, and this requires that
2294
-Torbutton include modified copies of this component for Firefox 2 and 3, which
2295
-has <ulink
2296
-url="https://bugs.torproject.org/flyspray/index.php?do=details&amp;id=722">raised
2297
-objections</ulink> from some developers.
2298
-
2299
-   </para>
2300
-   </listitem>
2301
-   <listitem><ulink
2302
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=439384">Bug 439384 -
2303
-"profile-do-change" event does not cause cookie table reload</ulink>
2304
-   <para>
2305
-
2306
-In Firefox 3, the change to the new SQLlite database for cookie storage has a
2307
-bug that prevents Torbutton's cookie jaring from working properly. The
2308
-"profile-do-change" observer event no longer properly causes either a sync or
2309
-reload of the cookie database from disk after it is copied into place.
2310
-Torbutton currently works around this by issuing the SQLLite queries manually
2311
-to store and rebuild the cookie database.
2312
-
2313
-   </para>
2314
-   </listitem>
2315
-
2316
-   <listitem><ulink
2317
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=248970">Bug 248970 (PrivateBrowsing) - Private Browsing mode (global toggle for
2318
-saving/caching everything)</ulink>
2319
-   <para>
2320
-
2321
-This bug catalogs the discussion of a 'Private Mode' in Firefox that would
2322
-perform many, but not all, of the activities of Torbutton. It would be useful
2323
-to leverage the resulting setting to simplify Torbutton. This bug is listed so
2324
-we can track this progress and ensure that it doesn't end up defining
2325
-behaviors contrary to and incompatible with Torbutton's requirements (though a
2326
-subset of the <link linkend="requirements">requirements</link> is of course fine).
2327
-
2328
-   </para>
2329
-   </listitem>
2330
--->
2331
-
2332
-
2333
-
2334
-  </orderedlist>
2335
-  </sect2>
2336
-  <sect2 id="FirefoxMiscBugs">
2337
-   <title>Low Priority Bugs</title>
2338
-   <para>
2339
-The following bugs have an effect upon Torbutton, but are superseded by more
2340
-practical and more easily fixable variant bugs above; or have stable, simple
2341
-workarounds.
2342
-  </para>
2343
-
2344
-    <orderedlist>
2345
-    <listitem><ulink
2346
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=435151">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</ulink>
2347
-     <para>
2348
-
2349
-Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
2350
-constructors of classes defined from within the scope of the sandbox, among
2351
-other things. This prevents Torbutton from applying the Timezone hooks under
2352
-Firefox 3, but a better solution for Torbutton's specific date hooking needs 
2353
-would be a fix for the above mentioned Bug 392274. Of course, many more
2354
-extensions may be interested in the sandbox hooking functionality working
2355
-properly though.
2356
-
2357
-     </para>
2358
-     </listitem>
2359
-     <listitem><ulink
2360
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">Bug 440892 -
2361
-network.protocol-handler.warn-external are ignored</ulink>
2362
-     <para>
2363
-
2364
-Sometime in the Firefox 3 development cycle, the preferences that governed
2365
-warning a user when external apps were launched got disconnected from the code
2366
-that does the launching. Torbutton depended on these prefs to prevent websites
2367
-from launching specially crafted documents and application arguments that
2368
-caused Proxy Bypass. We currently work around this issue by <link
2369
-linkend="appblocker">wrapping the app launching components</link> to present a
2370
-popup before launching external apps while Tor is enabled. While this works,
2371
-it would be nice if these prefs were either fixed or removed.
2372
-
2373
-     </para>
2374
-     </listitem>
2375
-    <listitem><ulink
2376
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">Bug 437014 -
2377
-nsIContentPolicy::shouldLoad no longer called for favicons</ulink>
2378
-    <para>
2379
-
2380
-Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
2381
-loads. Torbutton had relied on this call to block favicon loads for opposite
2382
-Tor states. The workaround it employs for Firefox 3 is to cancel the request
2383
-when it arrives in the <command>torbutton_http_observer</command> used for
2384
-blocking full page plugin loads. This seems to work just fine, but is a bit
2385
-dirty.
2386
-
2387
-    </para>
2388
-    </listitem>
2389
-<!--
2390
-    <listitem><ulink
2391
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=437016">Bug 437016 -
2392
-nsIContentPolicy::shouldLoad not called for livemarks</ulink>
2393
-    <para>
2394
-
2395
-An alternative fix for the livemarks bug above would be to block livemarks
2396
-fetches from the content policy. Unfortunately shouldLoad is not called for
2397
-livemarks fetches.
2398
-
2399
-    </para>
2400
-    </listitem>
2401
--->
2402
- 
2403
-     <listitem><ulink
2404
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">Bug 309524</ulink>
2405
-and <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">Bug
2406
-380556</ulink> - nsIContentPolicy::shouldProcess is not called.
2407
-     <para>
2408
-
2409
-This is a call that would be useful to develop a better workaround for the
2410
-allowPlugins issue above. If the content policy were called before a URL was
2411
-handed over to a plugin or helper app, it would make the workaround for the
2412
-above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
2413
-the others though, but it might be nice to have this API as a backup.
2414
-
2415
-     </para>
2416
-     </listitem>
2417
-
2418
-     <listitem><ulink
2419
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">Bug 401296 - docShell.allowPlugins
2420
-not honored for direct links</ulink> (Perhaps subset of <ulink
2421
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=282106">Bug 282106</ulink>?)
2422
-     <para>
2423
-
2424
-Similar to the javascript plugin disabling attribute, the plugin disabling
2425
-attribute is also not perfect &mdash; it is ignored for direct links to plugin
2426
-handled content, as well as meta-refreshes to plugin handled content.  This
2427
-requires Torbutton to listen to a number of different http events to intercept
2428
-plugin-related mime type URLs and cancel their requests. Again, since plugins
2429
-are quite horrible about obeying proxy settings, loading a plugin pretty much
2430
-ensures a way to break the <link linkend="isolation">Network Isolation</link>
2431
-requirement and reveal a user's original IP address. Torbutton's code to
2432
-perform this workaround has been subverted at least once already by Kyle
2433
-Williams.
2434
-
2435
-     </para>
2436
-     </listitem>
2437
-<!--
2438
-
2439
-XXX: This is likely fixed with nsICrypto.logout()
2440
-
2441
-     <listitem><ulink
2442
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">Bug 448747 -
2443
-Provide Mechanism to clear TLS Session IDs</ulink>
2444
-     <para>
2445
-
2446
-As <link linkend="browseroverlay">mentioned above</link>, Torbutton currently
2447
-toggles <command>security.enable_ssl2</command> to clear the SSL
2448
-Session ID cache via the pref observer at <ulink
2449
-url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
2450
-line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
2451
-better if there were a more standard interface for accomplishing the same
2452
-thing.
2453
-
2454
-     </para>
2455
-     </listitem>
2456
--->
2457
-
2458
-   <listitem><ulink
2459
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
2460
-Date' is deletable</ulink>
2461
-     <para>
2462
-
2463
-Based on Page 62 of the <ulink
2464
-url="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">ECMA-262
2465
-Javascript spec</ulink>, it seems like it should be possible to do something
2466
-like the following to prevent the Date object from being unmasked:
2467
-<screen>
2468
-with(window) {
2469
-    var Date = fakeDate;
2470
-    var otherVariable = 42;
2471
-}
2472
-
2473
-delete window.Date; // Should fail. Instead succeeds, revealing original Date.
2474
-delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
2475
-</screen>
2476
-
2477
-From the ECMA-262 spec:
2478
-
2479
-<blockquote>
2480
-If the variable statement occurs inside a FunctionDeclaration, the variables
2481
-are defined with function-local scope in that function, as described in
2482
-s10.1.3. Otherwise, they are defined with global scope (that is, they are
2483
-created as members of the global object, as described in 10.1.3) using
2484
-property attributes { DontDelete }. Variables are created when the execution
2485
-scope is entered. A Block does not define a new execution scope. Only Program
2486
-and FunctionDeclaration produce a new scope. Variables are initialized to
2487
-undefined when created. A variable with an Initialiser is assigned the value
2488
-of its AssignmentExpression when the VariableStatement is executed, not when
2489
-the variable is created.
2490
-</blockquote>
2491
-
2492
-In fact, this is exactly how the with statement with a variable declaration
2493
-behaves <emphasis>for all other variables other than ones that shadow system
2494
-variables</emphasis>. Some variables (such as
2495
-<command>window.screen</command>, and <command>window.history</command>) can't
2496
-even be shadowed in this way, and give an error about lacking a setter. If
2497
-such shadowing were possible, it would greatly simplify the Javascript hooking
2498
-code, which currently relies on undocumented semantics of
2499
-<command>__proto__</command> to copy the original values in the event of a
2500
-delete. This <command>__proto__</command> hack unfortunately does not work for
2501
-the Date object though.
2502
-
2503
-     </para>
2504
-    </listitem>
2505
-
2506
-  </orderedlist>
2507
-  </sect2>
2508
-</sect1>
2509
-
2510
-<sect1 id="TestPlan">
2511
-  <title>Testing</title>
2512
-  <para>
2513
-
2514
-The purpose of this section is to cover all the known ways that Tor browser
2515
-security can be subverted from a penetration testing perspective. The hope
2516
-is that it will be useful both for creating a &quot;Tor Safety Check&quot;
2517
-page, and for developing novel tests and actively attacking Torbutton with the
2518
-goal of finding vulnerabilities in either it or the Mozilla components,
2519
-interfaces and settings upon which it relies.
2520
-
2521
-  </para>
2522
-  <sect2 id="SingleStateTesting">
2523
-   <title>Single state testing</title>
2524
-   <para>
2525
-
2526
-Torbutton is a complicated piece of software. During development, changes to
2527
-one component can affect a whole slough of unrelated features.  A number of
2528
-aggregated test suites exist that can be used to test for regressions in
2529
-Torbutton and to help aid in the development of Torbutton-like addons and
2530
-other privacy modifications of other browsers. Some of these test suites exist
2531
-as a single automated page, while others are a series of pages you must visit
2532
-individually. They are provided here for reference and future regression
2533
-testing, and also in the hope that some brave soul will one day decide to
2534
-combine them into a comprehensive automated test suite.
2535
-
2536
-     <orderedlist>
2537
-      <listitem><ulink url="http://decloak.net/">Decloak.net</ulink>
2538
-       <para>
2539
-
2540
-Decloak.net is the canonical source of plugin and external-application based
2541
-proxy-bypass exploits. It is a fully automated test suite maintained by <ulink
2542
-url="http://digitaloffense.net/">HD Moore</ulink> as a service for people to
2543
-use to test their anonymity systems.
2544
-
2545
-       </para>
2546
-      </listitem>
2547
-      <listitem><ulink url="http://deanonymizer.com/">Deanonymizer.com</ulink>
2548
-       <para>
2549
-
2550
-Deanonymizer.com is another automated test suite that tests for proxy bypass
2551
-and other information disclosure vulnerabilities. It is maintained by Kyle
2552
-Williams, the author of <ulink url="http://www.janusvm.com/">JanusVM</ulink>
2553
-and <ulink url="http://www.januspa.com/">JanusPA</ulink>.
2554
-
2555
-       </para>
2556
-      </listitem>
2557
-      <listitem><ulink url="https://www.jondos.de/en/anontest">JonDos
2558
-AnonTest</ulink>
2559
-       <para>
2560
-
2561
-The <ulink url="https://www.jondos.de">JonDos people</ulink> also provide an
2562
-anonymity tester. It is more focused on HTTP headers than plugin bypass, and
2563
-points out a couple of headers Torbutton could do a better job with
2564
-obfuscating.
2565
-
2566
-       </para>
2567
-      </listitem>
2568
-      <listitem><ulink url="http://browserspy.dk">Browserspy.dk</ulink>
2569
-       <para>
2570
-
2571
-Browserspy.dk provides a tremendous collection of browser fingerprinting and
2572
-general privacy tests. Unfortunately they are only available one page at a
2573
-time, and there is not really solid feedback on good vs bad behavior in
2574
-the test results.
2575
-
2576
-       </para>
2577
-      </listitem>
2578
-      <listitem><ulink url="http://analyze.privacy.net/">Privacy
2579
-Analyzer</ulink>
2580
-       <para>
2581
-
2582
-The Privacy Analyzer provides a dump of all sorts of browser attributes and
2583
-settings that it detects, including some information on your origin IP
2584
-address. Its page layout and lack of good vs bad test result feedback makes it
2585
-not as useful as a user-facing testing tool, but it does provide some
2586
-interesting checks in a single page.
2587
-
2588
-       </para>
2589
-      </listitem>
2590
-      <listitem><ulink url="http://ha.ckers.org/mr-t/">Mr. T</ulink>
2591
-       <para>
2592
-
2593
-Mr. T is a collection of browser fingerprinting and deanonymization exploits
2594
-discovered by the <ulink url="http://ha.ckers.org">ha.ckers.org</ulink> crew
2595
-and others. It is also not as user friendly as some of the above tests, but it
2596
-is a useful collection.
2597
-
2598
-       </para>
2599
-      </listitem>
2600
-      <listitem>Gregory Fleischer's <ulink
2601
-url="http://pseudo-flaw.net/content/tor/torbutton/">Torbutton</ulink> and
2602
-<ulink
2603
-url="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html">Defcon
2604
-17</ulink> Test Cases
2605
-       <para>
2606
-
2607
-Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy
2608
-issues for the past 2 years. He has an excellent collection of all his test
2609
-cases that can be used for regression testing. In his Defcon work, he
2610
-demonstrates ways to infer Firefox version based on arcane browser properties.
2611
-We are still trying to determine the best way to address some of those test
2612
-cases.
2613
-
2614
-       </para>
2615
-      </listitem>
2616
-      <listitem><ulink url="https://torcheck.xenobite.eu/index.php">Xenobite's
2617
-TorCheck Page</ulink>
2618
-       <para>
2619
-
2620
-This page checks to ensure you are using a valid Tor exit node and checks for
2621
-some basic browser properties related to privacy. It is not very fine-grained
2622
-or complete, but it is automated and could be turned into something useful
2623
-with a bit of work.
2624
-
2625
-       </para>
2626
-      </listitem>
2627
-     </orderedlist>
2628
-    </para>
2629
-  </sect2>
2630
-  <sect2>
2631
-   <title>Multi-state testing</title>
2632
-   <para>
2633
-
2634
-The tests in this section are geared towards a page that would instruct the
2635
-user to toggle their Tor state after the fetch and perform some operations:
2636
-mouseovers, stray clicks, and potentially reloads.
2637
-
2638
-   </para>
2639
-   <sect3>
2640
-    <title>Cookies and Cache Correlation</title>
2641
-    <para>
2642
-The most obvious test is to set a cookie, ask the user to toggle tor, and then
2643
-have them reload the page. The cookie should no longer be set if they are
2644
-using the default Torbutton settings. In addition, it is possible to leverage
2645
-the cache to <ulink
2646
-url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
2647
-identifiers</ulink>. The default settings of Torbutton should also protect
2648
-against these from persisting across Tor Toggle.
2649
-
2650
-    </para>
2651
-   </sect3>
2652
-   <sect3>
2653
-    <title>Javascript timers and event handlers</title>
2654
-    <para>
2655
-
2656
-Javascript can set timers and register event handlers in the hopes of fetching
2657
-URLs after the user has toggled Torbutton. 
2658
-    </para>
2659
-   </sect3>
2660
-   <sect3>
2661
-    <title>CSS Popups and non-script Dynamic Content</title>
2662
-    <para>
2663
-
2664
-Even if Javascript is disabled, CSS is still able to 
2665
-<ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">create popup-like
2666
-windows</ulink>
2667
-via the 'onmouseover' CSS attribute, which can cause arbitrary browser
2668
-activity as soon as the mouse enters into the content window. It is also
2669
-possible for meta-refresh tags to set timers long enough to make it likely
2670
-that the user has toggled Tor before fetching content.
2671
-
2672
-    </para>
2673
-   </sect3>
2674
-  </sect2>
2675
-  <sect2 id="HackTorbutton">
2676
-   <title>Active testing (aka How to Hack Torbutton)</title>
2677
-   <para>
2678
-
2679
-The idea behind active testing is to discover vulnerabilities in Torbutton to
2680
-bypass proxy settings, run script in an opposite Tor state, store unique
2681
-identifiers, leak location information, or otherwise violate <link
2682
-linkend="requirements">its requirements</link>. Torbutton has ventured out
2683
-into a strange and new security landscape. It depends on Firefox mechanisms
2684
-that haven't necessarily been audited for security, certainly not for the
2685
-threat model that Torbutton seeks to address. As such, it and the interfaces
2686
-it depends upon still need a 'trial by fire' typical of new technologies. This
2687
-section of the document was written with the intention of making that period
2688
-as fast as possible. Please help us get through this period by considering
2689
-these attacks, playing with them, and reporting what you find (and potentially
2690
-submitting the test cases back to be run in the standard batch of Torbutton
2691
-tests.
2692
-
2693
-   </para>
2694
-   <sect3>
2695
-    <title>Some suggested vectors to investigate</title>
2696
-    <para>
2697
-    <itemizedlist>
2698
-     <listitem>Strange ways to register Javascript <ulink
2699
-url="http://en.wikipedia.org/wiki/DOM_Events">events</ulink> and <ulink
2700
-url="http://www.devshed.com/c/a/JavaScript/Using-Timers-in-JavaScript/">timeouts</ulink> should
2701
-be verified to actually be ineffective after Tor has been toggled.</listitem>
2702
-     <listitem>Other ways to cause Javascript to be executed after
2703
-<command>javascript.enabled</command> has been toggled off.</listitem>
2704
-     <listitem>Odd ways to attempt to load plugins. Kyle Williams has had
2705
-some success with direct loads/meta-refreshes of plugin-handled URLs.</listitem>
2706
-     <listitem>The Date and Timezone hooks should be verified to work with
2707
-crazy combinations of iframes, nested iframes, iframes in frames, frames in
2708
-iframes, and popups being loaded and
2709
-reloaded in rapid succession, and/or from one another. Think race conditions and deep, 
2710
-parallel nesting, involving iframes from both <ulink
2711
-url="http://en.wikipedia.org/wiki/Same_origin_policy">same-origin and
2712
-non-same-origin</ulink> domains.</listitem>
2713
-     <listitem>In addition, there may be alternate ways and other
2714
-methods to query the timezone, or otherwise use some of the Date object's
2715
-methods in combination to deduce the timezone offset. Of course, the author
2716
-tried his best to cover all the methods he could foresee, but it's always good
2717
-to have another set of eyes try it out.</listitem>
2718
-     <listitem>Similarly, is there any way to confuse the <link
2719
-linkend="contentpolicy">content policy</link>
2720
-mentioned above to cause it to allow certain types of page fetches? For
2721
-example, it was recently discovered that favicons are not fetched by the
2722
-content, but the chrome itself, hence the content policy did not look up the
2723
-correct window to determine the current Tor tag for the favicon fetch. Are
2724
-there other things that can do this? Popups? Bookmarklets? Active bookmarks? </listitem>
2725
-     <listitem>Alternate ways to store and fetch unique identifiers. For example, <ulink
2726
-url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink>
2727
-caught us off guard. 
2728
-It was
2729
-also discovered by <ulink url="http://pseudo-flaw.net">Gregory
2730
-Fleischer</ulink> that <ulink
2731
-url="http://pseudo-flaw.net/content/tor/torbutton/">content window access to
2732
-chrome</ulink> can be used to build <link linkend="fingerprinting">unique
2733
-identifiers</link>. 
2734
-Are there any other
2735
-arcane or experimental ways that Firefox provides to create and store unique
2736
-identifiers? Or perhaps unique identifiers can be queried or derived from
2737
-properties of the machine/browser that Javascript has access to? How unique
2738
-can these identifiers be?
2739
-     </listitem>
2740
-     <listitem>Is it possible to get the browser to write some history to disk
2741
-(aside from swap) that can be retrieved later? By default, Torbutton should
2742
-write no history, cookie, or other browsing activity information to the
2743
-harddisk.</listitem>
2744
-     <listitem>Do popup windows make it easier to break any of the above
2745
-behavior? Are javascript events still canceled in popups? What about recursive
2746
-popups from Javascript, data, and other funky URL types? What about CSS
2747
-popups? Are they still blocked after Tor is toggled?</listitem>
2748
-     <listitem>Chrome-escalation attacks. The interaction between the
2749
-Torbutton chrome Javascript and the client content window javascript is pretty
2750
-well-defined and carefully constructed, but perhaps there is a way to smuggle
2751
-javascript back in a return value, or otherwise inject network-loaded
2752
-javascript into the chrome (and thus gain complete control of the browser).
2753
-</listitem>
2754
-</itemizedlist>
2755
-
2756
-    </para>
2757
-   </sect3>
2758
-  </sect2>
2759
-</sect1>
2760
-</article>
... ...
@@ -1,1482 +0,0 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
-<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">Jun 28 2010</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2910402">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="#id2907285">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2927418">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2922900">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2907191">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="#id2922887">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2922834">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2917336">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2934128">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2915503">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2931338">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2898010">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2910532">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="#id2917719">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="#id2897638">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2924640">5.6. Disable Updates During Tor</a></span></dt><dt><span class="sect2"><a href="#id2892217">5.7. Redirect Torbutton Updates Via Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892261">5.8. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892300">5.9. Disable livemarks updates during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892371">5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892443">5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2892524">5.12. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2892609">5.13. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2892721">5.14. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2934267">5.15. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2934328">5.16. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2934378">5.17. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2934430">5.18. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2934481">5.19. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2934538">5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2934577">5.21. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2934592">5.22. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2934696">5.23. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2934733">5.24. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id2934788">5.25. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id2934863">5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2934935">5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id2934994">5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id2935059">5.29. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2935233">5.30. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id2935326">5.31. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id2935366">5.32. Strip platform and language off of Google Search Box queries</a></span></dt><dt><span class="sect2"><a href="#id2935407">5.33. Automatically use an alternate search engine when presented with a
4
-Google Captcha</a></span></dt><dt><span class="sect2"><a href="#id2935487">5.34. 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="#id2936532">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="id2910402"></a>1. Introduction</h2></div></div></div><p>
5
-
6
-This document describes the goals, operation, and testing procedures of the
7
-Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
8
-
9
-  </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>
10
-
11
-A Tor web browser adversary has a number of goals, capabilities, and attack
12
-types that can be used to guide us towards a set of requirements for the
13
-Torbutton extension. Let's start with the goals.
14
-
15
-   </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 
16
-Tor, causing the user to directly connect to an IP of the adversary's
17
-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
18
-happily settle for the ability to correlate something a user did via Tor with
19
-their non-Tor activity. This can be done with cookies, cache identifiers,
20
-javascript events, and even CSS. Sometimes the fact that a user uses Tor may
21
-be enough for some authorities.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p>
22
-The adversary may also be interested in history disclosure: the ability to
23
-query a user's history to see if they have issued certain censored search
24
-queries, or visited censored sites.
25
-     </p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p>
26
-
27
-Location information such as timezone and locality can be useful for the
28
-adversary to determine if a user is in fact originating from one of the
29
-regions they are attempting to control, or to zero-in on the geographical
30
-location of a particular dissident or whistleblower.
31
-
32
-     </p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
33
-
34
-Anonymity set reduction is also useful in attempting to zero in on a
35
-particular individual. If the dissident or whistleblower is using a rare build
36
-of Firefox for an obscure operating system, this can be very useful
37
-information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>.
38
-
39
-     </p></li><li class="listitem"><span class="command"><strong>History records and other on-disk
40
-information</strong></span><p>
41
-In some cases, the adversary may opt for a heavy-handed approach, such as
42
-seizing the computers of all Tor users in an area (especially after narrowing
43
-the field by the above two pieces of information). History records and cache
44
-data are the primary goals here.
45
-     </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>
46
-The adversary can position themselves at a number of different locations in
47
-order to execute their attacks.
48
-    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
49
-The adversary can run exit nodes, or alternatively, they may control routers
50
-upstream of exit nodes. Both of these scenarios have been observed in the
51
-wild.
52
-     </p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>
53
-The adversary can also run websites, or more likely, they can contract out
54
-ad space from a number of different adservers and inject content that way. For
55
-some users, the adversary may be the adservers themselves. It is not
56
-inconceivable that adservers may try to subvert or reduce a user's anonymity 
57
-through Tor for marketing purposes.
58
-     </p></li><li class="listitem"><span class="command"><strong>Local Network/ISP/Upstream Router</strong></span><p>
59
-The adversary can also inject malicious content at the user's upstream router
60
-when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
61
-activity.
62
-     </p></li><li class="listitem"><span class="command"><strong>Physical Access</strong></span><p>
63
-Some users face adversaries with intermittent or constant physical access.
64
-Users in Internet cafes, for example, face such a threat. In addition, in
65
-countries where simply using tools like Tor is illegal, users may face
66
-confiscation of their computer equipment for excessive Tor usage or just
67
-general suspicion.
68
-     </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>
69
-
70
-The adversary can perform the following attacks from a number of different 
71
-positions to accomplish various aspects of their goals. It should be noted
72
-that many of these attacks (especially those involving IP address leakage) are
73
-often performed by accident by websites that simply have Javascript, dynamic 
74
-CSS elements, and plugins. Others are performed by adservers seeking to
75
-correlate users' activity across different IP addresses, and still others are
76
-performed by malicious agents on the Tor network and at national firewalls.
77
-
78
-    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Inserting Javascript</strong></span><p>
79
-If not properly disabled, Javascript event handlers and timers
80
-can cause the browser to perform network activity after Tor has been disabled,
81
-thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
82
-a user's non-Tor IP address. Javascript
83
-also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure attacks</a>:
84
-to query the history via the different attributes of 'visited' links to search
85
-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
86
-users based on gender and other classifications</a>. Finally,
87
-Javascript can be used to query the user's timezone via the
88
-<code class="function">Date()</code> object, and to reduce the anonymity set by querying
89
-the <code class="function">navigator</code> object for operating system, CPU, locale, 
90
-and user agent information.
91
-     </p></li><li class="listitem"><span class="command"><strong>Inserting Plugins</strong></span><p>
92
-
93
-Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
94
-capable of performing network activity that the author has
95
-investigated is also capable of performing network activity independent of
96
-browser proxy settings - and often independent of its own proxy settings.
97
-Sites that have plugin content don't even have to be malicious to obtain a
98
-user's
99
-Non-Tor IP (it usually leaks by itself), though <a class="ulink" href="http://decloak.net" target="_top">plenty of active
100
-exploits</a> are possible as well. In addition, plugins can be used to store unique identifiers that are more
101
-difficult to clear than standard cookies. 
102
-<a class="ulink" href="http://epic.org/privacy/cookies/flash.html" target="_top">Flash-based
103
-cookies</a> fall into this category, but there are likely numerous other
104
-examples.
105
-
106
-     </p></li><li class="listitem"><span class="command"><strong>Inserting CSS</strong></span><p>
107
-
108
-CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
109
-Non-Tor IP address, via the usage of
110
-<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">CSS
111
-popups</a> - essentially CSS-based event handlers that fetch content via
112
-CSS's onmouseover attribute. If these popups are allowed to perform network
113
-activity in a different Tor state than they were loaded in, they can easily
114
-correlate Tor and Non-Tor activity and reveal a user's IP address. In
115
-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
116
-attacks</a>.
117
-     </p></li><li class="listitem"><span class="command"><strong>Read and insert cookies</strong></span><p>
118
-
119
-An adversary in a position to perform MITM content alteration can inject
120
-document content elements to both read and inject cookies for
121
-arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
122
-sort of <a class="ulink" href="http://seclists.org/bugtraq/2007/Aug/0070.html" target="_top">active
123
-sidejacking</a>.
124
-
125
-     </p></li><li class="listitem"><span class="command"><strong>Create arbitrary cached content</strong></span><p>
126
-
127
-Likewise, the browser cache can also be used to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
128
-identifiers</a>. Since by default the cache has no same-origin policy,
129
-these identifiers can be read by any domain, making them an ideal target for
130
-adserver-class adversaries.
131
-
132
-     </p></li><li class="listitem"><a id="fingerprinting"></a><span class="command"><strong>Fingerprint users based on browser
133
-attributes</strong></span><p>
134
-
135
-There is an absurd amount of information available to websites via attributes
136
-of the browser. This information can be used to reduce anonymity set, or even
137
-<a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">uniquely
138
-fingerprint individual users</a>. </p><p>
139
-For illustration, let's perform a
140
-back-of-the-envelope calculation on the number of anonymity sets for just the
141
-resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and
142
-<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
143
-objects. Browser window resolution information provides something like
144
-(1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
145
-information contributes about another factor of 5 (for about 5 resolutions in
146
-typical use). In addition, the dimensions and position of the desktop taskbar
147
-are available, which can reveal hints on OS information. This boosts the count
148
-by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
149
-and Gnome, and None). Subtracting the browser content window
150
-size from the browser outer window size provide yet more information.
151
-Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
152
-2<sup>3</sup>=8). Interface effects such as titlebar fontsize
153
-and window manager settings gives a factor of about 9 (say 3 common font sizes
154
-for the titlebar and 3 common sizes for browser GUI element fonts).
155
-Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
156
-2<sup>29</sup>, or a 29 bit identifier based on resolution
157
-information alone. </p><p>
158
-
159
-Of course, this space is non-uniform and prone to incremental changes.
160
-However, if a bit vector space consisting of the above extracted attributes
161
-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
162
-Webzine article above</a>, minor changes in browser window resolution will
163
-no longer generate totally new identifiers. 
164
-
165
-</p><p>
166
-
167
-To add insult to injury, <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">chrome URL disclosure
168
-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
169
-to that 2<sup>29</sup>. With hundreds of popular extensions
170
-and thousands of extensions total, it is easy to see that this sort of
171
-information is an impressively powerful identifier if used properly by a
172
-competent and determined adversary such as an ad network.  Again, a
173
-nearest-neighbor bit vector space approach here would also gracefully handle
174
-incremental changes to installed extensions.
175
-
176
-</p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or
177
-OS</strong></span><p>
178
-Last, but definitely not least, the adversary can exploit either general 
179
-browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
180
-install malware and surveillance software. An adversary with physical access
181
-can perform similar actions. Regrettably, this last attack capability is
182
-outside of Torbutton's ability to defend against, but it is worth mentioning
183
-for completeness.
184
-     </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>
185
-
186
-Since many settings satisfy multiple requirements, this design document is
187
-organized primarily by Torbutton components and settings. However, if you are
188
-the type that would rather read the document from the requirements
189
-perspective, it is in fact possible to search for each of the following
190
-requirement phrases in the text to find the relevant features that help meet
191
-that requirement.
192
-
193
-</div><p>
194
-
195
-From the above Adversary Model, a number of requirements become clear. 
196
-
197
-   </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
198
-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
199
- 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
200
- one Tor state MUST NOT be accessible via the network in
201
- another Tor state.</p></li><li class="listitem"><a id="undiscoverability"></a><span class="command"><strong>Tor Undiscoverability</strong></span><p>With
202
-the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
203
-users whose network fingerprint does not obviously betray the fact that they
204
-are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
205
-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
206
- 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
207
- timezone or locale via Tor.</p></li><li class="listitem"><a id="setpreservation"></a><span class="command"><strong>Anonymity Set
208
-Preservation</strong></span><p>The browser SHOULD NOT leak any other anonymity set reducing information 
209
- (such as user agent, extension presence, and resolution information)
210
-automatically via Tor. The assessment of the attacks above should make it clear
211
-that anonymity set reduction is a very powerful method of tracking and
212
-eventually identifying anonymous users.
213
-</p></li><li class="listitem"><a id="updates"></a><span class="command"><strong>Update Safety</strong></span><p>The browser
214
-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
215
- enable the user to switch between a number of different proxies. It MUST
216
- provide full Tor protection in the event a third-party proxy switcher has
217
- 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
218
-'Chrome'. Components are a fancy name for classes that implement a given
219
-interface or interfaces. In Firefox, components <a class="ulink" href="https://developer.mozilla.org/en/XPCOM" target="_top">can be
220
-written</a> in C++,
221
-Javascript, or a mixture of both. Components have two identifiers: their
222
-'<a class="ulink" href="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005" target="_top">Contract
223
-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
224
-ID</a>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
225
-'Interface ID'. It is possible to 'hook' system components - to reimplement
226
-their interface members with your own wrappers - but only if the rest of the
227
-browser refers to the component by its Contract ID. If the browser refers to
228
-the component by Class ID, it bypasses your hooks in that use case.
229
-Technically, it may be possible to hook Class IDs by unregistering the
230
-original component, and then re-registering your own, but this relies on
231
-obsolete and deprecated interfaces and has proved to be less than
232
-stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window.
233
-Extensions are allowed to create 'overlays' that are 'bound' to existing XML
234
-window definitions, or they can create their own windows. The DTD for this XML
235
-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="id2907285"></a>2. Components</h2></div></div></div><p>
236
-
237
-Torbutton installs components for two purposes: hooking existing components to
238
-reimplement their interfaces; and creating new components that provide
239
-services to other pieces of the extension.
240
-
241
-  </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2927418"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some
242
-of its own standalone components as well.  Let's discuss the hooked components
243
-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> -
244
-<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>
245
-requirements of Torbutton. As stated in the requirements, Torbutton needs to
246
-prevent Tor tabs from being written to disk by the Firefox session store for a
247
-number of reasons, primary among them is the fact that Firefox can crash at
248
-any time, and a restart can cause you to fetch tabs in the incorrect Tor
249
-state.</p><p>These components illustrate a complication with Firefox hooking: you can
250
-only hook member functions of a class if they are published in an
251
-interface that the class implements. Unfortunately, the sessionstore has no
252
-published interface that is amenable to disabling the writing out of Tor tabs
253
-in specific. As such, Torbutton had to include the <span class="emphasis"><em>entire</em></span>
254
-nsSessionStore from both Firefox 2.0, 3.0, 3.5 and 3.6
255
-with a couple of modifications to prevent tabs that were loaded with Tor
256
-enabled from being written to disk, and some version detection code to
257
-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
258
-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
259
-</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>,
260
-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>
261
-- <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>
262
-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
263
-applications without user intervention, Torbutton had to wrap the three
264
-components involved in launching external applications to provide user
265
-confirmation before doing so while Tor is enabled. Since external applications
266
-do not obey proxy settings, they can be manipulated to automatically connect
267
-back to arbitrary servers outside of Tor with no user intervention. Fixing
268
-this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy
269
-Obedience</a> Requirement.
270
- </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="id2924906"></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> -
271
-    <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
272
-charge of <a class="ulink" href="http://developer.mozilla.org/en/docs/Session_store_API" target="_top">restoring saved
273
-sessions</a>. The wrapper's only job is to intercept the
274
-<code class="function">doRestore()</code> function, which is called by Firefox if it is determined that the
275
-browser crashed and the session needs to be restored. The wrapper notifies the
276
-Torbutton chrome that the browser crashed by setting the pref
277
-<span class="command"><strong>extensions.torbutton.crashed</strong></span>, or that it is a normal
278
-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
279
-preference change</a> for this value and then does the appropriate cleanup. This
280
-includes setting the Tor state to the one the user selected for crash recovery
281
-in the preferences window (<span class="command"><strong>extensions.torbutton.restore_tor</strong></span>), and
282
-restoring cookies for the corresponding cookie jar, if it exists.</p><p>By performing this notification, this component assists in the 
283
-<a class="link" href="#proxy">Proxy Obedience</a>, and <a class="link" href="#isolation">Network Isolation</a> requirements.
284
-</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="id2921641"></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>
285
-- <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
286
-CSS and Javascript-based methods of history disclosure. The global-history
287
-component is what is used by Firefox to determine if a link was visited or not
288
-(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>
289
-and <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29" target="_top">addURI</a>
290
-methods, Torbutton is able to selectively prevent history items from being
291
-added or being displayed as visited, depending on the Tor state and the user's
292
-preferences.
293
-</p><p>
294
-This component helps satisfy the <a class="link" href="#state">State Separation</a>
295
-and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton.
296
-</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>
297
-- <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>
298
-
299
-The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html" target="_top">livemark</a> service
300
-is started by a timer that runs 5 seconds after Firefox
301
-startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
302
-disable it. We must wrap the component to prevent this start() call from
303
-firing in the event the browser starts in Tor mode.
304
-
305
-</p><p>
306
-This component helps satisfy the <a class="link" href="#isolation">Network
307
-Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
308
-Preservation</a> requirements.
309
-</p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2922900"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the
310
-extension. These components do not hook any interfaces, nor are they used
311
-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="id2909775"></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
312
-- 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
313
-Jackson</a>) is used by the Torbutton chrome to switch between
314
-Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
315
-move the current cookies.txt file to the appropriate backup location
316
-(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
317
-into place.</p><p>
318
-This component helps to address the <a class="link" href="#state">State
319
-Isolation</a> requirement of Torbutton.
320
-</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="id2906606"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1
321
-- components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
322
-logging messages to either Firefox stderr
323
-(<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
324
-(<span class="command"><strong>extensions.torbutton.logmethod=1</strong></span>), or the DebugLogger extension (if
325
-available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
326
-change the loglevel on the fly by changing
327
-<span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
328
-</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
329
-- 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
330
-state the tab was most recently used under to fetch a page. The problem is
331
-that for many Firefox events, it is not possible to determine the tab that is
332
-actually receiving the event. The Torbutton window mapper allows the Torbutton
333
-chrome and other components to look up a <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
334
-tab</a> for a given <a class="ulink" href="https://developer.mozilla.org/en/nsIDOMWindow" target="_top">HTML content
335
-window</a>. It does this by traversing all windows and all browsers, until it
336
-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
337
-and page loading in general can generate hundreds of these lookups, this
338
-result is cached inside the component.
339
-</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
340
-- components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is
341
-toggled, Javascript is disabled, and pages are instructed to stop loading.
342
-However, CSS is still able to perform network operations by loading styles for
343
-onmouseover events and other operations. In addition, favicons can still be
344
-loaded by the browser. The cssblocker component prevents this by implementing
345
-and registering an <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy" target="_top">nsIContentPolicy</a>.
346
-When an nsIContentPolicy is registered, Firefox checks every attempted network
347
-request against its <a class="ulink" href="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()" target="_top">shouldLoad</a>
348
-member function to determine if the load should proceed. In Torbutton's case,
349
-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>,
350
-and checks that tab's load tag against the current Tor state. If the tab was
351
-loaded in a different state than the current state, the fetch is denied.
352
-Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#isolation">Network
353
-Isolation</a> requirements of Torbutton.
354
-
355
-<p>In addition, the content policy also blocks website javascript from
356
-<a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">querying for
357
-versions and existence of extension chrome</a> while Tor is enabled, and
358
-also masks the presence of Torbutton to website javascript while Tor is
359
-disabled. </p><p>
360
-
361
-Finally, some of the work that logically belongs to the content policy is
362
-instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
363
-<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
364
-Firefox 3 favicon loads, popups, and full page plugins, which for whatever
365
-reason are not passed to the Firefox content policy itself (see Firefox Bugs 
366
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 
367
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
368
-
369
-</p><p>
370
-
371
-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
372
-Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2907191"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
373
-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
374
-files attached. The scope of these Javascript files is their containing
375
-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
376
-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>.
377
-It contains event handlers for preference update, shutdown, upgrade, and
378
-location change events.</p><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
379
-change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress" target="_top">webprogress
380
-listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most
381
-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
382
-listener</a> that handles receiving an event every time a page load or
383
-iframe load occurs. This class eventually calls down to
384
-<code class="function">torbutton_update_tags()</code> and
385
-<code class="function">torbutton_hookdoc()</code>, which apply the browser Tor load
386
-state tags, plugin permissions, and install the Javascript hooks to hook the
387
-<a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
388
-object to obfuscate browser and desktop resolution information.
389
-
390
-</p><p>
391
-The browser overlay helps to satisfy a number of Torbutton requirements. These
392
-are better enumerated in each of the Torbutton preferences below. However,
393
-there are also a number of Firefox preferences set in
394
-<code class="function">torbutton_update_status()</code> that aren't governed by any
395
-Torbutton setting. These are:
396
-</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>
397
-Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
398
-reads from <span class="command"><strong>extensions.torbutton.banned_ports</strong></span>) to the list
399
-of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
400
-and the Tor control port, respectively. This is set for both Tor and Non-Tor
401
-usage, and prevents websites from attempting to do http fetches from these
402
-ports to see if they are open, which addresses the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
403
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.send_pings" target="_top">browser.send_pings</a><p>
404
-This setting is currently always disabled. If anyone ever complains saying
405
-that they *want* their browser to be able to send ping notifications to a
406
-page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
407
-my breath. I haven't checked if the content policy is called for pings, but if
408
-not, this setting helps with meeting the <a class="link" href="#isolation">Network
409
-Isolation</a> requirement.
410
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups" target="_top">browser.safebrowsing.remoteLookups</a><p>
411
-Likewise for this setting. I find it hard to imagine anyone who wants to ask
412
-Google in real time if each URL they visit is safe, especially when the list
413
-of unsafe URLs is downloaded anyway. This helps fulfill the <a class="link" href="#disk">Disk Avoidance</a> requirement, by preventing your entire
414
-browsing history from ending up on Google's disks.
415
- </p></li><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Browser.safebrowsing.enabled" target="_top">browser.safebrowsing.enabled</a><p>
416
-Safebrowsing does <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=360387" target="_top">unauthenticated
417
-updates under Firefox 2</a>, so it is disabled during Tor usage. 
418
-This helps fulfill the <a class="link" href="#updates">Update
419
-Safety</a> requirement. Firefox 3 has the fix for that bug, and so
420
-safebrowsing updates are enabled during Tor usage.
421
- </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>
422
-If Tor is enabled, we need to prevent random external applications from
423
-launching without at least warning the user. This group of settings only
424
-partially accomplishes this, however. Applications can still be launched via
425
-plugins. The mechanisms for handling this are described under the "Disable
426
-Plugins During Tor Usage" preference. This helps fulfill the <a class="link" href="#proxy">Proxy Obedience</a> requirement, by preventing external
427
-applications from accessing network resources at the command of Tor-fetched
428
-pages. Unfortunately, due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a>
429
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a>,
430
-these prefs are no longer obeyed. They are set still anyway out of respect for
431
-the dead.
432
- </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>
433
-
434
-To help satisfy the Torbutton <a class="link" href="#state">State Separation</a>
435
-and <a class="link" href="#isolation">Network Isolation</a> requirements,
436
-Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
437
-"Undo Close" operations from accidentally restoring tabs from a different Tor
438
-State. This purge is accomplished by setting this preference to 0 and then
439
-restoring it to the previous user value upon toggle.
440
-
441
-   </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span><p>
442
-TLS Session IDs can persist for an indefinite duration, providing an
443
-identifier that is sent to TLS sites that can be used to link activity. This
444
-is particularly troublesome now that we have certificate verification in place
445
-in Firefox 3: The OCSP server can use this Session ID to build a history of
446
-TLS sites someone visits, and also correlate their activity as users move from
447
-network to network (such as home to work to coffee shop, etc), inside and
448
-outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we currently 
449
-toggle
450
-<span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
451
-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
452
-line 2134</a>. This is an arcane and potentially fragile fix. It would be
453
-better if there were a more standard interface for accomplishing the same
454
-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
455
-been filed for this.
456
-
457
-   </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>
458
-
459
-Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
460
-is enabled. This helps Torbutton maintain its
461
-<a class="link" href="#location">Location Neutrality</a> requirement.
462
-While Firefox does prompt before divulging geolocational information,
463
-the assumption is that Tor users will never want to give their
464
-location away during Tor usage, and even allowing websites to prompt
465
-them to do so will only cause confusion and accidents to happen. Moreover,
466
-just because users may approve a site to know their location in non-Tor mode
467
-does not mean they want it divulged during Tor mode.
468
-
469
-   </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>
470
-
471
-Firefox actually remembers your zoom settings for certain sites. CSS
472
-and Javascript rule can use this to recognize previous visitors to a site.
473
-This helps Torbutton fulfill its <a class="link" href="#state">State Separation</a>
474
-requirement.
475
-
476
-   </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>
477
-
478
-Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
479
-links on a page to decrease page load latency. While Firefox does typically
480
-disable this behavior when proxies are enabled, we set this pref for added
481
-safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
482
-their links prefetched after a toggle to Non-Tor mode occurs,
483
-we also set the docShell attribute
484
-<a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell" target="_top">
485
-allowDNSPrefetch</a> to false on Tor loaded tabs. This happens in the same
486
-positions in the code as those for disabling plugins via the allowPlugins
487
-docShell attribute. This helps Torbutton fulfill its <a class="link" href="#isolation">Network Isolation</a> requirement.
488
-
489
-   </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>
490
-
491
-Firefox has the ability to store web applications in a special cache to allow
492
-them to continue to operate while the user is offline. Since this subsystem
493
-is actually different than the normal disk cache, it must be dealt with
494
-separately. Thus, Torbutton sets this preference to false whenever Tor is
495
-enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk
496
-Avoidance</a> and <a class="link" href="#state">State Separation</a>
497
-requirements.
498
-
499
-   </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="id2922887"></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
500
-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="id2922834"></a>3.3. Other Windows</h3></div></div></div><p>There are additional windows that describe popups for right clicking on
501
-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="id2917336"></a>4. Toggle Code Path</h2></div></div></div><p>
502
-
503
-The act of toggling is connected to <code class="function">torbutton_toggle()</code>
504
-via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
505
-and <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul" target="_top">popup.xul</a>
506
-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> 
507
-
508
-</p><p>
509
-
510
-Toggling is a 3 stage process: Button Click, Proxy Update, and
511
-Settings Update. These stages are reflected in the prefs
512
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
513
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
514
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
515
-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
516
-javascript runs on a different thread than the chrome javascript, it is
517
-important to properly convey the stages to the content policy to avoid race
518
-conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
519
-409737</a> unfixed. The content policy does not allow any network activity
520
-whatsoever during this three stage transition.
521
-
522
- </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2934128"></a>4.1. Button Click</h3></div></div></div><p>
523
-
524
-This is the first step in the toggling process. When the user clicks the
525
-toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
526
-called. This function checks the current Tor status by comparing the current
527
-proxy settings to the selected Tor settings, and then sets the proxy settings
528
-to the opposite state, and sets the pref
529
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
530
-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
531
-observer</a>
532
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
533
-toggle.
534
-
535
-  </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2915503"></a>4.2. Proxy Update</h3></div></div></div><p>
536
-
537
-When Torbutton receives any proxy change notifications via its
538
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
539
-<code class="function">torbutton_set_status()</code> which checks against the Tor
540
-settings to see if the Tor proxy settings match the current settings. If so,
541
-it calls <code class="function">torbutton_update_status()</code>, which determines if
542
-the Tor state has actually changed, and sets
543
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
544
-state value, and ensures that
545
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
546
-value. This is decoupled from the button click functionalty via the pref
547
-observer so that other addons (such as SwitchProxy) can switch the proxy
548
-settings between multiple proxies.
549
-
550
-  </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2931338"></a>4.3. Settings Update</h3></div></div></div><p>
551
-
552
-The next stage is also handled by
553
-<code class="function">torbutton_update_status()</code>. This function sets scores of
554
-Firefox preferences, saving the original values to prefs under
555
-<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the history
556
-clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
557
-end of its work, it sets
558
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
559
-completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
560
-
561
-  </p></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2898010"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each
562
-option is presented as the string from the preferences window, a summary, the
563
-preferences it touches, and the effect this has on the components, chrome, and
564
-browser properties.</p><div class="sect2" title="5.1. Test Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2910532"></a>5.1. Test Settings</h3></div></div></div><p>
565
-This button under the Proxy Settings tab provides a way to verify that the 
566
-proxy settings are correct, and actually do route through the Tor network. It
567
-performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a>
568
-for <a class="ulink" href="https://check.torproject.org/?TorButton=True" target="_top">https://check.torproject.org/?Torbutton=True</a>.
569
-This is a special page that returns very simple, yet well-formed XHTML that
570
-Torbutton can easily inspect for a hidden link with an id of
571
-<span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
572
-or <span class="command"><strong>failure</strong></span> to indicate if the
573
-user hit the page from a Tor IP, a non-Tor IP. This check is handled in
574
-<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>.
575
-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
576
-window</a>
577
-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>.  
578
-
579
-  </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
580
-address</a> and report it back to the
581
-remote site. They can also <a class="ulink" href="http://decloak.net" target="_top">bypass proxy settings</a> and directly connect to a
582
-remote site without Tor. Every browser plugin we have tested with Firefox has
583
-some form of network capability, and every one ignores proxy settings or worse - only
584
-partially obeys them. This includes but is not limited to:
585
-QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
586
-Flash. 
587
-
588
- </p><p>
589
-Enabling this preference causes the above mentioned Torbutton chrome web progress
590
- 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
591
- plugins via the browser <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell" target="_top">docShell</a>
592
- attribute <span class="command"><strong>allowPlugins</strong></span>. These flags are set every time a new window is
593
- created (<code class="function">torbutton_tag_new_browser()</code>), every time a web
594
-load
595
-event occurs
596
- (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
597
- (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
598
- 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
599
- enabled and this option is set.
600
- </p><p>All of this turns out to be insufficient if the user directly clicks
601
-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>,
602
-the browser decides that maybe it should ignore all these other settings and
603
-load the plugin anyways, because maybe the user really did want to load it
604
-(never mind this same load-style could happen automatically  with meta-refresh
605
-or any number of other ways..). To handle these cases, Torbutton stores a list
606
-of plugin-handled mime-types, and sets the pref
607
-<span class="command"><strong>plugin.disable_full_page_plugin_for_types</strong></span> to this list.
608
-Additionally, (since nothing can be assumed when relying on Firefox
609
-preferences and internals) if it detects a load of one of them from the web
610
-progress listener, it cancels the request, tells the associated DOMWindow to
611
-stop loading, clears the document, AND throws an exception. Anything short of
612
-all this and the plugin managed to find some way to load.
613
- </p><p>
614
- 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
615
- allowPlugins</a> for directly visited URLs, or notify its content policy for such
616
- 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
617
- not very encouraging.
618
- </p><p>
619
-
620
-Since most plugins completely ignore browser proxy settings, the actions
621
-performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
622
-
623
- </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="id2917719"></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
624
-mentioned above, and causes it to block content load attempts in pages an
625
-opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
626
-tabs</a> are tagged
627
-with a <span class="command"><strong>__tb_load_state</strong></span> member in
628
-<code class="function">torbutton_update_tags()</code> and this
629
-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
630
-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
631
-<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
632
-equivalent of hitting the STOP button).</p><p>
633
-
634
-Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox bug
635
-409737</a> prevents <span class="command"><strong>docShell.allowJavascript</strong></span> from killing
636
-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>
637
-are still able to execute. The <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton Content
638
-Policy</a> should prevent such code from performing network activity within
639
-the current tab, but activity that happens via a popup window or via a
640
-Javascript redirect can still slip by. For this reason, Torbutton blocks
641
-popups by checking for a valid <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.opener" target="_top">window.opener</a>
642
-attribute in <code class="function">torbutton_check_progress()</code>. If the window
643
-has an opener from a different Tor state, its load is blocked. The content
644
-policy also takes similar action to prevent Javascript redirects. This also
645
-has the side effect/feature of preventing the user from following any links
646
-from a page loaded in an opposite Tor state.
647
-
648
-</p><p>
649
-This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
650
-</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
651
-hooking code</a>. This is done in the chrome in
652
-<code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
653
-<a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
654
-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
655
-javascript: urls).
656
-
657
-In the Firefox 2 days, this option did a lot more than
658
-it does now. It used to be responsible for timezone and improved useragent
659
-spoofing, and history object cloaking. However, now it only provides
660
-obfuscation of the <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
661
-object to mask your browser and desktop resolution.
662
-The resolution hooks
663
-effectively make the Firefox browser window appear to websites as if the renderable area
664
-takes up the entire desktop, has no toolbar or other GUI element space, and
665
-the desktop itself has no toolbars.
666
-These hooks drastically reduce the amount of information available to do <a class="link" href="#fingerprinting">anonymity set reduction attacks</a> and help to
667
-meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
668
-requirements. Unfortunately, Gregory Fleischer discovered it is still possible
669
-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>
670
-or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html" target="_top">Components.lookupMethod</a>.
671
-We are still looking for a workaround as of Torbutton 1.2.5.
672
-
673
-
674
-
675
-</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="id2897638"></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>
676
-
677
-This option drastically cuts down on the number of distinct anonymity sets
678
-that divide the Tor web userbase. Without this setting, the dimensions for a
679
-typical browser window range from 600-1200 horizontal pixels and 400-1000
680
-vertical pixels, or about 600x600 = 360000 different sets. Resizing the
681
-browser window to multiples of 50 on each side reduces the number of sets by
682
-50^2, bringing the total number of sets to 144. Of course, the distribution
683
-among these sets are not uniform, but scaling by 50 will improve the situation
684
-due to this non-uniformity for users in the less common resolutions.
685
-Obviously the ideal situation would be to lie entirely about the browser
686
-window size, but this will likely cause all sorts of rendering issues, and is
687
-also not implementable in a foolproof way from extension land.
688
-
689
-</p><p>
690
-
691
-The implementation of this setting is spread across a couple of different
692
-locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">browser
693
-overlay</a>. Since resizing minimized windows causes them to be restored,
694
-and since maximized windows remember their previous size to the pixel, windows
695
-must be resized before every document load (at the time of browser tagging)
696
-via <code class="function">torbutton_check_round()</code>, called by
697
-<code class="function">torbutton_update_tags()</code>. To prevent drift, the extension
698
-tracks the original values of the windows and uses this to perform the
699
-rounding on document load. In addition, to prevent the user from resizing a
700
-window to a non-50px multiple, a resize listener
701
-(<code class="function">torbutton_do_resize()</code>) is installed on every new browser
702
-window to record the new size and round it to a 50px multiple while Tor is
703
-enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
704
-are set. This ensures that there is no discrepancy between the 50 pixel cutoff
705
-and the actual renderable area of the browser (so that it is not possible to
706
-infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
707
-
708
-</p><p>
709
-This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
710
-</p></div><div class="sect2" title="5.6. Disable Updates During Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2924640"></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
711
-update settings</a> during Tor
712
-  usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
713
-<span class="command"><strong>app.update.enabled</strong></span>,
714
-  <span class="command"><strong>app.update.auto</strong></span>, and
715
-<span class="command"><strong>browser.search.update</strong></span>.  These prevent the
716
-  browser from updating extensions, checking for Firefox upgrades, and
717
-  checking for search plugin updates while Tor is enabled.
718
-  </p><p>
719
-This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
720
-</p></div><div class="sect2" title="5.7. Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892217"></a>5.7. Redirect Torbutton Updates Via Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.update_torbutton_via_tor</strong></span></p><p>This setting causes Torbutton to install an
721
-
722
-<a class="ulink" href="https://developer.mozilla.org/en/nsIProtocolProxyFilter" target="_top">nsIProtocolProxyFilter</a>
723
-in order to redirect all version update checks and Torbutton update downloads
724
-via Tor, regardless of if Tor is enabled or not. This was done both to address
725
-concerns about data retention done by <a class="ulink" href="https://www.addons.mozilla.org" target="_top">addons.mozilla.org</a>, as well as to
726
-help censored users meet the <a class="link" href="#undiscoverability">Tor
727
-Undiscoverability</a> requirement.
728
-
729
-  </p></div><div class="sect2" title="5.8. Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892261"></a>5.8. Disable Search Suggestions during Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
730
-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>
731
-during Tor usage.
732
-This governs if you get Google search suggestions during Tor
733
-usage. Your Google cookie is transmitted with google search suggestions, hence
734
-this is recommended to be disabled.
735
-
736
-</p><p>
737
-While this setting doesn't satisfy any Torbutton requirements, the fact that
738
-cookies are transmitted for partially typed queries does not seem desirable
739
-for Tor usage.
740
-</p></div><div class="sect2" title="5.9. Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892300"></a>5.9. Disable livemarks updates during Tor usage (recommended)</h3></div></div></div><p>Option:
741
-   </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>
742
-  </p><p>
743
-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
744
-Tor usage. Because people often have very personalized Livemarks (such as RSS
745
-feeds of Wikipedia articles they maintain, etc). This is accomplished both by
746
-<a class="link" href="#livemarks" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js">wrapping the livemark-service component</a> and
747
-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
748
-service</a> when Tor is enabled.
749
-
750
-</p><p>
751
-This helps satisfy the <a class="link" href="#isolation">Network
752
-Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
753
-Preservation</a> requirements.
754
-</p></div><div class="sect2" title="5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892371"></a>5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</h3></div></div></div><p>Options:
755
-   </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>
756
-  </p><p>
757
-
758
-These settings prevent file urls from performing network operations during the
759
-respective Tor states. Firefox 2's implementation of same origin policy allows
760
-file urls to read and <a class="ulink" href="http://www.gnucitizen.org/blog/content-disposition-hacking/" target="_top">submit
761
-arbitrary files from the local filesystem</a> to arbitrary websites. To
762
-make matters worse, the 'Content-Disposition' header can be injected
763
-arbitrarily by exit nodes to trick users into running arbitrary html files in
764
-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
765
-resources from File urls during the appropriate Tor state.
766
-
767
-</p><p>
768
-
769
-This preference helps to ensure Tor's <a class="link" href="#isolation">Network
770
-Isolation</a> requirement, by preventing file urls from executing network
771
-operations in opposite Tor states. Also, allowing pages to submit arbitrary
772
-files to arbitrary sites just generally seems like a bad idea.
773
-
774
-</p></div><div class="sect2" title="5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892443"></a>5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</h3></div></div></div><p>Options:
775
-   </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>
776
-  </p><p>
777
-
778
-These settings cause Torbutton to enumerate through all windows and close all
779
-tabs in each window for the appropriate Tor state. This code can be found in
780
-<code class="function">torbutton_update_status()</code>.  The main reason these settings
781
-exist is as a backup mechanism in the event of any Javascript or content policy
782
-leaks due to <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
783
-409737</a>.  Torbutton currently tries to block all Javascript network
784
-activity via the content policy, but until that bug is fixed, there is some
785
-risk that there are alternate ways to bypass the policy. This option is
786
-available as an extra assurance of <a class="link" href="#isolation">Network
787
-Isolation</a> for those who would like to be sure that when Tor is toggled
788
-all page activity has ceased. It also serves as a potential future workaround
789
-in the event a content policy failure is discovered, and provides an additional
790
-level of protection for the <a class="link" href="#disk">Disk Avoidance</a>
791
-protection so that browser state is not sitting around waiting to be swapped
792
-out longer than necessary.
793
-
794
-</p><p>
795
-While this setting doesn't satisfy any Torbutton requirements, the fact that
796
-cookies are transmitted for partially typed queries does not seem desirable
797
-for Tor usage.
798
-</p></div><div class="sect2" title="5.12. Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892524"></a>5.12. 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>
799
-This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener" target="_top">nsISHistoryListener</a>
800
-attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">sessionHistory</a> of 
801
-of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation" target="_top">webNavigatator</a>.
802
-The nsIShistoryListener is instantiated with a reference to the containing
803
-browser window and blocks the back, forward, and reload buttons on the browser
804
-navigation bar when Tor is in an opposite state than the one to load the
805
-current tab. In addition, Tor clears the session history during a new document
806
-load if this setting is enabled. 
807
-
808
-  </p><p>
809
-
810
-This is marked as a crucial setting in part
811
-because Javascript access to the history object is indistinguishable from 
812
-user clicks, and because
813
-<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug
814
-409737</a> allows javascript to execute in opposite Tor states, javascript
815
-can issue reloads after Tor toggle to reveal your original IP. Even without
816
-this bug, however, Javascript is still able to access previous pages in your
817
-session history that may have been loaded under a different Tor state, to
818
-attempt to correlate your activity.
819
-
820
-   </p><p>
821
-
822
-This setting helps to fulfill Torbutton's <a class="link" href="#state">State
823
-Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
824
-requirements.
825
-
826
-   </p></div><div class="sect2" title="5.13. History Access Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2892609"></a>5.13. History Access Settings</h3></div></div></div><p>Options:
827
-  </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>
828
-  </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>
829
-history blocker component mentioned above. By hooking the browser's view of
830
-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>
831
-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>
832
-components, this mechanism defeats all document-based <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure
833
-attacks</a>, including <a class="ulink" href="http://ha.ckers.org/weird/CSS-history.cgi" target="_top">CSS-only attacks</a>.
834
-
835
-The component also hooks functions involved in writing history to disk via
836
-both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History" target="_top">Places
837
-Database</a> and the older Firefox 2 mechanisms.
838
-
839
-</p><p>
840
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
841
-</p></div><div class="sect2" title="5.14. Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2892721"></a>5.14. 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
842
-<a class="ulink" href="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29" target="_top">nsIBrowserHistory.removeAllPages</a>
843
-and <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">nsISHistory.PurgeHistory</a>
844
-for each tab on Tor toggle.</p><p>
845
-This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.
846
-</p></div><div class="sect2" title="5.15. Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2934267"></a>5.15. Block Password+Form saving during Tor/Non-Tor</h3></div></div></div><p>Options:
847
-  </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>
848
-  </p><p>These settings govern if Torbutton disables
849
-<span class="command"><strong>browser.formfill.enable</strong></span>
850
-and <span class="command"><strong>signon.rememberSignons</strong></span> during Tor and Non-Tor usage.
851
-Since form fields can be read at any time by Javascript, this setting is a lot
852
-more important than it seems.
853
-</p><p>
854
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
855
-</p></div><div class="sect2" title="5.16. Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2934328"></a>5.16. 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>
856
-  </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>
857
-on Tor toggle to remove all entries from the cache. In addition, this setting
858
-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.
859
-</p><p>
860
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
861
-</p></div><div class="sect2" title="5.17. Block disk and memory cache during Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2934378"></a>5.17. 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
862
-causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>,
863
-<a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and
864
-<a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage.
865
-</p><p>
866
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
867
-</p></div><div class="sect2" title="5.18. Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2934430"></a>5.18. Clear Cookies on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
868
-  </p><p>
869
-
870
-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
871
-every Tor toggle. In addition, this sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
872
-to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
873
-which prevents them from being written to disk. 
874
-
875
-</p><p>
876
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
877
-</p></div><div class="sect2" title="5.19. Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h3 class="title"><a id="id2934481"></a>5.19. Store Non-Tor cookies in a protected jar</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
878
-  </p><p>
879
-
880
-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
881
-non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
882
-before restoring the jar.
883
-</p><p>
884
-This setting also sets <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
885
-to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
886
-which prevents them from being written to disk. 
887
-
888
-</p><p>
889
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
890
-</p></div><div class="sect2" title="5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2934538"></a>5.20. 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>
891
-  </p><p>
892
-
893
-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
894
-both Tor and Non-Tor cookies into protected jars.
895
-</p><p>
896
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
897
-</p></div><div class="sect2" title="5.21. Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2934577"></a>5.21. 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
898
-cookie prefs all to false.</p></div><div class="sect2" title="5.22. Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2934592"></a>5.22. Disable DOM Storage during Tor usage (crucial)</h3></div></div></div><div class="sect2" title="5.22.1. Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h3 class="title"><a id="id2934594"></a>5.22.1. Do not write Tor/Non-Tor cookies to disk</h3></div></div></div><p>Options:
899
-  </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>
900
-  </p><p>
901
-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>
902
-to 2 during the appropriate Tor state, and to store cookies acquired in that
903
-state into a Javascript
904
-<a class="ulink" href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X" target="_top">E4X</a>
905
-object as opposed to writing them to disk.
906
-</p><p>
907
-This allows Torbutton to provide an option to preserve a user's 
908
-cookies while still satisfying the <a class="link" href="#disk">Disk Avoidance</a>
909
-requirement.
910
-</p></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_domstorage</strong></span>
911
-  </p><p>
912
-
913
-This setting causes Torbutton to toggle <span class="command"><strong>dom.storage.enabled</strong></span> during Tor
914
-usage to prevent 
915
-<a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from
916
-  being used to store persistent information across Tor states.</p><p>
917
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
918
-</p></div><div class="sect2" title="5.23. Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2934696"></a>5.23. Clear HTTP Auth on Tor Toggle (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
919
-  </p><p>
920
-This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager" target="_top">nsIHttpAuthManager.clearAll()</a>
921
-every time Tor is toggled.
922
-</p><p>
923
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
924
-</p></div><div class="sect2" title="5.24. Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h3 class="title"><a id="id2934733"></a>5.24. Clear cookies on Tor/Non-Tor shutdown</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
925
-  </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
926
-cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
927
-clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
928
-for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
929
-<code class="function">https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</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>
930
-to clear out all cookies and all cookie jars upon shutdown.  </p><p>
931
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
932
-</p></div><div class="sect2" title="5.25. Reload cookie jar/clear cookies on Firefox crash"><div class="titlepage"><div><div><h3 class="title"><a id="id2934788"></a>5.25. Reload cookie jar/clear cookies on Firefox crash</h3></div></div></div><p>Options:
933
-  </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>
934
-  </p><p>This is no longer a user visible option, and is enabled by default. In
935
-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> 
936
-  component will notify the Chrome (via the
937
-  <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
938
-observer</a> in
939
-the chrome that listens for this update), and Torbutton will load the
940
-  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>
941
-  component.</p><p>
942
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
943
-crashes.
944
-</p></div><div class="sect2" title="5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2934863"></a>5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</h3></div></div></div><p>Options:
945
-  </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>
946
-  </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> 
947
-  to set the Tor state after a crash is detected (via the 
948
-  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref). To confirm for
949
-false positives (such as session restore failures, upgrade, normal
950
-session restore, etc), Torbutton also sets the pref
951
-extensions.torbutton.normal_exit during
952
-Firefox exit and checks this value as well during startup.  
953
-</p><p>
954
-
955
-Since the Tor state after a Firefox crash is unknown/indeterminate, this
956
-setting helps to satisfy the <a class="link" href="#state">State Separation</a>
957
-requirement in the event of Firefox crashes by ensuring all cookies,
958
-settings and saved sessions are reloaded from a fixed Tor state.
959
- 
960
-</p></div><div class="sect2" title="5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State"><div class="titlepage"><div><div><h3 class="title"><a id="id2934935"></a>5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</h3></div></div></div><p>Options:
961
-  </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>
962
-  </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> 
963
-  to set the Tor state after a normal startup is detected (via the 
964
-  <span class="command"><strong>extensions.torbutton.noncrashed</strong></span> pref). To confirm for
965
-false positives
966
-(such as session restore failures, etc), Torbutton also sets the pref
967
-extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
968
-Firefox exit and checks this value as well during startup.
969
-  
970
-</p></div><div class="sect2" title="5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h3 class="title"><a id="id2934994"></a>5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</h3></div></div></div><p>Options: 
971
-  </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>
972
-  </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>
973
-  component checks the <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tabs before writing them
974
-  out. If the tag is from a blocked Tor state, the tab is not written to disk.
975
-  </p><p>
976
-This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
977
-requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
978
-crashes.
979
-
980
-</p></div><div class="sect2" title="5.29. Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2935059"></a>5.29. Set user agent during Tor usage (crucial)</h3></div></div></div><p>Options:
981
-   </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>
982
-   </p><p>On face, user agent switching appears to be straight-forward in Firefox.
983
-It provides several options for controlling the browser user agent string:
984
-<span class="command"><strong>general.appname.override</strong></span>,
985
-<span class="command"><strong>general.appversion.override</strong></span>,
986
-<span class="command"><strong>general.platform.override</strong></span>,
987
-<span class="command"><strong>general.oscpu.override</strong></span>,
988
-<span class="command"><strong>general.productSub.override</strong></span>,
989
-<span class="command"><strong>general.buildID.override</strong></span>,
990
-<span class="command"><strong>general.useragent.override</strong></span>,
991
-<span class="command"><strong>general.useragent.vendor</strong></span>, and
992
-<span class="command"><strong>general.useragent.vendorSub</strong></span>. If
993
-the Torbutton preference <span class="command"><strong>extensions.torbutton.set_uagent</strong></span> is
994
-true, Torbutton copies all of the other above prefs into their corresponding
995
-browser preferences during Tor usage.</p><p>
996
-
997
-It also turns out that it is possible to detect the original Firefox version
998
-by <a class="ulink" href="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/" target="_top">inspecting
999
-certain resource:// files</a>. These cases are handled by Torbutton's
1000
-<a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
1001
-
1002
-</p><p>
1003
-This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1004
-</p></div><div class="sect2" title="5.30. Spoof US English Browser"><div class="titlepage"><div><div><h3 class="title"><a id="id2935233"></a>5.30. Spoof US English Browser</h3></div></div></div><p>Options:
1005
-</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>
1006
-</p><p> This option causes Torbutton to set
1007
-<span class="command"><strong>general.useragent.locale</strong></span>
1008
-<span class="command"><strong>intl.accept_languages</strong></span> to the value specified in
1009
-<span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
1010
-<span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
1011
-<span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
1012
-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>.
1013
- </p><p>
1014
-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.
1015
-</p></div><div class="sect2" title="5.31. Don't send referrer during Tor Usage"><div class="titlepage"><div><div><h3 class="title"><a id="id2935326"></a>5.31. Don't send referrer during Tor Usage</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_referer</strong></span>
1016
-</p><p> 
1017
-This option causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer" target="_top">network.http.sendSecureXSiteReferrer</a> and
1018
-<a class="ulink" href="http://kb.mozillazine.org/Network.http.sendRefererHeader" target="_top">network.http.sendRefererHeader</a> during Tor usage.</p><p>
1019
-This setting also does not directly satisfy any Torbutton requirement, but
1020
-some may desire to mask their referrer for general privacy concerns.
1021
-</p></div><div class="sect2" title="5.32. Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h3 class="title"><a id="id2935366"></a>5.32. Strip platform and language off of Google Search Box queries</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.fix_google_srch</strong></span>
1022
-</p><p> 
1023
-
1024
-This option causes Torbutton to use the <a class="ulink" href="https://wiki.mozilla.org/Search_Service:API" target="_top">@mozilla.org/browser/search-service;1</a>
1025
-component to wrap the Google search plugin. On many platforms, notably Debian
1026
-and Ubuntu, the Google search plugin is set to reveal a lot of language and
1027
-platform information. This setting strips off that info while Tor is enabled.
1028
-
1029
-</p><p>
1030
-This setting helps Torbutton to fulfill its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1031
-</p></div><div class="sect2" title="5.33. Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h3 class="title"><a id="id2935407"></a>5.33. Automatically use an alternate search engine when presented with a
1032
-Google Captcha</h3></div></div></div><p>Options:
1033
-</p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.asked_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.dodge_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.google_redir_url</strong></span></td></tr></table><p>
1034
-</p><p>
1035
-
1036
-Google's search engine has rate limiting features that cause it to
1037
-<a class="ulink" href="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html" target="_top">present
1038
-captchas</a> and sometimes even outright ban IPs that issue large numbers
1039
-of search queries, especially if a lot of these queries appear to be searching
1040
-for software vulnerabilities or unprotected comment areas.
1041
-
1042
-</p><p>
1043
-
1044
-Despite multiple discussions with Google, we were unable to come to a solution
1045
-or any form of compromise that would reduce the number of captchas and
1046
-outright bans seen by Tor users issuing regular queries.
1047
-
1048
-</p><p>
1049
-As a result, we've implemented this option as an <a class="ulink" href="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers" target="_top">'http-on-modify-request'</a>
1050
-http observer to optionally redirect banned or captcha-triggering Google
1051
-queries to search engines that do not rate limit Tor users. The current
1052
-options are ixquick.com, bing.com, yahoo.com and scroogle.org. These are
1053
-encoded in the preferences
1054
-<span class="command"><strong>extensions.torbutton.redir_url.[1-4]</strong></span>.
1055
-
1056
-</p></div><div class="sect2" title="5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2935487"></a>5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h3></div></div></div><p>Options:
1057
-</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>
1058
-</p><p>
1059
-
1060
-These settings govern if Torbutton attempts to isolate the user's SSL
1061
-certificates into separate jars for each Tor state. This isolation is
1062
-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>,
1063
-which calls <code class="function">torbutton_jar_cert_type()</code> and
1064
-<code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
1065
-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>.
1066
-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>.
1067
-</p><p>
1068
-The first time this pref is used, a backup of the user's certificates is
1069
-created in their profile directory under the name
1070
-<code class="filename">cert8.db.bak</code>. This file can be copied back to
1071
-<code class="filename">cert8.db</code> to fully restore the original state of the
1072
-user's certificates in the event of any error.
1073
-</p><p>
1074
-Since exit nodes and malicious sites can insert content elements sourced to
1075
-specific SSL sites to query if a user has a certain certificate,
1076
-this setting helps to satisfy the <a class="link" href="#state">State
1077
-Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Firefox Bug
1078
-435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
1079
-is currently not exposed via the preferences UI.
1080
-
1081
-</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>
1082
-
1083
-  </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>
1084
-
1085
-Torbutton has to work around a number of Firefox bugs that impact its
1086
-security. Most of these are mentioned elsewhere in this document, but they
1087
-have also been gathered here for reference. In order of decreasing severity,
1088
-they are:
1089
-
1090
-   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=429070" target="_top">Bug 429070 - exposing
1091
-Components.interfaces to untrusted content leaks information about installed
1092
-extensions</a><p>
1093
-<a class="ulink" href="http://pseudo-flaw.net/" target="_top">Gregory Fleischer</a> demonstrated at Defcon 17 that these interfaces can
1094
-also be used to <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html" target="_top">fingerprint
1095
-Firefox down the to the minor version</a>. Note that his test has not been
1096
-updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This
1097
-bug interferes with Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1098
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=280661" target="_top">Bug 280661 - SOCKS proxy server
1099
-connection timeout hard-coded</a><p>
1100
-
1101
-This bug prevents us from using the Firefox SOCKS layer directly, and
1102
-currently requires us to ship an auxiliary HTTP proxy called <a class="ulink" href="http://www.pps.jussieu.fr/~jch/software/polipo/" target="_top">Polipo</a>. If this
1103
-patch were landed, we would no longer need to ship Polipo, which has a number
1104
-of privacy and security issues of its own (in addition to being unmaintained).
1105
-
1106
-    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418986" target="_top">Bug 418986 - window.screen
1107
-provides a large amount of identifiable information</a><p>
1108
-
1109
-As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of
1110
-information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>.
1111
-Currently, there is no way to obscure this information without Javascript
1112
-hooking. This bug is a feature request to provide some other method to change
1113
-these values. This bug interferes with Torbutton's ability to fulfill its
1114
-<a class="link" href="#setpreservation">Anonymity Set Preservation</a>
1115
-requirement.
1116
-
1117
-   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=435159" target="_top">Bug 435159 -
1118
-nsNSSCertificateDB::DeleteCertificate has race conditions</a><p>
1119
-
1120
-In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
1121
-the user has installed. Unfortunately, the method call to delete a certificate
1122
-from the current certificate database acts lazily: it only sets a variable
1123
-that marks a cert for deletion later, and it is not cleared if that
1124
-certificate is re-added. This means that if the Tor state is toggled quickly,
1125
-that certificate could remain present until it is re-inserted (causing an
1126
-error dialog), and worse, it would still be deleted after that.  The lack of
1127
-this functionality is considered a Torbutton security bug because cert
1128
-isolation is considered a <a class="link" href="#state">State Separation</a>
1129
-feature.
1130
-
1131
-      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=575230" target="_top">Bug 575230 - Provide option to
1132
-reduce precision of Date()</a><p>
1133
-
1134
-Currently it is possible to <a class="ulink" href="http://arstechnica.com/tech-policy/news/2010/02/firm-uses-typing-cadence-to-finger-unauthorized-users.ars" target="_top">fingerprint
1135
-users based on their typing cadence</a> using the high precision timer
1136
-available to javascript. Using this same precision, it is possible to compute
1137
-an identifier based upon the clock drift of the client from some nominal
1138
-source. The latter is not much of a concern for Tor users, as the variable
1139
-delay to load and run a page is measured on the order of seconds, but the high
1140
-precision timer can still be used to fingerprint aspects of a browser's
1141
-javascript engine and processor, and apparently also a user's typing cadence.
1142
-This bug hinders Torbutton's ability to satisfy its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1143
-
1144
-      </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Bug 409737 -
1145
-javascript.enabled and docShell.allowJavascript do not disable all event
1146
-handlers</a><p>
1147
-
1148
-This bug allows pages to execute javascript via addEventListener and perhaps
1149
-other callbacks. In order to prevent this bug from enabling an attacker to
1150
-break the <a class="link" href="#isolation">Network Isolation</a> requirement,
1151
-Torbutton 1.1.13 began blocking popups and history manipulation from different
1152
-Tor states.  So long as there are no ways to open popups or redirect the user
1153
-to a new page, the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">Torbutton content
1154
-policy</a> should block Javascript network access. However, if there are
1155
-ways to open popups or perform redirects such that Torbutton cannot block
1156
-them, pages may still have free reign to break that requirement and reveal a
1157
-user's original IP address.
1158
-
1159
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448743" target="_top">Bug 448743 -
1160
-Decouple general.useragent.locale from spoofing of navigator.language</a><p>
1161
-
1162
-Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
1163
-attribute via <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
1164
-these do not work on Firefox 3. It would be ideal to have
1165
-a pref to set this value (something like a
1166
-<span class="command"><strong>general.useragent.override.locale</strong></span>),
1167
-to avoid fragmenting the anonymity set of users of foreign locales. This issue
1168
-impedes Torbutton from fully meeting its <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
1169
-requirement on Firefox 3.
1170
-
1171
-     </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>
1172
-The following bugs impact Torbutton and similar extensions' functionality.
1173
-   </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 -
1174
-Extensions cannot determine if firefox is fullScreen</a><p>
1175
-
1176
-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
1177
-state of the window in some cases on Linux. This causes Torbutton to attempt
1178
-to resize maximized and minimized windows when it should not.
1179
-
1180
-   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=290456" target="_top">Bug 290456 -
1181
-Block/clear Flash MX "cookies" as well</a><p>
1182
-
1183
-Today, it is possible to allow plugins if you have a transparent proxy such as
1184
-<a class="ulink" href="http://anonymityanywhere.com/incognito/" target="_top">Incognito</a> to prevent proxy bypass. However, flash cookies can still be used to
1185
-link your Tor and Non-Tor activity, and this reveal your IP to an adversary
1186
-that does so. This can be solved by manually removing your flash cookies (like
1187
-<a class="ulink" href="https://addons.mozilla.org/en-US/firefox/addon/6623" target="_top">BetterPrivacy</a> does), but
1188
-it would be nice if there was a standard way to do this from a Firefox API.
1189
-
1190
-   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=417869" target="_top">Bug 417869 -
1191
-Browser context is difficult to obtain from many XPCOM callbacks</a><p>
1192
-
1193
-It is difficult to determine which tabbrowser many XPCOM callbacks originate
1194
-from, and in some cases absolutely no context information is provided at all.
1195
-While this doesn't have much of an effect on Torbutton, it does make writing
1196
-extensions that would like to do per-tab settings and content filters (such as
1197
-FoxyProxy) difficult to impossible to implement securely.
1198
-
1199
-   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418321" target="_top">Bug 418321 -
1200
-Components do not expose disk interfaces</a><p>
1201
-
1202
-Several components currently provide no way of reimplementing their disk
1203
-access to easily satisfy Torbutton's <a class="link" href="#disk">Disk
1204
-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
1205
-some of them involve disabling functionality during Tor usage.
1206
-
1207
-   </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>
1208
-The following bugs have an effect upon Torbutton, but are superseded by more
1209
-practical and more easily fixable variant bugs above; or have stable, simple
1210
-workarounds.
1211
-  </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>
1212
-
1213
-Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
1214
-constructors of classes defined from within the scope of the sandbox, among
1215
-other things. This prevents Torbutton from applying the Timezone hooks under
1216
-Firefox 3, but a better solution for Torbutton's specific date hooking needs 
1217
-would be a fix for the above mentioned Bug 392274. Of course, many more
1218
-extensions may be interested in the sandbox hooking functionality working
1219
-properly though.
1220
-
1221
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">Bug 440892 -
1222
-network.protocol-handler.warn-external are ignored</a><p>
1223
-
1224
-Sometime in the Firefox 3 development cycle, the preferences that governed
1225
-warning a user when external apps were launched got disconnected from the code
1226
-that does the launching. Torbutton depended on these prefs to prevent websites
1227
-from launching specially crafted documents and application arguments that
1228
-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
1229
-popup before launching external apps while Tor is enabled. While this works,
1230
-it would be nice if these prefs were either fixed or removed.
1231
-
1232
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">Bug 437014 -
1233
-nsIContentPolicy::shouldLoad no longer called for favicons</a><p>
1234
-
1235
-Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
1236
-loads. Torbutton had relied on this call to block favicon loads for opposite
1237
-Tor states. The workaround it employs for Firefox 3 is to cancel the request
1238
-when it arrives in the <span class="command"><strong>torbutton_http_observer</strong></span> used for
1239
-blocking full page plugin loads. This seems to work just fine, but is a bit
1240
-dirty.
1241
-
1242
-    </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=309524" target="_top">Bug 309524</a>
1243
-and <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=380556" target="_top">Bug
1244
-380556</a> - nsIContentPolicy::shouldProcess is not called.
1245
-     <p>
1246
-
1247
-This is a call that would be useful to develop a better workaround for the
1248
-allowPlugins issue above. If the content policy were called before a URL was
1249
-handed over to a plugin or helper app, it would make the workaround for the
1250
-above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
1251
-the others though, but it might be nice to have this API as a backup.
1252
-
1253
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">Bug 401296 - docShell.allowPlugins
1254
-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>?)
1255
-     <p>
1256
-
1257
-Similar to the javascript plugin disabling attribute, the plugin disabling
1258
-attribute is also not perfect — it is ignored for direct links to plugin
1259
-handled content, as well as meta-refreshes to plugin handled content.  This
1260
-requires Torbutton to listen to a number of different http events to intercept
1261
-plugin-related mime type URLs and cancel their requests. Again, since plugins
1262
-are quite horrible about obeying proxy settings, loading a plugin pretty much
1263
-ensures a way to break the <a class="link" href="#isolation">Network Isolation</a>
1264
-requirement and reveal a user's original IP address. Torbutton's code to
1265
-perform this workaround has been subverted at least once already by Kyle
1266
-Williams.
1267
-
1268
-     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=419598" target="_top">Bug 419598 - 'var
1269
-Date' is deletable</a><p>
1270
-
1271
-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
1272
-Javascript spec</a>, it seems like it should be possible to do something
1273
-like the following to prevent the Date object from being unmasked:
1274
-</p><pre class="screen">
1275
-with(window) {
1276
-    var Date = fakeDate;
1277
-    var otherVariable = 42;
1278
-}
1279
-
1280
-delete window.Date; // Should fail. Instead succeeds, revealing original Date.
1281
-delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
1282
-</pre><p>
1283
-
1284
-From the ECMA-262 spec:
1285
-
1286
-</p><div class="blockquote"><blockquote class="blockquote">
1287
-If the variable statement occurs inside a FunctionDeclaration, the variables
1288
-are defined with function-local scope in that function, as described in
1289
-s10.1.3. Otherwise, they are defined with global scope (that is, they are
1290
-created as members of the global object, as described in 10.1.3) using
1291
-property attributes { DontDelete }. Variables are created when the execution
1292
-scope is entered. A Block does not define a new execution scope. Only Program
1293
-and FunctionDeclaration produce a new scope. Variables are initialized to
1294
-undefined when created. A variable with an Initialiser is assigned the value
1295
-of its AssignmentExpression when the VariableStatement is executed, not when
1296
-the variable is created.
1297
-</blockquote></div><p>
1298
-
1299
-In fact, this is exactly how the with statement with a variable declaration
1300
-behaves <span class="emphasis"><em>for all other variables other than ones that shadow system
1301
-variables</em></span>. Some variables (such as
1302
-<span class="command"><strong>window.screen</strong></span>, and <span class="command"><strong>window.history</strong></span>) can't
1303
-even be shadowed in this way, and give an error about lacking a setter. If
1304
-such shadowing were possible, it would greatly simplify the Javascript hooking
1305
-code, which currently relies on undocumented semantics of
1306
-<span class="command"><strong>__proto__</strong></span> to copy the original values in the event of a
1307
-delete. This <span class="command"><strong>__proto__</strong></span> hack unfortunately does not work for
1308
-the Date object though.
1309
-
1310
-     </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>
1311
-
1312
-The purpose of this section is to cover all the known ways that Tor browser
1313
-security can be subverted from a penetration testing perspective. The hope
1314
-is that it will be useful both for creating a "Tor Safety Check"
1315
-page, and for developing novel tests and actively attacking Torbutton with the
1316
-goal of finding vulnerabilities in either it or the Mozilla components,
1317
-interfaces and settings upon which it relies.
1318
-
1319
-  </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>
1320
-
1321
-Torbutton is a complicated piece of software. During development, changes to
1322
-one component can affect a whole slough of unrelated features.  A number of
1323
-aggregated test suites exist that can be used to test for regressions in
1324
-Torbutton and to help aid in the development of Torbutton-like addons and
1325
-other privacy modifications of other browsers. Some of these test suites exist
1326
-as a single automated page, while others are a series of pages you must visit
1327
-individually. They are provided here for reference and future regression
1328
-testing, and also in the hope that some brave soul will one day decide to
1329
-combine them into a comprehensive automated test suite.
1330
-
1331
-     </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>
1332
-
1333
-Decloak.net is the canonical source of plugin and external-application based
1334
-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
1335
-use to test their anonymity systems.
1336
-
1337
-       </p></li><li class="listitem"><a class="ulink" href="http://deanonymizer.com/" target="_top">Deanonymizer.com</a><p>
1338
-
1339
-Deanonymizer.com is another automated test suite that tests for proxy bypass
1340
-and other information disclosure vulnerabilities. It is maintained by Kyle
1341
-Williams, the author of <a class="ulink" href="http://www.janusvm.com/" target="_top">JanusVM</a>
1342
-and <a class="ulink" href="http://www.januspa.com/" target="_top">JanusPA</a>.
1343
-
1344
-       </p></li><li class="listitem"><a class="ulink" href="https://www.jondos.de/en/anontest" target="_top">JonDos
1345
-AnonTest</a><p>
1346
-
1347
-The <a class="ulink" href="https://www.jondos.de" target="_top">JonDos people</a> also provide an
1348
-anonymity tester. It is more focused on HTTP headers than plugin bypass, and
1349
-points out a couple of headers Torbutton could do a better job with
1350
-obfuscating.
1351
-
1352
-       </p></li><li class="listitem"><a class="ulink" href="http://browserspy.dk" target="_top">Browserspy.dk</a><p>
1353
-
1354
-Browserspy.dk provides a tremendous collection of browser fingerprinting and
1355
-general privacy tests. Unfortunately they are only available one page at a
1356
-time, and there is not really solid feedback on good vs bad behavior in
1357
-the test results.
1358
-
1359
-       </p></li><li class="listitem"><a class="ulink" href="http://analyze.privacy.net/" target="_top">Privacy
1360
-Analyzer</a><p>
1361
-
1362
-The Privacy Analyzer provides a dump of all sorts of browser attributes and
1363
-settings that it detects, including some information on your origin IP
1364
-address. Its page layout and lack of good vs bad test result feedback makes it
1365
-not as useful as a user-facing testing tool, but it does provide some
1366
-interesting checks in a single page.
1367
-
1368
-       </p></li><li class="listitem"><a class="ulink" href="http://ha.ckers.org/mr-t/" target="_top">Mr. T</a><p>
1369
-
1370
-Mr. T is a collection of browser fingerprinting and deanonymization exploits
1371
-discovered by the <a class="ulink" href="http://ha.ckers.org" target="_top">ha.ckers.org</a> crew
1372
-and others. It is also not as user friendly as some of the above tests, but it
1373
-is a useful collection.
1374
-
1375
-       </p></li><li class="listitem">Gregory Fleischer's <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">Torbutton</a> and
1376
-<a class="ulink" href="http://pseudo-flaw.net/content/defcon/dc-17-demos/d.html" target="_top">Defcon
1377
-17</a> Test Cases
1378
-       <p>
1379
-
1380
-Gregory Fleischer has been hacking and testing Firefox and Torbutton privacy
1381
-issues for the past 2 years. He has an excellent collection of all his test
1382
-cases that can be used for regression testing. In his Defcon work, he
1383
-demonstrates ways to infer Firefox version based on arcane browser properties.
1384
-We are still trying to determine the best way to address some of those test
1385
-cases.
1386
-
1387
-       </p></li><li class="listitem"><a class="ulink" href="https://torcheck.xenobite.eu/index.php" target="_top">Xenobite's
1388
-TorCheck Page</a><p>
1389
-
1390
-This page checks to ensure you are using a valid Tor exit node and checks for
1391
-some basic browser properties related to privacy. It is not very fine-grained
1392
-or complete, but it is automated and could be turned into something useful
1393
-with a bit of work.
1394
-
1395
-       </p></li></ol></div><p>
1396
-    </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2936532"></a>7.2. Multi-state testing</h3></div></div></div><p>
1397
-
1398
-The tests in this section are geared towards a page that would instruct the
1399
-user to toggle their Tor state after the fetch and perform some operations:
1400
-mouseovers, stray clicks, and potentially reloads.
1401
-
1402
-   </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2936545"></a>Cookies and Cache Correlation</h4></div></div></div><p>
1403
-The most obvious test is to set a cookie, ask the user to toggle tor, and then
1404
-have them reload the page. The cookie should no longer be set if they are
1405
-using the default Torbutton settings. In addition, it is possible to leverage
1406
-the cache to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safecachetest.html" target="_top">store unique
1407
-identifiers</a>. The default settings of Torbutton should also protect
1408
-against these from persisting across Tor Toggle.
1409
-
1410
-    </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2936567"></a>Javascript timers and event handlers</h4></div></div></div><p>
1411
-
1412
-Javascript can set timers and register event handlers in the hopes of fetching
1413
-URLs after the user has toggled Torbutton. 
1414
-    </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2936580"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
1415
-
1416
-Even if Javascript is disabled, CSS is still able to 
1417
-<a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like
1418
-windows</a>
1419
-via the 'onmouseover' CSS attribute, which can cause arbitrary browser
1420
-activity as soon as the mouse enters into the content window. It is also
1421
-possible for meta-refresh tags to set timers long enough to make it likely
1422
-that the user has toggled Tor before fetching content.
1423
-
1424
-    </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>
1425
-
1426
-The idea behind active testing is to discover vulnerabilities in Torbutton to
1427
-bypass proxy settings, run script in an opposite Tor state, store unique
1428
-identifiers, leak location information, or otherwise violate <a class="link" href="#requirements" title="1.2. Torbutton Requirements">its requirements</a>. Torbutton has ventured out
1429
-into a strange and new security landscape. It depends on Firefox mechanisms
1430
-that haven't necessarily been audited for security, certainly not for the
1431
-threat model that Torbutton seeks to address. As such, it and the interfaces
1432
-it depends upon still need a 'trial by fire' typical of new technologies. This
1433
-section of the document was written with the intention of making that period
1434
-as fast as possible. Please help us get through this period by considering
1435
-these attacks, playing with them, and reporting what you find (and potentially
1436
-submitting the test cases back to be run in the standard batch of Torbutton
1437
-tests.
1438
-
1439
-   </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2936635"></a>Some suggested vectors to investigate</h4></div></div></div><p>
1440
-    </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
1441
-be verified to actually be ineffective after Tor has been toggled.</li><li class="listitem">Other ways to cause Javascript to be executed after
1442
-<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
1443
-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
1444
-crazy combinations of iframes, nested iframes, iframes in frames, frames in
1445
-iframes, and popups being loaded and
1446
-reloaded in rapid succession, and/or from one another. Think race conditions and deep, 
1447
-parallel nesting, involving iframes from both <a class="ulink" href="http://en.wikipedia.org/wiki/Same_origin_policy" target="_top">same-origin and
1448
-non-same-origin</a> domains.</li><li class="listitem">In addition, there may be alternate ways and other
1449
-methods to query the timezone, or otherwise use some of the Date object's
1450
-methods in combination to deduce the timezone offset. Of course, the author
1451
-tried his best to cover all the methods he could foresee, but it's always good
1452
-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>
1453
-mentioned above to cause it to allow certain types of page fetches? For
1454
-example, it was recently discovered that favicons are not fetched by the
1455
-content, but the chrome itself, hence the content policy did not look up the
1456
-correct window to determine the current Tor tag for the favicon fetch. Are
1457
-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>
1458
-caught us off guard. 
1459
-It was
1460
-also discovered by <a class="ulink" href="http://pseudo-flaw.net" target="_top">Gregory
1461
-Fleischer</a> that <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">content window access to
1462
-chrome</a> can be used to build <a class="link" href="#fingerprinting">unique
1463
-identifiers</a>. 
1464
-Are there any other
1465
-arcane or experimental ways that Firefox provides to create and store unique
1466
-identifiers? Or perhaps unique identifiers can be queried or derived from
1467
-properties of the machine/browser that Javascript has access to? How unique
1468
-can these identifiers be?
1469
-     </li><li class="listitem">Is it possible to get the browser to write some history to disk
1470
-(aside from swap) that can be retrieved later? By default, Torbutton should
1471
-write no history, cookie, or other browsing activity information to the
1472
-harddisk.</li><li class="listitem">Do popup windows make it easier to break any of the above
1473
-behavior? Are javascript events still canceled in popups? What about recursive
1474
-popups from Javascript, data, and other funky URL types? What about CSS
1475
-popups? Are they still blocked after Tor is toggled?</li><li class="listitem">Chrome-escalation attacks. The interaction between the
1476
-Torbutton chrome Javascript and the client content window javascript is pretty
1477
-well-defined and carefully constructed, but perhaps there is a way to smuggle
1478
-javascript back in a return value, or otherwise inject network-loaded
1479
-javascript into the chrome (and thus gain complete control of the browser).
1480
-</li></ul></div><p>
1481
-
1482
-    </p></div></div></div></div></body></html>
1483 0