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. This value should contains four hierarchical numeric components: major, minor, build and revision. - [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). Note, that hydra protocol has some additional event. If you wan't to receive all possible events, then you can use ServiceEvents.HydraEvents (StateChanged | ErrorOccurred | TrafficChanged | ProcessExited | HydraProcessExiting | HydraUnsafeBlockedResource | HydraFireshieldDomainBlocked | HydraSocketCreated | HydraSocketClosed) or you can specify your own list of 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 loginResponse = await this.sdk.LoginAsync(CARRIERID, DEVICEID, Environment.MachineName, AuthenticationMethod.Anonymous, null).ConfigureAwait(false);

The last 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 loginResponse = await this.sdk.LoginAsync(CARRIERID, DEVICEID, Environment.MachineName, "YourCustomAuthenticationIdentifier", TOKEN).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.