Tor at the Heart: Onion Browser (and more iOS Tor)

by mtigas | December 6, 2016

During the month of December, we're highlighting other organizations and projects that rely on Tor, build on Tor, or are accomplishing their missions better because Tor exists. Check out our blog each day to learn about our fellow travelers. And please support the Tor Project! We're at the heart of Internet freedom.
Donate today!

Onion Browser

Onion Browser is an open-source iOS web browser that connects to Tor. The app has been available in the Apple App Store since 2012; it was previously $0.99 but recently became free of charge. You can download it in the App Store here and access the source code on GitHub.

In addition to Tor support, Onion Browser features an experimental NoScript-like mode, user agent spoofing, and (since August) support for obfs4 and meek bridges.

It’s primarily developed by Mike Tigas, who works as a developer and investigative journalist at ProPublica by day. (Did you know? ProPublica is one of the first major news sites to be available via an onion sitepropub3r6espa33w.onion) The app is an independent community project and is supported by Patreon backers and other donors (read more about supporting Onion Browser here), with some key support also coming from the Guardian Project.

Onion Browser isn’t the prettiest app, lacking features like tabbed browsing, and it is starting to show it’s age a bit. But it still receives regular security updates and a new user interface is actively being developed (discussed in full below).

Challenges on iOS

Tor hasn't been well-represented on iOS over the years for a variety of reasons, mostly due to system peculiarities on the iOS platform. And although there’s a version of Firefox for iOS, several challenges prevent the interoperability that Tor developers are accustomed to on other platforms.

The most glaring restriction on iOS is that you're not allowed to fork subprocesses. Tor must be compiled into the app binary and hacked to run as a thread inside the app process to work on iOS. Among other things, this means that a system-wide Tor app, like Orbot on Android, is simply not possible on the platform. (At least, not yet: read about iCepa below!) And simply relying on another app’s Tor instance — as some tools do with Tor Browser Bundle — also doesn’t work on iOS, since all of an app’s functionality is halted soon after a user switches out of the app.

Even after solving the problem of just getting Tor to run, several other quirks prevent a lot of the functionality of Tor Browser (or even Orfox) from being easily reimplemented on iOS:

  • You're not allowed to implement your own browser engine and must use the WebKit framework built into the operating system. This separates Onion Browser from Tor Browser and Orfox, which are browsers based on Firefox Gecko. (On the other hand, this inadvertently made Onion Browser immune to the Firefox vulnerability targeting Tor Browser users last week.)
  • Only the older WebKit API (UIWebView) allows control over the SOCKS settings of the browser stack, so that we can configure it to use Tor. The newer framework (WKWebView) always uses your system proxy settings and can’t be reconfigured by an app at runtime. The APIs also contain vastly different functionality so that it's not always possible to convert code relying on one API to use the other. Firefox for iOS uses the newer WKWebView framework, which unfortunately means that much of the work on Firefox for iOS is quite difficult to use in a Tor-supporting iOS browser.
  • The WebKit APIs don’t allow a lot of control over the rendering and execution of web pages, making a Tor Browser-style security slider very difficult to implement. Many multimedia features on iOS also bypass the browser network stack — in particular, the iOS video player doesn’t use the same network stack as WebKit and therefore any browser action that launches the native video player may possibly leak traffic outside of Tor. Onion Browser tries to provide some functionality to block JavaScript and multimedia, but these features aren’t yet as robust as on other platforms.

iOS developments in the community

Despite the challenges, there are quite a few positive developments on the horizon — both around Onion Browser and the larger Tor iOS landscape.

Endless is an open source browser for iOS that uses the older UIWebView API and thus can be modified to support Tor. It adds a lot of important features over the existing Onion Browser, like a nicer user interface with tabbed browsing, HTTPS Everywhere, and HSTS Preloading. There’s a new version of Onion Browser in the works that’s based on Endless that will hopefully enter beta testing this month.

The NetworkExtension framework introduced in iOS 9 allows writing custom VPN software that the iOS system can use. A small coalition of Tor iOS developers are working on a tool called iCepa to use this framework to provide a Tor VPN to the entire phone — similar to the VPN mode of Orbot on Android. The framework was introduced with a tiny 5MB memory limit — which wasn’t enough to run both Tor and the controller app. But the memory limits have been increased to usable levels in iOS 10 and Conrad Kramer, the lead iCepa developer, has been making a bit of progress in recent months.

There’s also work ongoing work to make Tor easier to implement in other apps, like Tor.framework and CPAProxy. ChatSecure for iOS uses CPAProxy to power encrypted XMPP instant messaging over Tor, and the next version of Onion Browser uses Tor.framework rather than a custom solution. Onion Browser’s obfs4/meek support comes from another similar reusable framework called iObfs. Reusable pieces like this will hopefully encourage more developers to work on iOS software that supports Tor.


Please note that the comment area below has been archived.


December 06, 2016


Thanks Mike!

