[or-cvs] r16373: add matt's auto update proposal (tor/trunk/doc/spec/proposals)
arma at seul.org
arma at seul.org
Sun Aug 3 13:49:14 UTC 2008
Author: arma
Date: 2008-08-03 09:49:14 -0400 (Sun, 03 Aug 2008)
New Revision: 16373
Added:
tor/trunk/doc/spec/proposals/154-automatic-updates.txt
Modified:
tor/trunk/doc/spec/proposals/000-index.txt
tor/trunk/doc/spec/proposals/153-automatic-software-update-protocol.txt
Log:
add matt's auto update proposal
Modified: tor/trunk/doc/spec/proposals/000-index.txt
===================================================================
--- tor/trunk/doc/spec/proposals/000-index.txt 2008-08-03 12:43:18 UTC (rev 16372)
+++ tor/trunk/doc/spec/proposals/000-index.txt 2008-08-03 13:49:14 UTC (rev 16373)
@@ -76,6 +76,7 @@
151 Improving Tor Path Selection [DRAFT]
152 Optionally allow exit from single-hop circuits [DRAFT]
153 Automatic software update protocol [DRAFT]
+154 Automatic Software Update Protocol [OPEN]
Proposals by status:
@@ -96,6 +97,7 @@
145 Separate "suitable as a guard" from "suitable as a new guard"
146 Add new flag to reflect long-term stability
149 Using data from NETINFO cells
+ 154 Automatic Software Update Protocol
NEEDS-REVISION:
131 Help users to verify they are using Tor
NEEDS-RESEARCH:
Property changes on: tor/trunk/doc/spec/proposals/153-automatic-software-update-protocol.txt
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
Added: tor/trunk/doc/spec/proposals/154-automatic-updates.txt
===================================================================
--- tor/trunk/doc/spec/proposals/154-automatic-updates.txt (rev 0)
+++ tor/trunk/doc/spec/proposals/154-automatic-updates.txt 2008-08-03 13:49:14 UTC (rev 16373)
@@ -0,0 +1,378 @@
+Filename: 154-automatic-updates.txt
+Title: Automatic Software Update Protocol
+Version: $Revision$
+Last-Modified: $Date$
+Author: Matt Edman
+Created: 30-July-2008
+Status: Open
+Target: 0.2.1.x
+
+
+Scope
+
+ This proposal specifies the method by which an automatic update client can
+ determine the most recent recommended Tor installation package for the
+ user's platform, download the package, and then verify that the package was
+ downloaded successfully. While this proposal focuses on only the Tor
+ software, the protocol defined is sufficiently extensible such that other
+ components of the Tor bundles, like Vidalia, Polipo, and Torbutton, can be
+ managed and updated by the automatic update client as well.
+
+ The initial target platform for the automatic update framework is Windows,
+ given that's the platform used by a majority of our users and that it lacks
+ a sane package management system that many Linux distributions already have.
+ Our second target platform will be Mac OS X, and so the protocol will be
+ designed with this near-future direction in mind.
+
+ Other client-side aspects of the automatic update process, such as user
+ interaction, the interface presented, and actual package installation
+ procedure, are outside the scope of this proposal.
+
+
+Motivation
+
+ Tor releases new versions frequently, often with important security,
+ anonymity, and stability fixes. Thus, it is important for users to be able
+ to promptly recognize when new versions are available and to easily
+ download, authenticate, and install updated Tor and Tor-related software
+ packages.
+
+ Tor's control protocol [2] provides a method by which controllers can
+ identify when the user's Tor software is obsolete or otherwise no longer
+ recommended. Currently, however, no mechanism exists for clients to
+ automatically download and install updated Tor and Tor-related software for
+ the user.
+
+
+Design Overview
+
+ The core of the automatic update framework is a well-defined file called a
+ "recommended-packages" file. The recommended-packages file is accessible via
+ HTTP[S] at one or more well-defined URLs. An example recommended-packages
+ URL may be:
+
+ https://updates.torproject.org/recommended-packages
+
+ The recommended-packages document is formatted according to Section 1.2
+ below and specifies the most recent recommended installation package
+ versions for Tor or Tor-related software, as well as URLs at which the
+ packages and their signatures can be downloaded.
+
+ An automatic update client process runs on the Tor user's computer and
+ periodically retrieves the recommended-packages file according to the method
+ described in Section 2.0. As described further in Section 1.2, the
+ recommended-packages file is signed and can be verified by the automatic
+ update client with one or more public keys included in the client software.
+ Since it is signed, the recommended-packages file can be mirrored by
+ multiple hosts (e.g., Tor directory authorities), whose URLs are included in
+ the automatic update client's configuration.
+
+ After retrieving and verifying the recommended-packages file, the automatic
+ update client compares the versions of the recommended software packages
+ listed in the file with those currently installed on the end-user's
+ computer. If one or more of the installed packages is determined to be out
+ of date, an updated package and its signature will be downloaded from one of
+ the package URLs listed in the recommended-packages file as described in
+ Section 2.2.
+
+ The automatic update system uses a multilevel signing key scheme for package
+ signatures. There are a small number of entities we call "packaging
+ authorities" that each have their own signing key. A packaging authority is
+ responsible for signing and publishing the recommended-packages file.
+ Additionally, each individual packager responsible for producing an
+ installation package for one or more platforms has their own signing key.
+ Every packager's signing key must be signed by at least one of the packaging
+ authority keys.
+
+
+Specification
+
+ 1. recommended-packages Specification
+
+ In this section we formally specify the format of the published
+ recommended-packages file.
+
+ 1.1. Document Meta-format
+
+ The recommended-packages document follows the lightweight extensible
+ information format defined in Tor's directory protocol specification [1]. In
+ the interest of self-containment, we have reproduced the relevant portions
+ of that format's specification in this Section. (Credits to Nick Mathewson
+ for much of the original format definition language.)
+
+ The highest level object is a Document, which consists of one or more
+ Items. Every Item begins with a KeywordLine, followed by zero or more
+ Objects. A KeywordLine begins with a Keyword, optionally followed by
+ whitespace and more non-newline characters, and ends with a newline. A
+ Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
+ An Object is a block of encoded data in pseudo-Open-PGP-style
+ armor. (cf. RFC 2440)
+
+ More formally:
+
+ Document ::= (Item | NL)+
+ Item ::= KeywordLine Object*
+ KeywordLine ::= Keyword NL | Keyword WS ArgumentChar+ NL
+ Keyword ::= KeywordChar+
+ KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
+ ArgumentChar ::= any printing ASCII character except NL.
+ WS ::= (SP | TAB)+
+ Object ::= BeginLine Base-64-encoded-data EndLine
+ BeginLine ::= "-----BEGIN " Keyword "-----" NL
+ EndLine ::= "-----END " Keyword "-----" NL
+
+ The BeginLine and EndLine of an Object must use the same keyword.
+
+ In our Document description below, we also tag Items with a multiplicity in
+ brackets. Possible tags are:
+
+ "At start, exactly once": These items MUST occur in every instance of the
+ document type, and MUST appear exactly once, and MUST be the first item in
+ their documents.
+
+ "Exactly once": These items MUST occur exactly one time in every
+ instance of the document type.
+
+ "Once or more": These items MUST occur at least once in any instance
+ of the document type, and MAY occur more than once.
+
+ "At end, exactly once": These items MUST occur in every instance of
+ the document type, and MUST appear exactly once, and MUST be the
+ last item in their documents.
+
+ 1.2. recommended-packages Document Format
+
+ When interpreting a recommended-packages Document, software MUST ignore
+ any KeywordLine that starts with a keyword it doesn't recognize; future
+ implementations MUST NOT require current automatic update clients to
+ understand any KeywordLine not currently described.
+
+ In lines that take multiple arguments, extra arguments SHOULD be
+ accepted and ignored.
+
+ The currently defined Items contained in a recommended-packages document
+ are:
+
+ "recommended-packages-format" SP number NL
+
+ [Exactly once]
+
+ This Item specifies the version of the recommended-packages format that
+ is contained in the subsequent document. The version defined in this
+ proposal is version "1". Subsequent iterations of this protocol MUST
+ increment this value if they introduce incompatible changes to the
+ document format and MAY increment this value if they only introduce
+ additional Keywords.
+
+ "published" SP YYYY-MM-DD SP HH:MM:SS NL
+
+ [Exactly once]
+
+ The time, in GMT, when this recommended-packages document was generated.
+ Automatic update clients SHOULD ignore Documents over 60 days old.
+
+ "tor-stable-win32-version" SP TorVersion NL
+
+ [Exactly once]
+
+ This keyword specifies the latest recommended release of Tor's "stable"
+ branch for the Windows platform that has an installation package
+ available. Note that this version does not necessarily correspond to the
+ most recently tagged stable Tor version, since that version may not yet
+ have an installer package available, or may have known issues on
+ Windows.
+
+ The TorVersion field is formatted according to Section 2 of Tor's
+ version specification [3].
+
+ "tor-stable-win32-package" SP Url NL
+
+ [Once or more]
+
+ This Item specifies the location from which the most recent
+ recommended Windows installation package for Tor's stable branch can be
+ downloaded.
+
+ When this Item appears multiple times within the Document, automatic
+ update clients SHOULD select randomly from the available package
+ mirrors.
+
+ "tor-dev-win32-version" SP TorVersion NL
+
+ [Exactly once]
+
+ This Item specifies the latest recommended release of Tor's
+ "development" branch for the Windows platform that has an installation
+ package available. The same caveats from the description of
+ "tor-stable-win32-version" also apply to this keyword.
+
+ The TorVersion field is formatted according to Section 2 of Tor's
+ version specification [3].
+
+ "tor-dev-win32-package" SP Url NL
+
+ [Once or more]
+
+ This Item specifies the location from which the most recent recommended
+ Windows installation package and its signature for Tor's development
+ branch can be downloaded.
+
+ When this Keyword appears multiple times within the Document, automatic
+ update clients SHOULD select randomly from the available package
+ mirrors.
+
+ "signature" NL SIGNATURE NL
+
+ [At end, exactly once]
+
+ The "SIGNATURE" Object contains a PGP signature (using a packaging
+ authority signing key) of the entire document, taken from the beginning
+ of the "recommended-packages-format" keyword, through the newline after
+ the "signature" Keyword.
+
+
+ 2. Automatic Update Client Behavior
+
+ The client-side component of the automatic update framework is an
+ application that runs on the end-user's machine. It is responsible for
+ fetching and verifying a recommended-packages document, as well as
+ downloading, verifying, and subsequently installing any necessary updated
+ software packages.
+
+ 2.1. Download and verify a recommended-packages document
+
+ The first step in the automatic update process is for the client to download
+ a copy of the recommended-packages file. The automatic update client
+ contains a (hardcoded and/or user-configurable) list of URLs from which it
+ will attempt to retrieve a recommended-packages file.
+
+ Connections to each of the recommended-packages URLs SHOULD be attempted in
+ the following order:
+
+ 1) HTTPS over Tor
+ 2) HTTP over Tor
+ 3) Direct HTTPS
+ 4) Direct HTTP
+
+ If the client fails to retrieve a recommended-packages document via any of
+ the above connection methods from any of the configured URLs, the client
+ SHOULD retry its download attempts following an exponential back-off
+ algorithm. After the first failed attempt, the client SHOULD delay one hour
+ before attempting again, up to a maximum of 24 hours delay between retry
+ attempts.
+
+ After successfully downloading a recommended-packages file, the automatic
+ update client will verify the signature using one of the public keys
+ distributed with the client software. If more than one recommended-packages
+ file is downloaded and verified, the file with the most recent "published"
+ date that is verified will be retained and the rest discarded.
+
+ 2.2. Download and verify the updated packages
+
+ The automatic update client next compares the latest recommended package
+ version from the recommended-packages document with the currently installed
+ Tor version. If the user currently has installed a Tor version from Tor's
+ "development" branch, then the version specified in "tor-dev-*-version" Item
+ is used for comparison. Similarly, if the user currently has installed a Tor
+ version from Tor's "stable" branch, then the version specified in the
+ "tor-stable-*version" Item is used for comparison. Version comparisons are
+ done according to Tor's version specification [3].
+
+ If the automatic update client determines an installation package newer than
+ the user's currently installed version is available, it will attempt to
+ download a package appropriate for the user's platform and Tor branch from a
+ URL specified by a "tor-[branch]-[platform]-package" Item. If more than one
+ mirror for the selected package is available, a mirror will be chosen at
+ random from all those available.
+
+ The automatic update client must also download a ".asc" signature file for
+ the retrieved package. The URL for the package signature is the same as that
+ for the package itself, except with the extension ".asc" appended to the
+ package URL.
+
+ Connections to download the updated package and its signature SHOULD be
+ attempted in the same order described in Section 2.1.
+
+ After completing the steps described in Sections 2.1 and 2.2, the automatic
+ update client will have downloaded and verified a copy of the latest Tor
+ installation package. It can then take whatever subsequent platform-specific
+ steps are necessary to install the downloaded software updates.
+
+ 2.3. Periodic checking for updates
+
+ The automatic update client SHOULD maintain a local state file in which it
+ records (at a minimum) the timestamp at which it last retrieved a
+ recommended-packages file and the timestamp at which the client last
+ successfully downloaded and installed a software update.
+
+ Automatic update clients SHOULD check for an updated recommended-packages
+ document at most once per day but at least once every 30 days.
+
+
+ 3. Future Extensions
+
+ There are several possible areas for future extensions of this framework.
+ The extensions below are merely suggestions and should be the subject of
+ their own proposal before being implemented.
+
+ 3.1. Additional Software Updates
+
+ There are several software packages often included in Tor bundles besides
+ Tor, such as Vidalia, Privoxy or Polipo, and Torbutton. The versions and
+ download locations of updated installation packages for these bundle
+ components can be easily added to the recommended-packages document
+ specification above.
+
+ 3.2. Including ChangeLog Information
+
+ It may be useful for automatic update clients to be able to display for
+ users a summary of the changes made in the latest Tor or Tor-related
+ software release, before the user chooses to install the update. In the
+ future, we can add keywords to the specification in Section 1.2 that specify
+ the location of a ChangeLog file for the latest recommended package
+ versions. It may also be desirable to allow localized ChangeLog information,
+ so that the automatic update client can fetch release notes in the
+ end-user's preferred language.
+
+ 3.3. Weighted Package Mirror Selection
+
+ We defined in Section 1.2 a method by which automatic update clients can
+ select from multiple available package mirrors. We may want to add a Weight
+ argument to the "*-package" Items that allows the recommended-packages file
+ to suggest to clients the probability with which a package mirror should be
+ chosen. This will allow clients to more appropriately distribute package
+ downloads across available mirrors proportional to their approximate
+ bandwidth.
+
+
+Implementation
+
+ Implementation of this proposal will consist of two separate components.
+
+ The first component is a small "au-publish" tool that takes as input a
+ configuration file specifying the information described in Section 1.2 and a
+ private key. The tool is run by a "packaging authority" (someone responsible
+ for publishing updated installation packages), who will be prompted to enter
+ the passphrase for the private key used to sign the recommended-packages
+ document. The output of the tool is a document formatted according to
+ Section 1.2, with a signature appended at the end. The resulting document
+ can then be published to any of the update mirrors.
+
+ The second component is an "au-client" tool that is run on the end-user's
+ machine. It periodically checks for updated installation packages according
+ to Section 2 and fetches the packages if necessary. The public keys used
+ to sign the recommended-packages file and any of the published packages are
+ included in the "au-client" tool.
+
+
+References
+
+ [1] Tor directory protocol (version 3),
+ https://tor-svn.freehaven.net/svn/tor/trunk/doc/spec/dir-spec.txt
+
+ [2] Tor control protocol (version 2),
+ https://tor-svn.freehaven.net/svn/tor/trunk/doc/spec/control-spec.txt
+
+ [3] Tor version specification,
+ https://tor-svn.freehaven.net/svn/tor/trunk/doc/spec/version-spec.txt
+
Property changes on: tor/trunk/doc/spec/proposals/154-automatic-updates.txt
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
More information about the tor-commits
mailing list