Filename: 350-remove-tap.md
Title: A phased plan to remove TAP onion keys
Author: Nick Mathewson
Created: 31 May 2024
Status: Accepted

Introduction

Back in proposal 216, we introduced the ntor circuit extension handshake. It replaced the older TAP handshake, which was badly designed, and dependent on insecure key lengths (RSA1024, DH1024).

With the final shutdown of v2 onion services, there are no longer any supported users of TAP anywhere in the Tor protocols. Anecdotally, a relay operator reports that fewer than one handshake in 300,000 is currently TAP. (Such handshakes are presumably coming from long-obsolete clients.)

Nonetheless, we continue to bear burdens from TAP support. For example:

  • TAP keys compose a significant (but useless!) portion of directory traffic.
  • The TAP handshake requires cryptographic primitives used nowhere else in the Tor protocols.

Now that we are implementing relays in Arti, the time is ripe to remove TAP. (The only alternative is to add a useless TAP implementation in Arti, which would be a waste of time.)

This document outlines a plan to completely remove the TAP handshake, and its associated keys, from the Tor protocols.

This is, in some respects, a modernized version of proposal 245.

Migration plan

Here is the plan in summary; we'll discuss each phase below.

  • Phase 1: Remove TAP dependencies
    • Item 1: Stop accepting TAP circuit requests.
    • Item 2: Make TAP keys optional in directory documents.
    • Item 3: Publish dummy TAP keys.
  • Phase 2: After everybody has updated
    • Item 1: Allow TAP-free routerdescs at the authorities
    • Item 2: Generate TAP-free microdescriptors
  • Phase 3: Stop publishing dummy TAP keys.

Phase 1 can begin immediately.

Phase 2 can begin once all supported clients and relays have upgraded to run versions with the changes made in Phase 1.

Phase 3 can begin once all authorities have made the changes described in phase 2.

Phase 4 can begin once C Tor is completely retired.

All items within each phase can happen in parallel.

Phase 1: Abolish TAP circuits, making TAP keys unused

Phase 1, Item 1: Stop accepting TAP circuit requests.

Immediately, Tor relays should stop accepting TAP requests. This includes all CREATE cells (not CREATE2), and any CREATE2 cell whose type is TAP (0x0000).

When receiving such a request, relays should respond with DESTROY. Relays MAY just drop the request entirely, however, if they find that they are getting too many requests.

Such relays must stop reporting Relay=1 among their supported protocol versions. (This protocol version is not currently required or recommended.)

If this proposal is accepted, we should clarify the protocol version specification to say that Relay=1 specifically denotes TAP.

Phase 1, Item 2: Make TAP keys optional in directory documents.

In C Tor, we should make the onion-key entry and the onion-key-crosscert entry optional. (If either is present, the other still must be present.)

When we do this, we should also modify the authority code to reject any descriptors that do not have these fields. (This will be needed so that existing Tor instances do not break.)

In the microdescriptor documents format, we should make the object of the onion-key element optional. (We do not want to make the element itself optional, since it is used to delimit microdescriptors.)

We use new protocol version flags (Desc=3, Microdesc=3) to note the ability to parse these documents.

This was done in C Tor 0.4.9.

All published versions of Arti treat TAP keys as optional.

In Arti client we should remove all knowledge of onion-key-crosscert items and onion-key items in routerdescs. For onion-key item in microdescs we must retain the item, since it's the intro item for the microdesc. Arti should tolerate and discard the item's object.

Phase 1, Item 3: Publish dummy TAP keys

Even after step 2 is done, many clients and relays on the network will still require TAP keys to be present in directory documents. Therefore, we can't remove those keys right away.

Relays, therefore, must put some kind of RSA key into their onion-key field.

I'll present three designs on what relays should do. We should pick one.

Option 1 (conservative)

Maybe, we should say that a relay should generate a TAP key, generate an onion-key-crosscert, and then discard the private component of the key.

Option 2 (low-effort)

In C tor, we can have relays simply proceed as they do now, maintaining TAP private keys and generating crosscerts.

This has little real risk beyond what is described in Option 1.

Option 3 (nutty)

We could generate a global, shared RSA1024 private key, to be used only for generating onion-key-crosscerts and placing into the onion-key field of a descriptor.

We would say that relays publishing this key MUST NOT actually handle any TAP requests.

