From 113b25fdf662b869318c8add6d5087297673f5a4 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 23 Nov 2011 23:53:57 -0500 Subject: 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 +++++++++++++++++++++++++++++ 3 files changed, 1061 insertions(+) create mode 100644 attic/bridges-spec.txt create mode 100644 attic/control-spec-v0.txt create mode 100644 attic/dir-spec-v1.txt (limited to 'attic') 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] + + + + 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 "desc/name/" -- 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 ' + 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. + -- cgit v1.2.3-54-g00ecf