$Id$ Tor Protocol Specification Roger Dingledine Nick Mathewson 0. Prelimaries THIS SPECIFICATION IS OBSOLETE. This document specifies the Tor directory protocol as used in version 0.1.0.x and earlier. See dir-spec.txt for a current version. 1. Basic operation There is a small number of directory authorities, and a larger number of caches. Client and servers know public keys for the directory authorities. Tor servers periodically upload self-signed "router descriptors" to the directory authorities. Each authority publishes a self-signed "directory" (containing all the router descriptors it knows, and a statement on which are running) and a self-signed "running routers" document containing only the statement on which routers are running. All Tors periodically download these documents, downloading the directory less frequently than they do the "running routers" document. Clients preferentially download from caches rather than authorities. 1.1. Document format Router descriptors, directories, and running-routers documents all obey the following lightweight extensible information format. The highest level object is a Document, which consists of one or more Items. Every Item begins with a KeywordLine, followed by one 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 ArgumentsChar+ 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. When interpreting a Document, software MUST reject any document containing a KeywordLine that starts with a keyword it doesn't recognize. The "opt" keyword is reserved for non-critical future extensions. All implementations MUST ignore any item of the form "opt keyword ....." when they would not recognize "keyword ....."; and MUST treat "opt keyword ....." as synonymous with "keyword ......" when keyword is recognized. 8.2. Router descriptor format. Every router descriptor MUST start with a "router" Item; MUST end with a "router-signature" Item and an extra NL; and MUST contain exactly one instance of each of the following Items: "published" "onion-key" "link-key" "signing-key" "bandwidth". Additionally, a router descriptor MAY contain any number of "accept", "reject", "fingerprint", "uptime", and "opt" Items. Other than "router" and "router-signature", the items may appear in any order. The items' formats are as follows: "router" nickname address ORPort SocksPort DirPort Indicates the beginning of a router descriptor. "address" must be an IPv4 address in dotted-quad format. The last three numbers indicate the TCP ports at which this OR exposes functionality. ORPort is a port at which this OR accepts TLS connections for the main OR protocol; SocksPort is deprecated and should always be 0; and DirPort is the port at which this OR accepts directory-related HTTP connections. If any port is not supported, the value 0 is given instead of a port number. "bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed Estimated bandwidth for this router, in bytes per second. The "average" bandwidth is the volume per second that the OR is willing to sustain over long periods; the "burst" bandwidth is the volume that the OR is willing to sustain in very short intervals. The "observed" value is an estimate of the capacity this server can handle. The server remembers the max bandwidth sustained output over any ten second period in the past day, and another sustained input. The "observed" value is the lesser of these two numbers. "platform" string A human-readable string describing the system on which this OR is running. This MAY include the operating system, and SHOULD include the name and version of the software implementing the Tor protocol. "published" YYYY-MM-DD HH:MM:SS The time, in GMT, when this descriptor was generated. "fingerprint" A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in hex, with a single space after every 4 characters) for this router's identity key. A descriptor is considered invalid (and MUST be rejected) if the fingerprint line does not match the public key. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be marked with "opt" until earlier versions of Tor are obsolete.] "hibernating" 0|1 If the value is 1, then the Tor server was hibernating when the descriptor was published, and shouldn't be used to build circuits. [We didn't start parsing this line until Tor 0.1.0.6-rc; it should be marked with "opt" until earlier versions of Tor are obsolete.] "uptime" The number of seconds that this OR process has been running. "onion-key" NL a public key in PEM format This key is used to encrypt EXTEND cells for this OR. The key MUST be accepted for at least XXXX hours after any new key is published in a subsequent descriptor. "signing-key" NL a public key in PEM format The OR's long-term identity key. "accept" exitpattern "reject" exitpattern These lines, in order, describe the rules that an OR follows when deciding whether to allow a new stream to a given address. The 'exitpattern' syntax is described below. "router-signature" NL Signature NL The "SIGNATURE" object contains a signature of the PKCS1-padded hash of the entire router descriptor, taken from the beginning of the "router" line, through the newline after the "router-signature" line. The router descriptor is invalid unless the signature is performed with the router's identity key. "contact" info NL Describes a way to contact the server's administrator, preferably including an email address and a PGP key fingerprint. "family" names NL 'Names' is a whitespace-separated list of server nicknames. If two ORs list one another in their "family" entries, then OPs should treat them as a single OR for the purpose of path selection. For example, if node A's descriptor contains "family B", and node B's descriptor contains "family A", then node A and node B should never be used on the same circuit. "read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL "write-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL Declare how much bandwidth the OR has used recently. Usage is divided into intervals of NSEC seconds. The YYYY-MM-DD HH:MM:SS field defines the end of the most recent interval. The numbers are the number of bytes used in the most recent intervals, ordered from oldest to newest. [We didn't start parsing these lines until Tor 0.1.0.6-rc; they should be marked with "opt" until earlier versions of Tor are obsolete.] 2.1. Nonterminals in routerdescriptors nickname ::= between 1 and 19 alphanumeric characters, case-insensitive. exitpattern ::= addrspec ":" portspec portspec ::= "*" | port | port "-" port port ::= an integer between 1 and 65535, inclusive. addrspec ::= "*" | ip4spec | ip6spec ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask ip4 ::= an IPv4 address in dotted-quad format ip4mask ::= an IPv4 mask in dotted-quad format num_ip4_bits ::= an integer between 0 and 32 ip6spec ::= ip6 | ip6 "/" num_ip6_bits ip6 ::= an IPv6 address, surrounded by square brackets. num_ip6_bits ::= an integer between 0 and 128 Ports are required; if they are not included in the router line, they must appear in the "ports" lines. 3. Directory format A Directory begins with a "signed-directory" item, followed by one each of the following, in any order: "recommended-software", "published", "router-status", "dir-signing-key". It may include any number of "opt" items. After these items, a directory includes any number of router descriptors, and a single "directory-signature" item. "signed-directory" Indicates the start of a directory. "published" YYYY-MM-DD HH:MM:SS The time at which this directory was generated and signed, in GMT. "dir-signing-key" The key used to sign this directory; see "signing-key" for format. "recommended-software" comma-separated-version-list A list of which versions of which implementations are currently believed to be secure and compatible with the network. "running-routers" whitespace-separated-list A description of which routers are currently believed to be up or down. Every entry consists of an optional "!", followed by either an OR's nickname, or "$" followed by a hexadecimal encoding of the hash of an OR's identity key. If the "!" is included, the router is believed not to be running; otherwise, it is believed to be running. If a router's nickname is given, exactly one router of that nickname will appear in the directory, and that router is "approved" by the directory server. If a hashed identity key is given, that OR is not "approved". [XXXX The 'running-routers' line is only provided for backward compatibility. New code should parse 'router-status' instead.] "router-status" whitespace-separated-list A description of which routers are currently believed to be up or down, and which are verified or unverified. Contains one entry for every router that the directory server knows. Each entry is of the format: !name=$digest [Verified router, currently not live.] name=$digest [Verified router, currently live.] !$digest [Unverified router, currently not live.] or $digest [Unverified router, currently live.] (where 'name' is the router's nickname and 'digest' is a hexadecimal encoding of the hash of the routers' identity key). When parsing this line, clients should only mark a router as 'verified' if its nickname AND digest match the one provided. "directory-signature" nickname-of-dirserver NL Signature The signature is computed by computing the digest of the directory, from the characters "signed-directory", through the newline after "directory-signature". This digest is then padded with PKCS.1, and signed with the directory server's signing key. If software encounters an unrecognized keyword in a single router descriptor, it MUST reject only that router descriptor, and continue using the others. Because this mechanism is used to add 'critical' extensions to future versions of the router descriptor format, implementation should treat it as a normal occurrence and not, for example, report it to the user as an error. [Versions of Tor prior to 0.1.1 did this.] If software encounters an unrecognized keyword in the directory header, it SHOULD reject the entire directory. 4. Network-status descriptor A "network-status" (a.k.a "running-routers") document is a truncated directory that contains only the current status of a list of nodes, not their actual descriptors. It contains exactly one of each of the following entries. "network-status" Must appear first. "published" YYYY-MM-DD HH:MM:SS (see 8.3 above) "router-status" list (see 8.3 above) "directory-signature" NL signature (see 8.3 above) 5. Behavior of a directory server lists nodes that are connected currently speaks HTTP on a socket, spits out directory on request Directory servers listen on a certain port (the DirPort), and speak a limited version of HTTP 1.0. Clients send either GET or POST commands. The basic interactions are: "%s %s HTTP/1.0\r\nContent-Length: %lu\r\nHost: %s\r\n\r\n", command, url, content-length, host. Get "/tor/" to fetch a full directory. Get "/tor/dir.z" to fetch a compressed full directory. Get "/tor/running-routers" to fetch a network-status descriptor. Post "/tor/" to post a server descriptor, with the body of the request containing the descriptor. "host" is used to specify the address:port of the dirserver, so the request can survive going through HTTP proxies.