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.
