Subprotocol-based versioning

Tor implementations use “subprotocols” to describe and negotiate which versions and features of the Tor protocol they support.

These subprotocols are grouped by the area of the protocol to which they apply, and denoted by individual numbers.

For example, “Relay=3” is a subprotocol, as is “Link=5”.

Each subprotocol also has a symbolic name for use by programmers. These names are for human convenience only, and not used within the Tor protocols.

For example, “Relay=3” is also known as RELAY_EXTEND_IPV6.

Relays advertise their supported subprotocols in the “proto” field in their descriptors. Authorities re-publish this information in the “pr” field of the relay’s microdescriptor.

Recognized protocols are as follows. When we need to indicate a protocol numerically in our protocol, we use the numeric Ids in this table.

Interpreting subprotocols

Each subprotocol should be interpreted as a single flag, independent of all others.

That is to say, from the fact that an instance supports “Relay=5”, it is incorrect to conclude that the relay supports “Relay=4”, even though 5 is greater than 4.

Earlier versions of this document, and some other places in our spec and code, refer to “subprotocol versions”. We are avoiding this vocabulary in the future, to avoid this misunderstanding.

Required and recommended subprotocols

The consensus document contains lists of subprotocols that are recommend or required for relays and clients.

They are:

• “recommended-client-protocols”
• “recommended-relay-protocols”
• “required-relay-protocols”
• “required-client-protocols”

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 should warn its operator as above. If the consensus is newer than the date when the software was released or scheduled for release, 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 should warn the user as above. If the consensus is newer than the date when the software was released, 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.

Software release dates SHOULD be automatically updated as part of the release process, to prevent forgetting to move them forward. Software release dates MAY be manually adjusted by maintainers if necessary.

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=1 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=1 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.

“Link”

The “link” protocols are those used by clients and relays to initiate and receive relay connections and to handle cells on relay connections. The “link” subprotocols 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 “5”. See Negotiating versions with VERSIONS cells for more information.

“LinkAuth”

LinkAuth protocols correspond to varieties of AUTHENTICATE cells used for the v3+ link protocols.

Current subprotocols are:

• “1” (LINKAUTH_RSA_SHA256_TLSSECRET) – the RSA link authentication described in Link authentication type 1: RSA-SHA256-TLSSecret.

• “2” is unused, and reserved by proposal 244.

• “3” (LINKAUTH_ED25519_SHA256_EXPORTER) – the ed25519 link authentication described in Link authentication type 3: Ed25519-SHA256-RFC5705.

“Relay”

The “relay” protocols are those used to handle CREATE/CREATE2 cells, and those that handle the various relay messages received after a CREATE/CREATE2 cell. (Except, relay cells used to manage introduction and rendezvous points are managed with the “HSIntro” and “HSRend” protocols respectively.)

Current subprotocols are as follows.

• “1” (RELAY_BASE) – supports the TAP key exchange, with all features in Tor 0.2.3. Support for CREATE and CREATED.

• “2” (RELAY_NTOR) – supports the ntor key exchange, and all features in Tor 0.2.4.19. Includes support for CREATE2 and CREATED2 and EXTEND2 and EXTENDED2.

  Relay=2 has limited IPv6 support:

  • Clients might not include IPv6 ORPorts in EXTEND2 messages.
  • Relays (and bridges) might not initiate IPv6 connections in response to EXTEND2 messages containing IPv6 ORPorts, even if they are configured with an IPv6 ORPort.

  However, relays support accepting inbound connections to their IPv6 ORPorts. And they might extend circuits via authenticated IPv6 connections to other relays.

• “3” (RELAY_EXTEND_IPv6) – relays support extending over IPv6 connections in response to an EXTEND2 message containing an IPv6 ORPort.

  Bridges might not extend over IPv6, because they try to imitate client behaviour.

  A successful IPv6 extend requires:

  • Relay=3 subprotocol (or later) on the extending relay,
  • an IPv6 ORPort on the extending relay,
  • an IPv6 ORPort for the accepting relay in the EXTEND2 message, and
  • an IPv6 ORPort on the accepting relay. (Because different tor instances can have different views of the network, these checks should be done when the path is selected. Extending relays should only check local IPv6 information, before attempting the extend.)

  When relays receive an EXTEND2 message containing both an IPv4 and an IPv6 ORPort, and there is no existing authenticated connection with the target relay, the extending relay may choose between IPv4 and IPv6 at random. The extending relay might not try the other address, if the first connection fails.

  As is the case with other subprotocols, tor advertises, recommends, or requires support for this subprotocol, regardless of its current configuration.

  In particular:

  • relays without an IPv6 ORPort, and
  • tor instances that are not relays, have the following behaviour, regardless of their configuration:
  • advertise support for “Relay=3” in their descriptor (if they are a relay, bridge, or directory authority), and
  • react to consensuses recommending or requiring support for “Relay=3”.

  This subprotocol is described in proposal 311, and implemented in Tor 0.4.5.1-alpha.

