tor-webwml.git

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>Apr 10 2011</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.3.2.

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) 

223)      <listitem id="fingerprinting"><command>Fingerprint users based on browser
224) attributes</command>
225) <para>
226) 
227) There is an absurd amount of information available to websites via attributes
228) of the browser. This information can be used to reduce anonymity set, or even
229) <ulink url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">uniquely
230) fingerprint individual users</ulink>. </para>
231) <para>
232) For illustration, let's perform a
233) back-of-the-envelope calculation on the number of anonymity sets for just the
234) resolution information available in the <ulink
235) url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
236) <ulink
237) url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>

238) objects.
239) 
240) 
241) 
242) Browser window resolution information provides something like

243) (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
244) information contributes about another factor of 5 (for about 5 resolutions in
245) typical use). In addition, the dimensions and position of the desktop taskbar
246) are available, which can reveal hints on OS information. This boosts the count
247) by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
248) and Gnome, and None). Subtracting the browser content window
249) size from the browser outer window size provide yet more information.
250) Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give

251) 2<superscript>3</superscript>=8). Interface effects such as title bar font size

252) and window manager settings gives a factor of about 9 (say 3 common font sizes

253) for the title bar and 3 common sizes for browser GUI element fonts).

254) Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
255) 2<superscript>29</superscript>, or a 29 bit identifier based on resolution
256) information alone. </para>
257) 
258) <para>
259) 

260) Of course, this space is non-uniform in user density and prone to incremental
261) changes. The <ulink
262) url="https://wiki.mozilla.org/Fingerprinting#Data">Panopticlick study
263) done</ulink> by the EFF attempts to measure the actual entropy - the number of
264) identifying bits of information encoded in browser properties.  Their result
265) data is definitely useful, and the metric is probably the appropriate one for
266) determining how identifying a particular browser property is. However, some
267) quirks of their study means that they do not extract as much information as
268) they could from display information: they only use desktop resolution (which
269) Torbutton reports as the window resolution) and do not attempt to infer the
270) size of toolbars.

271) 
272) </para>

273) <!--
274) FIXME: This is no longer true. Only certain addons are now discoverable, and
275) only if they want to be:
276) http://webdevwonders.com/detecting-firefox-add-ons/
277) https://developer.mozilla.org/en/Updating_web_applications_for_Firefox_3#section_7
278) 

279) <para>
280) 
281) To add insult to injury, <ulink
282) url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
283) attacks</ulink> mean that each and every extension on <ulink
284) url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
285) to that 2<superscript>29</superscript>. With hundreds of popular extensions
286) and thousands of extensions total, it is easy to see that this sort of
287) information is an impressively powerful identifier if used properly by a
288) competent and determined adversary such as an ad network.  Again, a
289) nearest-neighbor bit vector space approach here would also gracefully handle
290) incremental changes to installed extensions.
291) 
292) </para>

293) -->

294)      </listitem>
295)      <listitem><command>Remotely or locally exploit browser and/or
296) OS</command>
297)      <para>
298) Last, but definitely not least, the adversary can exploit either general 
299) browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
300) install malware and surveillance software. An adversary with physical access
301) can perform similar actions. Regrettably, this last attack capability is
302) outside of Torbutton's ability to defend against, but it is worth mentioning
303) for completeness.
304)      </para>
305)      </listitem>
306)     </orderedlist>
307)    </sect3>
308) 
309)   </sect2>
310) 
311)   <sect2 id="requirements">
312)    <title>Torbutton Requirements</title>
313) <note>
314) 
315) Since many settings satisfy multiple requirements, this design document is
316) organized primarily by Torbutton components and settings. However, if you are
317) the type that would rather read the document from the requirements
318) perspective, it is in fact possible to search for each of the following
319) requirement phrases in the text to find the relevant features that help meet
320) that requirement.
321) 
322) </note>
323)    <para>
324) 
325) From the above Adversary Model, a number of requirements become clear. 
326) 
327)    </para>
328) 
329) <orderedlist> 
330) <!-- These aren't really commands.. But it's the closest I could find in an
331) acceptable style.. Don't really want to make my own stylesheet -->
332)  <listitem id="proxy"><command>Proxy Obedience</command> 
333)  <para>The browser
334) MUST NOT bypass Tor proxy settings for any content.</para></listitem>
335)  <listitem id="state"><command>State Separation</command>
336)  <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
337)  one Tor state MUST NOT be accessible via the network in
338)  another Tor state.</para></listitem>

339)  <listitem id="isolation"><command>Network Isolation</command>
340)  <para>Pages MUST NOT perform any network activity in a Tor state different

341)  from the state they were originally loaded in.</para>
342)  <para>Note that this requirement is
343) being de-emphasized due to the coming shift to supporting only the Tor Browser
344) Bundles, which do not support a Toggle operation.</para></listitem>

345)  <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
346) the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
347) users whose network fingerprint does not obviously betray the fact that they
348) are using Tor. This should extend to the browser as well - Torbutton MUST NOT 

349) reveal its presence while Tor is disabled.
350) </para>
351)  <para>Note that this requirement is
352) being de-emphasized due to the coming shift to supporting only the Tor Browser
353) Bundles, which do not support a Toggle operation.</para>
354) </listitem>

355)  <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
356)  in memory beyond the duration of one Tor toggle.</para></listitem>
357)  <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
358)  timezone or locale via Tor.</para></listitem>
359)  <listitem id="setpreservation"><command>Anonymity Set

360) Preservation</command><para>The browser SHOULD NOT leak any other anonymity
361) set reducing or fingerprinting information

362)  (such as user agent, extension presence, and resolution information)
363) automatically via Tor. The assessment of the attacks above should make it clear
364) that anonymity set reduction is a very powerful method of tracking and
365) eventually identifying anonymous users.
366) </para></listitem>
367)  <listitem id="updates"><command>Update Safety</command><para>The browser
368) SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
369)  <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
370)  enable the user to switch between a number of different proxies. It MUST
371)  provide full Tor protection in the event a third-party proxy switcher has
372)  enabled the Tor proxy settings.</para></listitem>
373) </orderedlist>
374)   </sect2>
375)   <sect2 id="layout">
376)    <title>Extension Layout</title>
377) 
378) <para>Firefox extensions consist of two main categories of code: 'Components' and
379) 'Chrome'. Components are a fancy name for classes that implement a given
380) interface or interfaces. In Firefox, components <ulink
381) url="https://developer.mozilla.org/en/XPCOM">can be
382) written</ulink> in C++,
383) Javascript, or a mixture of both. Components have two identifiers: their
384) '<ulink
385) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
386) ID</ulink>' (a human readable path-like string), and their '<ulink
387) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
388) ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
389) 'Interface ID'. It is possible to 'hook' system components - to reimplement
390) their interface members with your own wrappers - but only if the rest of the
391) browser refers to the component by its Contract ID. If the browser refers to
392) the component by Class ID, it bypasses your hooks in that use case.
393) Technically, it may be possible to hook Class IDs by unregistering the
394) original component, and then re-registering your own, but this relies on
395) obsolete and deprecated interfaces and has proved to be less than
396) stable.</para>
397) 
398) <para>'Chrome' is a combination of XML and Javascript used to describe a window.
399) Extensions are allowed to create 'overlays' that are 'bound' to existing XML
400) window definitions, or they can create their own windows. The DTD for this XML
401) is called <ulink
402) url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
403)   </sect2>
404) </sect1>

405) <sect1 id="components">

406)   <title>Components</title>
407)   <para>
408) 
409) Torbutton installs components for two purposes: hooking existing components to
410) reimplement their interfaces; and creating new components that provide
411) services to other pieces of the extension.
412) 
413)   </para>
414) 

415)   <sect2 id="hookedxpcom">

416)    <title>Hooked Components</title>
417) 
418) <para>Torbutton makes extensive use of Contract ID hooking, and implements some
419) of its own standalone components as well.  Let's discuss the hooked components
420) first.</para>
421) 
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://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/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 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>
444) - <ulink

445)   url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink></title>

446) 
447) <para>This component was contributed by <ulink
448) url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
449) CSS and Javascript-based methods of history disclosure. The global-history
450) component is what is used by Firefox to determine if a link was visited or not
451) (to apply the appropriate style to the link). By hooking the <ulink
452) url="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29">isVisited</ulink>
453) and <ulink 
454) url="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29">addURI</ulink>
455) methods, Torbutton is able to selectively prevent history items from being
456) added or being displayed as visited, depending on the Tor state and the user's
457) preferences.
458) </para>
459) <para>
460) This component helps satisfy the <link linkend="state">State Separation</link>

461) and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton. It
462) is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
463) of the <ulink
464) url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">built-in
465) history protections</ulink>.

466) </para>
467) </sect3>
468) <sect3 id="livemarks">
469) <title><ulink
470) 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>
471) - <ulink

472)   url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>

473) <para>
474) 
475) The <ulink
476) url="http://www.mozilla.com/en-US/firefox/livebookmarks.html">livemark</ulink> service
477) is started by a timer that runs 5 seconds after Firefox
478) startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
479) disable it. We must wrap the component to prevent this start() call from
480) firing in the event the browser starts in Tor mode.
481) 
482) </para>
483) <para>
484) This component helps satisfy the <link linkend="isolation">Network
485) Isolation</link> and <link linkend="setpreservation">Anonymity Set
486) Preservation</link> requirements.
487) </para>
488) </sect3>
489) </sect2>
490) <sect2>
491) <title>New Components</title>
492) 
493) <para>Torbutton creates four new components that are used throughout the
494) extension. These components do not hook any interfaces, nor are they used
495) anywhere besides Torbutton itself.</para>
496) 

497) <sect3 id="cookiejar">

498) <title><ulink

499) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2

500) - components/cookie-jar-selector.js</ulink></title>
501) 
502) <para>The cookie jar selector (also based on code from <ulink
503) url="http://www.collinjackson.com/">Collin
504) Jackson</ulink>) is used by the Torbutton chrome to switch between

505) Tor and Non-Tor cookies. It stores an XML representation of the current
506) cookie state in memory and/or on disk. When Tor is toggled, it syncs the
507) current cookies to this XML store, and then loads the cookies for the other
508) state from the XML store.
509) </para>

510) 
511) <para>
512) This component helps to address the <link linkend="state">State
513) Isolation</link> requirement of Torbutton.
514) </para>
515) 
516) </sect3>
517) <sect3>
518) <title><ulink

519) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1

520) - components/torbutton-logger.js</ulink></title>
521) 
522) <para>The torbutton logger component allows on-the-fly redirection of torbutton
523) logging messages to either Firefox stderr
524) (<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
525) (<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
526) available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
527) change the loglevel on the fly by changing
528) <command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
529) </para>
530) </sect3>
531) <sect3 id="windowmapper">
532) 
533) <title><ulink

534) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js">@torproject.org/content-window-mapper;1

535) - components/window-mapper.js</ulink></title>
536) 
537) <para>Torbutton tags Firefox <ulink
538) url="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes">tabs</ulink> with a special variable that indicates the Tor
539) state the tab was most recently used under to fetch a page. The problem is
540) that for many Firefox events, it is not possible to determine the tab that is
541) actually receiving the event. The Torbutton window mapper allows the Torbutton
542) chrome and other components to look up a <ulink
543) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
544) tab</ulink> for a given <ulink
545) url="https://developer.mozilla.org/en/nsIDOMWindow">HTML content
546) window</ulink>. It does this by traversing all windows and all browsers, until it
547) finds the browser with the requested <ulink
548) url="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow">contentWindow</ulink> element. Since the content policy
549) and page loading in general can generate hundreds of these lookups, this
550) result is cached inside the component.
551) </para>
552) </sect3>

