Setup

Installation of the service, basic methods and examples of their use.

Getting Started

1. Sign in at pango-cloud.com.

2. Create a project and use a name for your project as a Public key. Private key is optional.

3. Use SDK where carrierId equals given Public Key and backend url equals default SDK url or url provided by Pango team.

Note that at this time, it is not possible for users to create their own accounts directly if they do not already have an account established with us. Please contact your sales representative to initiate account creation as part of the project and client onboarding process or contact us. We apologize for any inconvenience.

Install Unified SDK service

Run the commands below from the directory where SDK service executable is located.

Default installation

UnifiedSDK.Service.exe -i "ServiceName"

where:

• -i "ServiceName" - command to register UnifiedSDK service in the system with the name ServiceName.

During this call:

1. Service executable file will be registered as windows service with specified name (ServiceName).

2. Service will create the configuration file into the default folder "C:\ProgramData\UnifiedSDK.Service".

3. Service will use default fixed names for the command and event pipes - UnifiedSDKVPNCommandPipe/UnifiedSDKVPNEventPipe.

If several service instances are installed this way on one device, it can cause collisions and incorrect interaction between the client (UnifiedSDK Core) and the host (UnifiedSDK service).

This installation option is suitable for testing, but use in Production, please use the installation options below.

Static pipe names installation

UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -c "CommandPipeName" -e "EventPipeName"

where:

• -d "c:\ProgramData\MyApp" - configure path to the data folder.

• -c "CommandPipeName" - command pipe name.

• -e "EventPipeName" - event pipe name.

We recommend to specify -d option to avoid possible conflicts with other applications using the same data folders.

Also we recommend to specify -c and -e options to avoid possible conflicts with other applications using the same pipe names.

During this call:

1. Service executable file will be registered as windows service with specified name (ServiceName).

2. Service will create the configuration file into the specified -d folder "c:\ProgramData\MyApp".

3. Service will use specific names for the command and event pipes - CommandPipeName/EventPipeName.

Dynamic pipe names installation

UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -dpn "HKEY_LOCAL_MACHINE\SOFTWARE\MyApp"

where:

• -dpn "HKEY_LOCAL_MACHINE\SOFTWARE\MyApp" - enable dynamic pipe names mode and place the generated names to the specified registry key path.

During this call:

1. Service executable file will be registered as windows service with specified name (ServiceName).

2. Service will create the configuration file into the specified -d folder "c:\ProgramData\MyApp".

3. Service will create dynamic names for the command and event pipes itself and save them in the Windows registry at the specified path.

In this case you must provide same registry path to SDK instance.

You don't need to remove existed service before installation. UnifiedSDK service will remove existed itself.

Additional information about command line arguments can be found there:

Service command line arguments

If you use a self-contained UnifiedSDK service then you don't need to install a runtime.

Otherwise you need to install .NET 8.0 Desktop Runtime.

Set up UnifiedSDK Core

Add UnifiedSDK.Core.dll/ UnifiedSDK.Core.net48.dll to your project.

Create UnifiedSDK.Core.SDK class instance

Default

C#

var sdk = new SDK();

C++

auto sdk = gcnew SDK();

In this case SDK will use default fixed names for the command and event pipes - UnifiedSDKVPNCommandPipe/UnifiedSDKVPNEventPipe.

Using CreateWithFixedNaming PipeOptions

C#

var pipeOptions = PipeOptions.CreateWithFixedNaming("CommandPipeName", "EventPipeName");
var sdk = new SDK(pipeOptions, MessageFormat.JSON, logger);

C++

auto pipe_options = PipeOptions::CreateWithFixedNaming("CommandPipeName", "EventPipeName");
auto sdk = gcnew SDK(pipe_options, MessageFormat::JSON, logger);

In this case SDK will use specific names for the command and event pipes - CommandPipeName/EventPipeName.

Using CreateWithDynamicNaming PipeOptions

C#

var pipeOptions = PipeOptions.CreateWithDynamicNaming("HKEY_LOCAL_MACHINE\SOFTWARE\MyApp");
var sdk = new SDK(pipeOptions, MessageFormat.JSON, logger);

C++

auto pipe_options = PipeOptions::CreateWithDynamicNaming("HKEY_LOCAL_MACHINE\SOFTWARE\MyApp");
auto sdk = gcnew SDK(pipe_options, MessageFormat::JSON, logger);

In this case SDK will use the command and event pipe names that were created during the service installation with the -dpn command line argument.

Initialize the SDK

Initialize the SDK by sending an initialization request to the UnifiedSdkService with the required parameters: - Backend URI: The URL of the backend API. - AppVersion: The version of your application. - CarrierId: The unique public key. - DeviceId: The device ID. - DeviceName: The device name. - [Optional] Reserve URIs: Optional reserve backend server URIs. By default: null. - [Optional] EventMessageFormat: The format of the event messages from UnifiedSdkService (XML or JSON). By default: MessageFormat.JSON. - [Optional] Required events from UnifiedSdk service that will be sent by the event pipe. By default: ServiceEvents.Default (StateChanged | ErrorOccurred | TrafficChanged | ProcessExited). - [Optional] PrependDeviceIdWithCarrierId: A value indicating whether to prepend device ID with carrier ID. - [Optional] PreventDeviceIdEncode: A value indicating whether to prevent device ID encode

The parameter AppVersion should contain four hierarchical numeric components: Major, Minor, Build, and Revision, with validation allowing 2 digits for the Major component and 3 digits for the Minor and Build components.

Note, that Hydra protocol has some additional events. If you want to receive all possible events for the Hydra tunnel, then you can use ServiceEvents.HydraEvents (StateChanged | ErrorOccurred | TrafficChanged | ProcessExited | HydraProcessExiting | HydraUnsafeBlockedResource | HydraFireshieldDomainBlocked | HydraSocketCreated | HydraSocketClosed) or you can specify your own list of the events.

C#

var initRequest = new InitializeRequest
{
    BaseUri = backendAddress,
    ReserveUris = [.. reserveAddresses.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries)],
    AppVersion = appVersion,
    CarrierId = carrierId,
    DeviceId = deviceId,
    DeviceName = Environment.MachineName,
    EventMessageFormat = MessageFormat.JSON,
    Events = ServiceEvents.HydraEvents,
};

var initResponse = await sdk.InitializeAsync(initRequest).ConfigureAwait(false);

C++

auto init_request = gcnew InitializeRequest();
init_request->BaseUri = backend_url;
init_request->AppVersion = "1.0.0.0";
init_request->CarrierId = carrier_id;
init_request->DeviceId = device_id;
init_request->DeviceName = Environment::MachineName;
init_request->EventMessageFormat = MessageFormat::JSON;

auto init_response = sdk->Initialize(init_request);

An example response looks as follows:

{
    "Message": "Ok",
    "Result": "Ok"
}    

Make sure to call the Initialize/InitializeAsync methods before using any other SDK methods.

SDK has hardcoded PROD reserve addresses by default. You need to use empty collection of reserve addresses when you want to avoid this behavior.

More details about backend addresses configuration can be found there:

Backend URL Configuration

DeviceId configuration

To find detailed information about generating a unique Device Identifier, please refer to this page.

Generating a Unique Device Identifier

The DeviceId used for Backend requests has a default format of <carrier_id>_<device_id>, which is then encoded to base64. The CarrierId and DeviceId are provided as parameters in the InitializeRequest.

However, the InitializeRequest includes two additional settings that allow you to control the generation of the DeviceId:

• PreventDeviceIdEncode - This setting indicates whether the DeviceId should be encoded to base64. If set to true, the DeviceId will be used as-is without base64 encoding.

• PrependDeviceIdWithCarrierId - This setting indicates whether the DeviceId should be prepended with the CarrierId. If set to true, the CarrierId will be added to the beginning of the DeviceId.

var initRequest = new InitializeRequest
{
    BaseUri = backendAddress,
    ReserveUris = [.. reserveAddresses.Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries)],
    AppVersion = appVersion,
    CarrierId = carrierId,
    DeviceId = deviceId,
    PrependDeviceIdWithCarrierId = true, // Optional, enabled by defaul
    PreventDeviceIdEncode = false, // Optional, disabled by default
    DeviceName = Environment.MachineName,
    EventMessageFormat = MessageFormat.JSON,
    Events = ServiceEvents.HydraEvents,
};

var initResponse = await sdk.InitializeAsync(initRequest).ConfigureAwait(false);

Authentication

Pango Partner VPN Backend supports OAuth authentication with a partner's OAuth server as the primary authentication method.

Steps to Implement OAuth

1. Deploy and configure the OAuth service. Ensure that the service is publicly available on the Internet.

2. Configure the Partner Backend to use the OAuth service.

3. Implement client OAuth for your application.

4. Retrieve the access token in the client app. This token will be used to initialize and sign in.

Authentication method types

• AuthenticationMethod.Anonymous;

• AuthenticationMethod.OAuth

• AuthenticationMethod.Firebase

• Custom Authentication

Login Implementation Example

var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous,
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

The parameter (token) can be null only when using the Anonymous authentication method.

An example response looks as follows:

{
    "Message": "OK",
    "Result": "Ok",
    "UserId": "12345678",
    ...
}

Custom Authentication

Custom Authentication allows you to integrate your existing authentication system with our cloud platform. Instead of using a predefined authentication method such as google, facebook, or oauth, you can pass a custom string identifier to indicate your preferred authentication mechanism.

To implement Custom Authentication:

1. Replace the authentication method enum value with a string that uniquely identifies your authentication system, such as your company name or a specific identifier.

2. Obtain a token (TOKEN) from your authentication system.

3. Pass this custom string and the token received from your authentication system as parameters to the LoginAsync method.

Our team will work closely with you to customize the authentication method to meet your specific requirements. This will involve technical meetings and exchanging documentation to ensure a seamless integration with your existing authentication system.

Example login implementation using Custom Authentication:

var loginRequest = new LoginRequest
{
    Method = "YourCustomAuthenticationIdentifier",
    Token = TOKEN,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

Updating the SDK

Follow these steps to update the Unified SDK:

1. (Optional) Stop the current SDK service.

2. Download the latest version of the Unified SDK.

Contact your account manager to obtain the download link for the latest Windows SDK.

1. Reinstall the SDK service by running the following command:

UnifiedSDK.Service.exe -i "ServiceName" -d "c:\ProgramData\MyApp" -c "CommandPipeName" -e "EventPipeName"

You don't need to remove existed service before installation. UnifiedSDK service will remove existed itself.

1. (Optional) Start the Unified SDK service.

Always reinstall the SDK service if you modify any installation parameters to ensure the changes take effect.

Uninstalling the SDK

To uninstall the SDK, run the following command:

UnifiedSDK.Service.exe -u "ServiceName"

App is responsible to install and remove the NetFilter driver on app install/uninstall.

SDK is responsible to start and stop NetFilter driver on SDK service Init and service stop.