VPNWholesaler.com multi-platform in-app VPN SDK

Unified in-app VPN SDK's for Microsoft Windows Vista+, Android 4.4+, Mac OS 10.7+, iOS 9.0+, Ubuntu Linux LTS 18.04+. Earlier OS versions can be supported as well by request. Please contact [email protected] to receive your own API key.

Copyright © 2019 VPNWholesaler.com. All rights reserved.

Content

  1. Getting started
    1. Windows C++
    2. Windows C#
    3. OS X
    4. Android
    5. iOS
    6. Linux Ubuntu
  2. Generic interface
    1. Initialize SDK
    2. Finalize SDK
    3. Send command
  3. SDK Commands
    1. Login
    2. Get servers list (Deprecated)
    3. Get servers list by geolocation
    4. Get servers list by country
    5. Check internet connection
    6. Get device ID
    7. Check open port
    8. Set API domain
    9. Set API key
    10. Get ping
    11. Check AES support
    12. Set encryption
    13. Enable or disable IO counter
    14. Get current profile
    15. Get account type
    16. Get account credentials
    17. Get account expiration date
    18. Set XOR mode
    19. Set logger mode
    20. Start VPN connection
    21. Stop VPN connection
    22. Get VPN status
    23. Add client
    24. Remove client
    25. Reset password
    26. Enable IKEv2 Mode
    27. Start IKEv2 VPN connection
    28. Stop IKEv2 VPN connection
    29. Get IKEV2 VPN status
    30. Check TAP adapter status
    31. Logout
    32. Switch VPN server
    33. Disable IPv6
    34. Set Binary path
    35. Change Plan
    36. Set VPN Type

1. Getting started

1. Windows C++

Minimum OS version supported: Windows XP

Development tools recommended: Visual Studio 2015 - Windows XP (v140_xp)

To add SDK static lib to your project:

  1. Download the static library from Google Drive
  2. Unpack downloaded archive to a folder.
  3. Find "kucore.lib" and "CoreAPI.h" files.
  4. Place "kucore.lib" to a folder that contains the other static libraries of your project, or alternatively create a new folder named "Libs" in your project directory and place the file there.
  5. Place "CoreAPI.h" to your project's folder that contains the other header files.
  6. Add new input dependency "CoreAPI.h" in your linker. For example, in MS Visual Studio: Project->Properties->Linker->Input->Additional Dependencies.
  7. Add #include "CoreAPI.h" to the file where you plan to use the SDK commands.
2. Windows C#

.Net Framework supported: 3.5, 4.5

Development tools recommended: Visual Studio 2015

Please follow the steps below to use SDK as a part of a .NET project:

  1. Download dynamic library with dependencies from Google Drive

  2. Define callback signature. This callback will be invoked from SDK when request result is ready. Please note that all operations in the SDK are called asynchronously and callback is invoked in the thread associated with SDK.

    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
public delegate bool Callback([MarshalAs(UnmanagedType.LPStr)]string Mesg);

Callback callback = new Callback(CallbackHandler);

public bool CallbackHandler(String value)
{
    Console.WriteLine(‘callback data = ‘ + value);
}

  3. Import main SDK methods from DLL:

    [DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]
public static extern void CmdProc(String param);

[DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]

public static extern int InitOVSCore([MarshalAs(UnmanagedType.FunctionPtr)] Callback callbackPointer, String ovpn_path, bool isIKEv2Mode);
[DllImport("kucore.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)]
public static extern void FinalizeOVSCore();

  4. Use the SDK methods in the same manner as a C++ project

Please refer to a Sample C# In-app VPN SDK Demo Project and Instructions

3. OS X

Minimum OS version supported: OS X 10.7

Development tools recommended: X Code 9.4

To add SDK static lib to your project:

  1. Download static library from Google Drive
  2. Unpack downloaded archive to your project's folder
  3. Add libkucore.a file in Linked Framework and Libraries in project General setting page
  4. Add #include "CoreAPI.h" to the file where you are going to use SDK commands.
4. Android

Minimum OS version supported: Android KitKat API 19

Development tools recommended: Android Studio

To add SDK library to your project:

  1. Download library from Google Drive
  2. Unpack downloaded archive to libs subfolder of your application

  3. Add the following lines to your application build.gradle:

    implementation fileTree(include: ['vpnsdk-release.aar'], dir: 'libs')
implementation 'com.squareup.retrofit2:retrofit:2.3.0'
implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
implementation 'com.squareup.okhttp3:logging-interceptor:3.9.1'
implementation 'com.google.code.gson:gson:2.8.0'

  4. Add import com.keenmedia.keenowvpnsdk.VPNSDK; to main activity source file.

  5. Initialize SDK in Activity OnCreate handler:

    VPNSDK.InitOVSCore(new VPNSDK.OVSNotifyCB() {
    @Override
    public void onNotify(String s) {

    }
}, this);
4. iOS

Language recommended: Swift

  1. Download library from Google Drive

  2. Unpack downloaded archive

  3. Create new application for iOS using XCode

  4. Add VPNSDK.framework to Embedded Binaries section on General tab

  5. Turn on Personal VPN capability on Capabilities tab

  6. Import SDK in your main view controller:

    import VPNSDK

  7. Implement OVSNotifyDelegate interface in the view controller class:

    func OVSNotifyCB(_ notify_code: OVS_NOTIFY_CODES, _ err_code: OVS_ERROR_CODES, _ data: String?) { }

  8. Intialize SDK in viewDidLoad method of your main view:

    vpnsdk = VPNSDK()
vpnsdk.InitOVSCore(self)

  9. To call SDK methods there is a vpnsdk.CmdProc method

You can find example application here

4. Ubuntu Linux
  1. Download library from Google Drive
  2. Unpack downloaded archive

  3. Library can be used in 2 ways:

    a. As a static library linked to the application

    b. As a separate process listening for commands on localhost

  4. To use it as a static library it is necessary to link project towards lubkucore.a and add #include "CoreAPI.h" to the file where you are going to use SDK commands.

  5. To use it as a separate process it is necessary to run ovscore binary as a daemon:

    ovscore -d

    It will listen for commands on the TCP port 6733. You can find the example of client application in ovsconsole.cpp

2. Generic interface

1. InitOVSCore

C Signature: int InitOVSCore(callback, ovpn_path, isIKEv2Mode=false)

Java signature: int InitOVSCore(OVSNotifyCB callback, Activity context)

Android usage example

OS X usage example

Where:

callback - instance of OVSNotifyCB interface context - application activity

Parameters
callback - reference to callback function with following signature:

void (char* notify_data)

All operations in SDK are called asynchronously, and therefore this callback receives all responses from SDK. All responses are encoded as JSON and described at the relevant sections.

In general any response has the following structure:

{
  "code": integer
  "err": integer
  "data": { object }
}

Where:

code is notification code depending on invoked command or event. See appendix 2 for full list of codes or the SDK Commands and Events section.

err is error code. See appendix 3.

data depends on notification code. For detailed description see specific command description

ovpn_path - path to ovpn binary. Required on all platforms except:

On Android could be omitted due Android SDK includes built-in binaries for all major process architectures.

On Windows could be omitted only if IKEv2 Mode is enabled.

isIKEv2Mode - Use IKEv2 protocol instead of default OpenVPN protocol. Supported only on Windows. On other platforms it is ignored.

Return value
int - returns 0 if SDK was intialized sucessfully and other value in case of failure

Description

Intializes SDK with callback and sets necessary path to OpenVPN binary.

2. void FinalizeOVSCore()

Android usage example

OS X usage example

Parameters
None

Return value
None

Description

Unloads SDK and finalizes all running threads.

3. void CmdProc(szCmdData)

Android usage example

OS X usage example

Parameters
szCmdData - JSON encoded into string. It should be of the following structure:

{
    "cmd": int,
    "data: { Command parameters }
}

cmd is the command code. All codes are predefined as constants.

data is an object with structure corresponding to the command

Return value
None

Description

Asynchronously sends command to SDK. Command result will be returned by calling callback provided on initialization.

3. SDK Commands

1. Login
Code: OVS_CMD_LOGIN
Notification: OVS_NOTIFY_LOGIN
Possible errors: OVS_ERR_WEB_API, OVS_ERR_RESP_INVALID, OVS_ERR_LOGIN_FAILED
Login required: No

Android usage example

OS X usage example

Input
Data member of `cmd_data` parameter should have the following structure:

{
    "username": "",
    "password": ""
}

Where:

username - end-user's account email

password - end-user's password

Sucessful response
code is OVS_NOTIFY_LOGIN

err is OVS_ERR_OK

data contains information about user account and account status.

Deprecated variant (being returned on Windows)

 {
    "result": "success",
    "clientid": "2",
    "serviceid": null,
    "pid": null,
    "domain": null,
    "totalresults": 3,
    "startnumber": 0,
    "numreturned": 3,
    "products": {
      "product": [
        {
          "id": 78013,
          "clientid": 2,
          "orderid": 78065,
          "pid": 16,
          "regdate": "2018-07-19",
          "name": "24 Months",
          "translated_name": "24 Months",
          "groupname": "Keenow",
          "translated_groupname": "Keenow",
          "domain": "",
          "dedicatedip": "",
          "serverid": 0,
          "servername": "",
          "serverip": null,
          "serverhostname": null,
          "suspensionreason": "",
          "firstpaymentamount": "0.00",
          "recurringamount": "0.00",
          "paymentmethod": "amazonsimplepay",
          "paymentmethodname": "FREE",
          "billingcycle": "Biennially",
          "nextduedate": "2020-07-19",
          "status": "Active",
          "username": "some user name",
          "password": "some password",
          "subscriptionid": "",
          "promoid": 0,
          "overideautosuspend": 0,
          "overidesuspenduntil": "0000-00-00",
          "ns1": "",
          "ns2": "",
          "assignedips": "",
          "notes": "",
          "diskusage": 0,
          "disklimit": 0,
          "bwusage": 0,
          "bwlimit": 0,
          "lastupdate": "0000-00-00 00:00:00",
          "customfields": {
            "customfield": []
          },
          "configoptions": {
            "configoption": []
          }
        }
      ]
    },
    "debug": "on"
  }

The most important response is the products array which contains all products owned by user. The most important entry is status field which contains string Active for active products.

New variant (being returned on Android, iOS and OS X)

{
    "nextduedate":"2020-07-19",
    "password":"",
    "status":"Active",
    "username":"",
    "name":"24 Months",
    "email":"",
    "debug":true,
    "billingcycle": "Monthly"
}

Here is being returned only first active product.

Failed response
code is to OVS_NOTIFY_LOGIN

err is corresponding error code

data has message property with human readable error description

Description

Tries to login to management interface and retrieves registered products assosiated with given user.

2. Get servers list (Deprecated)
Code: OVS_CMD_GET_SERVLIST
Notification: OVS_NOTIFY_GET_SERVLIST
Possible errors: OVS_ERR_WEB_API
Login requiered: No

Android usage example

OS X usage example

Input
Data member of data parameter could have the following structure:

{
    "premium": true | false
}

Where:

premium - optional flag to select between premium and non-premium server list. true if omitted

Sucessfull response
code is OVS_NOTIFY_GET_SERVLIST

err is OVS_ERR_OK

data contains available server list. It includes human readable server names properties as objects, and array of objects respresenting each server's parameters.

Example

{
    "U.S. New York": [
      {
        "ip": "104.192.3.90"
      },
      {
        "tcp_ports": [
          "1194",
          "8080",
          "8181"
        ]
      },
      {
        "udp_ports": [
          "1194",
          "8080",
          "8181"
        ]
      },
      {
        "flag": "url/us.png"
      }
Available server parameters are:
  1. ip - server IP address
  2. tcp_ports - available TCP ports
  3. upd_ports - available UDP ports
  4. flag - server flag url.

Failed response
code is to OVS_NOTIFY_GET_SERVLIST

err is corresponding error code

data is empty object

Description

Requests available VPN servers.

3. Get servers list by geolocation
Code: OVS_CMD_GET_SERVLIST_BYGEO
Notification: OVS_NOTIFY_GET_SERVLIST_BYGEO
Possible errors: OVS_ERR_WEB_API
Login requiered: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter could have the following structure:

{
    "premium": true | false
}

Where:

premium - optional flag to select between premium and non-premium server list. true if omitted

Sucessfull response
code is OVS_NOTIFY_GET_SERVLIST_BYGEO

err is OVS_ERR_OK

data contains available server list. It includes server IP address properties as objects, and array of objects respresenting each server's parameters.

Example

[
    {
        "ip": "192.111.132.43",
        "name": "Canada Vancouver",
        "hostname": "canada-vancouver.keenvpn.me",
        "country": "CA",
        "cipher": [
            "BF-CBC",
            "AES-128-CBC",
            "AES-128-GCM",
            "AES-256-CBC",
            "AES-256-GCM"
        ],
        "cipher_tcp_ports": [
            "1194",
            "8080",
            "8181",
            "1299",
            "1199",
            "8989",
            "8289",
            "1399",
            "9989"
        ],
        "cipher_udp_ports": [
            "1194",
            "8080",
            "8181",
            "1299",
            "1199",
            "8989",
            "8289",
            "1399",
            "9989"
        ],
        "lz4": true,
        "lz4_ports": [
            "1149",
            "4600",
            "5500"
        ],
        "xor": true,
        "xor_ports": [
            "443",
            "80",
            "1499",
            "9919",
            "8332",
            "30303",
            "18080",
            "8081",
            "3333"
        ],
        "smart_dns_id": "14",
        "flag": "https:\/\/client-api.keenow.com\/serverlist\/flags\/new_res\/ca.png",
        "protocols": {
            "l2tp": true,
            "openvpn": true,
            "ikev2": true,
            "wg": true,
            "wg_pubkey": "SOME_WIREGUARD_PUBLIC_KEY"
        },
        "lat": "49.2366",
        "lon": "-122.8521",
        "distance": 10251.369694275
    }
]
Server description has following parameters:
  1. ip - server ip address
  2. name - human readable server name
  3. country - country code
  4. hostname - server host name
  5. cipher - array of available ciphers
  6. cipher_tcp_ports - available TCP ports
  7. cipher_upd_ports - available UDP ports
  8. lz4 - LZ4 support
  9. lz4_port - port where LZ4 is supported
  10. xor - XOR support
  11. xor_ports - ports where XOR is supported
  12. smart_dns_id
  13. flag - server flag url.
  14. protocols - supported protocols: L2TP, OpenVPN, IKEv2, WireGuard
  15. lat - server latitude
  16. lon - server longitude
  17. distance - distance to server

Failed response
code is to OVS_NOTIFY_GET_SERVLIST_BYGEO

err is corresponding error code

data is empty object

Description

Requests available VPN servers and sorts them from nearest to farest based on end-user's IP address.

4. Get servers list by country
Code: OVS_CMD_GET_SERVLIST_BYCOUNTRY
Notification: OVS_NOTIFY_GET_SERVLIST_BYCOUNTRY
Possible errors: OVS_ERR_WEB_API
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
    "country": "",
    "premium": true | false
}

Where:

country - country code premium - optional flag to select between premium and non-premium server list. true if omitted

Sucessfull response
code is OVS_CMD_GET_SERVLIST_BYCOUNTRY

err is OVS_ERR_OK

data contains available server list. It include server IP address properties as objects, and array of objects respresenting each server's parameters.

Example

[
    {
        "ip": "192.111.132.43",
        "name": "Canada Vancouver",
        "hostname": "canada-vancouver.keenvpn.me",
        "country": "CA",
        "cipher": [
            "BF-CBC",
            "AES-128-CBC",
            "AES-128-GCM",
            "AES-256-CBC",
            "AES-256-GCM"
        ],
        "cipher_tcp_ports": [
            "1194",
            "8080",
            "8181",
            "1299",
            "1199",
            "8989",
            "8289",
            "1399",
            "9989"
        ],
        "cipher_udp_ports": [
            "1194",
            "8080",
            "8181",
            "1299",
            "1199",
            "8989",
            "8289",
            "1399",
            "9989"
        ],
        "lz4": true,
        "lz4_ports": [
            "1149",
            "4600",
            "5500"
        ],
        "xor": true,
        "xor_ports": [
            "443",
            "80",
            "1499",
            "9919",
            "8332",
            "30303",
            "18080",
            "8081",
            "3333"
        ],
        "smart_dns_id": "14",
        "flag": "https:\/\/client-api.keenow.com\/serverlist\/flags\/new_res\/ca.png",
        "protocols": {
            "l2tp": true,
            "openvpn": true,
            "ikev2": true
        },
        "lat": "49.2366",
        "lon": "-122.8521",
        "distance": 10251.369694275
    }
]
Server description has following parameters:
  1. ip - server ip address
  2. name - human readable server name
  3. country - country code
  4. hostname - server host name
  5. cipher - array of available ciphers
  6. cipher_tcp_ports - available TCP ports
  7. cipher_upd_ports - available UDP ports
  8. lz4 - LZ4 support
  9. lz4_port - port where LZ4 is supported
  10. xor - XOR support
  11. xor_ports - ports where XOR is supported
  12. smart_dns_id
  13. flag - server flag url.
  14. protocols - supported protocols: L2TP, OpenVPN, IKEv2
  15. lat - server latitude
  16. lon - server longitude
  17. distance - distance to server

Failed response
code is to OVS_NOTIFY_GET_SERVLIST_BYCOUNTRY

err is corresponding error code

data is empty object

Description

Requests available VPN servers and sorts them from nearest to farest based on given country.

5 Check internet connection
Code: OVS_CMD_CHECK_INTERNET
Notification: OVS_NOTIFY_CHECK_INTERNET
Possible errors: OVS_ERR_INTERNET_DISCONNECTED
Login required: No

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_CHECK_INTERNET

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_CHECK_INTERNET

err is OVS_ERR_INTERNET_DISCONNECTED

data is null

Description

Attempts to make connection to API server. If connection failed, returns OVS_ERR_INTERNET_DISCONNECTED error.

6. Get device ID
Code: OVS_CMD_GET_DEVICEID
Notification: OVS_NOTIFY_GET_DEVICEID
Possible errors:
Login required: No

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_DEVICEID

err is OVS_ERR_OK

data is an object of following structure:

{
    "device_id" : ""
}

where device_id is a device identifier where application is being run.

Description

Returns device identifier where application is being run.

7. Check open port
Code: OVS_CMD_CHECK_PORT
Notification: OVS_NOTIFY_CHECK_PORT
Possible errors: OVS_ERR_PORT_CLOSED
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
    "ip_addr": "1.1.1.1",
     "proto": "tcp",
    "port": 1194
}

Where:

ip_addr - host to connect

proto - always should be tcp

port - port to connect

Sucessfull response
code is OVS_NOTIFY_CHECK_PORT

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_CHECK_PORT

err is OVS_ERR_PORT_CLOSED

data is null

Description

Attempts to make connection to specified host and port. If connection failed, returns OVS_ERR_PORT_CLOSED error.

8. Set API domain
Code: OVS_CMD_SET_API_DOMAIN
Notification: OVS_NOTIFY_SET_API_DOMAIN
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
    "api_domain": "test_domain.com"
}

Where:

api_domain - domain of API server

Sucessfull response
code is OVS_NOTIFY_SET_API_DOMAIN

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_SET_API_DOMAIN

err is OVS_ERR_MISSING_PARAMS

data is null

Description

Initialises API domain. Please ask VPNWholesaler.com for your own dedicated API domain.

9. Set API key
Code: OVS_CMD_SET_API_KEY
Notification: OVS_NOTIFY_SET_API_KEY
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "api_key": "test_api_key"
}

