commit 113b25fdf662b869318c8add6d5087297673f5a4
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Wed Nov 23 23:53:57 2011 -0500
Move some deprecated specs to attic subdir. bug 3529
---
attic/bridges-spec.txt | 249 ++++++++++++++++++++++
attic/control-spec-v0.txt | 498 +++++++++++++++++++++++++++++++++++++++++++++
attic/dir-spec-v1.txt | 314 ++++++++++++++++++++++++++++
bridges-spec.txt | 249 ----------------------
control-spec-v0.txt | 498 ---------------------------------------------
dir-spec-v1.txt | 314 ----------------------------
6 files changed, 1061 insertions(+), 1061 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.
+
diff --git a/bridges-spec.txt b/bridges-spec.txt
deleted file mode 100644
index 6471188..0000000
--- a/bridges-spec.txt
+++ /dev/null
@@ -1,249 +0,0 @@
-
- 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/control-spec-v0.txt b/control-spec-v0.txt
deleted file mode 100644
index 3515d39..0000000
--- a/control-spec-v0.txt
+++ /dev/null
@@ -1,498 +0,0 @@
-
- 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/dir-spec-v1.txt b/dir-spec-v1.txt
deleted file mode 100644
index a92fc79..0000000
--- a/dir-spec-v1.txt
+++ /dev/null
@@ -1,314 +0,0 @@
-
- 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.
-