553) <sect3 id="crashobserver">
554)  <title><ulink
555) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">@torproject.org/crash-observer;1</ulink></title>
556)   <para>
557) 
558) This component detects when Firefox crashes by altering Firefox prefs during
559) runtime and checking for the same values at startup. It <ulink
560) url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()">synchronizes
561) the preference service</ulink> to ensure the altered prefs are written to disk
562) immediately.
563) 
564)   </para>
565) </sect3>
566) <sect3 id="tbsessionstore">
567)  <title><ulink
568) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js">@torproject.org/torbutton-ss-blocker;1</ulink></title>
569)   <para>
570) 
571) This component subscribes to the Firefox <ulink
572) url="https://developer.mozilla.org/en/Observer_Notifications#Session_Store">sessionstore-state-write</ulink>
573) observer event to filter out URLs from tabs loaded during Tor, to prevent them
574) from being written to disk. To do this, it checks the
575) <command>__tb_tor_fetched</command> tag of tab objects before writing them out. If
576) the tag is from a blocked Tor state, the tab is not written to disk.  This is
577) a rather expensive operation that involves potentially very large JSON
578) evaluations and object tree traversals, but it preferable to replacing the
579) Firefox session store with our own implementation, which is what was done in
580) years past.
581) 
582)   </para>
583) </sect3>
584) 
585) <sect3 id="refspoofer">
586)  <title><ulink
587) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js">@torproject.org/torRefSpoofer;1</ulink></title>
588)  <para>

589) This component handles optional referer spoofing for Torbutton. It implements a

590) form of "smart" referer spoofing using <ulink
591) url="https://developer.mozilla.org/en/Setting_HTTP_request_headers">http-on-modify-request</ulink>

592) to modify the Referer header. The code sends the default browser referer

593) header only if the destination domain is a suffix of the source, or if the
594) source is a suffix of the destination. Otherwise, it sends no referer. This
595) strange suffix logic is used as a heuristic: some rare sites on the web block
596) requests without proper referer headers, and this logic is an attempt to cater
597) to them. Unfortunately, it may not be enough. For example, google.fr will not
598) send a referer to google.com using this logic. Hence, it is off by default.
599)  </para>
600) </sect3>
601) 
602) <!-- FIXME: tor-protocol, tors-protocol need documenting, but
603) they are disabled by default for now, so no reason to add the
604) clutter+confusion. -->
605) 

606) <sect3 id="contentpolicy">
607) <title><ulink

608) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1

609) - components/cssblocker.js</ulink></title>
610) 
611) <para>This is a key component to Torbutton's security measures. When Tor is
612) toggled, Javascript is disabled, and pages are instructed to stop loading.
613) However, CSS is still able to perform network operations by loading styles for
614) onmouseover events and other operations. In addition, favicons can still be
615) loaded by the browser. The cssblocker component prevents this by implementing
616) and registering an <ulink
617) url="https://developer.mozilla.org/en/nsIContentPolicy">nsIContentPolicy</ulink>.
618) When an nsIContentPolicy is registered, Firefox checks every attempted network
619) request against its <ulink
620) url="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()">shouldLoad</ulink>
621) member function to determine if the load should proceed. In Torbutton's case,
622) the content policy looks up the appropriate browser tab using the <link
623) linkend="windowmapper">window mapper</link>,
624) and checks that tab's load tag against the current Tor state. If the tab was
625) loaded in a different state than the current state, the fetch is denied.
626) Otherwise, it is allowed.</para> This helps to achieve the <link
627) linkend="isolation">Network
628) Isolation</link> requirements of Torbutton.
629) 
630) <para>In addition, the content policy also blocks website javascript from

631) <ulink
632) url="http://webdevwonders.com/detecting-firefox-add-ons/">querying for

633) versions and existence of extension chrome</ulink> while Tor is enabled, and
634) also masks the presence of Torbutton to website javascript while Tor is
635) disabled. </para>
636) 
637) <para>
638) 
639) Finally, some of the work that logically belongs to the content policy is
640) instead handled by the <command>torbutton_http_observer</command> and
641) <command>torbutton_weblistener</command> in <ulink

642) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of

643) Firefox 3 favicon loads, popups, and full page plugins, which for whatever
644) reason are not passed to the Firefox content policy itself (see Firefox Bugs 
645) <ulink
646) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and 
647) <ulink
648) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
649) 
650) </para>
651) 
652) <!-- 
653) FIXME: Hrmm, the content policy doesn't really lend itself well to display 
654) this way.. People looking for this much detail should consult the source.
655) 
656) <para>
657)     <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
658)     <tgroup cols='5' align='left' colsep='1' rowsep='1'>
659)        <tbody>
660)        <row>
661)          <entry></entry>
662)          <entry>chrome/resource</entry>
663)          <entry>a3</entry>
664)          <entry>a4</entry>
665)          <entry>a5</entry>
666)        </row>
667)        <row>
668)          <entry>file</entry>
669)          <entry>b2</entry>
670)          <entry>b3</entry>
671)          <entry>b4</entry>
672)          <entry>b5</entry>
673)        </row>
674)        <row>
675)          <entry>c1</entry>
676)          <entry>c2</entry>
677)          <entry>c3</entry>
678)          <entry>c4</entry>
679)          <entry>c5</entry>
680)        </row>
681)        <row>
682)          <entry>d1</entry>
683)          <entry>d2</entry>
684)          <entry>d3</entry>
685)          <entry>d4</entry>
686)          <entry>d5</entry>
687)        </row>
688)        </tbody>
689)        </tgroup>
690)        </table>
691) </para>
692) -->
693) 
694) <para>
695) 
696) This helps to fulfill both the <link
697) linkend="setpreservation">Anonymity Set Preservation</link> and the <link
698) linkend="undiscoverability">Tor Undiscoverability</link> requirements of
699) Torbutton.</para>
700) 
701) </sect3>
702) </sect2>
703) </sect1>
704) <sect1>
705)  <title>Chrome</title>
706) 
707) <para>The chrome is where all the torbutton graphical elements and windows are

708) located. </para>
709) <sect2>
710)  <title>XUL Windows and Overlays</title>
711) <para>
712) Each window is described as an <ulink

713) url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
714) files attached. The scope of these Javascript files is their containing

715) window. XUL files that add new elements and script to existing Firefox windows
716) are called overlays.</para>

717) 

718) <sect3 id="browseroverlay">

719) <title>Browser Overlay - <ulink

720) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>

721) 
722) <para>The browser overlay, torbutton.xul, defines the toolbar button, the status
723) bar, and events for toggling the button. The overlay code is in <ulink

724) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.

725) It contains event handlers for preference update, shutdown, upgrade, and
726) location change events.</para>
727) 

728) </sect3>
729) <sect3>
730)  <title>Preferences Window - <ulink
731) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
732) 
733) <para>The preferences window of course lays out the Torbutton preferences, with
734) handlers located in <ulink
735) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
736) </sect3>
737) <sect3>
738)  <title>Other Windows</title>
739) 
740) <para>There are additional windows that describe popups for right clicking on
741) the status bar, the toolbutton, and the about page.</para>
742) 
743) </sect3>
744) </sect2>
745) <sect2>
746)  <title>Major Chrome Observers</title>
747)  <para>
748) In addition to the <link linkend="components">components described
749) above</link>, Torbutton also instantiates several observers in the browser
750) overlay window. These mostly grew due to scoping convenience, and many should
751) probably be relocated into their own components.
752)  </para>
753)   <orderedlist>
754)    <listitem><command>torbutton_window_pref_observer</command>
755)     <para>
756) This is an observer that listens for Torbutton state changes, for the purposes
757) of updating the Torbutton button graphic as the Tor state changes.
758)     </para>
759)    </listitem>
760) 
761)    <listitem><command>torbutton_unique_pref_observer</command>
762)     <para>
763) 
764) This is an observer that only runs in one window, called the main window. It
765) listens for changes to all of the Torbutton preferences, as well as Torbutton
766) controlled Firefox preferences. It is what carries out the toggle path when
767) the proxy settings change. When the main window is closed, the
768) torbutton_close_window event handler runs to dub a new window the "main
769) window".
770) 
771)     </para>
772)    </listitem>
773) 
774)    <listitem><command>tbHistoryListener</command>
775)     <para>
776) The tbHistoryListener exists to prevent client window Javascript from
777) interacting with window.history to forcibly navigate a user to a tab session
778) history entry from a different Tor state. It also expunges the window.history
779) entries during toggle. This listener helps Torbutton
780) satisfy the <link linkend="isolation">Network Isolation</link> requirement as
781) well as the <link linkend="state">State Separation</link> requirement.
782) 
783)     </para>
784)    </listitem>
785) 
786)    <listitem><command>torbutton_http_observer</command>
787)     <para>
788) 
789) The torbutton_http_observer performs some of the work that logically belongs
790) to the content policy. This handles blocking of
791) Firefox 3 favicon loads, which for whatever
792) reason are not passed to the Firefox content policy itself (see Firefox Bugs
793) <ulink
794) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and
795) <ulink
796) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
797) 
798)     </para>
799)     <para>
800) The observer is also responsible for redirecting users to alternate
801) search engines when Google presents them with a Captcha, as well as copying
802) Google Captcha-related cookies between international Google domains.
803)     </para>
804)    </listitem>
805) 
806)    <listitem><command>torbutton_proxyservice</command>
807)     <para>
808) The Torbutton proxy service handles redirecting Torbutton-related update
809) checks on addons.mozilla.org through Tor. This is done to help satisfy the
810) <link linkend="undiscoverability">Tor Undiscoverability</link> requirement.
811)     </para>
812)    </listitem>
813) 
814)    <listitem><command>torbutton_weblistener</command>

815) <para>The <ulink
816) url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
817) change</ulink> <ulink
818) url="https://developer.mozilla.org/en/nsIWebProgress">webprogress
819) listener</ulink>, <command>torbutton_weblistener</command> is one of the most
820) important parts of the chrome from a security standpoint. It is a <ulink
821) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
822) listener</ulink> that handles receiving an event every time a page load or
823) iframe load occurs. This class eventually calls down to
824) <function>torbutton_update_tags()</function> and
825) <function>torbutton_hookdoc()</function>, which apply the browser Tor load
826) state tags, plugin permissions, and install the Javascript hooks to hook the
827) <ulink
828) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
829) object to obfuscate browser and desktop resolution information.
830) 
831) </para>

832)    </listitem>
833) 
834)   </orderedlist>
835)  </sect2>
836) </sect1>
837) 
838) <sect1>
839)  <title>Toggle Code Path</title>
840)  <para>
841) 
842) The act of toggling is connected to <function>torbutton_toggle()</function>
843) via the <ulink
844) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
845) and <ulink
846) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul">popup.xul</ulink>
847) overlay files. Most of the work in the toggling process is present in <ulink
848) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink> 

849) 

850) </para>

851) <para>

