Skip to content

Add WebTunnel support

Benefits

The benefits are quite clearly described in https://blog.torproject.org/introducing-webtunnel-evading-censorship-by-hiding-in-plain-sight/. tl;dr: obfs4 makes traffic look like fully encrypted & unknown; some censors block that; while WebTunnel makes traffic look like HTTPS traffic, which is allowed in some cases where obfs4 would be blocked.

For example, from #20267 (comment 259159) in May 2025:

Tails users connecting through mobile ISPs in Russia have reported difficulties to connect to Tor.

After some investigations, it seems obfs4 is partially blocked in certain mobile ISPs like T2 and Beeline. Some Tails users are connecting over mobile wifi hotspots. However, Tor Browser users connecting to the same ISPs reported that Webtunnel is working for them.

And from #20267 (comment 259812), in April 2025, Users in China can't connect to Tor using obfs4.

Cost

  • add webtunnel to our ClientTransportPlugin config (the copy of obfs4proxy aka. lyrebird that we take from the TB tarball supports it since https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/issues/41111)
  • adjust the Tor Connection backend to allow entering a webtunnel bridge
  • make it work (maybe it works out of the box, maybe not)
    • anonym has used a WebTunnel bridge successfully in Tails by manually editing torrc in the expected way, so he expects it to work out of the box
  • either test webtunnel with Chutney in our automated test suite, or using the real Tor network, or add to manual QA; expected challenges:
    • How does the Tor Browser team handle this? We're essentially in the same situation.
    • ideal version, using Chutney:
      • Chutney does not support webtunnel currently
      • How can we install, configure, and run the WebTunnel server component in the environments where we run our automated test suite? This seems pretty tricky (https://community.torproject.org/relay/setup/webtunnel/) but perhaps developers of WebTunnel clients or servers have tricks?
        • They're adding support for certificate pinning, so it'll be possible to bypass the requirement of a valid TLS cert.
    • If we end up having to use the real Tor network:
      • mitigate a bonus dose of flakiness, somehow
      • add support for running the full test suite with some scenarios using Chutney and others using the real Tor network
        • anonym wrote "As long as we base those scenarios on a snapshot that hasn't connected with TCA to a Chutney-powered Tor network it should just be a matter of running a step that reverts to the original torrc and default_bridges.txt (so we have to keep them). (If we base it on the usual scenarios I worry there will be subtle issues, and more things to do, like probably nuking /var/lib/tor and maybe resetting TCA some how, I don't know, but I don't like it.)"
    • If we end up adding to manual QA:
      • less robust (developers have to think about doing it when reviewing relevant code updates)
      • increases running costs potentially forever (1 single manual test should be enough)
  • update the Tor Connection UX to reflect the fact we allow entering a WebTunnel bridge manually but the email + QR code way only works for obfs4; we probably have to help the user figure out which kind they need, ideally in the UI, if needed with some support from the doc; chances are this is a bit messy until we do Support automatic bridge retrieval (#15331), but at least we'll allow users who need WebTunnel to use it
  • update the end-user doc
  • update the design doc
  • anything else?

UX

Together with Support Snowflake bridges (#5494).

Fundraising

https://gitlab.torproject.org/tpo/operations/proposals/-/issues/106

Edited by intrigeri
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information