d0a98d221dbafdd0ecd0f8fcce88d3ab086c47fd
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

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>
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

14)    <pubdate>Apr 10 2010</pubdate>
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

15)  </articleinfo>
16) 
17) <sect1>
18)   <title>Introduction</title>
19)   <para>
20) 
21) This document describes the goals, operation, and testing procedures of the
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

22) Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

23) 
24)   </para>
25)   <sect2 id="adversary">
26)    <title>Adversary Model</title>
27)    <para>
28) 
29) A Tor web browser adversary has a number of goals, capabilities, and attack
30) types that can be used to guide us towards a set of requirements for the
31) Torbutton extension. Let's start with the goals.
32) 
33)    </para>
34)    <sect3 id="adversarygoals">
35)     <title>Adversary Goals</title>
36)     <orderedlist>
37) <!-- These aren't really commands.. But it's the closest I could find in an
38) acceptable style.. Don't really want to make my own stylesheet -->
39)      <listitem><command>Bypassing proxy settings</command>
40)      <para>The adversary's primary goal is direct compromise and bypass of 
41) Tor, causing the user to directly connect to an IP of the adversary's
42) choosing.</para>
43)      </listitem>
44)      <listitem><command>Correlation of Tor vs Non-Tor Activity</command>
45)      <para>If direct proxy bypass is not possible, the adversary will likely
46) happily settle for the ability to correlate something a user did via Tor with
47) their non-Tor activity. This can be done with cookies, cache identifiers,
48) javascript events, and even CSS. Sometimes the fact that a user uses Tor may
49) be enough for some authorities.</para>
50)      </listitem>
51)      <listitem><command>History disclosure</command>
52)      <para>
53) The adversary may also be interested in history disclosure: the ability to
54) query a user's history to see if they have issued certain censored search
55) queries, or visited censored sites.
56)      </para>
57)      </listitem>
58)      <listitem><command>Location information</command>
59)      <para>
60) 
61) Location information such as timezone and locality can be useful for the
62) adversary to determine if a user is in fact originating from one of the
63) regions they are attempting to control, or to zero-in on the geographical
64) location of a particular dissident or whistleblower.
65) 
66)      </para>
67)      </listitem>
68)      <listitem><command>Miscellaneous anonymity set reduction</command>
69)      <para>
70) 
71) Anonymity set reduction is also useful in attempting to zero in on a
72) particular individual. If the dissident or whistleblower is using a rare build
73) of Firefox for an obscure operating system, this can be very useful
74) information for tracking them down, or at least <link
75) linkend="fingerprinting">tracking their activities</link>.
76) 
77)      </para>
78)      </listitem>
79)      <listitem><command>History records and other on-disk
80) information</command>
81)      <para>
82) In some cases, the adversary may opt for a heavy-handed approach, such as
83) seizing the computers of all Tor users in an area (especially after narrowing
84) the field by the above two pieces of information). History records and cache
85) data are the primary goals here.
86)      </para>
87)      </listitem>
88)     </orderedlist>
89)    </sect3>
90) 
91)    <sect3 id="adversarypositioning">
92)     <title>Adversary Capabilities - Positioning</title>
93)     <para>
94) The adversary can position themselves at a number of different locations in
95) order to execute their attacks.
96)     </para>
97)     <orderedlist>
98)      <listitem><command>Exit Node or Upstream Router</command>
99)      <para>
100) The adversary can run exit nodes, or alternatively, they may control routers
101) upstream of exit nodes. Both of these scenarios have been observed in the
102) wild.
103)      </para>
104)      </listitem>
105)      <listitem><command>Adservers and/or Malicious Websites</command>
106)      <para>
107) The adversary can also run websites, or more likely, they can contract out
108) ad space from a number of different adservers and inject content that way. For
109) some users, the adversary may be the adservers themselves. It is not
110) inconceivable that adservers may try to subvert or reduce a user's anonymity 
111) through Tor for marketing purposes.
112)      </para>
113)      </listitem>
114)      <listitem><command>Local Network/ISP/Upstream Router</command>
115)      <para>
116) The adversary can also inject malicious content at the user's upstream router
117) when they have Tor disabled, in an attempt to correlate their Tor and Non-Tor
118) activity.
119)      </para>
120)      </listitem>
121)      <listitem><command>Physical Access</command>
122)      <para>
123) Some users face adversaries with intermittent or constant physical access.
124) Users in Internet cafes, for example, face such a threat. In addition, in
125) countries where simply using tools like Tor is illegal, users may face
126) confiscation of their computer equipment for excessive Tor usage or just
127) general suspicion.
128)      </para>
129)      </listitem>
130)     </orderedlist>
131)    </sect3>
132) 
133)    <sect3 id="attacks">
134)     <title>Adversary Capabilities - Attacks</title>
135)     <para>
136) 
137) The adversary can perform the following attacks from a number of different 
138) positions to accomplish various aspects of their goals. It should be noted
139) that many of these attacks (especially those involving IP address leakage) are
140) often performed by accident by websites that simply have Javascript, dynamic 
141) CSS elements, and plugins. Others are performed by adservers seeking to
142) correlate users' activity across different IP addresses, and still others are
143) performed by malicious agents on the Tor network and at national firewalls.
144) 
145)     </para>
146)     <orderedlist>
147)      <listitem><command>Inserting Javascript</command>
148)      <para>
149) If not properly disabled, Javascript event handlers and timers
150) can cause the browser to perform network activity after Tor has been disabled,
151) thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
152) a user's non-Tor IP address. Javascript
153) also allows the adversary to execute <ulink
154) url="http://whattheinternetknowsaboutyou.com/">history disclosure attacks</ulink>:
155) to query the history via the different attributes of 'visited' links to search
156) for particular google queries, sites, or even to <ulink
157) url="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/">profile
158) users based on gender and other classifications</ulink>. Finally,
159) Javascript can be used to query the user's timezone via the
160) <function>Date()</function> object, and to reduce the anonymity set by querying
161) the <function>navigator</function> object for operating system, CPU, locale, 
162) and user agent information.
163)      </para>
164)      </listitem>
165) 
166)      <listitem><command>Inserting Plugins</command>
167)      <para>
168) 
169) Plugins are abysmal at obeying the proxy settings of the browser. Every plugin
170) capable of performing network activity that the author has
171) investigated is also capable of performing network activity independent of
172) browser proxy settings - and often independent of its own proxy settings.
173) Sites that have plugin content don't even have to be malicious to obtain a
174) user's
175) Non-Tor IP (it usually leaks by itself), though <ulink
176) url="http://decloak.net">plenty of active
177) exploits</ulink> are possible as well. In addition, plugins can be used to store unique identifiers that are more
178) difficult to clear than standard cookies. 
179) <ulink url="http://epic.org/privacy/cookies/flash.html">Flash-based
180) cookies</ulink> fall into this category, but there are likely numerous other
181) examples.
182) 
183)      </para>
184)      </listitem>
185)      <listitem><command>Inserting CSS</command>
186)      <para>
187) 
188) CSS can also be used to correlate Tor and Non-Tor activity and reveal a user's
189) Non-Tor IP address, via the usage of
190) <ulink url="http://www.tjkdesign.com/articles/css%20pop%20ups/">CSS
191) popups</ulink> - essentially CSS-based event handlers that fetch content via
192) CSS's onmouseover attribute. If these popups are allowed to perform network
193) activity in a different Tor state than they were loaded in, they can easily
194) correlate Tor and Non-Tor activity and reveal a user's IP address. In
195) addition, CSS can also be used without Javascript to perform <ulink
196) url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only history disclosure
197) attacks</ulink>.
198)      </para>
199)      </listitem>
200)      <listitem><command>Read and insert cookies</command>
201)      <para>
202) 
203) An adversary in a position to perform MITM content alteration can inject
204) document content elements to both read and inject cookies for
205) arbitrary domains. In fact, many "SSL secured" websites are vulnerable to this
206) sort of <ulink url="http://seclists.org/bugtraq/2007/Aug/0070.html">active
207) sidejacking</ulink>.
208) 
209)      </para>
210)      </listitem>
211)      <listitem><command>Create arbitrary cached content</command>
212)      <para>
213) 
214) Likewise, the browser cache can also be used to <ulink
215) url="http://crypto.stanford.edu/sameorigin/safecachetest.html">store unique
216) identifiers</ulink>. Since by default the cache has no same-origin policy,
217) these identifiers can be read by any domain, making them an ideal target for
218) adserver-class adversaries.
219) 
220)      </para>
221)      </listitem>
222)      <listitem id="fingerprinting"><command>Fingerprint users based on browser
223) attributes</command>
224) <para>
225) 
226) There is an absurd amount of information available to websites via attributes
227) of the browser. This information can be used to reduce anonymity set, or even
228) <ulink url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">uniquely
229) fingerprint individual users</ulink>. </para>
230) <para>
231) For illustration, let's perform a
232) back-of-the-envelope calculation on the number of anonymity sets for just the
233) resolution information available in the <ulink
234) url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
235) <ulink
236) url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>
237) objects. Browser window resolution information provides something like
238) (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
239) information contributes about another factor of 5 (for about 5 resolutions in
240) typical use). In addition, the dimensions and position of the desktop taskbar
241) are available, which can reveal hints on OS information. This boosts the count
242) by a factor of 5 (for each of the major desktop taskbars - Windows, OSX, KDE
243) and Gnome, and None). Subtracting the browser content window
244) size from the browser outer window size provide yet more information.
245) Firefox toolbar presence gives about a factor of 8 (3 toolbars on/off give
246) 2<superscript>3</superscript>=8). Interface effects such as titlebar fontsize
247) and window manager settings gives a factor of about 9 (say 3 common font sizes
248) for the titlebar and 3 common sizes for browser GUI element fonts).
249) Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
250) 2<superscript>29</superscript>, or a 29 bit identifier based on resolution
251) information alone. </para>
252) 
253) <para>
254) 
255) Of course, this space is non-uniform and prone to incremental changes.
256) However, if a bit vector space consisting of the above extracted attributes
257) were used instead of the hash approach from <ulink
258) url="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html">The Hacker
259) Webzine article above</ulink>, minor changes in browser window resolution will
260) no longer generate totally new identifiers. 
261) 
262) </para>
263) <para>
264) 
265) To add insult to injury, <ulink
266) url="http://pseudo-flaw.net/content/tor/torbutton/">chrome URL disclosure
267) attacks</ulink> mean that each and every extension on <ulink
268) url="https://addons.mozilla.org">addons.mozilla.org</ulink> adds another bit
269) to that 2<superscript>29</superscript>. With hundreds of popular extensions
270) and thousands of extensions total, it is easy to see that this sort of
271) information is an impressively powerful identifier if used properly by a
272) competent and determined adversary such as an ad network.  Again, a
273) nearest-neighbor bit vector space approach here would also gracefully handle
274) incremental changes to installed extensions.
275) 
276) </para>
277) 
278)      </listitem>
279)      <listitem><command>Remotely or locally exploit browser and/or
280) OS</command>
281)      <para>
282) Last, but definitely not least, the adversary can exploit either general 
283) browser vulnerabilities, plugin vulnerabilities, or OS vulnerabilities to
284) install malware and surveillance software. An adversary with physical access
285) can perform similar actions. Regrettably, this last attack capability is
286) outside of Torbutton's ability to defend against, but it is worth mentioning
287) for completeness.
288)      </para>
289)      </listitem>
290)     </orderedlist>
291)    </sect3>
292) 
293)   </sect2>
294) 
295)   <sect2 id="requirements">
296)    <title>Torbutton Requirements</title>
297) <note>
298) 
299) Since many settings satisfy multiple requirements, this design document is
300) organized primarily by Torbutton components and settings. However, if you are
301) the type that would rather read the document from the requirements
302) perspective, it is in fact possible to search for each of the following
303) requirement phrases in the text to find the relevant features that help meet
304) that requirement.
305) 
306) </note>
307)    <para>
308) 
309) From the above Adversary Model, a number of requirements become clear. 
310) 
311)    </para>
312) 
313) <orderedlist> 
314) <!-- These aren't really commands.. But it's the closest I could find in an
315) acceptable style.. Don't really want to make my own stylesheet -->
316)  <listitem id="proxy"><command>Proxy Obedience</command> 
317)  <para>The browser
318) MUST NOT bypass Tor proxy settings for any content.</para></listitem>
319)  <listitem id="isolation"><command>Network Isolation</command>
320)  <para>Pages MUST NOT perform any network activity in a Tor state different
321)  from the state they were originally loaded in.</para></listitem>
322)  <listitem id="state"><command>State Separation</command>
323)  <para>Browser state (cookies, cache, history, 'DOM storage'), accumulated in
324)  one Tor state MUST NOT be accessible via the network in
325)  another Tor state.</para></listitem>
326)  <listitem id="undiscoverability"><command>Tor Undiscoverability</command><para>With
327) the advent of bridge support in Tor 0.2.0.x, there are now a class of Tor
328) users whose network fingerprint does not obviously betray the fact that they
329) are using Tor. This should extend to the browser as well - Torbutton MUST NOT 
330) reveal its presence while Tor is disabled.</para></listitem>
331)  <listitem id="disk"><command>Disk Avoidance</command><para>The browser SHOULD NOT write any Tor-related state to disk, or store it
332)  in memory beyond the duration of one Tor toggle.</para></listitem>
333)  <listitem id="location"><command>Location Neutrality</command><para>The browser SHOULD NOT leak location-specific information, such as
334)  timezone or locale via Tor.</para></listitem>
335)  <listitem id="setpreservation"><command>Anonymity Set
336) Preservation</command><para>The browser SHOULD NOT leak any other anonymity set reducing information 
337)  (such as user agent, extension presence, and resolution information)
338) automatically via Tor. The assessment of the attacks above should make it clear
339) that anonymity set reduction is a very powerful method of tracking and
340) eventually identifying anonymous users.
341) </para></listitem>
342)  <listitem id="updates"><command>Update Safety</command><para>The browser
343) SHOULD NOT perform unauthenticated updates or upgrades via Tor.</para></listitem>
344)  <listitem id="interoperate"><command>Interoperability</command><para>Torbutton SHOULD interoperate with third-party proxy switchers that
345)  enable the user to switch between a number of different proxies. It MUST
346)  provide full Tor protection in the event a third-party proxy switcher has
347)  enabled the Tor proxy settings.</para></listitem>
348) </orderedlist>
349)   </sect2>
350)   <sect2 id="layout">
351)    <title>Extension Layout</title>
352) 
353) <para>Firefox extensions consist of two main categories of code: 'Components' and
354) 'Chrome'. Components are a fancy name for classes that implement a given
355) interface or interfaces. In Firefox, components <ulink
356) url="https://developer.mozilla.org/en/XPCOM">can be
357) written</ulink> in C++,
358) Javascript, or a mixture of both. Components have two identifiers: their
359) '<ulink
360) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005005">Contract
361) ID</ulink>' (a human readable path-like string), and their '<ulink
362) url="http://www.mozilla.org/projects/xpcom/book/cxc/html/quicktour2.html#1005329">Class
363) ID</ulink>' (a GUID hex-string). In addition, the interfaces they implement each have a hex
364) 'Interface ID'. It is possible to 'hook' system components - to reimplement
365) their interface members with your own wrappers - but only if the rest of the
366) browser refers to the component by its Contract ID. If the browser refers to
367) the component by Class ID, it bypasses your hooks in that use case.
368) Technically, it may be possible to hook Class IDs by unregistering the
369) original component, and then re-registering your own, but this relies on
370) obsolete and deprecated interfaces and has proved to be less than
371) stable.</para>
372) 
373) <para>'Chrome' is a combination of XML and Javascript used to describe a window.
374) Extensions are allowed to create 'overlays' that are 'bound' to existing XML
375) window definitions, or they can create their own windows. The DTD for this XML
376) is called <ulink
377) url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
378)   </sect2>
379) </sect1>
380) <sect1>
381)   <title>Components</title>
382)   <para>
383) 
384) Torbutton installs components for two purposes: hooking existing components to
385) reimplement their interfaces; and creating new components that provide
386) services to other pieces of the extension.
387) 
388)   </para>
389) 
390)   <sect2>
391)    <title>Hooked Components</title>
392) 
393) <para>Torbutton makes extensive use of Contract ID hooking, and implements some
394) of its own standalone components as well.  Let's discuss the hooked components
395) first.</para>
396) 
397) <sect3 id="sessionstore">
398)  <title><ulink
399) url="http://developer.mozilla.org/en/docs/nsISessionStore">@mozilla.org/browser/sessionstore;1</ulink> -
400) <ulink
401) url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js">components/nsSessionStore36.js</ulink></title>
402) 
403) <para>These components address the <link linkend="disk">Disk Avoidance</link>
404) requirements of Torbutton. As stated in the requirements, Torbutton needs to
405) prevent Tor tabs from being written to disk by the Firefox session store for a
406) number of reasons, primary among them is the fact that Firefox can crash at
407) any time, and a restart can cause you to fetch tabs in the incorrect Tor
408) state.</para>
409) 
410) <para>These components illustrate a complication with Firefox hooking: you can
411) only hook member functions of a class if they are published in an
412) interface that the class implements. Unfortunately, the sessionstore has no
413) published interface that is amenable to disabling the writing out of Tor tabs
414) in specific. As such, Torbutton had to include the <emphasis>entire</emphasis>
415) nsSessionStore from both Firefox 2.0, 3.0, 3.5 and 3.6
416) with a couple of modifications to prevent tabs that were loaded with Tor
417) enabled from being written to disk, and some version detection code to
418) determine which component to load. The <ulink
419) url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff">diff against the original session
420) store</ulink> is included in the git repository.</para>
421) </sect3>
422) <sect3 id="appblocker">
423)  <title><ulink
424) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1">@mozilla.org/uriloader/external-protocol-service;1
425) </ulink>, <ulink
426) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1">@mozilla.org/uriloader/external-helper-app-service;1</ulink>,
427) and <ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1">@mozilla.org/mime;1</ulink>
428) - <ulink
429)   url="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
430)  <para>
431) Due to <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
432) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink> allowing Firefox 3.x to automatically launch some
433) applications without user intervention, Torbutton had to wrap the three
434) components involved in launching external applications to provide user
435) confirmation before doing so while Tor is enabled. Since external applications
436) do not obey proxy settings, they can be manipulated to automatically connect
437) back to arbitrary servers outside of Tor with no user intervention. Fixing
438) this issue helps to satisfy Torbutton's <link linkend="proxy">Proxy
439) Obedience</link> Requirement.
440)  </para>
441) </sect3>
442) <sect3>
443) <title><ulink
444) url="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js">@mozilla.org/browser/sessionstartup;1</ulink> -
445)     <ulink
446) url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink></title>
447) 
448) <para>This component wraps the Firefox Session Startup component that is in
449) charge of <ulink
450) url="http://developer.mozilla.org/en/docs/Session_store_API">restoring saved
451) sessions</ulink>. The wrapper's only job is to intercept the
452) <function>doRestore()</function> function, which is called by Firefox if it is determined that the
453) browser crashed and the session needs to be restored. The wrapper notifies the
454) Torbutton chrome that the browser crashed by setting the pref
455) <command>extensions.torbutton.crashed</command>, or that it is a normal
456) startup via the pref <command>extensions.torbutton.noncrashed</command>. The Torbutton Chrome <ulink
457) url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">listens for a
458) preference change</ulink> for this value and then does the appropriate cleanup. This
459) includes setting the Tor state to the one the user selected for crash recovery
460) in the preferences window (<command>extensions.torbutton.restore_tor</command>), and
461) restoring cookies for the corresponding cookie jar, if it exists.</para>
462) 
463) <para>By performing this notification, this component assists in the 
464) <link linkend="proxy">Proxy Obedience</link>, and <link
465) linkend="isolation">Network Isolation</link> requirements.
466) </para>
467) 
468) 
469) </sect3>
470) <sect3>
471) <title><ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
472) - <ulink
473)   url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
474) 
475) <para>This component was contributed by <ulink
476) url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
477) CSS and Javascript-based methods of history disclosure. The global-history
478) component is what is used by Firefox to determine if a link was visited or not
479) (to apply the appropriate style to the link). By hooking the <ulink
480) url="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29">isVisited</ulink>
481) and <ulink 
482) url="https://developer.mozilla.org/en/nsIGlobalHistory2#addURI.28.29">addURI</ulink>
483) methods, Torbutton is able to selectively prevent history items from being
484) added or being displayed as visited, depending on the Tor state and the user's
485) preferences.
486) </para>
487) <para>
488) This component helps satisfy the <link linkend="state">State Separation</link>
489) and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
490) </para>
491) </sect3>
492) <sect3 id="livemarks">
493) <title><ulink
494) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">@mozilla.org/browser/livemark-service;2</ulink>
495) - <ulink
496)   url="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
497) <para>
498) 
499) The <ulink
500) url="http://www.mozilla.com/en-US/firefox/livebookmarks.html">livemark</ulink> service
501) is started by a timer that runs 5 seconds after Firefox
502) startup. As a result, we cannot simply call the stopUpdateLivemarks() method to
503) disable it. We must wrap the component to prevent this start() call from
504) firing in the event the browser starts in Tor mode.
505) 
506) </para>
507) <para>
508) This component helps satisfy the <link linkend="isolation">Network
509) Isolation</link> and <link linkend="setpreservation">Anonymity Set
510) Preservation</link> requirements.
511) </para>
512) </sect3>
513) </sect2>
514) <sect2>
515) <title>New Components</title>
516) 
517) <para>Torbutton creates four new components that are used throughout the
518) extension. These components do not hook any interfaces, nor are they used
519) anywhere besides Torbutton itself.</para>
520) 
521) <sect3>
522) <title><ulink
523) url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2
524) - components/cookie-jar-selector.js</ulink></title>
525) 
526) <para>The cookie jar selector (also based on code from <ulink
527) url="http://www.collinjackson.com/">Collin
528) Jackson</ulink>) is used by the Torbutton chrome to switch between
529) Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
530) move the current cookies.txt file to the appropriate backup location
531) (cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
532) into place.</para>
533) 
534) <para>
535) This component helps to address the <link linkend="state">State
536) Isolation</link> requirement of Torbutton.
537) </para>
538) 
539) </sect3>
540) <sect3>
541) <title><ulink
542) url="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
543) - components/torbutton-logger.js</ulink></title>
544) 
545) <para>The torbutton logger component allows on-the-fly redirection of torbutton
546) logging messages to either Firefox stderr
547) (<command>extensions.torbutton.logmethod=0</command>), the Javascript error console
548) (<command>extensions.torbutton.logmethod=1</command>), or the DebugLogger extension (if
549) available - <command>extensions.torbutton.logmethod=2</command>). It also allows you to
550) change the loglevel on the fly by changing
551) <command>extensions.torbutton.loglevel</command> (1-5, 1 is most verbose).
552) </para>
553) </sect3>
554) <sect3 id="windowmapper">
555) 
556) <title><ulink
557) url="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
558) - components/window-mapper.js</ulink></title>
559) 
560) <para>Torbutton tags Firefox <ulink
561) url="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes">tabs</ulink> with a special variable that indicates the Tor
562) state the tab was most recently used under to fetch a page. The problem is
563) that for many Firefox events, it is not possible to determine the tab that is
564) actually receiving the event. The Torbutton window mapper allows the Torbutton
565) chrome and other components to look up a <ulink
566) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
567) tab</ulink> for a given <ulink
568) url="https://developer.mozilla.org/en/nsIDOMWindow">HTML content
569) window</ulink>. It does this by traversing all windows and all browsers, until it
570) finds the browser with the requested <ulink
571) url="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow">contentWindow</ulink> element. Since the content policy
572) and page loading in general can generate hundreds of these lookups, this
573) result is cached inside the component.
574) </para>
575) </sect3>
576) <sect3 id="contentpolicy">
577) <title><ulink
578) url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1
579) - components/cssblocker.js</ulink></title>
580) 
581) <para>This is a key component to Torbutton's security measures. When Tor is
582) toggled, Javascript is disabled, and pages are instructed to stop loading.
583) However, CSS is still able to perform network operations by loading styles for
584) onmouseover events and other operations. In addition, favicons can still be
585) loaded by the browser. The cssblocker component prevents this by implementing
586) and registering an <ulink
587) url="https://developer.mozilla.org/en/nsIContentPolicy">nsIContentPolicy</ulink>.
588) When an nsIContentPolicy is registered, Firefox checks every attempted network
589) request against its <ulink
590) url="https://developer.mozilla.org/en/nsIContentPolicy#shouldLoad()">shouldLoad</ulink>
591) member function to determine if the load should proceed. In Torbutton's case,
592) the content policy looks up the appropriate browser tab using the <link
593) linkend="windowmapper">window mapper</link>,
594) and checks that tab's load tag against the current Tor state. If the tab was
595) loaded in a different state than the current state, the fetch is denied.
596) Otherwise, it is allowed.</para> This helps to achieve the <link
597) linkend="isolation">Network
598) Isolation</link> requirements of Torbutton.
599) 
600) <para>In addition, the content policy also blocks website javascript from
601) <ulink url="http://pseudo-flaw.net/content/tor/torbutton/">querying for
602) versions and existence of extension chrome</ulink> while Tor is enabled, and
603) also masks the presence of Torbutton to website javascript while Tor is
604) disabled. </para>
605) 
606) <para>
607) 
608) Finally, some of the work that logically belongs to the content policy is
609) instead handled by the <command>torbutton_http_observer</command> and
610) <command>torbutton_weblistener</command> in <ulink
611) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
612) Firefox 3 favicon loads, popups, and full page plugins, which for whatever
613) reason are not passed to the Firefox content policy itself (see Firefox Bugs 
614) <ulink
615) url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and 
616) <ulink
617) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
618) 
619) </para>
620) 
621) <!-- 
622) FIXME: Hrmm, the content policy doesn't really lend itself well to display 
623) this way.. People looking for this much detail should consult the source.
624) 
625) <para>
626)     <table rowheader="firstcol" frame='all'><title>Access Permissions Table</title>
627)     <tgroup cols='5' align='left' colsep='1' rowsep='1'>
628)        <tbody>
629)        <row>
630)          <entry></entry>
631)          <entry>chrome/resource</entry>
632)          <entry>a3</entry>
633)          <entry>a4</entry>
634)          <entry>a5</entry>
635)        </row>
636)        <row>
637)          <entry>file</entry>
638)          <entry>b2</entry>
639)          <entry>b3</entry>
640)          <entry>b4</entry>
641)          <entry>b5</entry>
642)        </row>
643)        <row>
644)          <entry>c1</entry>
645)          <entry>c2</entry>
646)          <entry>c3</entry>
647)          <entry>c4</entry>
648)          <entry>c5</entry>
649)        </row>
650)        <row>
651)          <entry>d1</entry>
652)          <entry>d2</entry>
653)          <entry>d3</entry>
654)          <entry>d4</entry>
655)          <entry>d5</entry>
656)        </row>
657)        </tbody>
658)        </tgroup>
659)        </table>
660) </para>
661) -->
662) 
663) <para>
664) 
665) This helps to fulfill both the <link
666) linkend="setpreservation">Anonymity Set Preservation</link> and the <link
667) linkend="undiscoverability">Tor Undiscoverability</link> requirements of
668) Torbutton.</para>
669) 
670) </sect3>
671) </sect2>
672) </sect1>
673) <sect1>
674)  <title>Chrome</title>
675) 
676) <para>The chrome is where all the torbutton graphical elements and windows are
677) located. Each window is described as an <ulink
678) url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
679) files attached. The scope of these Javascript files is their containing
680) window.</para>
681) 
682) <sect2 id="browseroverlay">
683) <title>Browser Overlay - <ulink
684) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
685) 
686) <para>The browser overlay, torbutton.xul, defines the toolbar button, the status
687) bar, and events for toggling the button. The overlay code is in <ulink
688) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
689) It contains event handlers for preference update, shutdown, upgrade, and
690) location change events.</para>
691) 
692) <para>The <ulink
693) url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
694) change</ulink> <ulink
695) url="https://developer.mozilla.org/en/nsIWebProgress">webprogress
696) listener</ulink>, <command>torbutton_weblistener</command> is one of the most
697) important parts of the chrome from a security standpoint. It is a <ulink
698) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
699) listener</ulink> that handles receiving an event every time a page load or
700) iframe load occurs. This class eventually calls down to
701) <function>torbutton_update_tags()</function> and
702) <function>torbutton_hookdoc()</function>, which apply the browser Tor load
703) state tags, plugin permissions, and install the Javascript hooks to hook the
704) <ulink
705) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
706) object to obfuscate browser and desktop resolution information.
707) 
708) </para>
709) 
710) <para>
711) The browser overlay helps to satisfy a number of Torbutton requirements. These
712) are better enumerated in each of the Torbutton preferences below. However,
713) there are also a number of Firefox preferences set in
714) <function>torbutton_update_status()</function> that aren't governed by any
715) Torbutton setting. These are:
716) </para>
717) <orderedlist>
718) 
719) <!--
720) Not set any more.
721)  <listitem><ulink
722) url="http://kb.mozillazine.org/Browser.bookmarks.livemark_refresh_seconds">browser.bookmarks.livemark_refresh_seconds</ulink>
723) <para>
724) This pref is set in an attempt to disable the fetching of LiveBookmarks via
725) Tor. Since users can potentially collect a large amount of live bookmarks to
726) very personal sites (blogs of friends, wikipedia articles they maintain,
727) comment feeds of their own blog), it is not possible to cleanly isolate these
728) fetches and they are simply disabled during Tor usage.
729) This helps to address the <link
730) linkend="state">State Separation</link> requirement.
731) Unfortunately <ulink
732) url="https://bugzilla.mozilla.org/show_bug.cgi?id=436250">Firefox Bug
733) 436250</ulink> prevents this from
734) functioning completely correctly.
735) </para>
736)   </listitem>
737) -->
738) 
739)  <listitem><ulink
740) url="http://kb.mozillazine.org/Network.security.ports.banned">network.security.ports.banned</ulink>
741)  <para>
742) Torbutton sets this setting to add ports 8123, 8118, 9050 and 9051 (which it
743) reads from <command>extensions.torbutton.banned_ports</command>) to the list
744) of ports Firefox is forbidden to access. These ports are Polipo, Privoxy, Tor,
745) and the Tor control port, respectively. This is set for both Tor and Non-Tor
746) usage, and prevents websites from attempting to do http fetches from these
747) ports to see if they are open, which addresses the <link
748) linkend="undiscoverability">Tor Undiscoverability</link> requirement.
749)  </para>
750)  </listitem>
751)  <listitem><ulink url="http://kb.mozillazine.org/Browser.send_pings">browser.send_pings</ulink>
752)  <para>
753) This setting is currently always disabled. If anyone ever complains saying
754) that they *want* their browser to be able to send ping notifications to a
755) page or arbitrary link, I'll make this a pref or Tor-only. But I'm not holding
756) my breath. I haven't checked if the content policy is called for pings, but if
757) not, this setting helps with meeting the <link linkend="isolation">Network
758) Isolation</link> requirement.
759)  </para>
760)  </listitem>
761)  <listitem><ulink
762) url="http://kb.mozillazine.org/Browser.safebrowsing.remoteLookups">browser.safebrowsing.remoteLookups</ulink>
763)  <para>
764) Likewise for this setting. I find it hard to imagine anyone who wants to ask
765) Google in real time if each URL they visit is safe, especially when the list
766) of unsafe URLs is downloaded anyway. This helps fulfill the <link
767) linkend="disk">Disk Avoidance</link> requirement, by preventing your entire
768) browsing history from ending up on Google's disks.
769)  </para>
770)  </listitem>
771)  <listitem><ulink
772) url="http://kb.mozillazine.org/Browser.safebrowsing.enabled">browser.safebrowsing.enabled</ulink>
773)  <para>
774) Safebrowsing does <ulink
775) url="https://bugzilla.mozilla.org/show_bug.cgi?id=360387">unauthenticated
776) updates under Firefox 2</ulink>, so it is disabled during Tor usage. 
777) This helps fulfill the <link linkend="updates">Update
778) Safety</link> requirement. Firefox 3 has the fix for that bug, and so
779) safebrowsing updates are enabled during Tor usage.
780)  </para>
781)  </listitem>
782)  <listitem><ulink
783) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
784)  <para>
785) If Tor is enabled, we need to prevent random external applications from
786) launching without at least warning the user. This group of settings only
787) partially accomplishes this, however. Applications can still be launched via
788) plugins. The mechanisms for handling this are described under the "Disable
789) Plugins During Tor Usage" preference. This helps fulfill the <link
790) linkend="proxy">Proxy Obedience</link> requirement, by preventing external
791) applications from accessing network resources at the command of Tor-fetched
792) pages. Unfortunately, due to <link linkend="FirefoxBugs">Firefox Bug</link>
793) <ulink
794) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink>,
795) these prefs are no longer obeyed. They are set still anyway out of respect for
796) the dead.
797)  </para>
798) </listitem>
799)   <listitem><ulink
800) url="http://kb.mozillazine.org/Browser.sessionstore.max_tabs_undo">browser.sessionstore.max_tabs_undo</ulink>
801)    <para>
802) 
803) To help satisfy the Torbutton <link linkend="state">State Separation</link>
804) and <link linkend="isolation">Network Isolation</link> requirements,
805) Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
806) "Undo Close" operations from accidentally restoring tabs from a different Tor
807) State. This purge is accomplished by setting this preference to 0 and then
808) restoring it to the previous user value upon toggle.
809) 
810)    </para>
811)   </listitem>
812) 
813)   <listitem><command>security.enable_ssl2</command>
814)    <para>
815) TLS Session IDs can persist for an indefinite duration, providing an
816) identifier that is sent to TLS sites that can be used to link activity. This
817) is particularly troublesome now that we have certificate verification in place
818) in Firefox 3: The OCSP server can use this Session ID to build a history of
819) TLS sites someone visits, and also correlate their activity as users move from
820) network to network (such as home to work to coffee shop, etc), inside and
821) outside of Tor. To handle this and to help satisfy our <link
822) linkend="state">State Separation Requirement</link>, we currently 
823) toggle
824) <command>security.enable_ssl2</command>, which clears the SSL Session ID
825) cache via the pref observer at <ulink
826) url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
827) line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
828) better if there were a more standard interface for accomplishing the same
829) thing. <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
830) url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">448747</ulink> has
831) been filed for this.
832) 
833)    </para>
834)   </listitem>
835) 
836)   <listitem><command><ulink url="http://www.mozilla.com/en-US/firefox/geolocation/">geo.enabled</ulink></command>
837)    <para>
838) 
839) Torbutton disables Geolocation support in Firefox 3.5 and above whenever tor
840) is enabled. This helps Torbutton maintain its
841) <link linkend="location">Location Neutrality</link> requirement.
842) While Firefox does prompt before divulging geolocational information,
843) the assumption is that Tor users will never want to give their
844) location away during Tor usage, and even allowing websites to prompt
845) them to do so will only cause confusion and accidents to happen. Moreover,
846) just because users may approve a site to know their location in non-Tor mode
847) does not mean they want it divulged during Tor mode.
848) 
849)    </para>
850)   </listitem>
851) 
852)   <listitem><command><ulink
853) url="http://kb.mozillazine.org/Browser.zoom.siteSpecific">browser.zoom.siteSpecific</ulink></command>
854)    <para>
855) 
856) Firefox actually remembers your zoom settings for certain sites. CSS
857) and Javascript rule can use this to recognize previous visitors to a site.
858) This helps Torbutton fulfill its <link linkend="state">State Separation</link>
859) requirement.
860) 
861)    </para>
862)   </listitem>
863) 
864)   <listitem><command><ulink
865) url="https://developer.mozilla.org/en/controlling_dns_prefetching">network.dns.disablePrefetch</ulink></command>
866)    <para>
867) 
868) Firefox 3.5 and above implement prefetching of DNS resolution for hostnames in
869) links on a page to decrease page load latency. While Firefox does typically
870) disable this behavior when proxies are enabled, we set this pref for added
871) safety during Tor usage. Additionally, to prevent Tor-loaded tabs from having
872) their links prefetched after a toggle to Non-Tor mode occurs,
873) we also set the docShell attribute
874) <ulink
875) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIDocShell">
876) allowDNSPrefetch</ulink> to false on Tor loaded tabs. This happens in the same
877) positions in the code as those for disabling plugins via the allowPlugins
878) docShell attribute. This helps Torbutton fulfill its <link
879) linkend="isolation">Network Isolation</link> requirement.
880) 
881)    </para>
882)   </listitem>
883) 
884)   <listitem><command><ulink
885) url="http://kb.mozillazine.org/Browser.cache.offline.enable">browser.cache.offline.enable</ulink></command>
886)    <para>
887) 
888) Firefox has the ability to store web applications in a special cache to allow
889) them to continue to operate while the user is offline. Since this subsystem
890) is actually different than the normal disk cache, it must be dealt with
891) separately. Thus, Torbutton sets this preference to false whenever Tor is
892) enabled. This helps Torbutton fulfill its <link linkend="disk">Disk
893) Avoidance</link> and <link linkend="state">State Separation</link>
894) requirements.
895) 
896)    </para>
897)   </listitem>
898) 
899) <!-- FIXME: We should make it possible to search for ALL modified FF prefs -->
900) 
901) </orderedlist>
902) </sect2>
903) <sect2>
904)  <title>Preferences Window - <ulink
905) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
906) 
907) <para>The preferences window of course lays out the Torbutton preferences, with
908) handlers located in <ulink
909) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
910) </sect2>
911) <sect2>
912)  <title>Other Windows</title>
913) 
914) <para>There are additional windows that describe popups for right clicking on
915) the status bar, the toolbutton, and the about page.</para>
916) 
917) </sect2>
918) </sect1>
919) 
920) <sect1>
921)  <title>Toggle Code Path</title>
922)  <para>
923) 
924) The act of toggling is connected to <function>torbutton_toggle()</function>
925) via the <ulink
926) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
927) and <ulink
928) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul">popup.xul</ulink>
929) overlay files. Most of the work in the toggling process is present in <ulink
930) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink> 
931) 
932) </para>
933) <para>
934) 
935) Toggling is a 3 stage process: Button Click, Proxy Update, and
936) Settings Update. These stages are reflected in the prefs
937) <command>extensions.torbutton.tor_enabled</command>,
938) <command>extensions.torbutton.proxies_applied</command>, and
939) <command>extensions.torbutton.settings_applied</command>. The reason for the
940) three stage preference update is to ensure immediate enforcement of <link
941) linkend="isolation">Network Isolation</link> via the <link
942) linkend="contentpolicy">content policy</link>. Since the content window
943) javascript runs on a different thread than the chrome javascript, it is
944) important to properly convey the stages to the content policy to avoid race
945) conditions and leakage, especially with <ulink
946) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
947) 409737</ulink> unfixed. The content policy does not allow any network activity
948) whatsoever during this three stage transition.
949) 
950)  </para>
951)  <sect2>
952)   <title>Button Click</title>
953)   <para>
954) 
955) This is the first step in the toggling process. When the user clicks the
956) toggle button or the toolbar, <function>torbutton_toggle()</function> is
957) called. This function checks the current Tor status by comparing the current
958) proxy settings to the selected Tor settings, and then sets the proxy settings
959) to the opposite state, and sets the pref
960) <command>extensions.torbutton.tor_enabled</command> to reflect the new state.
961) It is this proxy pref update that gives notification via the <ulink
962) url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
963) observer</ulink>
964) <command>torbutton_unique_pref_observer</command> to perform the rest of the
965) toggle.
966) 
967)   </para>
968)  </sect2>
969)  <sect2>
970)   <title>Proxy Update</title>
971)   <para>
972) 
973) When Torbutton receives any proxy change notifications via its
974) <command>torbutton_unique_pref_observer</command>, it calls
975) <function>torbutton_set_status()</function> which checks against the Tor
976) settings to see if the Tor proxy settings match the current settings. If so,
977) it calls <function>torbutton_update_status()</function>, which determines if
978) the Tor state has actually changed, and sets
979) <command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
980) state value, and ensures that
981) <command>extensions.torbutton.tor_enabled</command> is also set to the correct
982) value. This is decoupled from the button click functionalty via the pref
983) observer so that other addons (such as SwitchProxy) can switch the proxy
984) settings between multiple proxies.
985) 
986)   </para>
987)  </sect2>
988)  <sect2>
989)   <title>Settings Update</title>
990)   <para>
991) 
992) The next stage is also handled by
993) <function>torbutton_update_status()</function>. This function sets scores of
994) Firefox preferences, saving the original values to prefs under
995) <command>extensions.torbutton.saved.*</command>, and performs the history
996) clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
997) end of its work, it sets
998) <command>extensions.torbutton.settings_applied</command>, which signifies the
999) completion of the toggle operation to the <link
1000) linkend="contentpolicy">content policy</link>.
1001) 
1002)   </para>
1003)  </sect2>
1004) </sect1>
1005) 
1006) <sect1>
1007)  <title>Description of Options</title>
1008) <!-- FIXME: Review+update these during FF3.5 audit -->
1009) <para>This section provides a detailed description of Torbutton's options. Each
1010) option is presented as the string from the preferences window, a summary, the
1011) preferences it touches, and the effect this has on the components, chrome, and
1012) browser properties.</para>
1013)  <sect2>
1014)   <title>Test Settings</title>
1015)   <para>
1016) This button under the Proxy Settings tab provides a way to verify that the 
1017) proxy settings are correct, and actually do route through the Tor network. It
1018) performs this check by issuing an <ulink
1019) url="http://developer.mozilla.org/en/docs/XMLHttpRequest">XMLHTTPRequest</ulink>
1020) for <ulink
1021) url="https://check.torproject.org/?TorButton=True">https://check.torproject.org/?Torbutton=True</ulink>.
1022) This is a special page that returns very simple, yet well-formed XHTML that
1023) Torbutton can easily inspect for a hidden link with an id of
1024) <command>TorCheckResult</command> and a target of <command>success</command>
1025) or <command>failure</command> to indicate if the
1026) user hit the page from a Tor IP, a non-Tor IP. This check is handled in
1027) <function>torbutton_test_settings()</function> in <ulink
1028) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>.
1029) Presenting the results to the user is handled by the <ulink
1030) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul">preferences
1031) window</ulink>
1032) callback <function>torbutton_prefs_test_settings()</function> in <ulink
1033) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js">preferences.js</ulink>.  
1034) 
1035)   </para>
1036)  </sect2>
1037)  <sect2 id="plugins">
1038)   <title>Disable plugins on Tor Usage (crucial)</title>
1039)  <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
1040) 
1041)  <para>Java and plugins <ulink
1042) url="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html">can query</ulink> the <ulink
1043) url="http://www.rgagnon.com/javadetails/java-0095.html">local IP
1044) address</ulink> and report it back to the
1045) remote site. They can also <ulink
1046) url="http://decloak.net">bypass proxy settings</ulink> and directly connect to a
1047) remote site without Tor. Every browser plugin we have tested with Firefox has
1048) some form of network capability, and every one ignores proxy settings or worse - only
1049) partially obeys them. This includes but is not limited to:
1050) QuickTime, Windows Media Player, RealPlayer, mplayerplug-in, AcroRead, and
1051) Flash. 
1052) 
1053)  </para>
1054)  <para>
1055) Enabling this preference causes the above mentioned Torbutton chrome web progress
1056)  listener <command>torbutton_weblistener</command> to disable Java via <command>security.enable_java</command> and to disable
1057)  plugins via the browser <ulink
1058)  url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink>
1059)  attribute <command>allowPlugins</command>. These flags are set every time a new window is
1060)  created (<function>torbutton_tag_new_browser()</function>), every time a web
1061) load
1062) event occurs
1063)  (<function>torbutton_update_tags()</function>), and every time the tor state is changed
1064)  (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
1065)  prevented from loading by the content policy in <ulink
1066) url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
1067)  enabled and this option is set.
1068)  </para>
1069) 
1070)  <para>All of this turns out to be insufficient if the user directly clicks
1071) on a plugin-handled mime-type. <ulink
1072) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">In this case</ulink>,
1073) the browser decides that maybe it should ignore all these other settings and
1074) load the plugin anyways, because maybe the user really did want to load it
1075) (never mind this same load-style could happen automatically  with meta-refresh
1076) or any number of other ways..). To handle these cases, Torbutton stores a list
1077) of plugin-handled mime-types, and sets the pref
1078) <command>plugin.disable_full_page_plugin_for_types</command> to this list.
1079) Additionally, (since nothing can be assumed when relying on Firefox
1080) preferences and internals) if it detects a load of one of them from the web
1081) progress listener, it cancels the request, tells the associated DOMWindow to
1082) stop loading, clears the document, AND throws an exception. Anything short of
1083) all this and the plugin managed to find some way to load.
1084)  </para>
1085) 
1086) <!--
1087) 
1088) FIXME: Hrmm, technically this behavior is not covered by this pref.
1089) 
1090)  <para>
1091) Furthermore, with version 3.0 and above, Firefox
1092) <ulink
1093) url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">began ignoring</ulink>
1094) 
1095) <ulink
1096) url="http://kb.mozillazine.org/Network.protocol-handler.warn-external.%28protocol%29">network.protocol-handler.warn-external.(protocol)</ulink>
1097) prefs, which caused us to have to <link linkend="appblocker">wrap the external
1098) app launcher components</link> to prevent external apps from being loaded to
1099) bypass proxy settings.
1100)  </para>
1101) -->
1102) 
1103)  <para>
1104)  All this could be avoided, of course, if Firefox would either <ulink
1105) url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">obey
1106)  allowPlugins</ulink> for directly visited URLs, or notify its content policy for such
1107)  loads either <ulink
1108) url="https://bugzilla.mozilla.org/show_bug.cgi?id=309524">via</ulink> <ulink
1109) url="https://bugzilla.mozilla.org/show_bug.cgi?id=380556">shouldProcess</ulink> or shouldLoad. The fact that it does not is
1110)  not very encouraging.
1111)  </para>
1112) 
1113) 
1114)  <para>
1115) 
1116) Since most plugins completely ignore browser proxy settings, the actions
1117) performed by this setting are crucial to satisfying the <link
1118) linkend="proxy">Proxy Obedience</link> requirement.
1119) 
1120)  </para>
1121) </sect2>
1122) <sect2>
1123)  <title>Isolate Dynamic Content to Tor State (crucial)</title>
1124) 
1125)  <para>Option: <command>extensions.torbutton.isolate_content</command></para>
1126) 
1127) <para>Enabling this preference is what enables the <ulink
1128) url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
1129) mentioned above, and causes it to block content load attempts in pages an
1130) opposite Tor state from the current state. Freshly loaded <ulink
1131) url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
1132) tabs</ulink> are tagged
1133) with a <command>__tb_load_state</command> member in
1134) <function>torbutton_update_tags()</function> and this
1135) value is compared against the current tor state in the content policy.</para>
1136) 
1137) <para>It also kills all Javascript in each page loaded under that state by
1138) toggling the <command>allowJavascript</command> <ulink
1139) url="https://developer.mozilla.org/en/XUL%3aProperty%3adocShell">docShell</ulink> property, and issues a
1140) <ulink
1141) url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIWebNavigation#stop()">webNavigation.stop(webNavigation.STOP_ALL)</ulink> to each browser tab (the
1142) equivalent of hitting the STOP button).</para>
1143) 
1144) <para>
1145) 
1146) Unfortunately, <ulink
1147) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox bug
1148) 409737</ulink> prevents <command>docShell.allowJavascript</command> from killing
1149) all event handlers, and event handlers registered with <ulink
1150) url="http://developer.mozilla.org/en/docs/DOM:element.addEventListener">addEventListener()</ulink>
1151) are still able to execute. The <link linkend="contentpolicy">Torbutton Content
1152) Policy</link> should prevent such code from performing network activity within
1153) the current tab, but activity that happens via a popup window or via a
1154) Javascript redirect can still slip by. For this reason, Torbutton blocks
1155) popups by checking for a valid <ulink
1156) url="http://developer.mozilla.org/en/docs/DOM:window.opener">window.opener</ulink>
1157) attribute in <function>torbutton_check_progress()</function>. If the window
1158) has an opener from a different Tor state, its load is blocked. The content
1159) policy also takes similar action to prevent Javascript redirects. This also
1160) has the side effect/feature of preventing the user from following any links
1161) from a page loaded in an opposite Tor state.
1162) 
1163) </para>
1164) 
1165) <para>
1166) This setting is responsible for satisfying the <link
1167) linkend="isolation">Network Isolation</link> requirement.
1168) </para>
1169) 
1170) </sect2>
1171) <sect2 id="jshooks">
1172) 
1173) <title>Hook Dangerous Javascript</title>
1174) 
1175)  <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
1176) 
1177) <para>This setting enables injection of the <ulink
1178) url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js">Javascript
1179) hooking code</ulink>. This is done in the chrome in
1180) <function>torbutton_hookdoc()</function>, which is called ultimately by both the 
1181) <ulink
1182) url="https://developer.mozilla.org/en/nsIWebProgressListener">webprogress
1183) listener</ulink> <command>torbutton_weblistener</command> and the <link
1184) linkend="contentpolicy">content policy</link> (the latter being a hack to handle
1185) javascript: urls).
1186) 
1187) In the Firefox 2 days, this option did a lot more than
1188) it does now. It used to be responsible for timezone and improved useragent
1189) spoofing, and history object cloaking. However, now it only provides
1190) obfuscation of the <ulink
1191) url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
1192) object to mask your browser and desktop resolution.
1193) The resolution hooks
1194) effectively make the Firefox browser window appear to websites as if the renderable area
1195) takes up the entire desktop, has no toolbar or other GUI element space, and
1196) the desktop itself has no toolbars.
1197) These hooks drastically reduce the amount of information available to do <link
1198) linkend="fingerprinting">anonymity set reduction attacks</link> and help to
1199) meet the <link linkend="setpreservation">Anonymity Set Preservation</link>
1200) requirements. Unfortunately, Gregory Fleischer discovered it is still possible
1201) to retrieve the original screen values by using <ulink
1202) url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
1203) or <ulink
1204) url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

1205) We are still looking for a workaround as of Torbutton 1.2.5.
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

1206) 
1207) <!-- FIXME: Don't forget to update this -->
1208) 
1209) </para>
1210) </sect2>
1211) <sect2>
1212) <title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
1213) 
1214)  <para>Option: <command>extensions.torbutton.resize_windows</command></para>
1215) 
1216) <para>
1217) 
1218) This option drastically cuts down on the number of distinct anonymity sets
1219) that divide the Tor web userbase. Without this setting, the dimensions for a
1220) typical browser window range from 600-1200 horizontal pixels and 400-1000
1221) vertical pixels, or about 600x600 = 360000 different sets. Resizing the
1222) browser window to multiples of 50 on each side reduces the number of sets by
1223) 50^2, bringing the total number of sets to 144. Of course, the distribution
1224) among these sets are not uniform, but scaling by 50 will improve the situation
1225) due to this non-uniformity for users in the less common resolutions.
1226) Obviously the ideal situation would be to lie entirely about the browser
1227) window size, but this will likely cause all sorts of rendering issues, and is
1228) also not implementable in a foolproof way from extension land.
1229) 
1230) </para>
1231) <para>
1232) 
1233) The implementation of this setting is spread across a couple of different
1234) locations in the Torbutton javascript <link linkend="browseroverlay">browser
1235) overlay</link>. Since resizing minimized windows causes them to be restored,
1236) and since maximized windows remember their previous size to the pixel, windows
1237) must be resized before every document load (at the time of browser tagging)
1238) via <function>torbutton_check_round()</function>, called by
1239) <function>torbutton_update_tags()</function>. To prevent drift, the extension
1240) tracks the original values of the windows and uses this to perform the
1241) rounding on document load. In addition, to prevent the user from resizing a
1242) window to a non-50px multiple, a resize listener
1243) (<function>torbutton_do_resize()</function>) is installed on every new browser
1244) window to record the new size and round it to a 50px multiple while Tor is
1245) enabled. In all cases, the browser's contentWindow.innerWidth and innerHeight
1246) are set. This ensures that there is no discrepancy between the 50 pixel cutoff
1247) and the actual renderable area of the browser (so that it is not possible to
1248) infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
1249) 
1250) </para>
1251) <para>
1252) This setting helps to meet the <link
1253) linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1254) </para>
1255) </sect2>
1256) <sect2>
1257) <title>Disable Updates During Tor</title>
1258) 
1259)   <para>Option: <command>extensions.torbutton.no_updates</command></para>
1260) 
1261)   <para>This setting causes Torbutton to disable the four <ulink
1262) url="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State">Firefox
1263) update settings</ulink> during Tor
1264)   usage: <command>extensions.update.enabled</command>,
1265) <command>app.update.enabled</command>,
1266)   <command>app.update.auto</command>, and
1267) <command>browser.search.update</command>.  These prevent the
1268)   browser from updating extensions, checking for Firefox upgrades, and
1269)   checking for search plugin updates while Tor is enabled.
1270)   </para>
1271) <para>
1272) This setting satisfies the <link
1273) linkend="updates">Update Safety</link> requirement.
1274) </para>
1275) </sect2>
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

