[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[or-cvs] r6991: change the dir-spec to say that it's version 2 of the dir sp (tor/trunk/doc)

Author: arma
Date: 2006-08-08 18:56:26 -0400 (Tue, 08 Aug 2006)
New Revision: 6991

Added:
   tor/trunk/doc/dir-spec-v1.txt
Removed:
   tor/trunk/doc/dir-spec-v0.txt
Modified:
   tor/trunk/doc/dir-spec.txt
Log:
change the dir-spec to say that it's version 2 of the dir spec,
and move the v0 file to v1.


Deleted: tor/trunk/doc/dir-spec-v0.txt
===================================================================
--- tor/trunk/doc/dir-spec-v0.txt	2006-08-08 06:21:52 UTC (rev 6990)
+++ tor/trunk/doc/dir-spec-v0.txt	2006-08-08 22:56:26 UTC (rev 6991)
@@ -1,315 +0,0 @@
-$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.
-

Copied: tor/trunk/doc/dir-spec-v1.txt (from rev 6981, tor/trunk/doc/dir-spec-v0.txt)

Modified: tor/trunk/doc/dir-spec.txt
===================================================================
--- tor/trunk/doc/dir-spec.txt	2006-08-08 06:21:52 UTC (rev 6990)
+++ tor/trunk/doc/dir-spec.txt	2006-08-08 22:56:26 UTC (rev 6991)
@@ -1,11 +1,11 @@
 $Id$
 
-                      Tor directory protocol, version 1
+                      Tor directory protocol, version 2
 
 0. Scope and preliminaries
 
    This directory protocol is used by Tor version 0.1.1.x and later.  See
-   dir-spec-v0.txt for information on earlier versions.
+   dir-spec-v1.txt for information on earlier versions.
 
 0.1. Goals and motivation