An initial check in of the automatic update program. Mixed ideas, needs much work and spliting.

svn:r15925

1 files changed, 175 insertions, 0 deletions

diff --git a/proposals/153-automatic-software-update-protocol.txt b/proposals/153-automatic-software-update-protocol.txt
new file mode 100644
index 0000000..d87afca
--- /dev/null
+++ b/proposals/153-automatic-software-update-protocol.txt
@@ -0,0 +1,175 @@
+Filename: 153-automatic-software-update-protocol.txt
+Title: Automatic software update protocol
+Version: $Revision$
+Last-Modified: $Date$
+Author: Jacob Appelbaum 
+Created: 14-July-2008
+Status: Draft
+
+
+                      Automatic Software Update Protocol Proposal
+
+0.0 Introduction
+
+The Tor project and its users require a robust method to update shipped
+software bundles. The software bundles often includes Vidalia, Privoxy, Polipo,
+Torbutton and of course Tor itself. It is not inconcievable that an update
+could include all of the Tor Browser Bundle. It seems reasonable to make this 
+a standalone program that can be called in shell scripts, cronjobs or by
+various Tor controllers.
+
+0.1 Minimal Tasks To Implement Automatic Updating
+
+At the most minimal, an update must be able to do the following: 
+
+    0 - Detect the curent Tor version, note the working status of Tor.
+    1 - Detect the latest Tor version. 
+    2 - Fetch the latest version in the form of a platform specific package(s).
+    3 - Verify the itegrity of the downloaded package(s).
+    4 - Install the verified package(s).
+    5 - Test that the new package(s) works properly.
+
+0.2 Specific Enumeration Of Minimal Tasks
+
+To implement requirement 0, we need to detect the current Tor version of both 
+the updater and the current running Tor. The update program itself should be 
+versioned internally. This requirement should also test connecting through Tor 
+itself and note if such connections are possible.
+
+To implement requirement 1, we need to learn the concensus from the directory 
+authorities or fail back to a known good URL with cryptographically signed 
+content.
+
+To implement requirement 2, we need to download Tor - hopefully over Tor.
+
+To implement requirement 3, we need to verify the package signature.
+
+To implement requirement 4, we need to use a platform specific method of 
+installation. The Tor controller performing the update perform these platform 
+specific methods.
+
+To implement requirement 5, we need to be able to extend circuits and reach 
+the internet through Tor.
+
+0.x Implementation Goals
+
+The update system will be cross platform and rely on as little external code 
+as possible. If the update system uses it, it must be updated by the update 
+system itself. It will consist only of free software and will not rely on any 
+non-free components until the actual installation phase. If a package manager 
+is in use, it will be platform specific and thus only invoked by the update 
+system implementing the update protocol.
+
+The update system itself will attempt to perform update related network 
+activity over Tor. Possibly it will attempt to use a hidden service first.
+It will attempt to use novel and not so novel caching 
+when possible, it will always verify cryptographic signatures before any 
+remotely fetched code is executed. In the event of an unusable Tor system, 
+it will be able to attempt to fetch updates without Tor. This should be user 
+configurable, some users will be unwilling to update without the protection of 
+using Tor - others will simply be unable because of blocking of the main Tor 
+website.
+
+The update system will track current version numbers of Tor and supporting 
+software. The update system will also track known working versions to assist 
+with automatic The update system itself will be a standalone library. It will be 
+strongly versioned internally to match the Tor bundle it was shiped with. The 
+update system will keep track of the given platform, cpu architecture, lsb_release, 
+package management functionality and any other platform specific metadata.
+
+We have referenced two popular automatic update systems, though neither fit 
+our needs, both are useful as an idea of what others are doing in the same 
+area.
+
+The first is sparkle[0] but it is sadly only available for Cocoa 
+environments and is written in Objective C. This doesn't meet our requirements 
+because it is directly tied into the private Apple framework.
+
+The second is the Mozilla Automatic Update System[1]. It is possibly useful 
+as an idea of how other free software projects automatically update. It is 
+however not useful in its currently documented form.
+
+
+    [0] http://sparkle.andymatuschak.org/documentation/
+    [1] http://wiki.mozilla.org/AUS:Manual
+
+0.x Previous methods of Tor and related software update
+
+Previously, Tor users updated their Tor related software by hand. There has
+been no fully automatic method for any user to update. In addition, there
+hasn't been any specific way to find out the most current stable version of Tor
+or related software as voted on by the directory authority concensus.
+
+0.x Changes to the directory specification
+
+We will want to supplement client-versions and server-versions in the 
+concensus voting with another version identifier known as 
+'auto-update-versions'. This will keep track of the current concensus of 
+specific versions that are best per platform and per architecture. It should 
+be noted that while the Mac OS X universal binary may be the best for x86 
+processers with Tiger, it may not be the best for PPC users on Panther. This 
+goes for all of the package updates. We want to prevent updates that cause Tor 
+to break even if the updating program can recover gracefully.
+
+x.x Assumptions About Operating System Package Management
+
+It is assumed that users will use their package manager unless they are on 
+Microsoft Windows (any version) or Mac OS X (any version). Microsoft Windows 
+users will have integration with the normal "add/remove program" functionality 
+that said users would expect.
+
+x.x Package Update System Failure Modes
+
+The package update will try to ensure that a user always has a working Tor at 
+the very least. It will keep state to remember versions of Tor that were able 
+to bootstrap properly and reach the rest of the Tor network. It will also keep 
+note of which versions broke. It will select the best Tor that works for the 
+user. It will also allow for anonymized bug reporting on the packages 
+available and tested by the auto-update system.
+
+x.x Package Signature Verification
+
+The update system will be aware of replay attacks against the update signature 
+system itself. It will not allow package update signatures that are radically 
+out of date. It will be a multi-key system to prevent any single party from 
+forging an update. The key will be updated regularly. This is like authority 
+key (see proposal 103) usage.
+
+x.x Package Caching
+
+The update system will iterate over different update methods. Whichever method 
+is picked will have caching functionality. Each Tor server itself should be 
+able to serve cached update files. This will be an option that friendly server 
+administrators can turn on should they wish to support caching. In addition, 
+it is possible to cache the full contents of a package in an 
+authoratative DNS zone. Users can then query the DNS zone for their package. 
+If we wish to further distribute the update load, we can also offer packages 
+with encrypted bittorrent. Clients who wish to share the updates but do not 
+wish to be a server can help distribute Tor updates. This can be tied together 
+with the DNS caching[2][3] if needed.
+
+    [2] http://www.netrogenic.com/dnstorrent/
+    [3] http://www.doxpara.com/ozymandns_src_0.1.tgz
+
+x.x Helping Our Users Spread Tor
+
+There should be a way for a user to participate in the packaging caching as 
+described in section x.x. This option should be presented by the Tor 
+controller.
+
+x.x Simple HTTP Proxy To The Tor Project Website
+
+It has been suggested that we should provide a simple proxy that allows a user 
+to visit the main Tor website to download packages. This was part of a 
+previous proposal and has not been closely examined.
+
+x.x Package Installation
+
+Platform specific methods for proper package installation will be left to the 
+controller that is calling for an update. Each platform is different, the 
+installation options and user interface will be specific to the controller in 
+question.
+
+x.x Other Things
+
+Other things should be added to this proposal. What are they?