diff --git a/doc/spec/proposals/000-index.txt b/doc/spec/proposals/000-index.txt index a7ce7a8870..87ff2b952b 100644 --- a/doc/spec/proposals/000-index.txt +++ b/doc/spec/proposals/000-index.txt @@ -76,6 +76,7 @@ Proposals by number: 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 @@ Proposals by status: 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: diff --git a/doc/spec/proposals/154-automatic-updates.txt b/doc/spec/proposals/154-automatic-updates.txt new file mode 100644 index 0000000000..08e86bf576 --- /dev/null +++ b/doc/spec/proposals/154-automatic-updates.txt @@ -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 +