Merge remote-tracking branch 'dgoulet/ticket20803_01'

4 files changed, 240 insertions, 3 deletions

diff --git a/dir-spec.txt b/dir-spec.txt
index 2417dd0..c701842 100644
--- a/dir-spec.txt
+++ b/dir-spec.txt
@@ -731,6 +731,32 @@
        Present if the router accepts "tunneled" directory requests using a
        BEGIN_DIR cell over the router's OR port.
 
+   "proto" SP Entries NL
+
+       [At most one.]
+
+       Entries =
+       Entries = Entry
+       Entries = Entry SP Entries
+
+       Entry = Keyword "=" Values
+
+       Values = Value
+       Values = Value "," Values
+
+       Value = Int
+       Value = Int "-" Int
+
+       Int = NON_ZERO_DIGIT
+       Int = Int DIGIT
+
+       Each 'Entry' in the "proto" line indicates that the Tor relay supports
+       one or more versions of the protocol in question.  Entries should be
+       sorted by keyword.  Values should be numerically ascending within each
+       entry.  (This implies that there should be no overlapping ranges.)
+       Ranges should be represented as compactly as possible. Ints must be no
+       more than 2^32 - 1.
+
 2.1.2. Extra-info document format
 
    Extra-info documents consist of the following items:
@@ -1425,6 +1451,11 @@
         Implementations MUST ignore "id" lines with unrecognized
         key-types in place of "rsa1024" or "ed25519"
 
+     "pr" SP Entries NL
+
+        [At most once.]
+
+        The "proto" element as specified in section 2.1.1.
 
    (Note that with microdescriptors, clients do not learn the RSA identity of
    their routers: they only learn a hash of the RSA identity key.  This is
@@ -1733,6 +1764,27 @@
         Value is the actual shared random value encoded in base64. NumReveals
         is the number of commits used to generate this SRV.
 
+    "recommended-relay-protocols" SP Entries NL
+    "required-relay-protocols" SP Entries NL
+    "recommended-client-protocols" SP Entries NL
+    "required-client-protocols" SP Entries NL
+
+        [At most once for each.]
+
+        The "proto" element as specified in section 2.1.1.
+
+        To vote on these entries, a protocol/version combination is included
+        only if it is listed by a majority of the voters.
+
+        These lines should be voted on.  A majority of votes is sufficient to
+        make a protocol un-supported. and should require a supermajority of
+        authorities (2/3) to make a protocol required.  The required protocols
+        should not be torrc-configurable, but rather should be hardwired in
+        the Tor code.
+
+        The tor-spec.txt section 9 details how a relay and a client should
+        behave when they encounter these lines in the consensus.
+
     "params" SP [Parameters] NL
 
         [At most once]
@@ -2010,6 +2062,19 @@
         descriptors if they would cause "v" lines to be over 128 characters
         long.
 
+    "pr" SP Entries NL
+
+        [At most once.]
+
+        The "proto" family element as specified in section 2.1.1.
+
+        During voting, authorities copy these lines immediately below the "v"
+        lines. When a descriptor does not contain a "proto" entry, the
+        authorities should reconstruct it using the approach described below
+        in section D. They are included in the consensus using the same rules
+        as currently used for "v" lines, if a sufficiently late consensus
+        method is in use.
+
     "w" SP "Bandwidth=" INT [SP "Measured=" INT] [SP "Unmeasured=1"] NL
 
         [At most once.]
@@ -2575,6 +2640,7 @@
      "22" -- Instantiates Ed25519 voting algorithm correctly.
      "23" -- Adds shared randomness protocol data.
      "24" -- No longer lists routers that are not Valid in the consensus.
+     "25" -- Vote on recommended-protocols and required-protocols.
 
    Before generating a consensus, an authority must decide which consensus
    method to use.  To do this, it looks for the highest version number
@@ -3528,3 +3594,19 @@ C. Converting a curve25519 public key to an ed25519 public key
    feed it to the ed25519 public key generation algorithm, and see
    what the sign is.
 
+D. Inferring missing proto lines.
+
+   The directory authorities no longer allow versions of Tor before
+   0.2.4.18-rc.  But right now, there is no version of Tor in the consensus
+   before 0.2.4.19.  Therefore, we should disallow versions of Tor earlier
+   than 0.2.4.19, so that we can have the protocol list for all current Tor
+   versions include:
+
+     Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1-2 Link=1-4
+     LinkAuth=1 Microdesc=1-2 Relay=1-2
+
+   For Desc, Tor versions before 0.2.7.stable should be taken to have Desc=1
+   and versions 0.2.7.stable or later should have Desc=1-2.
+
+   For Microdesc and Cons, Tor versions before 0.2.7.stable should be taken to
+   support version 1; 0.2.7.stable and later should have 1-2.
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index f049d76..6828a64 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -184,7 +184,7 @@ Proposals by number:
 261  AEZ for relay cryptography [OPEN]
 262  Re-keying live circuits with new cryptographic material [OPEN]
 263  Request to change key exchange protocol for handshake v1.2 [OBSOLETE]
-264  Putting version numbers on the Tor subprotocols [FINISHED]
+264  Putting version numbers on the Tor subprotocols [CLOSED]
 265  Load Balancing with Overhead Parameters [ACCEPTED]
 266  Removing current obsolete clients from the Tor network [DRAFT]
 267  Tor Consensus Transparency [DRAFT]
@@ -281,7 +281,6 @@ Proposals by status:
    217  Tor Extended ORPort Authentication [for 0.2.5.x]
    232  Pluggable Transport through SOCKS proxy [in 0.2.6]
    235  Stop assigning (and eventually supporting) the Named flag [in 0.2.6, 0.2.7]
-   264  Putting version numbers on the Tor subprotocols [in 0.2.9.4-alpha]
    272  Listed routers should be Valid, Running, and treated as such [in 0.2.9.3-alpha, 0.2.9.4-alpha]
  CLOSED:
    101  Voting on the Tor Directory System [in 0.2.0.x]
@@ -344,6 +343,7 @@ Proposals by status:
    238  Better hidden service stats from Tor relays
    243  Give out HSDir flag only to relays with Stable flag
    250  Random Number Generation  During Tor Voting
+   264  Putting version numbers on the Tor subprotocols [in 0.2.9.4-alpha]
  SUPERSEDED:
    112  Bring Back Pathlen Coin Weight
    113  Simplifying directory authority administration
diff --git a/proposals/264-subprotocol-versions.txt b/proposals/264-subprotocol-versions.txt
index f183acc..75a1c8f 100644
--- a/proposals/264-subprotocol-versions.txt
+++ b/proposals/264-subprotocol-versions.txt
@@ -2,7 +2,7 @@ Filename: 264-subprotocol-versions.txt
 Title: Putting version numbers on the Tor subprotocols
 Author: Nick Mathewson
 Created: 6 Jan 2016
-Status: Finished
+Status: Closed
 Implemented-In: 0.2.9.4-alpha
 
 
diff --git a/tor-spec.txt b/tor-spec.txt
index ba9782f..e7be756 100644
--- a/tor-spec.txt
+++ b/tor-spec.txt
@@ -1610,3 +1610,158 @@ see tor-design.pdf.
             cells in both directions on that circuit.  Count the amount of
             memory we recovered towards the total.
 
+9. Subprotocol versioning
+
+   This section specifies the Tor subprotocol versioning. They are broken down
+   into different types with their current version numbers. Any new version
+   number should be added to this section.
+
+   The dir-spec.txt details how those versions are encoded. See the
+   "proto"/"pr" line in a descriptor and the "recommended-relay-protocols",
+   "required-relay-protocols", "recommended-client-protocols" and
+   "required-client-protocols" lines in the vote/consensus format.
+
+   Here are the rules a relay and client should follow when encountering a
+   protocol list in the consensus:
+
+      - When a relay lacks a protocol listed in recommended-relay-protocols,
+        it should warn its operator that the relay is obsolete.
+
+      - When a relay lacks a protocol listed in required-relay-protocols, it
+        must not attempt to join the network.
+
+      - When a client lacks a protocol listed in recommended-client-protocols,
+        it should warn the user that the client is obsolete.
+
+      - When a client lacks a protocol listed in required-client-protocols, it
+        must not connect to the network.  This implements a "safe forward
+        shutdown" mechanism for zombie clients.
+
+      - If a client or relay has a cached consensus telling it that a given
+        protocol is required, and it does not implement that protocol, it
+        SHOULD NOT try to fetch a newer consensus.
+
+   Starting in version 0.2.9.4-alpha, the initial required protocols for
+   clients that we will Recommend and Require are:
+
+      Cons=1-2 Desc=1-2 DirCache=1 HSDir=2 HSIntro=3 HSRend=1 Link=4
+      LinkAuth=1 Microdesc=1-2 Relay=2
+
+   For relays we will Require:
+
+      Cons=1 Desc=1 DirCache=1 HSDir=2 HSIntro=3 HSRend=1 Link=3-4
+      LinkAuth=1 Microdesc=1 Relay=1-2
+
+   For relays, we will additionally Recommend all protocols which we
+   recommend for clients.
+
+9.1. "Link"
+
+   The "link" protocols are those used by clients and relays to initiate and
+   receive OR connections and to handle cells on OR connections. The "link"
+   protocol versions correspond 1:1 to those versions.
+
+   Two Tor instances can make a connection to each other only if they have at
+   least one link protocol in common.
+
+   The current "link" versions are: "1" through "4". See section 4.1 for more
+   information. All current Tor versions support "1-3"; version from
+   0.2.4.11-alpha and on support "1-4". Eventually we will drop "1" and "2".
+
+9.2. "LinkAuth"
+
+   LinkAuth protocols correspond to varieties of Authenticate cells used for
+   the v3+ link protocools.
+
+   The current version is "1".
+
+   "2" is unused, and reserved by proposal 244.
+
+   "3" is the ed25519 link handshake of proposal 220.
+
+9.3. "Relay"
+
+   The "relay" protocols are those used to handle CREATE cells, and those that
+   handle the various RELAY cell types received after a CREATE cell.  (Except,
+   relay cells used to manage introduction and rendezvous points are managed
+   with the "HSIntro" and "HSRend" protocols respectively.)
+
+   Current versions are:
+
+   "1" -- supports the TAP key exchange, with all features in Tor 0.2.3.
+          Support for CREATE and CREATED and CREATE_FAST and CREATED_FAST
+          and EXTEND and EXTENDED.
+
+   "2" -- supports the ntor key exchange, and all features in Tor
+          0.2.4.19.  Includes support for CREATE2 and CREATED2 and
+          EXTEND2 and EXTENDED2.
+
+9.4. "HSIntro"
+
+   The "HSIntro" protocol handles introduction points.
+
+   "3" -- supports authentication as of proposal 121 in Tor
+          0.2.1.6-alpha.
+
+9.5. "HSRend"
+
+   The "HSRend" protocol handles rendezvous points.
+
+   "1" -- supports all features in Tor 0.0.6.
+
+   "2" -- supports RENDEZVOUS2 cells of arbitrary length as long as they
+          have 20 bytes of cookie in Tor 0.2.9.1-alpha.
+
+9.6. "HSDir"
+
+   The "HSDir" protocols are the set of hidden service document types that can
+   be uploaded to, understood by, and downloaded from a tor relay, and the set
+   of URLs available to fetch them.
+
+   "1" -- supports all features in Tor 0.2.0.10-alpha.
+
+9.7. "DirCache"
+
+   The "DirCache" protocols are the set of documents available for download
+   from a directory cache via BEGIN_DIR, and the set of URLs available to
+   fetch them.  (This excludes URLs for hidden service objects.)
+
+   "1" -- supports all features in Tor 0.2.4.19.
+
+9.8. "Desc"
+
+   Describes features present or absent in descriptors.
+
+   Most features in descriptors don't require a "Desc" update -- only those
+   that need to someday be required.  For example, someday clients will need
+   to understand ed25519 identities.
+
+   "1" -- supports all features in Tor 0.2.4.19.
+
+   "2" -- cross-signing with onion-keys, signing with ed25519
+   identities.
+
+9.9. "Microdesc"
+
+   Describes features present or absent in microdescriptors.
+
+   Most features in descriptors don't require a "MicroDesc" update -- only
+   those that need to someday be required.  These correspond more or less with
+   consensus methods.
+
+   "1" -- consensus methods 9 through 20.
+
+   "2" -- consensus method 21 (adds ed25519 keys to microdescs).
+
+9.10. "Cons"
+
+   Describes features present or absent in consensus documents.
+
+   Most features in consensus documents don't require a "Cons" update -- only
+   those that need to someday be required.
+
+   These correspond more or less with consensus methods.
+
+   "1" -- consensus methods 9 through 20.
+
+   "2" -- consensus method 21 (adds ed25519 keys to microdescs).