852) 
853) Toggling is a 3 stage process: Button Click, Proxy Update, and
854) Settings Update. These stages are reflected in the prefs
855) <command>extensions.torbutton.tor_enabled</command>,
856) <command>extensions.torbutton.proxies_applied</command>, and
857) <command>extensions.torbutton.settings_applied</command>. The reason for the
858) three stage preference update is to ensure immediate enforcement of <link
859) linkend="isolation">Network Isolation</link> via the <link
860) linkend="contentpolicy">content policy</link>. Since the content window
861) javascript runs on a different thread than the chrome javascript, it is
862) important to properly convey the stages to the content policy to avoid race
863) conditions and leakage, especially with <ulink
864) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
865) 409737</ulink> unfixed. The content policy does not allow any network activity
866) whatsoever during this three stage transition.
867) 
868)  </para>
869)  <sect2>
870)   <title>Button Click</title>
871)   <para>
872) 
873) This is the first step in the toggling process. When the user clicks the
874) toggle button or the toolbar, <function>torbutton_toggle()</function> is
875) called. This function checks the current Tor status by comparing the current
876) proxy settings to the selected Tor settings, and then sets the proxy settings
877) to the opposite state, and sets the pref
878) <command>extensions.torbutton.tor_enabled</command> to reflect the new state.
879) It is this proxy pref update that gives notification via the <ulink
880) url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
881) observer</ulink>
882) <command>torbutton_unique_pref_observer</command> to perform the rest of the
883) toggle.
884) 
885)   </para>
886)  </sect2>
887)  <sect2>
888)   <title>Proxy Update</title>
889)   <para>
890) 
891) When Torbutton receives any proxy change notifications via its
892) <command>torbutton_unique_pref_observer</command>, it calls
893) <function>torbutton_set_status()</function> which checks against the Tor
894) settings to see if the Tor proxy settings match the current settings. If so,
895) it calls <function>torbutton_update_status()</function>, which determines if
896) the Tor state has actually changed, and sets
897) <command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
898) state value, and ensures that
899) <command>extensions.torbutton.tor_enabled</command> is also set to the correct
900) value. This is decoupled from the button click functionality via the pref
901) observer so that other addons (such as SwitchProxy) can switch the proxy
902) settings between multiple proxies.
903) 
904)   </para>
905)  </sect2>
906) <!-- FIXME: Describe tab tagging and other state clearing hacks? -->
907)  <sect2>
908)   <title>Settings Update</title>
909)   <para>
910) 
911) The next stage is also handled by
912) <function>torbutton_update_status()</function>. This function sets scores of
913) Firefox preferences, saving the original values to prefs under
914) <command>extensions.torbutton.saved.*</command>, and performs the <link
915) linkend="cookiejar">cookie jarring</link>, state clearing (such as window.name
916) and DOM storage), and <link linkend="preferences">preference
917) toggling</link><!--, and ssl certificate jaring work of Torbutton-->. At the
918) end of its work, it sets
919) <command>extensions.torbutton.settings_applied</command>, which signifies the
920) completion of the toggle operation to the <link
921) linkend="contentpolicy">content policy</link>.
922) 
923)   </para>
924)  </sect2>
925) <sect2 id="preferences">
926) <title>Firefox preferences touched during Toggle</title>
927) <para>
928) There are also a number of Firefox preferences set in

929) <function>torbutton_update_status()</function> that aren't governed by any
930) Torbutton setting. These are:
931) </para>
932) <orderedlist>
933) 
934) <!--
935) Not set any more.
936)  <listitem><ulink
937) url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
938) <para>
939) This pref is set in an attempt to disable the fetching of LiveBookmarks via
940) Tor. Since users can potentially collect a large amount of live bookmarks to
941) very personal sites (blogs of friends, wikipedia articles they maintain,
942) comment feeds of their own blog), it is not possible to cleanly isolate these
943) fetches and they are simply disabled during Tor usage.
944) This helps to address the <link
945) linkend="state">State Separation</link> requirement.
946) Unfortunately <ulink
947) url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
948) 436250</ulink> prevents this from
949) functioning completely correctly.
950) </para>
951)   </listitem>
952) -->
953) 
954)  <listitem><ulink
955) url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
956)  <para>
957) Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
958) reads from <command>extensions.torbutton.banned_ports</command>) to the list
959) of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
960) and the Tor control port, respectively. This is set for both Tor and Non-Tor
961) usage, and prevents websites from attempting to do http fetches from these
962) ports to see if they are open, which addresses the <link
963) linkend="undiscoverability">Tor Undiscoverability</link> requirement.
964)  </para>
965)  </listitem>
966)  <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
967)  <para>
968) This setting is currently always disabled. If anyone ever complains saying
969) that they *want* their browser to be able to send ping notifications to a
970) page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
971) my breath. I haven't checked if the content policy is called for pings, but if
972) not, this setting helps with meeting the <link linkend="isolation">Network
973) Isolation</link> requirement.
974)  </para>
975)  </listitem>
976)  <listitem><ulink
977) url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
978)  <para>
979) Likewise for this setting. I find it hard to imagine anyone who wants to ask
980) Google in real time if each URL they visit is safe, especially when the list
981) of unsafe URLs is downloaded anyway. This helps fulfill the <link
982) linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
983) browsing history from ending up on Google's disks.
984)  </para>
985)  </listitem>
986)  <listitem><ulink
987) url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
988)  <para>
989) Safebrowsing does <ulink
990) url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
991) updates under Firefox 2</ulink>, so it is disabled during Tor usage. 
992) This helps fulfill the <link linkend="updates">Update
993) Safety</link> requirement. Firefox 3 has the fix for that bug, and so
994) safebrowsing updates are enabled during Tor usage.
995)  </para>
996)  </listitem>
997)  <listitem><ulink
998) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
999)  <para>
1000) If Tor is enabled, we need to prevent random external applications from
1001) launching without at least warning the user. This group of settings only
1002) partially accomplishes this, however. Applications can still be launched via
1003) plugins. The mechanisms for handling this are described under the "Disable
1004) Plugins During Tor Usage" preference. This helps fulfill the <link
1005) linkend="proxy">Proxy Obedience</link> requirement, by preventing external
1006) applications from accessing network resources at the command of Tor-fetched
1007) pages. Unfortunately, due to <link linkend="FirefoxBugs">Firefox Bug</link>
1008) <ulink
1009) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink>,
1010) these prefs are no longer obeyed. They are set still anyway out of respect for
1011) the dead.
1012)  </para>
1013) </listitem>
1014)   <listitem><ulink
1015) url="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo">browser.sessionstore.max_tabs_undo</ulink>
1016)    <para>
1017) 
1018) To help satisfy the Torbutton <link linkend="state">State Separation</link>
1019) and <link linkend="isolation">Network Isolation</link> requirements,
1020) Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
1021) "Undo Close" operations from accidentally restoring tabs from a different Tor
1022) State. This purge is accomplished by setting this preference to 0 and then
1023) restoring it to the previous user value upon toggle.
1024) 
1025)    </para>
1026)   </listitem>
1027) 

1028)   <listitem><command>security.enable_ssl2</command> or <ulink
1029) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto">nsIDOMCrypto::logout()</ulink>

1030)    <para>
1031) TLS Session IDs can persist for an indefinite duration, providing an
1032) identifier that is sent to TLS sites that can be used to link activity. This
1033) is particularly troublesome now that we have certificate verification in place
1034) in Firefox 3: The OCSP server can use this Session ID to build a history of
1035) TLS sites someone visits, and also correlate their activity as users move from
1036) network to network (such as home to work to coffee shop, etc), inside and
1037) outside of Tor. To handle this and to help satisfy our <link

1038) linkend="state">State Separation Requirement</link>, we call the logout()
1039) function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
1040) to toggling

1041) <command>security.enable_ssl2</command>, which clears the SSL Session ID
1042) cache via the pref observer at <ulink

1043) url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.

1044)    </para>
1045)   </listitem>

1046)   <listitem><command>security.OCSP.enabled</command>
1047)    <para>
1048) Similarly, we toggle <command>security.OCSP.enabled</command>, which clears the OCSP certificate
1049) validation cache via the pref observer at <ulink
1050) url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
1051) In this way, exit nodes will not be able to fingerprint you
1052) based the fact that non-Tor OCSP lookups were obviously previously cached.
1053) To handle this and to help satisfy our <link
1054) linkend="state">State Separation Requirement</link>,
1055)    </para>
1056)   </listitem>
1057)   <listitem><command><ulink
1058) url="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</ulink></command>
1059)   <para>
1060) We permanently disable addon usage statistic reporting to the
1061) addons.mozilla.org statistics engine. These statistics send version
1062) information about Torbutton users via non-Tor, allowing their Tor use to be
1063) uncovered. Disabling this reporting helps Torbutton to satisfy its <link
1064) linkend="undiscoverability">Tor Undiscoverability</link> requirement.
1065) 
1066)   </para>
1067)   </listitem>

1068) 
1069)   <listitem><command><ulink url="http://www.mozilla.com/en-US/firefox/geolocation/">geo.enabled</ulink></command>
1070)    <para>
1071) 
1072) Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
1073) is enabled. This helps Torbutton maintain its
1074) <link linkend="location">Location Neutrality</link> requirement.
1075) While Firefox does prompt before divulging geolocational information,
1076) the assumption is that Tor users will never want to give their
1077) location away during Tor usage, and even allowing websites to prompt
1078) them to do so will only cause confusion and accidents to happen. Moreover,
1079) just because users may approve a site to know their location in non-Tor mode
1080) does not mean they want it divulged during Tor mode.
1081) 
1082)    </para>
1083)   </listitem>
1084) 
1085)   <listitem><command><ulink
1086) url="http://kb.mozillazine.org/Browser.zoom.siteSpecific">browser.zoom.siteSpecific</ulink></command>
1087)    <para>
1088) 
1089) Firefox actually remembers your zoom settings for certain sites. CSS
1090) and Javascript rule can use this to recognize previous visitors to a site.
1091) This helps Torbutton fulfill its <link linkend="state">State Separation</link>
1092) requirement.
1093) 
1094)    </para>
1095)   </listitem>
1096) 
1097)   <listitem><command><ulink
1098) url="https://developer.mozilla.org/en/controlling_dns_prefetching">network.dns.disablePrefetch</ulink></command>
1099)    <para>
1100) 
1101) Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
1102) links on a page to decrease page load latency. While Firefox does typically
1103) disable this behavior when proxies are enabled, we set this pref for added
1104) safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
1105) their links prefetched after a toggle to Non-Tor mode occurs,
1106) we also set the docShell attribute
1107) <ulink
1108) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell">
1109) allowDNSPrefetch</ulink> to false on Tor loaded tabs. This happens in the same
1110) positions in the code as those for disabling plugins via the allowPlugins
1111) docShell attribute. This helps Torbutton fulfill its <link
1112) linkend="isolation">Network Isolation</link> requirement.
1113) 
1114)    </para>
1115)   </listitem>
1116) 
1117)   <listitem><command><ulink
1118) url="http://kb.mozillazine.org/Browser.cache.offline.enable">browser.cache.offline.enable</ulink></command>
1119)    <para>
1120) 
1121) Firefox has the ability to store web applications in a special cache to allow
1122) them to continue to operate while the user is offline. Since this subsystem
1123) is actually different than the normal disk cache, it must be dealt with
1124) separately. Thus, Torbutton sets this preference to false whenever Tor is
1125) enabled. This helps Torbutton fulfill its <link linkend="disk">Disk
1126) Avoidance</link> and <link linkend="state">State Separation</link>
1127) requirements.
1128) 
1129)    </para>
1130)   </listitem>
1131) 
1132) <!-- FIXME: We should make it possible to search for ALL modified FF prefs -->
1133) 
1134) </orderedlist>
1135) </sect2>
1136) 
1137) </sect1>
1138) 
1139) <sect1>
1140)  <title>Description of Options</title>
1141) <para>This section provides a detailed description of Torbutton's options. Each
1142) option is presented as the string from the preferences window, a summary, the
1143) preferences it touches, and the effect this has on the components, chrome, and
1144) browser properties.</para>

1145) <!-- FIXME: figure out how to give subsections # ids or make this into a
1146) listitem -->

1147)  <sect2>

1148)   <title>Proxy Settings</title>
1149)  <sect3>

1150)   <title>Test Settings</title>
1151)   <para>
1152) This button under the Proxy Settings tab provides a way to verify that the 
1153) proxy settings are correct, and actually do route through the Tor network. It
1154) performs this check by issuing an <ulink
1155) url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
1156) for <ulink
1157) url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
1158) This is a special page that returns very simple, yet well-formed XHTML that
1159) Torbutton can easily inspect for a hidden link with an id of
1160) <command>TorCheckResult</command> and a target of <command>success</command>
1161) or <command>failure</command> to indicate if the
1162) user hit the page from a Tor IP, a non-Tor IP. This check is handled in
1163) <function>torbutton_test_settings()</function> in <ulink

1164) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>.

1165) Presenting the results to the user is handled by the <ulink

1166) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences

1167) window</ulink>
1168) callback <function>torbutton_prefs_test_settings()</function> in <ulink

1169) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">preferences.js</ulink>.  

1170) 
1171)   </para>

1172)  </sect3>

1173)  </sect2>

1174)  <sect2>
1175)   <title>Dynamic Content Settings</title>
1176)  <sect3 id="plugins">

1177)   <title>Disable plugins on Tor Usage (crucial)</title>
1178)  <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
1179) 
1180)  <para>Java and plugins <ulink
1181) url="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html">can query</ulink> the <ulink
1182) url="http://www.rgagnon.com/javadetails/java-0095.html">local IP
1183) address</ulink> and report it back to the
1184) remote site. They can also <ulink
1185) url="http://decloak.net">bypass proxy settings</ulink> and directly connect to a
1186) remote site without Tor. Every browser plugin we have tested with Firefox has
1187) some form of network capability, and every one ignores proxy settings or worse - only
1188) partially obeys them. This includes but is not limited to:
1189) QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
1190) Flash. 
1191) 
1192)  </para>
1193)  <para>
1194) Enabling this preference causes the above mentioned Torbutton chrome web progress
1195)  listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
1196)  plugins via the browser <ulink
1197)  url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink>
1198)  attribute <command>allowPlugins</command>. These flags are set every time a new window is
1199)  created (<function>torbutton_tag_new_browser()</function>), every time a web
1200) load
1201) event occurs
1202)  (<function>torbutton_update_tags()</function>), and every time the tor state is changed
1203)  (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
1204)  prevented from loading by the content policy in <ulink

1205) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is

1206)  enabled and this option is set.
1207)  </para>
1208) 
1209)  <para>All of this turns out to be insufficient if the user directly clicks
1210) on a plugin-handled mime-type. <ulink
1211) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">In this case</ulink>,
1212) the browser decides that maybe it should ignore all these other settings and
1213) load the plugin anyways, because maybe the user really did want to load it
1214) (never mind this same load-style could happen automatically  with meta-refresh
1215) or any number of other ways..). To handle these cases, Torbutton stores a list
1216) of plugin-handled mime-types, and sets the pref
1217) <command>plugin.disable_full_page_plugin_for_types</command> to this list.
1218) Additionally, (since nothing can be assumed when relying on Firefox
1219) preferences and internals) if it detects a load of one of them from the web
1220) progress listener, it cancels the request, tells the associated DOMWindow to
1221) stop loading, clears the document, AND throws an exception. Anything short of
1222) all this and the plugin managed to find some way to load.
1223)  </para>
1224) 
1225) <!--
1226) 
1227) FIXME: Hrmm, technically this behavior is not covered by this pref.
1228) 
1229)  <para>
1230) Furthermore, with version 3.0 and above, Firefox
1231) <ulink
1232) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">began ignoring</ulink>
1233) 
1234) <ulink
1235) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
1236) prefs, which caused us to have to <link linkend="appblocker">wrap the external
1237) app launcher components</link> to prevent external apps from being loaded to
1238) bypass proxy settings.
1239)  </para>
1240) -->
1241) 
1242)  <para>
1243)  All this could be avoided, of course, if Firefox would either <ulink
1244) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
1245)  allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
1246)  loads either <ulink
1247) url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
1248) url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
1249)  not very encouraging.
1250)  </para>
1251) 
1252) 
1253)  <para>
1254) 
1255) Since most plugins completely ignore browser proxy settings, the actions
1256) performed by this setting are crucial to satisfying the <link
1257) linkend="proxy">Proxy Obedience</link> requirement.
1258) 
1259)  </para>

1260) </sect3>
1261) <sect3>

1262)  <title>Isolate Dynamic Content to Tor State (crucial)</title>
1263) 
1264)  <para>Option: <command>extensions.torbutton.isolate_content</command></para>
1265) 
1266) <para>Enabling this preference is what enables the <ulink

1267) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy

1268) mentioned above, and causes it to block content load attempts in pages an
1269) opposite Tor state from the current state. Freshly loaded <ulink
1270) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
1271) tabs</ulink> are tagged
1272) with a <command>__tb_load_state</command> member in
1273) <function>torbutton_update_tags()</function> and this
1274) value is compared against the current tor state in the content policy.</para>
1275) 
1276) <para>It also kills all Javascript in each page loaded under that state by
1277) toggling the <command>allowJavascript</command> <ulink
1278) url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink> property, and issues a
1279) <ulink
1280) url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
1281) equivalent of hitting the STOP button).</para>
1282) 
1283) <para>
1284) 
1285) Unfortunately, <ulink
1286) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
1287) 409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
1288) all event handlers, and event handlers registered with <ulink
1289) url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
1290) are still able to execute. The <link linkend="contentpolicy">Torbutton Content
1291) Policy</link> should prevent such code from performing network activity within
1292) the current tab, but activity that happens via a popup window or via a
1293) Javascript redirect can still slip by. For this reason, Torbutton blocks
1294) popups by checking for a valid <ulink
1295) url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
1296) attribute in <function>torbutton_check_progress()</function>. If the window
1297) has an opener from a different Tor state, its load is blocked. The content
1298) policy also takes similar action to prevent Javascript redirects. This also
1299) has the side effect/feature of preventing the user from following any links
1300) from a page loaded in an opposite Tor state.
1301) 
1302) </para>
1303) 
1304) <para>
1305) This setting is responsible for satisfying the <link
1306) linkend="isolation">Network Isolation</link> requirement.
1307) </para>
1308) 

1309) </sect3>
1310) <sect3 id="jshooks">

1311) 
1312) <title>Hook Dangerous Javascript</title>
1313) 
1314)  <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
1315) 
1316) <para>This setting enables injection of the <ulink

1317) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js">Javascript

1318) hooking code</ulink>. This is done in the chrome in
1319) <function>torbutton_hookdoc()</function>, which is called ultimately by both the 
1320) <ulink
1321) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
1322) listener</ulink> <command>torbutton_weblistener</command> and the <link
1323) linkend="contentpolicy">content policy</link> (the latter being a hack to handle
1324) javascript: urls).
1325) 
1326) In the Firefox 2 days, this option did a lot more than
1327) it does now. It used to be responsible for timezone and improved useragent
1328) spoofing, and history object cloaking. However, now it only provides
1329) obfuscation of the <ulink
1330) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
1331) object to mask your browser and desktop resolution.
1332) The resolution hooks
1333) effectively make the Firefox browser window appear to websites as if the renderable area
1334) takes up the entire desktop, has no toolbar or other GUI element space, and
1335) the desktop itself has no toolbars.
1336) These hooks drastically reduce the amount of information available to do <link
1337) linkend="fingerprinting">anonymity set reduction attacks</link> and help to
1338) meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
1339) requirements. Unfortunately, Gregory Fleischer discovered it is still possible
1340) to retrieve the original screen values by using <ulink
1341) url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
1342) or <ulink
1343) url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.

1344) We are still looking for a workaround as of Torbutton 1.3.2.

1345) 
1346) <!-- FIXME: Don't forget to update this -->

1347) <!-- XXX: Date() issue now fixed by TZ variable! -->

1348) 
1349) </para>

1350) </sect3>
1351) <sect3>

1352) <title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
1353) 
1354)  <para>Option: <command>extensions.torbutton.resize_windows</command></para>
1355) 
1356) <para>
1357) 
1358) This option drastically cuts down on the number of distinct anonymity sets
1359) that divide the Tor web userbase. Without this setting, the dimensions for a
1360) typical browser window range from 600-1200 horizontal pixels and 400-1000
1361) vertical pixels, or about 600x600 = 360000 different sets. Resizing the
1362) browser window to multiples of 50 on each side reduces the number of sets by
1363) 50^2, bringing the total number of sets to 144. Of course, the distribution
1364) among these sets are not uniform, but scaling by 50 will improve the situation
1365) due to this non-uniformity for users in the less common resolutions.
1366) Obviously the ideal situation would be to lie entirely about the browser
1367) window size, but this will likely cause all sorts of rendering issues, and is
1368) also not implementable in a foolproof way from extension land.
1369) 
1370) </para>
1371) <para>
1372) 
1373) The implementation of this setting is spread across a couple of different
1374) locations in the Torbutton javascript <link linkend="browseroverlay">browser
1375) overlay</link>. Since resizing minimized windows causes them to be restored,
1376) and since maximized windows remember their previous size to the pixel, windows
1377) must be resized before every document load (at the time of browser tagging)
1378) via <function>torbutton_check_round()</function>, called by
1379) <function>torbutton_update_tags()</function>. To prevent drift, the extension
1380) tracks the original values of the windows and uses this to perform the
1381) rounding on document load. In addition, to prevent the user from resizing a
1382) window to a non-50px multiple, a resize listener
1383) (<function>torbutton_do_resize()</function>) is installed on every new browser
1384) window to record the new size and round it to a 50px multiple while Tor is
1385) enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
1386) are set. This ensures that there is no discrepancy between the 50 pixel cutoff
1387) and the actual renderable area of the browser (so that it is not possible to
1388) infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
1389) 
1390) </para>
1391) <para>
1392) This setting helps to meet the <link
1393) linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1394) </para>

1395) </sect3>
1396) <sect3>
1397) 
1398) <title>Disable Search Suggestions during Tor (recommended)</title>
1399) 
1400)   <para>Option: <command>extensions.torbutton.no_search</command></para>
1401) 
1402) <para>
1403) This setting causes Torbutton to disable <ulink
1404) url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1405) during Tor usage.
1406) This governs if you get Google search suggestions during Tor
1407) usage. Your Google cookie is transmitted with google search suggestions, hence
1408) this is recommended to be disabled.
1409) 
1410) </para>
1411) <para>
1412) While this setting doesn't satisfy any Torbutton requirements, the fact that
1413) cookies are transmitted for partially typed queries does not seem desirable
1414) for Tor usage.
1415) </para>
1416) </sect3>
1417) 
1418) 
1419) <sect3>

1420) <title>Disable Updates During Tor</title>
1421) 
1422)   <para>Option: <command>extensions.torbutton.no_updates</command></para>
1423) 
1424)   <para>This setting causes Torbutton to disable the four <ulink
1425) url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
1426) update settings</ulink> during Tor
1427)   usage: <command>extensions.update.enabled</command>,
1428) <command>app.update.enabled</command>,
1429)   <command>app.update.auto</command>, and
1430) <command>browser.search.update</command>.  These prevent the
1431)   browser from updating extensions, checking for Firefox upgrades, and
1432)   checking for search plugin updates while Tor is enabled.
1433)   </para>
1434) <para>
1435) This setting satisfies the <link
1436) linkend="updates">Update Safety</link> requirement.
1437) </para>

1438) </sect3>
1439) <sect3>

1440) <title>Redirect Torbutton Updates Via Tor (recommended)</title>
1441) 
1442)   <para>Option: <command>extensions.torbutton.update_torbutton_via_tor</command></para>
1443) 
1444)   <para>This setting causes Torbutton to install an
1445) 
1446) <ulink
1447) url="https://developer.mozilla.org/en/nsIProtocolProxyFilter">nsIProtocolProxyFilter</ulink>
1448) in order to redirect all version update checks and Torbutton update downloads
1449) via Tor, regardless of if Tor is enabled or not. This was done both to address
1450) concerns about data retention done by <ulink
1451) url="https://www.addons.mozilla.org">addons.mozilla.org</ulink>, as well as to
1452) help censored users meet the <link linkend="undiscoverability">Tor
1453) Undiscoverability</link> requirement.
1454) 
1455)   </para>

1456) </sect3>

1457) 

1458) <sect3>

1459) <title>Disable livemarks updates during Tor usage (recommended)</title>
1460)   <para>Option:
1461)    <simplelist>
1462)    <member><command>extensions.torbutton.disable_livemarks</command></member>
1463)    </simplelist>
1464)   </para>
1465) 
1466) <para>

1467) 