Where:

api_key - API key to set

Sucessfull response
code is OVS_NOTIFY_SET_API_KEY

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_SET_API_KEY

err is OVS_ERR_MISSING_PARAMS

data is null

Description

Initializes API key required for new user creation. Please ask VPNWholesaler.com for your own dedicated API key.

10. Get ping
Code: OVS_CMD_GET_PING_RESULT
Notification: OVS_NOTIFY_GET_PING_RESULT
Possible errors: OVS_ERR_MISSING_PARAMS, OVS_ERR_WEB_API
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "ip_addr": "1.1.1.1"
}

Where:

ip_addr - IP address of VPN server.

Sucessfull response
code is OVS_NOTIFY_GET_PING_RESULT

err is OVS_ERR_OK

data contains the following object:

 {
    "ip_addr": "45.32.158.20",
    "time": 341
 }

Where:

ip_addr - IP address provided

time - ping time in msec.

Failed response
code is to OVS_NOTIFY_GET_PING_RESULT

err is corresponding error code

data is null

Description

Attempts to check connection to given VPN server and, if connection could be established, measures ping time.

11. Check AES support
Code: OVS_CMD_CHECK_AES
Notification: OVS_NOTIFY_CHECK_AES
Possible errors:
Login required: No

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_CHECK_AES

