proposals/153-automatic-software-update-protocol.txt

   1 Filename: 153-automatic-software-update-protocol.txt
   2 Title: Automatic software update protocol
   3 Version: $Revision$
   4 Last-Modified: $Date$
   5 Author: Jacob Appelbaum
   6 Created: 14-July-2008
   7 Status: Superseded
   8
   9 [Superceded by thandy-spec.txt]
  10
  11
  12                       Automatic Software Update Protocol Proposal
  13
  14 0.0 Introduction
  15
  16 The Tor project and its users require a robust method to update shipped
  17 software bundles. The software bundles often includes Vidalia, Privoxy, Polipo,
  18 Torbutton and of course Tor itself. It is not inconcievable that an update
  19 could include all of the Tor Browser Bundle. It seems reasonable to make this
  20 a standalone program that can be called in shell scripts, cronjobs or by
  21 various Tor controllers.
  22
  23 0.1 Minimal Tasks To Implement Automatic Updating
  24
  25 At the most minimal, an update must be able to do the following:
  26
  27     0 - Detect the curent Tor version, note the working status of Tor.
  28     1 - Detect the latest Tor version.
  29     2 - Fetch the latest version in the form of a platform specific package(s).
  30     3 - Verify the itegrity of the downloaded package(s).
  31     4 - Install the verified package(s).
  32     5 - Test that the new package(s) works properly.
  33
  34 0.2 Specific Enumeration Of Minimal Tasks
  35
  36 To implement requirement 0, we need to detect the current Tor version of both
  37 the updater and the current running Tor. The update program itself should be
  38 versioned internally. This requirement should also test connecting through Tor
  39 itself and note if such connections are possible.
  40
  41 To implement requirement 1, we need to learn the concensus from the directory
  42 authorities or fail back to a known good URL with cryptographically signed
  43 content.
  44
  45 To implement requirement 2, we need to download Tor - hopefully over Tor.
  46
  47 To implement requirement 3, we need to verify the package signature.
  48
  49 To implement requirement 4, we need to use a platform specific method of
  50 installation. The Tor controller performing the update perform these platform
  51 specific methods.
  52
  53 To implement requirement 5, we need to be able to extend circuits and reach
  54 the internet through Tor.
  55
  56 0.x Implementation Goals
  57
  58 The update system will be cross platform and rely on as little external code
  59 as possible. If the update system uses it, it must be updated by the update
  60 system itself. It will consist only of free software and will not rely on any
  61 non-free components until the actual installation phase. If a package manager
  62 is in use, it will be platform specific and thus only invoked by the update
  63 system implementing the update protocol.
  64
  65 The update system itself will attempt to perform update related network
  66 activity over Tor. Possibly it will attempt to use a hidden service first.
  67 It will attempt to use novel and not so novel caching
  68 when possible, it will always verify cryptographic signatures before any
  69 remotely fetched code is executed. In the event of an unusable Tor system,
  70 it will be able to attempt to fetch updates without Tor. This should be user
  71 configurable, some users will be unwilling to update without the protection of
  72 using Tor - others will simply be unable because of blocking of the main Tor
  73 website.
  74
  75 The update system will track current version numbers of Tor and supporting
  76 software. The update system will also track known working versions to assist
  77 with automatic The update system itself will be a standalone library. It will be
  78 strongly versioned internally to match the Tor bundle it was shiped with. The
  79 update system will keep track of the given platform, cpu architecture, lsb_release,
  80 package management functionality and any other platform specific metadata.
  81
  82 We have referenced two popular automatic update systems, though neither fit
  83 our needs, both are useful as an idea of what others are doing in the same
  84 area.
  85
  86 The first is sparkle[0] but it is sadly only available for Cocoa
  87 environments and is written in Objective C. This doesn't meet our requirements
  88 because it is directly tied into the private Apple framework.
  89
  90 The second is the Mozilla Automatic Update System[1]. It is possibly useful
  91 as an idea of how other free software projects automatically update. It is
  92 however not useful in its currently documented form.
  93
  94
  95     [0] http://sparkle.andymatuschak.org/documentation/
  96     [1] http://wiki.mozilla.org/AUS:Manual
  97
  98 0.x Previous methods of Tor and related software update
  99
 100 Previously, Tor users updated their Tor related software by hand. There has
 101 been no fully automatic method for any user to update. In addition, there
 102 hasn't been any specific way to find out the most current stable version of Tor
 103 or related software as voted on by the directory authority concensus.
 104
 105 0.x Changes to the directory specification
 106
 107 We will want to supplement client-versions and server-versions in the
 108 concensus voting with another version identifier known as
 109 'auto-update-versions'. This will keep track of the current concensus of
 110 specific versions that are best per platform and per architecture. It should
 111 be noted that while the Mac OS X universal binary may be the best for x86
 112 processers with Tiger, it may not be the best for PPC users on Panther. This
 113 goes for all of the package updates. We want to prevent updates that cause Tor
 114 to break even if the updating program can recover gracefully.
 115
 116 x.x Assumptions About Operating System Package Management
 117
 118 It is assumed that users will use their package manager unless they are on
 119 Microsoft Windows (any version) or Mac OS X (any version). Microsoft Windows
 120 users will have integration with the normal "add/remove program" functionality
 121 that said users would expect.
 122
 123 x.x Package Update System Failure Modes
 124
 125 The package update will try to ensure that a user always has a working Tor at
 126 the very least. It will keep state to remember versions of Tor that were able
 127 to bootstrap properly and reach the rest of the Tor network. It will also keep
 128 note of which versions broke. It will select the best Tor that works for the
 129 user. It will also allow for anonymized bug reporting on the packages
 130 available and tested by the auto-update system.
 131
 132 x.x Package Signature Verification
 133
 134 The update system will be aware of replay attacks against the update signature
 135 system itself. It will not allow package update signatures that are radically
 136 out of date. It will be a multi-key system to prevent any single party from
 137 forging an update. The key will be updated regularly. This is like authority
 138 key (see proposal 103) usage.
 139
 140 x.x Package Caching
 141
 142 The update system will iterate over different update methods. Whichever method
 143 is picked will have caching functionality. Each Tor server itself should be
 144 able to serve cached update files. This will be an option that friendly server
 145 administrators can turn on should they wish to support caching. In addition,
 146 it is possible to cache the full contents of a package in an
 147 authoratative DNS zone. Users can then query the DNS zone for their package.
 148 If we wish to further distribute the update load, we can also offer packages
 149 with encrypted bittorrent. Clients who wish to share the updates but do not
 150 wish to be a server can help distribute Tor updates. This can be tied together
 151 with the DNS caching[2][3] if needed.
 152
 153     [2] http://www.netrogenic.com/dnstorrent/
 154     [3] http://www.doxpara.com/ozymandns_src_0.1.tgz
 155
 156 x.x Helping Our Users Spread Tor
 157
 158 There should be a way for a user to participate in the packaging caching as
 159 described in section x.x. This option should be presented by the Tor
 160 controller.
 161
 162 x.x Simple HTTP Proxy To The Tor Project Website
 163
 164 It has been suggested that we should provide a simple proxy that allows a user
 165 to visit the main Tor website to download packages. This was part of a
 166 previous proposal and has not been closely examined.
 167
 168 x.x Package Installation
 169
 170 Platform specific methods for proper package installation will be left to the
 171 controller that is calling for an update. Each platform is different, the
 172 installation options and user interface will be specific to the controller in
 173 question.
 174
 175 x.x Other Things
 176
 177 Other things should be added to this proposal. What are they?