• “4” (RELAY_NTORV3) – support the ntorv3 (version 3) key exchange and all features in 0.4.7.3-alpha. This adds a new CREATE2 cell type. See proposal 332 and The “ntor-v3” handshake for more details.

• “5” (RELAY_NEGOTIATE_SUBPROTO) [RESERVED] – support the ntorv3 subprotocol request extension (proposal 346) allowing a client to request what features to be used on a circuit.

“HSIntro”

The “HSIntro” protocol handles introduction points.

• “3” (HSINTRO_V2) – supports the RSA-based introduction point protocol of proposal 121 in Tor 0.2.1.6-alpha.

• “4” (HSINTRO_V3) – support ed25519-based HS v3 introduction point protocol as defined by proposal 224 in Tor 0.3.0.4-alpha.

• “5” (HSINTRO_RATELIM) – support ESTABLISH_INTRO message DoS parameters extension for onion service version 3 only in Tor 0.4.2.1-alpha.

“HSRend”

The “HSRend” protocol handles rendezvous points.

• “1” (HSREND_V2) – supports all features in Tor 0.0.6.

• “2” (HSREND_V3) – supports RENDEZVOUS2 messages of arbitrary length as long as they have 20 bytes of cookie in Tor 0.2.9.1-alpha.

“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” (HSDIR_V2) – supports all features in Tor 0.2.0.10-alpha.

• “2” (HSDIR_V3) – support ed25519 blinded keys request which is defined by the HS v3 protocol as part of proposal 224 in Tor 0.3.0.4-alpha.

“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” (DIRCACHE_BASE) – supports all features in Tor 0.2.4.19.

• “2” (DIRCACHE_CONSDIFF) – adds support for consensus diffs in Tor 0.3.1.1-alpha.

“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” (DESC_BASE) – supports all features in Tor 0.2.4.19.

• “2” (DESC_CROSSSIGN) – cross-signing with onion-keys, signing with ed25519 identities.

• “3” (DESC_NO_TAP) – parsing relay descriptors without onion-keys; generating them when the publish-dummy-tap-key option is 0.

• “4” – Support for understanding family certs, family IDs, and building paths accordingly.

“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” (MICRODESC_BASE) – consensus methods 9 through 20.

• “2” (MICRODESC_ED25519_KEY) – consensus method 21 (adds ed25519 keys to microdescs).

• “3” (MICRODESC_NO_TAP) – Accepts Microdescriptors without onion-key bodies. (Consensus method TBD; see proposal 350.)

“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” (CONS_BASE) – consensus methods 9 through 20.

• “2” (CONST_ED25519_MDS) – consensus method 21 (adds ed25519 keys to microdescs).

“Padding”

Describes the padding capabilities of the relay.

• “1” [DEFUNCT] – Relay supports circuit-level padding. This subprotocol MUST NOT be used as it was also enabled in relays that don’t actually support circuit-level padding. Advertised by Tor versions from tor-0.4.0.1-alpha and only up to and including tor-0.4.1.4-rc.

• “2” (PADDING_MACHINES_CIRC_SETUP) – Relay supports the HS circuit setup padding machines (proposal 302). Advertised by Tor versions from tor-0.4.1.5 and onwards.

“FlowCtrl”

Describes the flow control protocol at the circuit and stream level. If there is no FlowCtrl advertised, tor supports the unauthenticated flow control features (version 0).

• “1” (FLOWCTRL_AUTH_SENDME) – supports authenticated circuit level SENDMEs as of proposal 289 in Tor 0.4.1.1-alpha.

• “2” (FLOWCTRL_CC) – supports congestion control by the Exits which implies a new SENDME format and algorithm. See proposal 324 for more details. Advertised in tor 0.4.7.3-alpha.

“Conflux”

Describes the communications mechanisms used to bundle circuits together, in order to split traffic across multiple paths.

• “1” (CONFLUX_BASE) – Supports the base coflux protocol from proposal 329.