<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<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"><<a class="email" href="mailto:mikeperry.fscked/org">mikeperry.fscked/org</a>></code></p></div></div></div></div><div><p class="pubdate">Jun 28 2010</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2910402">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="#id2907285">2. Components</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2927418">2.1. Hooked Components</a></span></dt><dt><span class="sect2"><a href="#id2922900">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2907191">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="#id2922887">3.2. Preferences Window - preferences.xul</a></span></dt><dt><span class="sect2"><a href="#id2922834">3.3. Other Windows</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2917336">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2934128">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2915503">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2931338">4.3. Settings Update</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2898010">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2910532">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="#id2917719">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="#id2897638">5.5. Resize windows to multiples of 50px during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2924640">5.6. Disable Updates During Tor</a></span></dt><dt><span class="sect2"><a href="#id2892217">5.7. Redirect Torbutton Updates Via Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892261">5.8. Disable Search Suggestions during Tor (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892300">5.9. Disable livemarks updates during Tor usage (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892371">5.10. Block Tor/Non-Tor access to network from file:// urls (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2892443">5.11. Close all Tor/Non-Tor tabs and windows on toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2892524">5.12. Isolate Access to History navigation to Tor state (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2892609">5.13. History Access Settings</a></span></dt><dt><span class="sect2"><a href="#id2892721">5.14. Clear History During Tor Toggle (optional)</a></span></dt><dt><span class="sect2"><a href="#id2934267">5.15. Block Password+Form saving during Tor/Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2934328">5.16. Block Tor disk cache and clear all cache on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2934378">5.17. Block disk and memory cache during Tor</a></span></dt><dt><span class="sect2"><a href="#id2934430">5.18. Clear Cookies on Tor Toggle</a></span></dt><dt><span class="sect2"><a href="#id2934481">5.19. Store Non-Tor cookies in a protected jar</a></span></dt><dt><span class="sect2"><a href="#id2934538">5.20. Store both Non-Tor and Tor cookies in a protected jar (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2934577">5.21. Manage My Own Cookies (dangerous)</a></span></dt><dt><span class="sect2"><a href="#id2934592">5.22. Disable DOM Storage during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2934696">5.23. Clear HTTP Auth on Tor Toggle (recommended)</a></span></dt><dt><span class="sect2"><a href="#id2934733">5.24. Clear cookies on Tor/Non-Tor shutdown</a></span></dt><dt><span class="sect2"><a href="#id2934788">5.25. Reload cookie jar/clear cookies on Firefox crash</a></span></dt><dt><span class="sect2"><a href="#id2934863">5.26. On crash recovery or session restored startup, restore via: Tor, Non-Tor</a></span></dt><dt><span class="sect2"><a href="#id2934935">5.27. On normal startup, set state to: Tor, Non-Tor, Shutdown State</a></span></dt><dt><span class="sect2"><a href="#id2934994">5.28. Prevent session store from saving Non-Tor/Tor-loaded tabs</a></span></dt><dt><span class="sect2"><a href="#id2935059">5.29. Set user agent during Tor usage (crucial)</a></span></dt><dt><span class="sect2"><a href="#id2935233">5.30. Spoof US English Browser</a></span></dt><dt><span class="sect2"><a href="#id2935326">5.31. Don't send referrer during Tor Usage</a></span></dt><dt><span class="sect2"><a href="#id2935366">5.32. Strip platform and language off of Google Search Box queries</a></span></dt><dt><span class="sect2"><a href="#id2935407">5.33. Automatically use an alternate search engine when presented with a
Google Captcha</a></span></dt><dt><span class="sect2"><a href="#id2935487">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="#id2936532">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="id2910402"></a>1.·Introduction</h2></div></div></div><p>
This document describes the goals, operation, and testing procedures of the
Torbutton Firefox extension. It is current as of Torbutton 1.2.5.
</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>
A Tor web browser adversary has a number of goals, capabilities, and attack
types that can be used to guide us towards a set of requirements for the
Torbutton extension. Let's start with the goals.
</p><div class="sect3" title="Adversary Goals"><div class="titlepage"><div><div><h4 class="title"><a id="adversarygoals"></a>Adversary Goals</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Bypassing proxy settings</strong></span><p>The adversary's primary goal is direct compromise and bypass of
Tor, causing the user to directly connect to an IP of the adversary's
choosing.</p></li><li class="listitem"><span class="command"><strong>Correlation of Tor vs Non-Tor Activity</strong></span><p>If direct proxy bypass is not possible, the adversary will likely
happily settle for the ability to correlate something a user did via Tor with
their non-Tor activity. This can be done with cookies, cache identifiers,
javascript events, and even CSS. Sometimes the fact that a user uses Tor may
be enough for some authorities.</p></li><li class="listitem"><span class="command"><strong>History disclosure</strong></span><p>
The adversary may also be interested in history disclosure: the ability to
query a user's history to see if they have issued certain censored search
queries, or visited censored sites.
</p></li><li class="listitem"><span class="command"><strong>Location information</strong></span><p>
Location information such as timezone and locality can be useful for the
adversary to determine if a user is in fact originating from one of the
regions they are attempting to control, or to zero-in on the geographical
location of a particular dissident or whistleblower.
</p></li><li class="listitem"><span class="command"><strong>Miscellaneous anonymity set reduction</strong></span><p>
Anonymity set reduction is also useful in attempting to zero in on a
particular individual. If the dissident or whistleblower is using a rare build
of Firefox for an obscure operating system, this can be very useful
information for tracking them down, or at least <a class="link" href="#fingerprinting">tracking their activities</a>.
</p></li><li class="listitem"><span class="command"><strong>History records and other on-disk
information</strong></span><p>
In some cases, the adversary may opt for a heavy-handed approach, such as
seizing the computers of all Tor users in an area (especially after narrowing
the field by the above two pieces of information). History records and cache
data are the primary goals here.
</p></li></ol></div></div><div class="sect3" title="Adversary Capabilities - Positioning"><div class="titlepage"><div><div><h4 class="title"><a id="adversarypositioning"></a>Adversary Capabilities - Positioning</h4></div></div></div><p>
The adversary can position themselves at a number of different locations in
order to execute their attacks.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="command"><strong>Exit Node or Upstream Router</strong></span><p>
The adversary can run exit nodes, or alternatively, they may control routers
upstream of exit nodes. Both of these scenarios have been observed in the
wild.