/iOS-OnionBrowser

An open-source, privacy-enhancing web browser for iOS, utilizing the Tor anonymity network

Primary LanguageObjective-COtherNOASSERTION

Onion Browser

Build Status
Official Site | Support | Changelog | Donate
© 2012-2016 Mike Tigas (@mtigas)
MIT License

A minimal, open-source web browser for iOS that tunnels web traffic through the Tor network. See the official site for more details and App Store links.

  • OnionBrowser: 1.6.0 (20160804.1) - See official release history and changelog.
  • Tor: 0.2.8.6 (Aug 02 2016)
  • iObfs: 26463e2 (Jul 15 2016)
    • obfs4proxy: 0.0.7-dev, upstream 6205762 (Jul 10 2016)
    • golang: 1.7rc3 (Jul 21 2016)
  • libevent: 2.0.22-stable (Jan 05 2015)
  • OpenSSL: 1.0.2h (May 03 2016)

Screenshots: iPhone 4/4S, iPhone 5, iPad 3

Adding Onion Browser support to other iOS apps

Onion Browser responds to two URL schemes: onionbrowser:// and onionbrowsers://, representing HTTP and HTTPS URLs, respectively. These work like the URI schemes in iOS Google Chrome and other popular third-party web browsers.

  • A URL of onionbrowser://opennews.org/ will launch Onion Browser and navigate the app to http://opennews.org/.
  • A URL of onionbrowsers://mike.tig.as/ will launch Onion Browser and navigate the app to https://mike.tig.as/.

Allowing your own app to launch Onion Browser instead of Safari works similarly to iOS Google Chrome:

  1. Check if Onion Browser is installed by seeing if iOS can open a onionbrowser:// URL.
  2. If so, replace the http:// prefix with onionbrowser:// and replace the https:// prefix with onionbrowsers://.
  3. Then tell iOS to open the newly defined URL (newURL) by executing [[UIApplication sharedApplication] openURL:newURL];

See the Google Chrome iOS instructions for more details -- just note that you should replace their googlechrome:// URL schemes with the proper onionbrowser:// ones.

Implementation notes

The app, when compiled, contains static library versions of Tor and it's dependencies, libevent and openssl.

The build scripts for Tor and other dependencies are based on build-libssl.sh from x2on/OpenSSL-for-iPhone. The scripts are configured to compile universal binaries for armv7 and i386 (for the iOS Simulator).

Because iOS applications cannot launch subprocesses or otherwise execute other binaries, the tor client is run in-process in a NSThread subclass which executes the tor_main() function (as an external tor executable would) and attempts to safely wrap Tor within the app. (libor.a and libtor.a, intermediate binaries created when compiling Tor, are used to provide Tor.) Side-effects of this method have not yet been fully evaluated. Management of most tor functionality (status checks, reloading tor on connection changes) is handled by accessing the Tor control port in an internal, telnet-like session from the AppDelegate.

The app uses a NSURLProtocol subclass (ProxyURLProtocol), registered to handle HTTP/HTTPS requests. That protocol uses the CKHTTPConnection class which nearly matches the NSURLConnection class, providing wrappers and access to the underlying CFHTTP Core Framework connection bits. This connection class is where SOCKS5 connectivity is enabled. (Because we are using SOCKS5, DNS requests are sent over the Tor network, as well.)

Information for forks

  1. If you're distributing an app that builds off of the Onion Browser code, you need to use your own app name and logo.

    • Note that you also cannot use the official Tor Project logo and names (i.e. "Tor", "Tor Browser", "Tor Browser Bundle") without written permission from the Tor Project. Please see their trademark FAQ for more information.

  2. If you're distributing an app that builds off of the Onion Browser code, you must cite Onion Browser within your app's credits as part of the terms of the normal MIT License.

    See the LICENSE file -- generally you need to include everything from the "ONION BROWSER LICENSE" section down through the rest of the file. Read that file for more information, though.

  3. You'll need to make sure the "Bundle identifier" (under "Info" in the app's Target Properties) is set to your own identifier and not "com.miketigas.OnionBrowser".

  4. You'll need to make sure the URL handlers for your app (see Integration notes above) don't conflict with the ones for Onion Browser. Make sure you edit your <app>-Info.plist file and edit values under "URL types".

    Change "URL identifier" to your own' app's identifier from #3, change the URL Schemes to the URL schemes your app should open if another app tries to open a URL with that prefix. ("test" and "tests" will make your app open if another app tries to open URLs starting with "test://" and "tests://".)

    You'll also need to edit code in AppDelegate.m. Look for instances of "onionbrowser:" and "onionbrowsers:", as these are the portions that check for your app's URL identifiers.