diff --git a/doc/tor-spec.txt b/doc/tor-spec.txt index a435830cbd..400033ee9d 100644 --- a/doc/tor-spec.txt +++ b/doc/tor-spec.txt @@ -1,9 +1,13 @@ $Id$ -Tor Spec + Tor Spec + + Roger Dingledine + Nick Mathewson + (who else wrote this?) Note: This is an attempt to specify Tor as it exists as implemented in -early March, 2004. It is not recommended that others implement this +mid-August, 2004. It is not recommended that others implement this design as it stands; future versions of Tor will implement improved protocols. @@ -14,7 +18,6 @@ TODO: (very soon) - REASON_CONNECTFAILED should include an IP. - Copy prose from tor-design to make everything more readable. - 0. Notation: PK -- a public key. @@ -39,6 +42,11 @@ TODO: (very soon) "A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6" "49286651ECE65381FFFFFFFFFFFFFFFF" + All "hashes" are 20-byte SHA1 cryptographic digests. + + When we refer to "the hash of a public key", we mean the SHA1 hash of the + ASN.1 encoding of an RSA public key (as specified in PKCS.1). + 1. System overview Onion Routing is a distributed overlay network designed to anonymize @@ -403,7 +411,8 @@ TODO: (very soon) ADDRESS | ':' | PORT | [00] where ADDRESS is be a DNS hostname, or an IPv4 address in - dotted-quad format; and where PORT is encoded in decimal. + dotted-quad format, or an IPv6 address surrounded by square brackets; + and where PORT is encoded in decimal. [What is the [00] for? -NM] [It's so the payload is easy to parse out with string funcs -RD] @@ -413,7 +422,8 @@ TODO: (very soon) address cannot be resolved, or a connection can't be established, the exit node replies with a RELAY_END cell. (See 5.4 below.) Otherwise, the exit node replies with a RELAY_CONNECTED cell, whose - payload is the 4-byte IP address to which the connection was made. + payload is the 4-byte IPv4 address or the 16-byte IPv6 address to which + the connection was made. The OP waits for a RELAY_CONNECTED cell before sending any data. Once a connection has been established, the OP and exit node @@ -445,9 +455,8 @@ TODO: (very soon) 6 -- REASON_DONE (anonymized TCP connection was closed) 7 -- REASON_TIMEOUT (OR timed out while connecting [???-NM]) - (With REASON_EXITPOLICY, the 4-byte IP address forms the optional - data; no other reason currently has extra data.) - + (With REASON_EXITPOLICY, the 4-byte IPv4 address or 16-byte IPv6 address + forms the optional data; no other reason currently has extra data.) *** [The rest of this section describes unimplemented functionality.] @@ -584,40 +593,106 @@ More formally: 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. + 7.1. 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". Additionally, a router descriptor MAY contain any number of -"accept", "reject", and "opt" Items. Other than "router" and -"router-signature", the items may appear in any order. +"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)? - "ports" ORPort SocksPort DirPort - "bandwidth" bandwidth-avg bandwidth-burst - "platform" string - "published" YYYY-MM-DD HH:MM:SS - "onion-key" NL a public key in PEM format - "signing-key" NL a public key in PEM format - "accept" string - "reject" string - "router-signature" NL "-----BEGIN SIGNATURE-----" NL Signature NL - "-----END SIGNATURE-----" - "opt" SP keyword string? NL,Object? -ORport ::= port where the router listens for routers/proxies (speaking cells) -SocksPort ::= where the router listens for applications (speaking socks) -DirPort ::= where the router listens for directory download requests -bandwidth-avg ::= maximum average bandwidth, in bytes/s -bandwidth-burst ::= maximum bandwidth spike, in bytes/s + Indicates the beginning of a router descriptor. "address" must be an + IPv4 address in dotted-quad format. The Port values will soon be + deprecated; using them here is equivalent to using them in a "ports" + item. + + "ports" ORPort SocksPort DirPort + + Indicates 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 the port at which this OR accepts SOCKS + connections; 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 + + 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. + + "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 (20 byte SHA1 hash of asn1 encoded public key, encoded + in hex, with spaces after every 4 characters) for this router's + identity key. + + "uptime" + + The number of seconds that this OR 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 SHA1 + 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. + nickname ::= between 1 and 19 alphanumeric characters, case-insensitive. -Bandwidth and ports are required; if they are not included in the router -line, they must appear in "bandwidth" and "ports" lines. +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 -"opt" is reserved for non-critical future extensions. +Ports are required; if they are not included in the router +line, they must appear in the "ports" lines. 7.2. Directory format @@ -628,12 +703,33 @@ items, a directory includes any number of router descriptors, and a single "directory-signature" item. "signed-directory" + + Indicates the start of a + "published" YYYY-MM-DD HH:MM:SS + + The time at which this directory was generated and signed, in GMT. + "recommended-software" comma-separated-version-list - "running-routers" comma-separated-nickname-list + + A list of which versions of which implementations are currently + believed to be secure and compatible with the network. + + "running-routers" comma-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 to be running; otherwise, it is believed not 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". + "directory-signature" nickname-of-dirserver NL Signature -Note: The router descriptor for the directory server must appear first. +Note: The router descriptor for the directory server MUST appear first. The signature is computed by computing the SHA-1 hash of the directory, from the characters "signed-directory", through the newline after "directory-signature". This digest is then padded with PKCS.1, @@ -644,11 +740,41 @@ it should reject only that router descriptor, and continue using the others. If it encounters an unrecognized keyword in the directory header, it should reject the entire directory. -7.3. Behavior of a directory server +7.3. 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 7.2 above) + + "running-routers" list + + (see 7.2 above) + + "directory-signature" NL signature + + (see 7.2 above) + +7.4. Behavior of a directory server lists nodes that are connected currently speaks http on a socket, spits out directory on request +A.1. Differences between spec and implementation + +- The current specification requires all ORs to have IPv4 addresses, but + allows servers to exit and resolve to IPv6 addresses, and to declare IPv6 + addresses in their exit policies. The current codebase has no IPv6 + support at all. + ----------- (for emacs) Local Variables: