Merge remote branch 'origin/maint-0.2.2'

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
@@ -477,25 +480,36 @@
          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
+
+     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"
       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
 
+     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
 
-      [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.]
+      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, 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'.]
 
@@ -770,46 +784,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
 
@@ -1000,7 +1015,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" /
@@ -1089,19 +1108,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
@@ -1138,7 +1164,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