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.

1. Install UnifiedSDK service . Run the command from the directory where SDK service executable is located:

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

where:

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

• -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, -c and -e options to avoid possible conflicts with other applications using the same pipe names or folders.

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

Additional information about command line argumets can be found there:

Service command line arguments

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".

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.

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

2. Create UnifiedSDK.Core.SDK class instance with parameters: - Command pipe name. - Event pipe name. - Command pipe message format (XML or JSON). - [Optional] Microsoft.Extensions.Logging.ILogger<SDK> instance.

C#

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

C++

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

1. Initialize the SDK by sending an initialization request to the UnifiedSdkService with the required parameters: - Backend URI: The URL of the backend API. - Netfilter driver name: The name of the netfilter driver. - AppVersion: The version of your application. - [Optional] Reserve URIs: Optional reserve backend server URIs. By default: null. - [Optional] MessageFormat: 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).

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 initResponse = await sdk.InitializeAsync(backendUrl, netfilterName, appVersion);

C++

auto initResponse = sdk->Initialize(backendUrl, netfilterName, appVersion);

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

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
{
    CarrierId = CARRIERID,
    DeviceId = DEVICEID,
    DeviceName = Environment.MachineName,
    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
{
    CarrierId = CARRIERID,
    DeviceId = DEVICEID,
    DeviceName = Environment.MachineName,
    Method = "YourCustomAuthenticationIdentifier",
    Token = TOKEN,
};

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

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 LoginRequest.

However, the LoginRequest 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 loginRequest = new LoginRequest
{
    CarrierId = CARRIERID,
    DeviceId = DEVICEID,
    DeviceName = Environment.MachineName,
    Method = "YourCustomAuthenticationIdentifier",
    Token = TOKEN,
    PreventDeviceIdEncode = false, // Optional, disabled by default
    PrependDeviceIdWithCarrierId = true, // Optional, enabled by default
};

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.