1468) This option causes Torbutton to prevent Firefox from loading <ulink
1469) url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
1470) Tor usage. Because people often have very personalized Livemarks (such as RSS
1471) feeds of Wikipedia articles they maintain, etc). This is accomplished both by
1472) <link linkend="livemarks">wrapping the livemark-service component</link> and
1473) by calling stopUpdateLivemarks() on the <ulink
1474) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">Livemark
1475) service</ulink> when Tor is enabled.
1476) 
1477) </para>
1478) 
1479) <para>
1480) This helps satisfy the <link linkend="isolation">Network
1481) Isolation</link> and <link linkend="setpreservation">Anonymity Set
1482) Preservation</link> requirements.
1483) </para>
1484) 

1485) </sect3>
1486) <sect3>

1487) <title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1488)   <para>Options:
1489)    <simplelist>
1490)    <member><command>extensions.torbutton.block_tor_file_net</command></member>
1491)    <member><command>extensions.torbutton.block_nontor_file_net</command></member>
1492)    </simplelist>
1493)   </para>
1494) 
1495) <para>
1496) 
1497) These settings prevent file urls from performing network operations during the
1498) respective Tor states. Firefox 2's implementation of same origin policy allows
1499) file urls to read and <ulink
1500) url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
1501) arbitrary files from the local filesystem</ulink> to arbitrary websites. To
1502) make matters worse, the 'Content-Disposition' header can be injected
1503) arbitrarily by exit nodes to trick users into running arbitrary html files in
1504) the local context. These preferences cause the <link
1505) linkend="contentpolicy">content policy</link> to block access to any network
1506) resources from File urls during the appropriate Tor state.
1507) 
1508) </para>
1509) <para>
1510) 
1511) This preference helps to ensure Tor's <link linkend="isolation">Network
1512) Isolation</link> requirement, by preventing file urls from executing network
1513) operations in opposite Tor states. Also, allowing pages to submit arbitrary
1514) files to arbitrary sites just generally seems like a bad idea.
1515) 
1516) </para>

1517) </sect3>
1518) 
1519) <sect3>

1520) 
1521) <title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1522) 
1523)   <para>Options:
1524)    <simplelist>
1525)    <member><command>extensions.torbutton.close_nontor</command></member>
1526)    <member><command>extensions.torbutton.close_tor</command></member>
1527)    </simplelist>
1528)   </para>
1529) 
1530) <para>
1531) 
1532) These settings cause Torbutton to enumerate through all windows and close all
1533) tabs in each window for the appropriate Tor state. This code can be found in
1534) <function>torbutton_update_status()</function>.  The main reason these settings
1535) exist is as a backup mechanism in the event of any Javascript or content policy
1536) leaks due to <ulink
1537) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1538) 409737</ulink>.  Torbutton currently tries to block all Javascript network
1539) activity via the content policy, but until that bug is fixed, there is some
1540) risk that there are alternate ways to bypass the policy. This option is
1541) available as an extra assurance of <link linkend="isolation">Network
1542) Isolation</link> for those who would like to be sure that when Tor is toggled
1543) all page activity has ceased. It also serves as a potential future workaround
1544) in the event a content policy failure is discovered, and provides an additional
1545) level of protection for the <link linkend="disk">Disk Avoidance</link>
1546) protection so that browser state is not sitting around waiting to be swapped
1547) out longer than necessary.
1548) 
1549) </para>
1550) <para>
1551) While this setting doesn't satisfy any Torbutton requirements, the fact that
1552) cookies are transmitted for partially typed queries does not seem desirable
1553) for Tor usage.
1554) </para>

1555) </sect3>
1556)  </sect2>
1557)  <sect2>
1558)   <title>History and Forms Settings</title>
1559) <sect3>

1560) <title>Isolate Access to History navigation to Tor state (crucial)</title>
1561)   <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1562)   <para>
1563) This setting determines if Torbutton installs an <ulink
1564) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener">nsISHistoryListener</ulink>
1565) attached to the <ulink
1566) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">sessionHistory</ulink> of 
1567) of each browser's <ulink
1568) url="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation">webNavigatator</ulink>.
1569) The nsIShistoryListener is instantiated with a reference to the containing
1570) browser window and blocks the back, forward, and reload buttons on the browser
1571) navigation bar when Tor is in an opposite state than the one to load the
1572) current tab. In addition, Tor clears the session history during a new document
1573) load if this setting is enabled. 
1574) 
1575)   </para>
1576)   <para>
1577) 
1578) This is marked as a crucial setting in part
1579) because Javascript access to the history object is indistinguishable from 
1580) user clicks, and because
1581) <ulink
1582) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1583) 409737</ulink> allows javascript to execute in opposite Tor states, javascript
1584) can issue reloads after Tor toggle to reveal your original IP. Even without
1585) this bug, however, Javascript is still able to access previous pages in your
1586) session history that may have been loaded under a different Tor state, to
1587) attempt to correlate your activity.
1588) 
1589)    </para>
1590)    <para>
1591) 
1592) This setting helps to fulfill Torbutton's <link linkend="state">State
1593) Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
1594) requirements.
1595) 
1596)    </para>

1597) </sect3>

1598) 
1599) 

1600) <sect3>

1601) <title>History Access Settings</title>
1602) 
1603)   <para>Options:
1604)   <simplelist>
1605)    <member><command>extensions.torbutton.block_thread</command></member>
1606)    <member><command>extensions.torbutton.block_nthread</command></member>
1607)    <member><command>extensions.torbutton.block_thwrite</command></member>
1608)    <member><command>extensions.torbutton.block_nthwrite</command></member>
1609)   </simplelist>
1610)   </para>
1611) 

1612) <para>On Firefox 3.x, these four settings govern the behavior of the <ulink
1613) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink>

1614) history blocker component mentioned above. By hooking the browser's view of
1615) the history itself via the <ulink
1616) 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>
1617) and <ulink
1618) 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>
1619) components, this mechanism defeats all document-based <ulink
1620) url="http://whattheinternetknowsaboutyou.com/">history disclosure
1621) attacks</ulink>, including <ulink
1622) url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
1623) 
1624) The component also hooks functions involved in writing history to disk via
1625) both the <ulink
1626) url="http://developer.mozilla.org/en/docs/Places_migration_guide#History">Places
1627) Database</ulink> and the older Firefox 2 mechanisms.
1628) 
1629) </para>
1630) 

1631) <para>
1632) On Firefox 4, Mozilla finally <ulink
1633) url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">addressed
1634) these issues</ulink>, so we can effectively ignore the "read" pair of the
1635) above prefs. We then only need to link the write prefs to
1636) <command>places.history.enabled</command>, which disabled writing to the
1637) history store while set.
1638) </para>
1639) 

1640) <para>
1641) This setting helps to satisfy the <link
1642) linkend="state">State Separation</link> and <link
1643) linkend="disk">Disk Avoidance</link> requirements.
1644) </para>
1645) 

1646) </sect3>
1647) <sect3>

1648) 
1649) <title>Clear History During Tor Toggle (optional)</title>
1650) 
1651) <para>Option: <command>extensions.torbutton.clear_history</command></para>
1652) 
1653) <para>This setting governs if Torbutton calls
1654) <ulink
1655) url="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29">nsIBrowserHistory.removeAllPages</ulink>
1656) and <ulink
1657) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">nsISHistory.PurgeHistory</ulink>
1658) for each tab on Tor toggle.</para>
1659) <para>
1660) This setting is an optional way to help satisfy the <link
1661) linkend="state">State Separation</link> requirement.
1662) </para>
1663) 

1664) </sect3>
1665) <sect3>

1666) <title>Block Password+Form saving during Tor/Non-Tor</title>
1667) 
1668) <para>Options:
1669)   <simplelist>
1670)   <member><command>extensions.torbutton.block_tforms</command></member>
1671)   <member><command>extensions.torbutton.block_ntforms</command></member>
1672)   </simplelist>
1673)   </para>
1674) 
1675) <para>These settings govern if Torbutton disables
1676) <command>browser.formfill.enable</command>
1677) and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
1678) Since form fields can be read at any time by Javascript, this setting is a lot
1679) more important than it seems.
1680) </para>
1681) 
1682) <para>
1683) This setting helps to satisfy the <link
1684) linkend="state">State Separation</link> and <link
1685) linkend="disk">Disk Avoidance</link> requirements.
1686) </para>
1687) 

1688) </sect3>
1689)  </sect2>
1690)  <sect2>
1691)   <title>Cache Settings</title>
1692) <sect3>

1693)   <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
1694) 
1695)   <para>Option: <command>extensions.torbutton.clear_cache</command>
1696)   </para>
1697) 
1698) <para>This option causes Torbutton to call <ulink
1699) url="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29">nsICacheService.evictEntries(0)</ulink>
1700) on Tor toggle to remove all entries from the cache. In addition, this setting
1701) causes Torbutton to set <ulink
1702) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
1703) </para>
1704) <para>
1705) This setting helps to satisfy the <link
1706) linkend="state">State Separation</link> and <link
1707) linkend="disk">Disk Avoidance</link> requirements.
1708) </para>
1709) 

1710) </sect3>
1711) <sect3>

1712)   <title>Block disk and memory cache during Tor</title>
1713) 
1714) <para>Option: <command>extensions.torbutton.block_cache</command></para>
1715) 
1716) <para>This setting
1717) causes Torbutton to set <ulink
1718) url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
1719) <ulink
1720) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
1721) <ulink
1722) url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
1723) </para>
1724) <para>
1725) This setting helps to satisfy the <link
1726) linkend="state">State Separation</link> and <link
1727) linkend="disk">Disk Avoidance</link> requirements.
1728) </para>
1729) 

1730) </sect3>
1731)  </sect2>
1732)  <sect2>
1733)   <title>Cookie and Auth Settings</title>
1734) <sect3>

1735)   <title>Clear Cookies on Tor Toggle</title>
1736) 
1737) <para>Option: <command>extensions.torbutton.clear_cookies</command>
1738)   </para>
1739) 
1740) <para>
1741) 
1742) This setting causes Torbutton to call <ulink
1743) url="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29">nsICookieManager.removeAll()</ulink> on
1744) every Tor toggle. In addition, this sets <ulink
1745) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1746) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1747) which prevents them from being written to disk. 
1748) 
1749) </para>
1750) <para>
1751) This setting helps to satisfy the <link
1752) linkend="state">State Separation</link> and <link
1753) linkend="disk">Disk Avoidance</link> requirements.
1754) </para>
1755) 

1756) </sect3>
1757) <sect3>

1758)   
1759)   <title>Store Non-Tor cookies in a protected jar</title>
1760) 
1761) <para>Option: <command>extensions.torbutton.cookie_jars</command>
1762)   </para>
1763) 
1764) <para>
1765) 
1766) This setting causes Torbutton to use <ulink

1767) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store

1768) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
1769) before restoring the jar.
1770) </para>
1771) <para>
1772) This setting also sets <ulink
1773) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1774) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1775) which prevents them from being written to disk. 
1776) 
1777) </para>
1778) 
1779) <para>
1780) This setting helps to satisfy the <link
1781) linkend="state">State Separation</link> and <link
1782) linkend="disk">Disk Avoidance</link> requirements.
1783) </para>
1784) 
1785) 

1786) </sect3>
1787) <sect3>

1788) 
1789)   <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
1790) 
1791) <para>Option: <command>extensions.torbutton.dual_cookie_jars</command>
1792)   </para>
1793) 
1794) <para>
1795) 
1796) This setting causes Torbutton to use <ulink

1797) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store

1798) both Tor and Non-Tor cookies into protected jars.
1799) </para>
1800) 
1801) <para>
1802) This setting helps to satisfy the <link
1803) linkend="state">State Separation</link> requirement.
1804) </para>
1805) 
1806) 

1807) </sect3>

1808) 

1809) <!-- FIXME: If we decide to keep it, document the cookie protections dialog
1810) -->

1811) 

1812) <sect3>

1813) 
1814)   <title>Manage My Own Cookies (dangerous)</title>
1815) 
1816) <para>Options: None</para>
1817) <para>This setting disables all Torbutton cookie handling by setting the above
1818) cookie prefs all to false.</para>

