Filename: 366-ntorv3-for-hs.md
Title: Ntorv3 (and beyond) for HS introduction
Author: Nick Mathewson
Created: 30 July 2025
Status: Open

Introduction

Despite their similarities, Tor circuit extensions (via EXTEND and EXTEND2) and onion service introductions (via INTRODUCE2) have used slightly different cryptographic handshakes.

These differences were once necessary because onion service INTRODUCE messages require additional encrypted information (specifying the rendezvous point) beyond the information given in ordinary circuit-extenstion handshakes.

But starting with ntorv3 handshakes, Tor circuits extension now has a built-in way to include extra encrypted information in the handshake request and response.

This proposal describes a way to migrate the INTRODUCE/RENDEZVOUS handshake to use ntorv3 in place of hs-ntor, and eventually to use whatever postquantum successor handshake we may choose to adopt.

This proposal requires no changes on relays serving as introduction or rendezvous points.

Proposal

Encoding introduce information for ntorv3 etc.

When using the ntorv3 handshake (or any other handshake besides hs-ntor) for INTRODUCE handshakes, the following extension is mandatory:

RENDEZVOUS_POINT (identifier TBD)

ONION_KEY_TYPE is here given in an HTYPE field of a CREATE2 cell.

This extension MUST NOT be sent for an EXTEND2 handshake, or in an hs-ntor handshake. If received in those contexts, the introduction attempt MUST be rejected.

Authenticating INTRODUCE1 plaintext

When using ntorv3 with an INTRODUCE1 message, clients MUST pass the plaintext portion of the INTRODUCE1 message (everything from LEGACY_KEY_ID up to but not including the ENCRYPTED field) as the VER (optional shared verification string) input to ntorv3. This value should be prefixed with the string "introduce1:" to distinguish it from a regular circuit extension.

This will ensure that the introduction point cannot modify these fields.

Future handshakes MUST include an input of this type.

Indicating the handshake type.

Here we specify two ways for the client to indicate which handshake is in use. One is more straightforward; the other tries to hide the handshake type from the introduction point.

Straightforward handshake indication

We define an unencrypted extension to be sent in INTRODUCE1 messages:

HANDSHAKE_TYPE (identifier tbd)

This value indicates which handshake is in use. If it is absent, the client is using hs-ntor.

Limitations: since the value is visible to the introduction point, it can use it to identify which handshake is in use.

We should decide if this is a problem, and if so, take one of the approaches described in the next session.

Encrypted handshake indications

TODO: Write this if we decide it is necessary.

We could in the worst case do: a curve25519 key + 2 bytes of message + 32 bytes of digest, to encode the v3 handshake type using the ntor key. But that's quite ugly and a bit large and slows introduction down by an additional PK handshake.

We could alternatively do something symmetric, deriving the encryption key from a digest of the service's encryption key (KP_hss_ntor) or some other value in the service descriptor. If the intro point knows this key, they already have access to the inner layer of the service descriptor, which means they know which server they are introducing for.

If this kind of encrypted extension is in use, clients should send it regardless of whether they're using hs-ntor, to hide the actual handshake type.

Encoding other responses in RENDEZVOUS messages.

The RENDEZVOUS1 and RENDEZVOUS2 message types do not impose limitations on their handshake contents; therefore, it's trivial to include an ntorv3 response (or any other kind of response) in place of an hs-ntor response.

Indicating support for these extensions

We add a new HsIntro subprotocol capability to indicate support for the extensions in this document.

Services SHOULD support, advertise, and enable the capability according to a new set of hss-advertise-hsintro-* and hss-hsintro-* network parameters as described in the parameters spec.

Clients SHOULD use these capabilities when they are advertised according to the rules of a new hsc-hsintro-* network parameter (ibid).

Encryption types

When negotiating keys with an onion service using ntorv3, clients MUST generate and discard a KH value as usual, and MUST continue to use the AES-256+SHA3 variant of tor1 encryption unless some later encryption type (such as CGO) is negotiated.

Appendices

Numeric identifiers to allocate

New handshake extensions:

• RENDEZVOUS_POINT
• INTRO_PLAINTEXT_DIGEST

New INTRODUCE1 extensions:

• HANDSHAKE_TYPE or something else

New subprotocol capabilities:

• HsIntro=TBD

New network parameters:

• hss-advertise-hsintro-TBD
• hss-hsintro-TBD
• hsc-hsintro-TBD