<?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">Apr 10 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2666923">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="#id2690319">2.2. New Components</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2681735">3. Chrome</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2702019">3.1. XUL Windows and Overlays</a></span></dt><dt><span class="sect2"><a href="#id2694797">3.2. Major Chrome Observers</a></span></dt></dl></dd><dt><span class="sect1"><a href="#id2696524">4. Toggle Code Path</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2699452">4.1. Button Click</a></span></dt><dt><span class="sect2"><a href="#id2697978">4.2. Proxy Update</a></span></dt><dt><span class="sect2"><a href="#id2697015">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="#id2702702">5. Description of Options</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2704948">5.1. Proxy Settings</a></span></dt><dt><span class="sect2"><a href="#id2686645">5.2. Dynamic Content Settings</a></span></dt><dt><span class="sect2"><a href="#id2705261">5.3. History and Forms Settings</a></span></dt><dt><span class="sect2"><a href="#id2705577">5.4. Cache Settings</a></span></dt><dt><span class="sect2"><a href="#id2705686">5.5. Cookie and Auth Settings</a></span></dt><dt><span class="sect2"><a href="#id2705999">5.6. Startup Settings</a></span></dt><dt><span class="sect2"><a href="#id2706113">5.7. Shutdown Settings</a></span></dt><dt><span class="sect2"><a href="#id2706173">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="#TorBrowserBugs">6.1. Tor Browser Bugs</a></span></dt><dt><span class="sect2"><a href="#ToggleModelBugs">6.2. Toggle Model 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="#id2707624">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="id2666923"></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.3.2.
</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.
</p></li><li class="listitem"><span class="command"><strong>Adservers and/or Malicious Websites</strong></span><p>