1 files changed, 119 insertions, 0 deletions
diff --git a/spec/dir-spec/index.md b/spec/dir-spec/index.md
new file mode 100644
index 0000000..626ded0
--- /dev/null
+++ b/spec/dir-spec/index.md
@@ -0,0 +1,119 @@
+# Tor directory protocol, version 3
+
+<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 { #v1-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 { #v2-protocol }
+
+During the Tor 0.1.1.x series, Tor revised its handling of directory
+documents in order to address two major problems:
+
+```text
+      * 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 { #v3-goals }
+
+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.
+```
+
+