The advantage of this approach over Option 1 would be that we'd see gains in our directory traffic immediately, since all identical onion keys would be highly compressible.

The downside here is that any client TAP requests sent to such a relay would be decryptable by anybody, which would expose long-obsolete clients to MITM attacks by hostile guards.

We would control the presence of these dummy TAP keys using a consensus parameter:

publish-dummy-tap-key — If set to 1, relays should include a dummy TAP key in their routerdescs. If set to 0, relays should omit the TAP key and corresponding crosscert. (Min: 0, Max, 1, Default: 0.)

We would want to ensure that all authorities voted for this parameter as "1" before enabling support for it at the relay level.

Phase 1, Item 4: Deprecate using full routerdescs for client use cases

C Tor has a configuration option which causes it to use full routerdescs rather than microdescs. (UseMicrodescriptors 0.)

This configuration exposes the client directly to relay-generated routerdescs, which is an unnecessary attack surface and compatibility hazard.

Specifically in this context, Arti dirauth will not check TAP key information in routerdescs. This means that after Arti dirauth is deployed (at earliest, Phase 3), C Tor clients configured to use full descriptors, may see broken TAP keys included in by broken relays in their routerdescs.

So, for client use cases (ie, "connect to the Tor network for anonymity and/or to access hidden services") we recommend against this option.

Network monitoring applications will obviously still want to look at full routerdescs. Many currently use C Tor with UseMicrodescriptors 0. This configuration is not deprecated. Instead, we will check C Tor's behaviour in this configuration when exposed to "bad" routerdescs (specifically, with bad TAP data), and make any necessary fixes.

Phase 2: Remove TAP keys from the consensus

Phase 2, Item 1: Allow TAP-free routerdescs at the authorities

Once all clients and relays have updated to a version where the onion-key router descriptor element is optional (see phase 1, item 2):

Remove the authority code that requires all descriptors to have TAP keys. (This applies to both directory authorities and bridge authorities.)

Declare DESC_NO_TAP a required subprotocol capability.

Phase 2, Item 2: Generate TAP-free microdescriptors

Once all clients and descriptors have updated to a version where the onion-key body is optional in microdescriptors (see phase 1, item 2):

Add a new consensus method in which authorities omit the body when generating microdescriptors.

Declare MICRODESC_NO_TAP a required subprotocol capability.

(We cannot deploy the Arti consensus method C Tor plugin except as part of this item, because Arti contains no code to include TAP keys in microdescriptors, so the Arti consensus method will produce microdescriptors that require MICRODESC_NO_TAP.)

Phase 3: Stop publishing dummy TAP keys.

Phase 3, Item 1: Remove TAP keys from C Tor routerdescs

Once all authorities (including directory authorities and bridge authorities) have stopped requiring the onion-key element in router descriptors (see phase 2, item 1):

Set the publish-dummy-tap-key consensus parameter to 0, so that relays will no longer include TAP keys in their router descriptors.

We cannot deploy Arti Relay on the live network except as part of, or after, this item, because its routerdesc will not contain onion-key.

(Arti Relay could be tested or deployed as an unlisted bridge, even before this point, and used by clients running C Tor 0.4.9 or later, or Arti.)

Phase 3, Item 2: Remove vestigial TAP code in Arti

Once all authorities have upgraded to a TAP-free consensus method (phase 2, item 2):

Remove the special handling in Arti of the object on an onion-key item in a microdesc. Consequently, microdescs whose onion-key item has an object would be rejected. (But the authorities won't generate those any more.)

Once there are no longer any C Tor relays on the network:

No longer publish the publish-dummy-tap-key netparam. (This only exists to control C Tor relays' TAP key generation. Arti never generates TAP keys.)

Relegate the following to historical/:

  • The publish-dummy-tap-key and NumNTorsPerTAP netparams
  • The onion-key item in routerdescs
  • The onion-key-crosscert item in routerdescs and microdescs
  • The dummy object on an onion-key item in microdescs
  • KP_onion_tap, KS_onion_tap
  • Mention of TAP in KDF-TOR
  • obsolete-circuit-extension.md

Relegate the following codepoint descriptions to historical/, leaving the codepoint allocated:

  • Subprotocol capability RELAY_BASE.
  • EXTEND and EXTENDED relay cells.
  • HTYPE TAP in CREATE2 cells.