|
@@ -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)?
|
|
|
+
|
|
|
+ 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
|
|
|
- "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
|
|
|
-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.
|
|
|
+ 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.
|
|
|
|
|
|
-"opt" is reserved for non-critical future extensions.
|
|
|
+ "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.
|
|
|
+
|
|
|
+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.
|
|
|
|
|
|
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:
|