1276) <sect2>
1277) <title>Redirect Torbutton Updates Via Tor (recommended)</title>
1278) 
1279)   <para>Option: <command>extensions.torbutton.update_torbutton_via_tor</command></para>
1280) 
1281)   <para>This setting causes Torbutton to install an
1282) 
1283) <ulink
1284) url="https://developer.mozilla.org/en/nsIProtocolProxyFilter">nsIProtocolProxyFilter</ulink>
1285) in order to redirect all version update checks and Torbutton update downloads
1286) via Tor, regardless of if Tor is enabled or not. This was done both to address
1287) concerns about data retention done by <ulink
1288) url="https://www.addons.mozilla.org">addons.mozilla.org</ulink>, as well as to
1289) help censored users meet the <link linkend="undiscoverability">Tor
1290) Undiscoverability</link> requirement.
1291) 
1292)   </para>
1293) </sect2>
1294) 
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

1295) <sect2>
1296) 
1297) <title>Disable Search Suggestions during Tor (recommended)</title>
1298) 
1299)   <para>Option: <command>extensions.torbutton.no_search</command></para>
1300) 
1301) <para>
1302) This setting causes Torbutton to disable <ulink
1303) url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1304) during Tor usage.
1305) This governs if you get Google search suggestions during Tor
1306) usage. Your Google cookie is transmitted with google search suggestions, hence
1307) this is recommended to be disabled.
1308) 
1309) </para>
1310) <para>
1311) While this setting doesn't satisfy any Torbutton requirements, the fact that
1312) cookies are transmitted for partially typed queries does not seem desirable
1313) for Tor usage.
1314) </para>
1315) </sect2>
1316) <sect2>
1317) <title>Disable livemarks updates during Tor usage (recommended)</title>
1318)   <para>Option:
1319)    <simplelist>
1320)    <member><command>extensions.torbutton.disable_livemarks</command></member>
1321)    </simplelist>
1322)   </para>
1323) 
1324) <para>
1325) This option causes Torbutton to prevent Firefox from loading <ulink
1326) url="http://www.mozilla.com/firefox/livebookmarks.html">Livemarks</ulink> during
1327) Tor usage. Because people often have very personalized Livemarks (such as RSS
1328) feeds of Wikipedia articles they maintain, etc). This is accomplished both by
1329) <link linkend="livemarks">wrapping the livemark-service component</link> and
1330) by calling stopUpdateLivemarks() on the <ulink
1331) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2">Livemark
1332) service</ulink> when Tor is enabled.
1333) 
1334) </para>
1335) 
1336) <para>
1337) This helps satisfy the <link linkend="isolation">Network
1338) Isolation</link> and <link linkend="setpreservation">Anonymity Set
1339) Preservation</link> requirements.
1340) </para>
1341) 
1342) </sect2>
1343) <sect2>
1344) <title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1345)   <para>Options:
1346)    <simplelist>
1347)    <member><command>extensions.torbutton.block_tor_file_net</command></member>
1348)    <member><command>extensions.torbutton.block_nontor_file_net</command></member>
1349)    </simplelist>
1350)   </para>
1351) 
1352) <para>
1353) 
1354) These settings prevent file urls from performing network operations during the
1355) respective Tor states. Firefox 2's implementation of same origin policy allows
1356) file urls to read and <ulink
1357) url="http://www.gnucitizen.org/blog/content-disposition-hacking/">submit
1358) arbitrary files from the local filesystem</ulink> to arbitrary websites. To
1359) make matters worse, the 'Content-Disposition' header can be injected
1360) arbitrarily by exit nodes to trick users into running arbitrary html files in
1361) the local context. These preferences cause the <link
1362) linkend="contentpolicy">content policy</link> to block access to any network
1363) resources from File urls during the appropriate Tor state.
1364) 
1365) </para>
1366) <para>
1367) 
1368) This preference helps to ensure Tor's <link linkend="isolation">Network
1369) Isolation</link> requirement, by preventing file urls from executing network
1370) operations in opposite Tor states. Also, allowing pages to submit arbitrary
1371) files to arbitrary sites just generally seems like a bad idea.
1372) 
1373) </para>
1374) </sect2>
1375) <sect2>
1376) 
1377) <title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1378) 
1379)   <para>Options:
1380)    <simplelist>
1381)    <member><command>extensions.torbutton.close_nontor</command></member>
1382)    <member><command>extensions.torbutton.close_tor</command></member>
1383)    </simplelist>
1384)   </para>
1385) 
1386) <para>
1387) 
1388) These settings cause Torbutton to enumerate through all windows and close all
1389) tabs in each window for the appropriate Tor state. This code can be found in
1390) <function>torbutton_update_status()</function>.  The main reason these settings
1391) exist is as a backup mechanism in the event of any Javascript or content policy
1392) leaks due to <ulink
1393) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1394) 409737</ulink>.  Torbutton currently tries to block all Javascript network
1395) activity via the content policy, but until that bug is fixed, there is some
1396) risk that there are alternate ways to bypass the policy. This option is
1397) available as an extra assurance of <link linkend="isolation">Network
1398) Isolation</link> for those who would like to be sure that when Tor is toggled
1399) all page activity has ceased. It also serves as a potential future workaround
1400) in the event a content policy failure is discovered, and provides an additional
1401) level of protection for the <link linkend="disk">Disk Avoidance</link>
1402) protection so that browser state is not sitting around waiting to be swapped
1403) out longer than necessary.
1404) 
1405) </para>
1406) <para>
1407) While this setting doesn't satisfy any Torbutton requirements, the fact that
1408) cookies are transmitted for partially typed queries does not seem desirable
1409) for Tor usage.
1410) </para>
1411) </sect2>
1412) 
1413) <sect2>
1414) <title>Isolate Access to History navigation to Tor state (crucial)</title>
1415)   <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1416)   <para>
1417) This setting determines if Torbutton installs an <ulink
1418) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener">nsISHistoryListener</ulink>
1419) attached to the <ulink
1420) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">sessionHistory</ulink> of 
1421) of each browser's <ulink
1422) url="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation">webNavigatator</ulink>.
1423) The nsIShistoryListener is instantiated with a reference to the containing
1424) browser window and blocks the back, forward, and reload buttons on the browser
1425) navigation bar when Tor is in an opposite state than the one to load the
1426) current tab. In addition, Tor clears the session history during a new document
1427) load if this setting is enabled. 
1428) 
1429)   </para>
1430)   <para>
1431) 
1432) This is marked as a crucial setting in part
1433) because Javascript access to the history object is indistinguishable from 
1434) user clicks, and because
1435) <ulink
1436) url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug
1437) 409737</ulink> allows javascript to execute in opposite Tor states, javascript
1438) can issue reloads after Tor toggle to reveal your original IP. Even without
1439) this bug, however, Javascript is still able to access previous pages in your
1440) session history that may have been loaded under a different Tor state, to
1441) attempt to correlate your activity.
1442) 
1443)    </para>
1444)    <para>
1445) 
1446) This setting helps to fulfill Torbutton's <link linkend="state">State
1447) Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Network Isolation</link>
1448) requirements.
1449) 
1450)    </para>
1451) </sect2>
1452) 
1453) 
1454) <sect2>
1455) <title>History Access Settings</title>
1456) 
1457)   <para>Options:
1458)   <simplelist>
1459)    <member><command>extensions.torbutton.block_thread</command></member>
1460)    <member><command>extensions.torbutton.block_nthread</command></member>
1461)    <member><command>extensions.torbutton.block_thwrite</command></member>
1462)    <member><command>extensions.torbutton.block_nthwrite</command></member>
1463)   </simplelist>
1464)   </para>
1465) 
1466) <para>These four settings govern the behavior of the <ulink
1467) url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink>
1468) history blocker component mentioned above. By hooking the browser's view of
1469) the history itself via the <ulink
1470) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2">@mozilla.org/browser/global-history;2</ulink>
1471) and <ulink
1472) url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1">@mozilla.org/browser/nav-history-service;1</ulink>
1473) components, this mechanism defeats all document-based <ulink
1474) url="http://whattheinternetknowsaboutyou.com/">history disclosure
1475) attacks</ulink>, including <ulink
1476) url="http://ha.ckers.org/weird/CSS-history.cgi">CSS-only attacks</ulink>.
1477) 
1478) The component also hooks functions involved in writing history to disk via
1479) both the <ulink
1480) url="http://developer.mozilla.org/en/docs/Places_migration_guide#History">Places
1481) Database</ulink> and the older Firefox 2 mechanisms.
1482) 
1483) </para>
1484) 
1485) <para>
1486) This setting helps to satisfy the <link
1487) linkend="state">State Separation</link> and <link
1488) linkend="disk">Disk Avoidance</link> requirements.
1489) </para>
1490) 
1491) </sect2>
1492) <sect2>
1493) 
1494) <title>Clear History During Tor Toggle (optional)</title>
1495) 
1496) <para>Option: <command>extensions.torbutton.clear_history</command></para>
1497) 
1498) <para>This setting governs if Torbutton calls
1499) <ulink
1500) url="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29">nsIBrowserHistory.removeAllPages</ulink>
1501) and <ulink
1502) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory">nsISHistory.PurgeHistory</ulink>
1503) for each tab on Tor toggle.</para>
1504) <para>
1505) This setting is an optional way to help satisfy the <link
1506) linkend="state">State Separation</link> requirement.
1507) </para>
1508) 
1509) </sect2>
1510) <sect2>
1511) 
1512) <title>Block Password+Form saving during Tor/Non-Tor</title>
1513) 
1514) <para>Options:
1515)   <simplelist>
1516)   <member><command>extensions.torbutton.block_tforms</command></member>
1517)   <member><command>extensions.torbutton.block_ntforms</command></member>
1518)   </simplelist>
1519)   </para>
1520) 
1521) <para>These settings govern if Torbutton disables
1522) <command>browser.formfill.enable</command>
1523) and <command>signon.rememberSignons</command> during Tor and Non-Tor usage.
1524) Since form fields can be read at any time by Javascript, this setting is a lot
1525) more important than it seems.
1526) </para>
1527) 
1528) <para>
1529) This setting helps to satisfy the <link
1530) linkend="state">State Separation</link> and <link
1531) linkend="disk">Disk Avoidance</link> requirements.
1532) </para>
1533) 
1534) </sect2>
1535) <sect2>
1536)   <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
1537) 
1538)   <para>Option: <command>extensions.torbutton.clear_cache</command>
1539)   </para>
1540) 
1541) <para>This option causes Torbutton to call <ulink
1542) url="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29">nsICacheService.evictEntries(0)</ulink>
1543) on Tor toggle to remove all entries from the cache. In addition, this setting
1544) causes Torbutton to set <ulink
1545) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> to false.
1546) </para>
1547) <para>
1548) This setting helps to satisfy the <link
1549) linkend="state">State Separation</link> and <link
1550) linkend="disk">Disk Avoidance</link> requirements.
1551) </para>
1552) 
1553) </sect2>
1554) <sect2>
1555)   <title>Block disk and memory cache during Tor</title>
1556) 
1557) <para>Option: <command>extensions.torbutton.block_cache</command></para>
1558) 
1559) <para>This setting
1560) causes Torbutton to set <ulink
1561) url="http://kb.mozillazine.org/Browser.cache.memory.enable">browser.cache.memory.enable</ulink>,
1562) <ulink
1563) url="http://kb.mozillazine.org/Browser.cache.disk.enable">browser.cache.disk.enable</ulink> and
1564) <ulink
1565) url="http://kb.mozillazine.org/Network.http.use-cache">network.http.use-cache</ulink> to false during tor usage.
1566) </para>
1567) <para>
1568) This setting helps to satisfy the <link
1569) linkend="state">State Separation</link> and <link
1570) linkend="disk">Disk Avoidance</link> requirements.
1571) </para>
1572) 
1573) </sect2>
1574) <sect2>
1575)   <title>Clear Cookies on Tor Toggle</title>
1576) 
1577) <para>Option: <command>extensions.torbutton.clear_cookies</command>
1578)   </para>
1579) 
1580) <para>
1581) 
1582) This setting causes Torbutton to call <ulink
1583) url="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29">nsICookieManager.removeAll()</ulink> on
1584) every Tor toggle. In addition, this sets <ulink
1585) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1586) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1587) which prevents them from being written to disk. 
1588) 
1589) </para>
1590) <para>
1591) This setting helps to satisfy the <link
1592) linkend="state">State Separation</link> and <link
1593) linkend="disk">Disk Avoidance</link> requirements.
1594) </para>
1595) 
1596) </sect2>
1597) <sect2>
1598)   
1599)   <title>Store Non-Tor cookies in a protected jar</title>
1600) 
1601) <para>Option: <command>extensions.torbutton.cookie_jars</command>
1602)   </para>
1603) 
1604) <para>
1605) 
1606) This setting causes Torbutton to use <ulink
1607) url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1608) non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
1609) before restoring the jar.
1610) </para>
1611) <para>
1612) This setting also sets <ulink
1613) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1614) to 2 for Tor usage, which causes all cookies to be demoted to session cookies,
1615) which prevents them from being written to disk. 
1616) 
1617) </para>
1618) 
1619) <para>
1620) This setting helps to satisfy the <link
1621) linkend="state">State Separation</link> and <link
1622) linkend="disk">Disk Avoidance</link> requirements.
1623) </para>
1624) 
1625) 
1626) </sect2>
1627) <sect2>
1628) 
1629)   <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
1630) 
1631) <para>Option: <command>extensions.torbutton.dual_cookie_jars</command>
1632)   </para>
1633) 
1634) <para>
1635) 
1636) This setting causes Torbutton to use <ulink
1637) url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1638) both Tor and Non-Tor cookies into protected jars.
1639) </para>
1640) 
1641) <para>
1642) This setting helps to satisfy the <link
1643) linkend="state">State Separation</link> requirement.
1644) </para>
1645) 
1646) 
1647) </sect2>
1648) 
1649) 
1650) <sect2>
1651) 
1652)   <title>Manage My Own Cookies (dangerous)</title>
1653) 
1654) <para>Options: None</para>
1655) <para>This setting disables all Torbutton cookie handling by setting the above
1656) cookie prefs all to false.</para>
1657) </sect2>
1658) <sect2>
1659) 
1660) <sect2>
1661)   <title>Do not write Tor/Non-Tor cookies to disk</title>
1662)   <para>Options:
1663)   <simplelist>
1664)   <member><command>extensions.torbutton.tor_memory_jar</command></member>
1665)   <member><command>extensions.torbutton.nontor_memory_jar</command></member>
1666)   </simplelist>
1667)   </para>
1668) 
1669) <para>
1670) These settings (contributed by arno) cause Torbutton to set <ulink
1671) url="http://kb.mozillazine.org/Network.cookie.lifetimePolicy">network.cookie.lifetimePolicy</ulink>
1672) to 2 during the appropriate Tor state, and to store cookies acquired in that
1673) state into a Javascript
1674) <ulink
1675) url="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:Processing_XML_with_E4X">E4X</ulink>
1676) object as opposed to writing them to disk.
1677) </para>
1678) 
1679) <para>
1680) This allows Torbutton to provide an option to preserve a user's 
1681) cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
1682) requirement.
1683) </para>
1684) </sect2>
1685) 
1686) 
1687)   <title>Disable DOM Storage during Tor usage (crucial)</title>
1688) 
1689) <para>Option: <command>extensions.torbutton.disable_domstorage</command>
1690)   </para>
1691) 
1692) <para>
1693) 
1694) This setting causes Torbutton to toggle <command>dom.storage.enabled</command> during Tor
1695) usage to prevent 
1696) <ulink
1697)   url="http://developer.mozilla.org/en/docs/DOM:Storage">DOM Storage</ulink> from
1698)   being used to store persistent information across Tor states.</para>
1699) <para>
1700) This setting helps to satisfy the <link
1701) linkend="state">State Separation</link> requirement.
1702) </para>
1703) 
1704) </sect2>
1705) 
1706) <sect2>
1707)   <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
1708) <para>Option: <command>extensions.torbutton.clear_http_auth</command>
1709)   </para>
1710) 
1711) <para>
1712) This setting causes Torbutton to call <ulink
1713) url="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager">nsIHttpAuthManager.clearAll()</ulink>
1714) every time Tor is toggled.
1715) </para>
1716) 
1717) <para>
1718) This setting helps to satisfy the <link
1719) linkend="state">State Separation</link> requirement.
1720) </para>
1721) </sect2>
1722) 
1723) <sect2>
1724) 
1725)   <title>Clear cookies on Tor/Non-Tor shutdown</title>
1726) 
1727) <para>Option: <command>extensions.torbutton.shutdown_method</command>
1728)   </para>
1729) 
1730) <para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1731) cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1732) clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1733) for the <ulink
1734) url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

