Application Setup

The first step in the process is to configure your application target. This involves modifying your app's build settings, linking necessary libraries, and ensuring that your app has the required permissions and entitlements to utilize the VPN functionality.

Installing the SDK

Create Xcode Project

To get started, create a new Xcode application project for either iOS or macOS.

Add SDK to Project

The VPN SDK is provided as an xcframework, enabling compatibility with both iOS and macOS applications. Follow these steps to install the SDK in your Xcode project:

1. Open your Xcode project and navigate to the project settings:

• In the project navigator, select your project at the top of the list.

• Select your application target in the targets list.

• Switch to the "General" tab.

2. Locate the VPNApplicationSDK.xcframework file on your system.

3. Drag the VPNApplicationSDK.xcframework file from its location into the "Frameworks and Libraries" section of your target's "General" settings tab.

4. Verify that the "Embed" option for the newly added framework is set to "Embed & Sign".

• This ensures that the framework is properly embedded and signed within your application bundle.

Configure Build Settings

A few build settings need to be adjusted for the VPN SDK to work properly:

1. In Project -> App Target -> Build Settings:

• Set "Enable Bitcode" to NO. This option is deprecated.
• Add the flag -ObjC to "Other Linker Flags"

1. Link the NetworkExtension system framework to your application target.

Add OpenSSL Dependency

The SDK relies on the OpenSSL library. Add it to your project using Swift Package Manager:

1. In Xcode, go to File -> Add Packages...

2. Enter the OpenSSL package URL: https://github.com/krzyzanowskim/OpenSSL.git

For more information, please see https://github.com/krzyzanowskim/OpenSSL

1. Link the OpenSSL package to your application target.

Configure App ID and Capabilities

Developer Portal Setup

On the Apple Developer portal, go to Certificates, Identifiers & Profiles -> Identifiers.

Create a new App ID for your application or use an existing one. Enable the "Personal VPN" capability for this App ID.

• Access WiFi Information

• App Groups

• Network Extensions

• Personal VPN

Apple Developer Account

If you already have an Apple Developer ID, you can skip this step.

Why do you need an Apple Developer Account:

You need to join the Apple Developer Program to access the necessary tools and resources for developing, testing, and distributing your app on the App Store, ensuring it meets Apple's security and quality standards. You will need to get the paid version of an Apple Developer account to be able to sign and publish your app.

Here is a link to the broad overview from Apple of the resources you will get when you join the Apple Developer program: https://developer.apple.com/programs/

Here is a link that gets more specific on the need for an Apple Developer program in regards to distributing software to Apple devices: https://developer.apple.com/support/developer-id/

Follow this link to set up an Apple Developer Account: https://idmsa.apple.com/IDMSWebAuth/signin

Xcode Project Capabilities

Back in your Xcode project, go to Project -> App Target -> Signing and Capabilities.

Add the following capabilities to your application target:

• Personal VPN

• App Groups

For macOS targets, enable Keychain Sharing capability with your Group ID. To learn more about this process, please see Configuring Keychain Sharing

For macOS targets, also enable the Keychain Sharing capability using your App Group ID.

Integration Checklist

To ensure the VPN SDK is set up correctly, verify the following:

• VPNApplicationSDK.framework is added to the application target

• "Enable Bitcode" is set to "No"

• -ObjC flag is present in "Other Linker Flags"

• Personal VPN capability is enabled for both the App ID and application target

• App Groups capability is enabled

• OpenSSL package is linked to the application target

• Keychain Sharing is enabled for macOS targets

Category	Description
Application Target	Ensure it is created
Frameworks	VPNApplicationSDK.framework is added to the application target
Build Settings	-ObjC flag is present in "Other Linker Flags"
OpenSSL	OpenSSL package is added via Swift Package Manager using URL: NEED PROPER PACKAGE AND URL
Apple Developer Portal	You have created an Apple Developer Portal Account
Identifiers	On the Apple Developer Portal, you have created an Application Identifier with the following enabled: Access Wi-Fi Information App Group Network Extensions Personal VPN
Xcode Project Capabilities	You have enabled the following within the Application Target: App Group Access Wi-Fi Information Network Extensions Packet Tunnel
Keychain	Keychain Sharing is on for macOS targets

