Opened 2 years ago

Last modified 6 months ago

#28015 new defect

Brainstorm improved ux for orgs that want to give bridges to their people

Reported by: arma Owned by: tbb-team
Priority: Medium Milestone:
Component: Applications/Tor Browser Version:
Severity: Normal Keywords: ux-team, education, documentation, ex-sponsor-19, s32-o32a2
Cc: ahf, mcs, brade, eighthave, phw, cohosh Actual Points:
Parent ID: #31283 Points:
Reviewer: Sponsor: Sponsor30-must


We have the new moat feature in Tor Browser, which provide a usable way for people in censored areas to fetch bridges from bridgedb. Great.

There's another bridge distribution model though, where an org runs bridges for its own people, and wants to get its custom bridge addresses into their people's tor browsers easily. Like, picture a human rights org wanting to help its own users in a given country.

I can imagine two ways that users might get these bridges with our current software:

(1) via email, and then manually clicking a bunch of things in Tor Browser and pasting the bridges into the right place.

(2) Getting a pre-populated Tor Browser from their org.

The first one is not great from a usability perspective, and the second one is not great from a "we taught them how to check the signatures but now their Tor Browser differs from the one we signed" perspective.

Is there a way in Tor Browser to help improve the usability flow for this goal?

One idea would be to essentially have a cheat code in our moat interface, where if you type in a secret password instead of the captcha solution, you get some secret bridges. We would still be "in the middle" in this scenario.

Another idea would be to make it easy for other orgs to run their own moat, and then add an interface option in Tor Browser to add your own moat url. We probably want some sort of authentication (so the domain name itself doesn't have to stay a secret), and maybe that's done by having a url with both a (fine if the adversary learns it) domain and a (should stay secret) path component.

Maybe there is some brilliant third idea?

We also want to ponder usability for mobile users, e.g. in the world where they get and scan a QR code.

[Ticket created based on discussions in]

Child Tickets

Change History (21)

comment:1 Changed 2 years ago by arma

Keywords: sponsor19 added

comment:2 Changed 2 years ago by gk

Cc: mcs brade added

comment:3 Changed 2 years ago by tom

Your ideas were the first that came to my mind. I wracked my brain for a little bit trying to come up with additional ones.

Ideas of varying quality:

Instead of 'via email, and then manually clicking a bunch of things in Tor Browser and pasting the bridges into the right place' - make this a supported flow where on copy/pastes a big blob of base64 and Tor Browser decodes and parses it and does all the right things.

Orgs distribute a symmetric key that decrypts an encrypted blob baked into the browser. This contains some or all of: a passphrase used to get secret bridges from our moat, the location of their moat, or even new default bridges. (This could be used by Tor Projects direct user support to test connection failures also, by having a few of our own secret bridges)

Org distributes an 'add-on pack' (but not a browser add-on in that sense, just the generic definition of 'supplemental') that one installs on top of tor browser that contains *something*. A new moat url, new default bridges, etc. The 'add-on pack' might be as simple as a specially named json file Tor Browser looks for in its startup process. You could even encrypt it by default with a passphrase Tor browser prompts you for on startup if you really wanted to?

Orgs could distribute a true browser add-on one installs over Tor Browser that alter's Tor Browser's behavior in the same sense of a Mozilla Partner Repack (as we call them): it could supply bridge info, but also theme the browser, add a default homepage, bookmarks, even add-ons. (Or maybe not add-ons :) ) I think Psiphon did this as a funding mechanism also.

Tangential: a 'secret passphrase with a public moat URL' approach could also have two other authentication mechanisms besides a high-entropy passphrase: a TOTP based token o a WebAuth/FIDO USB Key.

comment:4 Changed 2 years ago by pili

Sponsor: Sponsor19

comment:5 Changed 2 years ago by arma

Nathan tells me that in Orbot-land, Orbot hooks the "bridge://" url, so you can get a bridge address in your email or signal or instant messaging or web page or whatever, and click on it, and Orbot will intercept the click and populate your bridge configuration for you.

It's not immediately clear how to make use of this idea on Tor Browser Desktop, but it's another data point to consider (and it opens up a lot of new options on Android).

comment:6 Changed 2 years ago by gaba

Keywords: education documentation added; sponsor19 removed

comment:7 Changed 22 months ago by eighthave

Cc: eighthave added

One important part of this is working out an easy to use URL setup that works on all platforms. We've done a bunch of work on this for ChatSecure. Here's the thread on doing it for bridges:

comment:8 Changed 22 months ago by eighthave

It should be pretty straightforward to use "bridge://" URLs on desktop platforms. I only vaguely know Windows, but I've done this kind of thing on GNOME things and on Mac OS X over the years. Both have a system-wide place to register apps that handle certain URL schemes. So Tor Browser would just need to register itself to handle "bridge://" then receive it somewhere, and parse it. It should probably also bring up the bridge config UI after receiving such a link.

The trickier case to handle in Tor Browser is perhaps the case where there is a bridge URL with an "https://" scheme. Of course, all platforms will direct that to the browser, but only Android can provide strict matching of something like "" (perhaps iOS also, but I don't know the details there). Then the question is: if Tor Browser receives such a URL, is it appropriate for it to intercept that URL and show the bridge config UI instead of the web page?

comment:9 Changed 21 months ago by eighthave

I did a deep dive into the URL formats in #15035 and want to now outline the ramifications of the various URL schemes. In terms of UX, the two differentiating criteria are:

  1. potential network traffic
  2. widespread clickability

There are unfortunately no clear winners in terms of URL formats, so we'll need to figure out which to use depending on the use case and threat model. I think it will be possible to mostly hide the use of different URL formats from the user, since mostly, the aim is the have the URL something that the user just receives and clicks on, then the rest happens magically.

The examples below are based on this bridge config, represented first by a "Bridge" line from torrc, then in three possible URL formats:

Bridge obfs4 FD9DAEE45A2FDF70D462914A75ADE99A29957920 cert=LSOd9qOffpIFM4az+ueou7sY0eQRAsI/joW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA iat-mode=0

comment:10 Changed 21 months ago by eighthave

Network Traffic

The different URL formats can directly cause network traffic. If a user clicks on an HTTP link with a valid domain name, that will go to a browser, and try to load a page. Any URL format could indirectly cause network traffic, e.g. an app could accept a bridge: URL and then send the traffic itself to the network. That is out of scope here, since there is nothing we can do about it within the URL format and the code that generates and accepts these URLs. is the one format as laid out in #15035, that can cause network traffic. We do have a little control over what data is sent to the network:

"Query String" (everything after ?)

"Fragment" (everything after #)

domain name is a regular domain name and will automatically resolve if a browser loads the URL. For bridge.onion, a generic browser might try to resolve the .onion part of the domain name. Most DNS queries these days also include the full domain name in all queries, e.g. bridge.onion when asking for the DNS server for .onion. On the other hand, since search queries are typed into the browser's URL field, search strings are sometimes treated as domain names and queried in DNS servers.

Last edited 21 months ago by eighthave (previous) (diff)

comment:11 Changed 21 months ago by eighthave


The goal of a clickable bridge URL is that the user can just click/touch a URL, and the bridge config data will be routed to the right place automatically. Given two URL formats, bridge URLs can be clickable everywhere where URLs are clickable. The hard part about clickability is that there is no single URL format that will be clickable in all places, with the possibility of having it be automatically directed to the right app (e.g. Tor Browser). Here are some


  • web pages in desktop browsers
  • in all iOS apps that use the system's link definitions, where apps can register custom schemes
  • in Android and desktop apps that have specifically enabled linkifying them


  • any mobile app (though there might be an additional chooser prompt)
  • in browsers on Android
  • "Android App Links" and "Apple Universal Links" can make these work more directly

  • any mobile app (though there might be an additional chooser prompt)
  • in browsers on Android
  • "Android App Links" and "Apple Universal Links" can make these work more directly
  • can have a webpage with a bridge: URL to redirect user better, using either a Query String or fetching the Fragment with Javascript
Last edited 21 months ago by eighthave (previous) (diff)

comment:12 Changed 21 months ago by eighthave

Microsoft has something like "Android App Links" and "Apple Universal Links":

comment:13 Changed 21 months ago by eighthave

I made a test page with a bunch of these different kinds of links, including the Javascript parsing of the Fragment to make the bridge: URL:

comment:14 Changed 18 months ago by gaba

Keywords: ex-sponsor-19 added

Adding the keyword to mark everything that didn't fit into the time for sponsor 19.

comment:15 Changed 18 months ago by phw

Sponsor: Sponsor19Sponsor30-must

Moving from Sponsor 19 to Sponsor 30.

comment:16 Changed 17 months ago by phw

Cc: phw added

comment:17 Changed 16 months ago by pili

Parent ID: #31283

comment:18 Changed 14 months ago by gaba

Keywords: s32-o32a2 added

comment:19 Changed 11 months ago by sigvids

Shadowsocks (SS) uses a pseudo-URL constructed from the base-64 encoded parameters. This is then displayed as a QR code that can be scanned by desktop and mobile SS applications.

comment:20 Changed 11 months ago by eighthave

Thanks for that URL, good to know. A custom URL format for QR Codes is quite useful since you can make the QR Code a lot smaller. But ss://bWV0aG9kOnBhc3N3b3JkQGhvc3RuYW1lOnBvcnQ= would not work elsewhere since it would not be clickable in any Android or iOS app e.g. in a message or email. Same with most Desktop software.

comment:21 Changed 6 months ago by cohosh

Cc: cohosh added

cohosh cc'ing myself on sponsor 30 work

Note: See TracTickets for help on using tickets.