1735) <function>https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</function> and use <ulink
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

1736) url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1737) to clear out all cookies and all cookie jars upon shutdown.  </para>
1738) <para>
1739) This setting helps to satisfy the <link
1740) linkend="state">State Separation</link> requirement.
1741) </para>
1742) 
1743) 
1744) </sect2>
1745) <sect2>
1746) 
1747)   <title>Reload cookie jar/clear cookies on Firefox crash</title>
1748)   <para>Options:
1749)   <simplelist>
1750)     <member><command>extensions.torbutton.reload_crashed_jar</command></member>
1751)     <member><command>extensions.torbutton.crashed</command></member>
1752)   </simplelist>
1753)   </para>
1754) 
1755)   <para>This is no longer a user visible option, and is enabled by default. In
1756) the event of a crash, the Torbutton <ulink
1757) url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink> 
1758)   component will notify the Chrome (via the
1759)   <command>extensions.torbutton.crashed</command> pref and a <ulink
1760) url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
1761) observer</ulink> in
1762) the chrome that listens for this update), and Torbutton will load the
1763)   correct jar for the current Tor state via the <ulink
1764) url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1765)   component.</para>
1766) 
1767) <para>
1768) This setting helps to satisfy the <link
1769) linkend="state">State Separation</link> requirement in the event of Firefox
1770) crashes.
1771) </para>
1772) 
1773) </sect2>
1774) 
1775) 
1776) <sect2>
1777)   <title>On crash recovery or session restored startup, restore via: Tor, Non-Tor</title>
1778)   <para>Options:
1779)   <simplelist>
1780)    <member><command>extensions.torbutton.restore_tor</command></member>
1781)    <member><command>extensions.torbutton.crashed</command></member>
1782)    <member><command>extensions.torbutton.normal_exit</command></member>
1783)   </simplelist>
1784)   </para>
1785) 
1786)   <para>This option works with the Torbutton <ulink
1787) url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink> 
1788)   to set the Tor state after a crash is detected (via the 
1789)   <command>extensions.torbutton.crashed</command> pref). To confirm for
1790) false positives (such as session restore failures, upgrade, normal
1791) session restore, etc), Torbutton also sets the pref
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

