Update Torbutton design doc.
Mike Perry

Mike Perry commited on 2011-04-04 21:53:25
Zeige 2 geänderte Dateien mit 859 Einfügungen und 705 Löschungen.

... ...
@@ -11,7 +11,7 @@
11 11
      <address><email>mikeperry.fscked/org</email></address>
12 12
     </affiliation>
13 13
    </author>
14
-   <pubdate>Jun 28 2010</pubdate>
14
+   <pubdate>Apr 3 2011</pubdate>
15 15
  </articleinfo>
16 16
 
17 17
 <sect1>
... ...
@@ -19,7 +19,7 @@
19 19
   <para>
20 20
 
21 21
 This document describes the goals, operation, and testing procedures of the
22
-Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
22
+Torbutton Firefox extension. It is current as of Torbutton 1.3.2.
23 23
 
24 24
   </para>
25 25
   <sect2 id="adversary">
... ...
@@ -153,7 +153,7 @@ a user's non-Tor IP address. Javascript
153 153
 also allows the adversary to execute <ulink
154 154
 url="http://whattheinternetknowsaboutyou.com/">history disclosure attacks</ulink>:
155 155
 to query the history via the different attributes of 'visited' links to search
156
-for particular google queries, sites, or even to <ulink
156
+for particular Google queries, sites, or even to <ulink
157 157
 url="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/">profile
158 158
 users based on gender and other classifications</ulink>. Finally,
159 159
 Javascript can be used to query the user's timezone via the
... ...
@@ -234,7 +235,11 @@ resolution information available in the <ulink
234 235
 url="http://developer.mozilla.org/en/docs/DOM:window">window</ulink> and
235 236
 <ulink
236 237
 url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>
