Rename spec to be useful ; remove redundant copy of matt's spec draft.

git-svn-id: file:///home/or/svnrepo/updater/trunk@16857 55e972cd-5a19-0410-ae62-a4d7a52db4cd

2 files changed, 0 insertions, 377 deletions

diff --git a/specs/U1-automatic-updates.txt b/specs/U1-automatic-updates.txt
deleted file mode 100644
index b234748..0000000
--- a/specs/U1-automatic-updates.txt
+++ /dev/null
@@ -1,377 +0,0 @@
-
-Filename: xxx-automatic-updates.txt
-Title: Automatic Software Update Protocol
-Version: $Revision$
-Last-Modified: $Date$
-Author: Matt Edman
-Created: 30-July-2008
-Status: Open
-
-
-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
diff --git a/specs/U2-formats.txt b/specs/glider-spec.txt
index 476a92a..476a92a 100644
--- a/specs/U2-formats.txt
+++ b/specs/glider-spec.txt