Filename: 252-single-onion.txt
Title: Single Onion Services
Author: John Brooks, Paul Syverson, Roger Dingledine
Created: 2015-07-13
Status: Superseded
Superseded-by: 260
1. Overview
Single onion services are a modified form of onion services, which trade
service-side location privacy for improved performance, reliability, and
scalability.
Single onion services have a .onion address identical to any other onion
service. The descriptor contains information sufficient to do a relay
extend of a circuit to the onion service and to open a stream for the onion
address. The introduction point and rendezvous protocols are bypassed for
these services.
We also specify behavior for a tor instance to publish a single onion
service, which requires a reachable OR port, without necessarily acting
as a public relay in the network.
2. Motivation
Single onion services have a few benefits over double onion services:
* Connection latency is much lower by skipping rendezvous
* Stream latency is reduced on a 4-hop circuit
* Removing rendezvous circuits improves service scalability
* A single onion service can use multiple relays for load balancing
Single onion services are not location hidden on the service side,
but clients retain all of the benefits and privacy of onion
services. More details, relation to double onion services, and the
rationale for the 'single' and 'double' nomenclature are further
described in section 7.4.
We believe these improvements, along with the other benefits of onion
services, will be a significant incentive for website and other internet
service operators to provide these portals to preserve the privacy of their
users.
3. Onion descriptors
The onion descriptor format is extended to add:
"service-extend-locations" NL encrypted-string
[At most once]
A list of relay extend info, which is used instead of introduction
points and rendezvous for single onion services. This field is
encoded and optionally encrypted in the same way as the
"introduction-points" field.
The encoded contents of this field contains no more than 10 entries,
each containing the following data:
"service-extend-location" SP link-specifiers NL
[At start, exactly once]
link-specifiers is a base64 encoded link specifier block, in
the format described by proposal 224 [BUILDING-BLOCKS] and the
EXTEND2 cell.
"onion-key" SP key-type NL onion-key
[Exactly once]
Describes the onion key that must be used when extending to the
single onion service relay.
The key-type field is one of:
"tap"
onion-key is a PEM-encoded RSA relay onion key
"ntor"
onion-key is a base64-encoded NTOR relay onion key
[XXX: Should there be some kind of cookie to prove that we have the desc?
See also section 7.1. -special]
A descriptor may contain either or both of "introduction-points" and
"service-extend-locations"; see section 5.2.
[XXX: What kind of backwards compatibility issues exist here? Will existing
relays accept one of those descriptors? -special]
4. Reaching a single onion service as a client
Single onion services use normal onion hostnames, so the client will first
request the service's descriptor. If the descriptor contains a
"service-extend-locations" field, the client should ignore the introduction
points and rendezvous process in favor of the process defined here.
The descriptor's "service-extend-locations" information is sufficient for a
client to extend a circuit to the onion service, regardless of whether it
is also listed as a relay in the network consensus. This extend info must
not be used for any other purpose. If multiple extend locations are
specified, the client should randomly select one.
The client uses a 3-hop circuit to extend to the service location from the
descriptor. Once this circuit is built, the client sends a BEGIN cell to
the relay, with the onion address as hostname and the desired TCP port.
If the circuit or stream fails, the client should retry using another
extend location from the descriptor. If all extend locations fail, and the
descriptor contains an "introduction-points" field, the client may fall
back to a full rendezvous operation.
5. Publishing a single onion service
To act as a single onion service, a tor instance (or cooperating group of
tor instances) must:
* Have a publicly accessible OR port
* Publish onion descriptors in the same manner as any onion service
* Include a "service-extend-locations" section in the onion descriptor
* Accept RELAY_BEGIN cells for the service as defined in section 5.3
5.1. Configuration options
The tor server operating a single onion service must accept connections as
a tor relay, but is not required to be published in the consensus or to
allow extending circuits. To enable this, we propose the following
configuration option:
RelayAllowExtend 0|1
If set, allow clients to extend circuits from this relay. Otherwise,
refuse all extend cells. PublishServerDescriptor must also be disabled
if this option is disabled. If ExitRelay is also disabled, this relay
will not pass through any traffic.
5.2. Publishing descriptors
A single onion service must publish descriptors in the same manner as any
onion service, as defined by rend-spec and section 3 of this proposal.
Optionally, a set of introduction points may be included in the descriptor
to provide backwards compatibility with clients that don't support single
onion services, or to provide a fallback when the extend locations fail.
5.3. RELAY_BEGIN
When a RELAY_BEGIN cell is received with a configured single onion hostname
as the destination, the stream should be connected to the configured
backend server in the same manner as a service-side rendezvous stream.
All relays must reject any RELAY_BEGIN cell with an address ending in
".onion" that does not match a locally configured single onion service.
6. Other considerations
6.1. Load balancing
High capacity services can distribute load by including multiple entries in
the "service-extend-locations" section of the descriptor, or by publishing
several descriptors to different onion service directories, or by a
combination of these methods.
6.2. Benefits of also running a Tor relay
If a single onion service also acts as a published tor relay, it will keep
connections to many other tor relays. This can significantly reduce the
latency of connections to the single onion service, and also helps the tor
network.
6.3. Proposal 224 ("Next-Generation Hidden Services")
This proposal is compatible with proposal 224, with small changes to the
service descriptor format. In particular:
The "service-extend-location" sections are included in the encrypted
portion of the descriptor, adjacent to any "introduction-point" sections.
The "service-extend-locations" field is no longer present. An onion service
is also single onion service if any "service-extend-location" field is
present.
6.4. Proposal 246 ("Merging Hidden Service Directories and Intro Points")
This proposal is compatible with proposal 246. The onion service will
publish its descriptor to the introduction points in the same manner as any
other onion service. The client may choose to build a circuit to the
specified relays, or to continue with the rendezvous protocol.
The client should not extend from the introduction point to the single
onion service's relay, to avoid overloading the introduction point. The
client may truncate the circuit and extend through a new relay.
7. Discussion
7.1. Authorization
Client authorization for a single onion service is possible through
encryption of the service-extend-locations section in the descriptor, or
"stealth" publication under a new onion address, as with traditional onion
services.
One problem with this is that if you suspect a relay is also serving a
single onion service, you can connect to it and send RELAY_BEGIN without
any further authorization. To prevent this, we would need to include a
cookie from the descriptor in the RELAY_BEGIN information.
7.2. Preventing relays from being unintentionally published
Many single onion servers will not want to relay other traffic, and will
set 'PublishServerDescriptor 0' to prevent it. Even when they do, they will
still generate a relay descriptor, which could be downloaded and published
to a directory authority without the relay's consent. To prevent this, we
should insert a field in the relay descriptor when PublishServerDescriptor
is disabled that instructs relays to never include it as part of a
consensus.
[XXX: Also see task #16564]
7.3. Ephemeral single onion services (ADD_ONION)
The ADD_ONION control port command could be extended to support ephemerally
configured single onion services. We encourage this, but specifying its
behavior is out of the scope of this proposal.
7.4. Onion service taxonomy and nomenclature
Onion services in general provide several benefits. First, by requiring a
connection via Tor they provide the client the protections of Tor and make
it much more difficult to inadvertently bypass those protections than when
connecting to a non .onion site. Second, because .onion addresses are
self-authenticating, onion services have look-up, routing, and
authentication protections not provided by sites with standard domain
addresses. These benefits apply to all onion services.
Onion services as originally introduced also provide network location
hiding of the service itself: because the client only ever connects through
the end of a Tor circuit created by the onion service, the IP address of
the onion service also remains protected.
Applications and services already exist that use existing onion service
protocols for the above described general benefits without the need for
network location hiding. This Proposal is accordingly motivated by a desire
to provide the general benefits, without the complexity and overhead of
also protecting the location of the service.
Further, as with what had originally been called 'location hidden
services', there may be useful and valid applications of this design that
are not reflected in our current intent. Just as 'location hidden service'
is a misleading name for many current onion service applications, we prefer
a name that is descriptive of the system but flexible with respect to
applications of it. We also prefer a nomenclature that consistently works
for the different types of onion services.
It is also important to have short, simple names lest usage efficiencies
evolve easier names for us. For example, 'hidden service' has replaced the
original 'location hidden service' in Tor Proposals and other writings.
For these reasons, we have chosen 'onion services' to refer to both those
as set out in this Proposal and those with the client-side and server-side
protections of the original---also for referring indiscriminately to any
and all onion services. We use 'double-onion service' to refer to services
that join two Tor circuits, one from the server and one from the client. We
use 'single-onion' when referring to services that use only a client-side
Tor circuit. In speech we sometimes use the even briefer, 'two-nion' and
'one-ion' respectively.