commit 113b25fdf662b869318c8add6d5087297673f5a4 Author: Nick Mathewson <nickm@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. -