1792) extensions.torbutton.normal_exit during
Andrew Lewman add torbutton design dir fr...

Andrew Lewman authored 14 years ago

1793) Firefox exit and checks this value as well during startup.  
1794) </para>
1795) <para>
1796) 
1797) Since the Tor state after a Firefox crash is unknown/indeterminate, this
1798) setting helps to satisfy the <link linkend="state">State Separation</link>
1799) requirement in the event of Firefox crashes by ensuring all cookies,
1800) settings and saved sessions are reloaded from a fixed Tor state.
1801)  
1802) </para>
1803) </sect2>
1804) 
1805) <sect2>
1806)   <title>On normal startup, set state to: Tor, Non-Tor, Shutdown State</title>
1807) 
1808)   <para>Options:
1809)   <simplelist>
1810)    <member><command>extensions.torbutton.startup_state</command></member>
1811)   <member><command>extensions.torbutton.noncrashed</command></member>
1812)    <member><command>extensions.torbutton.normal_exit</command></member>
1813)   </simplelist>
1814)   </para>
1815) 
1816)   <para>This option also works with the Torbutton <ulink
1817) url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink> 
1818)   to set the Tor state after a normal startup is detected (via the 
1819)   <command>extensions.torbutton.noncrashed</command> pref). To confirm for
1820) false positives
1821) (such as session restore failures, etc), Torbutton also sets the pref
1822) extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
1823) Firefox exit and checks this value as well during startup.
1824)   
1825) </para>
1826) 
1827) </sect2>
1828) 
1829) <sect2>
1830)   <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
1831) 
1832)   <para>Options: 
1833)   <simplelist>
1834)     <member><command>extensions.torbutton.nonontor_sessionstore</command></member>
1835)     <member><command>extensions.torbutton.notor_sessionstore</command></member>
1836)   </simplelist>
1837)   </para>
1838) 
1839)   <para>If these options are enabled, the <ulink
1840) url="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js">replacement nsSessionStore.js</ulink>
1841)   component checks the <command>__tb_tor_fetched</command> tag of tabs before writing them
1842)   out. If the tag is from a blocked Tor state, the tab is not written to disk.
1843)   </para>
1844) <para>
1845) This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
1846) requirement, and also helps to satisfy the <link
1847) linkend="state">State Separation</link> requirement in the event of Firefox
1848) crashes.
1849) 
1850) </para>
1851) 
1852) </sect2>
1853) 
1854) <sect2>
1855) 
1856)   <title>Set user agent during Tor usage (crucial)</title>
1857)   <para>Options:
1858)    <simplelist>
1859)     <member><command>extensions.torbutton.set_uagent</command></member>
1860)     <member><command>extensions.torbutton.platform_override</command></member>
1861)     <member><command>extensions.torbutton.oscpu_override</command></member>
1862)     <member><command>extensions.torbutton.buildID_override</command></member>
1863)     <member><command>extensions.torbutton.productsub_override</command></member>
1864)     <member><command>extensions.torbutton.appname_override</command></member>
1865)     <member><command>extensions.torbutton.appversion_override</command></member>
1866)     <member><command>extensions.torbutton.useragent_override</command></member>
1867)     <member><command>extensions.torbutton.useragent_vendor</command></member>
1868)     <member><command>extensions.torbutton.useragent_vendorSub</command></member>
1869)   </simplelist>
1870)    </para>
1871) 
1872) <para>On face, user agent switching appears to be straight-forward in Firefox.
1873) It provides several options for controlling the browser user agent string:
1874) <command>general.appname.override</command>,
1875) <command>general.appversion.override</command>,
1876) <command>general.platform.override</command>,
1877) <command>general.oscpu.override</command>,
1878) <command>general.productSub.override</command>,
1879) <command>general.buildID.override</command>,
1880) <command>general.useragent.override</command>,
1881) <command>general.useragent.vendor</command>, and
1882) <command>general.useragent.vendorSub</command>. If
1883) the Torbutton preference <command>extensions.torbutton.set_uagent</command> is
1884) true, Torbutton copies all of the other above prefs into their corresponding
1885) browser preferences during Tor usage.</para>
1886) 
1887) 
1888) <para>
1889) 
1890) It also turns out that it is possible to detect the original Firefox version
1891) by <ulink url="http://ha.ckers.org/blog/20070516/read-firefox-settings-poc/">inspecting
1892) certain resource:// files</ulink>. These cases are handled by Torbutton's
1893) <link linkend="contentpolicy">content policy</link>.
1894) 
1895) </para>
1896) 
1897) <para>
1898) This setting helps to satisfy the <link
1899) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1900) </para>
1901) 
1902) 
1903) </sect2>
1904) <sect2>
1905) 
1906)   <title>Spoof US English Browser</title>
1907) <para>Options:
1908) <simplelist>
1909)  <member><command>extensions.torbutton.spoof_english</command></member>
1910)  <member><command>extensions.torbutton.spoof_charset</command></member>
1911)  <member><command>extensions.torbutton.spoof_language</command></member>
1912) </simplelist>
1913) </para>
1914) 
1915) <para> This option causes Torbutton to set
1916) <command>general.useragent.locale</command>
1917) <command>intl.accept_languages</command> to the value specified in
1918) <command>extensions.torbutton.spoof_locale</command>,
1919) <command>extensions.torbutton.spoof_charset</command> and
1920) <command>extensions.torbutton.spoof_language</command> during Tor usage, as
1921) well as hooking <command>navigator.language</command> via its <link
1922) linkend="jshooks">javascript hooks</link>.
1923)  </para>
1924) <para>
1925) This setting helps to satisfy the <link
1926) linkend="setpreservation">Anonymity Set Preservation</link> and <link
1927) linkend="location">Location Neutrality</link> requirements.
1928) </para>
1929) 
1930) </sect2>
1931) <sect2>
1932) 
1933)   <title>Don't send referrer during Tor Usage</title>
1934) 
1935) <para>Option: <command>extensions.torbutton.disable_referer</command>
1936) </para>
1937) 
1938) <para> 
1939) This option causes Torbutton to set <ulink
1940) url="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer">network.http.sendSecureXSiteReferrer</ulink> and
1941) <ulink
1942) url="http://kb.mozillazine.org/Network.http.sendRefererHeader">network.http.sendRefererHeader</ulink> during Tor usage.</para>
1943) 
1944) <para>
1945) This setting also does not directly satisfy any Torbutton requirement, but
1946) some may desire to mask their referrer for general privacy concerns.
Mike Perry Update design doc for 1.2.5.

