Skip to content

Onion Association

Onion Association proposals are those which basically links a "traditional" (i.e, DNS-based) domain names with an Onion Service address. Linkage can be uni or bi-directional.

They might also be referred here as "Traditional Address Translation", to distinguish then from Onion Names.

Opportunistic discoverability

See this discussion for an example about how opportunistic service discovery could work.

Transparent versus non-transparent

One question about address translation is whether they should be transparent or not to the user:

  • Shall it be non-transparent, requiring user intervention and indicating that an Onion Service is available?
  • Or shall it be transparent, automatically redirecting the user to the .onion counterpart, at least when the regular address is not available?

Some of the current proposals are non-transparent (Onion-Location, Sauteed Onions), while others are transparent (Alt-Svc). It's mostly an UX decision here which does not impact in the core idea of each proposal.

For the transparent address translation, it's important to consider @richard's remark about having a way to signal to the application that the connection is encrypted e2e (for websites that are HTTP on an onion service vs HTTP clearnet websites). Browser cares about this to warn users about mixed-mode content, whether the page is "secure" etc.

Overview

Method Technology Status Main properties
Onion-Location HTTP, HTML Implemented, officially supported Usability; easy deployment
Alt-Svc HTTP Implemented, fully supported Transparency
DNS-based discovery DNS Research Ubiquity
Sauteed Onions CT Logs Research Censorship resistance; usability

Main properties

Property Onion-Location Alt-Svc DNS-based Sauteed Onions
Privacy-enhanced queries Yes ? Yes Yes
Self-authentication No No TBD Not in the current proposal
Censorship resistance No No Some Yes
Human-friendliness No Yes Yes Yes
Discoverability Yes Yes Yes Yes
Anonymity ? ? ? ?
Hijacking resistance ? ? ? ?
State on client system ? ? ? ?
Usable Yes Yes Yes Yes

HTTP Header-based

Where a service announces by some way it's alternative Onion Service address, like with a HTTP Header (or an HTML meta tag in some cases).

The idea here is that a regular site can announce it's .onion version when it's offering content to a client.

Onion-Location

The Onion-Location method was introduced on Tor Browser 9.5 as a way for service operators announce their Onion Services in their regular HTTPS sites. It's specified under tor-browser-spec's Proposal 100 - "Onion redirects using Onion-Location HTTP header". The ticket about implementing Onion-Location also has important discussions about this specific approach as well as servide discovery in general.

Service discovery happens in the HTTP level, either as an HTTP Header or as an HTML <meta> tag. This means that users need first to access the regular site in order to discover the .onion address.

In the case of the Tor Browser, a special user interface indication show the available Onion Service address when this is provided by the site, which allows users to upgrade do the Onion Service version. It's also possible to configure Tor Browser to automatically upgrade the connection to it's corresponding Onion Service when the Onion-Location information is available.

Alt-Svc

Similar to Onion-Location, the Alt-Svc method also uses an HTTP Header (the Alt-Svc Header, specified by RFC 7838), which means that the user first need to access the regular site before their browser discovers the alternate Onion Service address.

But contrary to Onion-Location, the Alt-Svc method:

  1. Does not support an HTML tag, as it relies entirely in the Alt-Svc Header.
  2. Is fully transparent: all the discovery and upgrade happens automatically, without user intervention.

DNS or DNSSEC-based

Another approach for associating regular domains with their .onion counterparts is to use the Domain Name System (DNS) (RFC 1035) directly and to optionally take advantage of DNSSEC.

Using HTTPS records

RFC 9460 (from draft-ietf-dnsop-svcb-https-12) introduces a "Service binding and parameter specification via the DNS (DNS SVCB and HTTPS RRs)". In other words, it specifies a new DNS resource record called HTTPS that allows service operators add entries in the DNS specifying various parameters relates to TLS connections, like those currently done via HTTP Strict Transport Security (STS). Check this article for an introduction and this one for an overview about the HTTPS RRs security benefits and attack surface.

This standard opens the possibility to use HTTPS records for Onion Services in a way that clients such as Tor Browser to establish HTTPS connections directly to Onion Services in a transparent way: users would still be presented to the regular domain name of a service (such as torproject.org) but Tor-capable clients would automatically and transparently upgrade the connection to the Onion Service version, similar to what the Alt-Svc method does.

Advantages

The advantages of the HTTPS DNS record over the Alt-Svc method are:

  1. Service operators would need only to add the HTTPS resource record in their DNS zone, without the need to change their existing web applications to include an Alt-Svc Header in the HTTP responses.
  2. TLS connections could benefit from TLS Encrypted Client Hello (ECH) as a way of hiding the domain request from a passive adversary when establishing connections to remote endpoints. But note that, as of 2024-08, ECH is still a draft proposal (although) it's already being pushed hard and deployed by vendors

Disadvantages

As of 2024-08, it seems like major web browsers require queries to be done through DNS-over-HTTPS (DoH) in other to look for this field. But this might lead to additional centralization, since DoH is not widely deployed yet and browsers might come with just a few DoH server options by default.

This is discussed in more detail at:

Support

This specification is recent and not all client support may be supporting it, although the use of HTTPS resource records is increasing.

Firefox support, and hence potential Tor Browser support:

Chrome, in the other hand, seems not to be fully supporting it, which can make adoption harder for clients such as Brave. But Safari seems to be fully supporting it, which means WebKit is probably supporting it, paving the way for Onion Browser support it as well.

Further discussion

Check the Specs for DNS-based .onion records appendix for a detailed discussion.

Specific Onion Service DNS entry

Another way to include Onion Services addresses into the DNS is to standardize by either:

  1. Have a custom Onion Service DNS resource record (like ONION).
  2. Use the TXT record as stated by RFC 1464.
  3. Use the SRV record (RFC 2782).

In any case, currently there seems to be no formal proposal to standardize this method.

Check the Specs for DNS-based .onion records appendix for a detailed discussion.

Certificate Transparency (CT Logs) based

Certificate Transparency (CT) is a system compose of many append-only TLS certificate logs as a way to audit the issuance of digital certificates.

These logs may however be monitored for other purposes, such as to discover domains and services. With some additional conventions, CT Logs can be used to establish links between traditional domain names and Onion Service addresses.

[CT Logs][] can be used as a global index of registered domains relying on CA-validated certificates. Such index can then be used as a base for searching sites as well as onionsites having CA-validated certs.

With some ingenuity, [CT Logs][] can also be used to link regular domains with onionsites.

Sauteed Onions

The Sauteed Onions proposals is such a method to link regular domains with Onion Services. It relies on custom DNS entries, CA issued certificates and Certificate Transparency (CT) Logs:

One of the main advantages of Sauteed Onions over other traditional address translation techniques is that it may offer additional protection against internet censorship, as it may be harder to block CT Logs (as they tend to be a requirement in order to browsers function properly) than the DNS or any site.