Skip to content

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-11-05.

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 (1.2.2) VanguardsLiteEnabled vanguards
Restricted discovery9 rend-spec ✅ Implemented ✅ Implemented (1.2.7) ClientOnionAuthDir restricted_mode
Proof of Work protection prop327 ✅ Implemented (0.4.8.1-alpha) ✅ Implemented (1.3.0) N/A N/A
Conflux prop329 Planned ❌ Not implemented N/A N/A
Debian package1 Debian Policy ✅ Implemented Underway (1.2.7) 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 supported8 HiddenServiceOnionBalanceInstance; MasterOnionAddress
Vanguards (lite and full) vanguards-spec, prop333, prop292 ✅ Implemented ✅ Implemented (1.2.2) VanguardsLiteEnabled; full mode with plugin vanguards
Restricted discovery9 rend-spec ✅ Implemented ✅ Implemented (1.2.7) restricted_mode
Introduction-point auth6 Draft ❌ 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 Implemented (1.3.0) MaxMemInQueues system.memory, system.max_files
Onion Services DoS protections rend-spec ✅ Implemented Partially supported Many max_concurrent_streams_per_circuit
Proof of Work protection prop327 ✅ Implemented (0.4.8.1-alpha) Planned HiddenServicePoW{DefensesEnabled,QueueRate,QueueBurst}
Conflux prop329 Planned ❌ Not implemented N/A N/A
UNIX sockets2 Unspecified ✅ Implemented Planned HiddenServicePort
Observability and Metrics Unspecified ✅ Implemented Planned10 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 (1.2.8) 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).
  • Draft: there's a draft spec not yet proposed.
  • ❌ 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

From Onionbalance to C Tor

From C Tor to Arti

  • Partially works:
  • Arti can use existing C Tor keys.
  • Arti uses the SSH format.
  • Migrating keys from C Tor to Arti's format is still not available, but needs to be implemented at some point, so Onion Service Operators can fully migrate their services to Arti.

From Arti to C Tor

  • Not available.
  • Probably won't be implemented.

From Onionbalance to Arti

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

From Arti to Onionbalance

  • Not available.
  • Probably won't be implemented.

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. ↩

  8. "Partial" support here means that a simple load balancing functionality can be achieved by simply running an Onion Services in multiple parallel instances of Arti. ↩

  9. Restricted discovery is also known as Client Authorization. ↩↩

  10. This is planned on tpo/core/arti#1003 and on tpo/core/arti#1726. ↩