1819) </sect3>
1820) <sect3>

1821) 

1822) <sect3>

1823)   <title>Do not write Tor/Non-Tor cookies to disk</title>
1824)   <para>Options:
1825)   <simplelist>
1826)   <member><command>extensions.torbutton.tor_memory_jar</command></member>
1827)   <member><command>extensions.torbutton.nontor_memory_jar</command></member>
1828)   </simplelist>
1829)   </para>
1830) 
1831) <para>
1832) These settings (contributed by arno) cause Torbutton to set <ulink
1833) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1834) to 2 during the appropriate Tor state, and to store cookies acquired in that
1835) state into a Javascript
1836) <ulink
1837) url="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X">E4X</ulink>
1838) object as opposed to writing them to disk.
1839) </para>
1840) 
1841) <para>
1842) This allows Torbutton to provide an option to preserve a user's 
1843) cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
1844) requirement.
1845) </para>

1846) </sect3>

1847) 
1848) 
1849)   <title>Disable DOM Storage during Tor usage (crucial)</title>
1850) 
1851) <para>Option: <command>extensions.torbutton.disable_domstorage</command>
1852)   </para>
1853) 
1854) <para>
1855) 
1856) This setting causes Torbutton to toggle <command>dom.storage.enabled</command> during Tor
1857) usage to prevent 
1858) <ulink
1859)   url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink> from
1860)   being used to store persistent information across Tor states.</para>
1861) <para>
1862) This setting helps to satisfy the <link
1863) linkend="state">State Separation</link> requirement.
1864) </para>
1865) 

1866) </sect3>

1867) 

1868) <sect3>

1869)   <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
1870) <para>Option: <command>extensions.torbutton.clear_http_auth</command>
1871)   </para>
1872) 
1873) <para>
1874) This setting causes Torbutton to call <ulink
1875) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager">nsIHttpAuthManager.clearAll()</ulink>
1876) every time Tor is toggled.
1877) </para>
1878) 
1879) <para>
1880) This setting helps to satisfy the <link
1881) linkend="state">State Separation</link> requirement.
1882) </para>

1883) </sect3>
1884)  </sect2>
1885)  <sect2>
1886)   <title>Startup Settings</title>
1887) <sect3>
1888)   <title>On Browser Startup, set Tor state to: Tor, Non-Tor</title>

1889)   <para>Options:

1890)    <command>extensions.torbutton.restore_tor</command>

1891)   </para>
1892) 

1893)   <para>This option governs what Tor state tor is loaded in to.
1894) <function>torbutton_set_initial_state()</function> covers the case where the
1895) browser did not crash, and <function>torbutton_crash_recover()</function>
1896) covers the case where the <link linkend="crashobserver">crash observer</link>
1897) detected a crash.

1898) </para>
1899) <para>
1900) 
1901) Since the Tor state after a Firefox crash is unknown/indeterminate, this
1902) setting helps to satisfy the <link linkend="state">State Separation</link>
1903) requirement in the event of Firefox crashes by ensuring all cookies,
1904) settings and saved sessions are reloaded from a fixed Tor state.
1905)  
1906) </para>

1907) </sect3>

1908) 
1909) 

1910) <sect3>

1911)   <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
1912) 
1913)   <para>Options: 
1914)   <simplelist>
1915)     <member><command>extensions.torbutton.nonontor_sessionstore</command></member>
1916)     <member><command>extensions.torbutton.notor_sessionstore</command></member>
1917)   </simplelist>
1918)   </para>
1919) 

1920)   <para>If these options are enabled, the <link
1921) linkend="tbsessionstore">tbSessionStore.js</link> component uses the session
1922) store listeners to filter out the appropriate tabs before writing the session
1923) store data to disk.
1924) </para>

1925) <para>
1926) This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
1927) requirement, and also helps to satisfy the <link
1928) linkend="state">State Separation</link> requirement in the event of Firefox
1929) crashes.
1930) 
1931) </para>
1932) 

1933) </sect3>
1934)  </sect2>
1935)  <sect2>
1936)   <title>Shutdown Settings</title>
1937) <sect3>
1938) 
1939)   <title>Clear cookies on Tor/Non-Tor shutdown</title>
1940) 
1941) <para>Option: <command>extensions.torbutton.shutdown_method</command>
1942)   </para>
1943) 
1944) <para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1945) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1946) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1947) for the <ulink
1948) url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
1949) <link linkend="crashobserver">crash-observer.js</link> and use <ulink
1950) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1951) to clear out all cookies and all cookie jars upon shutdown.
1952) </para>
1953) <para>
1954) This setting helps to satisfy the <link
1955) linkend="state">State Separation</link> requirement.
1956) </para>

1957) 

1958) 
1959) </sect3>
1960)  </sect2>
1961)  <sect2>
1962)   <title>Header Settings</title>
1963) <sect3>

1964) 
1965)   <title>Set user agent during Tor usage (crucial)</title>
1966)   <para>Options:
1967)    <simplelist>
1968)     <member><command>extensions.torbutton.set_uagent</command></member>
1969)     <member><command>extensions.torbutton.platform_override</command></member>
1970)     <member><command>extensions.torbutton.oscpu_override</command></member>
1971)     <member><command>extensions.torbutton.buildID_override</command></member>
1972)     <member><command>extensions.torbutton.productsub_override</command></member>
1973)     <member><command>extensions.torbutton.appname_override</command></member>
1974)     <member><command>extensions.torbutton.appversion_override</command></member>
1975)     <member><command>extensions.torbutton.useragent_override</command></member>
1976)     <member><command>extensions.torbutton.useragent_vendor</command></member>
1977)     <member><command>extensions.torbutton.useragent_vendorSub</command></member>
1978)   </simplelist>
1979)    </para>
1980) 
1981) <para>On face, user agent switching appears to be straight-forward in Firefox.
1982) It provides several options for controlling the browser user agent string:
1983) <command>general.appname.override</command>,
1984) <command>general.appversion.override</command>,
1985) <command>general.platform.override</command>,
1986) <command>general.oscpu.override</command>,
1987) <command>general.productSub.override</command>,
1988) <command>general.buildID.override</command>,
1989) <command>general.useragent.override</command>,
1990) <command>general.useragent.vendor</command>, and
1991) <command>general.useragent.vendorSub</command>. If
1992) the Torbutton preference <command>extensions.torbutton.set_uagent</command> is
1993) true, Torbutton copies all of the other above prefs into their corresponding
1994) browser preferences during Tor usage.</para>
1995) 
1996) 
1997) <para>
1998) 
1999) It also turns out that it is possible to detect the original Firefox version
2000) by <ulink url="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/">inspecting
2001) certain resource:// files</ulink>. These cases are handled by Torbutton's
2002) <link linkend="contentpolicy">content policy</link>.
2003) 
2004) </para>
2005) 
2006) <para>
2007) This setting helps to satisfy the <link
2008) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2009) </para>
2010) 
2011) 

2012) </sect3>
2013) <sect3>

2014) 
2015)   <title>Spoof US English Browser</title>
2016) <para>Options:
2017) <simplelist>
2018)  <member><command>extensions.torbutton.spoof_english</command></member>
2019)  <member><command>extensions.torbutton.spoof_charset</command></member>
2020)  <member><command>extensions.torbutton.spoof_language</command></member>
2021) </simplelist>
2022) </para>
2023) 
2024) <para> This option causes Torbutton to set
2025) <command>general.useragent.locale</command>
2026) <command>intl.accept_languages</command> to the value specified in
2027) <command>extensions.torbutton.spoof_locale</command>,
2028) <command>extensions.torbutton.spoof_charset</command> and
2029) <command>extensions.torbutton.spoof_language</command> during Tor usage, as
2030) well as hooking <command>navigator.language</command> via its <link
2031) linkend="jshooks">javascript hooks</link>.
2032)  </para>
2033) <para>
2034) This setting helps to satisfy the <link
2035) linkend="setpreservation">Anonymity Set Preservation</link> and <link
2036) linkend="location">Location Neutrality</link> requirements.
2037) </para>
2038) 

2039) </sect3>

2040) 

2041) <sect3>
2042)   <title>Referer Spoofing Options</title>

2043) 

2044) <para>Option: <command>extensions.torbutton.refererspoof</command>

2045) </para>
2046) 

2047) <para>
2048) This option variable has three values. If it is 0, "smart" referer spoofing is
2049) enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is
2050) sent. The default value is 1. The smart referer spoofing is implemented by the
2051) <link linkend="refspoofer">torRefSpoofer</link> component.

2052) 

2053) </para>

2054) <para>
2055) This setting also does not directly satisfy any Torbutton requirement, but

2056) some may desire to mask their referer for general privacy concerns.

2057) </para>

2058) </sect3>
2059) 
2060) <sect3>

2061)   <title>Strip platform and language off of Google Search Box queries</title>
2062) 
2063) <para>Option: <command>extensions.torbutton.fix_google_srch</command>
2064) </para>
2065) 
2066) <para> 
2067) 
2068) This option causes Torbutton to use the <ulink
2069) url="https://wiki.mozilla.org/Search_Service:API">@mozilla.org/browser/search-service;1</ulink>
2070) component to wrap the Google search plugin. On many platforms, notably Debian
2071) and Ubuntu, the Google search plugin is set to reveal a lot of language and
2072) platform information. This setting strips off that info while Tor is enabled.
2073) 
2074) </para>
2075) <para>
2076) This setting helps Torbutton to fulfill its <link
2077) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2078) </para>

2079) </sect3>

2080) 

2081) <sect3>

2082)   <title>Automatically use an alternate search engine when presented with a
2083) Google Captcha</title>
2084) 
2085) <para>Options:
2086) <simplelist>
2087)  <member><command>extensions.torbutton.asked_google_captcha</command></member>
2088)  <member><command>extensions.torbutton.dodge_google_captcha</command></member>
2089)  <member><command>extensions.torbutton.google_redir_url</command></member>
2090) </simplelist>
2091) </para>
2092) 
2093) <para>
2094) 
2095) Google's search engine has rate limiting features that cause it to
2096) <ulink
2097) url="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html">present
2098) captchas</ulink> and sometimes even outright ban IPs that issue large numbers
2099) of search queries, especially if a lot of these queries appear to be searching
2100) for software vulnerabilities or unprotected comment areas.
2101) 
2102) </para>
2103) <para>
2104) 
2105) Despite multiple discussions with Google, we were unable to come to a solution
2106) or any form of compromise that would reduce the number of captchas and
2107) outright bans seen by Tor users issuing regular queries.
2108) 
2109) </para>
2110) <para>
2111) As a result, we've implemented this option as an <ulink
2112) url="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">'http-on-modify-request'</ulink>
2113) http observer to optionally redirect banned or captcha-triggering Google
2114) queries to search engines that do not rate limit Tor users. The current

2115) options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. These are

2116) encoded in the preferences

2117) <command>extensions.torbutton.redir_url.[1-5]</command>.

2118) 
2119) </para>

2120) </sect3>

2121) 

2122) <sect3>

2123) 
2124)   <title>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</title>
2125) 
2126) <para>Options:
2127) <simplelist>
2128)  <member><command>extensions.torbutton.jar_certs</command></member>
2129)  <member><command>extensions.torbutton.jar_ca_certs</command></member>
2130) </simplelist>
2131) </para>
2132) <para>
2133) 
2134) These settings govern if Torbutton attempts to isolate the user's SSL
2135) certificates into separate jars for each Tor state. This isolation is
2136) implemented in <function>torbutton_jar_certs()</function> in <ulink

2137) url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,

