add torbutton design dir from git.
Andrew Lewman

Andrew Lewman commited on 2009-12-31 03:42:43
Zeige 7 geänderte Dateien mit 4390 Einfügungen und 0 Löschungen.

... ...
@@ -0,0 +1,120 @@
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
+
... ...
@@ -0,0 +1,195 @@
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
... ...
@@ -0,0 +1 @@
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 
... ...
@@ -0,0 +1,2640 @@
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>Dec 15 2009</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.4.
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.4.
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
+
1278
+<title>Disable Search Suggestions during Tor (recommended)</title>
1279
+
1280
+  <para>Option: <command>extensions.torbutton.no_search</command></para>
1281
+
1282
+<para>
1283
+This setting causes Torbutton to disable <ulink
1284
+url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1285
+during Tor usage.
1286
+This governs if you get Google search suggestions during Tor
1287
+usage. Your Google cookie is transmitted with google search suggestions, hence
1288
+this is recommended to be disabled.
1289
+
1290
+</para>
1291
+<para>
1292
+While this setting doesn't satisfy any Torbutton requirements, the fact that
1293
+cookies are transmitted for partially typed queries does not seem desirable
1294
+for Tor usage.
1295
+</para>
1296
+</sect2>
1297
+<sect2>
1298
+<title>Disable livemarks updates during Tor usage (recommended)</title>
1299
+  <para>Option:
1300
+   <simplelist>
1301
+   <member><command>extensions.torbutton.disable_livemarks</command></member>
1302
+   </simplelist>
1303
+  </para>
1304
+
1305
+<para>
1306
+This option causes Torbutton to prevent Firefox from loading <ulink
1307
+url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
1308
+Tor usage. Because people often have very personalized Livemarks (such as RSS
1309
+feeds of Wikipedia articles they maintain, etc). This is accomplished both by
1310
+<link linkend="livemarks">wrapping the livemark-service component</link> and
1311
+by calling stopUpdateLivemarks() on the <ulink
1312
+url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">Livemark
1313
+service</ulink> when Tor is enabled.
1314
+
1315
+</para>
1316
+
1317
+<para>
1318
+This helps satisfy the <link linkend="isolation">Network
1319
+Isolation</link> and <link linkend="setpreservation">Anonymity Set
1320
+Preservation</link> requirements.
1321
+</para>
1322
+
1323
+</sect2>
1324
+<sect2>
1325
+<title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1326
+  <para>Options:
1327
+   <simplelist>
1328
+   <member><command>extensions.torbutton.block_tor_file_net</command></member>
1329
+   <member><command>extensions.torbutton.block_nontor_file_net</command></member>
1330
+   </simplelist>
1331
+  </para>
1332
+
1333
+<para>
1334
+
1335
+These settings prevent file urls from performing network operations during the
1336
+respective Tor states. Firefox 2's implementation of same origin policy allows
1337
+file urls to read and <ulink
1338
+url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
1339
+arbitrary files from the local filesystem</ulink> to arbitrary websites. To
1340
+make matters worse, the 'Content-Disposition' header can be injected
1341
+arbitrarily by exit nodes to trick users into running arbitrary html files in
1342
+the local context. These preferences cause the <link
1343
+linkend="contentpolicy">content policy</link> to block access to any network
1344
+resources from File urls during the appropriate Tor state.
1345
+
1346
+</para>
1347
+<para>
1348
+
1349
+This preference helps to ensure Tor's <link linkend="isolation">Network
1350
+Isolation</link> requirement, by preventing file urls from executing network
1351
+operations in opposite Tor states. Also, allowing pages to submit arbitrary
1352
+files to arbitrary sites just generally seems like a bad idea.
1353
+
1354
+</para>
1355
+</sect2>
1356
+<sect2>
1357
+
1358
+<title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1359
+
1360
+  <para>Options:
1361
+   <simplelist>
1362
+   <member><command>extensions.torbutton.close_nontor</command></member>
1363
+   <member><command>extensions.torbutton.close_tor</command></member>
1364
+   </simplelist>
1365
+  </para>
1366
+
1367
+<para>
1368
+
1369
+These settings cause Torbutton to enumerate through all windows and close all
1370
+tabs in each window for the appropriate Tor state. This code can be found in
1371
+<function>torbutton_update_status()</function>.  The main reason these settings
1372
+exist is as a backup mechanism in the event of any Javascript or content policy
1373
+leaks due to <ulink
1374
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1375
+409737</ulink>.  Torbutton currently tries to block all Javascript network
1376
+activity via the content policy, but until that bug is fixed, there is some
1377
+risk that there are alternate ways to bypass the policy. This option is
1378
+available as an extra assurance of <link linkend="isolation">Network
1379
+Isolation</link> for those who would like to be sure that when Tor is toggled
1380
+all page activity has ceased. It also serves as a potential future workaround
1381
+in the event a content policy failure is discovered, and provides an additional
1382
+level of protection for the <link linkend="disk">Disk Avoidance</link>
1383
+protection so that browser state is not sitting around waiting to be swapped
1384
+out longer than necessary.
1385
+
1386
+</para>
1387
+<para>
1388
+While this setting doesn't satisfy any Torbutton requirements, the fact that
1389
+cookies are transmitted for partially typed queries does not seem desirable
1390
+for Tor usage.
1391
+</para>
1392
+</sect2>
1393
+
1394
+<sect2>
1395
+<title>Isolate Access to History navigation to Tor state (crucial)</title>
1396
+  <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1397
+  <para>
1398
+This setting determines if Torbutton installs an <ulink
1399
+url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener">nsISHistoryListener</ulink>
1400
+attached to the <ulink
1401
+url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">sessionHistory</ulink> of 
1402
+of each browser's <ulink
1403
+url="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation">webNavigatator</ulink>.
1404
+The nsIShistoryListener is instantiated with a reference to the containing
1405
+browser window and blocks the back, forward, and reload buttons on the browser
1406
+navigation bar when Tor is in an opposite state than the one to load the
1407
+current tab. In addition, Tor clears the session history during a new document
1408
+load if this setting is enabled. 
1409
+
1410
+  </para>
1411
+  <para>
1412
+
1413
+This is marked as a crucial setting in part
1414
+because Javascript access to the history object is indistinguishable from 
1415
+user clicks, and because
1416
+<ulink
1417
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1418
+409737</ulink> allows javascript to execute in opposite Tor states, javascript
1419
+can issue reloads after Tor toggle to reveal your original IP. Even without
1420
+this bug, however, Javascript is still able to access previous pages in your
1421
+session history that may have been loaded under a different Tor state, to
1422
+attempt to correlate your activity.
1423
+
1424
+   </para>
1425
+   <para>
1426
+
1427
+This setting helps to fulfill Torbutton's <link linkend="state">State
1428
+Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
1429
+requirements.
1430
+
1431
+   </para>
1432
+</sect2>
1433
+
1434
+
1435
+<sect2>
1436
+<title>History Access Settings</title>
1437
+
1438
+  <para>Options:
1439
+  <simplelist>
1440
+   <member><command>extensions.torbutton.block_thread</command></member>
1441
+   <member><command>extensions.torbutton.block_nthread</command></member>
1442
+   <member><command>extensions.torbutton.block_thwrite</command></member>
1443
+   <member><command>extensions.torbutton.block_nthwrite</command></member>
1444
+  </simplelist>
1445
+  </para>
1446
+
1447
+<para>These four settings govern the behavior of the <ulink
1448
+url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink>
1449
+history blocker component mentioned above. By hooking the browser's view of
1450
+the history itself via the <ulink
1451
+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>
1452
+and <ulink
1453
+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>
1454
+components, this mechanism defeats all document-based <ulink
1455
+url="http://whattheinternetknowsaboutyou.com/">history disclosure
1456
+attacks</ulink>, including <ulink
1457
+url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
1458
+
1459
+The component also hooks functions involved in writing history to disk via
1460
+both the <ulink
1461
+url="http://developer.mozilla.org/en/docs/Places_migration_guide#History">Places
1462
+Database</ulink> and the older Firefox 2 mechanisms.
1463
+
1464
+</para>
1465
+
1466
+<para>
1467
+This setting helps to satisfy the <link
1468
+linkend="state">State Separation</link> and <link
1469
+linkend="disk">Disk Avoidance</link> requirements.
1470
+</para>
1471
+
1472
+</sect2>
1473
+<sect2>
1474
+
1475
+<title>Clear History During Tor Toggle (optional)</title>
1476
+
1477
+<para>Option: <command>extensions.torbutton.clear_history</command></para>
1478
+
1479
+<para>This setting governs if Torbutton calls
1480
+<ulink
1481
+url="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29">nsIBrowserHistory.removeAllPages</ulink>
1482
+and <ulink
1483
+url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">nsISHistory.PurgeHistory</ulink>
1484
+for each tab on Tor toggle.</para>
1485
+<para>
1486
+This setting is an optional way to help satisfy the <link
1487
+linkend="state">State Separation</link> requirement.
1488
+</para>
1489
+
1490
+</sect2>
1491
+<sect2>
1492
+
1493
+<title>Block Password+Form saving during Tor/Non-Tor</title>
1494
+
1495
+<para>Options:
1496
+  <simplelist>
1497
+  <member><command>extensions.torbutton.block_tforms</command></member>
1498
+  <member><command>extensions.torbutton.block_ntforms</command></member>
1499
+  </simplelist>
1500</