- tor-commits - lists.torproject.org

[torbrowser/maint-2.3] disable gcc warnings on windows and osx until next stable release
by erinn＠torproject.org 24 Nov '11

24 Nov '11

commit 1ffcd9dafb9dd76c3a29dd686e05a71a95599fb5 Author: Erinn Clark <erinn(a)torproject.org> Date: Thu Nov 24 14:07:11 2011 +0000 disable gcc warnings on windows and osx until next stable release --- build-scripts/osx.mk | 2 +- build-scripts/windows.mk | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/build-scripts/osx.mk b/build-scripts/osx.mk index 9af4622..f53941b 100644 --- a/build-scripts/osx.mk +++ b/build-scripts/osx.mk @@ -99,7 +99,7 @@ build-libevent: TOR_DIR=$(FETCH_DIR)/tor-$(TOR_VER) TOR_CFLAGS="-O -g -arch $(ARCH_TYPE) -I$(BUILT_DIR)/include -mmacosx-version-min=10.5 -isysroot /Developer/SDKs/MacOSX10.5.sdk" TOR_LDFLAGS="-L$(BUILT_DIR)/lib -Wl,-syslibroot,/Developer/SDKs/MacOSX10.5.sdk" -TOR_OPTS=--enable-gcc-warnings --enable-static-openssl --enable-static-libevent --with-openssl-dir=$(BUILT_DIR)/lib --with-libevent-dir=$(BUILT_DIR)/lib --prefix=$(BUILT_DIR) --disable-dependency-tracking CC="gcc-4.0" +TOR_OPTS=--enable-static-openssl --enable-static-libevent --with-openssl-dir=$(BUILT_DIR)/lib --with-libevent-dir=$(BUILT_DIR)/lib --prefix=$(BUILT_DIR) --disable-dependency-tracking CC="gcc-4.0" build-tor: cd $(TOR_DIR) && CFLAGS=$(TOR_CFLAGS) LDFLAGS=$(TOR_LDFLAGS) ./configure $(TOR_OPTS) cd $(TOR_DIR) && make diff --git a/build-scripts/windows.mk b/build-scripts/windows.mk index 6b74a0a..8f21e98 100644 --- a/build-scripts/windows.mk +++ b/build-scripts/windows.mk @@ -105,7 +105,7 @@ build-libevent: TOR_DIR=$(FETCH_DIR)/tor-$(TOR_VER) TOR_CFLAGS="-O -g -I$(BUILT_DIR)/include" TOR_LDFLAGS="-L$(BUILT_DIR)/lib -L$(BUILT_DIR)/bin" -TOR_OPTS=--enable-gcc-warnings --enable-static-libevent --with-libevent-dir=$(BUILT_DIR)/lib --prefix=$(BUILT_DIR) +TOR_OPTS=--enable-static-libevent --with-libevent-dir=$(BUILT_DIR)/lib --prefix=$(BUILT_DIR) build-tor: cd $(TOR_DIR) && CFLAGS=$(TOR_CFLAGS) LDFLAGS=$(TOR_LDFLAGS) ./configure $(TOR_OPTS) cd $(TOR_DIR) && make

1 0

[tor/master] Update check-spaces to remove false positive for timercmp macro
by arma＠torproject.org 24 Nov '11

24 Nov '11

commit 11221d0f17bf3ea6039249ad8b06b3a1afd6291d Author: Sebastian Hahn <sebastian(a)torproject.org> Date: Thu Nov 24 09:24:59 2011 +0100 Update check-spaces to remove false positive for timercmp macro The timercmp macro uses triggers a "space between function name and opening parentheses" warning for the check spaces script. Work around this by simply disabling the check for all "functions" named 'op()'. --- changes/checkSpaces | 5 +++++ contrib/checkSpace.pl | 2 +- 2 files changed, 6 insertions(+), 1 deletions(-) diff --git a/changes/checkSpaces b/changes/checkSpaces new file mode 100644 index 0000000..91f79ed --- /dev/null +++ b/changes/checkSpaces @@ -0,0 +1,5 @@ + o Minor bugfixes: + - Prevent a false positive from the check-spaces script by disabling + the "whitespace between function name and (" check for functions + named 'op()'. + diff --git a/contrib/checkSpace.pl b/contrib/checkSpace.pl index 6eb32e5..a18df99 100755 --- a/contrib/checkSpace.pl +++ b/contrib/checkSpace.pl @@ -97,7 +97,7 @@ for $fn (@ARGV) { if ($1 ne "if" and $1 ne "while" and $1 ne "for" and $1 ne "switch" and $1 ne "return" and $1 ne "int" and $1 ne "elsif" and $1 ne "WINAPI" and $2 ne "WINAPI" and - $1 ne "void" and $1 ne "__attribute__") { + $1 ne "void" and $1 ne "__attribute__" and $1 ne "op") { print " fn ():$fn:$.\n"; } }

1 0

[tor/master] appease check-spaces
by arma＠torproject.org 24 Nov '11

24 Nov '11

commit f77f9bddb8bf0dd6e9c3e0d94269aa23f459a272 Author: Sebastian Hahn <sebastian(a)torproject.org> Date: Thu Nov 24 09:20:51 2011 +0100 appease check-spaces --- src/common/compat_libevent.c | 5 ++--- 1 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/common/compat_libevent.c b/src/common/compat_libevent.c index 7a28c9b..0cedef8 100644 --- a/src/common/compat_libevent.c +++ b/src/common/compat_libevent.c @@ -243,8 +243,8 @@ tor_libevent_initialize(tor_libevent_cfg *torcfg) * again. */ #if defined(MS_WINDOWS) && defined(USE_BUFFEREVENTS) if (torcfg->disable_iocp == 0) { - log_warn(LD_GENERAL, "Unable to initialize Libevent. Trying again with " - "IOCP disabled."); + log_warn(LD_GENERAL, "Unable to initialize Libevent. Trying again " + "with IOCP disabled."); } else #endif { @@ -254,7 +254,6 @@ tor_libevent_initialize(tor_libevent_cfg *torcfg) torcfg->disable_iocp = 1; goto retry; } - } #else the_event_base = event_init();

1 0

[tor/master] Fix compile warning in tor_inet_pton() (on 64bit)
by arma＠torproject.org 24 Nov '11

24 Nov '11