err is OVS_ERR_OK

data is an object of following structure:

{
    "AES_Support" : true|false
}

where AES_Support is a boolean value

Description

Checks if device has support of AES encryption

12. Set encryption
Code: OVS_CMD_SET_ENCRYPTION
Notification: OVS_NOTIFY_SET_ENCRYPTION
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "cipher": "CBC"
}

Where:

cipher - cipher name. Supported ciphers could be retrived by one of the server list functions listed above.

Sucessfull response
code is OVS_NOTIFY_SET_ENCRYPTION

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_SET_ENCRYPTION

err is corresponding error code

data is null

Description

Sets cipher for VPN connection

13. Enable or disable IO counter
Code: OVS_CMD_SET_IOCOUNT
Notification: OVS_NOTIFY_SET_IOCOUNT
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "status": true|false
}

Where:

status - status of counter

Sucessfull response
code is OVS_NOTIFY_SET_IOCOUNT

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_SET_IOCOUNT

err is corresponding error code

data is null

Description

Enables of disables IO counter. When IO counter is enabled, SDK will send notifications with code OVS_NOTIFY_VPN_IOCOUNT with data parameter of the following structure:

{
    "data_in": 0,
    "speed_in": 0,
    "data_out": 0,
    "speed_out": 0
}

Where:

