Integrate the VPN SDK

Integrate the VPN SDK into your application

Prerequisites

1. Complete the Getting Started Guide

2. Integrate the User SDK

3. Integrate the Entitlements SDK

Get Started

• Integrate the iOS SDK

• Integrate the Android SDK

• Integrate the JS SDK

Integrate the iOS SDK

To gain access to the iOS SDK and iOS sample app providing a reference for integrating the SDK, please contact us..

Apple Macs running on Apple Silicon are currently not supported. This means that iOS simulators on these machines are currently not supported.

Use either a real device, or an Intel Mac system for Sudo Platform VPN application development.

It is recommended to use a real iOS device as the simulator does not support VPN configurations.

Client Initialization

When setting up, ensure that you include a PersonalVPNentitlement capability on the application id.

To instantiate a client in your application, add the following

Swift

import SudoVPN

let userClient = // ... see "Users" docs

do {
    let vpnClient = DefaultSudoVPNClient(userClient: userClient)
} catch {
    // Handle initialization error. An error might be thrown due to invalid
    // or missing configuration file.
}

You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.

Client Preparation

To ensure that the correct data is returned from API calls in the iOS client, please ensure that the prepare method is called.

This method must be called once after the following sequence **has occurred: registration, sign in, and redeem entitlements.** This method must be called on each initialized VPN Client.

To call the prepare method:

vpnClient.prepare { result in
    switch result {
    case .success:
        // Handle success result
    case .failure(let error):
        // Handle failure result
}

User Sign Out

To prevent re-use of user credentials, when the user signs out of the VPN application, ensure that the iOS profile is uninstalled.

Swift

import SudoVPN

do {
    if try await vpnClient.isProfileInstalled() {
        try await vpnClient.uninstallProfile()
    }
} catch {
    // errors returned specifically by the profile management interface include:
    // SudoVPNError.profileStale: the profile has been changed since last read
    // SudoVPNError.profileReadWriteFailed: the system was unable to read or write the profile
    // SudoVPNError.unknown: an unexpected or unknown error occurred when uninstalling the profile (includes an error message)
}
try await userClient.signOut()

Integrate the Android SDK

The Android SDK is compatible with Android 6 (API level 23) and above.

To gain access to the Android SDK and Android sample app providing a reference for integrating the SDK, please contact us.

Client Initialization

In order to instantiate a VPN client, make sure you have followed instructions for Getting Started and User SDK (see Prerequisities above)

To instantiate a client in your application, add the following:

Kotlin

val userClient = // ... see "Users" docs

val vpnClient = SudoVPNClient.builder()
    .setContext(appContext)
    .setSudoUserClient(userClient)
    .build()

You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.

Integrate the JS SDK

To gain access to the JS SDK for use on Windows or MacOS (Intel or Apple silicon), please contact us.

Client Initialization

When setting up on macOS, ensure that you include a PersonalVPNentitlement capability on the application id.

To use the VPN SDK in a Web or Node.js project, you must add @sudoplatform/sudo-vpn and @sudo-platform/sudo-vpn-provider as dependencies to your project. This provider package provides native binaries for 64-bit Windows, and Intel and Apple silicon macOS.

yarn add '@sudoplatform/sudo-vpn'
yarn add '@sudoplatform/sudo-vpn-provider'
# or
npm install --save '@sudoplatform/sudo-vpn'
npm install --save '@sudoplatform/sudo-vpn-provider'

In order to instantiate a VPN client, make sure you have followed instructions for Getting Started, User SDK and Sudo Entitlements SDK (see Prerequisites above).

To instantiate and initialize a client in your application, add the following:

Typescript

import { DefaultSudoVPNClient } from '@sudoplatform/sudo-virtual-cards'
import { DefaultSudoKeyManager } from '@sudoplatform/sudo-common'
import { DefaultSudoUserClient } from '@sudoplatform/sudo-user'
import { WebSudoCryptoProvider } from '@sudoplatform/sudo-web-crypto-provider'
// OR
import { NativeSudoCryptoProvider } from '@sudoplatform/sudo-native-crypto-provider'

const sudoUserClient = new DefaultSudoUserClient(/* refer to Users documentation */)
const sudoKeyManager = environment == 'web' ? /* if using browser 'secure storage' */
    new WebSudoCryptoProvider('your.keymanager.namespace', 'your.servicename') :
    new NativeSudoCryptProvider('your.keymanager.namespace', 'your.servicename')
const logPath = 'your path to log files'

const vpnClient = new DefaultSudoVpnClient({
    userClient,
    logPath,
    sudoKeyManager
)

You only need one client instance for a given user per device. Instantiating multiple clients with the same configuration and using them at the same time may cause unexpected runtime errors to occur.

Client Preparation

Once the user has been entitled, call sudoVpnClient.registerWithService() to complete the registration process and permit access to all vpnClient interfaces.

Entitlement Redemption

Before VPN SDK APIs can be called, the user must be entitled. To ensure the user is entitled first call the redeemEntitlements API in the Sudo Entitlements SDK.