commit 46d69cb9157abdf8655822963a6ad4c4161577a1 Author: Sebastian Hahn <sebastian(a)torproject.org> Date: Thu Nov 24 09:16:43 2011 +0100 Fix compile warning in tor_inet_pton() (on 64bit) This slipped through into 0.2.3.8-alpha unfortunately. --- changes/bug4554 | 4 ++++ src/common/compat.c | 2 +- 2 files changed, 5 insertions(+), 1 deletions(-) diff --git a/changes/bug4554 b/changes/bug4554 new file mode 100644 index 0000000..e4754c2 --- /dev/null +++ b/changes/bug4554 @@ -0,0 +1,4 @@ + o Minor bugfixes: + - Fix a compile warning in tor_inet_pton(). Bugfix on 0.2.3.8-alpha; + fixes bug 4554. + diff --git a/src/common/compat.c b/src/common/compat.c index 20c45af..9a2c9d7 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -1733,7 +1733,7 @@ tor_inet_pton(int af, const char *src, void *dst) return 0; if (TOR_ISXDIGIT(*src)) { char *next; - int len; + ssize_t len; long r = strtol(src, &next, 16); tor_assert(next != NULL); tor_assert(next != src);

1 0

[metrics-web/master] Consider perconnbw{rate, burst} consensus params valid.
by karsten＠torproject.org 24 Nov '11

24 Nov '11

commit 9eaf3f82f54c0a0876741d5b6941ffdadbcca855 Author: Karsten Loesing <karsten.loesing(a)gmx.net> Date: Thu Nov 24 09:23:17 2011 +0100 Consider perconnbw{rate,burst} consensus params valid. --- src/org/torproject/chc/Checker.java | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/org/torproject/chc/Checker.java b/src/org/torproject/chc/Checker.java index 5614c04..c7a2d00 100644 --- a/src/org/torproject/chc/Checker.java +++ b/src/org/torproject/chc/Checker.java @@ -179,9 +179,9 @@ public class Checker { ("circwindow,CircuitPriorityHalflifeMsec,refuseunknownexits," + "cbtdisabled,cbtnummodes,cbtrecentcount,cbtmaxtimeouts," + "cbtmincircs,cbtquantile,cbtclosequantile,cbttestfreq," - + "cbtmintimeout,cbtinitialtimeout,bwauthpid,bwauthbestratio," - + "bwauthcircs,bwauthkp,bwauthtd,bwauthti,bwauthtidecay," - + "bwauthdescbw").split(","))); + + "cbtmintimeout,cbtinitialtimeout,perconnbwburst,perconnbwrate," + + "bwauthpid,bwauthbestratio,bwauthcircs,bwauthkp,bwauthtd," + + "bwauthti,bwauthtidecay,bwauthdescbw").split(","))); SortedSet<String> conflicts = new TreeSet<String>(); for (Status vote : this.downloadedVotes) { Map<String, String> voteConsensusParams =

1 0

r25234: {website} User manual is now available in Arabic as well (website/trunk/docs/en)
by Runa Sandvik 24 Nov '11

24 Nov '11

Author: runa Date: 2011-11-24 07:58:02 +0000 (Thu, 24 Nov 2011) New Revision: 25234 Modified: website/trunk/docs/en/short-user-manual.wml Log: User manual is now available in Arabic as well Modified: website/trunk/docs/en/short-user-manual.wml =================================================================== --- website/trunk/docs/en/short-user-manual.wml 2011-11-23 17:05:54 UTC (rev 25233) +++ website/trunk/docs/en/short-user-manual.wml 2011-11-24 07:58:02 UTC (rev 25234) @@ -21,6 +21,7 @@ <p>The user manual is available in the following languages:</p> <ul> + <li><a href="https://www.torproject.org/dist/manual/short-user-manual_ar.xhtml">Arabic</a></li> <li><a href="https://www.torproject.org/dist/manual/short-user-manual_zh.xhtml">Chinese</a></li> <li><a href="https://www.torproject.org/dist/manual/short-user-manual_cs.xhtml">Czech</a></li> <li><a href="https://www.torproject.org/dist/manual/short-user-manual_nl.xhtml">Dutch</a></li>

1 0

[torspec/master] Move some deprecated specs to attic subdir. bug 3529
by nickm＠torproject.org 24 Nov '11

24 Nov '11

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

1 0

[tor/master] Merge branch 'bug2474'
by nickm＠torproject.org 23 Nov '11

23 Nov '11

commit f067067ee66e104b2d1e97fb881bf6d2277ea589 Merge: 3890c81 2b4d4ff Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Nov 23 17:14:54 2011 -0500 Merge branch 'bug2474' Had to resolve conflicts wrt the " (using bufferevents)" addition to the startup string. Conflicts: src/or/main.c changes/bug2474 | 5 +++++ src/or/main.c | 20 +++++++++++++++----- 2 files changed, 20 insertions(+), 5 deletions(-) diff --cc src/or/main.c index c1a7015,f6f47db..7008d38 --- a/src/or/main.c +++ b/src/or/main.c @@@ -2235,17 -1885,21 +2235,27 @@@ tor_init(int argc, char *argv[] default: add_temp_log(LOG_NOTICE); } + quiet_level = quiet; - log(LOG_NOTICE, LD_GENERAL, "Tor v%s%s. This is experimental software. " - "Do not rely on it for strong anonymity. (Running on %s)", get_version(), + { + const char *version = get_version(); - log_notice(LD_GENERAL, "Tor v%s running on %s.", version, get_uname()); ++ log_notice(LD_GENERAL, "Tor v%s%s running on %s.", version, +#ifdef USE_BUFFEREVENTS - " (with bufferevents)", ++ " (with bufferevents)", +#else - "", ++ "", +#endif - get_uname()); ++ get_uname()); + + log_notice(LD_GENERAL, "WARNING: Tor can't help you if you use it wrong. " + "Learn how to be safe at " + "https://www.torproject.org/download/download#warning"); + + if (strstr(version, "alpha") || strstr(version, "beta")) + log_notice(LD_GENERAL, "This version is not a stable Tor release. " + "Expect more bugs than usual."); + } - if (network_init()<0) { log_err(LD_BUG,"Error initializing network; exiting."); return -1;

1 0

[tor/master] Tweak the startup message to be more helpful
by nickm＠torproject.org 23 Nov '11

23 Nov '11

commit 4f7587a5ed64b2b5894157103d2d50f543434d64 Author: Nick Mathewson <nickm(a)torproject.org> Date: Thu Apr 28 22:00:22 2011 -0400 Tweak the startup message to be more helpful Instead of just saying "boogity boogity!" let's actually warn people that they need to configure stuff right to be safe, and point them at instructions for how to do that. Resolves bug 2474. --- changes/bug2474 | 5 +++++ src/or/main.c | 16 +++++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/changes/bug2474 b/changes/bug2474 new file mode 100644 index 0000000..02d3eb7 --- /dev/null +++ b/changes/bug2474 @@ -0,0 +1,5 @@ + o Minor features + - Try to make the introductory warning message that Tor prints on + startup more useful for actually finding help and information. + Resolves bug2474. + diff --git a/src/or/main.c b/src/or/main.c index a26be39..867dd60 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -1886,9 +1886,19 @@ tor_init(int argc, char *argv[]) add_temp_log(LOG_NOTICE); } - log(LOG_NOTICE, LD_GENERAL, "Tor v%s. This is experimental software. " - "Do not rely on it for strong anonymity. (Running on %s)",get_version(), - get_uname()); + { + const char *version = get_version(); + log_notice(LD_GENERAL, "Tor v%s running on %s.", version, get_uname()); + + log_notice(LD_GENERAL, "WARNING: Tor can't help you if you use it wrong. " + "Learn how to be safe at " + "https://www.torproject.org/download/download#warning"); + + if (strstr(version, "alpha")) + log_notice(LD_GENERAL, "This is an alpha release; do not rely on it for " + "strong anonymity."); + } + if (network_init()<0) { log_err(LD_BUG,"Error initializing network; exiting.");

1 0

[tor/master] Tweak the "this is not a stable release" warning some more
by nickm＠torproject.org 23 Nov '11

23 Nov '11

commit 2b4d4ffa8f2d893cf5df1480aa2db86e75e8292a Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Nov 23 17:09:36 2011 -0500 Tweak the "this is not a stable release" warning some more --- src/or/main.c | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/or/main.c b/src/or/main.c index 867dd60..f6f47db 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -1894,9 +1894,9 @@ tor_init(int argc, char *argv[]) "Learn how to be safe at " "https://www.torproject.org/download/download#warning"); - if (strstr(version, "alpha")) - log_notice(LD_GENERAL, "This is an alpha release; do not rely on it for " - "strong anonymity."); + if (strstr(version, "alpha") || strstr(version, "beta")) + log_notice(LD_GENERAL, "This version is not a stable Tor release. " + "Expect more bugs than usual."); }

1 0