Merge proposal 264 to dir-spec and tor-spec

Signed-off-by: David Goulet <dgoulet@torproject.org>

1 files changed, 155 insertions, 0 deletions

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).