So it sounds like having some variant of Firefox on iOS is still really far out -- which means that porting Tor Browser to it (like Orfox on Android) isn't going to be feasible in the short or mid term either, which means that we'll be missing all the application-level privacy features that Tor Browser provides:

A) Can you give us your sense of whether Apple will ever change its position there? Should we just give up on Firefox on iOS, or are there upcoming shifts inside Apple that might change things?

B) "Endless" sounds neat. Can you give us your guesses about how close it could reasonably become to the protections provided by Tor Browser? I'm thinking of more complicated things like per-domain isolation of browser state, rather than the simple things like "throws away cookies at exit".

The consensus seems to be that the "system WebKit only" policy is fairly set in stone.

In terms of allowing the newer WebKit APIs to allow some control over the network stack (so we can patch it to use Tor), there’s been a little bit of lobbying (mostly via tickets) to regain some of that functionality.

The older UIWebView API allowed _full_ control to intercept and modify requests from the app -- which allows apps to do things like rewrite content or inject javascript into loaded pages. I’ve heard a rumor that there’s some hesitation to provide that much control in the new API due to concerns that some developers have been using the old API’s full access to inject their own tracking javascript to web views within their apps (though I haven’t myself verified these claims).

Browser state isolation is a tricky problem since we’re limited to what we can accomplish with the built in WebKit APIs.

  • We do have full control over the headers and body content of requests, so we can easily filter out Cookie headers and handle things like that (and possibly do some content filtering for other things)
  • We do get access to where caches (including HTML5 localStorage) are stored on disk.
  • But some of these non-cookie features, like HTML5 localStorage, are more difficult to pin down since script-based features take place within WebKit and we don’t generally have access to customize what they do. There’s some internal shared state across all web views (i.e. "browser tabs") within an app as well (the internal cookie handler is a singleton), which may have some ramifications as well.

Our isolation options are essentially limited to what we can control from the network stack (in terms of content processing and filtering) and via access to disk storage and browser cache.

In terms of other protections, there are some hidden options to the UIWebView that allow disabling JavaScript some other multimedia features, controlling hardware acceleration on <canvas> elements, and a few other things like cache size. Combining those with our control of the network stack (since we can do things like inject Content-Security-Policy headers to all incoming HTTP responses to coerce WebKit into disabling things like remote fonts & etc) we can get some of the way toward a "Security Level" slider like in Tor Browser.

However, since we lack control over a great portion of the rendering engine, the number of things we can protect against is always going to be a _lot_ more limited than on other platforms.

December 06, 2016


Thank you so much for all of your work! Mobiles aren't the safest but bringing Tor to mobiles is a very critical step in blowing up the anonymity set. Thank you!

December 06, 2016


Thanks so much for all that you do; I'm going to encourage my friends with iOS devices to use Onion Browser instead of Firefox.

Yes, we disabled that part of the blog because it opened users up to cross-site attacks. Our blog software is obsolete. We're in the process of fixing that but we're not there yet. Sorry that the duct tape is showing, but at least some of the duct tape is still sticky. :)

December 13, 2016


It so much work to do.It going to be a long trip but I wish you good luck. When you are going to finally make the app please use the classic onion icon that Tor browser looks interesting

December 13, 2016


I downloaded The onion browser for Ios but I don't know what to say about the needs some work in terms or design and functionality.
In the app store is another browser called Vpn using tor and has more functions and a better design but I don't know if the app is trustfull because of the developer (Art Fusion). I need an advice. This app is safe or not?

December 27, 2016


I don't think anyone needs Apple torbrowser because anyone needeng privacy won't use iOS because it has built-in surveillance. Anyone using Apple devices and OSes is Tim Cook's anal slave.

First of all, that's not an insult. Plenty of people enjoy anal sex, along the entire gender spectrum. So it makes no sense to mention it unless you're homophobic. Tim Cook is also gay so is that why? Get off it.

Segundo, yes, iOS is bad not good. But that doesn't mean that we should abandon the dawgs money who be illin wit dat. Sheeeeet. Everyone deserves access to freedom, not just those of us who use GNU and free systems. Are you also against Tor on Windows?

The bottom line is that we can either be traitors who refuse to meet people where they are, like the moron who tried to tell me no one is "stuck" using proprietary garbageware, or we can be decents who try to help people in a plurality and diversity of ways.

January 18, 2017


A small coalition of Tor iOS developers are working on a tool called iCepa to use this framework to provide a Tor VPN to the entire phone — similar to the VPN mode of Orbot on Android.

But, unlike on Android, it doesn't have the ability to apply the VPN in a per-app manner. Apparently, Apple in all their infinite wisdom decided that particular feature should only apply to MDM'd iDevices, which instantly alienates the vast majority of iOS users. Sending all your app traffic through Tor is a Really Bad Idea. You think the iOS video player leaks data? What about every logged-in account on that device betraying your identity to anyone sniffing around an exit node?