This is a demo application for macOS Applications with basic usage of ATOM VPN SDK which will help the developers to create smooth applications over ATOM SDK quickly.
- Connection with Parameters
- Connection with Pre-Shared Key (PSK)
- Connection with Dedicated IP
- Connection with Multiple Protocols (Auto-Retry Functionality)
- Connection with Real-time Optimized Servers (Countries based on latency from user in Real-time)
- Connection with Smart Dialing (Use getCountriesForSmartDialing() to get the Advanced VPN Dialing supported countries)
- Connection with Smart Connect (Tags based dialing)
- Compatible with Xcode 15.3, macOS 10.13 and later
- Compatible with ATOM SDK Version 5.0 and onwards
- IPSec
- IKEv2
- TCP
- UDP
- Wireguard
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate AtomSDK into your Xcode project using CocoaPods, specify it in your Podfile:
pod 'AtomSDKBySecure'
pod 'AtomSDKTunnel'You can add AtomWireguardTunnel package via Swift Package Manager
- Open your project in Xcode 15.3 or above
- Go to File > Swift Packages > Add Package Dependency...
- In the field Enter package repository URL, enter "https://github.com/AtomSDK/AtomWireguardTunnel"
- Choose Dependency Rule "Branch", and add the branch name "main"
To add the SDK in Xcode:
- Open your Xcode project.
- Add your developer account to Xcode from Preferences -> Account if you didn't add before.
- Select General tab from your app target and then set your developer account details.
- From your app target select Capabilities tab and select the switch right of the Personal VPN. Then select the capabilties you are going to use.
- Drag and drop AtomSDK.framework into your project. (Skip if using Cocoapods)
- Go to your project -> General tab from your app target, add the framework using ‘+’ to the Embedded Binaries section. (Skip if using Cocoapods)
- After the setup is completed, you should be able to use all the classes from the SDK by including it with the #import <AtomSDK/AtomSDK.h> directive.
- ATOM SDK needs to be initialized with a “SecretKey” provided to you after you buy the subscription which is typically a hex-numeric literal.
It can be initialized using an instance of AtomConfiguration. It should have a vpnInterfaceName which will be used to create the Network Interface for VPN connection.
AtomConfiguration *atomConfiguration= [[AtomConfiguration alloc] init];
atomConfiguration.secretKey = @"SECRETKEY_GOES_HERE";
atomConfiguration.vpnInterfaceName = @"Atom";
atomConfiguration.tunnelProviderBundleIdentifier = “ENTER_YOUR _NETWORK_EXTENSION_BUNDLE_ID”;
atomConfiguration.wireGuardTunnelProviderBundleIdentifier = “ENTER_YOUR_WIREGUARD_NETWORK_EXTENSION_BUNDLE_ID”;
[AtomManager sharedInstanceWithAtomConfiguration:atomConfiguration];PS: ATOM SDK is a singleton, and must be initialized before accessing its methods.
ATOM SDK offers a feature to enable the local inventory support. This can help Application to fetch Countries and Protocols even when device network is not working.
- To enable it, Log In to the Atom Console
- Download the local data file in json format
- File name should be localdata.json. Please rename the file to localdata.json if you find any discrepancy in the file name.
- Paste the file in root of your application folder.
ATOM SDK offers four delegates to register for the ease of the developer.
- atomManagerDidConnect:
- atomManagerDidDisconnect:
- atomManagerOnRedialing:
- atomManagerDialErrorReceived:
- atomManagerOnUnableToAccessInternet:
- atomManagerDidReceiveConnectedLocation:
ATOM SDK offers stateDidChangedHandler for the ease of the developer.
[AtomManager sharedInstance].stateDidChangedHandler = ^(AtomVPNState status) { };ATOM SDK provided two ways to authenticate your vpn user. First one is to offer VPN Credentials directly to the SDK which you may create through the Admin Panel provided by ATOM.
[AtomManager sharedInstance].atomCredential = [[AtomCredential alloc] initWithUsername:@"<username>" password:@"<password>"];Alternatively, if you don’t want to take hassle of creating users yourself, leave it on us and we will do the rest for you!
[AtomManager sharedInstance].UUID = @<"[[[UIDevice currentDevice] identifierForVendor] UUIDString]>";You just need to provide a Unique User ID for your user e.g. any unique hash or even user’s email which you think remains consistent and unique for your user. ATOM SDK will generate VPN Account behind the scenes automatically and gets your user connected! Easy isn’t it?
You need to declare an object of “AtomProperties” Class to define your connection preferences. Details of all the available properties can be seen in the inline documentation of “AtomProperties” Class. For the least, you need to give Country and Protocol with which you want to connect.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<country>" protocol:@"<protocol>"];Countries can be obtained through ATOM SDK as well.
[[AtomManager sharedInstance] getCountriesWithSuccess:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];You can get the Recommended Country for user's location through ATOM SDK.
[[AtomManager sharedInstance] getRecommendedCountry:^(AtomCountry *country) {
} errorBlock:^(NSError *error) {
}];You can get the Countries those support Smart Dialing through ATOM SDK.
[[AtomManager sharedInstance] getCountriesForSmartDialing:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];Protocols can be obtained through ATOM SDK as well.
[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray<AtomProtocol *> *success) {}
errorBlock:^(NSError *error) {}];For VPN connection speed you need to registor onPacketsTransmitted handler from AtomManager class to get the VPN connection speed in bytes per second. This callback is recieve only in VPN connected state.
AtomManager.sharedInstance.onPacketsTransmitted = ^(NSNumber *bytesReceived, NSNumber *bytesSent) {
NSLog(@"bytesIN: %ld | bytesOUT: %ld ",(long)bytesReceived.integerValue,bytesSent.integerValue);
};You can enable or disable protocol switch from VPNProperties class. By default its value is set to true.
properties.enableProtocolSwitch = false;or
properties.enableProtocolSwitch = true;If you didn't specify the protocol in case of Country, City and Channel dailing then Atom SDK dialed with recommanded protocol according to the specified country, city and channel. It did not work in PSK, Smart connect dialing and dedicated IP.
Failover is a mechanism in which Atom dialed with nearest server if requested server is busy or not found for any reason. You can control this mechanism from VPNPorperties class. By default its value is set to true.
properties.useFailover = false;or
properties.useFailover = true;As soon as you call Connect method, the events you were listening to will get the updates about the states being changed and VPNDialedError (if any occurs) as well.
It is the simplest way of connection which is well explained in the steps above. You just need to provide the country and the protocol objects and call the Connect method.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];When connecting with parameters, a server can be included or excluded with its Nas Identifier
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
NSMutableArray<ServerFilter *> *serverFilters = [NSMutableArray new];
[serverFilters addObject:[[ServerFilter alloc] initWithNasIdentifier:@"nas-identifier-here"" andFilter:INCLUDE]];
[serverFilters addObject:[[ServerFilter alloc] initWithNasIdentifier:@"nas-identifier-here" andFilter:EXCLUDE]];
[properties setServerFilters:serverFilters];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];In this way of connection, it is pre-assumed that you have your own backend server which communicates with ATOM Backend APIs directly and creates a Pre-Shared Key (usually called as PSK) which you can then provide to the SDK for dialing. While providing PSK, no VPN Property other than PSK is required to make the connection. ATOM SDK will handle the rest.
AtomProperties *properties = [[AtomProperties alloc] initWithPreSharedKey:@"<#PSK#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];You can also make your user comfortable with this type of connection by just providing them with a Dedicated IP/Host and they will always connect to a dedicated server! For this purpose, ATOM SDK provides you with the following constructor.
AtomProperties *properties = [[AtomProperties alloc] initWithDedicatedHostName:@"<#DedicatedIP/Host#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];This one is same as the first one i.e. “Connection with Parameters” with a slight addition of using Real-time optimized servers best from your user’s location. You just need to set this property to TRUE and rest will be handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseOptimization:YES];
[[AtomManager sharedInstance] connectWithPropertiesconnectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];If you want to show your user the best location for him on your GUI then ATOM SDK have it ready for you as well! ATOM SDK has a method exposed namely “getOptimizedCountries” which adds a property “RoundTripTime” in the country object which has the real-time latency of all countries from your user’s location (only if ping is enabled on your user’s system and ISP doesn’t blocks any of our datacenters). You can use this property to find the best speed countries from your user’s location.
“Connection with Parameters” with a slight addition of using smart dialing to connect. You just need to call "withSmartDialing" and rest will handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseSmartDialing:YES];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];For more information, please see the inline documentation of AtomProperties Class.
You can provide three protocols at max so ATOM SDK can attempt automatically on your behalf to get your user connected with the Secondary or Tertiary protocol if your base Protocol fails to connect.
properties.secondaryProtocol = @"<protocol2>";
properties.tertiaryProtocol = @"<protocol3>";If you want us to connect your user with what's best for him, you can now do it using SmartConnect feature. Atom has introduced an enum list of feature a.k.a Tags you want to apply over those smart connections which can be found under Atom.Core.AtomSmartConnectTag. An example usage of SmartConnect is depicted below.
NSArray *selectedAtomTags = [[NSArray alloc] initWithObjects: @(AtomSmartConnectTagFileSharing),@(AtomSmartConnectTagPaid), nil];
AtomProperties *properties = [[AtomProperties alloc] initWithProtocol:selectedProtocol andTags:selectedAtomTags];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {
} errorBlock:^(NSError *error) {
}];Tags aren't mandatory and are nil parameter. You can only provide Protocol to connect and rest Atom will manage.
You can cancel connection between dialing process by calling the cancelVPN method.
[[AtomManager sharedInstance] cancelVPN];To disconnect, simply call the disconnectVPN method of AtomManager.
[[AtomManager sharedInstance] disconnectVPN];To remove VPN profile, simply call the removeVPNProfileWithCompletion method of AtomManager.
[[AtomManager sharedInstance] removeVPNProfileWithCompletion:^(BOOL isSuccess) {
}];We are going to integrate AtomSDKTunnel in macOS application for dialing with TCP/UDP protocol.
There are few steps that needs to followed carefully.
Lets start setting up system extension.
macOS 10.15
SystemExtension Packet Tunnel (Network Extension) Keychain Groups App Groups
We need to add a new target. Press plus sign on bottom left of xcode where all the targets are listed.
Now choose Network Extension under System Extension heading.
Now add relevant information while creating target.
Congrats, new target has been created. But we need to configure it.
Go to capabilities tab on top of xcode and under Network Extension Capabilities please choose Packet Tunnel and enable Out going connection
In your macOS application target add system extension capability.
Now let add the framework in dependency manager (Cocoapods) using the following command.
Note: This framework must be added to Network extension target since this target will only be running in 10.15 macOS.
Let install Pod using,
pod install --verbose
Since there is a limitation on cocoapod to embed framework in System extension, we will be adding it manually.
Press Plus sign under Framework and Libraries
and select AtomOPVPNTunnel.xcframework, AtomSDKTunnel.xcframework, LZ4.xcframework, mbedTLS.xcframework, OpenVPNClient.xcframework for OpenVPN specific System Extension
and select AtomWireguardTunnel for Wireguard specific System Extension
Here comes to the coding part. Simple pass the tunnel bundle identifier and app group identifier of new created target to AtomConfiguration class.
Note: You can enable/disable OpenVPN connection logs using the bit enableVPNLogs.
In order to activate System Extension you need to call ExtensionManager's activeExtension method. Note: This should be done after AtomSDK being initialized.
You should also listen to the ExtensionManagerDelegate in order to receive events.
Open PacketTunnelProvider class which was created with newly created target and subclass it with AtomPacketTunnelProvider after importing AtomSDKTunnel.
In your Extension's info.plist, change the value of NEMachServiceName to be the App group's identifier.
Wolaa, Integartion is completed. Time to test it.
If you run your app system extension will ask for user's approval.
Which can be allowed from Security Preferences.
Once the system Extension is installed you can verify it using the following command.
systemextensionsctl list
In order to release the system extension there are few requirement.
Entitlement file of Extension manager in release must have the following key value pair.
<key>com.apple.developer.networking.networkextension</key>
<array>
<string>packet-tunnel-provider-systemextension</string>
</array>
While in debug it should be the following
<key>com.apple.developer.networking.networkextension</key>
<array>
<string>packet-tunnel-provider</string>
</array>