README

   1 Torbutton is a 1-click way for Firefox users to enable or disable the
   2 browser's use of Tor. It adds a panel to the statusbar that says "Tor
   3 Enabled" (in green) or "Tor Disabled" (in red). The user may click on the
   4 panel to toggle the status. If the user (or some other extension) changes
   5 the proxy settings, the change is automatically reflected in the
   6 statusbar.
   7
   8 Some users may prefer a toolbar button instead of a statusbar panel. Such
   9 a button is included, and one adds it to the toolbar by right-clicking on
  10 the desired toolbar, selecting "Customize...", and then dragging the
  11 Torbutton icon onto the toolbar. There is an option in the preferences to
  12 hide the statusbar panel (Tools->Extensions, select Torbutton, and click
  13 on Preferences).
  14
  15 Newer Firefoxes have the ability to send DNS resolves through the socks
  16 proxy, and Torbutton will make use of this feature if it is available in
  17 your version of Firefox.
  18
  19                                FAQ
  20
  21 1. I can't click on links or hit reload after I toggle Tor! Why?
  22
  23    Due to Firefox Bug 409737, pages can still open popups and perform
  24    Javascript redirects and history access after Tor has been toggled. These
  25    popups and redirects can be blocked, but unfortunately they are
  26    indistinguishable from normal user interactions with the page (such as
  27    clicking on links, opening them in new tabs/windows, or using the history
  28    buttons), and so those are blocked as a side effect. Once that Firefox bug
  29    is fixed, this degree of isolation will become optional (for people who do
  30    not want to accidentally click on links and give away information via
  31    referrers). A workaround is to right click on the link, and open it in a
  32    new tab or window. The tab or window won't load automatically, but you can
  33    hit enter in the URL bar, and it will begin loading. Hitting enter in the
  34    URL bar will also reload the page without clicking the reload button.
  35
  36 2. My browser is in some weird state where nothing works right!
  37
  38    Try to disable Tor by clicking on the button, and then open a new window.
  39    If that doesn't fix the issue, go to the preferences page and hit 'Restore
  40    Defaults'. This should reset the extension and Firefox to a known good
  41    configuration. If you can manage to reproduce whatever issue gets your
  42    Firefox wedged, please file details at the bug tracker.
  43
  44 3. When I toggle Tor, my sites that use javascript stop working. Why?
  45
  46    Javascript can do things like wait until you have disabled Tor before
  47    trying to contact its source site, thus revealing your IP address. As
  48    such, Torbutton must disable Javascript, Meta-Refresh tags, and certain
  49    CSS behavior when Tor state changes from the state that was used to load a
  50    given page. These features are re-enabled when Torbutton goes back into
  51    the state that was used to load the page, but in some cases (particularly
  52    with Javascript and CSS) it is sometimes not possible to fully recover
  53    from the resulting errors, and the page is broken. Unfortunately, the only
  54    thing you can do (and still remain safe from having your IP address leak)
  55    is to reload the page when you toggle Tor, or just ensure you do all your
  56    work in a page before switching tor state.
  57
  58 4. When I use Tor, Firefox is no longer filling in logins/search boxes for
  59    me. Why?
  60
  61    Currently, this is tied to the "Block history writes during Tor" setting.
  62    If you have enabled that setting, all formfill functionality (both saving
  63    and reading) is disabled. If this bothers you, you can uncheck that
  64    option, but both history and forms will be saved. To prevent history
  65    disclosure attacks via Non-Tor usage, it is recommended you disable
  66    Non-Tor history reads if you allow history writing during Tor.
  67
  68 5. Which Firefox extensions should I avoid using?
  69
  70    This is a tough one. There are thousands of Firefox extensions: making a
  71    complete list of ones that are bad for anonymity is near impossible.
  72    However, here are a few examples that should get you started as to what
  73    sorts of behavior are dangerous.
  74
  75     1. StumbleUpon, et al These extensions will send all sorts of information
  76        about the websites you visit to the stumbleupon servers, and correlate
  77        this information with a unique identifier. This is obviously terrible
  78        for your anonymity. More generally, any sort of extension that
  79        requires registration, or even extensions that provide information
  80        about websites you visit should be suspect.
  81     2. FoxyProxy While FoxyProxy is a nice idea in theory, in practice it is
  82        impossible to configure securely for Tor usage without Torbutton. Like
  83        all vanilla third party proxy plugins, the main risks are plugin
  84        leakage and history disclosure, followed closely by cookie theft
  85        by exit nodes and tracking by adservers (see the Torbutton
  86        Adversary Model for more information). However, even with Torbutton
  87        installed in tandem and always enabled, it is still very difficult
  88        (though not impossible) to configure FoxyProxy securely. Since
  89        FoxyProxy's 'Patterns' mode only applies to specific urls, and not to
  90        an entire tab, setting FoxyProxy to only send specific sites through
  91        Tor will still allow adservers to still learn your real IP. Worse, if
  92        those sites use offsite logging services such as Google Analytics, you
  93        may still end up in their logs with your real IP. Malicious exit nodes
  94        can also cooperate with sites to inject images into pages that bypass
  95        your filters. Setting FoxyProxy to only send certain URLs via Non-Tor
  96        is much more viable, but be very careful with the filters you allow.
  97        For example, something as simple as allowing *google* to go via
  98        Non-Tor will still cause you to end up in all the logs of all websites
  99        that use Google Analytics! See this question on the FoxyProxy FAQ
 100        for more information.
 101     3. NoScript Torbutton currently mitigates all known anonymity issues with
 102        Javascript. While it may be tempting to get better security by
 103        disabling Javascript for certain sites, you are far better off with an
 104        all-or-nothing approach. NoScript is exceedingly complicated, and has
 105        many subtleties that can surprise even advanced users. For example,
 106        addons.mozilla.org verifies extension integrity via Javascript over
 107        https, but downloads them in the clear. Not adding it to your
 108        whitelist effectively means you are pulling down unverified
 109        extensions. Worse still, using NoScript can actually disable
 110        protections that Torbutton itself provides via Javascript, yet still
 111        allow malicious exit nodes to compromise your anonymity via the
 112        default whitelist (which they can spoof to inject any script they
 113        want).
 114
 115 6. Which Firefox extensions do you recommend?
 116
 117     1. RefControl Mentioned above, this extension allows more
 118        fine-grained referrer spoofing than Torbutton currently provides. It
 119        should break less sites than Torbutton's referrer spoofing option.
 120     2. SafeCache If you use Tor excessively, and rarely disable it, you
 121        probably want to install this extension to minimize the ability of
 122        sites to store long term identifiers in your cache. This extension
 123        applies same origin policy to the cache, so that elements are
 124        retrieved from the cache only if they are fetched from a document in
 125        the same origin domain as the cached element.
 126
 127 7. Are there any other issues I should be concerned about?
 128
 129    There is currently one known unfixed security issue with Torbutton: it is
 130    possible to unmask the javascript hooks that wrap the Date object to
 131    conceal your timezone in Firefox 2, and the timezone masking code does not
 132    work at all on Firefox 3. We are working with the Firefox team to fix one
 133    of Bug 399274 or Bug 419598 to address this. In the meantime, it
 134    is possible to set the TZ environment variable to UTC to cause the browser
 135    to use UTC as your timezone. Under Linux, you can add an export TZ=UTC to
 136    the /usr/bin/firefox script, or edit your system bashrc to do the same.
 137    Under Windows, you can set either a User or System Environment
 138    Variable for TZ via My Computer's properties. In MacOS, the situation is
 139    a lot more complicated, unfortunately.
 140
 141    In addition, RSS readers such as Firefox Livemarks can perform periodic
 142    fetches. Due to Firefox Bug 436250, there is no way to disable
 143    Livemark fetches during Tor. This can be a problem if you have a lot of
 144    custom Livemark urls that can give away information about your identity.