2138) which calls <function>torbutton_jar_cert_type()</function> and
2139) <function>torbutton_unjar_cert_type()</function> for each certificate type in
2140) the <ulink
2141) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1">@mozilla.org/security/nsscertcache;1</ulink>.
2142) Certificates are deleted from and imported to the <ulink
2143) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/x509certdb;1">@mozilla.org/security/x509certdb;1</ulink>.
2144) </para>
2145) 
2146) <para>
2147) The first time this pref is used, a backup of the user's certificates is
2148) created in their profile directory under the name
2149) <filename>cert8.db.bak</filename>. This file can be copied back to
2150) <filename>cert8.db</filename> to fully restore the original state of the
2151) user's certificates in the event of any error.
2152) </para>
2153) 
2154) <para>
2155) Since exit nodes and malicious sites can insert content elements sourced to
2156) specific SSL sites to query if a user has a certain certificate,
2157) this setting helps to satisfy the <link linkend="state">State
2158) Separation</link> requirement of Torbutton. Unfortunately, <ulink
2159) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Firefox Bug
2160) 435159</ulink> prevents it from functioning correctly in the event of rapid Tor toggle, so it
2161) is currently not exposed via the preferences UI.
2162) 
2163) </para>
2164) 

2165) </sect3>
2166) 
2167) 

2168) </sect2>
2169) </sect1>
2170) 
2171) <sect1 id="FirefoxBugs">
2172)   <title>Relevant Firefox Bugs</title>
2173)   <para>

2174) Future releases of Torbutton are going to be designed around supporting only
2175) <ulink url="https://www.torproject.org/projects/torbrowser.html.en">Tor
2176) Browser Bundle</ulink>, which greatly simplifies the number and nature of Firefox
2177) bugs we must fix. This allows us to abandon the complexities of <link
2178) linkend="state">State
2179) Separation</link> and <link linkend="isolation">Network Isolation</link> requirements
2180) associated with the Toggle Model.

2181)   </para>

2182)   <sect2 id="TorBrowserBugs">
2183)    <title>Tor Browser Bugs</title>
2184)    <para>
2185) The list of Firefox patches we must create to improve privacy on the
2186) Tor Browser Bundle are collected in the Tor Bug Tracker under <ulink
2187) url="https://trac.torproject.org/projects/tor/ticket/2871">ticket
2188) #2871</ulink>. These bugs are also applicable to the Toggle Model, and
2189) should be considered higher priority than all Toggle Model specific bugs
2190) below.
2191)    </para>
2192)   </sect2>
2193)   <sect2 id="ToggleModelBugs">
2194)    <title>Toggle Model Bugs</title>
2195)    <para>
2196) In addition to the Tor Browser bugs, the Torbutton Toggle Model suffers from
2197) additional bugs specific to the need to isolate state across the toggle.
2198) Toggle model bugs are considered a lower priority than the bugs against the
2199) Tor Browser model.
2200)    </para>
2201)   <sect3 id="FirefoxSecurity">

2202)    <title>Bugs impacting security</title>
2203)    <para>
2204) 
2205) Torbutton has to work around a number of Firefox bugs that impact its
2206) security. Most of these are mentioned elsewhere in this document, but they
2207) have also been gathered here for reference. In order of decreasing severity,
2208) they are:
2209) 
2210)    </para>
2211)    <orderedlist>

2212) <!--
2213) Duplicated in toggle model.

2214)     <listitem><ulink
2215) url="https://bugzilla.mozilla.org/show_bug.cgi?id=429070">Bug 429070 - exposing
2216) Components.interfaces to untrusted content leaks information about installed
2217) extensions</ulink>
2218)      <para>
2219) <ulink url="http://pseudo-flaw.net/">Gregory Fleischer</ulink> demonstrated at Defcon 17 that these interfaces can
2220) also be used to <ulink
2221) url="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html">fingerprint
2222) Firefox down the to the minor version</ulink>. Note that his test has not been
2223) updated since 3.5.3, hence it reports 3.5.3 for more recent Firefoxes. This
2224) bug interferes with Torbutton's ability to satisfy its <link
2225) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2226)      </para>
2227)     </listitem>
2228)    <listitem><ulink
2229) url="https://bugzilla.mozilla.org/show_bug.cgi?id=280661">Bug 280661 - SOCKS proxy server
2230) connection timeout hard-coded</ulink>
2231)     <para>
2232) 
2233) This bug prevents us from using the Firefox SOCKS layer directly, and
2234) currently requires us to ship an auxiliary HTTP proxy called <ulink
2235) url="http://www.pps.jussieu.fr/~jch/software/polipo/">Polipo</ulink>. If this
2236) patch were landed, we would no longer need to ship Polipo, which has a number
2237) of privacy and security issues of its own (in addition to being unmaintained).
2238) 
2239)     </para>
2240)    </listitem>
2241)    <listitem><ulink
2242) url="https://bugzilla.mozilla.org/show_bug.cgi?id=418986">Bug 418986 - window.screen
2243) provides a large amount of identifiable information</ulink>
2244)    <para>
2245) 
2246) As <link linkend="fingerprinting">mentioned above</link>, a large amount of
2247) information is available from <ulink
2248) url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>.

2249) The most sensitive data to anonymity is actually that which is not used in
2250) rendering - such as desktop resolution, and window decoration size.

2251) Currently, there is no way to obscure this information without Javascript

2252) hooking. In addition, many of this same desktop and window decoration
2253) resolution information is available via <ulink
2254) url="https://developer.mozilla.org/En/CSS/Media_queries">CSS Media
2255) Queries</ulink>, so perhaps some more lower-level rendering controls or
2256) preferences need to be provided. These issues interfere with Torbutton's
2257) ability to fulfill its <link linkend="setpreservation">Anonymity Set
2258) Preservation</link> requirement.

2259) 
2260)    </para>
2261)    </listitem>

2262) -->

2263)    <listitem><ulink
2264) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435159">Bug 435159 -
2265) nsNSSCertificateDB::DeleteCertificate has race conditions</ulink>
2266)       <para>
2267) 
2268) In Torbutton 1.2.0rc1, code was added to attempt to isolate SSL certificates
2269) the user has installed. Unfortunately, the method call to delete a certificate
2270) from the current certificate database acts lazily: it only sets a variable
2271) that marks a cert for deletion later, and it is not cleared if that
2272) certificate is re-added. This means that if the Tor state is toggled quickly,
2273) that certificate could remain present until it is re-inserted (causing an
2274) error dialog), and worse, it would still be deleted after that.  The lack of
2275) this functionality is considered a Torbutton security bug because cert
2276) isolation is considered a <link linkend="state">State Separation</link>
2277) feature.
2278) 
2279)       </para>
2280)      </listitem>

2281)      <listitem>Give more visibility into and control over TLS
2282) negotiation
2283)      <para>

2284) 

2285) There are several <ulink
2286) url="https://trac.torproject.org/projects/tor/ticket/2482">TLS issues
2287) impacting Torbutton security</ulink>. It is not clear if these should be one
2288) Firefox bug or several, but in particular we need better control over various
2289) aspects of TLS connections. Firefox currently provides no observer capable of
2290) extracting TLS parameters or certificates early enough to cancel a TLS
2291) request. We would like to be able to provide <ulink
2292) url="https://www.eff.org/https-everywhere">HTTPS-Everywhere</ulink> users with
2293) the ability to <ulink
2294) url="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission">have
2295) their certificates audited</ulink> by a <ulink
2296) url="http://www.networknotary.org/">Perspectives</ulink>-style set of
2297) notaries. The problem with this is that the API observer points do not exist
2298) for any Firefox addon to actually block authentication token submission over a
2299) TLS channel, so every addon to date (including Perspectives) is actually
2300) providing users with notification *after* their authentication tokens have
2301) already been compromised. This obviously needs to be fixed.
2302)      </para>
2303)      </listitem>

2304) <!--
2305) This is under the Tor Browser model.

2306)      <listitem><ulink
2307) url="https://bugzilla.mozilla.org/show_bug.cgi?id=575230">Bug 575230 - Provide option to
2308) reduce precision of Date()</ulink>
2309)       <para>
2310) 
2311) Currently it is possible to <ulink
2312) url="http://arstechnica.com/tech-policy/news/2010/02/firm-uses-typing-cadence-to-finger-unauthorized-users.ars">fingerprint
2313) users based on their typing cadence</ulink> using the high precision timer
2314) available to javascript. Using this same precision, it is possible to compute
2315) an identifier based upon the clock drift of the client from some nominal
2316) source. The latter is not much of a concern for Tor users, as the variable
2317) delay to load and run a page is measured on the order of seconds, but the high
2318) precision timer can still be used to fingerprint aspects of a browser's
2319) javascript engine and processor, and apparently also a user's typing cadence.
2320) This bug hinders Torbutton's ability to satisfy its <link
2321) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2322) 
2323)       </para>
2324)      </listitem>

2325) -->

2326)     <listitem><ulink

2327) url="https://bugzilla.mozilla.org/show_bug.cgi?id=122752">Bug 122752 - SOCKS

2328) Username/Password Support</ulink>
2329)     <para>
2330) We need <ulink url="https://developer.mozilla.org/en/nsIProxyInfo">Firefox
2331) APIs</ulink> or about:config settings to control the SOCKS Username and
2332) Password fields. The reason why we need this support is to utilize an (as yet
2333) unimplemented) scheme to separate Tor traffic based <ulink
2334) url="https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/171-separate-streams.txt">on
2335) SOCKS username/password</ulink>.
2336)     </para>
2337)     </listitem>

2338) 
2339)      <listitem><ulink
2340) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Bug 409737 -
2341) javascript.enabled and docShell.allowJavascript do not disable all event
2342) handlers</ulink>
2343)      <para>
2344) 
2345) This bug allows pages to execute javascript via addEventListener and perhaps
2346) other callbacks. In order to prevent this bug from enabling an attacker to
2347) break the <link linkend="isolation">Network Isolation</link> requirement,
2348) Torbutton 1.1.13 began blocking popups and history manipulation from different
2349) Tor states.  So long as there are no ways to open popups or redirect the user
2350) to a new page, the <link linkend="contentpolicy">Torbutton content
2351) policy</link> should block Javascript network access. However, if there are
2352) ways to open popups or perform redirects such that Torbutton cannot block
2353) them, pages may still have free reign to break that requirement and reveal a
2354) user's original IP address.
2355) 
2356)      </para>
2357)      </listitem>
2358)      <listitem><ulink
2359) url="https://bugzilla.mozilla.org/show_bug.cgi?id=448743">Bug 448743 -
2360) Decouple general.useragent.locale from spoofing of navigator.language</ulink>
2361)      <para>
2362) 
2363) Currently, Torbutton spoofs the <command>navigator.language</command>
2364) attribute via <link linkend="jshooks">Javascript hooks</link>. Unfortunately,
2365) these do not work on Firefox 3. It would be ideal to have
2366) a pref to set this value (something like a
2367) <command>general.useragent.override.locale</command>),
2368) to avoid fragmenting the anonymity set of users of foreign locales. This issue
2369) impedes Torbutton from fully meeting its <link
2370) linkend="setpreservation">Anonymity Set Preservation</link>
2371) requirement on Firefox 3.
2372) 
2373)      </para>
2374)      </listitem>
2375)     </orderedlist>

2376)   </sect3>

2377) <!-- XXX: Need to create a bug for DOM storage APIs at some point -->

2378)   <sect3 id="FirefoxWishlist">

2379)    <title>Bugs blocking functionality</title>
2380)    <para>
2381) The following bugs impact Torbutton and similar extensions' functionality.
2382)    </para>
2383) 
2384)     <orderedlist>
2385) 

2386) <!--

2387)    <listitem><ulink
2388) url="https://bugzilla.mozilla.org/show_bug.cgi?id=445696">Bug 445696 -

2389) Extensions cannot determine if Firefox is full screen</ulink>

2390)    <para>
2391) 
2392) The windowState property of <ulink
2393) url="https://developer.mozilla.org/en/XUL/window">ChromeWindows</ulink> does not accurately reflect the true
2394) state of the window in some cases on Linux. This causes Torbutton to attempt
2395) to resize maximized and minimized windows when it should not.
2396) 
2397)    </para>
2398)    </listitem>

2399) -->

2400)    <listitem><ulink

