Filename: 100-onion-location-header.txt
Title: Onion redirects using Onion-Location HTTP header
Author: George Kadianakis
Created: 02-02-2018
Status: Open
Ticket: #21952

1. Motivation:

   Lots of high-profile websites have onion addresses these days (e.g. Tor,
   NYT, blockchain, ProPublica).  All those websites seem confused on what's
   the right way to inform their users about their onion addresses. Here are
   some confusion examples:
     a) torproject.org does not even advertise their onion address to Tor users (!!!)
     b) blockchain.info throws an ugly ASCII page to Tor users mentioning their onion
        address and completely wrecking the UX (loses URL params, etc.)
     c) ProPublica has a "Browse via Tor" section which redirects to the onion site.

   Ideally there would be a consistent way for websites to inform their users
   about their onion counterpart. This would provide the following positives:
     + Tor users would use onions more often. That's important for user
       education and user perception, and also to partially dispell the darkweb myth.
     + Website operators wouldn't have to come up with ad-hoc ways to advertise
       their onion services, which sometimes results in complete breakage of
       the user experience (particularly with blockchain)

   This proposal specifies a simple way forward here that's far from perfect,
   but can still provide benefits and also improve user-education around onions
   so that in the future we could employ more advanced techniques.

   Also see Tor ticket #21952 for more discussion on this:
      https://trac.torproject.org/projects/tor/ticket/21952

2. Proposal

2.1. Redirection method

   We introduce a new HTTP header called "Onion-Location", which websites
   can use to specify their onion counterpart.

   Example:
    Onion-Location: http://vwc43ag5jyewlfgf.onion

2.2. Browser logic

   The Tor Browser intercepts the Onion-Location HTTP header (if any) and
   acts upon it in two possible ways, depending on the configuration state
   of the browser:

   a) If the user has enabled automatic Onion-Location redirects
      the header is equivalent to a redirect with a Refresh header and a
      timeout of 0 seconds [1]. As an example: the header in 2.1 would be
      treated like a `Refresh: 0;URL='http://vwc43ag5jyewlfgf.onion'` header.

   b) If the user has not enabled automatic Onion-Location redirects,
      it informs them of the existence of the onionsite, giving them the option
      to visit it. If the user chooses to visit the onionsite, the webpage
      will be reloaded and redirected to its onion counterpart, as in a).

   Before acting upon it, the browser checks whether the Onion-Location has
   a valid value, and ignores it if it does not. For the header to be valid
   the following conditions need to be fulfilled:

   * The Onion-Location value must be a valid URL with http: or https: protocol
     and a .onion hostname.

   * The webpage defining the Onion-Location header must be served over HTTPS.

   * The webpage defining the Onion-Location header must not be an onionsite.

   Tor Browser should inform the user about the onion in a non-intrusive way
   (e.g. an infobar below the address bar), it should also provide a way for
   the user to visit the onion, and a button that offers more information about
   onions.

   Browsers that don't support Tor SHOULD ignore the Onion-Location header.

2.3. Using an HTML <meta> attribute instead of an HTTP header

   The (conditionally) identical behaviour of Onion-Location and a Refresh
   header (with 0 seconds timeout) includes the option of defining it as a
   HTML <meta> http-equiv attribute. This may be used by websites that prefer
   (or need) to define Onion-Location by modifying the served HTML content
   instead of adding a new HTTP header.

   As an example, the Onion-Location header in 2.1 would be equivalent to a
   `<meta http-equiv="onion-location" content="http://vwc43ag5jyewlfgf.onion" />`
   added in the HTML head element of the webpage.

3. Drawbacks

3.1. No security/performance benefits

   While we could come up with onion redirection proposals that provide
   security and performance benefits, this proposal does not actually provide
   any of those.

   As a matter of fact, the security remains the same as connecting to normal
   websites, since for this proposal to work we need to trust their HTTP headers,
   and the user might have already provided identifying information
   (e.g. cookies) to the website. The performance is worse than connecting to a
   normal website, since Tor first needs to connect to the website, get its
   headers, and then finally connect to the onion.

   Still _all_ the website approaches mentioned in the "Motivation" section
   suffer from the above drawbacks, and sysadmins still come up with ad-hoc
   ways to inform users about their onions. So this simple proposal will still
   help those websites and also pave the way forward for future auto-redirect
   techniques.

3.2. Defining new HTTP headers is not the best idea

   This proposal defines a new non-standard HTTP header. This is not great
   because it makes Tor into a "special" thing that needs to be supported with
   special headers. However, the fact that it's a new HTTP header that only
   works for Tor is a positive thing since it means that non-Tor browsers will
   just ignore it.

   Furthermore, another drawback is that this HTTP header will increase the
   bandwidth needlessly if it's also served to non-Tor clients. Hence websites
   with lots of client traffic are encouraged to use tools that detect Tor
   users and only serve the header to them (e.g. tordnsel). Website operators
   should be aware that tools like tordnsel have false negative potential (they
   might treat Tor users as non-Tor users) which will result in not sending
   them the Onion-Location header.

   Finally, websites can also detect Tor users (as discussed in the above
   paragraph) and redirect them using the Location header, thus triggering a
   non-prompting redirect. Websites doing so should consider the potential user
   confusion of being redirected to an odd-looking domain. The Onion-Location
   mechanism offered in this proposal is designed to provide a
   browser-supported option to consistently offer an onion service in a
   hopefuly less-confusing way.

4. The future

   As previously discussed, this is just a simple proposal to introduce the
   redirection concept to people, and also to help some sysadmins who are
   currently coming up with weird ways to inform people about their
   onions. It's not the best way to do this, but it's definitely one of the
   simplest ways.

   In the future we could implement more advanced auto-redirect proposals like:

   a) Have a "domains to onions" map into HTTPS-everywhere and have the
      extension do the autoredirects for us (performance benefits, and security
      benefits under many threat models).

   b) Bake onion addresses into SSL certificates and Let's Encrypt as suggested
      by comment:42 in #21952.

   But both of the designs above require non-trivial engineering/policy work
   and would still confuse people. So I think starting with a simple approach
   that will educate users and then moving to more advanced designs is a more
   normative way to go.


[1] https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/H76