Brainstorm improved ux for orgs that want to give bridges to their people
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 https://trac.torproject.org/projects/tor/wiki/org/meetings/2018MexicoCity/Notes/BridgeDB]
Activity
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.
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).
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: https://trac.torproject.org/projects/tor/ticket/15035
Trac:
Cc: ahf, mcs, brade to ahf, mcs, brade, 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 "https://bridge.torproject.org/config#984ujqw9d82m398end" (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?
-
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:
- potential network traffic
- 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 104.224.78.19:443 FD9DAEE45A2FDF70D462914A75ADE99A29957920 cert=LSOd9qOffpIFM4az+ueou7sY0eQRAsI/joW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA iat-mode=0 bridge://obfs4@104.224.78.19:443/FD9DAEE45A2FDF70D462914A75ADE99A29957920?cert=LSOd9qOffpIFM4az%2Bueou7sY0eQRAsI%2FjoW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA&iat-mode=0 http://bridge.onion/FD9DAEE45A2FDF70D462914A75ADE99A29957920?transport=obfs4&ip=104.224.78.19&port=443&cert=LSOd9qOffpIFM4az%2Bueou7sY0eQRAsI%2FjoW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA&iat-mode=0 https://bridges.torproject.org/FD9DAEE45A2FDF70D462914A75ADE99A29957920?transport=obfs4&ip=104.224.78.19&port=443&cert=LSOd9qOffpIFM4az%2Bueou7sY0eQRAsI%2FjoW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA&iat-mode=0 -
== 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.https://bridges.torproject.org 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
?)**- https://bridges.torproject.org/FD9DAEE45A2FDF70D462914A75ADE99A29957920?transport=obfs4&ip=104.224.78.19&port=443&cert=LSOd9qOffpIFM4az%2Bueou7sY0eQRAsI%2FjoW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA&iat-mode=0
- the browser always sends the Query String to bridges.torproject.org
- default and standard webserver settings will cause the Query String to be logged
"Fragment" (everything after
#)- https://bridges.torproject.org/#FD9DAEE45A2FDF70D462914A75ADE99A29957920?transport=obfs4&ip=104.224.78.19&port=443&cert=LSOd9qOffpIFM4az%2Bueou7sY0eQRAsI%2FjoW4QgCl/LSDo2ecQzAQHNu281oAivLDZuTQNA&iat-mode=0
- the browser does not send the Fragment to bridges.torproject.org by default
- one line of Javascript from the server can fetch the Fragment and send it to the server
- if the browser has Javascript disabled, the Fragment cannot be sent to the server
- since Javascript is required to fetch the Fragment, it is very unlikely to be logged by the webserver
domain name
bridges.torproject.org 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.
-
== Clickability
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
bridge:- 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
http://bridge.onion- 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
https://bridges.torproject.org- 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
-
Microsoft has something like "Android App Links" and "Apple Universal Links": https://blogs.windows.com/buildingapps/2016/10/14/web-to-app-linking-with-appurihandlers/
-
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: https://torproject.gitlab.io/Bridge-URLs 
Trac:
Parent: N/A to #31283 (closed)
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. https://github.com/shadowsocks/shadowsocks/wiki/Generate-QR-Code-for-Android-or-iOS-Clients
Trac:
Username: sigvids-
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. mentioned in issue #28526 (moved)
mentioned in issue #31283 (closed)
mentioned in issue tpo/community/support#28526 (closed)
