mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-28 14:23:30 +01:00
380 lines
16 KiB
Plaintext
380 lines
16 KiB
Plaintext
Filename: 154-automatic-updates.txt
|
|
Title: Automatic Software Update Protocol
|
|
Version: $Revision$
|
|
Last-Modified: $Date$
|
|
Author: Matt Edman
|
|
Created: 30-July-2008
|
|
Status: Superseded
|
|
Target: 0.2.1.x
|
|
|
|
Superseded by thandy-spec.txt
|
|
|
|
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
|
|
|