doc/dir-spec-v1.txt

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