Tor.framework is the easiest way to embed Tor in your iOS application. The API is not stable yet, and subject to change.
Currently, the framework compiles in the following versions of tor
, libevent
, openssl
, and liblzma
:
Component | Version |
---|---|
tor | 0.4.8.11 |
libevent | 2.1.12 |
OpenSSL | 3.3.0 |
liblzma | 5.4.6 |
Onionmasq | 0.6.0 |
To run the example project, clone the repo, and run pod install
from the Example directory first.
- iOS 9.0 or later
- MacOS 12.0 or later
- Xcode 13.0 or later
autoconf
,automake
,libtool
andgettext
in yourPATH
Install build tools via Homebrew:
brew install automake autoconf libtool gettext
Tor is available through CocoaPods. To install it, simply add the following line to your Podfile:
If you use dynamic frameworks, use the root spec:
use_frameworks!
pod 'Tor', '~> 408'
(or Tor/GeoIP
- see below.)
If you need to add it as a static library, you will need to add it from a modified podspec:
pod 'Tor', :podspec => 'https://raw.githubusercontent.com/iCepa/Tor.framework/pure_pod/TorStatic.podspec'
Currently static library support is unstable. You might encounter build issues. Every contribution to fix this is welcome!
(or Tor/GeoIP
- see below.)
If you check out this repository directly, you will also need to fetch the submodules:
git submodule update --init --recursive
If you use it as a normal CocoaPods dependency, that will be done by CocoaPods.
For maintainers/contributors of Tor.framework, a new release should be prepared by doing the following:
Ensure that you have committed changes to the submodule trees for tor, libevent, openssl, and xz.
Also update info and version numbers in README.md
and Tor.podspec
!
Then lint like this:
pod lib lint --verbose --allow-warnings
(Use verbose
, otherwise you'll get very bored.)
If the linting went well, create a git tag for the version, push to GitHub and then publish to CocoaPods:
pod trunk push Tor.podspec --verbose --allow-warnings --skip-import-validation --skip-tests
(Unfortunately, you can not not lint on publish, so you might skip the first lint. However, pod trunk push
will take even longer, because it will clone everything fresh, too.)
Then create a release in GitHub which corresponds to the tag, and attach latest info as per older releases.
To upgrade Tor:
cd Tor/tor
git fetch
git checkout tor-0.4.8.11 # Find latest versions with git tag -l
rm -r * && git checkout . # Get rid of all autogenerated configuration files, which may not work with the newest version anymore.
git submodule update --init --recursive # Later Tor has submodules.
-> Test build by running the Example apps.
Check build output in the Report Navigator. (Last tab in the left pane.)
For a headache-free start into the world of Tor on iOS and macOS, check out
the new TorManager
project!
Starting an instance of Tor involves using three classes: TORThread
, TORConfiguration
and TORController
.
Here is an example of integrating Tor with NSURLSession
:
TORConfiguration *configuration = [TORConfiguration new];
configuration.ignoreMissingTorrc = YES;
configuration.cookieAuthentication = YES;
configuration.dataDirectory = [NSURL fileURLWithPath:NSTemporaryDirectory()];
configuration.controlSocket = [configuration.dataDirectory URLByAppendingPathComponent:@"control_port"];
TORThread *thread = [[TORThread alloc] initWithConfiguration:configuration];
[thread start];
NSData *cookie = configuration.cookie;
TORController *controller = [[TORController alloc] initWithSocketURL:configuration.controlSocket];
NSError *error;
[controller connect:&error];
if (error) {
NSLog(@"Error: %@", error);
return;
}
[controller authenticateWithData:cookie completion:^(BOOL success, NSError *error) {
if (!success)
return;
[controller addObserverForCircuitEstablished:^(BOOL established) {
if (!established)
return;
[controller getSessionConfiguration:^(NSURLSessionConfiguration *configuration) {
NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration];
...
}];
}];
}];
In your Podfile
use the subspec GeoIP
or StaticGeoIP
instead of the root spec:
use_frameworks!
pod 'Tor/GeoIP'
or
pod 'Tor/GeoIP', :podspec => 'https://raw.githubusercontent.com/iCepa/Tor.framework/pure_pod/TorStatic.podspec'
The subspec will create a "GeoIP" bundle and install a run script phase which will download the appropriate GeoIP files.
To use it with Tor, add this to your configuration:
TORConfiguration *configuration = [TORConfiguration new];
configuration.geoipFile = NSBundle.geoIpBundle.geoipFile;
configuration.geoip6File = NSBundle.geoIpBundle.geoip6File;
https://tordev.guardianproject.info
- Conrad Kramer, conrad@conradkramer.com
- Chris Ballinger, chris@chatsecure.org
- Mike Tigas, mike@tig.as
- Benjamin Erhart, berhart@netzarchitekten.com
Tor.framework is available under the MIT license. See the
LICENSE
file for more info.