Mike Perry authored 14 years ago

1947) </para>
1948) </sect2>
1949) <sect2>
1950)   <title>Strip platform and language off of Google Search Box queries</title>
1951) 
1952) <para>Option: <command>extensions.torbutton.fix_google_srch</command>
1953) </para>
1954) 
1955) <para> 
1956) 
1957) This option causes Torbutton to use the <ulink
1958) url="https://wiki.mozilla.org/Search_Service:API">@mozilla.org/browser/search-service;1</ulink>
1959) component to wrap the Google search plugin. On many platforms, notably Debian
1960) and Ubuntu, the Google search plugin is set to reveal a lot of language and
1961) platform information. This setting strips off that info while Tor is enabled.
1962) 
1963) </para>
1964) <para>
1965) This setting helps Torbutton to fulfill its <link
1966) linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1967) </para>
1968) </sect2>
1969) 
1970) <sect2>
1971)   <title>Automatically use an alternate search engine when presented with a
1972) Google Captcha</title>
1973) 
1974) <para>Options:
1975) <simplelist>
1976)  <member><command>extensions.torbutton.asked_google_captcha</command></member>
1977)  <member><command>extensions.torbutton.dodge_google_captcha</command></member>
1978)  <member><command>extensions.torbutton.google_redir_url</command></member>
1979) </simplelist>
1980) </para>
1981) 
1982) <para>
1983) 
1984) Google's earch engine has rate limiting features that cause it to
1985) <ulink
1986) url="http://googleonlinesecurity.blogspot.com/2007/07/reason-behind-were-sorry-message.html">present
1987) captchas</ulink> and sometimes even outright ban IPs that issue large numbers
1988) of search queries, especially if a lot of these queries appear to be searching
1989) for software vulnerabilities or unprotected comment areas.
1990) 
1991) </para>
1992) <para>
1993) 
1994) Despite multiple discussions with Google, we were unable to come to a solution
1995) or any form of compromise that would reduce the number of captchas and
1996) outright bans seen by Tor users issuing regular queries.
1997) 
1998) </para>
1999) <para>
2000) As a result, we've implemented this option as an <ulink
2001) url="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">'http-on-modify-request'</ulink>
2002) http observer to optionally redirect banned or captcha-triggering Google
2003) queries to search engines that do not rate limit Tor users. The current
2004) options are ixquick.com, bing.com, yahoo.com and scroogle.org. These are
2005) encoded in the preferences
2006) <command>extensions.torbutton.redir_url.[1-4]</command>.
2007)