dir-spec-v1.txt

   1
   2                          Tor Protocol Specification
   3
   4                               Roger Dingledine
   5                                Nick Mathewson
   6
   7 0. Preliminaries
   8
   9   THIS SPECIFICATION IS OBSOLETE.
  10
  11   This document specifies the Tor directory protocol as used in version
  12   0.1.0.x and earlier.  See dir-spec.txt for a current version.
  13
  14 1. Basic operation
  15
  16   There is a small number of directory authorities, and a larger number of
  17   caches.  Client and servers know public keys for the directory authorities.
  18   Tor servers periodically upload self-signed "router descriptors" to the
  19   directory authorities.  Each authority publishes a self-signed "directory"
  20   (containing all the router descriptors it knows, and a statement on which
  21   are running) and a self-signed "running routers" document containing only
  22   the statement on which routers are running.
  23
  24   All Tors periodically download these documents, downloading the directory
  25   less frequently than they do the "running routers" document.  Clients
  26   preferentially download from caches rather than authorities.
  27
  28 1.1. Document format
  29
  30   Router descriptors, directories, and running-routers documents all obey the
  31   following lightweight extensible information format.
  32
  33   The highest level object is a Document, which consists of one or more
  34   Items.  Every Item begins with a KeywordLine, followed by one or more
  35   Objects. A KeywordLine begins with a Keyword, optionally followed by
  36   whitespace and more non-newline characters, and ends with a newline.  A
  37   Keyword is a sequence of one or more characters in the set [A-Za-z0-9-].
  38   An Object is a block of encoded data in pseudo-Open-PGP-style
  39   armor. (cf. RFC 2440)
  40
  41   More formally:
  42
  43     Document ::= (Item | NL)+
  44     Item ::= KeywordLine Object*
  45     KeywordLine ::= Keyword NL | Keyword WS ArgumentsChar+ NL
  46     Keyword = KeywordChar+
  47     KeywordChar ::= 'A' ... 'Z' | 'a' ... 'z' | '0' ... '9' | '-'
  48     ArgumentChar ::= any printing ASCII character except NL.
  49     WS = (SP | TAB)+
  50     Object ::= BeginLine Base-64-encoded-data EndLine
  51     BeginLine ::= "-----BEGIN " Keyword "-----" NL
  52     EndLine ::= "-----END " Keyword "-----" NL
  53
  54     The BeginLine and EndLine of an Object must use the same keyword.
  55
  56   When interpreting a Document, software MUST reject any document containing a
  57   KeywordLine that starts with a keyword it doesn't recognize.
  58
  59   The "opt" keyword is reserved for non-critical future extensions.  All
  60   implementations MUST ignore any item of the form "opt keyword ....." when
  61   they would not recognize "keyword ....."; and MUST treat "opt keyword ....."
  62   as synonymous with "keyword ......" when keyword is recognized.
  63
  64 2. Router descriptor format.
  65
  66   Every router descriptor MUST start with a "router" Item; MUST end with a
  67   "router-signature" Item and an extra NL; and MUST contain exactly one
  68   instance of each of the following Items: "published" "onion-key" "link-key"
  69   "signing-key" "bandwidth".  Additionally, a router descriptor MAY contain
  70   any number of "accept", "reject", "fingerprint", "uptime", and "opt" Items.
  71   Other than "router" and "router-signature", the items may appear in any
  72   order.
  73
  74   The items' formats are as follows:
  75    "router" nickname address ORPort SocksPort DirPort
  76
  77       Indicates the beginning of a router descriptor.  "address"
  78       must be an IPv4 address in dotted-quad format. The last
  79       three numbers indicate the TCP ports at which this OR exposes
  80       functionality. ORPort is a port at which this OR accepts TLS
  81       connections for the main OR protocol; SocksPort is deprecated and
  82       should always be 0; and DirPort is the port at which this OR accepts
  83       directory-related HTTP connections.  If any port is not supported,
  84       the value 0 is given instead of a port number.
  85
  86    "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed
  87
  88       Estimated bandwidth for this router, in bytes per second.  The
  89       "average" bandwidth is the volume per second that the OR is willing
  90       to sustain over long periods; the "burst" bandwidth is the volume
  91       that the OR is willing to sustain in very short intervals.  The
  92       "observed" value is an estimate of the capacity this server can
  93       handle.  The server remembers the max bandwidth sustained output
  94       over any ten second period in the past day, and another sustained
  95       input.  The "observed" value is the lesser of these two numbers.
  96
  97    "platform" string
  98
  99       A human-readable string describing the system on which this OR is
 100       running.  This MAY include the operating system, and SHOULD include
 101       the name and version of the software implementing the Tor protocol.
 102
 103    "published" YYYY-MM-DD HH:MM:SS
 104
 105       The time, in GMT, when this descriptor was generated.
 106
 107    "fingerprint"
 108
 109       A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded
 110       in hex, with a single space after every 4 characters) for this router's
 111       identity key. A descriptor is considered invalid (and MUST be
 112       rejected) if the fingerprint line does not match the public key.
 113
 114       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
 115        be marked with "opt" until earlier versions of Tor are obsolete.]
 116
 117    "hibernating" 0|1
 118
 119       If the value is 1, then the Tor server was hibernating when the
 120       descriptor was published, and shouldn't be used to build circuits.
 121
 122       [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
 123        be marked with "opt" until earlier versions of Tor are obsolete.]
 124
 125    "uptime"
 126
 127       The number of seconds that this OR process has been running.
 128
 129    "onion-key" NL a public key in PEM format
 130
 131       This key is used to encrypt EXTEND cells for this OR.  The key MUST
 132       be accepted for at least XXXX hours after any new key is published in
 133       a subsequent descriptor.
 134
 135    "signing-key" NL a public key in PEM format
 136
 137       The OR's long-term identity key.
 138
 139    "accept" exitpattern
 140    "reject" exitpattern
 141
 142        These lines, in order, describe the rules that an OR follows when
 143        deciding whether to allow a new stream to a given address.  The
 144        'exitpattern' syntax is described below.
 145
 146    "router-signature" NL Signature NL
 147
 148        The "SIGNATURE" object contains a signature of the PKCS1-padded
 149        hash of the entire router descriptor, taken from the beginning of the
 150        "router" line, through the newline after the "router-signature" line.
 151        The router descriptor is invalid unless the signature is performed
 152        with the router's identity key.
 153
 154    "contact" info NL
 155
 156        Describes a way to contact the server's administrator, preferably
 157        including an email address and a PGP key fingerprint.
 158
 159    "family" names NL
 160
 161        'Names' is a whitespace-separated list of server nicknames. If two ORs
 162        list one another in their "family" entries, then OPs should treat them
 163        as a single OR for the purpose of path selection.
 164
 165        For example, if node A's descriptor contains "family B", and node B's
 166        descriptor contains "family A", then node A and node B should never
 167        be used on the same circuit.
 168
 169    "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
 170    "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
 171
 172        Declare how much bandwidth the OR has used recently. Usage is divided
 173        into intervals of NSEC seconds.  The YYYY-MM-DD HH:MM:SS field defines
 174        the end of the most recent interval.  The numbers are the number of
 175        bytes used in the most recent intervals, ordered from oldest to newest.
 176
 177        [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should
 178         be marked with "opt" until earlier versions of Tor are obsolete.]
 179
 180 2.1. Nonterminals in routerdescriptors
 181
 182   nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
 183
 184   exitpattern ::= addrspec ":" portspec
 185   portspec ::= "*" | port | port "-" port
 186   port ::= an integer between 1 and 65535, inclusive.
 187   addrspec ::= "*" | ip4spec | ip6spec
 188   ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
 189   ip4 ::= an IPv4 address in dotted-quad format
 190   ip4mask ::= an IPv4 mask in dotted-quad format
 191   num_ip4_bits ::= an integer between 0 and 32
 192   ip6spec ::= ip6 | ip6 "/" num_ip6_bits
 193   ip6 ::= an IPv6 address, surrounded by square brackets.
 194   num_ip6_bits ::= an integer between 0 and 128
 195
 196   Ports are required; if they are not included in the router
 197   line, they must appear in the "ports" lines.
 198
 199 3. Directory format
 200
 201   A Directory begins with a "signed-directory" item, followed by one each of
 202   the following, in any order: "recommended-software", "published",
 203   "router-status", "dir-signing-key".  It may include any number of "opt"
 204   items.  After these items, a directory includes any number of router
 205   descriptors, and a single "directory-signature" item.
 206
 207     "signed-directory"
 208
 209         Indicates the start of a directory.
 210
 211     "published" YYYY-MM-DD HH:MM:SS
 212
 213         The time at which this directory was generated and signed, in GMT.
 214
 215     "dir-signing-key"
 216
 217         The key used to sign this directory; see "signing-key" for format.
 218
 219     "recommended-software"  comma-separated-version-list
 220
 221         A list of which versions of which implementations are currently
 222         believed to be secure and compatible with the network.
 223
 224     "running-routers" whitespace-separated-list
 225
 226         A description of which routers are currently believed to be up or
 227         down.  Every entry consists of an optional "!", followed by either an
 228         OR's nickname, or "$" followed by a hexadecimal encoding of the hash
 229         of an OR's identity key.  If the "!" is included, the router is
 230         believed not to be running; otherwise, it is believed to be running.
 231         If a router's nickname is given, exactly one router of that nickname
 232         will appear in the directory, and that router is "approved" by the
 233         directory server.  If a hashed identity key is given, that OR is not
 234         "approved".  [XXXX The 'running-routers' line is only provided for
 235         backward compatibility.  New code should parse 'router-status'
 236         instead.]
 237
 238     "router-status" whitespace-separated-list
 239
 240         A description of which routers are currently believed to be up or
 241         down, and which are verified or unverified.  Contains one entry for
 242         every router that the directory server knows.  Each entry is of the
 243         format:
 244
 245               !name=$digest  [Verified router, currently not live.]
 246               name=$digest   [Verified router, currently live.]
 247               !$digest       [Unverified router, currently not live.]
 248           or  $digest        [Unverified router, currently live.]
 249
 250         (where 'name' is the router's nickname and 'digest' is a hexadecimal
 251         encoding of the hash of the routers' identity key).
 252
 253         When parsing this line, clients should only mark a router as
 254         'verified' if its nickname AND digest match the one provided.
 255
 256     "directory-signature" nickname-of-dirserver NL Signature
 257
 258   The signature is computed by computing the digest of the
 259   directory, from the characters "signed-directory", through the newline
 260   after "directory-signature".  This digest is then padded with PKCS.1,
 261   and signed with the directory server's signing key.
 262
 263   If software encounters an unrecognized keyword in a single router descriptor,
 264   it MUST reject only that router descriptor, and continue using the
 265   others.  Because this mechanism is used to add 'critical' extensions to
 266   future versions of the router descriptor format, implementation should treat
 267   it as a normal occurrence and not, for example, report it to the user as an
 268   error.  [Versions of Tor prior to 0.1.1 did this.]
 269
 270   If software encounters an unrecognized keyword in the directory header,
 271   it SHOULD reject the entire directory.
 272
 273 4. Network-status descriptor
 274
 275   A "network-status" (a.k.a "running-routers") document is a truncated
 276   directory that contains only the current status of a list of nodes, not
 277   their actual descriptors.  It contains exactly one of each of the following
 278   entries.
 279
 280      "network-status"
 281
 282         Must appear first.
 283
 284      "published" YYYY-MM-DD HH:MM:SS
 285
 286         (see section 3 above)
 287
 288      "router-status" list
 289
 290         (see section 3 above)
 291
 292      "directory-signature" NL signature
 293
 294         (see section 3 above)
 295
 296 5. Behavior of a directory server
 297
 298   lists nodes that are connected currently
 299   speaks HTTP on a socket, spits out directory on request
 300
 301   Directory servers listen on a certain port (the DirPort), and speak a
 302   limited version of HTTP 1.0. Clients send either GET or POST commands.
 303   The basic interactions are:
 304     "%s %s HTTP/1.0\r\nContent-Length: %lu\r\nHost: %s\r\n\r\n",
 305       command, url, content-length, host.
 306     Get "/tor/" to fetch a full directory.
 307     Get "/tor/dir.z" to fetch a compressed full directory.
 308     Get "/tor/running-routers" to fetch a network-status descriptor.
 309     Post "/tor/" to post a server descriptor, with the body of the
 310       request containing the descriptor.
 311
 312     "host" is used to specify the address:port of the dirserver, so
 313     the request can survive going through HTTP proxies.
 314