237
-objects. Browser window resolution information provides something like
238
+objects.
239
+
240
+
241
+
242
+Browser window resolution information provides something like
238 243
 (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
239 244
 information contributes about another factor of 5 (for about 5 resolutions in
240 245
 typical use). In addition, the dimensions and position of the desktop taskbar
... ...
@@ -252,14 +257,25 @@ information alone. </para>
252 257
 
253 258
 <para>
254 259
 
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. 
260
+Of course, this space is non-uniform in user density and prone to incremental
261
+changes. The <ulink
262
+url="https://wiki.mozilla.org/Fingerprinting#Data">Panopticlick study
263
+done</ulink> by the EFF attempts to measure the actual entropy - the number of
264
+identifying bits of information encoded in browser properties.  Their result
265
+data is definitely useful, and the metric is probably the appropriate one for
266
+determining how identifying a particular browser property is. However, some
267
+quirks of their study means that they do not extract as much information as
268
+they could from display information: they only use desktop resolution (which
269
+Torbutton reports as the window resolution) and do not attempt to infer the
270
+size of toolbars.
261 271
 
262 272
 </para>
273
+<!--
274
+FIXME: This is no longer true. Only certain addons are now discoverable, and
275
+only if they want to be:
276
+http://webdevwonders.com/detecting-firefox-add-ons/
277
+https://developer.mozilla.org/en/Updating_web_applications_for_Firefox_3#section_7
278
+
263 279
 <para>
264 280
 
265 281
 To add insult to injury, <ulink
... ...
@@ -274,7 +290,7 @@ nearest-neighbor bit vector space approach here would also gracefully handle
274 290
 incremental changes to installed extensions.
275 291
 
276 292
 </para>
277
-
293
+-->
278 294
      </listitem>
279 295
      <listitem><command>Remotely or locally exploit browser and/or
280 296
 OS</command>
... ...
@@ -377,7 +393,7 @@ is called <ulink
377 393
 url="http://developer.mozilla.org/en/docs/XUL_Reference">XUL</ulink>.</para>
378 394
   </sect2>
379 395
 </sect1>
380
-<sect1>
396
+<sect1 id="components">
381 397
   <title>Components</title>
382 398
   <para>
383 399
 
... ...
@@ -387,38 +403,13 @@ services to other pieces of the extension.
387 403
 
388 404
   </para>
389 405
 
390
-  <sect2>
406
+  <sect2 id="hookedxpcom">
391 407
    <title>Hooked Components</title>
392 408
 
393 409
 <para>Torbutton makes extensive use of Contract ID hooking, and implements some
394 410
 of its own standalone components as well.  Let's discuss the hooked components
395 411
 first.</para>
396 412
 
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 413
 <sect3 id="appblocker">
423 414
  <title><ulink
424 415
 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
... ...
@@ -426,7 +417,7 @@ url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/c
426 417
 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 418
 and <ulink url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1">@mozilla.org/mime;1</ulink>
428 419
 - <ulink
429
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
420
+  url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js">components/external-app-blocker.js</ulink></title>
430 421
  <para>
431 422
 Due to <link linkend="FirefoxBugs">Firefox Bug</link> <ulink
432 423
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=440892">440892</ulink> allowing Firefox 3.x to automatically launch some
... ...
@@ -438,39 +429,11 @@ back to arbitrary servers outside of Tor with no user intervention. Fixing
438 429
 this issue helps to satisfy Torbutton's <link linkend="proxy">Proxy
439 430
 Obedience</link> Requirement.
440 431
  </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 432
 </sect3>
470 433
 <sect3>
471 434
 <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 435
 - <ulink
473
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
436
+  url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink></title>
474 437
 
475 438
 <para>This component was contributed by <ulink
476 439
 url="http://www.collinjackson.com/">Collin Jackson</ulink> as a method for defeating
... ...
@@ -486,14 +449,18 @@ preferences.
486 449
 </para>
487 450
 <para>
488 451
 This component helps satisfy the <link linkend="state">State Separation</link>
489
-and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton.
452
+and <link linkend="disk">Disk Avoidance</link> requirements of Torbutton. It
453
+is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
454
+of the <ulink
455
+url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">built-in
456
+history protections</ulink>.
490 457
 </para>
491 458
 </sect3>
492 459
 <sect3 id="livemarks">
493 460
 <title><ulink
494 461
 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 462
 - <ulink
496
-  url="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
463
+  url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js">components/block-livemarks.js</ulink></title>
497 464
 <para>
498 465
 
499 466
 The <ulink
... ...
@@ -518,18 +485,19 @@ Preservation</link> requirements.
518 485
 extension. These components do not hook any interfaces, nor are they used
519 486
 anywhere besides Torbutton itself.</para>
520 487
 
521
-<sect3>
488
+<sect3 id="cookiejar">
522 489
 <title><ulink
523
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2
490
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2
524 491
 - components/cookie-jar-selector.js</ulink></title>
525 492
 
526 493
 <para>The cookie jar selector (also based on code from <ulink
527 494
 url="http://www.collinjackson.com/">Collin
528 495
 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>
496
+Tor and Non-Tor cookies. It stores an XML representation of the current
497
+cookie state in memory and/or on disk. When Tor is toggled, it syncs the
498
+current cookies to this XML store, and then loads the cookies for the other
499
+state from the XML store.
500
+</para>
533 501
 
534 502
 <para>
535 503
 This component helps to address the <link linkend="state">State
... ...
@@ -539,7 +507,7 @@ Isolation</link> requirement of Torbutton.
539 507
 </sect3>
540 508
 <sect3>
541 509
 <title><ulink
542
-url="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
510
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js">@torproject.org/torbutton-logger;1
543 511
 - components/torbutton-logger.js</ulink></title>
544 512
 
545 513
 <para>The torbutton logger component allows on-the-fly redirection of torbutton
... ...
@@ -554,7 +522,7 @@ change the loglevel on the fly by changing
554 522
 <sect3 id="windowmapper">
555 523
 
556 524
 <title><ulink
557
-url="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
525
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js">@torproject.org/content-window-mapper;1
558 526
 - components/window-mapper.js</ulink></title>
559 527
 
560 528
 <para>Torbutton tags Firefox <ulink
... ...
@@ -573,9 +541,62 @@ and page loading in general can generate hundreds of these lookups, this
573 541
 result is cached inside the component.
574 542
 </para>
575 543
 </sect3>
544
+<sect3 id="crashobserver">
545
+ <title><ulink
546
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js">@torproject.org/crash-observer;1</ulink></title>
547
+  <para>
548
+
549
+This component detects when Firefox crashes by altering Firefox prefs during
550
+runtime and checking for the same values at startup. It <ulink
551
+url="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()">synchronizes
552
+the preference service</ulink> to ensure the altered prefs are written to disk
553
+immediately.
554
+
555
+  </para>
556
+</sect3>
557
+<sect3 id="tbsessionstore">
558
+ <title><ulink
559
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js">@torproject.org/torbutton-ss-blocker;1</ulink></title>
560
+  <para>
561
+
562
+This component subscribes to the Firefox <ulink
563
+url="https://developer.mozilla.org/en/Observer_Notifications#Session_Store">sessionstore-state-write</ulink>
564
+observer event to filter out URLs from tabs loaded during Tor, to prevent them
565
+from being written to disk. To do this, it checks the
566
+<command>__tb_tor_fetched</command> tag of tab objects before writing them out. If
567
+the tag is from a blocked Tor state, the tab is not written to disk.  This is
568
+a rather expensive operation that involves potentially very large JSON
569
+evaluations and object tree traversals, but it preferable to replacing the
570
+Firefox session store with our own implementation, which is what was done in
571
+years past.
572
+
573
+  </para>
574
+</sect3>
575
+
576
+<sect3 id="refspoofer">
577
+ <title><ulink
578
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js">@torproject.org/torRefSpoofer;1</ulink></title>
579
+ <para>
580
+This component handles optional referrer spoofing for Torbuton. It implements a
581
+form of "smart" referer spoofing using <ulink
582
+url="https://developer.mozilla.org/en/Setting_HTTP_request_headers">http-on-modify-request</ulink>
583
+to modify the Referrer header. The code sends the default browser referrer
584
+header only if the destination domain is a suffix of the source, or if the
585
+source is a suffix of the destination. Otherwise, it sends no referer. This
586
+strange suffix logic is used as a heuristic: some rare sites on the web block
587
+requests without proper referer headers, and this logic is an attempt to cater
588
+to them. Unfortunately, it may not be enough. For example, google.fr will not
589
+send a referer to google.com using this logic. Hence, it is off by default.
590
+ </para>
591
+</sect3>
592
+
593
+<!-- FIXME: tor-protocol, tors-protocol need documenting, but
594
+they are disabled by default for now, so no reason to add the
595
+clutter+confusion. -->
596
+
576 597
 <sect3 id="contentpolicy">
577 598
 <title><ulink
578
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js">@torproject.org/cssblocker;1
599
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1
579 600
 - components/cssblocker.js</ulink></title>
580 601
 
581 602
 <para>This is a key component to Torbutton's security measures. When Tor is
... ...
@@ -598,7 +619,8 @@ linkend="isolation">Network
598 619
 Isolation</link> requirements of Torbutton.
599 620
 
600 621
 <para>In addition, the content policy also blocks website javascript from
601
-<ulink url="http://pseudo-flaw.net/content/tor/torbutton/">querying for
622
+<ulink
623
+url="http://webdevwonders.com/detecting-firefox-add-ons/">querying for
602 624
 versions and existence of extension chrome</ulink> while Tor is enabled, and
603 625
 also masks the presence of Torbutton to website javascript while Tor is
604 626
 disabled. </para>
... ...
@@ -608,7 +630,7 @@ disabled. </para>
608 630
 Finally, some of the work that logically belongs to the content policy is
609 631
 instead handled by the <command>torbutton_http_observer</command> and
610 632
 <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
633
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>. These two objects handle blocking of
612 634
 Firefox 3 favicon loads, popups, and full page plugins, which for whatever
613 635
 reason are not passed to the Firefox content policy itself (see Firefox Bugs 
614 636
 <ulink
... ...
@@ -674,21 +696,113 @@ Torbutton.</para>
674 696
  <title>Chrome</title>
675 697
 
676 698
 <para>The chrome is where all the torbutton graphical elements and windows are
677
-located. Each window is described as an <ulink
699
+located. </para>
700
+<sect2>
701
+ <title>XUL Windows and Overlays</title>
702
+<para>
703
+Each window is described as an <ulink
678 704
 url="http://developer.mozilla.org/en/docs/XUL_Reference">XML file</ulink>, with zero or more Javascript
679 705
 files attached. The scope of these Javascript files is their containing
680
-window.</para>
706
+window. XUL files that add new elements and script to existing Firefox windows
707
+are called overlays.</para>
681 708
 
682
-<sect2 id="browseroverlay">
709
+<sect3 id="browseroverlay">
683 710
 <title>Browser Overlay - <ulink
684
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
711
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink></title>
685 712
 
686 713
 <para>The browser overlay, torbutton.xul, defines the toolbar button, the status
687 714
 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>.
715
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>.
689 716
 It contains event handlers for preference update, shutdown, upgrade, and
690 717
 location change events.</para>
691 718
 
719
+</sect3>
720
+<sect3>
721
+ <title>Preferences Window - <ulink
722
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences.xul</ulink></title>
723
+
724
+<para>The preferences window of course lays out the Torbutton preferences, with
725
+handlers located in <ulink
726
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">chrome/content/preferences.js</ulink>.</para>
727
+</sect3>
728
+<sect3>
729
+ <title>Other Windows</title>
730
+
731
+<para>There are additional windows that describe popups for right clicking on
732
+the status bar, the toolbutton, and the about page.</para>
733
+
734
+</sect3>
735
+</sect2>
736
+<sect2>
737
+ <title>Major Chrome Observers</title>
738
+ <para>
739
+In addition to the <link linkend="components">components described
740
+above</link>, Torbutton also instantiates several observers in the browser
741
+overlay window. These mostly grew due to scoping convenience, and many should
742
+probably be relocated into their own components.
743
+ </para>
744
+  <orderedlist>
745
+   <listitem><command>torbutton_window_pref_observer</command>
746
+    <para>
747
+This is an observer that listens for Torbutton state changes, for the purposes
748
+of updating the Torbutton button graphic as the Tor state changes.
749
+    </para>
750
+   </listitem>
751
+
752
+   <listitem><command>torbutton_unique_pref_observer</command>
753
+    <para>
754
+
755
+This is an observer that only runs in one window, called the main window. It
756
+listens for changes to all of the Torbutton preferences, as well as Torbutton
757
+controlled Firefox preferences. It is what carries out the toggle path when
758
+the proxy settings change. When the main window is closed, the
759
+torbutton_close_window event handler runs to dub a new window the "main
760
+window".
761
+
762
+    </para>
763
+   </listitem>
764
+
765
+   <listitem><command>tbHistoryListener</command>
766
+    <para>
767
+The tbHistoryListener exists to prevent client window Javascript from
768
+interacting with window.history to forcibly navigate a user to a tab session
769
+history entry from a different Tor state. It also expunges the window.history
770
+entries during toggle. This listener helps Torbutton
771
+satisfy the <link linkend="isolation">Network Isolation</link> requirement as
772
+well as the <link linkend="state">State Separation</link> requirement.
773
+
774
+    </para>
775
+   </listitem>
776
+
777
+   <listitem><command>torbutton_http_observer</command>
778
+    <para>
779
+
780
+The torbutton_http_observer performs some of the work that logically belongs
781
+to the content policy. This handles blocking of
782
+Firefox 3 favicon loads, which for whatever
783
+reason are not passed to the Firefox content policy itself (see Firefox Bugs
784
+<ulink
785
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=437014">437014</ulink> and
786
+<ulink
787
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=401296">401296</ulink>).
788
+
789
+    </para>
790
+    <para>
791
+The observer is also responsible for redirecting users to alternate
792
+search engines when Google presents them with a Captcha, as well as copying
793
+Google Captcha-related cookies between international Google domains.
794
+    </para>
795
+   </listitem>
796
+
797
+   <listitem><command>torbutton_proxyservice</command>
798
+    <para>
799
+The Torbutton proxy service handles redirecting Torbutton-related update
800
+checks on addons.mozilla.org through Tor. This is done to help satisfy the
801
+<link linkend="undiscoverability">Tor Undiscoverability</link> requirement.
802
+    </para>
803
+   </listitem>
804
+
805
+   <listitem><command>torbutton_weblistener</command>
692 806
 <para>The <ulink
693 807
 url="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange">location
694 808
 change</ulink> <ulink
... ...
@@ -706,11 +820,103 @@ url="https://developer.mozilla.org/en/DOM/window.screen">window.screen</ulink>
706 820
 object to obfuscate browser and desktop resolution information.
707 821
 
708 822
 </para>
823
+   </listitem>
824
+
825
+  </orderedlist>
826
+ </sect2>
827
+</sect1>
828
+
829
+<sect1>
830
+ <title>Toggle Code Path</title>
831
+ <para>
832
+
833
+The act of toggling is connected to <function>torbutton_toggle()</function>
834
+via the <ulink
835
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul">torbutton.xul</ulink>
836
+and <ulink
837
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul">popup.xul</ulink>
838
+overlay files. Most of the work in the toggling process is present in <ulink
839
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink> 
840
+
841
+</para>
842
+<para>
843
+
844
+Toggling is a 3 stage process: Button Click, Proxy Update, and
845
+Settings Update. These stages are reflected in the prefs
846
+<command>extensions.torbutton.tor_enabled</command>,
847
+<command>extensions.torbutton.proxies_applied</command>, and
848
+<command>extensions.torbutton.settings_applied</command>. The reason for the
849
+three stage preference update is to ensure immediate enforcement of <link
850
+linkend="isolation">Network Isolation</link> via the <link
851
+linkend="contentpolicy">content policy</link>. Since the content window
852
+javascript runs on a different thread than the chrome javascript, it is
853
+important to properly convey the stages to the content policy to avoid race
854
+conditions and leakage, especially with <ulink
855
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Firefox Bug 
856
+409737</ulink> unfixed. The content policy does not allow any network activity
857
+whatsoever during this three stage transition.
858
+
859
+ </para>
860
+ <sect2>
861
+  <title>Button Click</title>
862
+  <para>
709 863
 
864
+This is the first step in the toggling process. When the user clicks the
865
+toggle button or the toolbar, <function>torbutton_toggle()</function> is
866
+called. This function checks the current Tor status by comparing the current
867
+proxy settings to the selected Tor settings, and then sets the proxy settings
868
+to the opposite state, and sets the pref
869
+<command>extensions.torbutton.tor_enabled</command> to reflect the new state.
870
+It is this proxy pref update that gives notification via the <ulink
871
+url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
872
+observer</ulink>
873
+<command>torbutton_unique_pref_observer</command> to perform the rest of the
874
+toggle.
875
+
876
+  </para>
877
+ </sect2>
878
+ <sect2>
879
+  <title>Proxy Update</title>
710 880
   <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
881
+
882
+When Torbutton receives any proxy change notifications via its
883
+<command>torbutton_unique_pref_observer</command>, it calls
884
+<function>torbutton_set_status()</function> which checks against the Tor
885
+settings to see if the Tor proxy settings match the current settings. If so,
886
+it calls <function>torbutton_update_status()</function>, which determines if
887
+the Tor state has actually changed, and sets
888
+<command>extensions.torbutton.proxies_applied</command> to the appropriate Tor
889
+state value, and ensures that
890
+<command>extensions.torbutton.tor_enabled</command> is also set to the correct
891
+value. This is decoupled from the button click functionality via the pref
892
+observer so that other addons (such as SwitchProxy) can switch the proxy
893
+settings between multiple proxies.
894
+
895
+  </para>
896
+ </sect2>
897
+<!-- FIXME: Describe tab tagging and other state clearing hacks? -->
898
+ <sect2>
899
+  <title>Settings Update</title>
900
+  <para>
901
+
902
+The next stage is also handled by
903
+<function>torbutton_update_status()</function>. This function sets scores of
904
+Firefox preferences, saving the original values to prefs under
905
+<command>extensions.torbutton.saved.*</command>, and performs the <link
906
+linkend="cookiejar">cookie jarring</link>, state clearing (such as window.name
907
+and DOM storage), and <link linkend="preferences">preference
908
+toggling</link><!--, and ssl certificate jaring work of Torbutton-->. At the
909
+end of its work, it sets
910
+<command>extensions.torbutton.settings_applied</command>, which signifies the
911
+completion of the toggle operation to the <link
912
+linkend="contentpolicy">content policy</link>.
913
+
914
+  </para>
915
+ </sect2>
916
+<sect2 id="preferences">
917
+<title>Firefox preferences touched during Toggle</title>
918
+<para>
919
+There are also a number of Firefox preferences set in
714 920
 <function>torbutton_update_status()</function> that aren't governed by any
715 921
 Torbutton setting. These are:
716 922
 </para>
... ...
@@ -810,7 +1016,8 @@ restoring it to the previous user value upon toggle.
810 1016
    </para>
811 1017
   </listitem>
812 1018
 
813
-  <listitem><command>security.enable_ssl2</command>
1019
+  <listitem><command>security.enable_ssl2</command> or <ulink
1020
+url="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto">nsIDOMCrypto::logout()</ulink>
814 1021
    <para>
815 1022
 TLS Session IDs can persist for an indefinite duration, providing an
816 1023
 identifier that is sent to TLS sites that can be used to link activity. This
... ...
@@ -819,16 +1026,33 @@ in Firefox 3: The OCSP server can use this Session ID to build a history of
819 1026
 TLS sites someone visits, and also correlate their activity as users move from
820 1027
 network to network (such as home to work to coffee shop, etc), inside and
821 1028
 outside of Tor. To handle this and to help satisfy our <link
822
-linkend="state">State Separation Requirement</link>, we currently 
823
-toggle
1029
+linkend="state">State Separation Requirement</link>, we call the logout()
1030
+function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
1031
+to toggling
824 1032
 <command>security.enable_ssl2</command>, which clears the SSL Session ID
825 1033
 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.
1034
+url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
1035
+   </para>
1036
+  </listitem>
1037
+  <listitem><command>security.OCSP.enabled</command>
1038
+   <para>
1039
+Similarly, we toggle <command>security.OCSP.enabled</command>, which clears the OCSP certificate
1040
+validation cache via the pref observer at <ulink
1041
+url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp">nsNSSComponent.cpp</ulink>.
1042
+In this way, exit nodes will not be able to fingerprint you
1043
+based the fact that non-Tor OCSP lookups were obviously previously cached.
1044
+To handle this and to help satisfy our <link
1045
+linkend="state">State Separation Requirement</link>,
1046
+   </para>
1047
+  </listitem>
1048
+  <listitem><command><ulink
1049
+url="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</ulink></command>
1050
+  <para>
1051
+We permanently disable addon usage statistic reporting to the
1052
+addons.mozilla.org statistics engine. These statistics send version
1053
+information about Torbutton users via non-Tor, allowing their Tor use to be
1054
+uncovered. Disabling this reporting helps Torbutton to satisfy its <link
1055
+linkend="undiscoverability">Tor Undiscoverability</link> requirement.
832 1056
 
833 1057
   </para>
834 1058
   </listitem>
... ...
@@ -900,117 +1124,20 @@ requirements.
900 1124
 
901 1125
 </orderedlist>
902 1126
 </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 1127
 
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 1128
 </sect1>
1005 1129
 
1006 1130
 <sect1>
1007 1131
  <title>Description of Options</title>
1008
-<!-- FIXME: Review+update these during FF3.5 audit -->
1009 1132
 <para>This section provides a detailed description of Torbutton's options. Each
1010 1133
 option is presented as the string from the preferences window, a summary, the
1011 1134
 preferences it touches, and the effect this has on the components, chrome, and
1012 1135
 browser properties.</para>
1136
+<!-- FIXME: figure out how to give subsections # ids or make this into a
1137
+listitem -->
1013 1138
  <sect2>
1139
+  <title>Proxy Settings</title>
1140
+ <sect3>
1014 1141
   <title>Test Settings</title>
1015 1142
   <para>
1016 1143
 This button under the Proxy Settings tab provides a way to verify that the 
... ...
@@ -1025,16 +1152,19 @@ Torbutton can easily inspect for a hidden link with an id of
1025 1152
 or <command>failure</command> to indicate if the
1026 1153
 user hit the page from a Tor IP, a non-Tor IP. This check is handled in
1027 1154
 <function>torbutton_test_settings()</function> in <ulink
1028
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">torbutton.js</ulink>.
1155
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">torbutton.js</ulink>.
1029 1156
 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
1157
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul">preferences
1031 1158
 window</ulink>
1032 1159
 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>.  
1160
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js">preferences.js</ulink>.  
1034 1161
 
1035 1162
   </para>
1163
+ </sect3>
1036 1164
  </sect2>
1037
- <sect2 id="plugins">
1165
+ <sect2>
1166
+  <title>Dynamic Content Settings</title>
1167
+ <sect3 id="plugins">
1038 1168
   <title>Disable plugins on Tor Usage (crucial)</title>
1039 1169
  <para>Option: <command>extensions.torbutton.no_tor_plugins</command></para>
1040 1170
 
... ...
@@ -1063,7 +1193,7 @@ event occurs
1063 1193
  (<function>torbutton_update_tags()</function>), and every time the tor state is changed
1064 1194
  (<function>torbutton_update_status()</function>). As a backup measure, plugins are also
1065 1195
  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
1196
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> if Tor is
1067 1197
  enabled and this option is set.
1068 1198
  </para>
1069 1199
 
... ...
@@ -1118,14 +1248,14 @@ performed by this setting are crucial to satisfying the <link
1118 1248
 linkend="proxy">Proxy Obedience</link> requirement.
1119 1249
 
1120 1250
  </para>
1121
-</sect2>
1122
-<sect2>
1251
+</sect3>
1252
+<sect3>
1123 1253
  <title>Isolate Dynamic Content to Tor State (crucial)</title>
1124 1254
 
1125 1255
  <para>Option: <command>extensions.torbutton.isolate_content</command></para>
1126 1256
 
1127 1257
 <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
1258
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js">@torproject.org/cssblocker;1</ulink> content policy
1129 1259
 mentioned above, and causes it to block content load attempts in pages an
1130 1260
 opposite Tor state from the current state. Freshly loaded <ulink
1131 1261
 url="https://developer.mozilla.org/en/XUL/tabbrowser">browser
... ...
@@ -1167,15 +1297,15 @@ This setting is responsible for satisfying the <link
1167 1297
 linkend="isolation">Network Isolation</link> requirement.
1168 1298
 </para>
1169 1299
 
1170
-</sect2>
1171
-<sect2 id="jshooks">
1300
+</sect3>
1301
+<sect3 id="jshooks">
1172 1302
 
1173 1303
 <title>Hook Dangerous Javascript</title>
1174 1304
 
1175 1305
  <para>Option: <command>extensions.torbutton.kill_bad_js</command></para>
1176 1306
 
1177 1307
 <para>This setting enables injection of the <ulink
1178
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js">Javascript
1308
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js">Javascript
1179 1309
 hooking code</ulink>. This is done in the chrome in
1180 1310
 <function>torbutton_hookdoc()</function>, which is called ultimately by both the 
1181 1311
 <ulink
... ...
@@ -1202,13 +1332,13 @@ to retrieve the original screen values by using <ulink
1202 1332
 url="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html">XPCNativeWrapper</ulink>
1203 1333
 or <ulink
1204 1334
 url="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html">Components.lookupMethod</ulink>.
1205
-We are still looking for a workaround as of Torbutton 1.2.5.
1335
+We are still looking for a workaround as of Torbutton 1.3.2.
1206 1336
 
1207 1337
 <!-- FIXME: Don't forget to update this -->
1208 1338
 
1209 1339
 </para>
1210
-</sect2>
1211
-<sect2>
1340
+</sect3>
1341
+<sect3>
1212 1342
 <title>Resize windows to multiples of 50px during Tor usage (recommended)</title>
1213 1343
 
1214 1344
  <para>Option: <command>extensions.torbutton.resize_windows</command></para>
... ...
@@ -1249,11 +1379,34 @@ infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
1249 1379
 
1250 1380
 </para>
1251 1381
 <para>
1252
-This setting helps to meet the <link
1253
-linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1382
+This setting helps to meet the <link
1383
+linkend="setpreservation">Anonymity Set Preservation</link> requirements.
1384
+</para>
1385
+</sect3>
1386
+<sect3>
1387
+
1388
+<title>Disable Search Suggestions during Tor (recommended)</title>
1389
+
1390
+  <para>Option: <command>extensions.torbutton.no_search</command></para>
1391
+
1392
+<para>
1393
+This setting causes Torbutton to disable <ulink
1394
+url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1395
+during Tor usage.
1396
+This governs if you get Google search suggestions during Tor
1397
+usage. Your Google cookie is transmitted with google search suggestions, hence
1398
+this is recommended to be disabled.
1399
+
1400
+</para>
1401
+<para>
1402
+While this setting doesn't satisfy any Torbutton requirements, the fact that
1403
+cookies are transmitted for partially typed queries does not seem desirable
1404
+for Tor usage.
1254 1405
 </para>
1255
-</sect2>
1256
-<sect2>
1406
+</sect3>
1407
+
1408
+
1409
+<sect3>
1257 1410
 <title>Disable Updates During Tor</title>
1258 1411
 
1259 1412
   <para>Option: <command>extensions.torbutton.no_updates</command></para>
... ...
@@ -1272,8 +1425,8 @@ update settings</ulink> during Tor
1272 1425
 This setting satisfies the <link
1273 1426
 linkend="updates">Update Safety</link> requirement.
1274 1427
 </para>
1275
-</sect2>
1276
-<sect2>
1428
+</sect3>
1429
+<sect3>
1277 1430
 <title>Redirect Torbutton Updates Via Tor (recommended)</title>
1278 1431
 
1279 1432
   <para>Option: <command>extensions.torbutton.update_torbutton_via_tor</command></para>
... ...
@@ -1290,30 +1443,9 @@ help censored users meet the <link linkend="undiscoverability">Tor
1290 1443
 Undiscoverability</link> requirement.
1291 1444
 
1292 1445
   </para>
1293
-</sect2>
1294
-
1295
-<sect2>
1296
-
1297
-<title>Disable Search Suggestions during Tor (recommended)</title>
1298
-
1299
-  <para>Option: <command>extensions.torbutton.no_search</command></para>
1300
-
1301
-<para>
1302
-This setting causes Torbutton to disable <ulink
1303
-url="http://kb.mozillazine.org/Browser.search.suggest.enabled"><command>browser.search.suggest.enabled</command></ulink>
1304
-during Tor usage.
1305
-This governs if you get Google search suggestions during Tor
1306
-usage. Your Google cookie is transmitted with google search suggestions, hence
1307
-this is recommended to be disabled.
1446
+</sect3>
1308 1447
 
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>
1448
+<sect3>
1317 1449
 <title>Disable livemarks updates during Tor usage (recommended)</title>
1318 1450
   <para>Option:
1319 1451
    <simplelist>
... ...
@@ -1339,8 +1472,8 @@ Isolation</link> and <link linkend="setpreservation">Anonymity Set
1339 1472
 Preservation</link> requirements.
1340 1473
 </para>
1341 1474
 
1342
-</sect2>
1343
-<sect2>
1475
+</sect3>
1476
+<sect3>
1344 1477
 <title>Block Tor/Non-Tor access to network from file:// urls (recommended)</title>
1345 1478
   <para>Options:
1346 1479
    <simplelist>
... ...
@@ -1371,8 +1504,9 @@ operations in opposite Tor states. Also, allowing pages to submit arbitrary
1371 1504
 files to arbitrary sites just generally seems like a bad idea.
1372 1505
 
1373 1506
 </para>
1374
-</sect2>
1375
-<sect2>
1507
+</sect3>
1508
+
1509
+<sect3>
1376 1510
 
1377 1511
 <title>Close all Tor/Non-Tor tabs and windows on toggle (optional)</title>
1378 1512
 
... ...
@@ -1408,9 +1542,11 @@ While this setting doesn't satisfy any Torbutton requirements, the fact that
1408 1542
 cookies are transmitted for partially typed queries does not seem desirable
1409 1543
 for Tor usage.
1410 1544
 </para>
1545
+</sect3>
1411 1546
  </sect2>
1412
-
1413 1547
  <sect2>
1548
+  <title>History and Forms Settings</title>
1549
+<sect3>
1414 1550
 <title>Isolate Access to History navigation to Tor state (crucial)</title>
1415 1551
   <para>Option: <command>extensions.torbutton.block_js_history</command></para>
1416 1552
   <para>
... ...
@@ -1448,10 +1584,10 @@ Separation</link> and (until Bug 409737 is fixed) <link linkend="isolation">Netw
1448 1584
 requirements.
1449 1585
 
1450 1586
    </para>
1451
-</sect2>
1587
+</sect3>
1452 1588
 
1453 1589
 
1454
-<sect2>
1590
+<sect3>
1455 1591
 <title>History Access Settings</title>
1456 1592
 
1457 1593
   <para>Options:
... ...
@@ -1463,8 +1599,8 @@ requirements.
1463 1599
   </simplelist>
1464 1600
   </para>
1465 1601
 
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>
1602
+<para>On Firefox 3.x, these four settings govern the behavior of the <ulink
1603
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js">components/ignore-history.js</ulink>
1468 1604
 history blocker component mentioned above. By hooking the browser's view of
1469 1605
 the history itself via the <ulink
1470 1606
 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>
... ...
@@ -1482,14 +1618,23 @@ Database</ulink> and the older Firefox 2 mechanisms.
1482 1618
 
1483 1619
 </para>
1484 1620
 
1621
+<para>
1622
+On Firefox 4, Mozilla finally <ulink
1623
+url="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector">addressed
1624
+these issues</ulink>, so we can effectively ignore the "read" pair of the
1625
+above prefs. We then only need to link the write prefs to
1626
+<command>places.history.enabled</command>, which disabled writing to the
1627
+history store while set.
1628
+</para>
1629
+
1485 1630
 <para>
1486 1631
 This setting helps to satisfy the <link
1487 1632
 linkend="state">State Separation</link> and <link
1488 1633
 linkend="disk">Disk Avoidance</link> requirements.
1489 1634
 </para>
1490 1635
 
1491
-</sect2>
1492
-<sect2>
1636
+</sect3>
1637
+<sect3>
1493 1638
 
1494 1639
 <title>Clear History During Tor Toggle (optional)</title>
1495 1640
 
... ...
@@ -1506,9 +1651,8 @@ This setting is an optional way to help satisfy the <link
1506 1651
 linkend="state">State Separation</link> requirement.
1507 1652
 </para>
1508 1653
 
1509
-</sect2>
1510
-<sect2>
1511
-
1654
+</sect3>
1655
+<sect3>
1512 1656
 <title>Block Password+Form saving during Tor/Non-Tor</title>
1513 1657
 
1514 1658
 <para>Options:
... ...
@@ -1531,8 +1675,11 @@ linkend="state">State Separation</link> and <link
1531 1675
 linkend="disk">Disk Avoidance</link> requirements.
1532 1676
 </para>
1533 1677
 
1678
+</sect3>
1534 1679
  </sect2>
1535 1680
  <sect2>
1681
+  <title>Cache Settings</title>
1682
+<sect3>
1536 1683
   <title>Block Tor disk cache and clear all cache on Tor Toggle</title>
1537 1684
 
1538 1685
   <para>Option: <command>extensions.torbutton.clear_cache</command>
... ...
@@ -1550,8 +1697,8 @@ linkend="state">State Separation</link> and <link
1550 1697
 linkend="disk">Disk Avoidance</link> requirements.
1551 1698
 </para>
1552 1699
 
1553
-</sect2>
1554
-<sect2>
1700
+</sect3>
1701
+<sect3>
1555 1702
   <title>Block disk and memory cache during Tor</title>
1556 1703
 
1557 1704
 <para>Option: <command>extensions.torbutton.block_cache</command></para>
... ...
@@ -1570,8 +1717,11 @@ linkend="state">State Separation</link> and <link
1570 1717
 linkend="disk">Disk Avoidance</link> requirements.
1571 1718
 </para>
1572 1719
 
1720
+</sect3>
1573 1721
  </sect2>
1574 1722
  <sect2>
1723
+  <title>Cookie and Auth Settings</title>
1724
+<sect3>
1575 1725
   <title>Clear Cookies on Tor Toggle</title>
1576 1726
 
1577 1727
 <para>Option: <command>extensions.torbutton.clear_cookies</command>
... ...
@@ -1593,8 +1743,8 @@ linkend="state">State Separation</link> and <link
1593 1743
 linkend="disk">Disk Avoidance</link> requirements.
1594 1744
 </para>
1595 1745
 
1596
-</sect2>
1597
-<sect2>
1746
+</sect3>
1747
+<sect3>
1598 1748
   
1599 1749
   <title>Store Non-Tor cookies in a protected jar</title>
1600 1750
 
... ...
@@ -1604,7 +1754,7 @@ linkend="disk">Disk Avoidance</link> requirements.
1604 1754
 <para>
1605 1755
 
1606 1756
 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
1757
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1608 1758
 non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
1609 1759
 before restoring the jar.
1610 1760
 </para>
... ...
@@ -1623,8 +1773,8 @@ linkend="disk">Disk Avoidance</link> requirements.
1623 1773
 </para>
1624 1774
 
1625 1775
 
1626
-</sect2>
1627
-<sect2>
1776
+</sect3>
1777
+<sect3>
1628 1778
 
1629 1779
   <title>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</title>
1630 1780
 
... ...
@@ -1634,7 +1784,7 @@ linkend="disk">Disk Avoidance</link> requirements.
1634 1784
 <para>
1635 1785
 
1636 1786
 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
1787
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink> to store
1638 1788
 both Tor and Non-Tor cookies into protected jars.
1639 1789
 </para>
1640 1790
 
... ...
@@ -1644,20 +1794,22 @@ linkend="state">State Separation</link> requirement.
1644 1794
 </para>
1645 1795
 
1646 1796
 
1647
-</sect2>
1797
+</sect3>
1648 1798
 
1799
+<!-- FIXME: If we decide to keep it, document the cookie protections dialog
1800
+-->
1649 1801
 
1650
-<sect2>
1802
+<sect3>
1651 1803
 
1652 1804
   <title>Manage My Own Cookies (dangerous)</title>
1653 1805
 
1654 1806
 <para>Options: None</para>
1655 1807
 <para>This setting disables all Torbutton cookie handling by setting the above
1656 1808
 cookie prefs all to false.</para>
1657
-</sect2>
1658
-<sect2>
1809
+</sect3>
1810
+<sect3>
1659 1811
 
1660
-<sect2>
1812
+<sect3>
1661 1813
   <title>Do not write Tor/Non-Tor cookies to disk</title>
1662 1814
   <para>Options:
1663 1815
   <simplelist>
... ...
@@ -1681,7 +1833,7 @@ This allows Torbutton to provide an option to preserve a user's
1681 1833
 cookies while still satisfying the <link linkend="disk">Disk Avoidance</link>
1682 1834
 requirement.
1683 1835
 </para>
1684
-</sect2>
1836
+</sect3>
1685 1837
 
1686 1838
 
1687 1839
   <title>Disable DOM Storage during Tor usage (crucial)</title>
... ...
@@ -1701,9 +1853,9 @@ This setting helps to satisfy the <link
1701 1853
 linkend="state">State Separation</link> requirement.
1702 1854
 </para>
1703 1855
 
1704
-</sect2>
1856
+</sect3>
1705 1857
 
1706
-<sect2>
1858
+<sect3>
1707 1859
   <title>Clear HTTP Auth on Tor Toggle (recommended)</title>
1708 1860
 <para>Option: <command>extensions.torbutton.clear_http_auth</command>
1709 1861
   </para>
... ...
@@ -1718,79 +1870,21 @@ every time Tor is toggled.
1718 1870
 This setting helps to satisfy the <link
1719 1871
 linkend="state">State Separation</link> requirement.
1720 1872
 </para>
1873
+</sect3>
1721 1874
  </sect2>
1722
-
1723
-<sect2>
1724
-
1725
-  <title>Clear cookies on Tor/Non-Tor shutdown</title>
1726
-
1727
-<para>Option: <command>extensions.torbutton.shutdown_method</command>
1728
-  </para>
1729
-
1730
-<para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1731
-cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1732
-clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1733
-for the <ulink
1734
-url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
1735
-<function>https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</function> and use <ulink
1736
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1737
-to clear out all cookies and all cookie jars upon shutdown.  </para>
1738
-<para>
1739
-This setting helps to satisfy the <link
1740
-linkend="state">State Separation</link> requirement.
1741
-</para>
1742
-
1743
-
1744
-</sect2>
1745
-<sect2>
1746
-
1747
-  <title>Reload cookie jar/clear cookies on Firefox crash</title>
1748
-  <para>Options:
1749
-  <simplelist>
1750
-    <member><command>extensions.torbutton.reload_crashed_jar</command></member>
1751
-    <member><command>extensions.torbutton.crashed</command></member>
1752
-  </simplelist>
1753
-  </para>
1754
-
1755
-  <para>This is no longer a user visible option, and is enabled by default. In
1756
-the event of a crash, the Torbutton <ulink
1757
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">components/crash-observer.js</ulink> 
1758
-  component will notify the Chrome (via the
1759
-  <command>extensions.torbutton.crashed</command> pref and a <ulink
1760
-url="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29">pref
1761
-observer</ulink> in
1762
-the chrome that listens for this update), and Torbutton will load the
1763
-  correct jar for the current Tor state via the <ulink
1764
-url="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1765
-  component.</para>
1766
-
1767
-<para>
1768
-This setting helps to satisfy the <link
1769
-linkend="state">State Separation</link> requirement in the event of Firefox
1770
-crashes.
1771
-</para>
1772
-
1773
-</sect2>
1774
-
1775
-
1776 1875
  <sect2>
1777
-  <title>On crash recovery or session restored startup, restore via: Tor, Non-Tor</title>
1876
+  <title>Startup Settings</title>
1877
+<sect3>
1878
+  <title>On Browser Startup, set Tor state to: Tor, Non-Tor</title>
1778 1879
   <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>
1880
+   <command>extensions.torbutton.restore_tor</command>
1784 1881
   </para>
1785 1882
 
1786
-  <para>This option works with the Torbutton <ulink
1787
-url="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js">crash-observer.js</ulink> 
1788
-  to set the Tor state after a crash is detected (via the 
1789
-  <command>extensions.torbutton.crashed</command> pref). To confirm for
1790
-false positives (such as session restore failures, upgrade, normal
1791
-session restore, etc), Torbutton also sets the pref
1792
-extensions.torbutton.normal_exit during
1793
-Firefox exit and checks this value as well during startup.  
1883
+  <para>This option governs what Tor state tor is loaded in to.
1884
+<function>torbutton_set_initial_state()</function> covers the case where the
1885
+browser did not crash, and <function>torbutton_crash_recover()</function>
1886
+covers the case where the <link linkend="crashobserver">crash observer</link>
1887
+detected a crash.
1794 1888
 </para>
1795 1889
 <para>
1796 1890
 
... ...
@@ -1800,33 +1894,10 @@ requirement in the event of Firefox crashes by ensuring all cookies,
1800 1894
 settings and saved sessions are reloaded from a fixed Tor state.
1801 1895
  
1802 1896
 </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>
1897
+</sect3>
1826 1898
 
1827
-</sect2>
1828 1899
 
1829
-<sect2>
1900
+<sect3>
1830 1901
   <title>Prevent session store from saving Non-Tor/Tor-loaded tabs</title>
1831 1902
 
1832 1903
   <para>Options: 
... ...
@@ -1836,10 +1907,10 @@ Firefox exit and checks this value as well during startup.
1836 1907
   </simplelist>
1837 1908
   </para>
1838 1909
 
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.
1910
+  <para>If these options are enabled, the <link
1911
+linkend="tbsessionstore">tbSessionStore.js</link> component uses the session
1912
+store listeners to filter out the appropriate tabs before writing the session
1913
+store data to disk.
1843 1914
 </para>
1844 1915
 <para>
1845 1916
 This setting helps to satisfy the <link linkend="disk">Disk Avoidance</link>
... ...
@@ -1849,9 +1920,37 @@ crashes.
1849 1920
 
1850 1921
 </para>
1851 1922
 
1923
+</sect3>
1852 1924
  </sect2>
1925
+ <sect2>
1926
+  <title>Shutdown Settings</title>
1927
+<sect3>
1928
+
1929
+  <title>Clear cookies on Tor/Non-Tor shutdown</title>
1930
+
1931
+<para>Option: <command>extensions.torbutton.shutdown_method</command>
1932
+  </para>
1853 1933
 
1934
+<para> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1935
+cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1936
+clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1937
+for the <ulink
1938
+url="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown">quit-application-granted</ulink> event in
1939
+<link linkend="crashobserver">crash-observer.js</link> and use <ulink
1940
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js">@torproject.org/cookie-jar-selector;2</ulink>
1941
+to clear out all cookies and all cookie jars upon shutdown.
1942
+</para>
1943
+<para>
1944
+This setting helps to satisfy the <link
1945
+linkend="state">State Separation</link> requirement.
1946
+</para>
1947
+
1948
+
1949
+</sect3>
1950
+ </sect2>
1854 1951
  <sect2>
1952
+  <title>Header Settings</title>
1953
+<sect3>
1855 1954
 
1856 1955
   <title>Set user agent during Tor usage (crucial)</title>
1857 1956
   <para>Options:
... ...
@@ -1900,8 +1999,8 @@ linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1900 1999
 </para>
1901 2000
 
1902 2001
 
1903
-</sect2>
1904
-<sect2>
2002
+</sect3>
2003
+<sect3>
1905 2004
 
1906 2005
   <title>Spoof US English Browser</title>
1907 2006
 <para>Options:
... ...
@@ -1927,26 +2026,28 @@ linkend="setpreservation">Anonymity Set Preservation</link> and <link
1927 2026
 linkend="location">Location Neutrality</link> requirements.
1928 2027
 </para>
1929 2028
 
1930
-</sect2>
1931
-<sect2>
2029
+</sect3>
1932 2030
 
1933
-  <title>Don't send referrer during Tor Usage</title>
2031
+<sect3>
2032
+  <title>Referer Spoofing Options</title>
1934 2033
 
1935
-<para>Option: <command>extensions.torbutton.disable_referer</command>
2034
+<para>Option: <command>extensions.torbutton.refererspoof</command>
1936 2035
 </para>
1937 2036
 
1938 2037
 <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>
2038
+This option variable has three values. If it is 0, "smart" referer spoofing is
2039
+enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is
2040
+sent. The default value is 1. The smart referer spoofing is implemented by the
2041
+<link linkend="refspoofer">torRefSpoofer</link> component.
1943 2042
 
2043
+</para>
1944 2044
 <para>
1945 2045
 This setting also does not directly satisfy any Torbutton requirement, but
1946 2046
 some may desire to mask their referrer for general privacy concerns.
1947 2047
 </para>
1948
-</sect2>
1949
-<sect2>
2048
+</sect3>
2049
+
2050
+<sect3>
1950 2051
   <title>Strip platform and language off of Google Search Box queries</title>
1951 2052
 
1952 2053
 <para>Option: <command>extensions.torbutton.fix_google_srch</command>
... ...
@@ -1965,9 +2066,9 @@ platform information. This setting strips off that info while Tor is enabled.
1965 2066
 This setting helps Torbutton to fulfill its <link
1966 2067
 linkend="setpreservation">Anonymity Set Preservation</link> requirement.
1967 2068
 </para>
1968
-</sect2>
2069
+</sect3>
1969 2070
 
1970
-<sect2>
2071
+<sect3>
1971 2072
   <title>Automatically use an alternate search engine when presented with a
1972 2073
 Google Captcha</title>
1973 2074
 
... ...
@@ -2001,14 +2102,14 @@ As a result, we've implemented this option as an <ulink
2001 2102
 url="https://developer.mozilla.org/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">'http-on-modify-request'</ulink>
2002 2103
 http observer to optionally redirect banned or captcha-triggering Google
2003 2104
 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
2105
+options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. These are
2005 2106
 encoded in the preferences
2006
-<command>extensions.torbutton.redir_url.[1-4]</command>.
2107
+<command>extensions.torbutton.redir_url.[1-5]</command>.
2007 2108
 
2008 2109
 </para>
2009
-</sect2>
2110
+</sect3>
2010 2111
 
2011
-<sect2>
2112
+<sect3>
2012 2113
 
2013 2114
   <title>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</title>
2014 2115
 
... ...
@@ -2023,7 +2124,7 @@ encoded in the preferences
2023 2124
 These settings govern if Torbutton attempts to isolate the user's SSL
2024 2125
 certificates into separate jars for each Tor state. This isolation is
2025 2126
 implemented in <function>torbutton_jar_certs()</function> in <ulink
2026
-url="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
2127
+url="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js">chrome/content/torbutton.js</ulink>,
2027 2128
 which calls <function>torbutton_jar_cert_type()</function> and
2028 2129
 <function>torbutton_unjar_cert_type()</function> for each certificate type in
2029 2130
 the <ulink
... ...
@@ -2051,6 +2152,9 @@ is currently not exposed via the preferences UI.
2051 2152
 
2052 2153
 </para>
2053 2154
 
2155
+</sect3>
2156
+
2157
+
2054 2158
 </sect2>
2055 2159
 </sect1>
2056 2160
 
... ...
@@ -2070,34 +2174,6 @@ they are:
2070 2174
 
2071 2175
    </para>
2072 2176
    <orderedlist>
2073
-
2074
-<!--
2075
-
2076
-XXX: We should just consider this one fixed. FF3.0 is pretty much at EOL.
2077
-
2078
-   <listitem><ulink
2079
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=392274">Bug 392274 - Timezone
2080
-config/chrome API</ulink>
2081
-   <para>
2082
-
2083
-The lack of a config or API to configure the timezone requires Torbutton to
2084
-<link linkend="jshooks">insert client content window javascript</link> to hook
2085
-the Date object. Additionally, a way to <ulink
2086
-url="http://pseudo-flaw.net/tor/torbutton/unmask-date.html">remove the Date
2087
-hooks</ulink> was discovered by Greg Fleischer. Worse, on Firefox 3,
2088
-javascript sandboxing prevents most of the javascript hooks from being
2089
-installed, including the Date hooks. On Windows and Linux, you can set the TZ
2090
-environment variable to "UTC" as a workaround. Firefox will obey this
2091
-environment variable for your Timezone on those platforms, but on Windows this
2092
-does not take effect until browser restart. A fix for this has landed in
2093
-Firefox 3.5, but still has not been backported to Firefox 3.0. The lack of an
2094
-easy way to reliably spoof the timezone interferes with Torbutton's ability to
2095
-fulfill its <link linkend="location">Location Neutrality</link> requirement.
2096
-
2097
-
2098
-   </para>
2099
-   </listitem>
2100
--->
2101 2177
     <listitem><ulink
2102 2178
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=429070">Bug 429070 - exposing
2103 2179
 Components.interfaces to untrusted content leaks information about installed
... ...
@@ -2134,11 +2210,16 @@ provides a large amount of identifiable information</ulink>
2134 2210
 As <link linkend="fingerprinting">mentioned above</link>, a large amount of
2135 2211
 information is available from <ulink
2136 2212
 url="http://developer.mozilla.org/en/docs/DOM:window.screen">window.screen</ulink>.
2213
+The most sensitive data to anonymity is actually that which is not used in
2214
+rendering - such as desktop resolution, and window decoration size.
2137 2215
 Currently, there is no way to obscure this information without Javascript
2138
-hooking. This bug is a feature request to provide some other method to change
2139
-these values. This bug interferes with Torbutton's ability to fulfill its
2140
-<link linkend="setpreservation">Anonymity Set Preservation</link>
2141
-requirement.
2216
+hooking. In addition, many of this same desktop and window decoration
2217
+resolution information is available via <ulink
2218
+url="https://developer.mozilla.org/En/CSS/Media_queries">CSS Media
2219
+Queries</ulink>, so perhaps some more lower-level rendering controls or
2220
+preferences need to be provided. These issues interfere with Torbutton's
2221
+ability to fulfill its <link linkend="setpreservation">Anonymity Set
2222
+Preservation</link> requirement.
2142 2223
 
2143 2224
    </para>
2144 2225
    </listitem>
... ...
@@ -2160,7 +2241,29 @@ feature.
2160 2241
 
2161 2242
       </para>
2162 2243
      </listitem>
2163
-
2244
+     <listitem>Give more visibility into and control over TLS
2245
+negotiation
2246
+     <para>
2247
+
2248
+There are several <ulink
2249
+url="https://trac.torproject.org/projects/tor/ticket/2482">TLS issues
2250
+impacting Torbutton security</ulink>. It is not clear if these should be one
2251
+Firefox bug or several, but in particular we need better control over various
2252
+aspects of TLS connections. Firefox currently provides no observer capable of
2253
+extracting TLS parameters or certificates early enough to cancel a TLS
2254
+request. We would like to be able to provide <ulink
2255
+url="https://www.eff.org/https-everywhere">HTTPS-Everywhere</ulink> users with
2256
+the ability to <ulink
2257
+url="https://trac.torproject.org/projects/tor/wiki/HTTPSEverywhere/SSLObservatorySubmission">have
2258
+their certificates audited</ulink> by a <ulink
2259
+url="http://www.networknotary.org/">Perspectives</ulink>-style set of
2260
+notaries. The problem with this is that the API observer points do not exist
2261
+for any Firefox addon to actually block authentication token submission over a
2262
+TLS channel, so every addon to date (including Perspectives) is actually
2263
+providing users with notification *after* their authentication tokens have
2264
+already been compromised. This obviously needs to be fixed.
2265
+     </para>
2266
+     </listitem>
2164 2267
      <listitem><ulink
2165 2268
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=575230">Bug 575230 - Provide option to
2166 2269
 reduce precision of Date()</ulink>
... ...
@@ -2180,6 +2283,18 @@ linkend="setpreservation">Anonymity Set Preservation</link> requirement.
2180 2283
 
2181 2284
       </para>
2182 2285
      </listitem>
2286
+    <listitem><ulink
2287
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=122752">SOCKS
2288
+Username/Password Support</ulink>
2289
+    <para>
2290
+We need <ulink url="https://developer.mozilla.org/en/nsIProxyInfo">Firefox
2291
+APIs</ulink> or about:config settings to control the SOCKS Username and
2292
+Password fields. The reason why we need this support is to utilize an (as yet
2293
+unimplemented) scheme to separate Tor traffic based <ulink
2294
+url="https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/171-separate-streams.txt">on
2295
+SOCKS username/password</ulink>.
2296
+    </para>
2297
+    </listitem>
2183 2298
 
2184 2299
      <listitem><ulink
2185 2300
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=409737">Bug 409737 -
... ...
@@ -2230,7 +2345,7 @@ The following bugs impact Torbutton and similar extensions' functionality.
2230 2345
 
2231 2346
    <listitem><ulink
2232 2347
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=445696">Bug 445696 -
2233
-Extensions cannot determine if firefox is fullScreen</ulink>
2348
+Extensions cannot determine if Firefox is full screen</ulink>
2234 2349
    <para>
2235 2350
 
2236 2351
 The windowState property of <ulink
... ...
@@ -2241,6 +2356,22 @@ to resize maximized and minimized windows when it should not.
2241 2356
    </para>
2242 2357
    </listitem>
2243 2358
    <listitem><ulink
2359
+url="https://bugzilla.mozilla.org/show_bug.cgi?id=629820">nsIContentPolicy::shouldLoad not
2360
+called for web request in Firefox Mobile</ulink>
2361
+    <para>
2362
+
2363
+The new <ulink
2364
+url="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis">Electrolysis</ulink>
2365
+multiprocess system appears to have some pretty rough edge cases with respect
2366
+to registering XPCOM category managers such as the nsIContentPolicy, which
2367
+make it difficult to do a straight-forward port of Torbutton or
2368
+HTTPS-Everywhere to Firefox Mobile.  It probably also has similar issues with
2369
+wrapping existing <link linkend="hookedxpcom">Firefox XPCOM components</link>,
2370
+which will also cause more problems for porting Torbutton.
2371
+
2372
+    </para>
2373
+   </listitem>
2374
+   <listitem><ulink
2244 2375
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=290456">Bug 290456 -
2245 2376
 Block/clear Flash MX "cookies" as well</ulink>
2246 2377
    <para>
... ...
@@ -2268,6 +2399,8 @@ FoxyProxy) difficult to impossible to implement securely.
2268 2399
 
2269 2400
    </para>
2270 2401
    </listitem>
2402
+<!--
2403
+FIXME: This doesn't really apply anymore.
2271 2404
    <listitem><ulink
2272 2405
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=418321">Bug 418321 -
2273 2406
 Components do not expose disk interfaces</ulink>
... ...
@@ -2281,6 +2414,7 @@ some of them involve disabling functionality during Tor usage.
2281 2414
 
2282 2415
    </para>
2283 2416
    </listitem>
2417
+-->
2284 2418
 
2285 2419
 <!--
2286 2420
 FIXME: Need to use new observer methods if possible
... ...
@@ -2434,27 +2568,6 @@ Williams.
2434 2568
 
2435 2569
      </para>
2436 2570
      </listitem>
2437
-<!--
2438
-
2439
-XXX: This is likely fixed with nsICrypto.logout()
2440
-
2441
-     <listitem><ulink
2442
-url="https://bugzilla.mozilla.org/show_bug.cgi?id=448747">Bug 448747 -
2443
-Provide Mechanism to clear TLS Session IDs</ulink>
2444
-     <para>
2445
-
2446
-As <link linkend="browseroverlay">mentioned above</link>, Torbutton currently
2447
-toggles <command>security.enable_ssl2</command> to clear the SSL
2448
-Session ID cache via the pref observer at <ulink
2449
-url="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134">nsNSSComponent.cpp
2450
-line 2134</ulink>. This is an arcane and potentially fragile fix. It would be
2451
-better if there were a more standard interface for accomplishing the same
2452
-thing.
2453
-
2454
-     </para>
2455
-     </listitem>
2456
--->
2457
-
2458 2571
    <listitem><ulink
2459 2572
 url="https://bugzilla.mozilla.org/show_bug.cgi?id=419598">Bug 419598 - 'var
2460 2573
 Date' is deletable</ulink>
... ...
@@ -1,10 +1,9 @@
1 1
 <?xml version="1.0" encoding="UTF-8"?>
2 2
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Torbutton Design Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="Torbutton Design Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>Torbutton Design Documentation</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Perry</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">Mar 25 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2940331">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2955313">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2972601">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2974988">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2976801">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#browseroverlay">3.1. Browser Overlay - torbutton.xul</a></span></dt><dt><span class="sect2"><a href="#id2959444">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2952051">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2943135">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2973670">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2975844">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2954530">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2971938">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2967115">5.1. Test Settings</a></span></dt><dt><span class="sect2"><a href="#plugins">5.2. Disable plugins on Tor Usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2951289">5.3. Isolate Dynamic Content to Tor State (crucial)</a></span></dt><dt><span class="sect2"><a href="#jshooks">5.4. Hook Dangerous Javascript</a></span></dt><dt><span class="sect2"><a href="#id2960649">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2952949">5.6. Disable Updates During Tor</a></span></dt><dt><span class="sect2"><a href="#id2936606">5.7. Redirect Torbutton Updates Via Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936650">5.8. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936689">5.9. Disable livemarks updates during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936761">5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2936833">5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2936914">5.12. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2936998">5.13. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2937111">5.14. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2978657">5.15. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2978718">5.16. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2978768">5.17. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2978820">5.18. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2978871">5.19. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2978928">5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2978967">5.21. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2978982">5.22. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2979086">5.23. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2979123">5.24. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id2979178">5.25. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id2979253">5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2979325">5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id2979384">5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id2979449">5.29. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2979623">5.30. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id2979716">5.31. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id2979756">5.32. Strip platform and language off of Google Search Box queries</a></span></dt><dt><span class="sect2"><a href="#id2979797">5.33. Automatically use an alternate search engine when presented with a
4
-Google Captcha</a></span></dt><dt><span class="sect2"><a href="#id2979878">5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#FirefoxSecurity">6.1. Bugs impacting security</a></span></dt><dt><span class="sect2"><a href="#FirefoxWishlist">6.2. Bugs blocking functionality</a></span></dt><dt><span class="sect2"><a href="#FirefoxMiscBugs">6.3. Low Priority Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id2980994">7.2. Multi-state testing</a></span></dt><dt><span class="sect2"><a href="#HackTorbutton">7.3. Active testing (aka How to Hack Torbutton)</a></span></dt></dl></dd></dl></div><div class="sect1" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2940331"></a>1. Introduction</h2></div></div></div><p>
3
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Torbutton Design Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="Torbutton Design Documentation"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>Torbutton Design Documentation</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Mike</span> <span class="surname">Perry</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">Apr 3 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2632653">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt><dt><span class="sect2"><a href="#requirements">1.2. Torbutton Requirements</a></span></dt><dt><span class="sect2"><a href="#layout">1.3. Extension Layout</a></span></dt></dl></dd><dt><span class="sect1"><a href="#components">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#hookedxpcom">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2657921">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2636893">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2658833">3.1. XUL Windows and Overlays</a></span></dt><dt><span class="sect2"><a href="#id2655137">3.2. Major Chrome Observers</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2657565">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2653926">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2652911">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2647095">4.3. Settings Update</a></span></dt><dt><span class="sect2"><a href="#preferences">4.4. Firefox preferences touched during Toggle</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2659431">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2661813">5.1. Proxy Settings</a></span></dt><dt><span class="sect2"><a href="#id2660939">5.2. Dynamic Content Settings</a></span></dt><dt><span class="sect2"><a href="#id2670963">5.3. History and Forms Settings</a></span></dt><dt><span class="sect2"><a href="#id2671276">5.4. Cache Settings</a></span></dt><dt><span class="sect2"><a href="#id2671385">5.5. Cookie and Auth Settings</a></span></dt><dt><span class="sect2"><a href="#id2671698">5.6. Startup Settings</a></span></dt><dt><span class="sect2"><a href="#id2671812">5.7. Shutdown Settings</a></span></dt><dt><span class="sect2"><a href="#id2671872">5.8. Header Settings</a></span></dt></dl></dd><dt><span class="sect1"><a href="#FirefoxBugs">6. Relevant Firefox Bugs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#FirefoxSecurity">6.1. Bugs impacting security</a></span></dt><dt><span class="sect2"><a href="#FirefoxWishlist">6.2. Bugs blocking functionality</a></span></dt><dt><span class="sect2"><a href="#FirefoxMiscBugs">6.3. Low Priority Bugs</a></span></dt></dl></dd><dt><span class="sect1"><a href="#TestPlan">7. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">7.1. Single state testing</a></span></dt><dt><span class="sect2"><a href="#id2673409">7.2. Multi-state testing</a></span></dt><dt><span class="sect2"><a href="#HackTorbutton">7.3. Active testing (aka How to Hack Torbutton)</a></span></dt></dl></dd></dl></div><div class="sect1" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2632653"></a>1. Introduction</h2></div></div></div><p>
5 4
 
6 5
 This document describes the goals, operation, and testing procedures of the
7
-Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
6
+Torbutton Firefox extension. It is current as of Torbutton 1.3.2.
8 7
 
9 8
   </p><div class="sect2" title="1.1. Adversary Model"><div class="titlepage"><div><div><h3 class="title"><a id="adversary"></a>1.1. Adversary Model</h3></div></div></div><p>
10 9
 
... ...
@@ -82,7 +81,7 @@ thus allowing the adversary to correlate Tor and Non-Tor activity and reveal
82 81
 a user's non-Tor IP address. Javascript
83 82
 also allows the adversary to execute <a class="ulink" href="http://whattheinternetknowsaboutyou.com/" target="_top">history disclosure attacks</a>:
84 83
 to query the history via the different attributes of 'visited' links to search
85
-for particular google queries, sites, or even to <a class="ulink" href="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/" target="_top">profile
84
+for particular Google queries, sites, or even to <a class="ulink" href="http://www.mikeonads.com/2008/07/13/using-your-browser-url-history-estimate-gender/" target="_top">profile
86 85
 users based on gender and other classifications</a>. Finally,
87 86
 Javascript can be used to query the user's timezone via the
88 87
 <code class="function">Date()</code> object, and to reduce the anonymity set by querying
... ...
@@ -140,7 +139,11 @@ For illustration, let's perform a
140 139
 back-of-the-envelope calculation on the number of anonymity sets for just the
141 140
 resolution information available in the <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window" target="_top">window</a> and
142 141
 <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>
143
-objects. Browser window resolution information provides something like
142
+objects.
143
+
144
+
145
+
146
+Browser window resolution information provides something like
144 147
 (1280-640)*(1024-480)=348160 different anonymity sets. Desktop resolution
145 148
 information contributes about another factor of 5 (for about 5 resolutions in
146 149
 typical use). In addition, the dimensions and position of the desktop taskbar
... ...
@@ -156,22 +159,16 @@ Multiply this all out, and you have (1280-640)*(1024-480)*5*5*8*9 ~=
156 159
 2<sup>29</sup>, or a 29 bit identifier based on resolution
157 160
 information alone. </p><p>
158 161
 
159
-Of course, this space is non-uniform and prone to incremental changes.
160
-However, if a bit vector space consisting of the above extracted attributes
161
-were used instead of the hash approach from <a class="ulink" href="http://mandark.fr/0x000000/articles/Total_Recall_On_Firefox..html" target="_top">The Hacker
162
-Webzine article above</a>, minor changes in browser window resolution will
163
-no longer generate totally new identifiers. 
164
-
165
-</p><p>
166
-
167
-To add insult to injury, <a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">chrome URL disclosure
168
-attacks</a> mean that each and every extension on <a class="ulink" href="https://addons.mozilla.org" target="_top">addons.mozilla.org</a> adds another bit
169
-to that 2<sup>29</sup>. With hundreds of popular extensions
170
-and thousands of extensions total, it is easy to see that this sort of
171
-information is an impressively powerful identifier if used properly by a
172
-competent and determined adversary such as an ad network.  Again, a
173
-nearest-neighbor bit vector space approach here would also gracefully handle
174
-incremental changes to installed extensions.
162
+Of course, this space is non-uniform in user density and prone to incremental
163
+changes. The <a class="ulink" href="https://wiki.mozilla.org/Fingerprinting#Data" target="_top">Panopticlick study
164
+done</a> by the EFF attempts to measure the actual entropy - the number of
165
+identifying bits of information encoded in browser properties.  Their result
166
+data is definitely useful, and the metric is probably the appropriate one for
167
+determining how identifying a particular browser property is. However, some
168
+quirks of their study means that they do not extract as much information as
169
+they could from display information: they only use desktop resolution (which
170
+Torbutton reports as the window resolution) and do not attempt to infer the
171
+size of toolbars.
175 172
 
176 173
 </p></li><li class="listitem"><span class="command"><strong>Remotely or locally exploit browser and/or
177 174
 OS</strong></span><p>
... ...
@@ -232,33 +229,18 @@ obsolete and deprecated interfaces and has proved to be less than
232 229
 stable.</p><p>'Chrome' is a combination of XML and Javascript used to describe a window.
233 230
 Extensions are allowed to create 'overlays' that are 'bound' to existing XML
234 231
 window definitions, or they can create their own windows. The DTD for this XML
235
-is called <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XUL</a>.</p></div></div><div class="sect1" title="2. Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2955313"></a>2. Components</h2></div></div></div><p>
232
+is called <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XUL</a>.</p></div></div><div class="sect1" title="2. Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="components"></a>2. Components</h2></div></div></div><p>
236 233
 
237 234
 Torbutton installs components for two purposes: hooking existing components to
238 235
 reimplement their interfaces; and creating new components that provide
239 236
 services to other pieces of the extension.
240 237
 
241
-  </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2972601"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some
238
+  </p><div class="sect2" title="2.1. Hooked Components"><div class="titlepage"><div><div><h3 class="title"><a id="hookedxpcom"></a>2.1. Hooked Components</h3></div></div></div><p>Torbutton makes extensive use of Contract ID hooking, and implements some
242 239
 of its own standalone components as well.  Let's discuss the hooked components
243
-first.</p><div class="sect3" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js"><div class="titlepage"><div><div><h4 class="title"><a id="sessionstore"></a><a class="ulink" href="http://developer.mozilla.org/en/docs/nsISessionStore" target="_top">@mozilla.org/browser/sessionstore;1</a> -
244
-<a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.js" target="_top">components/nsSessionStore36.js</a></h4></div></div></div><p>These components address the <a class="link" href="#disk">Disk Avoidance</a>
245
-requirements of Torbutton. As stated in the requirements, Torbutton needs to
246
-prevent Tor tabs from being written to disk by the Firefox session store for a
247
-number of reasons, primary among them is the fact that Firefox can crash at
248
-any time, and a restart can cause you to fetch tabs in the incorrect Tor
249
-state.</p><p>These components illustrate a complication with Firefox hooking: you can
250
-only hook member functions of a class if they are published in an
251
-interface that the class implements. Unfortunately, the sessionstore has no
252
-published interface that is amenable to disabling the writing out of Tor tabs
253
-in specific. As such, Torbutton had to include the <span class="emphasis"><em>entire</em></span>
254
-nsSessionStore from both Firefox 2.0, 3.0, 3.5 and 3.6
255
-with a couple of modifications to prevent tabs that were loaded with Tor
256
-enabled from being written to disk, and some version detection code to
257
-determine which component to load. The <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore36.diff" target="_top">diff against the original session
258
-store</a> is included in the git repository.</p></div><div class="sect3" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="appblocker"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1" target="_top">@mozilla.org/uriloader/external-protocol-service;1
240
+first.</p><div class="sect3" title="@mozilla.org/uriloader/external-protocol-service;1 , @mozilla.org/uriloader/external-helper-app-service;1, and @mozilla.org/mime;1 - components/external-app-blocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="appblocker"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-protocol-service%3B1" target="_top">@mozilla.org/uriloader/external-protocol-service;1
259 241
 </a>, <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/uriloader/external-helper-app-service%3B1" target="_top">@mozilla.org/uriloader/external-helper-app-service;1</a>,
260 242
 and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/mime%3B1" target="_top">@mozilla.org/mime;1</a>
261
-- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/external-app-blocker.js" target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>
243
+- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/external-app-blocker.js" target="_top">components/external-app-blocker.js</a></h4></div></div></div><p>
262 244
 Due to <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=440892" target="_top">440892</a> allowing Firefox 3.x to automatically launch some
263 245
 applications without user intervention, Torbutton had to wrap the three
264 246
 components involved in launching external applications to provide user
... ...
@@ -267,22 +249,8 @@ do not obey proxy settings, they can be manipulated to automatically connect
267 249
 back to arbitrary servers outside of Tor with no user intervention. Fixing
268 250
 this issue helps to satisfy Torbutton's <a class="link" href="#proxy">Proxy
269 251
 Obedience</a> Requirement.
270
- </p></div><div class="sect3" title="@mozilla.org/browser/sessionstartup;1 - components/crash-observer.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2951475"></a><a class="ulink" href="http://lxr.mozilla.org/seamonkey/source/browser/components/sessionstore/src/nsSessionStartup.js" target="_top">@mozilla.org/browser/sessionstartup;1</a> -
271
-    <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">components/crash-observer.js</a></h4></div></div></div><p>This component wraps the Firefox Session Startup component that is in
272
-charge of <a class="ulink" href="http://developer.mozilla.org/en/docs/Session_store_API" target="_top">restoring saved
273
-sessions</a>. The wrapper's only job is to intercept the
274
-<code class="function">doRestore()</code> function, which is called by Firefox if it is determined that the
275
-browser crashed and the session needs to be restored. The wrapper notifies the
276
-Torbutton chrome that the browser crashed by setting the pref
277
-<span class="command"><strong>extensions.torbutton.crashed</strong></span>, or that it is a normal
278
-startup via the pref <span class="command"><strong>extensions.torbutton.noncrashed</strong></span>. The Torbutton Chrome <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">listens for a
279
-preference change</a> for this value and then does the appropriate cleanup. This
280
-includes setting the Tor state to the one the user selected for crash recovery
281
-in the preferences window (<span class="command"><strong>extensions.torbutton.restore_tor</strong></span>), and
282
-restoring cookies for the corresponding cookie jar, if it exists.</p><p>By performing this notification, this component assists in the 
283
-<a class="link" href="#proxy">Proxy Obedience</a>, and <a class="link" href="#isolation">Network Isolation</a> requirements.
284
-</p></div><div class="sect3" title="@mozilla.org/browser/global-history;2 - components/ignore-history.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2971802"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2" target="_top">@mozilla.org/browser/global-history;2</a>
285
-- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js" target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin Jackson</a> as a method for defeating
252
+ </p></div><div class="sect3" title="@mozilla.org/browser/global-history;2 - components/ignore-history.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2644921"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2" target="_top">@mozilla.org/browser/global-history;2</a>
253
+- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js" target="_top">components/ignore-history.js</a></h4></div></div></div><p>This component was contributed by <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin Jackson</a> as a method for defeating
286 254
 CSS and Javascript-based methods of history disclosure. The global-history
287 255
 component is what is used by Firefox to determine if a link was visited or not
288 256
 (to apply the appropriate style to the link). By hooking the <a class="ulink" href="https://developer.mozilla.org/en/nsIGlobalHistory2#isVisited.28.29" target="_top">isVisited</a>
... ...
@@ -292,9 +260,12 @@ added or being displayed as visited, depending on the Tor state and the user's
292 260
 preferences.
293 261
 </p><p>
294 262
 This component helps satisfy the <a class="link" href="#state">State Separation</a>
295
-and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton.
263
+and <a class="link" href="#disk">Disk Avoidance</a> requirements of Torbutton. It
264
+is only needed for Firefox 3.x. On Firefox 4, we omit this component in favor
265
+of the <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">built-in
266
+history protections</a>.
296 267
 </p></div><div class="sect3" title="@mozilla.org/browser/livemark-service;2 - components/block-livemarks.js"><div class="titlepage"><div><div><h4 class="title"><a id="livemarks"></a><a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/livemark-service;2" target="_top">@mozilla.org/browser/livemark-service;2</a>
297
-- <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/block-livemarks.js" target="_top">components/block-livemarks.js</a></h4></div></div></div><p>
268
+- <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/block-livemarks.js" target="_top">components/block-livemarks.js</a></h4></div></div></div><p>
298 269
 
299 270
 The <a class="ulink" href="http://www.mozilla.com/en-US/firefox/livebookmarks.html" target="_top">livemark</a> service
300 271
 is started by a timer that runs 5 seconds after Firefox
... ...
@@ -306,18 +277,19 @@ firing in the event the browser starts in Tor mode.
306 277
 This component helps satisfy the <a class="link" href="#isolation">Network
307 278
 Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
308 279
 Preservation</a> requirements.
309
-</p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2974988"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the
280
+</p></div></div><div class="sect2" title="2.2. New Components"><div class="titlepage"><div><div><h3 class="title"><a id="id2657921"></a>2.2. New Components</h3></div></div></div><p>Torbutton creates four new components that are used throughout the
310 281
 extension. These components do not hook any interfaces, nor are they used
311
-anywhere besides Torbutton itself.</p><div class="sect3" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2951018"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2
282
+anywhere besides Torbutton itself.</p><div class="sect3" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js"><div class="titlepage"><div><div><h4 class="title"><a id="cookiejar"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2
312 283
 - components/cookie-jar-selector.js</a></h4></div></div></div><p>The cookie jar selector (also based on code from <a class="ulink" href="http://www.collinjackson.com/" target="_top">Collin
313 284
 Jackson</a>) is used by the Torbutton chrome to switch between
314
-Tor and Non-Tor cookies. Its operations are simple: sync cookies to disk, then
315
-move the current cookies.txt file to the appropriate backup location
316
-(cookies-tor.txt or cookies-nontor.txt), and then moving the other cookie jar
317
-into place.</p><p>
285
+Tor and Non-Tor cookies. It stores an XML representation of the current
286
+cookie state in memory and/or on disk. When Tor is toggled, it syncs the
287
+current cookies to this XML store, and then loads the cookies for the other
288
+state from the XML store.
289
+</p><p>
318 290
 This component helps to address the <a class="link" href="#state">State
319 291
 Isolation</a> requirement of Torbutton.
320
-</p></div><div class="sect3" title="@torproject.org/torbutton-logger;1 - components/torbutton-logger.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2975569"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1
292
+</p></div><div class="sect3" title="@torproject.org/torbutton-logger;1 - components/torbutton-logger.js"><div class="titlepage"><div><div><h4 class="title"><a id="id2670270"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torbutton-logger.js" target="_top">@torproject.org/torbutton-logger;1
321 293
 - components/torbutton-logger.js</a></h4></div></div></div><p>The torbutton logger component allows on-the-fly redirection of torbutton
322 294
 logging messages to either Firefox stderr
323 295
 (<span class="command"><strong>extensions.torbutton.logmethod=0</strong></span>), the Javascript error console
... ...
@@ -325,7 +297,7 @@ logging messages to either Firefox stderr
325 297
 available - <span class="command"><strong>extensions.torbutton.logmethod=2</strong></span>). It also allows you to
326 298
 change the loglevel on the fly by changing
327 299
 <span class="command"><strong>extensions.torbutton.loglevel</strong></span> (1-5, 1 is most verbose).
328
-</p></div><div class="sect3" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1
300
+</p></div><div class="sect3" title="@torproject.org/content-window-mapper;1 - components/window-mapper.js"><div class="titlepage"><div><div><h4 class="title"><a id="windowmapper"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/window-mapper.js" target="_top">@torproject.org/content-window-mapper;1
329 301
 - components/window-mapper.js</a></h4></div></div></div><p>Torbutton tags Firefox <a class="ulink" href="https://developer.mozilla.org/en/XUL_Tutorial/Tabboxes" target="_top">tabs</a> with a special variable that indicates the Tor
330 302
 state the tab was most recently used under to fetch a page. The problem is
331 303
 that for many Firefox events, it is not possible to determine the tab that is
... ...
@@ -336,7 +308,36 @@ window</a>. It does this by traversing all windows and all browsers, until it
336 308
 finds the browser with the requested <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser#p-contentWindow" target="_top">contentWindow</a> element. Since the content policy
337 309
 and page loading in general can generate hundreds of these lookups, this
338 310
 result is cached inside the component.
339
-</p></div><div class="sect3" title="@torproject.org/cssblocker;1 - components/cssblocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
311
+</p></div><div class="sect3" title="@torproject.org/crash-observer;1"><div class="titlepage"><div><div><h4 class="title"><a id="crashobserver"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/crash-observer.js" target="_top">@torproject.org/crash-observer;1</a></h4></div></div></div><p>
312
+
313
+This component detects when Firefox crashes by altering Firefox prefs during
314
+runtime and checking for the same values at startup. It <a class="ulink" href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIPrefService#savePrefFile()" target="_top">synchronizes
315
+the preference service</a> to ensure the altered prefs are written to disk
316
+immediately.
317
+
318
+  </p></div><div class="sect3" title="@torproject.org/torbutton-ss-blocker;1"><div class="titlepage"><div><div><h4 class="title"><a id="tbsessionstore"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/tbSessionStore.js" target="_top">@torproject.org/torbutton-ss-blocker;1</a></h4></div></div></div><p>
319
+
320
+This component subscribes to the Firefox <a class="ulink" href="https://developer.mozilla.org/en/Observer_Notifications#Session_Store" target="_top">sessionstore-state-write</a>
321
+observer event to filter out URLs from tabs loaded during Tor, to prevent them
322
+from being written to disk. To do this, it checks the
323
+<span class="command"><strong>__tb_tor_fetched</strong></span> tag of tab objects before writing them out. If
324
+the tag is from a blocked Tor state, the tab is not written to disk.  This is
325
+a rather expensive operation that involves potentially very large JSON
326
+evaluations and object tree traversals, but it preferable to replacing the
327
+Firefox session store with our own implementation, which is what was done in
328
+years past.
329
+
330
+  </p></div><div class="sect3" title="@torproject.org/torRefSpoofer;1"><div class="titlepage"><div><div><h4 class="title"><a id="refspoofer"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/torRefSpoofer.js" target="_top">@torproject.org/torRefSpoofer;1</a></h4></div></div></div><p>
331
+This component handles optional referrer spoofing for Torbuton. It implements a
332
+form of "smart" referer spoofing using <a class="ulink" href="https://developer.mozilla.org/en/Setting_HTTP_request_headers" target="_top">http-on-modify-request</a>
333
+to modify the Referrer header. The code sends the default browser referrer
334
+header only if the destination domain is a suffix of the source, or if the
335
+source is a suffix of the destination. Otherwise, it sends no referer. This
336
+strange suffix logic is used as a heuristic: some rare sites on the web block
337
+requests without proper referer headers, and this logic is an attempt to cater
338
+to them. Unfortunately, it may not be enough. For example, google.fr will not
339
+send a referer to google.com using this logic. Hence, it is off by default.
340
+ </p></div><div class="sect3" title="@torproject.org/cssblocker;1 - components/cssblocker.js"><div class="titlepage"><div><div><h4 class="title"><a id="contentpolicy"></a><a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1
340 341
 - components/cssblocker.js</a></h4></div></div></div><p>This is a key component to Torbutton's security measures. When Tor is
341 342
 toggled, Javascript is disabled, and pages are instructed to stop loading.
342 343
 However, CSS is still able to perform network operations by loading styles for
... ...
@@ -353,14 +354,14 @@ Otherwise, it is allowed.</p> This helps to achieve the <a class="link" href="#i
353 354
 Isolation</a> requirements of Torbutton.
354 355
 
355 356
 <p>In addition, the content policy also blocks website javascript from
356
-<a class="ulink" href="http://pseudo-flaw.net/content/tor/torbutton/" target="_top">querying for
357
+<a class="ulink" href="http://webdevwonders.com/detecting-firefox-add-ons/" target="_top">querying for
357 358
 versions and existence of extension chrome</a> while Tor is enabled, and
358 359
 also masks the presence of Torbutton to website javascript while Tor is
359 360
 disabled. </p><p>
360 361
 
361 362
 Finally, some of the work that logically belongs to the content policy is
362 363
 instead handled by the <span class="command"><strong>torbutton_http_observer</strong></span> and
363
-<span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of
364
+<span class="command"><strong>torbutton_weblistener</strong></span> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>. These two objects handle blocking of
364 365
 Firefox 3 favicon loads, popups, and full page plugins, which for whatever
365 366
 reason are not passed to the Firefox content policy itself (see Firefox Bugs 
366 367
 <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and 
... ...
@@ -369,13 +370,59 @@ reason are not passed to the Firefox content policy itself (see Firefox Bugs
369 370
 </p><p>
370 371
 
371 372
 This helps to fulfill both the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and the <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirements of
372
-Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2976801"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
373
-located. Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XML file</a>, with zero or more Javascript
373
+Torbutton.</p></div></div></div><div class="sect1" title="3. Chrome"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2636893"></a>3. Chrome</h2></div></div></div><p>The chrome is where all the torbutton graphical elements and windows are
374
+located. </p><div class="sect2" title="3.1. XUL Windows and Overlays"><div class="titlepage"><div><div><h3 class="title"><a id="id2658833"></a>3.1. XUL Windows and Overlays</h3></div></div></div><p>
375
+Each window is described as an <a class="ulink" href="http://developer.mozilla.org/en/docs/XUL_Reference" target="_top">XML file</a>, with zero or more Javascript
374 376
 files attached. The scope of these Javascript files is their containing
375
-window.</p><div class="sect2" title="3.1. Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h3 class="title"><a id="browseroverlay"></a>3.1. Browser Overlay - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h3></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
376
-bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
377
+window. XUL files that add new elements and script to existing Firefox windows
378
+are called overlays.</p><div class="sect3" title="Browser Overlay - torbutton.xul"><div class="titlepage"><div><div><h4 class="title"><a id="browseroverlay"></a>Browser Overlay - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a></h4></div></div></div><p>The browser overlay, torbutton.xul, defines the toolbar button, the status
379
+bar, and events for toggling the button. The overlay code is in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>.
377 380
 It contains event handlers for preference update, shutdown, upgrade, and
378
-location change events.</p><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
381
+location change events.</p></div><div class="sect3" title="Preferences Window - preferences.xul"><div class="titlepage"><div><div><h4 class="title"><a id="id2647653"></a>Preferences Window - <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h4></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
382
+handlers located in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect3" title="Other Windows"><div class="titlepage"><div><div><h4 class="title"><a id="id2665081"></a>Other Windows</h4></div></div></div><p>There are additional windows that describe popups for right clicking on
383
+the status bar, the toolbutton, and the about page.</p></div></div><div class="sect2" title="3.2. Major Chrome Observers"><div class="titlepage"><div><div><h3 class="title"><a id="id2655137"></a>3.2. Major Chrome Observers</h3></div></div></div><p>
384
+In addition to the <a class="link" href="#components" title="2. Components">components described
385
+above</a>, Torbutton also instantiates several observers in the browser
386
+overlay window. These mostly grew due to scoping convenience, and many should
387
+probably be relocated into their own components.
388
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>torbutton_window_pref_observer</strong></span><p>
389
+This is an observer that listens for Torbutton state changes, for the purposes
390
+of updating the Torbutton button graphic as the Tor state changes.
391
+    </p></li><li class="listitem"><span class="command"><strong>torbutton_unique_pref_observer</strong></span><p>
392
+
393
+This is an observer that only runs in one window, called the main window. It
394
+listens for changes to all of the Torbutton preferences, as well as Torbutton
395
+controlled Firefox preferences. It is what carries out the toggle path when
396
+the proxy settings change. When the main window is closed, the
397
+torbutton_close_window event handler runs to dub a new window the "main
398
+window".
399
+
400
+    </p></li><li class="listitem"><span class="command"><strong>tbHistoryListener</strong></span><p>
401
+The tbHistoryListener exists to prevent client window Javascript from
402
+interacting with window.history to forcibly navigate a user to a tab session
403
+history entry from a different Tor state. It also expunges the window.history
404
+entries during toggle. This listener helps Torbutton
405
+satisfy the <a class="link" href="#isolation">Network Isolation</a> requirement as
406
+well as the <a class="link" href="#state">State Separation</a> requirement.
407
+
408
+    </p></li><li class="listitem"><span class="command"><strong>torbutton_http_observer</strong></span><p>
409
+
410
+The torbutton_http_observer performs some of the work that logically belongs
411
+to the content policy. This handles blocking of
412
+Firefox 3 favicon loads, which for whatever
413
+reason are not passed to the Firefox content policy itself (see Firefox Bugs
414
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=437014" target="_top">437014</a> and
415
+<a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">401296</a>).
416
+
417
+    </p><p>
418
+The observer is also responsible for redirecting users to alternate
419
+search engines when Google presents them with a Captcha, as well as copying
420
+Google Captcha-related cookies between international Google domains.
421
+    </p></li><li class="listitem"><span class="command"><strong>torbutton_proxyservice</strong></span><p>
422
+The Torbutton proxy service handles redirecting Torbutton-related update
423
+checks on addons.mozilla.org through Tor. This is done to help satisfy the
424
+<a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
425
+    </p></li><li class="listitem"><span class="command"><strong>torbutton_weblistener</strong></span><p>The <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener#onLocationChange" target="_top">location
379 426
 change</a> <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgress" target="_top">webprogress
380 427
 listener</a>, <span class="command"><strong>torbutton_weblistener</strong></span> is one of the most
381 428
 important parts of the chrome from a security standpoint. It is a <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
... ...
@@ -387,10 +434,69 @@ state tags, plugin permissions, and install the Javascript hooks to hook the
387 434
 <a class="ulink" href="https://developer.mozilla.org/en/DOM/window.screen" target="_top">window.screen</a>
388 435
 object to obfuscate browser and desktop resolution information.
389 436
 
437
+</p></li></ol></div></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2657565"></a>4. Toggle Code Path</h2></div></div></div><p>
438
+
439
+The act of toggling is connected to <code class="function">torbutton_toggle()</code>
440
+via the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
441
+and <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/popup.xul" target="_top">popup.xul</a>
442
+overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 
443
+
390 444
 </p><p>
391
-The browser overlay helps to satisfy a number of Torbutton requirements. These
392
-are better enumerated in each of the Torbutton preferences below. However,
393
-there are also a number of Firefox preferences set in
445
+
446
+Toggling is a 3 stage process: Button Click, Proxy Update, and
447
+Settings Update. These stages are reflected in the prefs
448
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
449
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
450
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
451
+three stage preference update is to ensure immediate enforcement of <a class="link" href="#isolation">Network Isolation</a> via the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. Since the content window
452
+javascript runs on a different thread than the chrome javascript, it is
453
+important to properly convey the stages to the content policy to avoid race
454
+conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
455
+409737</a> unfixed. The content policy does not allow any network activity
456
+whatsoever during this three stage transition.
457
+
458
+ </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2653926"></a>4.1. Button Click</h3></div></div></div><p>
459
+
460
+This is the first step in the toggling process. When the user clicks the
461
+toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
462
+called. This function checks the current Tor status by comparing the current
463
+proxy settings to the selected Tor settings, and then sets the proxy settings
464
+to the opposite state, and sets the pref
465
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
466
+It is this proxy pref update that gives notification via the <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">pref
467
+observer</a>
468
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
469
+toggle.
470
+
471
+  </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2652911"></a>4.2. Proxy Update</h3></div></div></div><p>
472
+
473
+When Torbutton receives any proxy change notifications via its
474
+<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
475
+<code class="function">torbutton_set_status()</code> which checks against the Tor
476
+settings to see if the Tor proxy settings match the current settings. If so,
477
+it calls <code class="function">torbutton_update_status()</code>, which determines if
478
+the Tor state has actually changed, and sets
479
+<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
480
+state value, and ensures that
481
+<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
482
+value. This is decoupled from the button click functionality via the pref
483
+observer so that other addons (such as SwitchProxy) can switch the proxy
484
+settings between multiple proxies.
485
+
486
+  </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2647095"></a>4.3. Settings Update</h3></div></div></div><p>
487
+
488
+The next stage is also handled by
489
+<code class="function">torbutton_update_status()</code>. This function sets scores of
490
+Firefox preferences, saving the original values to prefs under
491
+<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the <a class="link" href="#cookiejar" title="@torproject.org/cookie-jar-selector;2 - components/cookie-jar-selector.js">cookie jarring</a>, state clearing (such as window.name
492
+and DOM storage), and <a class="link" href="#preferences" title="4.4. Firefox preferences touched during Toggle">preference
493
+toggling</a>. At the
494
+end of its work, it sets
495
+<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
496
+completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
497
+
498
+  </p></div><div class="sect2" title="4.4. Firefox preferences touched during Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="preferences"></a>4.4. Firefox preferences touched during Toggle</h3></div></div></div><p>
499
+There are also a number of Firefox preferences set in
394 500
 <code class="function">torbutton_update_status()</code> that aren't governed by any
395 501
 Torbutton setting. These are:
396 502
 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="http://kb.mozillazine.org/Network.security.ports.banned" target="_top">network.security.ports.banned</a><p>
... ...
@@ -438,21 +544,29 @@ Torbutton needs to purge the Undo Tab history on toggle to prevent repeat
438 544
 State. This purge is accomplished by setting this preference to 0 and then
439 545
 restoring it to the previous user value upon toggle.
440 546
 
441
-   </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span><p>
547
+   </p></li><li class="listitem"><span class="command"><strong>security.enable_ssl2</strong></span> or <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/interfaces/nsIDOMCrypto" target="_top">nsIDOMCrypto::logout()</a><p>
442 548
 TLS Session IDs can persist for an indefinite duration, providing an
443 549
 identifier that is sent to TLS sites that can be used to link activity. This
444 550
 is particularly troublesome now that we have certificate verification in place
445 551
 in Firefox 3: The OCSP server can use this Session ID to build a history of
446 552
 TLS sites someone visits, and also correlate their activity as users move from
447 553
 network to network (such as home to work to coffee shop, etc), inside and
448
-outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we currently 
449
-toggle
554
+outside of Tor. To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>, we call the logout()
555
+function of nsIDOMCrypto. Since this may be absent, or may fail, we fall back
556
+to toggling
450 557
 <span class="command"><strong>security.enable_ssl2</strong></span>, which clears the SSL Session ID
451
-cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp#2134" target="_top">nsNSSComponent.cpp
452
-line 2134</a>. This is an arcane and potentially fragile fix. It would be
453
-better if there were a more standard interface for accomplishing the same
454
-thing. <a class="link" href="#FirefoxBugs" title="6. Relevant Firefox Bugs">Firefox Bug</a> <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=448747" target="_top">448747</a> has
455
-been filed for this.
558
+cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>.
559
+   </p></li><li class="listitem"><span class="command"><strong>security.OCSP.enabled</strong></span><p>
560
+Similarly, we toggle <span class="command"><strong>security.OCSP.enabled</strong></span>, which clears the OCSP certificate
561
+validation cache via the pref observer at <a class="ulink" href="http://mxr.mozilla.org/security/source/security/manager/ssl/src/nsNSSComponent.cpp" target="_top">nsNSSComponent.cpp</a>.
562
+In this way, exit nodes will not be able to fingerprint you
563
+based the fact that non-Tor OCSP lookups were obviously previously cached.
564
+To handle this and to help satisfy our <a class="link" href="#state">State Separation Requirement</a>,
565
+   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://kb.mozillazine.org/Updating_extensions#Disabling_update_checks_for_individual_add-ons_-_Advanced_users" target="_top">extensions.e0204bd5-9d31-402b-a99d-a6aa8ffebdca.getAddons.cache.enabled</a></strong></span><p>
566
+We permanently disable addon usage statistic reporting to the
567
+addons.mozilla.org statistics engine. These statistics send version
568
+information about Torbutton users via non-Tor, allowing their Tor use to be
569
+uncovered. Disabling this reporting helps Torbutton to satisfy its <a class="link" href="#undiscoverability">Tor Undiscoverability</a> requirement.
456 570
 
457 571
   </p></li><li class="listitem"><span class="command"><strong><a class="ulink" href="http://www.mozilla.com/en-US/firefox/geolocation/" target="_top">geo.enabled</a></strong></span><p>
458 572
 
... ...
@@ -496,72 +610,10 @@ enabled. This helps Torbutton fulfill its <a class="link" href="#disk">Disk
496 610
 Avoidance</a> and <a class="link" href="#state">State Separation</a>
497 611
 requirements.
498 612
 
499
-   </p></li></ol></div></div><div class="sect2" title="3.2. Preferences Window - preferences.xul"><div class="titlepage"><div><div><h3 class="title"><a id="id2959444"></a>3.2. Preferences Window - <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul" target="_top">preferences.xul</a></h3></div></div></div><p>The preferences window of course lays out the Torbutton preferences, with
500
-handlers located in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js" target="_top">chrome/content/preferences.js</a>.</p></div><div class="sect2" title="3.3. Other Windows"><div class="titlepage"><div><div><h3 class="title"><a id="id2952051"></a>3.3. Other Windows</h3></div></div></div><p>There are additional windows that describe popups for right clicking on
501
-the status bar, the toolbutton, and the about page.</p></div></div><div class="sect1" title="4. Toggle Code Path"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2943135"></a>4. Toggle Code Path</h2></div></div></div><p>
502
-
503
-The act of toggling is connected to <code class="function">torbutton_toggle()</code>
504
-via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.xul" target="_top">torbutton.xul</a>
505
-and <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/popup.xul" target="_top">popup.xul</a>
506
-overlay files. Most of the work in the toggling process is present in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a> 
507
-
508
-</p><p>
509
-
510
-Toggling is a 3 stage process: Button Click, Proxy Update, and
511
-Settings Update. These stages are reflected in the prefs
512
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span>,
513
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span>, and
514
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>. The reason for the
515
-three stage preference update is to ensure immediate enforcement of <a class="link" href="#isolation">Network Isolation</a> via the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>. Since the content window
516
-javascript runs on a different thread than the chrome javascript, it is
517
-important to properly convey the stages to the content policy to avoid race
518
-conditions and leakage, especially with <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=409737" target="_top">Firefox Bug 
519
-409737</a> unfixed. The content policy does not allow any network activity
520
-whatsoever during this three stage transition.
521
-
522
- </p><div class="sect2" title="4.1. Button Click"><div class="titlepage"><div><div><h3 class="title"><a id="id2973670"></a>4.1. Button Click</h3></div></div></div><p>
523
-
524
-This is the first step in the toggling process. When the user clicks the
525
-toggle button or the toolbar, <code class="function">torbutton_toggle()</code> is
526
-called. This function checks the current Tor status by comparing the current
527
-proxy settings to the selected Tor settings, and then sets the proxy settings
528
-to the opposite state, and sets the pref
529
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> to reflect the new state.
530
-It is this proxy pref update that gives notification via the <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">pref
531
-observer</a>
532
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span> to perform the rest of the
533
-toggle.
534
-
535
-  </p></div><div class="sect2" title="4.2. Proxy Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2975844"></a>4.2. Proxy Update</h3></div></div></div><p>
536
-
537
-When Torbutton receives any proxy change notifications via its
538
-<span class="command"><strong>torbutton_unique_pref_observer</strong></span>, it calls
539
-<code class="function">torbutton_set_status()</code> which checks against the Tor
540
-settings to see if the Tor proxy settings match the current settings. If so,
541
-it calls <code class="function">torbutton_update_status()</code>, which determines if
542
-the Tor state has actually changed, and sets
543
-<span class="command"><strong>extensions.torbutton.proxies_applied</strong></span> to the appropriate Tor
544
-state value, and ensures that
545
-<span class="command"><strong>extensions.torbutton.tor_enabled</strong></span> is also set to the correct
546
-value. This is decoupled from the button click functionalty via the pref
547
-observer so that other addons (such as SwitchProxy) can switch the proxy
548
-settings between multiple proxies.
549
-
550
-  </p></div><div class="sect2" title="4.3. Settings Update"><div class="titlepage"><div><div><h3 class="title"><a id="id2954530"></a>4.3. Settings Update</h3></div></div></div><p>
551
-
552
-The next stage is also handled by
553
-<code class="function">torbutton_update_status()</code>. This function sets scores of
554
-Firefox preferences, saving the original values to prefs under
555
-<span class="command"><strong>extensions.torbutton.saved.*</strong></span>, and performs the history
556
-clearing, cookie jaring, and ssl certificate jaring work of Torbutton. At the
557
-end of its work, it sets
558
-<span class="command"><strong>extensions.torbutton.settings_applied</strong></span>, which signifies the
559
-completion of the toggle operation to the <a class="link" href="#contentpolicy" title="@torproject.org/cssblocker;1 - components/cssblocker.js">content policy</a>.
560
-
561
-  </p></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2971938"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each
613
+   </p></li></ol></div></div></div><div class="sect1" title="5. Description of Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2659431"></a>5. Description of Options</h2></div></div></div><p>This section provides a detailed description of Torbutton's options. Each
562 614
 option is presented as the string from the preferences window, a summary, the
563 615
 preferences it touches, and the effect this has on the components, chrome, and
564
-browser properties.</p><div class="sect2" title="5.1. Test Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2967115"></a>5.1. Test Settings</h3></div></div></div><p>
616
+browser properties.</p><div class="sect2" title="5.1. Proxy Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2661813"></a>5.1. Proxy Settings</h3></div></div></div><div class="sect3" title="Test Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2663502"></a>Test Settings</h4></div></div></div><p>
565 617
 This button under the Proxy Settings tab provides a way to verify that the 
566 618
 proxy settings are correct, and actually do route through the Tor network. It
567 619
 performs this check by issuing an <a class="ulink" href="http://developer.mozilla.org/en/docs/XMLHttpRequest" target="_top">XMLHTTPRequest</a>
... ...
@@ -571,12 +623,12 @@ Torbutton can easily inspect for a hidden link with an id of
571 623
 <span class="command"><strong>TorCheckResult</strong></span> and a target of <span class="command"><strong>success</strong></span>
572 624
 or <span class="command"><strong>failure</strong></span> to indicate if the
573 625
 user hit the page from a Tor IP, a non-Tor IP. This check is handled in
574
-<code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>.
575
-Presenting the results to the user is handled by the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.xul" target="_top">preferences
626
+<code class="function">torbutton_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">torbutton.js</a>.
627
+Presenting the results to the user is handled by the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.xul" target="_top">preferences
576 628
 window</a>
577
-callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/preferences.js" target="_top">preferences.js</a>.  
629
+callback <code class="function">torbutton_prefs_test_settings()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/preferences.js" target="_top">preferences.js</a>.  
578 630
 
579
-  </p></div><div class="sect2" title="5.2. Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="plugins"></a>5.2. Disable plugins on Tor Usage (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html" target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html" target="_top">local IP
631
+  </p></div></div><div class="sect2" title="5.2. Dynamic Content Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2660939"></a>5.2. Dynamic Content Settings</h3></div></div></div><div class="sect3" title="Disable plugins on Tor Usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="plugins"></a>Disable plugins on Tor Usage (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_tor_plugins</strong></span></p><p>Java and plugins <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/net/class-use/NetworkInterface.html" target="_top">can query</a> the <a class="ulink" href="http://www.rgagnon.com/javadetails/java-0095.html" target="_top">local IP
580 632
 address</a> and report it back to the
581 633
 remote site. They can also <a class="ulink" href="http://decloak.net" target="_top">bypass proxy settings</a> and directly connect to a
582 634
 remote site without Tor. Every browser plugin we have tested with Firefox has
... ...
@@ -595,7 +647,7 @@ load
595 647
 event occurs
596 648
  (<code class="function">torbutton_update_tags()</code>), and every time the tor state is changed
597 649
  (<code class="function">torbutton_update_status()</code>). As a backup measure, plugins are also
598
- prevented from loading by the content policy in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is
650
+ prevented from loading by the content policy in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> if Tor is
599 651
  enabled and this option is set.
600 652
  </p><p>All of this turns out to be insufficient if the user directly clicks
601 653
 on a plugin-handled mime-type. <a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=401296" target="_top">In this case</a>,
... ...
@@ -620,7 +672,7 @@ all this and the plugin managed to find some way to load.
620 672
 Since most plugins completely ignore browser proxy settings, the actions
621 673
 performed by this setting are crucial to satisfying the <a class="link" href="#proxy">Proxy Obedience</a> requirement.
622 674
 
623
- </p></div><div class="sect2" title="5.3. Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2951289"></a>5.3. Isolate Dynamic Content to Tor State (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> content policy
675
+ </p></div><div class="sect3" title="Isolate Dynamic Content to Tor State (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2660188"></a>Isolate Dynamic Content to Tor State (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.isolate_content</strong></span></p><p>Enabling this preference is what enables the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cssblocker.js" target="_top">@torproject.org/cssblocker;1</a> content policy
624 676
 mentioned above, and causes it to block content load attempts in pages an
625 677
 opposite Tor state from the current state. Freshly loaded <a class="ulink" href="https://developer.mozilla.org/en/XUL/tabbrowser" target="_top">browser
626 678
 tabs</a> are tagged
... ...
@@ -647,7 +699,7 @@ from a page loaded in an opposite Tor state.
647 699
 
648 700
 </p><p>
649 701
 This setting is responsible for satisfying the <a class="link" href="#isolation">Network Isolation</a> requirement.
650
-</p></div><div class="sect2" title="5.4. Hook Dangerous Javascript"><div class="titlepage"><div><div><h3 class="title"><a id="jshooks"></a>5.4. Hook Dangerous Javascript</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/jshooks.js" target="_top">Javascript
702
+</p></div><div class="sect3" title="Hook Dangerous Javascript"><div class="titlepage"><div><div><h4 class="title"><a id="jshooks"></a>Hook Dangerous Javascript</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.kill_bad_js</strong></span></p><p>This setting enables injection of the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/jshooks.js" target="_top">Javascript
651 703
 hooking code</a>. This is done in the chrome in
652 704
 <code class="function">torbutton_hookdoc()</code>, which is called ultimately by both the 
653 705
 <a class="ulink" href="https://developer.mozilla.org/en/nsIWebProgressListener" target="_top">webprogress
... ...
@@ -668,11 +720,11 @@ meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a>
668 720
 requirements. Unfortunately, Gregory Fleischer discovered it is still possible
669 721
 to retrieve the original screen values by using <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-sandbox-xpcnativewrapper.html" target="_top">XPCNativeWrapper</a>
670 722
 or <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/unmask-components-lookupmethod.html" target="_top">Components.lookupMethod</a>.
671
-We are still looking for a workaround as of Torbutton 1.2.5.
723
+We are still looking for a workaround as of Torbutton 1.3.2.
672 724
 
673 725
 
674 726
 
675
-</p></div><div class="sect2" title="5.5. Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2960649"></a>5.5. Resize windows to multiples of 50px during Tor usage (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
727
+</p></div><div class="sect3" title="Resize windows to multiples of 50px during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629024"></a>Resize windows to multiples of 50px during Tor usage (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.resize_windows</strong></span></p><p>
676 728
 
677 729
 This option drastically cuts down on the number of distinct anonymity sets
678 730
 that divide the Tor web userbase. Without this setting, the dimensions for a
... ...
@@ -689,7 +741,7 @@ also not implementable in a foolproof way from extension land.
689 741
 </p><p>
690 742
 
691 743
 The implementation of this setting is spread across a couple of different
692
-locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="3.1. Browser Overlay - torbutton.xul">browser
744
+locations in the Torbutton javascript <a class="link" href="#browseroverlay" title="Browser Overlay - torbutton.xul">browser
693 745
 overlay</a>. Since resizing minimized windows causes them to be restored,
694 746
 and since maximized windows remember their previous size to the pixel, windows
695 747
 must be resized before every document load (at the time of browser tagging)
... ...
@@ -707,7 +759,18 @@ infer toolbar size/presence by the distance to the nearest 50 pixel roundoff).
707 759
 
708 760
 </p><p>
709 761
 This setting helps to meet the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirements.
710
-</p></div><div class="sect2" title="5.6. Disable Updates During Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2952949"></a>5.6. Disable Updates During Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox
762
+</p></div><div class="sect3" title="Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629109"></a>Disable Search Suggestions during Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
763
+This setting causes Torbutton to disable <a class="ulink" href="http://kb.mozillazine.org/Browser.search.suggest.enabled" target="_top"><span class="command"><strong>browser.search.suggest.enabled</strong></span></a>
764
+during Tor usage.
765
+This governs if you get Google search suggestions during Tor
766
+usage. Your Google cookie is transmitted with google search suggestions, hence
767
+this is recommended to be disabled.
768
+
769
+</p><p>
770
+While this setting doesn't satisfy any Torbutton requirements, the fact that
771
+cookies are transmitted for partially typed queries does not seem desirable
772
+for Tor usage.
773
+</p></div><div class="sect3" title="Disable Updates During Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2629148"></a>Disable Updates During Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_updates</strong></span></p><p>This setting causes Torbutton to disable the four <a class="ulink" href="http://wiki.mozilla.org/Update:Users/Checking_For_Updates#Preference_Controls_and_State" target="_top">Firefox
711 774
 update settings</a> during Tor
712 775
   usage: <span class="command"><strong>extensions.update.enabled</strong></span>,
713 776
 <span class="command"><strong>app.update.enabled</strong></span>,
... ...
@@ -717,7 +780,7 @@ update settings</a> during Tor
717 780
   checking for search plugin updates while Tor is enabled.
718 781
   </p><p>
719 782
 This setting satisfies the <a class="link" href="#updates">Update Safety</a> requirement.
720
-</p></div><div class="sect2" title="5.7. Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936606"></a>5.7. Redirect Torbutton Updates Via Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.update_torbutton_via_tor</strong></span></p><p>This setting causes Torbutton to install an
783
+</p></div><div class="sect3" title="Redirect Torbutton Updates Via Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629209"></a>Redirect Torbutton Updates Via Tor (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.update_torbutton_via_tor</strong></span></p><p>This setting causes Torbutton to install an
721 784
 
722 785
 <a class="ulink" href="https://developer.mozilla.org/en/nsIProtocolProxyFilter" target="_top">nsIProtocolProxyFilter</a>
723 786
 in order to redirect all version update checks and Torbutton update downloads
... ...
@@ -726,20 +789,10 @@ concerns about data retention done by <a class="ulink" href="https://www.addons.
726 789
 help censored users meet the <a class="link" href="#undiscoverability">Tor
727 790
 Undiscoverability</a> requirement.
728 791
 
729
-  </p></div><div class="sect2" title="5.8. Disable Search Suggestions during Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936650"></a>5.8. Disable Search Suggestions during Tor (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.no_search</strong></span></p><p>
730
-This setting causes Torbutton to disable <a class="ulink" href="http://kb.mozillazine.org/Browser.search.suggest.enabled" target="_top"><span class="command"><strong>browser.search.suggest.enabled</strong></span></a>
731
-during Tor usage.
732
-This governs if you get Google search suggestions during Tor
733
-usage. Your Google cookie is transmitted with google search suggestions, hence
734
-this is recommended to be disabled.
735
-
736
-</p><p>
737
-While this setting doesn't satisfy any Torbutton requirements, the fact that
738
-cookies are transmitted for partially typed queries does not seem desirable
739
-for Tor usage.
740
-</p></div><div class="sect2" title="5.9. Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936689"></a>5.9. Disable livemarks updates during Tor usage (recommended)</h3></div></div></div><p>Option:
792
+  </p></div><div class="sect3" title="Disable livemarks updates during Tor usage (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629253"></a>Disable livemarks updates during Tor usage (recommended)</h4></div></div></div><p>Option:
741 793
    </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.disable_livemarks</strong></span></td></tr></table><p>
742 794
   </p><p>
795
+
743 796
 This option causes Torbutton to prevent Firefox from loading <a class="ulink" href="http://www.mozilla.com/firefox/livebookmarks.html" target="_top">Livemarks</a> during
744 797
 Tor usage. Because people often have very personalized Livemarks (such as RSS
745 798
 feeds of Wikipedia articles they maintain, etc). This is accomplished both by
... ...
@@ -751,7 +804,7 @@ service</a> when Tor is enabled.
751 804
 This helps satisfy the <a class="link" href="#isolation">Network
752 805
 Isolation</a> and <a class="link" href="#setpreservation">Anonymity Set
753 806
 Preservation</a> requirements.
754
-</p></div><div class="sect2" title="5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936761"></a>5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</h3></div></div></div><p>Options:
807
+</p></div><div class="sect3" title="Block Tor/Non-Tor access to network from file:// urls (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629325"></a>Block Tor/Non-Tor access to network from file:// urls (recommended)</h4></div></div></div><p>Options:
755 808
    </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tor_file_net</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nontor_file_net</strong></span></td></tr></table><p>
756 809
   </p><p>
757 810
 
... ...
@@ -771,7 +824,7 @@ Isolation</a> requirement, by preventing file urls from executing network
771 824
 operations in opposite Tor states. Also, allowing pages to submit arbitrary
772 825
 files to arbitrary sites just generally seems like a bad idea.
773 826
 
774
-</p></div><div class="sect2" title="5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936833"></a>5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</h3></div></div></div><p>Options:
827
+</p></div><div class="sect3" title="Close all Tor/Non-Tor tabs and windows on toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2629397"></a>Close all Tor/Non-Tor tabs and windows on toggle (optional)</h4></div></div></div><p>Options:
775 828
    </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.close_nontor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.close_tor</strong></span></td></tr></table><p>
776 829
   </p><p>
777 830
 
... ...
@@ -795,7 +848,7 @@ out longer than necessary.
795 848
 While this setting doesn't satisfy any Torbutton requirements, the fact that
796 849
 cookies are transmitted for partially typed queries does not seem desirable
797 850
 for Tor usage.
798
-</p></div><div class="sect2" title="5.12. Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2936914"></a>5.12. Isolate Access to History navigation to Tor state (crucial)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
851
+</p></div></div><div class="sect2" title="5.3. History and Forms Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2670963"></a>5.3. History and Forms Settings</h3></div></div></div><div class="sect3" title="Isolate Access to History navigation to Tor state (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2670968"></a>Isolate Access to History navigation to Tor state (crucial)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_js_history</strong></span></p><p>
799 852
 This setting determines if Torbutton installs an <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistoryListener" target="_top">nsISHistoryListener</a>
800 853
 attached to the <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">sessionHistory</a> of 
801 854
 of each browser's <a class="ulink" href="https://developer.mozilla.org/en/XUL%3aProperty%3awebNavigation" target="_top">webNavigatator</a>.
... ...
@@ -823,9 +876,9 @@ This setting helps to fulfill Torbutton's <a class="link" href="#state">State
823 876
 Separation</a> and (until Bug 409737 is fixed) <a class="link" href="#isolation">Network Isolation</a>
824 877
 requirements.
825 878
 
826
-   </p></div><div class="sect2" title="5.13. History Access Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2936998"></a>5.13. History Access Settings</h3></div></div></div><p>Options:
879
+   </p></div><div class="sect3" title="History Access Settings"><div class="titlepage"><div><div><h4 class="title"><a id="id2671045"></a>History Access Settings</h4></div></div></div><p>Options:
827 880
   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_thread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthread</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_thwrite</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_nthwrite</strong></span></td></tr></table><p>
828
-  </p><p>These four settings govern the behavior of the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/ignore-history.js" target="_top">components/ignore-history.js</a>
881
+  </p><p>On Firefox 3.x, these four settings govern the behavior of the <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/ignore-history.js" target="_top">components/ignore-history.js</a>
829 882
 history blocker component mentioned above. By hooking the browser's view of
830 883
 the history itself via the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/global-history;2" target="_top">@mozilla.org/browser/global-history;2</a>
831 884
 and <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/browser/nav-history-service;1" target="_top">@mozilla.org/browser/nav-history-service;1</a>
... ...
@@ -836,14 +889,20 @@ The component also hooks functions involved in writing history to disk via
836 889
 both the <a class="ulink" href="http://developer.mozilla.org/en/docs/Places_migration_guide#History" target="_top">Places
837 890
 Database</a> and the older Firefox 2 mechanisms.
838 891
 
892
+</p><p>
893
+On Firefox 4, Mozilla finally <a class="ulink" href="https://developer.mozilla.org/en/CSS/Privacy_and_the_%3avisited_selector" target="_top">addressed
894
+these issues</a>, so we can effectively ignore the "read" pair of the
895
+above prefs. We then only need to link the write prefs to
896
+<span class="command"><strong>places.history.enabled</strong></span>, which disabled writing to the
897
+history store while set.
839 898
 </p><p>
840 899
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
841
-</p></div><div class="sect2" title="5.14. Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h3 class="title"><a id="id2937111"></a>5.14. Clear History During Tor Toggle (optional)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls
900
+</p></div><div class="sect3" title="Clear History During Tor Toggle (optional)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671171"></a>Clear History During Tor Toggle (optional)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_history</strong></span></p><p>This setting governs if Torbutton calls
842 901
 <a class="ulink" href="https://developer.mozilla.org/en/nsIBrowserHistory#removeAllPages.28.29" target="_top">nsIBrowserHistory.removeAllPages</a>
843 902
 and <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsISHistory" target="_top">nsISHistory.PurgeHistory</a>
844 903
 for each tab on Tor toggle.</p><p>
845 904
 This setting is an optional way to help satisfy the <a class="link" href="#state">State Separation</a> requirement.
846
-</p></div><div class="sect2" title="5.15. Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2978657"></a>5.15. Block Password+Form saving during Tor/Non-Tor</h3></div></div></div><p>Options:
905
+</p></div><div class="sect3" title="Block Password+Form saving during Tor/Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2671214"></a>Block Password+Form saving during Tor/Non-Tor</h4></div></div></div><p>Options:
847 906
   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.block_tforms</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.block_ntforms</strong></span></td></tr></table><p>
848 907
   </p><p>These settings govern if Torbutton disables
849 908
 <span class="command"><strong>browser.formfill.enable</strong></span>
... ...
@@ -852,19 +911,19 @@ Since form fields can be read at any time by Javascript, this setting is a lot
852 911
 more important than it seems.
853 912
 </p><p>
854 913
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
855
-</p></div><div class="sect2" title="5.16. Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2978718"></a>5.16. Block Tor disk cache and clear all cache on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
914
+</p></div></div><div class="sect2" title="5.4. Cache Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2671276"></a>5.4. Cache Settings</h3></div></div></div><div class="sect3" title="Block Tor disk cache and clear all cache on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2671281"></a>Block Tor disk cache and clear all cache on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cache</strong></span>
856 915
   </p><p>This option causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICacheService#evictEntries.28.29" target="_top">nsICacheService.evictEntries(0)</a>
857 916
 on Tor toggle to remove all entries from the cache. In addition, this setting
858 917
 causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> to false.
859 918
 </p><p>
860 919
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
861
-</p></div><div class="sect2" title="5.17. Block disk and memory cache during Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2978768"></a>5.17. Block disk and memory cache during Tor</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting
920
+</p></div><div class="sect3" title="Block disk and memory cache during Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2671331"></a>Block disk and memory cache during Tor</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.block_cache</strong></span></p><p>This setting
862 921
 causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.memory.enable" target="_top">browser.cache.memory.enable</a>,
863 922
 <a class="ulink" href="http://kb.mozillazine.org/Browser.cache.disk.enable" target="_top">browser.cache.disk.enable</a> and
864 923
 <a class="ulink" href="http://kb.mozillazine.org/Network.http.use-cache" target="_top">network.http.use-cache</a> to false during tor usage.
865 924
 </p><p>
866 925
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
867
-</p></div><div class="sect2" title="5.18. Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h3 class="title"><a id="id2978820"></a>5.18. Clear Cookies on Tor Toggle</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
926
+</p></div></div><div class="sect2" title="5.5. Cookie and Auth Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2671385"></a>5.5. Cookie and Auth Settings</h3></div></div></div><div class="sect3" title="Clear Cookies on Tor Toggle"><div class="titlepage"><div><div><h4 class="title"><a id="id2671390"></a>Clear Cookies on Tor Toggle</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_cookies</strong></span>
868 927
   </p><p>
869 928
 
870 929
 This setting causes Torbutton to call <a class="ulink" href="https://developer.mozilla.org/en/nsICookieManager#removeAll.28.29" target="_top">nsICookieManager.removeAll()</a> on
... ...
@@ -874,10 +933,10 @@ which prevents them from being written to disk.
874 933
 
875 934
 </p><p>
876 935
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
877
-</p></div><div class="sect2" title="5.19. Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h3 class="title"><a id="id2978871"></a>5.19. Store Non-Tor cookies in a protected jar</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
936
+</p></div><div class="sect3" title="Store Non-Tor cookies in a protected jar"><div class="titlepage"><div><div><h4 class="title"><a id="id2671441"></a>Store Non-Tor cookies in a protected jar</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.cookie_jars</strong></span>
878 937
   </p><p>
879 938
 
880
-This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
939
+This setting causes Torbutton to use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
881 940
 non-tor cookies in a cookie jar during Tor usage, and clear the Tor cookies
882 941
 before restoring the jar.
883 942
 </p><p>
... ...
@@ -887,15 +946,15 @@ which prevents them from being written to disk.
887 946
 
888 947
 </p><p>
889 948
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> and <a class="link" href="#disk">Disk Avoidance</a> requirements.
890
-</p></div><div class="sect2" title="5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2978928"></a>5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>
949
+</p></div><div class="sect3" title="Store both Non-Tor and Tor cookies in a protected jar (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671498"></a>Store both Non-Tor and Tor cookies in a protected jar (dangerous)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.dual_cookie_jars</strong></span>
891 950
   </p><p>
892 951
 
893
-This setting causes Torbutton to use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
952
+This setting causes Torbutton to use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a> to store
894 953
 both Tor and Non-Tor cookies into protected jars.
895 954
 </p><p>
896 955
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
897
-</p></div><div class="sect2" title="5.21. Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h3 class="title"><a id="id2978967"></a>5.21. Manage My Own Cookies (dangerous)</h3></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
898
-cookie prefs all to false.</p></div><div class="sect2" title="5.22. Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2978982"></a>5.22. Disable DOM Storage during Tor usage (crucial)</h3></div></div></div><div class="sect2" title="5.22.1. Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h3 class="title"><a id="id2978984"></a>5.22.1. Do not write Tor/Non-Tor cookies to disk</h3></div></div></div><p>Options:
956
+</p></div><div class="sect3" title="Manage My Own Cookies (dangerous)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671540"></a>Manage My Own Cookies (dangerous)</h4></div></div></div><p>Options: None</p><p>This setting disables all Torbutton cookie handling by setting the above
957
+cookie prefs all to false.</p></div><div class="sect3" title="Disable DOM Storage during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671556"></a>Disable DOM Storage during Tor usage (crucial)</h4></div></div></div><div class="sect3" title="Do not write Tor/Non-Tor cookies to disk"><div class="titlepage"><div><div><h4 class="title"><a id="id2671558"></a>Do not write Tor/Non-Tor cookies to disk</h4></div></div></div><p>Options:
899 958
   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.tor_memory_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.nontor_memory_jar</strong></span></td></tr></table><p>
900 959
   </p><p>
901 960
 These settings (contributed by arno) cause Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.cookie.lifetimePolicy" target="_top">network.cookie.lifetimePolicy</a>
... ...
@@ -915,41 +974,19 @@ usage to prevent
915 974
 <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:Storage" target="_top">DOM Storage</a> from
916 975
   being used to store persistent information across Tor states.</p><p>
917 976
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
918
-</p></div><div class="sect2" title="5.23. Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979086"></a>5.23. Clear HTTP Auth on Tor Toggle (recommended)</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
977
+</p></div><div class="sect3" title="Clear HTTP Auth on Tor Toggle (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671659"></a>Clear HTTP Auth on Tor Toggle (recommended)</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.clear_http_auth</strong></span>
919 978
   </p><p>
920 979
 This setting causes Torbutton to call <a class="ulink" href="http://www.oxymoronical.com/experiments/apidocs/interface/nsIHttpAuthManager" target="_top">nsIHttpAuthManager.clearAll()</a>
921 980
 every time Tor is toggled.
922 981
 </p><p>
923 982
 This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
924
-</p></div><div class="sect2" title="5.24. Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h3 class="title"><a id="id2979123"></a>5.24. Clear cookies on Tor/Non-Tor shutdown</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
925
-  </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
926
-cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
927
-clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
928
-for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
929
-<code class="function">https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js</code> and use <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a>
930
-to clear out all cookies and all cookie jars upon shutdown.  </p><p>
931
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
932
-</p></div><div class="sect2" title="5.25. Reload cookie jar/clear cookies on Firefox crash"><div class="titlepage"><div><div><h3 class="title"><a id="id2979178"></a>5.25. Reload cookie jar/clear cookies on Firefox crash</h3></div></div></div><p>Options:
933
-  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.reload_crashed_jar</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr></table><p>
934
-  </p><p>This is no longer a user visible option, and is enabled by default. In
935
-the event of a crash, the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">components/crash-observer.js</a> 
936
-  component will notify the Chrome (via the
937
-  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref and a <a class="ulink" href="https://developer.mozilla.org/en/NsIPrefBranch2#addObserver.28.29" target="_top">pref
938
-observer</a> in
939
-the chrome that listens for this update), and Torbutton will load the
940
-  correct jar for the current Tor state via the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a>
941
-  component.</p><p>
942
-This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
943
-crashes.
944
-</p></div><div class="sect2" title="5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor"><div class="titlepage"><div><div><h3 class="title"><a id="id2979253"></a>5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</h3></div></div></div><p>Options:
945
-  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.restore_tor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.crashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
946
-  </p><p>This option works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
947
-  to set the Tor state after a crash is detected (via the 
948
-  <span class="command"><strong>extensions.torbutton.crashed</strong></span> pref). To confirm for
949
-false positives (such as session restore failures, upgrade, normal
950
-session restore, etc), Torbutton also sets the pref
951
-extensions.torbutton.normal_exit during
952
-Firefox exit and checks this value as well during startup.  
983
+</p></div></div><div class="sect2" title="5.6. Startup Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2671698"></a>5.6. Startup Settings</h3></div></div></div><div class="sect3" title="On Browser Startup, set Tor state to: Tor, Non-Tor"><div class="titlepage"><div><div><h4 class="title"><a id="id2671703"></a>On Browser Startup, set Tor state to: Tor, Non-Tor</h4></div></div></div><p>Options:
984
+   <span class="command"><strong>extensions.torbutton.restore_tor</strong></span>
985
+  </p><p>This option governs what Tor state tor is loaded in to.
986
+<code class="function">torbutton_set_initial_state()</code> covers the case where the
987
+browser did not crash, and <code class="function">torbutton_crash_recover()</code>
988
+covers the case where the <a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash observer</a>
989
+detected a crash.
953 990
 </p><p>
954 991
 
955 992
 Since the Tor state after a Firefox crash is unknown/indeterminate, this
... ...
@@ -957,27 +994,26 @@ setting helps to satisfy the <a class="link" href="#state">State Separation</a>
957 994
 requirement in the event of Firefox crashes by ensuring all cookies,
958 995
 settings and saved sessions are reloaded from a fixed Tor state.
959 996
  
960
-</p></div><div class="sect2" title="5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State"><div class="titlepage"><div><div><h3 class="title"><a id="id2979325"></a>5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</h3></div></div></div><p>Options:
961
-  </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.startup_state</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.noncrashed</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.normal_exit</strong></span></td></tr></table><p>
962
-  </p><p>This option also works with the Torbutton <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/crash-observer.js" target="_top">crash-observer.js</a> 
963
-  to set the Tor state after a normal startup is detected (via the 
964
-  <span class="command"><strong>extensions.torbutton.noncrashed</strong></span> pref). To confirm for
965
-false positives
966
-(such as session restore failures, etc), Torbutton also sets the pref
967
-extensions.torbutton.normal_exit in torbutton_uninstall_observer() during
968
-Firefox exit and checks this value as well during startup.
969
-  
970
-</p></div><div class="sect2" title="5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h3 class="title"><a id="id2979384"></a>5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</h3></div></div></div><p>Options: 
997
+</p></div><div class="sect3" title="Prevent session store from saving Non-Tor/Tor-loaded tabs"><div class="titlepage"><div><div><h4 class="title"><a id="id2671754"></a>Prevent session store from saving Non-Tor/Tor-loaded tabs</h4></div></div></div><p>Options: 
971 998
   </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.nonontor_sessionstore</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.notor_sessionstore</strong></span></td></tr></table><p>
972
-  </p><p>If these options are enabled, the <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/components/nsSessionStore3.js" target="_top">replacement nsSessionStore.js</a>
973
-  component checks the <span class="command"><strong>__tb_tor_fetched</strong></span> tag of tabs before writing them
974
-  out. If the tag is from a blocked Tor state, the tab is not written to disk.
999
+  </p><p>If these options are enabled, the <a class="link" href="#tbsessionstore" title="@torproject.org/torbutton-ss-blocker;1">tbSessionStore.js</a> component uses the session
1000
+store listeners to filter out the appropriate tabs before writing the session
1001
+store data to disk.
975 1002
 </p><p>
976 1003
 This setting helps to satisfy the <a class="link" href="#disk">Disk Avoidance</a>
977 1004
 requirement, and also helps to satisfy the <a class="link" href="#state">State Separation</a> requirement in the event of Firefox
978 1005
 crashes.
979 1006
 
980
-</p></div><div class="sect2" title="5.29. Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979449"></a>5.29. Set user agent during Tor usage (crucial)</h3></div></div></div><p>Options:
1007
+</p></div></div><div class="sect2" title="5.7. Shutdown Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2671812"></a>5.7. Shutdown Settings</h3></div></div></div><div class="sect3" title="Clear cookies on Tor/Non-Tor shutdown"><div class="titlepage"><div><div><h4 class="title"><a id="id2671818"></a>Clear cookies on Tor/Non-Tor shutdown</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.shutdown_method</strong></span>
1008
+  </p><p> This option variable can actually take 3 values: 0, 1, and 2. 0 means no
1009
+cookie clearing, 1 means clear only during Tor-enabled shutdown, and 2 means
1010
+clear for both Tor and Non-Tor shutdown. When set to 1 or 2, Torbutton listens
1011
+for the <a class="ulink" href="http://developer.mozilla.org/en/docs/Observer_Notifications#Application_shutdown" target="_top">quit-application-granted</a> event in
1012
+<a class="link" href="#crashobserver" title="@torproject.org/crash-observer;1">crash-observer.js</a> and use <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/components/cookie-jar-selector.js" target="_top">@torproject.org/cookie-jar-selector;2</a>
1013
+to clear out all cookies and all cookie jars upon shutdown.
1014
+</p><p>
1015
+This setting helps to satisfy the <a class="link" href="#state">State Separation</a> requirement.
1016
+</p></div></div><div class="sect2" title="5.8. Header Settings"><div class="titlepage"><div><div><h3 class="title"><a id="id2671872"></a>5.8. Header Settings</h3></div></div></div><div class="sect3" title="Set user agent during Tor usage (crucial)"><div class="titlepage"><div><div><h4 class="title"><a id="id2671878"></a>Set user agent during Tor usage (crucial)</h4></div></div></div><p>Options:
981 1017
    </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.set_uagent</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.platform_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.oscpu_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.buildID_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.productsub_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appname_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.appversion_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_override</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendor</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.useragent_vendorSub</strong></span></td></tr></table><p>
982 1018
    </p><p>On face, user agent switching appears to be straight-forward in Firefox.
983 1019
 It provides several options for controlling the browser user agent string:
... ...
@@ -1001,7 +1037,7 @@ certain resource:// files</a>. These cases are handled by Torbutton's
1001 1037
 
1002 1038
 </p><p>
1003 1039
 This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1004
-</p></div><div class="sect2" title="5.30. Spoof US English Browser"><div class="titlepage"><div><div><h3 class="title"><a id="id2979623"></a>5.30. Spoof US English Browser</h3></div></div></div><p>Options:
1040
+</p></div><div class="sect3" title="Spoof US English Browser"><div class="titlepage"><div><div><h4 class="title"><a id="id2672052"></a>Spoof US English Browser</h4></div></div></div><p>Options:
1005 1041
 </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.spoof_english</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_charset</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.spoof_language</strong></span></td></tr></table><p>
1006 1042
 </p><p> This option causes Torbutton to set
1007 1043
 <span class="command"><strong>general.useragent.locale</strong></span>
... ...
@@ -1009,16 +1045,20 @@ This setting helps to satisfy the <a class="link" href="#setpreservation">Anonym
1009 1045
 <span class="command"><strong>extensions.torbutton.spoof_locale</strong></span>,
1010 1046
 <span class="command"><strong>extensions.torbutton.spoof_charset</strong></span> and
1011 1047
 <span class="command"><strong>extensions.torbutton.spoof_language</strong></span> during Tor usage, as
1012
-well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">javascript hooks</a>.
1048
+well as hooking <span class="command"><strong>navigator.language</strong></span> via its <a class="link" href="#jshooks" title="Hook Dangerous Javascript">javascript hooks</a>.
1013 1049
  </p><p>
1014 1050
 This setting helps to satisfy the <a class="link" href="#setpreservation">Anonymity Set Preservation</a> and <a class="link" href="#location">Location Neutrality</a> requirements.
1015
-</p></div><div class="sect2" title="5.31. Don't send referrer during Tor Usage"><div class="titlepage"><div><div><h3 class="title"><a id="id2979716"></a>5.31. Don't send referrer during Tor Usage</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.disable_referer</strong></span>
1051
+</p></div><div class="sect3" title="Referer Spoofing Options"><div class="titlepage"><div><div><h4 class="title"><a id="id2672145"></a>Referer Spoofing Options</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.refererspoof</strong></span>
1052
+</p><p>
1053
+This option variable has three values. If it is 0, "smart" referer spoofing is
1054
+enabled. If it is 1, the referer behaves as normal. If it is 2, no referer is
1055
+sent. The default value is 1. The smart referer spoofing is implemented by the
1056
+<a class="link" href="#refspoofer" title="@torproject.org/torRefSpoofer;1">torRefSpoofer</a> component.
1057
+
1016 1058
 </p><p>
1017
-This option causes Torbutton to set <a class="ulink" href="http://kb.mozillazine.org/Network.http.sendSecureXSiteReferrer" target="_top">network.http.sendSecureXSiteReferrer</a> and
1018
-<a class="ulink" href="http://kb.mozillazine.org/Network.http.sendRefererHeader" target="_top">network.http.sendRefererHeader</a> during Tor usage.</p><p>
1019 1059
 This setting also does not directly satisfy any Torbutton requirement, but
1020 1060
 some may desire to mask their referrer for general privacy concerns.
1021
-</p></div><div class="sect2" title="5.32. Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h3 class="title"><a id="id2979756"></a>5.32. Strip platform and language off of Google Search Box queries</h3></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.fix_google_srch</strong></span>
1061
+</p></div><div class="sect3" title="Strip platform and language off of Google Search Box queries"><div class="titlepage"><div><div><h4 class="title"><a id="id2672179"></a>Strip platform and language off of Google Search Box queries</h4></div></div></div><p>Option: <span class="command"><strong>extensions.torbutton.fix_google_srch</strong></span>
1022 1062
 </p><p> 
1023 1063
 
1024 1064
 This option causes Torbutton to use the <a class="ulink" href="https://wiki.mozilla.org/Search_Service:API" target="_top">@mozilla.org/browser/search-service;1</a>
... ...
@@ -1028,8 +1068,8 @@ platform information. This setting strips off that info while Tor is enabled.
1028 1068
 
1029 1069
 </p><p>
1030 1070
 This setting helps Torbutton to fulfill its <a class="link" href="#setpreservation">Anonymity Set Preservation</a> requirement.
1031
-</p></div><div class="sect2" title="5.33. Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h3 class="title"><a id="id2979797"></a>5.33. Automatically use an alternate search engine when presented with a
1032
-Google Captcha</h3></div></div></div><p>Options:
1071
+</p></div><div class="sect3" title="Automatically use an alternate search engine when presented with a Google Captcha"><div class="titlepage"><div><div><h4 class="title"><a id="id2672220"></a>Automatically use an alternate search engine when presented with a
1072
+Google Captcha</h4></div></div></div><p>Options:
1033 1073
 </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.asked_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.dodge_google_captcha</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.google_redir_url</strong></span></td></tr></table><p>
1034 1074
 </p><p>
1035 1075
 
... ...
@@ -1053,13 +1093,13 @@ options are duckduckgo.com, ixquick.com, bing.com, yahoo.com and scroogle.org. T
1053 1093
 encoded in the preferences
1054 1094
 <span class="command"><strong>extensions.torbutton.redir_url.[1-5]</strong></span>.
1055 1095
 
1056
-</p></div><div class="sect2" title="5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h3 class="title"><a id="id2979878"></a>5.34. Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h3></div></div></div><p>Options:
1096
+</p></div><div class="sect3" title="Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)"><div class="titlepage"><div><div><h4 class="title"><a id="id2672300"></a>Store SSL/CA Certs in separate jars for Tor/Non-Tor (recommended)</h4></div></div></div><p>Options:
1057 1097
 </p><table border="0" summary="Simple list" class="simplelist"><tr><td><span class="command"><strong>extensions.torbutton.jar_certs</strong></span></td></tr><tr><td><span class="command"><strong>extensions.torbutton.jar_ca_certs</strong></span></td></tr></table><p>
1058 1098
 </p><p>
1059 1099
 
1060 1100
 These settings govern if Torbutton attempts to isolate the user's SSL
1061 1101
 certificates into separate jars for each Tor state. This isolation is
1062
-implemented in <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://git.torproject.org/checkout/torbutton/master/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>,
1102
+implemented in <code class="function">torbutton_jar_certs()</code> in <a class="ulink" href="https://gitweb.torproject.org/torbutton.git/blob_plain/HEAD:/src/chrome/content/torbutton.js" target="_top">chrome/content/torbutton.js</a>,
1063 1103
 which calls <code class="function">torbutton_jar_cert_type()</code> and
1064 1104
 <code class="function">torbutton_unjar_cert_type()</code> for each certificate type in
1065 1105
 the <a class="ulink" href="http://www.oxymoronical.com/experiments/xpcomref/applications/Firefox/3.5/components/%40mozilla.org/security/nsscertcache;1" target="_top">@mozilla.org/security/nsscertcache;1</a>.
... ...
@@ -1078,7 +1118,7 @@ Separation</a> requirement of Torbutton. Unfortunately, <a class="ulink" href="h
1078 1118
 435159</a> prevents it from functioning correctly in the event of rapid Tor toggle, so it
1079 1119
 is currently not exposed via the preferences UI.
1080 1120
 
1081
-</p></div></div><div class="sect1" title="6. Relevant Firefox Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>
1121
+</p></div></div></div><div class="sect1" title="6. Relevant Firefox Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="FirefoxBugs"></a>6. Relevant Firefox Bugs</h2></div></div></div><p>
1082 1122
 
1083 1123
   </p><div class="sect2" title="6.1. Bugs impacting security"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxSecurity"></a>6.1. Bugs impacting security</h3></div></div></div><p>
1084 1124
 
... ...
@@ -1108,7 +1148,7 @@ provides a large amount of identifiable information</a><p>
1108 1148
 
1109 1149
 As <a class="link" href="#fingerprinting">mentioned above</a>, a large amount of
1110 1150
 information is available from <a class="ulink" href="http://developer.mozilla.org/en/docs/DOM:window.screen" target="_top">window.screen</a>.
1111
-The most sensative data to anonymity is actually that which is not used in
1151
+The most sensitive data to anonymity is actually that which is not used in
1112 1152
 rendering - such as desktop resolution, and window decoration size.
1113 1153
 Currently, there is no way to obscure this information without Javascript
1114 1154
 hooking. In addition, many of this same desktop and window decoration
... ...
@@ -1165,7 +1205,7 @@ This bug hinders Torbutton's ability to satisfy its <a class="link" href="#setpr
1165 1205
       </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=122752" target="_top">SOCKS
1166 1206
 Username/Password Support</a><p>
1167 1207
 We need <a class="ulink" href="https://developer.mozilla.org/en/nsIProxyInfo" target="_top">Firefox
1168
-APIs</a> or about:config settings to conrol the SOCKS Username and
1208
+APIs</a> or about:config settings to control the SOCKS Username and
1169 1209
 Password fields. The reason why we need this support is to utilize an (as yet
1170 1210
 unimplemented) scheme to separate Tor traffic based <a class="ulink" href="https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/171-separate-streams.txt" target="_top">on
1171 1211
 SOCKS username/password</a>.
... ...
@@ -1188,7 +1228,7 @@ user's original IP address.
1188 1228
 Decouple general.useragent.locale from spoofing of navigator.language</a><p>
1189 1229
 
1190 1230
 Currently, Torbutton spoofs the <span class="command"><strong>navigator.language</strong></span>
1191
-attribute via <a class="link" href="#jshooks" title="5.4. Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
1231
+attribute via <a class="link" href="#jshooks" title="Hook Dangerous Javascript">Javascript hooks</a>. Unfortunately,
1192 1232
 these do not work on Firefox 3. It would be ideal to have
1193 1233
 a pref to set this value (something like a
1194 1234
 <span class="command"><strong>general.useragent.override.locale</strong></span>),
... ...
@@ -1199,12 +1239,23 @@ requirement on Firefox 3.
1199 1239
      </p></li></ol></div></div><div class="sect2" title="6.2. Bugs blocking functionality"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxWishlist"></a>6.2. Bugs blocking functionality</h3></div></div></div><p>
1200 1240
 The following bugs impact Torbutton and similar extensions' functionality.
1201 1241
    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=445696" target="_top">Bug 445696 -
1202
-Extensions cannot determine if firefox is fullScreen</a><p>
1242
+Extensions cannot determine if Firefox is full screen</a><p>
1203 1243
 
1204 1244
 The windowState property of <a class="ulink" href="https://developer.mozilla.org/en/XUL/window" target="_top">ChromeWindows</a> does not accurately reflect the true
1205 1245
 state of the window in some cases on Linux. This causes Torbutton to attempt
1206 1246
 to resize maximized and minimized windows when it should not.
1207 1247
 
1248
+   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=629820" target="_top">nsIContentPolicy::shouldLoad not
1249
+called for web request in Firefox Mobile</a><p>
1250
+
1251
+The new <a class="ulink" href="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Electrolysis" target="_top">Electrolysis</a>
1252
+multiprocess system appears to have some pretty rough edge cases with respect
1253
+to registering XPCOM category managers such as the nsIContentPolicy, which
1254
+make it difficult to do a straight-forward port of Torbutton or
1255
+HTTPS-Everywhere to Firefox Mobile.  It probably also has similar issues with
1256
+wrapping existing <a class="link" href="#hookedxpcom" title="2.1. Hooked Components">Firefox XPCOM components</a>,
1257
+which will also cause more problems for porting Torbutton.
1258
+
1208 1259
     </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=290456" target="_top">Bug 290456 -
1209 1260
 Block/clear Flash MX "cookies" as well</a><p>
1210 1261
 
... ...
@@ -1224,14 +1275,6 @@ While this doesn't have much of an effect on Torbutton, it does make writing
1224 1275
 extensions that would like to do per-tab settings and content filters (such as
1225 1276
 FoxyProxy) difficult to impossible to implement securely.
1226 1277
 
1227
-   </p></li><li class="listitem"><a class="ulink" href="https://bugzilla.mozilla.org/show_bug.cgi?id=418321" target="_top">Bug 418321 -
1228
-Components do not expose disk interfaces</a><p>
1229
-
1230
-Several components currently provide no way of reimplementing their disk
1231
-access to easily satisfy Torbutton's <a class="link" href="#disk">Disk
1232
-Avoidance</a> requirements. Workarounds exist, but they are <a class="link" href="#sessionstore" title="@mozilla.org/browser/sessionstore;1 - components/nsSessionStore36.js">clunky</a>, and
1233
-some of them involve disabling functionality during Tor usage.
1234
-
1235 1278
    </p></li></ol></div></div><div class="sect2" title="6.3. Low Priority Bugs"><div class="titlepage"><div><div><h3 class="title"><a id="FirefoxMiscBugs"></a>6.3. Low Priority Bugs</h3></div></div></div><p>
1236 1279
 The following bugs have an effect upon Torbutton, but are superseded by more
1237 1280
 practical and more easily fixable variant bugs above; or have stable, simple
... ...
@@ -1421,13 +1464,13 @@ or complete, but it is automated and could be turned into something useful
1421 1464
 with a bit of work.
1422 1465
 
1423 1466
        </p></li></ol></div><p>
1424
-    </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2980994"></a>7.2. Multi-state testing</h3></div></div></div><p>
1467
+    </p></div><div class="sect2" title="7.2. Multi-state testing"><div class="titlepage"><div><div><h3 class="title"><a id="id2673409"></a>7.2. Multi-state testing</h3></div></div></div><p>
1425 1468
 
1426 1469
 The tests in this section are geared towards a page that would instruct the
1427 1470
 user to toggle their Tor state after the fetch and perform some operations:
1428 1471
 mouseovers, stray clicks, and potentially reloads.
1429 1472
 
1430
-   </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2981006"></a>Cookies and Cache Correlation</h4></div></div></div><p>
1473
+   </p><div class="sect3" title="Cookies and Cache Correlation"><div class="titlepage"><div><div><h4 class="title"><a id="id2673421"></a>Cookies and Cache Correlation</h4></div></div></div><p>
1431 1474
 The most obvious test is to set a cookie, ask the user to toggle tor, and then
1432 1475
 have them reload the page. The cookie should no longer be set if they are
1433 1476
 using the default Torbutton settings. In addition, it is possible to leverage
... ...
@@ -1435,11 +1478,11 @@ the cache to <a class="ulink" href="http://crypto.stanford.edu/sameorigin/safeca
1435 1478
 identifiers</a>. The default settings of Torbutton should also protect
1436 1479
 against these from persisting across Tor Toggle.
1437 1480
 
1438
-    </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2981029"></a>Javascript timers and event handlers</h4></div></div></div><p>
1481
+    </p></div><div class="sect3" title="Javascript timers and event handlers"><div class="titlepage"><div><div><h4 class="title"><a id="id2673444"></a>Javascript timers and event handlers</h4></div></div></div><p>
1439 1482
 
1440 1483
 Javascript can set timers and register event handlers in the hopes of fetching
1441 1484
 URLs after the user has toggled Torbutton. 
1442
-    </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2981042"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
1485
+    </p></div><div class="sect3" title="CSS Popups and non-script Dynamic Content"><div class="titlepage"><div><div><h4 class="title"><a id="id2673456"></a>CSS Popups and non-script Dynamic Content</h4></div></div></div><p>
1443 1486
 
1444 1487
 Even if Javascript is disabled, CSS is still able to 
1445 1488
 <a class="ulink" href="http://www.tjkdesign.com/articles/css%20pop%20ups/" target="_top">create popup-like
... ...
@@ -1464,7 +1507,7 @@ these attacks, playing with them, and reporting what you find (and potentially
1464 1507
 submitting the test cases back to be run in the standard batch of Torbutton
1465 1508
 tests.
1466 1509
 
1467
-   </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2981097"></a>Some suggested vectors to investigate</h4></div></div></div><p>
1510
+   </p><div class="sect3" title="Some suggested vectors to investigate"><div class="titlepage"><div><div><h4 class="title"><a id="id2673511"></a>Some suggested vectors to investigate</h4></div></div></div><p>
1468 1511
     </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Strange ways to register Javascript <a class="ulink" href="http://en.wikipedia.org/wiki/DOM_Events" target="_top">events</a> and <a class="ulink" href="http://www.devshed.com/c/a/JavaScript/Using-Timers-in-JavaScript/" target="_top">timeouts</a> should
1469 1512
 be verified to actually be ineffective after Tor has been toggled.</li><li class="listitem">Other ways to cause Javascript to be executed after
1470 1513
 <span class="command"><strong>javascript.enabled</strong></span> has been toggled off.</li><li class="listitem">Odd ways to attempt to load plugins. Kyle Williams has had
1471 1514