diff options
Diffstat (limited to 'spec/dir-spec-intro.md')
| -rw-r--r-- | spec/dir-spec-intro.md | 201 |
1 files changed, 136 insertions, 65 deletions
diff --git a/spec/dir-spec-intro.md b/spec/dir-spec-intro.md index 71b1090..0f4cafd 100644 --- a/spec/dir-spec-intro.md +++ b/spec/dir-spec-intro.md @@ -1,69 +1,140 @@ -Tor directory protocol, version 3 +# Tor directory protocol, version 3 -Table of Contents +<a id="dir-spec.txt-0"></a> + +This directory protocol is used by Tor version 0.2.0.x-alpha and later. +See dir-spec-v1.txt for information on the protocol used up to the +0.1.0.x series, and dir-spec-v2.txt for information on the protocol +used by the 0.1.1.x and 0.1.2.x series. + +This document merges and supersedes the following proposals: + +- 101 Voting on the Tor Directory System +- 103 Splitting identity key from regularly used signing key +- 104 Long and Short Router Descriptors + +XXX timeline +XXX fill in XXXXs + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +RFC 2119. + +<a id="dir-spec.txt-0.1"></a> + +## History + +The earliest versions of Onion Routing shipped with a list of known +routers and their keys. When the set of routers changed, users needed to +fetch a new list. + +### The Version 1 Directory protocol + +Early versions of Tor (0.0.2) introduced "Directory authorities": servers +that served signed "directory" documents containing a list of signed +"server descriptors", along with short summary of the status of each +router. Thus, clients could get up-to-date information on the state of +the network automatically, and be certain that the list they were getting +was attested by a trusted directory authority. + +Later versions (0.0.8) added directory caches, which download +directories from the authorities and serve them to clients. Non-caches +fetch from the caches in preference to fetching from the authorities, thus +distributing bandwidth requirements. + +Also added during the version 1 directory protocol were "router status" +documents: short documents that listed only the up/down status of the +routers on the network, rather than a complete list of all the +descriptors. Clients and caches would fetch these documents far more +frequently than they would fetch full directories. + +### The Version 2 Directory Protocol + +During the Tor 0.1.1.x series, Tor revised its handling of directory +documents in order to address two major problems: ```text - 0. Scope and preliminaries - 0.1. History - 0.2. Goals of the version 3 protoc - 0.3. Some Remaining questions - 1. Outline - 1.1. What's different from version 2? - 1.2. Document meta-format - 1.3. Signing documents - 1.4. Voting timeline - 2. Router operation and formats - 2.1. Uploading server descriptors and extra-info documents - 2.1.1. Server descriptor format - 2.1.2. Extra-info document format - 2.1.3. Nonterminals in server descriptors - 3. Directory authority operation and formats - 3.1. Creating key certificates - 3.2. Accepting server descriptor and extra-info document uploads - 3.3. Computing microdescriptors - 3.4. Exchanging votes - 3.4.1. Vote and consensus status document formats - 3.4.2. Assigning flags in a vote - 3.4.3. Serving bandwidth list files - 3.5. Downloading missing certificates from other directory authorities - 3.6. Downloading server descriptors from other directory authorities - 3.7. Downloading extra-info documents from other directory authorities - 3.8. Computing a consensus from a set of votes - 3.8.0.1. Deciding which Ids to include. - 3.8.0.2. Deciding which descriptors to include - 3.8.1. Forward compatibility - 3.8.2. Encoding port lists - 3.8.3. Computing Bandwidth Weights - 3.9. Computing consensus flavors - 3.9.1. ns consensus - 3.9.2. Microdescriptor consensus - 3.10. Exchanging detached signatures - 3.11. Publishing the signed consensus - 4. Directory cache operation - 4.1. Downloading consensus status documents from directory authorities - 4.2. Downloading server descriptors from directory authorities - 4.3. Downloading microdescriptors from directory authorities - 4.4. Downloading extra-info documents from directory authorities - 4.5. Consensus diffs - 4.5.1. Consensus diff format - 4.5.2. Serving and requesting diff - 4.6 Retrying failed downloads - 5. Client operation - 5.1. Downloading network-status documents - 5.2. Downloading server descriptors or microdescriptors - 5.3. Downloading extra-info documents - 5.4. Using directory information - 5.4.1. Choosing routers for circuits. - 5.4.2. Managing naming - 5.4.3. Software versions - 5.4.4. Warning about a router's status. - 5.5. Retrying failed downloads - 6. Standards compliance - 6.1. HTTP headers - 6.2. HTTP status codes - A. Consensus-negotiation timeline. - B. General-use HTTP URLs - C. Converting a curve25519 public key to an ed25519 public key - D. Inferring missing proto lines. - E. Limited ed diff format + * Directories had grown quite large (over 1MB), and most directory + downloads consisted mainly of server descriptors that clients + already had. + + * Every directory authority was a trust bottleneck: if a single + directory authority lied, it could make clients believe for a time + an arbitrarily distorted view of the Tor network. (Clients + trusted the most recent signed document they downloaded.) Thus, + adding more authorities would make the system less secure, not + more. ``` + +To address these, we extended the directory protocol so that +authorities now published signed "network status" documents. Each +network status listed, for every router in the network: a hash of its +identity key, a hash of its most recent descriptor, and a summary of +what the authority believed about its status. Clients would download +the authorities' network status documents in turn, and believe +statements about routers iff they were attested to by more than half of +the authorities. + +Instead of downloading all server descriptors at once, clients +downloaded only the descriptors that they did not have. Descriptors +were indexed by their digests, in order to prevent malicious caches +from giving different versions of a server descriptor to different +clients. + +Routers began working harder to upload new descriptors only when their +contents were substantially changed. + +<a id="dir-spec.txt-0.2"></a> + +### Goals of the version 3 protocol + +Version 3 of the Tor directory protocol tries to solve the following +issues: + +```text + * A great deal of bandwidth used to transmit server descriptors was + used by two fields that are not actually used by Tor routers + (namely read-history and write-history). We save about 60% by + moving them into a separate document that most clients do not + fetch or use. + + * It was possible under certain perverse circumstances for clients + to download an unusual set of network status documents, thus + partitioning themselves from clients who have a more recent and/or + typical set of documents. Even under the best of circumstances, + clients were sensitive to the ages of the network status documents + they downloaded. Therefore, instead of having the clients + correlate multiple network status documents, we have the + authorities collectively vote on a single consensus network status + document. + + * The most sensitive data in the entire network (the identity keys + of the directory authorities) needed to be stored unencrypted so + that the authorities can sign network-status documents on the fly. + Now, the authorities' identity keys are stored offline, and used + to certify medium-term signing keys that can be rotated. +``` + +<a id="dir-spec.txt-0.3"></a> + +## Some Remaining questions + +Things we could solve on a v3 timeframe: + +The SHA-1 hash is showing its age. We should do something about our +dependency on it. We could probably future-proof ourselves here in +this revision, at least so far as documents from the authorities are +concerned. + +Too many things about the authorities are hardcoded by IP. + +Perhaps we should start accepting longer identity keys for routers +too. + +Things to solve eventually: + +Requiring every client to know about every router won't scale forever. + +Requiring every directory cache to know every router won't scale +forever. |