Move some deprecated specs to attic subdir. bug 3529

3 files changed, 1061 insertions, 0 deletions

diff --git a/attic/bridges-spec.txt b/attic/bridges-spec.txt
new file mode 100644
index 0000000..6471188
--- /dev/null
+++ b/attic/bridges-spec.txt
@@ -0,0 +1,249 @@
+
+                          Tor bridges specification
+
+0. Preface
+
+  This document describes the design decisions around support for bridge
+  users, bridge relays, and bridge authorities. It acts as an overview
+  of the bridge design and deployment for developers, and it also tries
+  to point out limitations in the current design and implementation.
+
+  For more details on what all of these mean, look at blocking.tex in
+  /doc/design-paper/
+
+1. Bridge relays
+
+  Bridge relays are just like normal Tor relays except they don't publish
+  their server descriptors to the main directory authorities.
+
+1.1. PublishServerDescriptor
+
+  To configure your relay to be a bridge relay, just add
+    BridgeRelay 1
+    PublishServerDescriptor bridge
+  to your torrc. This will cause your relay to publish its descriptor
+  to the bridge authorities rather than to the default authorities.
+
+  Alternatively, you can say
+    BridgeRelay 1
+    PublishServerDescriptor 0
+  which will cause your relay to not publish anywhere. This could be
+  useful for private bridges.
+
+1.2. Recommendations.
+
+  Bridge relays should use an exit policy of "reject *:*". This is
+  because they only need to relay traffic between the bridge users
+  and the rest of the Tor network, so there's no need to let people
+  exit directly from them.
+
+  We invented the RelayBandwidth* options for this situation: Tor clients
+  who want to allow relaying too. See proposal 111 for details. Relay
+  operators should feel free to rate-limit their relayed traffic.
+
+1.3. Implementation note.
+
+  Vidalia 0.0.15 has turned its "Relay" settings page into a tri-state
+  "Don't relay" / "Relay for the Tor network" / "Help censored users".
+
+  If you click the third choice, it forces your exit policy to reject *:*.
+
+  If all the bridges end up on port 9001, that's not so good. On the
+  other hand, putting the bridges on a low-numbered port in the Unix
+  world requires jumping through extra hoops. The current compromise is
+  that Vidalia makes the ORPort default to 443 on Windows, and 9001 on
+  other platforms.
+
+  At the bottom of the relay config settings window, Vidalia displays
+  the bridge identifier to the operator (see Section 3.1) so he can pass
+  it on to bridge users.
+
+2. Bridge authorities.
+
+  Bridge authorities are like normal v3 directory authorities, except
+  they don't create their own network-status documents or votes. So if
+  you ask a bridge authority for a network-status document or consensus,
+  they behave like a directory mirror: they give you one from one of
+  the main authorities. But if you ask the bridge authority for the
+  descriptor corresponding to a particular identity fingerprint, it will
+  happily give you the latest descriptor for that fingerprint.
+
+  To become a bridge authority, add these lines to your torrc:
+    AuthoritativeDirectory 1
+    BridgeAuthoritativeDir 1
+
+  Right now there's one bridge authority, running on the Tonga relay.
+
+2.1. Exporting bridge-purpose descriptors
+
+  We've added a new purpose for server descriptors: the "bridge"
+  purpose. With the new router-descriptors file format that includes
+  annotations, it's easy to look through it and find the bridge-purpose
+  descriptors.
+
+  Currently we export the bridge descriptors from Tonga to the
+  BridgeDB server, so it can give them out according to the policies
+  in blocking.pdf.
+
+2.2. Reachability/uptime testing
+
+  Right now the bridge authorities do active reachability testing of
+  bridges, so we know which ones to recommend for users.
+
+  But in the design document, we suggested that bridges should publish
+  anonymously (i.e. via Tor) to the bridge authority, so somebody watching
+  the bridge authority can't just enumerate all the bridges. But if we're
+  doing active measurement, the game is up. Perhaps we should back off on
+  this goal, or perhaps we should do our active measurement anonymously?
+
+  Answering this issue is scheduled for 0.2.1.x.
+
+2.3. Future work: migrating to multiple bridge authorities
+
+  Having only one bridge authority is both a trust bottleneck (if you
+  break into one place you learn about every single bridge we've got)
+  and a robustness bottleneck (when it's down, bridge users become sad).
+
+  Right now if we put up a second bridge authority, all the bridges would
+  publish to it, and (assuming the code works) bridge users would query
+  a random bridge authority. This resolves the robustness bottleneck,
+  but makes the trust bottleneck even worse.
+
+  In 0.2.2.x and later we should think about better ways to have multiple
+  bridge authorities.
+
+3. Bridge users.
+
+  Bridge users are like ordinary Tor users except they use encrypted
+  directory connections by default, and they use bridge relays as both
+  entry guards (their first hop) and directory guards (the source of
+  all their directory information).
+
+  To become a bridge user, add the following line to your torrc:
+    UseBridges 1
+
+  and then add at least one "Bridge" line to your torrc based on the
+  format below.
+
+3.1. Format of the bridge identifier.
+
+  The canonical format for a bridge identifier contains an IP address,
+  an ORPort, and an identity fingerprint:
+    bridge 128.31.0.34:9009 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
+
+  However, the identity fingerprint can be left out, in which case the
+  bridge user will connect to that relay and use it as a bridge regardless
+  of what identity key it presents:
+    bridge 128.31.0.34:9009
+  This might be useful for cases where only short bridge identifiers
+  can be communicated to bridge users.
+
+  In a future version we may also support bridge identifiers that are
+  only a key fingerprint:
+    bridge 4C17 FB53 2E20 B2A8 AC19 9441 ECD2 B017 7B39 E4B1
+  and the bridge user can fetch the latest descriptor from the bridge
+  authority (see Section 3.4).
+
+3.2. Bridges as entry guards
+
+  For now, bridge users add their bridge relays to their list of "entry
+  guards" (see path-spec.txt for background on entry guards). They are
+  managed by the entry guard algorithms exactly as if they were a normal
+  entry guard -- their keys and timing get cached in the "state" file,
+  etc. This means that when the Tor user starts up with "UseBridges"
+  disabled, he will skip past the bridge entries since they won't be
+  listed as up and usable in his networkstatus consensus. But to be clear,
+  the "entry_guards" list doesn't currently distinguish guards by purpose.
+
+  Internally, each bridge user keeps a smartlist of "bridge_info_t"
+  that reflects the "bridge" lines from his torrc along with a download
+  schedule (see Section 3.5 below). When he starts Tor, he attempts
+  to fetch a descriptor for each configured bridge (see Section 3.4
+  below). When he succeeds at getting a descriptor for one of the bridges
+  in his list, he adds it directly to the entry guard list using the
+  normal add_an_entry_guard() interface. Once a bridge descriptor has
+  been added, should_delay_dir_fetches() will stop delaying further
+  directory fetches, and the user begins to bootstrap his directory
+  information from that bridge (see Section 3.3).
+
+  Currently bridge users cache their bridge descriptors to the
+  "cached-descriptors" file (annotated with purpose "bridge"), but
+  they don't make any attempt to reuse descriptors they find in this
+  file. The theory is that either the bridge is available now, in which
+  case you can get a fresh descriptor, or it's not, in which case an
+  old descriptor won't do you much good.
+
+  We could disable writing out the bridge lines to the state file, if
+  we think this is a problem.
+
+  As an exception, if we get an application request when we have one
+  or more bridge descriptors but we believe none of them are running,
+  we mark them all as running again. This is similar to the exception
+  already in place to help long-idle Tor clients realize they should
+  fetch fresh directory information rather than just refuse requests.
+
+3.3. Bridges as directory guards
+
+  In addition to using bridges as the first hop in their circuits, bridge
+  users also use them to fetch directory updates. Other than initial
+  bootstrapping to find a working bridge descriptor (see Section 3.4
+  below), all further non-anonymized directory fetches will be redirected
+  to the bridge.
+
+  This means that bridge relays need to have cached answers for all
+  questions the bridge user might ask. This makes the upgrade path
+  tricky --- for example, if we migrate to a v4 directory design, the
+  bridge user would need to keep using v3 so long as his bridge relays
+  only knew how to answer v3 queries.
+
+  In a future design, for cases where the user has enough information
+  to build circuits yet the chosen bridge doesn't know how to answer a
+  given query, we might teach bridge users to make an anonymized request
+  to a more suitable directory server.
+
+3.4. How bridge users get their bridge descriptor
+
+  Bridge users can fetch bridge descriptors in two ways: by going directly
+  to the bridge and asking for "/tor/server/authority", or by going to
+  the bridge authority and asking for "/tor/server/fp/ID". By default,
+  they will only try the direct queries. If the user sets
+    UpdateBridgesFromAuthority 1
+  in his config file, then he will try querying the bridge authority
+  first for bridges where he knows a digest (if he only knows an IP
+  address and ORPort, then his only option is a direct query).
+
+  If the user has at least one working bridge, then he will do further
+  queries to the bridge authority through a full three-hop Tor circuit.
+  But when bootstrapping, he will make a direct begin_dir-style connection
+  to the bridge authority.
+
+  As of Tor 0.2.0.10-alpha, if the user attempts to fetch a descriptor
+  from the bridge authority and it returns a 404 not found, the user
+  will automatically fall back to trying a direct query. Therefore it is
+  recommended that bridge users always set UpdateBridgesFromAuthority,
+  since at worst it will delay their fetches a little bit and notify
+  the bridge authority of the identity fingerprint (but not location)
+  of their intended bridges.
+
+3.5. Bridge descriptor retry schedule
+
+  Bridge users try to fetch a descriptor for each bridge (using the
+  steps in Section 3.4 above) on startup. Whenever they receive a
+  bridge descriptor, they reschedule a new descriptor download for 1
+  hour from then.
+
+  If on the other hand it fails, they try again after 15 minutes for the
+  first attempt, after 15 minutes for the second attempt, and after 60
+  minutes for subsequent attempts.
+
+  In 0.2.2.x we should come up with some smarter retry schedules.
+
+3.6. Implementation note.
+
+  Vidalia 0.1.0 has a new checkbox in its Network config window called
+  "My ISP blocks connections to the Tor network." Users who click that
+  box change their configuration to:
+    UseBridges 1
+    UpdateBridgesFromAuthority 1
+  and should add at least one bridge identifier.
+
diff --git a/attic/control-spec-v0.txt b/attic/control-spec-v0.txt
new file mode 100644
index 0000000..3515d39
--- /dev/null
+++ b/attic/control-spec-v0.txt
@@ -0,0 +1,498 @@
+
+                   TC: A Tor control protocol (Version 0)
+
+-1. Deprecation
+
+THIS PROTOCOL IS DEPRECATED.  It is still documented here because Tor
+0.1.1.x happens to support much of it; but the support for v0 is not
+maintained, so you should expect it to rot in unpredictable ways.  Support
+for v0 will be removed some time after Tor 0.1.2.
+
+0. Scope
+
+This document describes an implementation-specific protocol that is used
+for other programs (such as frontend user-interfaces) to communicate
+with a locally running Tor process.  It is not part of the Tor onion
+routing protocol.
+
+We're trying to be pretty extensible here, but not infinitely
+forward-compatible.
+
+1. Protocol outline
+
+TC is a bidirectional message-based protocol.  It assumes an underlying
+stream for communication between a controlling process (the "client") and
+a Tor process (the "server").  The stream may be implemented via TCP,
+TLS-over-TCP, a Unix-domain socket, or so on, but it must provide
+reliable in-order delivery.  For security, the stream should not be
+accessible by untrusted parties.
+
+In TC, the client and server send typed variable-length messages to each
+other over the underlying stream.  By default, all messages from the server
+are in response to messages from the client.  Some client requests, however,
+will cause the server to send messages to the client indefinitely far into
+the future.
+
+Servers respond to messages in the order they're received.
+
+2. Message format
+
+The messages take the following format:
+
+   Length [2 octets; big-endian]
+   Type   [2 octets; big-endian]
+   Body   [Length octets]
+
+Upon encountering a recognized Type, implementations behave as described in
+section 3 below.  If the type is not recognized, servers respond with an
+"ERROR" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
+the message.
+
+2.1. Types and encodings
+
+  All numbers are given in big-endian (network) order.
+
+  OR identities are given in hexadecimal, in the same format as identity key
+  fingerprints, but without spaces; see tor-spec.txt for more information.
+
+3. Message types
+
+  Message types are drawn from the following ranges:
+
+  0x0000-0xEFFF   : Reserved for use by official versions of this spec.
+  0xF000-0xFFFF   : Unallocated; usable by unofficial extensions.
+
+3.1. ERROR (Type 0x0000)
+
+  Sent in response to a message that could not be processed as requested.
+
+  The body of the message begins with a 2-byte error code.  The following
+  values are defined:
+
+        0x0000 Unspecified error
+               []
+
+        0x0001 Internal error
+               [Something went wrong inside Tor, so that the client's
+                request couldn't be fulfilled.]
+
+        0x0002 Unrecognized message type
+               [The client sent a message type we don't understand.]
+
+        0x0003 Syntax error
+               [The client sent a message body in a format we can't parse.]
+
+        0x0004 Unrecognized configuration key
+               [The client tried to get or set a configuration option we don't
+                recognize.]
+
+        0x0005 Invalid configuration value
+               [The client tried to set a configuration option to an
+                incorrect, ill-formed, or impossible value.]
+
+        0x0006 Unrecognized byte code
+               [The client tried to set a byte code (in the body) that
+                we don't recognize.]
+
+        0x0007 Unauthorized.
+               [The client tried to send a command that requires
+                authorization, but it hasn't sent a valid AUTHENTICATE
+                message.]
+
+        0x0008 Failed authentication attempt
+               [The client sent a well-formed authorization message.]
+
+        0x0009 Resource exhausted
+               [The server didn't have enough of a given resource to
+                fulfill a given request.]
+
+        0x000A No such stream
+
+        0x000B No such circuit
+
+        0x000C No such OR
+
+  The rest of the body should be a human-readable description of the error.
+
+  In general, new error codes should only be added when they don't fall under
+  one of the existing error codes.
+
+3.2. DONE (Type 0x0001)
+
+  Sent from server to client in response to a request that was successfully
+  completed, with no more information needed.  The body is usually empty but
+  may contain a message.
+
+3.3. SETCONF (Type 0x0002)
+
+  Change the value of a configuration variable. The body contains a list of
+  newline-terminated key-value configuration lines.  An individual key-value
+  configuration line consists of the key, followed by a space, followed by
+  the value. The server behaves as though it had just read the key-value pair
+  in its configuration file.
+
+  The server responds with a DONE message on success, or an ERROR message on
+  failure.
+
+  When a configuration options takes multiple values, or when multiple
+  configuration keys form a context-sensitive group (see below), then
+  setting _any_ of the options in a SETCONF command is taken to reset all of
+  the others.  For example, if two ORBindAddress values are configured,
+  and a SETCONF command arrives containing a single ORBindAddress value, the
+  new command's value replaces the two old values.
+
+  To _remove_ all settings for a given option entirely (and go back to its
+  default value), send a single line containing the key and no value.
+
+3.4. GETCONF (Type 0x0003)
+
+  Request the value of a configuration variable.  The body contains one or
+  more NL-terminated strings for configuration keys.  The server replies
+  with a CONFVALUE message.
+
+  If an option appears multiple times in the configuration, all of its
+  key-value pairs are returned in order.
+
+  Some options are context-sensitive, and depend on other options with
+  different keywords.  These cannot be fetched directly.  Currently there
+  is only one such option: clients should use the "HiddenServiceOptions"
+  virtual keyword to get all HiddenServiceDir, HiddenServicePort,
+  HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
+
+3.5. CONFVALUE (Type 0x0004)
+
+  Sent in response to a GETCONF message; contains a list of "Key Value\n"
+  (A non-whitespace keyword, a single space, a non-NL value, a NL)
+  strings.
+
+3.6. SETEVENTS (Type 0x0005)
+
+  Request the server to inform the client about interesting events.
+  The body contains a list of 2-byte event codes (see "event" below).
+  Any events *not* listed in the SETEVENTS body are turned off; thus, sending
+  SETEVENTS with an empty body turns off all event reporting.
+
+  The server responds with a DONE message on success, and an ERROR message
+  if one of the event codes isn't recognized.  (On error, the list of active
+  event codes isn't changed.)
+
+3.7. EVENT (Type 0x0006)
+
+  Sent from the server to the client when an event has occurred and the
+  client has requested that kind of event.  The body contains a 2-byte
+  event code followed by additional event-dependent information.  Event
+  codes are:
+      0x0001 -- Circuit status changed
+
+                Status [1 octet]
+                   0x00 Launched - circuit ID assigned to new circuit
+                   0x01 Built    - all hops finished, can now accept streams
+                   0x02 Extended - one more hop has been completed
+                   0x03 Failed   - circuit closed (was not built)
+                   0x04 Closed   - circuit closed (was built)
+                Circuit ID [4 octets]
+                   (Must be unique to Tor process/time)
+                Path [NUL-terminated comma-separated string]
+                   (For extended/failed, is the portion of the path that is
+                   built)
+
+      0x0002 -- Stream status changed
+
+                Status [1 octet]
+                   (Sent connect=0,sent resolve=1,succeeded=2,failed=3,
+                    closed=4, new connection=5, new resolve request=6,
+                    stream detached from circuit and still retriable=7)
+                Stream ID [4 octets]
+                   (Must be unique to Tor process/time)
+                Target (NUL-terminated address-port string]
+
+      0x0003 -- OR Connection status changed
+
+                Status [1 octet]
+                   (Launched=0,connected=1,failed=2,closed=3)
+                OR nickname/identity [NUL-terminated]
+
+      0x0004 -- Bandwidth used in the last second
+
+                Bytes read [4 octets]
+                Bytes written [4 octets]
+
+      0x0005 -- Notice/warning/error occurred
+
+                Message [NUL-terminated]
+
+                <obsolete: use 0x0007-0x000B instead.>
+
+      0x0006 -- New descriptors available
+
+                OR List [NUL-terminated, comma-delimited list of
+                    OR identity]
+
+      0x0007 -- Debug message occurred
+      0x0008 -- Info message occurred
+      0x0009 -- Notice message occurred
+      0x000A -- Warning message occurred
+      0x000B -- Error message occurred
+
+                Message [NUL-terminated]
+
+3.8. AUTHENTICATE (Type 0x0007)
+
+  Sent from the client to the server.  Contains a 'magic cookie' to prove
+  that client is really allowed to control this Tor process.  The server
+  responds with DONE or ERROR.
+
+  The format of the 'cookie' is implementation-dependent; see 4.1 below for
+  information on how the standard Tor implementation handles it.
+
+3.9. SAVECONF (Type 0x0008)
+
+  Sent from the client to the server. Instructs the server to write out
+  its config options into its torrc. Server returns DONE if successful, or
+  ERROR if it can't write the file or some other error occurs.
+
+3.10. SIGNAL (Type 0x0009)
+
+  Sent from the client to the server. The body contains one byte that
+  indicates the action the client wishes the server to take.
+
+       1 (0x01) -- Reload: reload config items, refetch directory.
+       2 (0x02) -- Controlled shutdown: if server is an OP, exit immediately.
+                   If it's an OR, close listeners and exit after 30 seconds.
+      10 (0x0A) -- Dump stats: log information about open connections and
+                   circuits.
+      12 (0x0C) -- Debug: switch all open logs to loglevel debug.
+      15 (0x0F) -- Immediate shutdown: clean up and exit now.
+
+  The server responds with DONE if the signal is recognized (or simply
+  closes the socket if it was asked to close immediately), else ERROR.
+
+3.11. MAPADDRESS (Type 0x000A)
+
+  Sent from the client to the server.  The body contains a sequence of
+  address mappings, each consisting of the address to be mapped, a single
+  space, the replacement address, and a NL character.
+
+  Addresses may be IPv4 addresses, IPv6 addresses, or hostnames.
+
+  The client sends this message to the server in order to tell it that future
+  SOCKS requests for connections to the original address should be replaced
+  with connections to the specified replacement address.  If the addresses
+  are well-formed, and the server is able to fulfill the request, the server
+  replies with a single DONE message containing the source and destination
+  addresses.  If request is malformed, the server replies with a syntax error
+  message.  The server can't fulfill the request, it replies with an internal
+  ERROR message.
+
+  The client may decline to provide a body for the original address, and
+  instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
+  "." for hostname), signifying that the server should choose the original
+  address itself, and return that address in the DONE message.  The server
+  should ensure that it returns an element of address space that is unlikely
+  to be in actual use.  If there is already an address mapped to the
+  destination address, the server may reuse that mapping.
+
+  If the original address is already mapped to a different address, the old
+  mapping is removed.  If the original address and the destination address
+  are the same, the server removes any mapping in place for the original
+  address.
+
+  {Note: This feature is designed to be used to help Tor-ify applications
+  that need to use SOCKS4 or hostname-less SOCKS5.  There are three
+  approaches to doing this:
+     1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
+     2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
+        feature) to resolve the hostname remotely.  This doesn't work
+        with special addresses like x.onion or x.y.exit.
+     3. Use MAPADDRESS to map an IP address to the desired hostname, and then
+        arrange to fool the application into thinking that the hostname
+        has resolved to that IP.
+  This functionality is designed to help implement the 3rd approach.}
+
+  [XXXX When, if ever, can mappings expire?  Should they expire?]
+  [XXXX What addresses, if any, are safe to use?]
+
+3.12 GETINFO (Type 0x000B)
+
+  Sent from the client to the server.  The message body is as for GETCONF:
+  one or more NL-terminated strings.  The server replies with an INFOVALUE
+  message.
+
+  Unlike GETCONF, this message is used for data that are not stored in the
+  Tor configuration file, but instead.
+
+  Recognized key and their values include:
+
+    "version" -- The version of the server's software, including the name
+      of the software. (example: "Tor 0.0.9.4")
+
+    "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest server
+      descriptor for a given OR, NUL-terminated.  If no such OR is known, the
+      corresponding value is an empty string.
+
+    "network-status" -- a space-separated list of all known OR identities.
+      This is in the same format as the router-status line in directories;
+      see tor-spec.txt for details.
+
+    "addr-mappings/all"
+    "addr-mappings/config"
+    "addr-mappings/cache"
+    "addr-mappings/control" -- a NL-terminated list of address mappings, each
+      in the form of "from-address" SP "to-address".  The 'config' key
+      returns those address mappings set in the configuration; the 'cache'
+      key returns the mappings in the client-side DNS cache; the 'control'
+      key returns the mappings set via the control interface; the 'all'
+      target returns the mappings set through any mechanism.
+
+3.13 INFOVALUE (Type 0x000C)
+
+  Sent from the server to the client in response to a GETINFO message.
+  Contains one or more items of the format:
+
+     Key          [(NUL-terminated string)]
+     Value        [(NUL-terminated string)]
+
+  The keys match those given in the GETINFO message.
+
+3.14 EXTENDCIRCUIT (Type 0x000D)
+
+  Sent from the client to the server.  The message body contains two fields:
+      Circuit ID [4 octets]
+      Path [NUL-terminated, comma-delimited string of OR nickname/identity]
+
+  This request takes one of two forms: either the Circuit ID is zero, in
+  which case it is a request for the server to build a new circuit according
+  to the specified path, or the Circuit ID is nonzero, in which case it is a
+  request for the server to extend an existing circuit with that ID according
+  to the specified path.
+
+  If the request is successful, the server sends a DONE message containing
+  a message body consisting of the four-octet Circuit ID of the newly created
+  circuit.
+
+3.15 ATTACHSTREAM (Type 0x000E)
+
+  Sent from the client to the server.  The message body contains two fields:
+      Stream ID [4 octets]
+      Circuit ID [4 octets]
+
+  This message informs the server that the specified stream should be
+  associated with the specified circuit.  Each stream may be associated with
+  at most one circuit, and multiple streams may share the same circuit.
+  Streams can only be attached to completed circuits (that is, circuits that
+  have sent a circuit status 'built' event).
+
+  If the circuit ID is 0, responsibility for attaching the given stream is
+  returned to Tor.
+
+  {Implementation note: By default, Tor automatically attaches streams to
+  circuits itself, unless the configuration variable
+  "__LeaveStreamsUnattached" is set to "1".  Attempting to attach streams
+  via TC when "__LeaveStreamsUnattached" is false may cause a race between
+  Tor and the controller, as both attempt to attach streams to circuits.}
+
+3.16 POSTDESCRIPTOR (Type 0x000F)
+
+  Sent from the client to the server.  The message body contains one field:
+      Descriptor [NUL-terminated string]
+
+  This message informs the server about a new descriptor.
+
+  The descriptor, when parsed, must contain a number of well-specified
+  fields, including fields for its nickname and identity.
+
+  If there is an error in parsing the descriptor, the server must send an
+  appropriate error message.  If the descriptor is well-formed but the server
+  chooses not to add it, it must reply with a DONE message whose body
+  explains why the server was not added.
+
+3.17 FRAGMENTHEADER (Type 0x0010)
+
+  Sent in either direction.  Used to encapsulate messages longer than 65535
+  bytes in length.
+
+      Underlying type [2 bytes]
+      Total Length    [4 bytes]
+      Data            [Rest of message]
+
+  A FRAGMENTHEADER message MUST be followed immediately by a number of
+  FRAGMENT messages, such that lengths of the "Data" fields of the
+  FRAGMENTHEADER and FRAGMENT messages add to the "Total Length" field of the
+  FRAGMENTHEADER message.
+
+  Implementations MUST NOT fragment messages of length less than 65536 bytes.
+  Implementations MUST be able to process fragmented messages that not
+  optimally packed.
+
+3.18 FRAGMENT (Type 0x0011)
+
+      Data           [Entire message]
+
+  See FRAGMENTHEADER for more information
+
+3.19 REDIRECTSTREAM (Type 0x0012)
+
+  Sent from the client to the server. The message body contains two fields:
+      Stream ID [4 octets]
+      Address [variable-length, NUL-terminated.]
+
+  Tells the server to change the exit address on the specified stream.  No
+  remapping is performed on the new provided address.
+
+  To be sure that the modified address will be used, this event must be sent
+  after a new stream event is received, and before attaching this stream to
+  a circuit.
+
+3.20 CLOSESTREAM (Type 0x0013)
+
+  Sent from the client to the server.  The message body contains three
+  fields:
+      Stream ID [4 octets]
+      Reason    [1 octet]
+      Flags     [1 octet]
+
+  Tells the server to close the specified stream.  The reason should be
+  one of the Tor RELAY_END reasons given in tor-spec.txt.  Flags is not
+  used currently.  Tor may hold the stream open for a while to flush
+  any data that is pending.
+
+3.21 CLOSECIRCUIT (Type 0x0014)
+
+  Sent from the client to the server.  The message body contains two
+  fields:
+     Circuit ID [4 octets]
+     Flags      [1 octet]
+
+  Tells the server to close the specified circuit.  If the LSB of the flags
+  field is nonzero, do not close the circuit unless it is unused.
+
+4. Implementation notes
+
+4.1. Authentication
+
+  By default, the current Tor implementation trusts all local users.
+
+  If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
+  file named "control_auth_cookie" into its data directory.  To authenticate,
+  the controller must send the contents of this file.
+
+  If the 'HashedControlPassword' option is set, it must contain the salted
+  hash of a secret password.  The salted hash is computed according to the
+  S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
+  This is then encoded in hexadecimal, prefixed by the indicator sequence
+  "16:".  Thus, for example, the password 'foo' could encode to:
+     16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
+        ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+           salt                       hashed value
+                       indicator
+  You can generate the salt of a password by calling
+           'tor --hash-password <password>'
+  or by using the example code in the Python and Java controller libraries.
+  To authenticate under this scheme, the controller sends Tor the original
+  secret that was used to generate the password.
+
+4.2. Don't let the buffer get too big.
+
+  If you ask for lots of events, and 16MB of them queue up on the buffer,
+  the Tor process will close the socket.
+
diff --git a/attic/dir-spec-v1.txt b/attic/dir-spec-v1.txt
new file mode 100644
index 0000000..a92fc79
--- /dev/null
+++ b/attic/dir-spec-v1.txt
@@ -0,0 +1,314 @@
+
+                         Tor Protocol Specification
+
+                              Roger Dingledine
+                               Nick Mathewson
+
+0. Preliminaries
+
+  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.
+
+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 section 3 above)
+
+     "router-status" list
+
+        (see section 3 above)
+
+     "directory-signature" NL signature
+
+        (see section 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.
+