Filename: 363-required-protovers-and-hs.md
Title: Required/recommended protocols for onion services
Author: Nick Mathewson
Created: 29 April 2025
Status: Open

Introduction

In proposals 264 and 297, we defined a mechanism for Tor implementations to check whether they are missing any recommended (or required) Tor subprotocol capabilities, and to warn the user (or shut down) if so.

But while implementing this behavior in Arti, we found an interesting corner case: because Arti clients can be built without onion service support, it is problematic that recommended-client-protocols contains HSDir=2 HSIntro=4 HSRend=2.

According to the letter of the spec, any client that does not support these protocols should warn its user that its software is likely to be obsolete. But that isn't true for Arti: It's just possible to build Arti with no onion services.

Now, we could just remove all HS* entries from recommended-client-protocols, but that would leave us with no way to encourage clients with onion service support to upgrade to new versions.

Recommended protocols for onion services

Instead, we will add the following new entries to the consensus:

• recommended-hsc-protocols
• required-hsc-protocols
• recommended-hss-protocols
• required-hss-protocols

They are voted on using the same mechanism as the existing (recommended/required)-(client/server)-protocols entries.

hsc stands for "hidden service client"; hss stands fore "hidden service service".

The rules for obeying these entries are as follows:

Any implementation that can connect to onion services SHOULD warn if it is missing any subprotocol capability from recommended-hsc-protocols.

Any implementation that can connect to onion services SHOULD refuse to do so if it is missing any subprotocol capability from required-hsc-protocols. Such an implementation MAY refuse to start.

Any implementation that is configured to run an onion service SHOULD warn if it is missing any subprotocol capability from recommended-hss-protocols. Implementations that are able to run onion services MAY warn under this circumstance, even if they are not configured to run an onion service.

Any implementation that is configured to run an onion service SHOULD refuse to do so if it is missing any subprotocol capability from required-hss-protocols. Such an implementation MAY refuse to start.

Appendix: New reserved values

We must reserve a new consensus method to vote on the new entries in the consensus.