data_in - downloaded data amount

speed_in - current download speed

data_out - uploaded data amount

speed_out - current upload speed

14. Get current profile
Code: OVS_CMD_GET_CURRENT_PROFILE
Notification: OVS_NOTIFY_GET_CURRENT_PROFILE
Possible errors: OVS_ERR_VPN_DISCONNECTED
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_CURRENT_PROFILE

err is OVS_ERR_OK

data is object of the following structure:

{
    "server_ip": "45.32.158.20",
    "protocol": "tcp",
    "server_port": 1194
}

Where:

server_ip - VPN server IP address

protocol - VPN protocol

server_port - Connection port

Failed response
code is to OVS_NOTIFY_GET_CURRENT_PROFILE

err is corresponding error code

data is null

Description

Returns current VPN connection parameters like server, protocol and port. VPN should be connected.

15. Get account type
Code: OVS_CMD_GET_ACCOUNT_TYPE
Notification: OVS_NOTIFY_GET_ACCOUNT_TYPE
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_ACCOUNT_TYPE

err is OVS_ERR_OK

data is object of the following structure:

{
    "account_type": "24 Months"
}

Where:

account_type - user plan description

Description

Returns current user's plan desciption

16. Get account credentials
Code: OVS_CMD_GET_ACCOUNT_CREDENTIAL
Notification: OVS_NOTIFY_GET_ACCOUNT_CREDENTIAL
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_ACCOUNT_CREDENTIAL

