commit 10771f66534d7db55001bcd43fde8fc7b9d033ca Author: Nick Mathewson nickm@torproject.org Date: Wed Jan 6 15:13:41 2016 -0800

264: Putting version numbers on the Tor subprotocols --- proposals/000-index.txt | 2 + proposals/264-subprotocol-versions.txt | 510 ++++++++++++++++++++++++++++++++ 2 files changed, 512 insertions(+)

diff --git a/proposals/000-index.txt b/proposals/000-index.txt index 8da27da..7979244 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -184,6 +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 [OPEN] +264 Putting version numbers on the Tor subprotocols [OPEN]

Proposals by status: @@ -240,6 +241,7 @@ Proposals by status: 261 AEZ for relay cryptography 262 Re-keying live circuits with new cryptographic material 263 Request to change key exchange protocol for handshake + 264 Putting version numbers on the Tor subprotocols ACCEPTED: 140 Provide diffs between consensuses 172 GETINFO controller option for circuit information diff --git a/proposals/264-subprotocol-versions.txt b/proposals/264-subprotocol-versions.txt new file mode 100644 index 0000000..d0626f0 --- /dev/null +++ b/proposals/264-subprotocol-versions.txt @@ -0,0 +1,510 @@ +Filename: 264-subprotocol-versions.txt +Title: Putting version numbers on the Tor subprotocols +Author: Nick Mathewson +Created: 6 Jan 2016 +Status: Open + + +1. Introduction + + At various points in Tor's history, we've needed to migrate from one + protocol to another. In the past, we've mostly done this by allowing + relays to advertise support for various features. We've done this in + an ad-hoc way, though. In some cases, we've done it entirely based on + the relays' advertised Tor version. + + That's a pattern we shouldn't continue. We'd like to support more + live Tor relay implementations, and that means that tying "features" + to "tor version" won't work going forwards. + + This proposal describes and alternative method that we can use to + simplify the advertisement and discovery of features, and the + transition from one set of features to another. + +1.1. History: "Protocols" vs version-based gating. + + For ages, we've specified a "protocols" line in relay descriptors, + with a list of supported versions for "relay" and "link" protocols. + But we've never actually looked at it, and instead we've relied on + tor version numbers to determine which features we could rely upon. + We haven't kept the relay and link protocols listed there up-to-date + either. + + Clients have used version checks for three purposes historically: + checking relays for bugs, checking relays for features, and + implementing bug-workarounds on their own state files. + + In this design, feature checks are now performed directly with + subprotocol versions. We only need to keep using Tor versions + specifically for bug workarounds. + +2. Design: Advertising protocols. + + We revive the "Protocols" design above, in a new form. + + "proto" Entries NL + + 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 + must be sorted by keyword. Values must be numerically ascending + within each entry. (This implies that there are no overlapping + ranges.) Ranges must be represented as compactly as possible. Ints + must be no more than 2^32 - 1. + + The semantics for each keyword must be defined in a Tor + specification. Extension keywords are allowed if they begin with + "x-" or "X-". Keywords are case-sensitive. + + 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 A.1. 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. + +2.1. An alternative: Moving 'v' lines into microdescriptors. + + [[[[[ + Here's an alternative: we could put "v" and "proto" lines into + microdescriptors. + + When building microdescriptors, authorities could copy all valid + "proto" entries verbatim if a sufficiently late consensus method is + in use. When a descriptor does not contain a "proto" entry, the + authorities should reconstruct it using the approach described below + in section A.1. + + Tor clients that want to use "v" lines should prefer those in + microdescriptors if present, and ignore those in the consensus. + + (Existing maintined client versions can be adapted to never look at + "v" lines at all; the only versions that they still check for are + ones not allowed on the network. The "v" line can be dropped + from the consensus entirely when current clients have upgraded.) + ]]]]] + + [I am rejecting this alternative for now, since proto lines should + compress very well, given that the proto line is completely + inferrable from the v line. Removing all the v lines from the + current consensus would save only 1.7% after gzip compression.] + +3. Using "protos" and "v" lines + + Whenever possible, clients and relays should use the list of + advertised protocols instead of version numbers. Version numbers + should only be used when implementing bug-workarounds for specific + Tor versions. + + Every new feature in tor-spec.txt, dir-spec.txt, and rend-spec.txt + should be gated on a particular protocol version. + +4. Required protocols + + The consensus may contain three lines: RequiredRelayProtocols, + RecommendedClientProtocols, and RequiredClientProtocols. Each has + the same format as the "protos" line. To vote on these entries, a + protocol/version combination is included only if it is listed by a + majority of the voters. + + When a relay lacks a protocol listed in RequiredRelayProtocols, it + must not attempt to join the network. + + When a client lacks a protocol listed in RecommendedClientProtocols, + it should warn the user that the client is obsolete. + + When a client lacks a protocol listed in RequiredClientProtocols, it + must not use the corresponding feature. If the corresponding feature + is required to operate a Tor client, the client must must log an + error message and shut down without connecting to the network, even + if the cached consensus is out-of-date. This implements a "safe + forward shutdown" mechanism for zombie clients. + + The above features should be backported to 0.2.4 and later. + +5. Current protocols + + (See "6. Maintaining the protocol list" below for information about + how I got these, and why version 0.2.4.19 comes up so often.) + +5.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 tor-spec.txt + 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". + +5.2. "LinkAuth" + + LinkAuth protocols correspond to varieties of Authenticate cells used + for the v3+ link protocools. + + The currrent version is "1". + +5.3. "Relay" + + The "relay" protocols are those used to handle CREATE cells, and + those that 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 "HSMid" protocols.) + + "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. + +5.3. "HSMid" + + The "HSMid" protocols are those that handle introduction points and + rendezvous points. + + "1" -- supports all features in Tor 0.2.4.19 + +5.4. "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. + +5.5. "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.4.19. + +5.6. "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. + +5.7. "Microdesc" + + Describes features present or absent in microdescriptors. + + Most features in descriptors don't require a "MircoDesc" 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). + +5.8. "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). + + +6. Maintaining the protocol lists + + What makes a good fit for a "protocol" type? Generally, it's a set + of communications functionality that tends to upgrade in tandem, and + in isolation from other parts of the Tor protocols. It tends to be + functionality where it doesn't make sense to implement only part of + it -- though omitting the whole thing might make sense. + + (Looking through our suite of protocols, you might make a case for + splitting DirCache into sub-protocols.) + + We shouldn't add protocols for features where others can remain + oblivious to their presence or absence. For example, if some + directory caches start supporting a new header, and clients can + safely send that header without knowing whether the directory cache + will understand it, then a new protocol version is not required. + + Because all relays currently on the network are 0.2.4.19 or later, we + can require 0.2.4.19, and use 0.2.4.19 as the minimal version so we + we don't need to do code archeology to determine which number + + Adding new protocol types is pretty cheap, given compression. + +A.1. Inferring missing protos lines. + + The directory authorities no longer allow versions of Tor before + 0.2.4.8-alpha. 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: + + DirCache=1 HSDir=1 HSMid=1 Link=1-4 LinkAuth=1 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. + +A.2. Initial required protocols + + For clients we will Recommend and Require: + + DirCache=1 HSDir=1 Desc=1 Cons=ANYOF(9-20) Microdesc=ANYOF(9-20) + HSMid=1 Link=4 LinkAuth=1 Relay=2 + + For relays we will Require: + + DirCache=1 HSDir=1 Desc=1 Cons=ANYOF(9-20) Microdesc=ANYOF(9-20) + HSMid=1 Link=3-4 LinkAuth=1 Relay=1-2 + +A.3. Example integration with other open proposals + + In this appendix, I try to show that this proposal is viable by + showing how it can integrate with other open proposals to avoid + version-gating. I'm looking at open/draft/accepted proposals only. + + 140 Provide diffs between consensuses + + This proposal doesn't affect interoperability, though we could + add a DirCache protocol version for it if we think we might + want to require it someday. + + 164 Reporting the status of server votes + + Interoperability not affected; no new protocol. + + 165 Easy migration for voting authority sets + + Authority-only; no new protocol. + + 168 Reduce default circuit window + + Interoperability slightly affected; could be a new Relay + protocol. + + 172 GETINFO controller option for circuit information + 173 GETINFO Option Expansion + + Client/Relay interop not affected; no new protocol. + + 177 Abstaining from votes on individual flags + + Authority-only; no new protocol. + + 182 Credit Bucket + + No new protocol. + + 188 Bridge Guards and other anti-enumeration defenses + + No new protocol. + + 189 AUTHORIZE and AUTHORIZED cells + + This would be a new protocol, either a Link protocol or a new + LinkAuthz protocol. + + 191 Bridge Detection Resistance against MITM-capable Adversaries + + No new protocol. + + 192 Automatically retrieve and store information about bridges + + No new protocol. + + 195 TLS certificate normalization for Tor 0.2.4.x + + Interop not affected; no new protocol. + + 201 Make bridges report statistics on daily v3 network status + requests + + No new protocol. + + 202 Two improved relay encryption protocols for Tor cells + + This would be a new Relay protocol. + + 203 Avoiding censorship by impersonating an HTTPS server + + Bridge/PT only; no new protocol. + + 209 Tuning the Parameters for the Path Bias Defense + + Client behavior only; no new protocol. + + 210 Faster Headless Consensus Bootstrapping + + Client behavior only; no new protocol. + + 212 Increase Acceptable Consensus Age + + Possibly add a new DirCache protocol version to describe the + "will hold older descriptors" property. + + 219 Support for full DNS and DNSSEC resolution in Tor + + New relay protocol, or new protocol class (DNS=2?) + + 220 Migrate server identity keys to Ed25519 + + Once link authentication is supported, that's a new LinkAuth + protocol version. + + No new protocol version is required for circuit extension, + since it's a backward-compatible change. + + 224 Next-Generation Hidden Services in Tor + + Adds new HSDir and HSMid protocols. + + 226 "Scalability and Stability Improvements to BridgeDB: Switching + to a Distributed Database System and RDBMS" + + No new protocol. + + 229 Further SOCKS5 extensions + + Client-only; no new protocol. + + 233 Making Tor2Web mode faster + + No new protocol. + + 234 Adding remittance field to directory specification + + Could be a new protocol; or not. + + 237 All relays are directory servers + + No new protocol. + + 239 Consensus Hash Chaining + + No new protocol. + + 242 Better performance and usability for the MyFamily option + + New Desc protocol. + + 244 Use RFC5705 Key Exporting in our AUTHENTICATE calls + + Part of prop220. Also adds another LinkAuth protocol version. + + 245 Deprecating and removing the TAP circuit extension protocol + + Removes Linkauth protocol 1. + + Removes a Desc protocol. + + 246 Merging Hidden Service Directories and Introduction Points + + Possibly adds a new HSMid protocol. + + 247 Defending Against Guard Discovery Attacks using Vanguards + + No new protocol. + + 248 Remove all RSA identity keys + + Adds a new Desc protocol version and a new Cons protocol + version; eventually removes a version of each. + + 249 Allow CREATE cells with >505 bytes of handshake data + + Adds a new Link protocol version for CREATE2V. + + Adds a new Relay protocol version for new EXTEND2 semantics. + + 250 Random Number Generation During Tor Voting + + No new protocol. + + 251 Padding for netflow record resolution reduction + + No new protocol. + + 252 Single Onion Services + + No new protocol. + + 253 Out of Band Circuit HMACs + + New Relay protocol. + + 254 Padding Negotiation + + New Link protocol, new Relay protocol. + + 255 Controller features to allow for load-balancing hidden services + + No new protocol. + + 256 Key revocation for relays and authorities + + New Desc protocol. + + 257 Refactoring authorities and taking parts offline + + No new protocol. + + 258 Denial-of-service resistance for directory authorities + + No new protocol. + + 259 New Guard Selection Behaviour + + No new protocol + + 260 Rendezvous Single Onion Services + + No new protocol + + 261 AEZ for relay cryptography + + New Relay protocol version. + + 262 Re-keying live circuits with new cryptographic material + + New Relay protocol version + + 263 Request to change key exchange protocol for handshake + + New Relay protocol version. +