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)


svn:r2204

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)?
+
+      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: