Author: mikeperry Date: 2011-12-17 04:41:37 +0000 (Sat, 17 Dec 2011) New Revision: 25263
Modified: website/trunk/projects/torbrowser/design/index.html.en Log: Update TBB design doc.
Modified: website/trunk/projects/torbrowser/design/index.html.en =================================================================== --- website/trunk/projects/torbrowser/design/index.html.en 2011-12-17 04:14:56 UTC (rev 25262) +++ website/trunk/projects/torbrowser/design/index.html.en 2011-12-17 04:41:37 UTC (rev 25263) @@ -1,6 +1,6 @@ <?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>The Design and Implementation of the Tor Browser [DRAFT]</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="The Design and Implementation of the Tor Browser [DRAFT]"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>The Design and Implementation of the Tor Browser [DRAFT]</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#torproject org">mikeperry#torproject org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Erinn</span> <span class="surname">Clark</span></h3><div class="affiliation"><div class="address"><p><code class= "email"><<a class="email" href="mailto:erinn#torproject org">erinn#torproject org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Steven</span> <span class="surname">Murdoch</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:sjmurdoch#torproject org">sjmurdoch#torproject org</a>></code></p></div></div></div></div><div><p class="pubdate">Dec 16 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2785164">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt></dl></dd><dt><span class="sect1"><a href="#DesignRequirements">2. Design Requirements and Philosophy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#security">2.1. Security Requirements</a></span></dt><dt><span class="sect2"><a href="#privacy">2.2. Pr ivacy Requirements</a></span></dt><dt><span class="sect2"><a href="#philosophy">2.3. Philosophy</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Implementation">3. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="#proxy-obedience">3.1. Proxy Obedience</a></span></dt><dt><span class="sect2"><a href="#state-separation">3.2. State Separation</a></span></dt><dt><span class="sect2"><a href="#disk-avoidance">3.3. Disk Avoidance</a></span></dt><dt><span class="sect2"><a href="#app-data-isolation">3.4. Application Data Isolation</a></span></dt><dt><span class="sect2"><a href="#identifier-linkability">3.5. Cross-Origin Identifier Unlinkability</a></span></dt><dt><span class="sect2"><a href="#fingerprinting-linkability">3.6. Cross-Origin Fingerprinting Unlinkability</a></span></dt><dt><span class="sect2"><a href="#new-identity">3.7. Long-Term Unlinkability via "New Identity" button</a></span></dt><dt><span class="sect2"><a href="#click-to-play">3.8. Cli ck-to-play for plugins and invasive content</a></span></dt><dt><span class="sect2"><a href="#firefox-patches">3.9. Description of Firefox Patches</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Packaging">4. Packaging</a></span></dt><dd><dl><dt><span class="sect2"><a href="#build-security">4.1. Build Process Security</a></span></dt><dt><span class="sect2"><a href="#addons">4.2. External Addons</a></span></dt><dt><span class="sect2"><a href="#prefs">4.3. Pref Changes</a></span></dt><dt><span class="sect2"><a href="#update-mechanism">4.4. Update Security</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Testing">5. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">5.1. Single state testing</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="id2785164"></a>1. Introduction</h2></div></div></div><p> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Design and Implementation of the Tor Browser [DRAFT]</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div class="article" title="The Design and Implementation of the Tor Browser [DRAFT]"><div class="titlepage"><div><div><h2 class="title"><a id="design"></a>The Design and Implementation of the Tor Browser [DRAFT]</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#torproject org">mikeperry#torproject org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Erinn</span> <span class="surname">Clark</span></h3><div class="affiliation"><div class="address"><p><code class= "email"><<a class="email" href="mailto:erinn#torproject org">erinn#torproject org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Steven</span> <span class="surname">Murdoch</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:sjmurdoch#torproject org">sjmurdoch#torproject org</a>></code></p></div></div></div></div><div><p class="pubdate">Dec 16 2011</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id2532509">1. Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#adversary">1.1. Adversary Model</a></span></dt></dl></dd><dt><span class="sect1"><a href="#DesignRequirements">2. Design Requirements and Philosophy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#security">2.1. Security Requirements</a></span></dt><dt><span class="sect2"><a href="#privacy">2.2. Pr ivacy Requirements</a></span></dt><dt><span class="sect2"><a href="#philosophy">2.3. Philosophy</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Implementation">3. Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="#proxy-obedience">3.1. Proxy Obedience</a></span></dt><dt><span class="sect2"><a href="#state-separation">3.2. State Separation</a></span></dt><dt><span class="sect2"><a href="#disk-avoidance">3.3. Disk Avoidance</a></span></dt><dt><span class="sect2"><a href="#app-data-isolation">3.4. Application Data Isolation</a></span></dt><dt><span class="sect2"><a href="#identifier-linkability">3.5. Cross-Origin Identifier Unlinkability</a></span></dt><dt><span class="sect2"><a href="#fingerprinting-linkability">3.6. Cross-Origin Fingerprinting Unlinkability</a></span></dt><dt><span class="sect2"><a href="#new-identity">3.7. Long-Term Unlinkability via "New Identity" button</a></span></dt><dt><span class="sect2"><a href="#click-to-play">3.8. Cli ck-to-play for plugins and invasive content</a></span></dt><dt><span class="sect2"><a href="#firefox-patches">3.9. Description of Firefox Patches</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Packaging">4. Packaging</a></span></dt><dd><dl><dt><span class="sect2"><a href="#build-security">4.1. Build Process Security</a></span></dt><dt><span class="sect2"><a href="#addons">4.2. External Addons</a></span></dt><dt><span class="sect2"><a href="#prefs">4.3. Pref Changes</a></span></dt><dt><span class="sect2"><a href="#update-mechanism">4.4. Update Security</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Testing">5. Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#SingleStateTesting">5.1. Single state testing</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="id2532509"></a>1. Introduction</h2></div></div></div><p>
This document describes the <a class="link" href="#adversary" title="1.1. Adversary Model">adversary model</a>, <a class="link" href="#DesignRequirements" title="2. Design Requirements and Philosophy">design requirements</a>, @@ -447,7 +447,7 @@ supported mime types for all currently installed plugins. </p><p> In addition, to prevent any unproxied activity by plugins at load time, we -also patch the Firefox source code to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0007-Block-all-plugins-except-flash.patch" target="_top">prevent the load of any plugins except +also patch the Firefox source code to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0007-Block-all-plugins-except-flash.patch" target="_top">prevent the load of any plugins except for Flash and Gnash</a>.
</p><p> @@ -473,13 +473,13 @@ Tor Browser State is separated from existing browser state through use of a custom Firefox profile. Furthermore, plugins are disabled, which prevents Flash cookies from leaking from a pre-existing Flash directory. - </p></div><div class="sect2" title="3.3. Disk Avoidance"><div class="titlepage"><div><div><h3 class="title"><a id="disk-avoidance"></a>3.3. Disk Avoidance</h3></div></div></div><div class="sect3" title="Design Goal:"><div class="titlepage"><div><div><h4 class="title"><a id="id2817563"></a>Design Goal:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> + </p></div><div class="sect2" title="3.3. Disk Avoidance"><div class="titlepage"><div><div><h3 class="title"><a id="disk-avoidance"></a>3.3. Disk Avoidance</h3></div></div></div><div class="sect3" title="Design Goal:"><div class="titlepage"><div><div><h4 class="title"><a id="id2564908"></a>Design Goal:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> Tor Browser MUST (at user option) prevent all disk records of browser activity. The user should be able to optionally enable URL history and other history features if they so desire. Once we <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/3100" target="_top">simplify the preferences interface</a>, we will likely just enable Private Browsing mode by default to handle this goal. - </blockquote></div></div><div class="sect3" title="Implementation Status:"><div class="titlepage"><div><div><h4 class="title"><a id="id2815614"></a>Implementation Status:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> + </blockquote></div></div><div class="sect3" title="Implementation Status:"><div class="titlepage"><div><div><h4 class="title"><a id="id2562959"></a>Implementation Status:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> For now, Tor Browser blocks write access to the disk through Torbutton using several Firefox preferences.
@@ -501,11 +501,11 @@ In addition, three Firefox patches are needed to prevent disk writes, even if Private Browsing Mode is enabled. We need to
-<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0002-Make-Permissions-Manager-memory-only.patch" target="_top">prevent +<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0002-Make-Permissions-Manager-memory-only.patch" target="_top">prevent the permissions manager from recording HTTPS STS state</a>, -<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0003-Make-Intermediate-Cert-Store-memory-only.patch" target="_top">prevent +<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0003-Make-Intermediate-Cert-Store-memory-only.patch" target="_top">prevent intermediate SSL certificates from being recorded</a>, and -<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0008-Make-content-pref-service-memory-only-clearable.patch" target="_top">prevent +<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0008-Make-content-pref-service-memory-only-clearable.patch" target="_top">prevent the content preferences service from recording site zoom</a>.
For more details on these patches, <a class="link" href="#firefox-patches" title="3.9. Description of Firefox Patches">see the @@ -544,7 +544,7 @@ context-menu option to drill down into specific types of state or permissions. An example of this simplification can be seen in Figure 1.
- </p><div class="figure"><a id="id2799780"></a><p class="title"><b>Figure 1. Improving the Privacy UI</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="CookieManagers.png" align="middle" alt="Improving the Privacy UI" /></div><div class="caption"><p></p> + </p><div class="figure"><a id="id2547125"></a><p class="title"><b>Figure 1. Improving the Privacy UI</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="CookieManagers.png" align="middle" alt="Improving the Privacy UI" /></div><div class="caption"><p></p>
On the left is the standard Firefox cookie manager. On the right is a mock-up of how isolating identifiers to the URL bar origin might simplify the privacy @@ -584,7 +584,7 @@ However, to <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/3666" target="_top">increase the security of the isolation</a> and to <a class="ulink" href="https://trac.torproject.org/projects/tor/ticket/3754" target="_top">solve conflicts with OCSP relying the cacheKey property for reuse of POST requests</a>, we -had to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0005-Add-a-string-based-cacheKey.patch" target="_top">patch +had to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0005-Add-a-string-based-cacheKey.patch" target="_top">patch Firefox to provide a cacheDomain cache attribute</a>. We use the fully qualified url bar domain as input to this field.
@@ -612,7 +612,7 @@ HTTP authentication tokens are removed for third party elements using the <a class="ulink" href="https://developer.mozilla.org/en/Setting_HTTP_request_headers#Observers" target="_top">http-on-modify-request observer</a> to remove the Authorization headers to prevent <a class="ulink" href="http://jeremiahgrossman.blogspot.com/2007/04/tracking-users-without-cookies.html" target="_top">silent -linkability between domains</a>. We also needed to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0004-Add-HTTP-auth-headers-before-the-modify-request-obse.patch" target="_top">patch +linkability between domains</a>. We also needed to <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0004-Add-HTTP-auth-headers-before-the-modify-request-obse.patch" target="_top">patch Firefox to cause the headers to get added early enough</a> to allow the observer to modify it.
@@ -849,7 +849,7 @@ Firefox provides several options for controlling the browser user agent string which we leverage. We also set similar prefs for controlling the Accept-Language and Accept-Charset headers, which we spoof to English by default. Additionally, we -<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/refs/heads/maint-2.2:/src/current-patches/0001-Block-Components.interfaces-lookupMethod-from-conten.patch" target="_top">remove +<a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/blob/maint-2.2:/src/current-patches/firefox/0001-Block-Components.interfaces-lookupMethod-from-conten.patch" target="_top">remove content script access</a> to Components.interfaces, which <a class="ulink" href="http://pseudo-flaw.net/tor/torbutton/fingerprint-firefox.html" target="_top">can be used</a> to fingerprint OS, platform, and Firefox minor version. </p></li><li class="listitem">Desktop resolution and CSS Media Queries <p> @@ -962,11 +962,11 @@ </p></li></ol></div></div><div class="sect2" title="3.7. Long-Term Unlinkability via "New Identity" button"><div class="titlepage"><div><div><h3 class="title"><a id="new-identity"></a>3.7. Long-Term Unlinkability via "New Identity" button</h3></div></div></div><p> In order to avoid long-term linkability, we provide a "New Identity" context menu option in Torbutton. - </p><div class="sect3" title="Design Goal:"><div class="titlepage"><div><div><h4 class="title"><a id="id2802993"></a>Design Goal:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> + </p><div class="sect3" title="Design Goal:"><div class="titlepage"><div><div><h4 class="title"><a id="id2550338"></a>Design Goal:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote">
All linkable identifiers and browser state MUST be cleared by this feature.
- </blockquote></div></div><div class="sect3" title="Implementation Status:"><div class="titlepage"><div><div><h4 class="title"><a id="id2782032"></a>Implementation Status:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"> + </blockquote></div></div><div class="sect3" title="Implementation Status:"><div class="titlepage"><div><div><h4 class="title"><a id="id2529377"></a>Implementation Status:</h4></div></div></div><div class="blockquote"><blockquote class="blockquote">
First, Torbutton disables all open tabs and windows by tagging them and blocking them via the nsIContentPolicy, and then closes each tab and @@ -996,8 +996,7 @@ Currently, the content types isolated in this way include Flash, WebGL, and audio and video objects. </p></div><div class="sect2" title="3.9. Description of Firefox Patches"><div class="titlepage"><div><div><h3 class="title"><a id="firefox-patches"></a>3.9. Description of Firefox Patches</h3></div></div></div><p> -The set of patches we have against Firefox can be found in the <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/tree/refs/heads/maint-2.2:/src/current-patches" target="_top">current-patches -directory of the torbrowser git repository</a>. They are: +The set of patches we have against Firefox can be found in the <a class="ulink" href="https://gitweb.torproject.org/torbrowser.git/tree/maint-2.2:/src/current-patches/firefox" target="_top">current-patches directory of the torbrowser git repository</a>. They are: </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Block Components.interfaces and Components.lookupMethod <p>
@@ -1070,8 +1069,34 @@ This patch prevents random URLs from being inserted into content-prefs.sqllite in the profile directory as content prefs change (includes site-zoom and perhaps other site prefs?). - </p></li></ol></div></div></div><div class="sect1" title="4. Packaging"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Packaging"></a>4. Packaging</h2></div></div></div><p> </p><div class="sect2" title="4.1. Build Process Security"><div class="titlepage"><div><div><h3 class="title"><a id="build-security"></a>4.1. Build Process Security</h3></div></div></div><p> </p></div><div class="sect2" title="4.2. External Addons"><div class="titlepage"><div><div><h3 class="title"><a id="addons"></a>4.2. External Addons</h3></div></div></div><p> </p><div class="sect3" title="Included Addons"><div class="titlepage"><div><div><h4 class="title"><a id="id2776736"></a>Included Addons</h4></div></div></div></div><div class="sect3" title="Excluded Addons"><div class="titlepage"><div><div><h4 class="title"><a id="id2776743"></a>Excluded Addons</h4></div></div></div></div><div class="sect3" title="Dangerous Addons"><div class="titlepage"><div><div><h4 cla ss="title"><a id="id2776760"></a>Dangerous Addons</h4></div></div></div></div></div><div class="sect2" title="4.3. Pref Changes"><div class="titlepage"><div><div><h3 class="title"><a id="prefs"></a>4.3. Pref Changes</h3></div></div></div><p> </p></div><div class="sect2" title="4.4. Update Security"><div class="titlepage"><div><div><h3 class="title"><a id="update-mechanism"></a>4.4. Update Security</h3></div></div></div><p> </p></div></div><div class="sect1" title="5. Testing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Testing"></a>5. Testing</h2></div></div></div><p> + </p></li><li class="listitem">Make Tor Browser exit when not launched from Vidalia + <p>
+It turns out that on Windows 7 and later systems, the Taskbar attempts to +automatically learn the most frequent apps used by the user, and it recognizes +Tor Browser as a seperate app from Vidalia. This can cause users to try to +launch Tor Brower without Vidalia or a Tor instance running. Worse, the Tor +Browser will automatically find their default Firefox profile, and properly +connect directly without using Tor. This patch is a simple hack to cause Tor +Browser to immediately exit in this case. + + </p></li><li class="listitem">Disable SSL Session ID tracking + <p> + +This patch is a simple 1-line hack to prevent SSL connections from caching +(and then later transmitting) their Session IDs. There was no preference to +govern this behavior, so we had to hack it by altering the SSL new connection +defaults. + + </p></li><li class="listitem">Provide an observer event to close persistent connections + <p> + +This patch creates an observer event in the HTTP connection manager to close +all keep-alive connections that still happen to be open. This event is emitted +by the <a class="link" href="#new-identity" title="3.7. Long-Term Unlinkability via "New Identity" button">New Identity</a> button. + + </p></li></ol></div></div></div><div class="sect1" title="4. Packaging"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Packaging"></a>4. Packaging</h2></div></div></div><p> </p><div class="sect2" title="4.1. Build Process Security"><div class="titlepage"><div><div><h3 class="title"><a id="build-security"></a>4.1. Build Process Security</h3></div></div></div><p> </p></div><div class="sect2" title="4.2. External Addons"><div class="titlepage"><div><div><h3 class="title"><a id="addons"></a>4.2. External Addons</h3></div></div></div><p> </p><div class="sect3" title="Included Addons"><div class="titlepage"><div><div><h4 class="title"><a id="id2524128"></a>Included Addons</h4></div></div></div></div><div class="sect3" title="Excluded Addons"><div class="titlepage"><div><div><h4 class="title"><a id="id2524142"></a>Excluded Addons</h4></div></div></div></div><div class="sect3" title="Dangerous Addons"><div class="titlepage"><div><div><h4 cla ss="title"><a id="id2524152"></a>Dangerous Addons</h4></div></div></div></div></div><div class="sect2" title="4.3. Pref Changes"><div class="titlepage"><div><div><h3 class="title"><a id="prefs"></a>4.3. Pref Changes</h3></div></div></div><p> </p></div><div class="sect2" title="4.4. Update Security"><div class="titlepage"><div><div><h3 class="title"><a id="update-mechanism"></a>4.4. Update Security</h3></div></div></div><p> </p></div></div><div class="sect1" title="5. Testing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Testing"></a>5. Testing</h2></div></div></div><p> + The purpose of this section is to cover all the known ways that Tor browser security can be subverted from a penetration testing perspective. The hope is that it will be useful both for creating a "Tor Safety Check"