VPN Unlimited SDK v1.1 for iOS

Overview

VPN Unlimited SDK for iOS is shipped as a static framework. It is written in Objective-C and C++ and is available for iOS 7 and later.

SDK supports Apple's Network Extension framework and NEVPNManager class. This means that starting from iOS 8 users can turn VPN connection on and off from inside your application without the need to go to system preferences (as previously needed on iOS 7).

Moreover, starting from iOS 9 VPN Unlimited SDK supports custom protocol from Apple's Network Extension framework. This custom protocol is called KeepSolid Wise.

Setup

Drag and drop VPNUnlimitedSDK.framework into your project.
You have to include the VPNUnlimitedSDKResource.bundle file (drag and drop too).

In order to use it you have to add -ObjC linker flag in XCode (Target -> Build Settings -> Linker -> Other Linker Flags). You also have to add the following additional frameworks and libraries in XCode (Target -> Build Phases -> Link Binary With Libraries):

• AdSupport.framework
• MobileCoreServices.framework
• SystemConfiguration.framework
• NetworkExtension.framework (use "Optional" if you compile for OS version prior to iOS 8)
• libc++.dylib
• libz.dylib
• libresolv.dylib

After setup is done you should be able to use all the classes from SDK by including it with #import <VPNUnlimitedSDK/VPNUnlimitedSDK.h> directive.

On iOS 8+ you should also turn on "Personal VPN" entitlement in "Capabilities" section of your project settings.

Xcode 7.x and App Transport Security

VPNUnlimited SDK uses local HTTP server to download VPN profiles in iOS 7 mode (which does not use NEVPNManager class). If you want to support this mode, you must include Allow Arbitrary Loads flag in your project's Info.plist file if you use Xcode 7.x+. See Apple's documentation on this issue.

Using App ID and App secret

Use the following setup code in your AppDelegate's application:didFinishLaunchingWithOptions: method:

[VPNURequest setApplicationID:@""];
[VPNURequest setApplicationSecret:@""];
[VPNURequest setApplicationBundleID:@""];

Setting custom name for VPN profiles (iOS 8+ only)

You can set custom name for a downloaded VPN profile using NSString *profileName property of your instance of VPNUConfigurator class. If you do not do so before any calls to this instance, the default name ("VPN Unlimited") will be used.

Classes

This SDK is designed in classical OOP style. We provide a handful of classes which you can use in any desired combination. All network calls are synchronous, so you should never call them from main thread. This limitation is highlighted by the fact, that you actually can perform several steps in a row serially on secondary thread and come back to main thread with a desired result.

Here is the complete list of classes:

• VPNUTransport
• VPNURequest
• VPNUAuthorizer
• VPNUAccount
• VPNUAccountStatus
• VPNUAccountUserInfo
• VPNUAccountDeviceStatistics
• VPNUAccountDevice
• VPNUServersListAccessor
• VPNUServerItem
• VPNUConfigurator
• VPNUPurchaseManager
• VPNUPurchaseItem
• VPNUOnDemandConnectionManager
• VPNUStorage

You can see the complete documentation for each class at Reference page.

Here we just briefly describe the standard workflow.

VPNUTransport and its dependers

The VPNUTransport is the main networking class in SDK. It is responsible for communicating with our server as well as dealing with active session. A lot of classes which involve network communication are dependant on this class, namely:

• VPNUAuthorizer
• VPNUAccount
• VPNUServersListAccessor
• VPNUConfigurator
• VPNUPurchaseManager

All these classes have a designated initializer initWithTransport:. Their instances have to be instantiated using this constructor, otherwise they just will not work. Here is a basic example of how you can use it:

// In your view controller declaration, e.g.:
@interface ViewController ()
@property VPNUTransport *transport;
@property VPNUAuthorizer *authorizer;
@end

// Then, initialize transport somewhere, for example in `viewDidAppear`:
- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    // 1. Setup transport
    self.transport = [[VPNUTransport alloc] init];

    // 2. Setup authorizer
    self.authorizer = [[VPNUAuthorizer alloc] initWithTransport:self.transport];
}

Now you can perform all needed actions with authorizer object.

Multithreading

As stated previously, all network calls in this SDK are performed synchronously. That means that you should perform them all on a non-main thread, otherwise it would block it and never come back. Every method which falls into this category is explicitly documented.

In order to achieve asynchronous behavior you can use any multithreading technique you like. We recommend Grand Central Dispatch. When an operation is finished you can move back to main thread. You can stay on secondary thread and perform more networking actions serially, if you desire.

KSVPNUFacade

KSVPNUFacade is a class which serves as a 'facade' to other VPN Unlimited SDK classes. It hides the complexity of VPN Unlimited SDK by encapsulating most of the needed features.

If you do not want to construct API requests and VPN configurator by yourself you can use KSVPNUFacade singleton. Please check the documentation for this class: it is convenient for most applications.

FAQ

In every example in the FAQ section it is implicitly considered that the code is executing on a secondary thread using this syntax:

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
    // Sample code from FAQ
});

It is also considered that transport property is set up before any calls:

self.transport = [[VPNUTransport alloc] init];

self.authorizer = [[VPNUAuthorizer alloc] initWithTransport:self.transport];

NSString *login = @"login@some.domain";
NSString *password = @"password";
NSError *error;
VPNUAccountUserInfo *userInfo = [self.authorizer authorizeWithLogin:login andPassword:password error:&error];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Logged in user:%@", userInfo.name);
    }
});

self.authorizer = [[VPNUAuthorizer alloc] initWithTransport:self.transport];

NSString *login = @"login@some.domain";
NSString *password = @"password";
NSError *error;
VPNUAccountUserInfo *userInfo = [self.authorizer registerWithLogin:login andPassword:password error:&error];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Registered and Logged in user:\n%@", userInfo.name);
    }
});

NSError *error;
BOOL signedOut = [self.authorizer signOutWithError:&error];
dispatch_async(dispatch_get_main_queue(), ^{
    if (!signedOut && error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Logged out");
    }
});

VPNUAccount *account = [[VPNUAccount alloc] initWithTransport:self.transport];
NSError *error;
VPNUAccountStatus *accountStatus = [account statusWithError:&error];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Will expire on:\n%@", accountStatus.timeLeftString);
    }
});

VPNUServersListAccessor *serversListAccessor = [[VPNUServersListAccessor alloc] initWithTransport:self.transport];
NSError *error;
NSArray *servers = [serversListAccessor listWithError:&error];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Available regions:");
        for (VPNUServerItem *listItem in servers) {
            NSLog(@"%@ (%@)", listItem.name, listItem.region);
        }

        //Selecting some server
        self.selectedServerItem = [servers firstObject];
    }
});

self.configurator = [[VPNUConfigurator alloc] initWithTransport:self.transport];

BOOL alreadyInstalled;
NSError *error = [self.configurator setupWithServerItem:self.selectedServerItem alreadyInstalled:&alreadyInstalled];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        // Now you can connect to VPN
    }
});

NSError *error;
BOOL started = [self.configurator startVPNWithError:&error];
dispatch_sync(dispatch_get_main_queue(), ^{
    if (error) {
        NSLog(@"Error: %@", error);
    } else {
        NSLog(@"Connection started: %d", started);
    }
});

VPNURequest *request = [VPNURequest authRequestWithAction:kKSVPNUFacadeActionChangePassword];
[request setParameterObject:oldPassword forKey:@"password"];
[request setParameterObject:newPassword forKey:@"newpassword"];

NSError *error;
id responseObject = [self.transport sendRequest:request error:&error];