2401) url="https://bugzilla.mozilla.org/show_bug.cgi?id=629820">Bug 629820 - nsIContentPolicy::shouldLoad not

2402) called for web request in Firefox Mobile</ulink>
2403)     <para>
2404) 
2405) The new <ulink
2406) url="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis">Electrolysis</ulink>
2407) multiprocess system appears to have some pretty rough edge cases with respect
2408) to registering XPCOM category managers such as the nsIContentPolicy, which
2409) make it difficult to do a straight-forward port of Torbutton or
2410) HTTPS-Everywhere to Firefox Mobile.  It probably also has similar issues with
2411) wrapping existing <link linkend="hookedxpcom">Firefox XPCOM components</link>,
2412) which will also cause more problems for porting Torbutton.
2413) 
2414)     </para>
2415)    </listitem>

2416) <!--

2417)    <listitem><ulink

2418) url="https://bugzilla.mozilla.org/show_bug.cgi?id=290456">Bug 290456 -
2419) Block/clear Flash MX "cookies" as well</ulink>
2420)    <para>
2421) 
2422) Today, it is possible to allow plugins if you have a transparent proxy such as
2423) <ulink url="http://anonymityanywhere.com/incognito/">Incognito</ulink> to prevent proxy bypass. However, flash cookies can still be used to
2424) link your Tor and Non-Tor activity, and this reveal your IP to an adversary
2425) that does so. This can be solved by manually removing your flash cookies (like
2426) <ulink
2427) url="https://addons.mozilla.org/en-US/firefox/addon/6623">BetterPrivacy</ulink> does), but
2428) it would be nice if there was a standard way to do this from a Firefox API.
2429) 
2430)    </para>
2431)    </listitem>

2432) -->

2433)    <listitem><ulink
2434) url="https://bugzilla.mozilla.org/show_bug.cgi?id=417869">Bug 417869 -
2435) Browser context is difficult to obtain from many XPCOM callbacks</ulink>
2436)    <para>
2437) 
2438) It is difficult to determine which tabbrowser many XPCOM callbacks originate
2439) from, and in some cases absolutely no context information is provided at all.
2440) While this doesn't have much of an effect on Torbutton, it does make writing
2441) extensions that would like to do per-tab settings and content filters (such as
2442) FoxyProxy) difficult to impossible to implement securely.
2443) 
2444)    </para>
2445)    </listitem>

2446) <!--
2447) FIXME: This doesn't really apply anymore.

2448)    <listitem><ulink
2449) url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
2450) Components do not expose disk interfaces</ulink>
2451)    <para>
2452) 
2453) Several components currently provide no way of reimplementing their disk
2454) access to easily satisfy Torbutton's <link linkend="disk">Disk
2455) Avoidance</link> requirements. Workarounds exist, but they are <link
2456) linkend="sessionstore">clunky</link>, and
2457) some of them involve disabling functionality during Tor usage.
2458) 
2459)    </para>
2460)    </listitem>

2461) -->

2462) 
2463) <!--
2464) FIXME: Need to use new observer methods if possible
2465)    <listitem><ulink
2466) url="https://bugzilla.mozilla.org/show_bug.cgi?id=448741">Bug 448741 -
2467) nsISessionStore uses private methods and is not extensible</ulink>
2468)    <para>
2469) 
2470) Similar to the above bug, in the specific case of the sessionstore component,
2471) the API is not amenable to Contract ID hooking, and this requires that
2472) Torbutton include modified copies of this component for Firefox 2 and 3, which
2473) has <ulink
2474) url="https://bugs.torproject.org/flyspray/index.php?do=details&amp;id=722">raised
2475) objections</ulink> from some developers.
2476) 
2477)    </para>
2478)    </listitem>
2479)    <listitem><ulink
2480) url="https://bugzilla.mozilla.org/show_bug.cgi?id=439384">Bug 439384 -
2481) "profile-do-change" event does not cause cookie table reload</ulink>
2482)    <para>
2483) 
2484) In Firefox 3, the change to the new SQLlite database for cookie storage has a
2485) bug that prevents Torbutton's cookie jaring from working properly. The
2486) "profile-do-change" observer event no longer properly causes either a sync or
2487) reload of the cookie database from disk after it is copied into place.
2488) Torbutton currently works around this by issuing the SQLLite queries manually
2489) to store and rebuild the cookie database.
2490) 
2491)    </para>
2492)    </listitem>
2493) 
2494)    <listitem><ulink
2495) url="https://bugzilla.mozilla.org/show_bug.cgi?id=248970">Bug 248970 (PrivateBrowsing) - Private Browsing mode (global toggle for
2496) saving/caching everything)</ulink>
2497)    <para>
2498) 
2499) This bug catalogs the discussion of a 'Private Mode' in Firefox that would
2500) perform many, but not all, of the activities of Torbutton. It would be useful
2501) to leverage the resulting setting to simplify Torbutton. This bug is listed so
2502) we can track this progress and ensure that it doesn't end up defining
2503) behaviors contrary to and incompatible with Torbutton's requirements (though a
2504) subset of the <link linkend="requirements">requirements</link> is of course fine).
2505) 
2506)    </para>
2507)    </listitem>
2508) -->
2509) 
2510) 
2511) 
2512)   </orderedlist>

2513)   </sect3>
2514)   <sect3 id="FirefoxMiscBugs">

2515)    <title>Low Priority Bugs</title>
2516)    <para>
2517) The following bugs have an effect upon Torbutton, but are superseded by more
2518) practical and more easily fixable variant bugs above; or have stable, simple
2519) workarounds.
2520)   </para>
2521) 
2522)     <orderedlist>

2523) <!--

2524)     <listitem><ulink
2525) url="https://bugzilla.mozilla.org/show_bug.cgi?id=435151">Bug 435151 - XPCSafeJSObjectWrapper breaks evalInSandbox</ulink>
2526)      <para>
2527) 
2528) Under Firefox 3, the XPCSafeJSObjectWrapper breaks when you try to use
2529) constructors of classes defined from within the scope of the sandbox, among
2530) other things. This prevents Torbutton from applying the Timezone hooks under
2531) Firefox 3, but a better solution for Torbutton's specific date hooking needs 
2532) would be a fix for the above mentioned Bug 392274. Of course, many more
2533) extensions may be interested in the sandbox hooking functionality working
2534) properly though.
2535) 
2536)      </para>
2537)      </listitem>

2538) -->

2539)      <listitem><ulink
2540) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">Bug 440892 -
2541) network.protocol-handler.warn-external are ignored</ulink>
2542)      <para>
2543) 
2544) Sometime in the Firefox 3 development cycle, the preferences that governed
2545) warning a user when external apps were launched got disconnected from the code
2546) that does the launching. Torbutton depended on these prefs to prevent websites
2547) from launching specially crafted documents and application arguments that
2548) caused Proxy Bypass. We currently work around this issue by <link
2549) linkend="appblocker">wrapping the app launching components</link> to present a
2550) popup before launching external apps while Tor is enabled. While this works,
2551) it would be nice if these prefs were either fixed or removed.
2552) 
2553)      </para>
2554)      </listitem>
2555)     <listitem><ulink
2556) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">Bug 437014 -
2557) nsIContentPolicy::shouldLoad no longer called for favicons</ulink>
2558)     <para>
2559) 
2560) Firefox 3.0 stopped calling the shouldLoad call of content policy for favicon
2561) loads. Torbutton had relied on this call to block favicon loads for opposite
2562) Tor states. The workaround it employs for Firefox 3 is to cancel the request
2563) when it arrives in the <command>torbutton_http_observer</command> used for
2564) blocking full page plugin loads. This seems to work just fine, but is a bit
2565) dirty.
2566) 
2567)     </para>
2568)     </listitem>
2569) <!--
2570)     <listitem><ulink
2571) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437016">Bug 437016 -
2572) nsIContentPolicy::shouldLoad not called for livemarks</ulink>
2573)     <para>
2574) 
2575) An alternative fix for the livemarks bug above would be to block livemarks
2576) fetches from the content policy. Unfortunately shouldLoad is not called for
2577) livemarks fetches.
2578) 
2579)     </para>
2580)     </listitem>
2581) -->
2582)  
2583)      <listitem><ulink
2584) url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">Bug 309524</ulink>
2585) and <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">Bug
2586) 380556</ulink> - nsIContentPolicy::shouldProcess is not called.
2587)      <para>
2588) 
2589) This is a call that would be useful to develop a better workaround for the
2590) allowPlugins issue above. If the content policy were called before a URL was
2591) handed over to a plugin or helper app, it would make the workaround for the
2592) above allowPlugins bug a lot cleaner. Obviously this bug is not as severe as
2593) the others though, but it might be nice to have this API as a backup.
2594) 
2595)      </para>
2596)      </listitem>
2597) 
2598)      <listitem><ulink
2599) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">Bug 401296 - docShell.allowPlugins
2600) not honored for direct links</ulink> (Perhaps subset of <ulink
2601) url="https://bugzilla.mozilla.org/show_bug.cgi?id=282106">Bug 282106</ulink>?)
2602)      <para>
2603) 
2604) Similar to the javascript plugin disabling attribute, the plugin disabling
2605) attribute is also not perfect &mdash; it is ignored for direct links to plugin
2606) handled content, as well as meta-refreshes to plugin handled content.  This
2607) requires Torbutton to listen to a number of different http events to intercept
2608) plugin-related mime type URLs and cancel their requests. Again, since plugins
2609) are quite horrible about obeying proxy settings, loading a plugin pretty much
2610) ensures a way to break the <link linkend="isolation">Network Isolation</link>
2611) requirement and reveal a user's original IP address. Torbutton's code to
2612) perform this workaround has been subverted at least once already by Kyle
2613) Williams.
2614) 
2615)      </para>
2616)      </listitem>

2617) <!--
2618) Actually, ECMAScript 5 handles this correctly now.

2619)    <listitem><ulink
2620) url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
2621) Date' is deletable</ulink>
2622)      <para>
2623) 
2624) Based on Page 62 of the <ulink
2625) url="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf">ECMA-262
2626) Javascript spec</ulink>, it seems like it should be possible to do something
2627) like the following to prevent the Date object from being unmasked:
2628) <screen>
2629) with(window) {
2630)     var Date = fakeDate;
2631)     var otherVariable = 42;
2632) }
2633) 
2634) delete window.Date; // Should fail. Instead succeeds, revealing original Date.
2635) delete window.otherVariable; // Fails, leaving window.otherVariable set to 42.
2636) </screen>
2637) 
2638) From the ECMA-262 spec:
2639) 
2640) <blockquote>
2641) If the variable statement occurs inside a FunctionDeclaration, the variables
2642) are defined with function-local scope in that function, as described in
2643) s10.1.3. Otherwise, they are defined with global scope (that is, they are
2644) created as members of the global object, as described in 10.1.3) using
2645) property attributes { DontDelete }. Variables are created when the execution
2646) scope is entered. A Block does not define a new execution scope. Only Program
2647) and FunctionDeclaration produce a new scope. Variables are initialized to
2648) undefined when created. A variable with an Initialiser is assigned the value
2649) of its AssignmentExpression when the VariableStatement is executed, not when
2650) the variable is created.
2651) </blockquote>
2652) 
2653) In fact, this is exactly how the with statement with a variable declaration
2654) behaves <emphasis>for all other variables other than ones that shadow system
2655) variables</emphasis>. Some variables (such as
2656) <command>window.screen</command>, and <command>window.history</command>) can't
2657) even be shadowed in this way, and give an error about lacking a setter. If
2658) such shadowing were possible, it would greatly simplify the Javascript hooking
2659) code, which currently relies on undocumented semantics of
2660) <command>__proto__</command> to copy the original values in the event of a
2661) delete. This <command>__proto__</command> hack unfortunately does not work for
2662) the Date object though.
2663) 
2664)      </para>
2665)     </listitem>

2666) -->

2667)   </orderedlist>

2668)   </sect3>
2669)  </sect2>