Onion Service implementations

Considering to add Onion Service support in your application?

This page may help you choose the right implementation or to migrate between implementations.

Last updated on 2024-09-17.

Feature matrix

Onion Service clients

Feature	Specification	Status on C Tor	Status on Arti	Config on C Tor	Config on Arti
Vanguards (lite and full)	vanguards-spec, prop333, prop292	Implemented	Implemented	VanguardsLiteEnabled	vanguards
Client Authorization	rend-spec	Implemented	Implemented	ClientOnionAuthDir	restricted_mode
Proof of Work protection	prop327	Implemented	Needs work	N/A	N/A
Debian package1	Debian Policy	Implemented	Underway	N/A	N/A

Onion Service servers

Feature	Specification	Status on C Tor	Status on Arti	Config on C Tor	Config on Arti
Load balancing	Unspecified4	Implemented	Partially supported	HiddenServiceOnionBalanceInstance; MasterOnionAddress
Vanguards (lite and full)	vanguards-spec, prop333, prop292	Implemented	Implemented	VanguardsLiteEnabled; full mode with plugin	vanguards
Client Authorization	rend-spec	Implemented	Implemented		restricted_mode
Introduction-point auth	Unspecified6	Unlikely	Not implemented
Stealth/hidden auth mode	Unspecified7	Unlikely	Not implemented
Single Hop Mode	prop260	Implemented	Planned	HiddenServiceSingleHopMode; HiddenServiceNonAnonymousMode
OOM DoS protections	dos-spec	Implemented	Underway	MaxMemInQueues
Onion Services DoS protections	rend-spec	Implemented	Partially supported	Many	max_concurrent_streams_per_circuit
Proof of Work protection	prop327	Implemented	Needs work	HiddenServicePoW{DefensesEnabled,QueueRate,QueueBurst}
UNIX sockets2	Unspecified	Implemented	Planned	HiddenServicePort
Observability and Metrics	Unspecified	Implemented	Planned	MetricsPort; MetricsPortPolicy
Circuit ID exporting	Unspecified	Implemented	Not implemented	HiddenServiceExportCircuitID
CAA (ACME)	prop343	Needs work	Planned	HiddenServiceCAA
Offline Keys	rend-spec	Unlikely	Planned
PKCS#11 tokens	PKCS#11	Unlikely	Considered
CLI for key generation	Unspecified	Third-party5	Implemented	N/A	N/A
Keys migration3	Unspecified	Not implemented	Not implemented	N/A	N/A
Debian package1	Debian Policy	Implemented	Underway	N/A	N/A
Dockerfile	dockerfile	Not implemented	Not implemented	N/A	N/A
Official container image	Unspecified	Not implemented	Not implemented	N/A	N/A

Legend

• N/A: not applicable.
• Unspecified: this means there's no tor-spec for the feature, which usually means it's implementation specific, and not standardized (yet).
• Not implemented: the feature is not implemented, and still not planned.
• Unlikely: it's unlikely that the feature will be implemented.
• Considered: feature is being considered, but not planned (yet).
• Planned: feature was added in the roadmap.
• Underway: feature is being actively developed, or (almost) ready for production.
• Needs work: there's initial code implementing the feature, but additional work is needed.
• Partially supported: feature has partial support, either by being partially implemented or by being leveraged by some property or third-party plugin.
• Third-party: functionality works through third-party tools or plugins.
• Implemented: feature has been fully implemented.

Key formats

Each implementation has it's own storage format for the keys (C Tor, Onionbalance and Arti).

Migration support right now is like the following.

Tip

If unsure between the C Tor and Onionbalance formats, generate your keys in a program that uses the C Tor format, and then load it on Onionbalance as needed.

From C Tor to Onionbalance

• Works: Onionbalance can load the keys in C Tor's format.
• References:
• Onionbalance v3 tutorial.
• onionbalance/hs_v3/service.py

Onionbalance to C Tor

• Not available.
• Onionbalance format is defined at onionbalance/config_generator/config_generator.py.
• It seems that the C Tor key storage format is not standardized/specified anywhere, but it's defined at src/lib/crypt_ops/crypto_ed25519.c.
• This is handled by tpo/onion-services/onionbalance#35.

C Tor to/from Arti

• Not available, but needs to be implemented at some point so Onion Service Operators can migrate their services to Arti.
• Arti uses the SSH format.

Onionbalance to/from Arti

• Not available, but needs to be implemented at some point so Onion Service Operators can migrate their services to Arti.

Notes

---

1. Debian package with Onion Services server support. ↩↩

2. UNIX sockets sockets for proxying requests. ↩

3. Keys migration from one implementation to the other. ↩

4. Although prop255 (Controller features to allow for load-balancing hidden services) and prop307 (Onion Balance Support for Onion Service v3) exists, it seems that the current implementation is not specified, relying only on the control-spec built upon a naive load balancing which depends on a faulty cross-certs in introduction point keys. It's also worth noting that any Onion Service implementation should support running multiple parallel instances out-of-the-box. ↩

5. According to tpo/core/tor#18098, this is unlikely to be implemented on C Tor, but can be achieved using tools such as Onionmine. ↩

6. This idea is discussed at tpo/core/arti#1028. ↩

7. While this was specified for rend-spec-v2 (2.2. Authorization for limited number of clients), this was never implemented, at least for Onion Services v3. Idea is further discussed on tpo/core/torspec#119 and tpo/core/torspec#150. ↩