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-30.
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) | Needs work | 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 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 (0.4.8.1-alpha) | 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 (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).
- 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¶
-
UNIX sockets sockets for proxying requests. ↩
-
Keys migration from one implementation to the other. ↩
-
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. ↩
-
According to tpo/core/tor#18098, this is unlikely to be implemented on C Tor, but can be achieved using tools such as Onionmine. ↩
-
This idea is discussed at tpo/core/arti#1028. ↩
-
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. ↩
-
"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. ↩
-
Restricted discovery is also known as Client Authorization. ↩↩