[tor-commits] [torspec/master] Merge proposal 264 to dir-spec and tor-spec
nickm at torproject.org
nickm at torproject.org
Fri Dec 2 17:12:08 UTC 2016
commit eb4fb3c5851aa77d3fca4ca899e656180e48f5ed
Author: David Goulet <dgoulet at torproject.org>
Date: Tue Nov 29 11:03:41 2016 -0500
Merge proposal 264 to dir-spec and tor-spec
Signed-off-by: David Goulet <dgoulet at torproject.org>
---
dir-spec.txt | 82 +++++++++++++++++++++++++++++++
tor-spec.txt | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 237 insertions(+)
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/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).
More information about the tor-commits
mailing list