Opened 20 months ago

Last modified 5 days ago

#23888 assigned enhancement

Creating a Snowflake WebExtension addon

Reported by: oarel Owned by: arlolra
Priority: Medium Milestone:
Component: Circumvention/Snowflake Version:
Severity: Normal Keywords: ux-team, tor-pt, ex-sponsor-19, anti-censorship-roadmap
Cc: oarel@…, dcf, arlolra, mcs, antonela, gaba, cohosh Actual Points:
Parent ID: Points:
Reviewer: Sponsor: Sponsor28-must

Description

The idea is to create a WebExtension that allows one to become a Snowflake bridge by just installing it. That way it only suffices to install an extension and forget about it, unlike the approach of keeping a tab always open with the snowflake JS code.

Since it's based on WebExtensions it can be easily deployed for other browsers in their addon store.

I did try to make one myself but I don't have the expertise and time to debug all the problems that resulted. One of the important take aways that I learned in that process was that automatically loading scripts from external sites is prohibited and will result in the addon not passing the review in the addon store, so the snowflake.js and modernizr.js should be embedded with the addon. However, this would require modifying snowflake.js since when it's loaded locally it throws some typeError and doesn't show that there's some connection to snowflake.bamsoftware.com in the browser console. For debugging, to verify that the addon works as intended one may load it from about:debug and check about:networking in the DNS and WebSockets part.

For the implementation these resources should be loaded in the background to ensure a permanent state with this in the manifest.json,

"background": {
                "page": "pages/Snowflake.html"
        },

Child Tickets

Attachments (7)

concept1.jpg (957.6 KB) - added by antonela 6 months ago.
concept2.jpg (783.0 KB) - added by antonela 6 months ago.
00.png (39.4 KB) - added by antonela 6 months ago.
01.png (40.1 KB) - added by antonela 6 months ago.
00.01.png (42.3 KB) - added by antonela 6 months ago.
browser_extension.sketch (1.8 MB) - added by antonela 7 weeks ago.
snowflake-icon.zip (76.3 KB) - added by antonela 7 weeks ago.

Change History (42)

comment:1 Changed 20 months ago by arlolra

Cc: dcf arlolra added; dcf@… arlo@… removed

Thanks for your effort here. We've been discussing something like this in #20813

There's a fairly successful browser extension that's in the process (hopefully) of being converted to use snowflake in,
https://github.com/glamrock/cupcake/issues/24

comment:2 Changed 7 months ago by pili

Sponsor: Sponsor19

comment:3 Changed 6 months ago by antonela

Keywords: ux-team added

Added to ux-team roadmap

Changed 6 months ago by antonela

Attachment: concept1.jpg added

Changed 6 months ago by antonela

Attachment: concept2.jpg added

Changed 6 months ago by antonela

Attachment: 00.png added

Changed 6 months ago by antonela

Attachment: 01.png added

Changed 6 months ago by antonela

Attachment: 00.01.png added

comment:4 Changed 6 months ago by mcs

Cc: mcs added

comment:5 Changed 6 months ago by antonela

Hey, I hand-made some wireframes to explore some ideas around this web extension. With this web extension, users will have the option to enable/disable snowflake. You can see them here:

https://trac.torproject.org/projects/tor/raw-attachment/ticket/23888/concept1.jpg
https://trac.torproject.org/projects/tor/raw-attachment/ticket/23888/concept2.jpg

If this extension is a browserAction kind of extension, we should have a toolbar button with a popup. If that is the case, users will be able to enable webRTC globally.

In this scenario, the user will enable snowflake in global settings and users will not get informed when snowflake is transferring.

https://trac.torproject.org/projects/tor/raw-attachment/ticket/23888/00.png
https://trac.torproject.org/projects/tor/raw-attachment/ticket/23888/01.png

A second option could be having this extension working per site as a pageAction extension. Then, when the user visits a website which has webRTC available, the snowflake icon appears at the right side of the URL Bar and when it is transferring turn into violet. On first time use, if webRTC is not enabled, we should prompt the Control Center doorhanger to allow users to enable webRTC.

https://trac.torproject.org/projects/tor/raw-attachment/ticket/23888/00.01.png

Another option could be having both described above, running together. Here, the user can enable/disable snowflake globally on about:extensions. And, when webRTC is active in a site, then we can show the snowflake icon at the URL bar.

We could have Advanced Settings at the Extension Options page. There we can allow users to set some preferences about "how much of my bandwidth I want to give to snowflake" and another type of advanced network settings.



I think we can keep this idea raised in #27385 about to having the rotational motion on the snowflake when it is running.


I think that showing the number of peers connected to the bridge is rewarding for the user who is enabling the bridge. I also know that it is not possible now, but we can keep this in mind for later.


I think the snowflake icon should work better at small sizes. If you like to have that icon idea, I'll give it another round of work to synthesize the lines when it works small.

Next step for me is iterate over this mockups. Once we have defined how this extension will work, I'll create a prototype to see how the user flow works.

Last edited 6 months ago by antonela (previous) (diff)

comment:6 Changed 6 months ago by saint

As arlolra mentioned, after some discussion and delays, snowflake is to be included in Cupcake as a replacement for flashproxy. There are other roadmap items, but those are pushed back pending funding. Cupcake has ~4000 users on Chrome, and a few dozen on Firefox (which needs to be rewritten).

Currently, when flashproxy is active, the cupcake becomes a happy cupcake with eyes and a mustache. I did a lot of user testing with movement and soft/subtle gradient shifts, but unfortunately they all proved too distracting to end-users. The mustache is just enough of a change to be noticeable but not enough to steal focus from page content. So for snowflake, a color change would probably work better than a rotation.

comment:7 Changed 6 months ago by saint

Discussion ongoing at $dayjob about potentially placing a Snowflake snippet onto one of our most popular sites. So if you wanted to turn the changes above into a smaller form factor for the website badge, that would look pretty great. 👍

comment:8 Changed 6 months ago by gaba

Keywords: tor-pt added

comment:9 Changed 6 months ago by gaba

Cc: antonela gaba added

comment:10 in reply to:  6 Changed 6 months ago by antonela

Replying to saint:

As arlolra mentioned, after some discussion and delays, snowflake is to be included in Cupcake as a replacement for flashproxy. There are other roadmap items, but those are pushed back pending funding. Cupcake has ~4000 users on Chrome, and a few dozen on Firefox (which needs to be rewritten).

Wow that's awesome!

So for snowflake, a color change would probably work better than a rotation.

Yes, the main idea is having both: When it is disabled is grey, when it is enabled is violet and when it is enabled with clients, then we can add the rotation.

comment:11 Changed 5 months ago by cohosh

Here are some links to MassBrowser, a project by a University of Massachusetts research group on Browser-based proxies. I don't think it's a web extension, but some of the features available to proxies (being able to decide how much bandwidth to provide, what kinds of exit traffic to support, etc.) would be interesting to look into as features for the web extension.

Website (looks like their cert is bad): https://massbrowser.cs.umass.edu/

Technical report: https://web.cs.umass.edu/publication/docs/2018/UM-CS-2018-005.pdf

  • the most relevant section is probably Content Whitelisting

Code: https://github.com/SPIN-UMass/MassBrowser

comment:12 Changed 8 weeks ago by arlolra

Owner: set to arlolra
Status: newassigned

comment:13 Changed 7 weeks ago by arlolra

Here's a branch that starts on this,
https://github.com/keroserene/snowflake/commits/webext

Changed 7 weeks ago by antonela

Attachment: browser_extension.sketch added

Changed 7 weeks ago by antonela

Attachment: snowflake-icon.zip added

comment:14 Changed 6 weeks ago by arlolra

Thanks for attaching those assets. I pushed a few more commits that make use of them to display the on/off state in the browser icon.

comment:15 in reply to:  13 ; Changed 6 weeks ago by cohosh

Replying to arlolra:

Here's a branch that starts on this,
https://github.com/keroserene/snowflake/commits/webext

I just started looking at #27385 as well. I noticed you're making changes in the /proxy directory of snowflake.git. Was the plan to tackle both this ticket and #27385 at once?

comment:16 in reply to:  15 ; Changed 6 weeks ago by arlolra

Replying to cohosh:

I just started looking at #27385 as well. I noticed you're making changes in the /proxy directory of snowflake.git. Was the plan to tackle both this ticket and #27385 at once?

No, I can look into that after if you want.

My plan was to reuse, wherever possible, the same code for both the badge and the webextension, which inevitably means some refactoring will touch other files in proxy/.

If you're going to do that simultaneously, maybe I should merge what I have so far and we can coordinate a tighter review timeline so there are less conflicts?

comment:17 Changed 6 weeks ago by dcf

It looks good so far. I like the refactoring changes. If it makes things easier re #27385, I'm fine with merging what's been changed so far.

I built the WebExtension by running cake.coffeescript webext in the proxy directory. Then I loaded it into Firefox by going to about:debugging, clicking "Load Temporary Add-on", and selecting manifest.json.

The browser console (Ctrl+Shift+J) shows a couple of warnings that I don't immediately know how to interpret, and also text showing that tmp.js isn't working to set the opt-in cookie.

1557301394666	addons.webextension.280b152ec6e19b8aec7a29eebdd1af8e61a85964@temporary-addon	WARN	Loading extension '280b152ec6e19b8aec7a29eebdd1af8e61a85964@temporary-addon': Reading manifest: Error processing background.persistent: Event pages are not currently supported. This will run as a persistent background page.
1557301394692	addons.webextension.280b152ec6e19b8aec7a29eebdd1af8e61a85964@temporary-addon	WARN	Please specify whether you want browser_style or not in your browser_action options.
Snowflake: == snowflake proxy ==
Snowflake: Not opted-in. Please click the badge to change options.
Snowflake: Currently not active.

It works for me in Chromium. I seem to remember that the cookie thing is one of the incompatibilities between Firefox and Chromium. I remember encountering this problem when I spent a little time trying to hack together a WebExtension, but I don't remember if I figured it out or not. One thing to try would be cookies.set with a url from runtime.getURL. Of course, if you're planning to refactor the opt-in so that the WebExtension doesn't even need a cookie to work, that's better.

comment:18 in reply to:  17 Changed 6 weeks ago by arlolra

Replying to dcf:

It looks good so far. I like the refactoring changes. If it makes things easier re #27385, I'm fine with merging what's been changed so far.

Ok, I merged the changes so far, ending in https://gitweb.torproject.org/pluggable-transports/snowflake.git/commit/?id=e7f3ade06827f6501333f986661ed7aa4277946e

Of course, if you're planning to refactor the opt-in so that the WebExtension doesn't even need a cookie to work, that's better.

Yes, that will be the next thing I do. Split up the initialization so that the badge/node/webextension build their own. Thetmp.js was just a hack to get things started.

comment:19 in reply to:  16 ; Changed 6 weeks ago by cohosh

Replying to arlolra:

Replying to cohosh:

I just started looking at #27385 as well. I noticed you're making changes in the /proxy directory of snowflake.git. Was the plan to tackle both this ticket and #27385 at once?

No, I can look into that after if you want.

My plan was to reuse, wherever possible, the same code for both the badge and the webextension, which inevitably means some refactoring will touch other files in proxy/.

If you're going to do that simultaneously, maybe I should merge what I have so far and we can coordinate a tighter review timeline so there are less conflicts?

Thanks for the merge! If you think you can make the changes for #27385 easily in a way that will match the WebExtension and it sounds like a fun task please feel free to do so. I can help out here but it will also take me longer to get up to speed with how the coffeescript proxy works.

There are other things like setting it up for localization that I can work on once the UI is set :)

Also in case you're interested: I set up a way to test the browser-based proxy in snowbox: https://github.com/cohosh/snowbox/commit/6775554566b71325b5716a4794529f5a686cc403
You probably already have a good setup but I found this useful for not having to install coffeescript on my host machine.

comment:20 Changed 6 weeks ago by cohosh

Cc: cohosh added

comment:21 in reply to:  19 ; Changed 6 weeks ago by arlolra

Replying to cohosh:

Thanks for the merge!

There's a bunch more refactoring again in that branch,
https://github.com/keroserene/snowflake/commits/webext

It's getting closer to a point where there's a cleaner separation between what's library code and what's necessary for each of the use cases.

If you think you can make the changes for #27385 easily in a way that will match the WebExtension and it sounds like a fun task please feel free to do so. I can help out here but it will also take me longer to get up to speed with how the coffeescript proxy works.

Ok, I'll try and tackle that next.

There are other things like setting it up for localization that I can work on once the UI is set :)

Also in case you're interested: I set up a way to test the browser-based proxy in snowbox: https://github.com/cohosh/snowbox/commit/6775554566b71325b5716a4794529f5a686cc403
You probably already have a good setup but I found this useful for not having to install coffeescript on my host machine.

Neat, I'll give it a look, thanks!

comment:22 in reply to:  21 ; Changed 5 weeks ago by cohosh

Replying to arlolra:

Replying to cohosh:

Thanks for the merge!

There's a bunch more refactoring again in that branch,
https://github.com/keroserene/snowflake/commits/webext

It's getting closer to a point where there's a cleaner separation between what's library code and what's necessary for each of the use cases.

Sorry this took so long, it looks good and I verified that the snowflake proxy still works as expected.

comment:23 in reply to:  22 Changed 5 weeks ago by arlolra

Replying to cohosh:

Sorry this took so long, it looks good and I verified that the snowflake proxy still works as expected.

No problem. I rebased and merged those patches.

comment:25 Changed 2 weeks 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:26 Changed 2 weeks ago by phw

Sponsor: Sponsor19Sponsor28-must

Moving from Sponsor 19 to Sponsor 28.

comment:27 Changed 7 days ago by gaba

Keywords: anti-censorship-roadmap added

comment:28 Changed 7 days ago by cohosh

We now have a final deadline (July 26) for getting this done in time for Roger's Defcon talk from which we will try to get volunteers.

@arlolra: do you have a good idea of when you'll be able to work on this? I'm happy to jump in and help if you're running low on time, but I don't want to step on your toes.

comment:29 Changed 7 days ago by arlolra

do you have a good idea of when you'll be able to work on this?

I will have lots of time starting July 1, leading up to the meeting in Stockholm. Before then I will continue to make steady progress though ... but keep me honest about that.

I'm happy to jump in and help if you're running low on time, but I don't want to step on your toes.

It would be helpful if you tried it out in its current state and provided feedback.

comment:30 in reply to:  29 Changed 6 days ago by phw

Replying to arlolra:

It would be helpful if you tried it out in its current state and provided feedback.


I installed the extension (based on commit 7989810) in Firefox 67.0.2. The snowflake icon shows up in my toolbar but it keeps saying "Offline."

In the browser console, I see the following:

1560530472019	addons.xpi	WARN	Addon with ID 494b27b305cec4fbca825a9f4cca849518e73f41@temporary-addon already installed, older version will be disabled
Snowflake: == snowflake proxy == snowflake.js:1134:13
Snowflake: Using snowflake.bamsoftware.com:443 as Relay. snowflake.js:1134:13
Snowflake: ProxyPair Slots: 1 snowflake.js:1134:13
Snowflake: Snowflake IDs: 6r3t6xpg4g8 snowflake.js:1134:13

XML Parsing Error: no root element found
Location: https://snowflake-broker.bamsoftware.com/proxy
Line Number 1, Column 1: proxy:1:1

XML Parsing Error: no root element found
Location: https://snowflake-broker.bamsoftware.com/proxy
Line Number 1, Column 1: proxy:1:1

XML Parsing Error: no root element found
Location: https://snowflake-broker.bamsoftware.com/proxy
Line Number 1, Column 1:

...

I could also install the extension in both Chromium and Google Chrome but my icon says "Offline" there as well.

comment:31 Changed 6 days ago by arlolra

The snowflake icon shows up in my toolbar but it keeps saying "Offline."

That just means that no client is connected. See the mockups in comment:5

Until #25601 is implemented, it's a binary state.

But, this has been a useful exercise since clearly the messaging needs improvement.

In the browser console, I see the following:

That's the 504 returned from the broker.

You'll see the same thing on https://snowflake.torproject.org/embed.html (assuming you've accepted the cookie)

comment:32 Changed 6 days ago by cohosh

I just got it to work and made a bunch of snowflake client connections locally to trigger the connected state.

This looks awesome arlo!

comment:33 in reply to:  31 Changed 6 days ago by cohosh

Replying to arlolra:

The snowflake icon shows up in my toolbar but it keeps saying "Offline."

That just means that no client is connected. See the mockups in comment:5

Until #25601 is implemented, it's a binary state.

But, this has been a useful exercise since clearly the messaging needs improvement.

Were there plans to have another state to indicate that the proxy is polling for clients and therefore ready to accept them? As a user it is a bit confusing to see the "offline" state and wonder whether I'm in a position to be useful or whether I need to enable something.

comment:34 Changed 6 days ago by arlolra

Were there plans to have another state to indicate that the proxy is polling for clients and therefore ready to accept them?

The mockup has a "Turn Off/On" toggle that I've yet to implement. That's next up.

As a user it is a bit confusing to see the "offline" state and wonder whether I'm in a position to be useful or whether I need to enable something.

I will change the verbiage to just say, "x clients connected" based on this feedback.

If you have other suggestions, or features you'd like to see, let me know.

Something to start thinking about is setting up the credentials / process necessary to distribute the extension.

comment:35 in reply to:  31 Changed 5 days ago by phw

Replying to arlolra:

But, this has been a useful exercise since clearly the messaging needs improvement.


As a semi-ignorant user, I would expect the icon to take on one of three states:

  • Disconnected, meaning that my proxy isn't able to talk to the broker.
  • Waiting, meaning that my proxy is able to poll the broker and waiting for clients.
  • Proxying, meaning that I'm currently serving a client.

The ability to toggle between Disconnected and Waiting sounds reasonable.

I think we should also let the user know how useful their proxy has been. Maybe something along the lines of "Your snowflake helped X users circumvent censorship in the last 24 hours."

Note: See TracTickets for help on using tickets.