Merge remote branch 'origin/maint-0.2.2'

  ; 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

         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'.]

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

               "FAILED"   / ; circuit closed (was not built)

               "CLOSED"     ; circuit closed (was built)

      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" /

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

4.1.6. New descriptors available

  Syntax:

     "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