Creating a Snowflake WebExtension addon

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"
        },

Trac:
Username: oarel

added anti-censorship-roadmap component::circumvention/snowflake ex-sponsor-19 owner::arlolra parent::30931 priority::medium reporter::oarel resolution::implemented severity::normal snowflake-webextension sponsor::28-must status::closed tor-pt type::enhancement ux-team labels

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

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

Trac:
Cc: oarel@tuta.io, dcf@torproject.org, arlo@torproject.org to oarel@tuta.io, dcf, arlolra

Trac:
Sponsor: N/A to Sponsor19

Added to ux-team roadmap

Trac:
Keywords: N/A deleted, ux-team added

Trac:

Trac:

Trac:

Trac:

Trac:

Trac:
Cc: oarel@tuta.io, dcf, arlolra to oarel@tuta.io, dcf, arlolra, mcs

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.

 

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.


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 (moved) 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.

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.

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.

Trac:
Keywords: ux-team deleted, ux-team tor-pt added

Trac:
Cc: oarel@tuta.io, dcf, arlolra, mcs to oarel@tuta.io, dcf, arlolra, mcs, antonela, gaba

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.

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

Trac:
Owner: N/A to arlolra
Status: new to assigned

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

Trac:
browser_extension.sketch

Trac:
snowflake-icon.zip

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.

Replying to arlolra:

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

I just started looking at #27385 (moved) 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 (moved) at once?

Replying to cohosh:

I just started looking at #27385 (moved) 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 (moved) 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?

It looks good so far. I like the refactoring changes. If it makes things easier re #27385 (moved), 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.

Replying to dcf:

It looks good so far. I like the refactoring changes. If it makes things easier re #27385 (moved), 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.

Replying to arlolra:

Replying to cohosh:

I just started looking at #27385 (moved) 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 (moved) 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 (moved) 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.

Trac:
Cc: oarel@tuta.io, dcf, arlolra, mcs, antonela, gaba to oarel@tuta.io, dcf, arlolra, mcs, antonela, gaba, cohosh

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 (moved) 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!

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.

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.

Started on the popup in, https://github.com/keroserene/snowflake/commit/7989810eef9dda3263cc946680b8b92b6258b923

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

Trac:
Keywords: ux-team tor-pt deleted, ux-team, ex-sponsor-19, tor-pt added

Moving from Sponsor 19 to Sponsor 28.

Trac:
Sponsor: Sponsor19 to Sponsor28-must

Trac:
Keywords: N/A deleted, anti-censorship-roadmap added

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.

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.

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.

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 (moved) 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)

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

This looks awesome arlo!

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 (moved) 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.

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.

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."

Trac:
Parent: N/A to #30931 (moved)
Status: assigned to closed
Keywords: N/A deleted, snowflake-webextension added
Resolution: N/A to implemented

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."

Done in, https://gitweb.torproject.org/pluggable-transports/snowflake.git/commit/?id=85625e19f923a7f5eac071fcbafd2838525ac3fd

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.

I'm going to file individual task from here on out to avoid licking all the cookies. It would be good if others were familiar with developing the webextension.

hi! could I have an extension build to review the UI?

Replying to antonela:

hi! could I have an extension build to review the UI?

I sent you the current build over email.

Thanks phw!

Some comments:

• The icon is a great way to offer visual feedback to users. I remember we discussed it a bit at https://trac.torproject.org/projects/tor/ticket/27385#comment:8. Using the states described at the comment:35, we have:

1. Gray icon for disabled
2. Purple icon for enabled (waiting)
3. Rotating purple icon for proxying (enabled + transferring). I did the animation with CSS here https://snowfl4k3.glitch.me/.

• The doorhanger can be narrower. 320px is fair enough.
• Could we use the system font? In that way, it will use the client's default. Now, it is loading Times New Roman.
• The copy is great. Although, I think we can iterate over the technical terms in the future.

I'm not sure if re-open this ticket or file a new one.

Thanks antonela! Please file a new ticket with all this issues.

Please publish it on Mozilla's AMO, if it's functional please let us know so I can start publicizing it.

I'm not sure if re-open this ticket or file a new one.

I opened #30962 (moved), let's continue there.

Please publish it on Mozilla's AMO, if it's functional please let us know so I can start publicizing it.

Thanks for your interest. We're still working on getting it published in #30931 (moved)

closed

mentioned in issue #23947 (moved)

mentioned in issue #28917 (moved)

mentioned in issue #29260 (moved)

mentioned in issue #29278 (moved)

mentioned in issue #29857 (moved)

mentioned in issue #30350 (moved)

mentioned in issue #30777 (moved)

mentioned in issue #30931 (moved)

mentioned in issue tpo/community/outreach#30777 (closed)

moved to tpo/anti-censorship/pluggable-transports/snowflake#23888 (closed)