[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] Spec cleanups: improved accuracy and detail of description of
Update of /home/or/cvsroot/doc
In directory moria.mit.edu:/tmp/cvs-serv8363/doc
Modified Files:
tor-spec.txt
Log Message:
Spec cleanups: improved accuracy and detail of description of
directory formats, added ipv6 exit spec.
(The IPv6 stuff is only for exiting connections: ORs still need IPv4 addrs)
Index: tor-spec.txt
===================================================================
RCS file: /home/or/cvsroot/doc/tor-spec.txt,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -d -r1.62 -r1.63
--- tor-spec.txt 8 Aug 2004 18:59:17 -0000 1.62
+++ tor-spec.txt 9 Aug 2004 04:23:15 -0000 1.63
@@ -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 @@
- 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 @@
"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 @@
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 @@
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 @@
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 @@
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
+ 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 @@
"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 @@
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: