Introducing Capacitor-Tor: A Capacitor plugin for integrating Tor into Ionic Apps

If you’ve been following Start9 Labs at all for the last year, you’ll have noticed we talk a lot about Tor. For a company obsessed with individual sovereignty on the internet, Tor is a natural fit; it allows for anonymous and private communications between online parties. The Tor Project — a non-profit devoted to the maintenance and improvement of the Tor network — has done excellent work in improving the network since 2006, including the official and easy-to-use Tor Browser. (Please download it if you haven’t already!) But despite all of this work, Tor is still not particularly common across the internet landscape. Growth has been in large part hindered by the technical challenges of making Tor available to mobile applications.

If the internet can be described as the ‘cloud’, one might imagine the Tor network as a dense fog; the moment communications enter the fog, they become entirely obscured. Unfortunately, entrance to the fog is no small technical challenge, and is done by running what’s called an “onion proxy”. Here, the term ‘onion’ refers to the many layered encryption protocol which secures communications within the Tor network, while ‘proxy’ can be thought of as a doorway or portal to the network. These onion proxies accept unobscured information on one side and release that information into the obscuring Tor network on the other.

Apps have so far been written for both iOS and Android devices which create onion proxies on the phones themselves. But, so far, the onion proxy code has been written bespoke to each platform and each specific app which desires Tor connectivity. In other words, there is no reusable and general-purpose onion proxy solution which can be used by either platform and any app. Any mobile developer who wants Tor for their app needs to tackle the difficult onion proxy problem themselves. Few bother.

Until today, there has been no easy to use and cross-platform technology for mobile app developers to bring Tor into their mobile applications.

Start9 Labs is proud to introduce the open-source Capacitor-Tor Ionic plugin. Ionic, a brilliant and massively popular tool for developing hybrid mobile apps that run on both iOS and Android, can now be easily augmented with the Capacitor-Tor plugin to bring the Tor network into any mobile app for both platforms. Here’s how it works.

Building and communicating through an onion proxy requires low level access to iOS and Android capabilities. When such capabilities are required, Ionic utilizes Capacitor, a framework which opens up bits of native functionality to the Ionic app via Capacitor “plugins”. There are plugins for interacting with the phone’s keyboard and camera. And now, there is a plugin for interacting with a Tor onion proxy.

Capacitor-tor is installed according to the Capacitor plugin standard and gives Ionic app developers access to a new Typescript class called `Tor`. Instances of this class have a straightforward API allowing one to `start` and `stop` an onion proxy, as well as refresh it (`reconnect`) and check whether it is running (`isRunning`). This functionality is granted by communicating with a running tor executable via the tor-control protocol.

With an onion proxy running, the next step is to send http requests through it and into the Tor network beyond. This is done by leveraging the Socks5H protocol and the Sock5H listener which is created as part of the onion proxy. A significant feature of Socks5H is that DNS lookup (i.e. asking name servers for the ip-address of a site) is done through the onion proxy as well. This means that even the name of the site you are attempting to communicate with is hidden within the Tor network. A second plugin, Start9’s Capacitor-Http — an extension of the Capacitor team’s official http plugin — grants Socks5H capabilities, allowing any http request to be executed via Tor.

The lowest level details are all platform specific; we have tied together iOS and Android native code to manage the tor executable according to the idiosyncrasies of each platform. Capacitor itself is able to determine whether the app exists within an iOS or Android machine and determines the appropriate code to use. All of this is done behind the scenes, so that app developers can fire and forget Tor requests without worry.

We are hopeful that this open-source plugin helps usher in a wave of all kinds of Tor-enabled mobile applications. Start9 is making use of the plugin in both the Embassy Companion App as well as the most recent version of Cups Messenger. Imagine everything from your maps app to your banking app protected by the privacy of the Tor network — now more possible than ever before.

Aaron Greenspan
Head of Engineering