• Bitcode is now deprecated.

Uninstalling the SDK

This guide describes the steps and considerations for fully uninstalling the VPN SDK from your application. With these steps, you can ensure a complete removal of the SDK and its associated data when your app is uninstalled. Proper cleanup prevents unused data from being left behind on the user's device.

Uninstalling the SDK in macOS

To fully uninstall the VPN SDK in macOS:

1. Remove any app-specific data, configurations, and credentials related to the SDK.

2. Delete the keychain item created for the SDK's deviceUUID using the security command:

security delete-generic-password -s com.anchorfree.vpnsdk.deviceUUID

Alternatively, you can delete the keychain item manually by opening the Keychain Access app, then search for the com.anchorfree.vpnsdk.deviceUUID item.

1. Remove the following directories and files associated with the app and SDK:

#!/bin/sh

ID='your-app-bundle-id'
HYDRA_ID='your-ne-app-bundle-id'
WG_ID='your-wg-ne-app-bundle-id'
APP='your-app-name'
GROUP='your-group-id' # (e.g. 3TH5R7YS88.group...)

defaults delete $ID
defaults delete $HYDRA_ID
defaults delete $WG_ID

sudo rm -rf "/Applications/$APP"
sudo rm -rf ~/Library/Containers/$ID*
sudo rm -rf ~/Library/Group\ Containers/$GROUP*
sudo rm -rf ~/Library/Caches/$ID

• The main application bundle: /Applications/APP_NAME

• The app's container: ~/Library/Containers/APP_BUNDLE_ID

• The app group container: ~/Library/Group Containers/APP_GROUP_ID

• The app's cache: ~/Library/Caches/APP_BUNDLE_ID

• Please note that the script will require you to input your admin password when running the sudo commands to execute tasks with elevated privileges.

• Alternatively, you can create a non-sudo version of the script that will not remove everything, but only files and directories accessible without elevated privileges. This approach allows you to clean up certain areas of the system without requiring admin rights.

• The provided shell script for app deletion is intended as a debugging tool and cannot be automatically invoked upon app deletion. The script serves as an optional resource for developers who want to ensure that all app-related data and settings are thoroughly removed, particularly on macOS.

• On iOS, the operating system automatically removes all app settings and data when an app is deleted. However, on macOS, some residual data may persist after app deletion. In such cases, running the provided script manually can help ensure a complete cleanup.

• For complete data deletion of production accounts, please contact our support team.

Uninstalling the SDK in iOS

To fully uninstall the VPN SDK in iOS:

Remove any app-specific data, configurations, and credentials related to the SDK. Note:

• When an app is uninstalled by the user, the system automatically deletes all associated app data, including stored files. However, the app deletion process does not remove keychain data. Our app stores only the device ID in the keychain and no other data. Currently, there is no mechanism for an app to detect its own deletion or execute any clean-up logic during the uninstallation process.

• The only exception is the com.anchorfree.vpnsdk.deviceUUID keychain item, which may persist after app deletion (this behavior is subject to change). If your app relies on the deletion of this item, consider tying it to an encryption key stored in the app bundle - this will effectively render the keychain item inaccessible once the app is removed. Alternatively, users can manually locate this keychain item using the service name com.anchorfree.vpnsdk.deviceUUID and remove it from their keychain if desired.

Considerations

Most of the data associated with the VPN SDK is generated and stored by the client application rather than the SDK itself. Therefore, the app developer is responsible for cleaning up this data as part of the uninstallation process. This includes:

• Removing any stored parameters, configurations, or credentials used with the SDK

• Deleting keychain items created for the SDK (see platform-specific details above)

• Removing any other persisted SDK-related data from the app's storage