err is OVS_ERR_OK

data is object of the following structure:

{
    "username": "",
    "password": ""
}

Where:

username - current user's name password - current user's password

Description

Returns current user's credentials used to connect to VPN server

17. Get account expiration date
Code: OVS_CMD_GET_ACCOUNT_EXP_DATE
Notification: OVS_NOTIFY_GET_ACCOUNT_EXP_DATE
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_ACCOUNT_EXP_DATE

err is OVS_ERR_OK

data is object of the following structure:

{
    "exp_date": "2020-12-31",
}

Where:

exp_date - current user's account expiration date in format of YYYY-MM-DD

Description

Returns current user's account expiration date

18. Set XOR mode
Code: OVS_CMD_ENABLE_XOR
Notification: OVS_NOTIFY_ENABLE_XOR
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "status": true|false
}

Where:

status - boolean value of XOR mode status.

Sucessfull response
code is OVS_NOTIFY_ENABLE_XOR

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_ENABLE_XOR

err is corresponding error code

data is null

Description

Enable or disable VPN traffic obfuscation.

19. Set logger mode
Code: OVS_CMD_SET_LOGGING
Notification: OVS_NOTIFY_SET_LOGGING
Possible errors: OVS_ERR_MISSING_PARAMS
Login required: No

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
     "status": true | false
}

Where:

status - true/false of bool

Sucessfull response
code is OVS_NOTIFY_SET_LOGGING

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_SET_LOGGING

err is corresponding error code

data is null

Description

Enable or disable log file creation. Loggin is disabled by default.

20. Start VPN connection
Code: OVS_CMD_CONNECT
Notification: OVS_NOTIFY_VPN_CONNECTING,OVS_NOTIFY_VPN_CONNECTED, OVS_NOTIFY_VPN_DISCONNECTED, OVS_NOTIFY_VPN_CONNECT_FAILED, OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Windows usage example

Input
Structure of cmd_data parameter depends on the used protocol:

OpenVPN connection:

{
    "ip_addr": "45.32.158.20",
    "proto": "tcp",
    "port": 1194,
    "ipv6_leak": 1,
    "kill_switch": 1,
    "primary":"62.210.122.43",
    "seconday":"157.55.83.218"
}

Where:

ip_addr - VPN server IP address

proto - "upd" or "tcp" protocol

port - port to connect. Available ports are returned by server list methods

ipv6_leak - enable or disable ipv6 leak prevention

kill_switch - enable or disable existing connections drop

primary - primary DNS server (used to fix DNS leak on Windows 10)

seconday - secondary DNS server (used to fix DNS leak on Windows 10)

IKEv2 connection

{
    "server_name": "server.com",
    "ipv6_leak": 1,
    "kill_switch": 1,
    "primary":"62.210.122.43",
    "seconday":"157.55.83.218"
}

server_name - VPN server Hostname

ipv6_leak - enable or disable ipv6 leak prevention

kill_switch - enable or disable existing connections drop

primary - primary DNS server (used to fix DNS leak on Windows 10)

seconday - secondary DNS server (used to fix DNS leak on Windows 10)

WireGuard connection

{
    "ip_addr": "45.32.158.20",
    "wg_pubkey": "",
    "ipv6_leak": 1,
    "kill_switch": 1,
    "primary":"62.210.122.43",
    "seconday":"157.55.83.218"
}

ip_addr - VPN server IP address

wg_pubkey - public key for wireguard server, taken from server desciption

ipv6_leak - enable or disable ipv6 leak prevention

kill_switch - enable or disable existing connections drop

primary - primary DNS server (used to fix DNS leak on Windows 10)

seconday - secondary DNS server (used to fix DNS leak on Windows 10)

Description

Start VPN connection to given server. While establishing connection SDK will notify application with the following notification when connection status is changed:

OVS_NOTIFY_VPN_CONNECTING - connection is being established

OVS_NOTIFY_VPN_CONNECTED - connection was established sucessfully

OVS_NOTIFY_VPN_DISCONNECTED - VPN was disconnected

OVS_NOTIFY_VPN_CONNECT_FAILED - VPN failed to connect

OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED - connection was dropped

Each notification has data property set to null

When using IKEv2 and WireGuard connections method SET_BINARY_PATH should be called prior to starting connection

21. Stop VPN connection
Code: OVS_CMD_DISCONNECT
Notification: OVS_NOTIFY_VPN_DISCONNECTED
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Description

Stops established VPN connection. When VPN is disconnected SDK sends OVS_NOTIFY_VPN_DISCONNECTED notification

This notification has data property set to null

22. Get VPN status
Code: OVS_CMD_GET_STATUS
Notification: OVS_NOTIFY_GET_STATUS
Possible errors:
Login required: Yes

Android usage example

OS X usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_STATUS

err is OVS_ERR_OK

data is an object of the following structure:

{
    "VPN_Status": 1
}

Where VPN_Status has one of the following values:

  1. VPN_NOTIFY_CONNECTING
  2. VPN_NOTIFY_CONNECTED
  3. VPN_NOTIFY_DISCONNECTED
  4. VPN_NOTIFY_CONN_FAILED
  5. VPN_NOTIFY_ABNORMALLY_DISCONNECTED
  6. VPN_NOTIFY_AUTH
  7. VPN_NOTIFY_ASSIGNIP
  8. VPN_NOTIFY_GETCONFIG
Description

Requests current VPN connection status.

23. Add client
Code: OVS_CMD_ADD_CLIENT
Notification: OVS_NOTIFY_ADD_CLIENT
Possible errors: OVS_ERR_MISSING_PARAMS, OVS_ERR_WEB_API, OVS_ERR_FAILED_ADD_CLIENT
Login required: No
API Key required

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
       "email": "[email protected]",
        "password": "123456",
        "countrycode": "US",
        "type": ""
}

Where:

email - user's email

password - password to set

countrycode - user's country

type - user's account plan.

type parameter depends on particular implementation, but generally can be one of following values:

  1. free
  2. trial
  3. string representing number of months.

Sucessfull response
code is OVS_NOTIFY_ADD_CLIENT

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_ADD_CLIENT

err is corresponding error code

data, depending on error, can contain object with err property with human readable description

Description

Registers client on server. Requires valid API key to be set.

24. Remove client
Code: OVS_CMD_CLOSE_CLIENT
Notification: OVS_NOTIFY_CLOSE_CLIENT
Possible errors: OVS_ERR_MISSING_PARAMS, OVS_ERR_WEB_API
Login required: No
API Key required

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
       "email": "[email protected]",
}

Where:

email - user's email

Sucessfull response
code is OVS_NOTIFY_CLOSE_CLIENT

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_CLOSE_CLIENT

err is corresponding error code

data is null

Description

Disables client's account on server. Requires valid API key to be set.

25. Reset password
Code: OVS_CMD_RESET_PASSWORD
Notification: OVS_NOTIFY_RESET_PASSWORD
Possible errors: OVS_ERR_MISSING_PARAMS, OVS_ERR_WEB_API
Login required: No
API Key required

Android usage example

OS X usage example

Input
Data member of cmd_data parameter should have the following structure:

{
       "email": "[email protected]",
}

Where:

email - user's email

Sucessfull response
code is OVS_NOTIFY_RESET_PASSWORD

err is OVS_ERR_OK

data is null

Failed response
code is to OVS_NOTIFY_RESET_PASSWORD

err is corresponding error code

data is null

Description

Initiates user password reset. If successful, the end-user shall recieve an email with new password.

26. Enable IKEv2 VPN connection mode
Code: OVS_CMD_ENABLE_IKEV2
Notification: OVS_NOTIFY_ENABLE_IKEV2
Possible errors:
Login required: Yes

Windows usage example

Input
Data member of cmd_data parameter should have the following structure:

{
    "status": true | false
}

Where:

status - enable/disable IKEv2 mode

Description

Enable IKEv2 VPN connection mode. When mode changed SDK sends OVS_NOTIFY_ENABLE_IKEV2 notification

This notification has data property set to null

27. Start IKEv2 VPN connection
Code: OVS_CMD_CONNECT_IKEV2
Notification: OVS_NOTIFY_VPN_CONNECTING,OVS_NOTIFY_VPN_CONNECTED, OVS_NOTIFY_VPN_DISCONNECTED, OVS_NOTIFY_VPN_CONNECT_FAILED, OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED
Possible errors:
Login required: Yes

Windows usage example

Input
Data member of cmd_data parameter should have the following structure:

{
    "ip_addr": "45.32.158.20",
    "server_name": "russia-st-petersburg.keenvpn.me",
    "proto": "tcp",
    "port": 1194,
    "ipv6_leak": 1,
    "kill_switch": 1,
    "primary":"62.210.122.43",
    "secondary":"157.55.83.218"
}

Where:

ip_addr - VPN server IP address

server_name - VPN server domain name

proto - "upd" or "tcp" protocol

port - port to connect. Available ports are returned by server list methods

ipv6_leak - enable or disable ipv6 leak prevention

kill_switch - enable or disable existing connections drop

primary - primary DNS server (used to fix DNS leak on Windows 10)

secondary - secondary DNS server (used to fix DNS leak on Windows 10)

Description

Start VPN connection using IKEv2 protocol to given server. While establishing connection SDK will notify application with the following notification when connection status is changed:

OVS_NOTIFY_VPN_CONNECTING - connection is being established

OVS_NOTIFY_VPN_CONNECTED - connection was established sucessfully

OVS_NOTIFY_VPN_DISCONNECTED - VPN was disconnected

OVS_NOTIFY_VPN_CONNECT_FAILED - VPN failed to connect

OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED - connection was dropped

Each notification has data property set to null

Here is the guide to create ipsec command

28. Stop IKEv2 VPN connection
Code: OVS_CMD_DISCONNECT_IKEV2
Notification: OVS_NOTIFY_VPN_DISCONNECTED
Possible errors:
Login required: Yes

Windows usage example

Input
Not required

Description

Stops established IKEv2 VPN connection. When VPN is disconnected SDK sends OVS_NOTIFY_VPN_DISCONNECTED notification

This notification has data property set to null

29. Get VPN status
Code: OVS_CMD_GET_STATUS_IKEV2
Notification: OVS_NOTIFY_GET_STATUS
Possible errors:
Login required: Yes

Windows usage example

Input
Not required

Sucessfull response
code is OVS_NOTIFY_GET_STATUS

err is OVS_ERR_OK

data is an object of the following structure:

{
    "VPN_Status": 0
}

Where VPN_Status has one of the following values:

  1. CONN_STATE_DISCONNECTED,
  2. CONN_STATE_CONNECTING,
  3. CONN_STATE_CONNECTED,
  4. CONN_STATE_DISCONNECTING
Description

Requests current VPN connection status.

30. Check TAP adapter status
Code: OVS_CMD_CHECK_TAP_ADAPTER
Notification: OVS_NOTIFY_CHECK_TAP_ADAPTER
Possible errors:
Login required: Yes

Windows usage example

Input
Not required

Sucessfull response

code is OVS_NOTIFY_CHECK_TAP_ADAPTER

err is corresponding error code

This notification has data property set to null

Where err code has one of the following values:

  1. TAP_ADAPTER_STATUS_OK
  2. TAP_ADAPTER_STATUS_NOT_INSTALLED
  3. TAP_ADAPTER_STATUS_DISABLE
Description

Requests current TAP adapter status.

31. Log out
Code: OVS_CMD_LOGOUT
Notification: OVS_NOTIFY_LOGOUT
Possible errors:
Login required: Yes

Windows usage example

OS X usage example

Input
Not required

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Requests current TAP adapter status.

32. Switch VPN server
Code: OVS_CMD_SWITCH_VPN_SERVER
Notification: OVS_NOTIFY_SWITCH_VPN_SERVER
Possible errors:
Login required: Yes

Windows usage example

OS X usage example

Input

Data member of cmd_data parameter should have the following structure:

{
    "ip_addr": "45.32.158.20",
    "server_name": "russia-st-petersburg.keenvpn.me"
}

Where:

ip_addr - VPN server IP address

server_name - VPN server domain name

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Switch VPN server

33. Disable IPv6
Code: OVS_CMD_DISABLE_IPV6
Notification: OVS_NOTIFY_DISABLE_IPV6
Possible errors:
Login required: Yes

Windows usage example

Input
Not required

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Disable IPv6

34. Set Binary Path
Code: OVS_CMD_SET_BINARY_PATH
Notification: OVS_NOTIFY_SET_BINARY_PATH
Possible errors:
Login required: No

Windows usage example

OS X usage example

Input
data is an object of the following structure:

{
    "path": "/folder/with/binaries"
}

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Set path where SDK should search StrongSwan and WireGuard binaries.

Folder with binaries should have the following structure:

/folder/with/binaries
    /wireguard
        /wg
        /wg-quick3
        /wg-quick5
        /wireguard-go
    /ipsec
        /sbin
            /ipsec
            /swanctl
35. Change Plan
Code: OVS_CMD_CHANGE_PLAN
Notification: OVS_NOTIFY_CHANGE_PLAN
Possible errors:
Login required: Yes

Windows usage example

OS X usage example

Input
data is an object of the following structure:

{
    "email": "[email protected]",
    "type": "test"
}

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Change Plan

35. set VPN Type
Code: OVS_CMD_SET_VPN_TYPE
Notification: OVS_NOTIFY_SET_VPN_TYPE
Possible errors:
Login required: Yes

OS X usage example

Input
data is an object of the following structure:

{
    "vpn_type": 0
}

0: OpenVPN

1: IKEv2

2: WireGuard

Sucessfull response

code is OVS_ERR_OK

err is corresponding error code

This notification has data property set to null

Description

Change VPN Protocol