From cff180f8b0e2066e566ba63ef4197e1463aa1fb1 Mon Sep 17 00:00:00 2001 From: "Poet (Tim Sally)" Date: Wed, 1 Dec 2010 05:21:34 -0600 Subject: Clarify description of FEATURES in control-spec. (1) On by default is a bad way to describe features. Rather, they are always on and should be viewed as a part of the control protocol. Updated the wording in USEFEATURE to reflect this. (2) Made descriptions of Tor versions consistant across all features. There is the version in which a feature was introduced and the version in which it became part of the protocol. (3) Reworded the description of the VERBOSE_NAMES feature. The previous wording describes the way things used to be first. Better to lead with the current state of things and then describe how it differs from old versions. --- doc/spec/control-spec.txt | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) (limited to 'doc') diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 1864666047..3bc1c54eff 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -770,46 +770,47 @@ 3.19. USEFEATURE + Adding additional features to the control protocol sometimes will break + backwards compatibility. Initially such features are added into Tor and + disabled by default. USEFEATURE can enable these additional features. + The syntax is: "USEFEATURE" *(SP FeatureName) CRLF FeatureName = 1*(ALPHA / DIGIT / "_" / "-") - Sometimes extensions to the controller protocol break compatibility with - older controllers. In this case, whenever possible, the extensions are - first included in Tor disabled by default, and only enabled on a given - controller connection when the "USEFEATURE" command is given. Once a - "USEFEATURE" command is given, it applies to all subsequent interactions on - the same connection; to disable an enabled feature, a new controller - connection must be opened. + Feature names are case-insensitive. - This is a forward-compatibility mechanism; each feature will eventually - become a regular part of the control protocol in some future version of Tor. - Tor will ignore a request to use any feature that is already on by default. - Tor will give a "552" error if any requested feature is not recognized. + Once enabled, a feature stays enabled for the duration of the connection + to the controller. A new connection to the controller must be opened to + disable an enabled feature. - Feature names are case-insensitive. + Features are a forward-compatibility mechanism; each feature will eventually + become a standard part of the control protocol. Once a feature becomes part + of the protocol, it is always-on. Each feature documents the version it was + introduced as a feature and the version in which it became part of the + protocol. + + Tor will ignore a request to use any feature that is always-on. Tor will give + a 552 error in response to an unrecognized feature. EXTENDED_EVENTS Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to request the extended event syntax. - This feature was first used in 0.1.2.3-alpha. It is always-on in - Tor 0.2.2.1-alpha and later. + This feature was first introduced in 0.1.2.3-alpha. It is always-on + and part of the protocol in Tor 0.2.2.1-alpha and later. VERBOSE_NAMES - Instead of ServerID as specified above, the controller should - identify ORs by LongName in events and GETINFO results. This format is - strictly more informative: rather than including Nickname for - known Named routers and Fingerprint for unknown or unNamed routers, the - LongName format includes a Fingerprint, an indication of Named status, - and a Nickname (if one is known). + Replaces ServerID with LongName in events and GETINFO results. LongName + provides a Fingerprint for all routers, an indication of Named status, + and a Nickname if one is known. LongName is strictly more informative + than ServerID, which only provides either a Fingerprint or a Nickname. - This will not be always-enabled until at least two stable - releases after 0.1.2.2-alpha, the release where it was first - available. It is always-on in Tor 0.2.2.1-alpha and later. + This feature was first introduced in 0.1.2.2-alpha. It is always-on and + part of the protocol in Tor 0.2.2.1-alpha and later. 3.20. RESOLVE -- cgit v1.2.3-54-g00ecf From 608bad6e3246d1bfbcb4e3009237f72d3292b747 Mon Sep 17 00:00:00 2001 From: "Poet (Tim Sally)" Date: Wed, 1 Dec 2010 05:24:33 -0600 Subject: Several changes to the way tokens describing servers are documented. (1) Made the wording of the comments consistant with token names. Digest/Fingerprint and Name/Nickname were being used interchangeably. Better to just use Fingerprint and Nickname becuase they are the names of the tokens. (2) Places the tokens currently in use before the tokens used in older versions. ServerSpec should be documented before ServerID. (3) Added a note to the comments about ServerID that cross reference the VERBOSE_FEATURE, allowing users to see when and why ServerID was replaced with LongName. --- doc/spec/control-spec.txt | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 3bc1c54eff..1b9a692d7b 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -96,32 +96,35 @@ ; followed by the ASCII Linefeed character (decimal value 10)." CRLF = CR LF - ; Identifiers for servers. - ServerID = Nickname / Fingerprint - - Nickname = 1*19 NicknameChar - NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9" - Fingerprint = "$" 40*HEXDIG - - ; A "=" indicates that the given nickname is canonical; a "~" indicates - ; that the given nickname is not canonical. If no nickname is given at - ; all, Tor does not even have a guess for what this router calls itself. - LongName = Fingerprint [ ( "=" / "~" ) Nickname ] - ; How a controller tells Tor about a particular OR. There are four ; possible formats: - ; $Digest -- The router whose identity key hashes to the given digest. + ; $Fingerprint -- The router whose identity key hashes to the fingerprint. ; This is the preferred way to refer to an OR. - ; $Digest~Name -- The router whose identity key hashes to the given - ; digest, but only if the router has the given nickname. - ; $Digest=Name -- The router whose identity key hashes to the given - ; digest, but only if the router is Named and has the given + ; $Fingerprint~Nickname -- The router whose identity key hashes to the + ; given fingerprint, but only if the router has the given nickname. + ; $Fingerprint=Nickname -- The router whose identity key hashes to the + ; given fingerprint, but only if the router is Named and has the given ; nickname. - ; Name -- The Named router with the given nickname, or, if no such + ; Nickname -- The Named router with the given nickname, or, if no such ; router exists, any router whose nickname matches the one given. ; This is not a safe way to refer to routers, since Named status ; could under some circumstances change over time. + ; + ; The tokens that implement the above follow: + ServerSpec = LongName / Nickname + LongName = Fingerprint [ ( "=" / "~" ) Nickname ] + + Fingerprint = "$" 40*HEXDIG + NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9" + Nickname = 1*19 NicknameChar + + ; What follows is an outdated way to refer to ORs. + ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and + ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version + ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later. + ServerID = Nickname / Fingerprint + ; Unique identifiers for streams or circuits. Currently, Tor only ; uses digits, but this may change -- cgit v1.2.3-54-g00ecf From 87158368dc02350d7eda43cbadc00a3cfc4d8815 Mon Sep 17 00:00:00 2001 From: "Poet (Tim Sally)" Date: Wed, 1 Dec 2010 05:25:17 -0600 Subject: Correct grammars to reflect that VERBOSE_NAMES is part of the protocol. Several updates to grammars for events and GETINFO results. All relate to the fact that LongName has replaced ServerID since 0.2.2.1-alpha. See documentation of VERBOSE_NAMES for more information. The following grammars were changed: * orconn-status GETINFO result * entry-guards GETINFO result * Path general token * OR Connection status changed event * New descriptors available event In all cases a note was added about when the old grammar applies. --- doc/spec/control-spec.txt | 48 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 1b9a692d7b..14b5903f59 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -480,21 +480,28 @@ StreamID SP StreamStatus SP CircID SP Target CRLF "orconn-status" - A series of lines as for an OR connection status event. Each is of the - form: + A series of lines as for an OR connection status event. In Tor + 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP ORStatus CRLF + + Before 0.1.2.2-alpha, each line is of the form: ServerID SP ORStatus CRLF "entry-guards" A series of lines listing the currently chosen entry guards, if any. - Each is of the form: - ServerID2 SP Status [SP ISOTime] CRLF - - Status-with-time = ("unlisted") SP ISOTime - Status = ("up" / "never-connected" / "down" / - "unusable" / "unlisted" ) + In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP Status [SP ISOTime] CRLF + Before 0.1.2.2-alpha, each line is of the form: + ServerID2 SP Status [SP ISOTime] CRLF ServerID2 = Nickname / 40*HEXDIG + The definition of Status is the same for both: + Status = "up" / "never-connected" / "down" / + "unusable" / "unlisted" + [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes". Tor still supports calling it that for now, but support will be removed in 0.1.3.x.] @@ -1004,7 +1011,11 @@ "FAILED" / ; circuit closed (was not built) "CLOSED" ; circuit closed (was built) - Path = ServerID *("," ServerID) + Path = LongName *("," LongName) + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path + ; is as follows: + Path = ServerID *("," ServerID) Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" / "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" / @@ -1093,19 +1104,26 @@ 4.1.3. OR Connection status changed The syntax is: - "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + + "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON=" Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED" + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR + ; Connection is as follows: + "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF + NEW is for incoming connections, and LAUNCHED is for outgoing connections. CONNECTED means the TLS handshake has finished (in either direction). FAILED means a connection is being closed that hasn't finished its handshake, and CLOSED is for connections that have handshaked. - A ServerID is specified unless it's a NEW connection, in which - case we don't know what server it is yet, so we use Address:Port. + A LongName or ServerID is specified unless it's a NEW connection, in + which case we don't know what server it is yet, so we use Address:Port. If extended events are enabled (see 3.19), optional reason and circuit counting information is provided for CLOSED and FAILED @@ -1142,7 +1160,11 @@ 4.1.6. New descriptors available Syntax: - "650" SP "NEWDESC" 1*(SP ServerID) CRLF + "650" SP "NEWDESC" 1*(SP LongName) CRLF + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it + ; is as follows: + "650" SP "NEWDESC" 1*(SP ServerID) CRLF 4.1.7. New Address mapping -- cgit v1.2.3-54-g00ecf From 45c302efe0156636fbe1ce9e14c724e47949fa71 Mon Sep 17 00:00:00 2001 From: "Poet (Tim Sally)" Date: Wed, 1 Dec 2010 05:26:05 -0600 Subject: Correct information about support for guards being called helper nodes. The spec stated that support for the helper-nodes command would be removed in 0.1.3.x, however support for this command is still in Tor. Updated the spec to reflect this and added a node that the command is deprecated. --- doc/spec/control-spec.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 14b5903f59..66ad11c53c 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -502,10 +502,10 @@ Status = "up" / "never-connected" / "down" / "unusable" / "unlisted" - [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes". - Tor still supports calling it that for now, but support will be - removed in 0.1.3.x.] - + [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called + "helper-nodes". Tor still supports calling "helper-nodes", but it + is deprecated and should not be used.] + [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead of unlisted/unusable. Current Tors never generate 'down'.] -- cgit v1.2.3-54-g00ecf From 31b69027d39d0dc77dd1d8fd0895928768894654 Mon Sep 17 00:00:00 2001 From: "Poet (Tim Sally)" Date: Wed, 1 Dec 2010 11:19:26 -0600 Subject: Specified grammars for orconn-status and entry-guards for Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature VERBOSE_NAMES turned off. --- doc/spec/control-spec.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 66ad11c53c..255adf00a4 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -485,7 +485,9 @@ 0.2.2.1-alpha and later by default, each line is of the form: LongName SP ORStatus CRLF - Before 0.1.2.2-alpha, each line is of the form: + In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line + is of the form: ServerID SP ORStatus CRLF "entry-guards" @@ -494,7 +496,9 @@ 0.2.2.1-alpha and later by default, each line is of the form: LongName SP Status [SP ISOTime] CRLF - Before 0.1.2.2-alpha, each line is of the form: + In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line + is of the form: ServerID2 SP Status [SP ISOTime] CRLF ServerID2 = Nickname / 40*HEXDIG -- cgit v1.2.3-54-g00ecf