Spec cleanups: improved accuracy and detail of description of

                                  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.

      - REASON_CONNECTFAILED should include an IP.

      - Copy prose from tor-design to make everything more readable.

0. Notation:

   PK -- a public key.

     "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

         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]

   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

       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.]

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

"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,

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: