commit eb4fb3c5851aa77d3fca4ca899e656180e48f5ed Author: David Goulet dgoulet@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@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).