Home Console

Network extension setup

Network extension setup

You should already have prepared application target in order to continue, if you haven't done it yet, please check this.

Create network extension target

You need to create network extension in order to use Hydra and WireGuard protocols.

Go to Project -> Targets, and in menu bar select Editor > Add Target. Select needed platform (iOS or macOS), then choose Network Extension type, provide the name and bundle ID for this Network Extension target.

NOTE: It is recommended to give distinctive names to your targets and bundle IDs with mention of target protocol, e.g. for Hydra:

  • Application target: MyApp, com.blabla.myapp

  • Network extension target: MyApp Hydra Provider, com.blabla.myapp.hydraprovider

Install tunnel provider SDK

At this point you have to have at least two targets:

  • Application target

  • Network Extension target

Now you should link tunnel provider SDK to the Network Extension target. We're providing SDK packed as xcframework, which means it can be used both for iOS and macOS apps.

Manual

  1. Link frameworks:

Hydra

  • Copy HydraTunnelProvider.xcframework file to some place inside your project folder on disk.

  • Go to Project -> Network Extension Target -> General and drag copied framework to Frameworks, Libraries and Embedded Content section.

  • Set Do Not Embed under Embed and sign option for HydraTunnelProvider.framework.

WireGuard

  • Copy WireguardTunnelProvider.framework file to some place inside your project folder on disk.

  • Go to Project -> Network Extension Target -> General and drag copied framework to Frameworks, Libraries and Embedded Content section.

  • Set Do Not Embed under Embed and sign option for WireguardTunnelProvider.framework.

  1. Link NetworkExtension system framework to the Network Extension target.

  2. Link libz.tbd and libresolv.tbd libraries to the Network Extension target.

  3. Go to Project -> Network Extension Target -> Build Settings and:

  • Set Enable Bitcode to NO;

  • Add -ObjC to Other Linker Flags.

Conform to Network Extension delegate

After the Network Extension target is created, you should observe that new class is added to your project (file PacketTunnelProvider.swift). Go to the PacketTunnelProvider.swift, rename it to ProviderDelegate and make this class implement BaseNetworkExtensionDelegate instead of NEPacketTunnelProvider. It should now look like:

import HydraTunnelProvider

class ProviderDelegate: NSObject, BaseNetworkExtensionDelegate {
	// ...
}

Remove Xcode-generated empty PacketTunnelProvider's implementation. Now you can implement needed methods from BaseNetworkExtensionDelegate. Also, if you want to use Fireshield related methods in network extension you can make your ProviderDelagate class conform to FireshieldNetworkExtensionDelegate protocol which extends base delegate. Pay attention that it makes sense only if you're using Hydra protocol, otherwise Fireshield methods won't be called.

Setup Info.plist

  1. Staying in Network Extension target, set NSExtensionPrincipalClass in NSExtension dictionary of Info.plist to corresponding value depending on protocol:

  • Hydra: AFHydraTunnelProvider

  • WireGuard: AFWireGuardTunnelProvider

  1. Add new key to a plist root: NetworkExtensionDelegate with a value that is your provider delegate class from the previous step. For example, if your class named ProviderDelegate, then the value would be $(PRODUCT_MODULE_NAME).ProviderDelegate.

Read more about Creating a Packet Tunnel Provider Extension from Apple docs.

Setup App ID

Next you need to perform all needed setup on Apple developer portal.

Setup on developer portal

You should already have app ID for Application target, now you need another one for Network Extension target. Go to Apple developer portal->Certificates, Identifiers & Profiles->Identifiers and add new identifier for your Network Extension. Turn on following capabilities for both app IDs (Application and Network Extension):

  • Access WiFi Information

  • App Groups

  • Network Extensions

  • Personal VPN

Create App Group

Since HydraSDK is mostly a Network Extension you also have to create an App Group and provide group ID to the SDK to allow Hydra to interact with Packet Tunnel Provider Extension. See Adding an App to an App Group for more information about how to create app group.

You need to assign this group to both, the Application and the Network Extension targets and App IDs.

Turn on capabilities in project

For both, Application and Network Extension targets, go to Project -> Target -> Capabilities and enable the following capabilities:

  • Access WiFi Information

  • App Groups

  • Network Extensions

    • Packet Tunnel

  • Personal VPN

For macOS targets, enable Keychain Sharing capability with your Group ID

NOTE: Make sure that respective .entitlement files are added to the project for both targets.

Re/Generate Provision Profiles

Application and Network Extension, both have to have its respective Provision Profiles generated from the Developer Portal. When creating and/or regenerating Provision Profiles, make sure you select Network Extension entitlement.

NOTE: The Provision Profiles' entitlements must corresponds to entitlements configured through Xcode's project Capabilities tab. If there is a missconfiguration between the two, VPN connection will not be established.

Integration Checklist & Troubleshooting

Checklist that should help you to verify correct integration:

  • Make sure that you've created Network extension.

  • VPNApplicationSDK.framework is added to the Application target.

  • For Hydra, HydraTunnelProvider.framework is added to the Extension target.

  • For WireGuard, WireguardTunnelProvider.framework is added to the Extension target.

  • libz.tbd and libresolv.tbd added to the Extension target.

  • Enable Bitcode is set to "No" and -ObjC is present in "Other linker flags" for both targets.

  • You have created and enabled App Groups (General > Capabilities) for both targets, active App Group is set to "builder.groupId" (App Groups is enabled for both bundle ids (Application and Extension) in Apple Developer Portal).

  • Personal VPN (General > Capabilities) is enabled for both targets (Personal VPN is enabled for both bundle ids (Application and Extension) in Apple Developer Portal).

  • You have added Network Extension (iOS) entitlement for both Application and Extension provisioning profiles.

  • SDK instance is configured with correct groupData, extensionBundleID.

PreviousChangelogNextAPI Reference

Last updated