- OnionBrowser: 1.5.13pre (20151002.1) — See changelog
- Tor: 0.2.7.3-rc (Sep 25 2015)
- libevent: 2.0.22-stable (Jan 05 2015)
- OpenSSL: 1.0.2d (Jul 09 2015)
Screenshots: iPhone 4/4S, iPhone 5, iPad 3
Onion Browser responds to two URL schemes:
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
- A URL of
onionbrowsers://mike.tig.as/will launch Onion Browser and navigate the app to
Allowing your own app to launch Onion Browser instead of Safari works similarly to iOS Google Chrome:
- Check if Onion Browser is installed by seeing if iOS can open a
- If so, replace the
onionbrowser://and replace the
- 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
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).
build-tor.sh script patches one file in Tor (
to remove references to
_NSGetEnviron(). This first is only used
DisableDebuggerAttachment feature (default: True) implemented in Tor
0.2.3.9-alpha. (See changelog and manual.)
_NSGetEnviron() calls are not allowed in App Store apps; apps
ptrace() symbols are rejected on upload by Apple's
auto-validation of the uploaded binary. (The
_NSGetEnviron() code does not
even compile when using iPhoneSDK due to that function being undefined.)
See the patch files in
build-patches/ if you are interested in the changes.
Tor 0.2.3.17-beta introduced compiler and linker "hardening" (Tor ticket 5210),
which is incompatible with the iOS Device build chain. The app (when building
for iOS devices) is configured with
to get around this issue. (Due to the isolation of executable code on iOS devices,
this should not cause a significant change in security.)
Because iOS applications cannot launch subprocesses or otherwise execute other
binaries, the tor client is run in-process in a
NSThread subclass which
tor_main() function (as an external
tor executable would)
and attempts to safely wrap Tor within the app. (
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
The app uses a
NSURLProtocol subclass (
ProxyURLProtocol), registered to
handle HTTP/HTTPS requests. That protocol uses the
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.)
(I had WireShark packet logs to support the claim that this app protects all HTTP/HTTPS/DNS traffic in the browser, but seem to have misplaced them. You'll have to take my word for it or run your own tests.)
The app uses Automatic Reference Counting (ARC) and was developed against iOS 5.X or greater. (It may work when building against iOS 4.X, since most of the ARC behavior exists in that older SDK, with the notable exception of weakrefs.)
- Check Xcode version
- Build dependencies via command-line
- Build application in XCode
Check Xcode version
Double-check that the "currently selected" Xcode Tools correspond to the version of Xcode you have installed:
For the newer Xcode 4.3+ installed via the App Store, the directory should be
/Applications/Xcode.app/Contents/Developer, and not the straight
(used by Xcode 4.2 and earlier). If you have both copies of Xcode installed
(or if you have updated to Xcode 4.3 but
/Developer still shows), do this:
sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
Optional: PGP key verification for dependencies
(Currently in testing.) The build scripts for OpenSSL, libevent, and tor, verify that the package downloaded is PGP signed by one of the users responsible for packaging the library. You'll need to have GnuPG installed and import their public keys to allow this to work.
- OpenSSL: core developers. 1.0.2a is known to be signed by Matt Caswell 0xD9C4D26D0E604491 0xF295C759.
- libevent: Nick Mathewson (0x165733EA) or Neils Provos (0xC2009841). 2.0.21 is known to be signed by Nick Matthewson 0x910397D88D29319A (subkey of 0x21194EBB165733EA).
- tor: signing key info. 0.2.6.5-rc is known to be signed by Nick Matthewson 0x910397D88D29319A (subkey of 0x21194EBB165733EA).
If you don't care about PGP key verification, you'll need to run each of
the scripts with the
--noverify option or change
in each of the
build-*.sh scripts before continuing.)
cd to the root directory of this repository and then run these commands in
the following order to build the dependencies. (This can take anywhere between
five and thirty minutes depending on your system speed.)
bash build-libssl.sh bash build-libevent.sh bash build-tor.sh
This should create a
dependencies directory in the root of the repository,
containing the statically-compiled library files.
If you are inside a country or network that blocks connections to torproject.org,
you may have to use a mirror
(alt) to successfully build
the Tor dependency. Please see the instructions in
build-tor.sh if you require
Build OnionBrowser.xcodeproj in Xcode
OnionBrowser/OnionBrowser.xcodeproj. You should be
able to compile and run the application at this point.
The app and all dependencies are compiled to run against
platforms (the default as of iOS 8).
All dependencies are further compiled for
x86_64 targets, so
that both the 32-bit and 64-bit iOS Simulators are supported.
Information for forks
If you're distributing an app that builds off of the Onion Browser code, you need to use your own app name and logo.
If you're distributing an app that builds off of the Onion Browser code, you need to cite Onion Browser within your app's credits as part of the terms of the normal MIT License.
See the LICENSE file for information -- generally you need to include everything from the "ONION BROWSER LICENSE" section down through the rest of the file, but see the "TRADEMARK / LICENSE / FORK INFORMATION" section there.
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".
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.plistfile 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
"onionbrowsers:", as these are the portions that check for your app's URL identifiers.