Skip to content

Instantly share code, notes, and snippets.



Last active Aug 29, 2015
What would you like to do?
Tor HTTP to Onion Upgrade Protocol Draft Proposal

Tor HTTP Upgrade Protocol Draft Proposal

Version 0.1

6th December 2014

This is very much a draft - there are many security, privacy and performance considerations

1. Background

As of December 2014 there are almost 2.5 million directly conencting user to the Tor anonymity network. This number does not include those connecting via Tor Bridges, which are a popular method to access the network in countries and on networks where Tor directory servers are blocked.

Tor proxies web traffic through exit nodes, neccesetating transport layer security to protect the user from malicious nodes configured to intercept traffic. Tor users are advised to assure that all connections to clearweb sites are over SSL1, but there have been a large number of successful ssl stripping2 attacks against Tor users of Bitcoin sites.

Alternate Services are websites or web applications that are provided both on the clearnet and on Tor as hidden services. Visitors to a web site with an alternate service available on the Tor network should be redirected to the onion address for the alternate service. By accessing the onion service user agents avoid exit nodes and potential MITM attacks.

The idea of automatically redirecting Tor clients requesting a clearweb site that has an alternate service has come up on Tor mailing lists a number of times:

  1. tor-talk: using HTTPS Everywhere to redirect to .onion
  2. tor-talk: darkweb everywhere

This document outlines the purpose of the upgrade protocol and some proposed solutions with the idea of soliciting feedback and considering the advantages and disadvantages of each approach.

2. Current Solutions

Manual change:

  1. Providers of alternate services list the onion address on an authenticated channel such as their website or Twitter account
  2. Users visit the onion address manually, update bookmarks etc.
  3. Some services block access to their clearweb service to traffic from Tor exit nodes in order to force UA's to visit the onion.

Disadvantages to this approach are that it requires an established secure channel to communicate the onion address, user authentication of the site message, the message being a positive signal that an MITM can remove and not forward to the UA and user not being forced to adopt the onion link without the site blocking all exit node traffic.

Browser extensions:

  1. The Darkweb Everywhere browser extension, a fork of HTTPS Everywhere, maintains an index of clearweb to onion address mappings and will automatically redirect the UA with any visit to a clearweb hostname contained in its index to the respective onion address.

Extension requires maintenance of links, proof and an audit trail of legitimate onion links, is open to forgery, requires the user to recognize the problem and install the extension as it isn't bundled with Tor Browser (TB).

The browser extension has advantages. It doesn't require any message or signal to be sent by the clearweb website nor does it require any traffic to pass through an exit node as the redirect is internal to the UA. The browser extensions can be used to implement the proposed upgrade protocol for sites that are not in its index, or for websites that wish to update their entry in the index. Before a protocol is proposed and ratified the browser extension will be required until all sites roll out the onion redirect protocol.

3. Design Goals

Two classes of solution:

  1. Client directed - client has some knowledge of either upgrade protocol or is preconfigured to check a path, host, record, etc. and redirect internally
  2. Server directed - server redirects the client using either currently supported redirection (HTTP location header) or a new format


  1. Clearweb site messages to Tor capable UA's that an alternate service on onion is available
  2. Message is cached for future visits
  3. Message is sent over an authenticated and secure channel
  4. Message is resistant to tampering, filtering or censorship
  5. Sites which signal alternate service hostnames are potentially preloaded into supporting browsers
  6. Users are redirected with no or little user intervention or promting
  7. Minimize any potential data leaks or correlation attacks where an adversary monitoring exit traffic or entry points can link the clearweb visitor to an onion visitor (how important is this?)
  8. Only top-frame links are rewritten, not embedded or thrd-party content (prevent user tracking using hidden services)
  9. Provide more than one method to signal the protocol upgrade for censorship or filtering resistance

4. Security and Privacy Concerns

  1. Upgrade must take place over an authenticated channel otherwise open the client up to MITM attacks
  2. Embedded content must not redirect - prevent tracking
  3. Correlation attacks when observing traffic
  4. With HTTP requests to onion hostnames the user needs to authenticate the request prior to it being made, so it would require a user prompt. An automatic protocol upgrade may only take place with HTTPS -> HTTPS
  5. Browser plugins have the advantage of not having to request the original clearweb site, so an internal redirect takes place. By caching the redirect it could be 'pinned' in the browser, similar to HSTS. These pins could then be preloaded (which is similar to having a plugin, except the site operators specify the parameters rather than having a single central repository of redirects maintained by an extension developer)

5. Proposals and Implementation Ideas

Example hostnames and URLs:

  • - example clearweb website
  • examplexxxxxxxxx.onion - example alternate service

5.1 HTTP Header in Server Response

  1. Clearweb server returns an HTTP header with a pointer to the onion host
  2. UA parser the header and redirects, attaching the full path

Similar to the implementation of HSTS. Set response header (from tor-talk):

X-Onion-Address: examplexxxxxxxxx.onion

Add paramters such as max-age if caching is considered.


GET / HTTP/1.1
User-Agent: "Mozilla/5.0 (Windows NT 6.1; rv:31.0) Gecko/20100101 Firefox/31.0"
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Encoding: gzip, deflate, sdch

HTTP/1.1 200 OK
Content-Type: text/html
Content-Lenght: 150
X-Onion-Address: examplexxxxxxxxx.onion

<page content>

Tor capable clients parse response header and request examplexxxxxxxxx.onion attaching the relevant path.


  • Simple to implement and maintain for web hosts and for UA's


  • Adds a lot of content that needs to be delivered (AlecMuffett)
  • In most cases of Alt Services would only be relevant to a small percentage of users (as opposed to HSTS which is relevant to all)
  • Would need to be set over HTTPS to prevent MITM attacks

5.2 HTTP Protocol Upgrade Header

HTTP has native support for protocol upgrades


5.x HTML Link Headers

Link in HTML headers

5.x Application Link Protocol

Used in mobile applications

5.x DNS Response

Use TXT or other record with DNSSEC

5.x Known Resource

Client requests a known preshared resource with marked up metadata at site root (per flamsmark):

GET /tor.json HTTP/1.1



  • v0.1 - 6th December 2014 - initial draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment