VPN Commands
Set, start and stop a VPN connection.
Set Binary Path​
Sets the path for OpenVPN, StrongSwan, Shadowsocks and WireGuard binaries.
Required step for macOS
When using the C library on macOS, SET_BINARY_PATH should be called prior starting any VPN connection.
Login required: Yes
CmdProc Code: OVS_CMD_SET_BINARY_PATH
Command number: 31
Input:
{
"path": "/folder/with/binaries"
}
path - The folder with the binaries. The folder itself should have the following structure:
folder/with/binaries/
openvpn-x86_64/
sbin/
openvpn
ipsec-x86_64/
etc/
lib/
libexec/
sbin/
wireguard-x86_64/
wg
wg-quick3
wg-quick5
wireguard-go
openvpn-arm64/
sbin/
openvpn
ipsec-arm64/
etc/
lib/
libexec/
sbin/
wireguard-arm64/
wg
wg-quick3
wg-quick5
wireguard-go
ss2/
shadowsocks2-macos-amd64
shadowsocks2-macos-arm64
Response: OVS_NOTIFY_SET_BINARY_PATH
- Success
- Failure
OVS_ERR_OK
OVS_ERR_MISSING_PARAMS
data is null
Code sample:
- macOS
void setStrongswanPath(const char *path)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_BINARY_PATH));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "path", json_object_new_string(path));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
Start VPN Connection​
Establishes a VPN connection with a given server.
Using different protocols
You can select a VPN protocol by using the Set VPN Type command.
When using the C library on macOS, SET_BINARY_PATH should be called prior starting any VPN connection.
Login required: Yes
CmdProc Code: OVS_CMD_CONNECT
Command number: 3
Input:
- OpenVPN
- IKEv2-IPSec
- WireGuard
- Shadowsocks2
{
"ip_addr": "104.192.3.90",
"proto": "tcp",
"port": 1194,
"ipv6_leak": 1,
"kill_switch": 1
}
ip_addr - VPN server's IP address
proto - Use UDP or TCP protocol
port - Use this 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
{
"server_name": "us-new-york-2.keenvpn.me",
"ip_addr": "104.192.3.90",
"ipv6_leak": 1,
"kill_switch": 1
}
server_name - VPN Server's hostname
ip_addr - VPN server's IP address
ipv6_leak - Enable or disable ipv6 leak prevention
kill_switch - Enable or disable existing connections drop
{
"ip_addr": "104.192.3.90",
"wg_pubkey": "",
"ipv6_leak": 1,
"kill_switch": 1,
"port": "3300",
"ipv6_prefix": "2600:3c03:e003:f200::"
}
ip_addr - VPN server's IP address
port - VPN server's port
wg_pubkey - Public key for the desired WireGuard server, taken from the public server list
ipv6_leak - Enable or disable ipv6 leak prevention
kill_switch - Enable or disable existing connections drop
ipv6_prefix - IPv6 address prefix from server information (Optional)
{
"ip_addr": "104.192.3.90",
"ipv6_leak": 1,
"kill_switch": 1
}
ip_addr - VPN server's IP address
ipv6_leak - Enable or disable ipv6 leak prevention
kill_switch - Enable or disable existing connections drop
Response:
This method doesn't invoke any callback. While establishing connection, the SDK will notify application with the following notifications when connection status is changed (data property is set to null):
OVS_NOTIFY_VPN_CONNECTING
OVS_NOTIFY_VPN_CONNECTED
OVS_NOTIFY_VPN_DISCONNECTED
OVS_NOTIFY_VPN_CONNECT_FAILED
OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED
Code sample:
- Windows
- macOS
- Android
- Android (JSON)
void StartVPNConnection(const char *ip_addr, const char *proto, const char *port, int ipv6_leak, int kill_switch)
{
Json::Value val;
Json::Value data;
val["cmd"] = OVS_CMD_CONNECT;
data["ip_addr"] = ip_addr;
data["proto"] = proto;
data["port"] = port;
data["ipv6_leak"] = ipv6_leak;
data["ip_addr"] = ip_addr;
data["kill_switch"] = kill_switch;
val["data"] = data;
CmdProc(jsonToString(val).c_str());
}
void StartVPNConnection(const char *ip_addr, const char *proto, int port, int kill_switch)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_CONNECT));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "ip_addr", json_object_new_string(ip_addr));
json_object_object_add(j_data_obj, "proto", json_object_new_string(proto));
json_object_object_add(j_data_obj, "port", json_object_new_int(port));
json_object_object_add(j_data_obj, "kill_switch", json_object_new_int(kill_switch));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_CONNECT, null, "104.192.3.90", "tcp", 1194, 1, 1);
VPNSDK.CmdProc("{ \"cmd\": 3, \"data\": { \"ip_addr\": \"104.192.3.90\", \"proto\": \"tcp\", \"port\": 1194, \"ipv6_leak\": 1, \"kill_switch\": 1}}");
Stop VPN Connection​
Stops the established VPN connection. Once VPN is successfully disconnected, the SDK sends OVS_NOTIFY_VPN_DISCONNECTED notification.
Login required: Yes
CmdProc Code: OVS_CMD_DISCONNECT
Command number: 4
Input: Not required
Response: OVS_NOTIFY_VPN_DISCONNECTED
- Success
- Failure
OVS_ERR_OK
data is null
data is null
Code sample:
- macOS
- Android
- Android (JSON)
void StopVPNConnection()
{
json_object *j_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_DISCONNECT));
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_DISCONNECT, null);
VPNSDK.CmdProc("{\"cmd\": 24 }");
Get servers list by geolocation​
Requests available VPN servers and sorts them from nearest to farest based on the estimated location of the end-user's IP address (GeoIP).
Login required: No
CmdProc Code: OVS_CMD_GET_SERVLIST_BYGEO
Command number: 24
Input:
{
"premium": true | false
}
premium - optional flag to select between premium and non-premium server list (true by default).
Response: OVS_NOTIFY_GET_SERVLIST_BYGEO
- Success
- Failure
OVS_ERR_OK
data contains the available server list.
Server data response includes the following array of objects respresenting each server's parameters:
ip - Server's ip address
hostname - Server host name
protocols - Supported protocols (L2TP, OpenVPN, IKEv2, WireGuard)
name - Human readable server name
country - Country code
cipher - Array of available ciphers
cipher_tcp_ports - Available TCP ports
cipher_upd_ports - Available UDP ports
lz4 - LZ4 support
lz4_port - Port where LZ4 is supported
xor - XOR support
xor_ports - Port where XOR is supported
smart_dns_id - Smart DNS ID (for Smart DNS API)
flag - URL for server's country flag
lat - Server latitude
lon - Server longitude
distance - Physical distance from the end-user's estimated location to the server location
ipv6_enabled - Server supports Wireguard IPv6
ipv6_prefix - IPv6 address prefix for Wireguard IPv6
wg_port - Port where Wireguard service is listening
wg_public - Wireguard public key
OVS_ERR_WEB_API
data is null
Code sample:
- macOS
- Android
- Android (JSON)
- Succesful Response Sample
void GetServerListbyGeo(bool premium)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_SERVLIST_BYGEO));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "premium", json_object_new_boolean(premium));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CommandNotifyCB callback = new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int notification, int error, Object data) {
if (error == VPNSDK.OVS_ERROR_CODES.OVS_ERR_OK) {
// Do something when command is successful
} else {
// Process error
}
}
}; VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_GET_SERVLIST_BYGEO, callback, true);
VPNSDK.CmdProc("{\"cmd\": 24, \"data\": {\"premium\": true}}");
OVS_ERR_OK
data:
{
"104.192.3.90": {
"name": "U.S. New York",
"hostname": "us-new-york.keenvpn.me",
"country": "US",
"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": "1",
"flag": "https:\/\/client-api.keenow.com\/serverlist\/flags\/new_res\/us.png",
"protocols": {
"l2tp": true,
"openvpn": true,
"ikev2": true
},
"lat": "40.9375",
"lon": "-73.8994",
"distance": 6827.8522822623
}
}
Get servers list by country​
Requests available VPN servers and sorts them from nearest to farest based on the specified country.
Login required: No
CmdProc Code: OVS_CMD_GET_SERVLIST_BYCOUNTRY
Command number: 25
Input:
{
country": "",
"premium": true | false
}
country - two characters ISO country code (for example - US, CA, FR).
premium - optional flag to select between premium and non-premium server list (true by default).
Response: OVS_NOTIFY_GET_SERVLIST_BYCOUNTRY
- Success
- Failure
OVS_ERR_OK
data contains the available server list.
Server data response includes the following array of objects respresenting each server's parameters:
ip - Server's ip address
hostname - Server host name
protocols - Supported protocols (L2TP, OpenVPN, IKEv2, WireGuard)
name - Human readable server name
country - Country code
cipher - Array of available ciphers
cipher_tcp_ports - Available TCP ports
cipher_upd_ports - Available UDP ports
lz4 - LZ4 support
lz4_port - Port where LZ4 is supported
xor - XOR support
xor_ports - Port where XOR is supported
smart_dns_id - Smart DNS ID (for Smart DNS API)
flag - URL for server's country flag
lat - Server latitude
lon - Server longitude
distance - Physical distance from the end-user's estimated location to the server location
OVS_ERR_WEB_API
data is null
Code sample:
- macOS
- Android
- Android (JSON)
- Succesful Response Sample
void GetServerListbyCountry(const char *country, bool premium)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_SERVLIST_BYCOUNTRY));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "country", json_object_new_string(country));
json_object_object_add(j_data_obj, "premium", json_object_new_boolean(premium));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CommandNotifyCB callback = new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int notification, int error, Object data) {
if (error == VPNSDK.OVS_ERROR_CODES.OVS_ERR_OK) {
// Do something when command is successful
} else {
// Process error
}
}
};
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_GET_SERVLIST_BYCOUNTRY, callback, "US", true);
VPNSDK.CmdProc("{\"cmd\": 25, \"data\": {\"country\": \"US\", \"premium\": true}}");
OVS_ERR_OK
data:
{
"104.192.3.90": {
"name": "U.S. New York",
"hostname": "us-new-york.keenvpn.me",
"country": "US",
"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": "1",
"flag": "https:\/\/client-api.keenow.com\/serverlist\/flags\/new_res\/us.png",
"protocols": {
"l2tp": true,
"openvpn": true,
"ikev2": true
},
"lat": "40.9375",
"lon": "-73.8994",
"distance": 6827.8522822623
}
}
Switch VPN Server​
Switch to the specified VPN server.
Login required: Yes
CmdProc Code: OVS_CMD_SWITCH_VPN_SERVER
Command number: 41
Input: { "ip_addr": "45.79.163.199", "server_name": "us-new-jersey.keenvpn.me" }
ip_addr - The designated VPN server's IP address
server_name - The designated VPN server's hostname
Response: OVS_NOTIFY_SWITCH_VPN_SERVER
- Success
- Failure
OVS_ERR_OK
data is null
data is null
Code sample:
- Windows
- macOS
void switchVpnServer(const char *ip_addr, const char *server_name)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SWITCH_VPN_SERVER));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "ip_addr", json_object_new_string(ip_addr));
json_object_object_add(j_data_obj, "server_name", json_object_new_string(server_name));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
void switchVpnServer(const char *ip_addr, const char *server_name)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SWITCH_VPN_SERVER));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "ip_addr", json_object_new_string(ip_addr));
json_object_object_add(j_data_obj, "server_name", json_object_new_string(server_name));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
Set VPN Type​
Change VPN Protocol
Login required: Yes
CmdProc Code: OVS_CMD_SET_VPN_TYPE
Command number: 51
Input:
{
"vpn_type": 0
}
vpn_type can be any of the following:
0: OpenVPN
1: IKEv2-IPSec
2: WireGuard
3: ShadowSocks
Response: OVS_NOTIFY_SET_VPN_TYPE
- Success
- Failure
OVS_ERR_OK
data is null
Code sample:
- Windows
- macOS
- Android
- Android (JSON)
void setVPNType(int type)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_VPN_TYPE));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "vpn_tye", json_object_new_int(type));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
void setVPNType(int type)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_VPN_TYPE));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "vpn_tye", json_object_new_int(type));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_SET_VPN_TYPE, new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int i, int i1, Object o) {
//Here connect method could be invoked
}
}, VPNSDK.VPN_TYPES.WIREGUARD);
VPNSDK.CmdProc("{\"cmd\": 51, \"data\": {\"vpn_type\": 2}}");
Set Adblock​
Enabled or disables Adblock functionality
Login required: Yes
CmdProc Code: OVS_CMD_SET_ADBLOCK
Comand number: 81
Input:
{
"adblock": "0"|"1"
}
adblock - 0: Adblock disabled for current user, 1: Adblock enabled for current user
Response: OVS_NOTIFY_SET_ADBLOCK
- Success
- Failure
OVS_ERR_OK
OVS_ERR_MISSING_PARAMS, OVS_ERR_WEB_API
data is null
Code Sample
- macOS
- Android
- Android (JSON)
void SetAdblock(const char *adblock)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_ADBLOCK));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "adblock", json_object_new_string(adblock));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CommandNotifyCB callback = new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int notification, int error, Object data) {
if (error == VPNSDK.OVS_ERROR_CODES.OVS_ERR_OK) {
// Do something when command is successful
} else {
// Process error
}
}
};
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_SET_ADBLOCK, callback, "1");
VPNSDK.CmdProc("{\"cmd\": 81, \"data\": {\"adblock\" : \"1\" } }");;
Get Adblock​
Get current Adblock functionality status
Login required: Yes
CmdProc Code: OVS_CMD_GET_ADBLOCK
Comand number: 82
Input: Not required
Response: OVS_NOTIFY_GET_ADBLOCK
- Success
- Failure
OVS_ERR_OK
{
"adblock": "0"|"1"
}
OVS_ERR_WEB_API
data is null
Code Sample
- macOS
- Android
- Android (JSON)
void GetAdblock()
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_ADBLOCK));
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CommandNotifyCB callback = new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int notification, int error, Object data) {
if (error == VPNSDK.OVS_ERROR_CODES.OVS_ERR_OK) {
// Do something when command is successful
String adblock = (String)((Map)data).get("adblock");
} else {
// Process error
}
}
};
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_GET_ADBLOCK, callback);
VPNSDK.CmdProc("{\"cmd\": 82 }");;
Set OpenVPN cipher​
Sets a cipher for OpenVPN connection
Login required: Yes
CmdProc Code: OVS_CMD_SET_ENCRYPTION
Command number: 14
Input:
{
"cipher": "AES-256-CBC"
}
cipher - Cipher name. Supported ciphers could be retrived by one of the server list functions listed above.
Response: OVS_NOTIFY_SET_ENCRYPTION
- Success
- Failure
OVS_ERR_OK
OVS_ERR_MISSING_PARAMS
data is null
Code sample:
- macOS
- Android
- Android (JSON)
void SetEncryption(const char *cipher)
{
json_object *j_obj, *j_data_obj;
char szCmd[1024];
j_obj = json_object_new_object();
json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_ENCRYPTION));
j_data_obj = json_object_new_object();
json_object_object_add(j_data_obj, "cipher", json_object_new_string(cipher));
json_object_object_add(j_obj, "data", j_data_obj);
snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
json_object_put(j_obj);
CmdProc(szCmd);
}
VPNSDK.CommandNotifyCB callback = new VPNSDK.CommandNotifyCB() {
@Override
public void onNotify(int notification, int error, Object data) {
if (error == VPNSDK.OVS_ERROR_CODES.OVS_ERR_OK) {
// Do something when command is successful
} else {
// Process error
}
}
};
VPNSDK.CmdProc(VPNSDK.OVS_CMD_CODES.OVS_CMD_SET_ENCRYPTION, callback, "AES-256-CBC");
VPNSDK.CmdProc("{\"cmd\": 14, \"data\": {\"cipher\" : \"AES-256-CBC\" } }");;