# KidVPN : KidVPN server and client module

This module provides KidVPN server and client functions, and developers can use this module to quickly build a VPN (Virtual Private Network) network.

KidVPN is an implementation of VPN, the open source C language implementation can refer to KidVPNopen in new window. Developers can under the premise of obtaining national permission, develop servers and clients to establish related virtual networks with EdgerOS for remote office, game acceleration, etc.

KidVPN is only responsible for the underlying virtual network communication, and developers can design VPN business management programs by themselves, such as how to distribute connection parameters, how to change cipher IV, how to manage connection relationships, etc.

This module is provided in EdgerOS 1.9.6 and later, and apps need to have vpn permission to use this module. For details, please refer to permission.

At present, according to the relevant provisions of national laws and regulations, this permission is not yet open.

User can use the following code to import the KidVPN module.

var KidVPN = require('kidvpn');

# Support

The following shows KidVPN module APIs available for each permissions.

# KidVPN Class

# new KidVPN(mode)

• mode {String} Network mode 'server' or 'client'.
• Returns: {KidVPN} KidVPN object.

Create a KidVPN object with the specified mode. The mode argument can only be 'server' or 'client'.

# KidVPN.ca(callback)

• callback {Function} Callback.
  • error {Error} Specify the cause of the error.
  • ca {String} EdgerOS root CA.

Privileged App to get EdgerOS KidVPN root CA certificate.

# KidVPN.certificate(callback)

• callback {Function} Callback.
  • error {Error} Specify the cause of the error.
  • info {Object} EdgerOS KidVPN server certificate.

Privileged App to get EdgerOS KidVPN server certificate.

# KidVPN Object

# kidvpn.id

• {Integer}

VPN network ID, Each VPN channel has an independent ID.

# kidvpn.ifname

• {String}

VPN virtual network interface name, It can cooperate with the NetIf module to obtain all the parameters and working conditions of the virtual network interface.

# kidvpn.request(callback)

• callback {Function} Callback.
  • error {Error} Specify the cause of the error.
  • ifname {String} VPN network interface name.

Request to use a VPN network channel. Before doing anything with VPN, you must first request VPN network channel.

# Example

kidvpn.request((error, ifname) => {
  if (error) {
    console.error('VPN request error:', error);
  } else {
    console.log('VPN interface:', ifname);
  }
});

The network interface defaults to disabled NAT mode, which can be enable NAT mode using kidvpn.natMode().

# kidvpn.release([callback])

• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Release the VPN network channel, the VPN will stop working after release. The current kidvpn object can call request to use VPN again. After the VPN is released, the previously added routes and NAT port mappings will be deleted at the same time.

# kidvpn.start(conf, passwd[, callback])

• conf {Object} VPN config.
• passwd {String} VPN password.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Start VPN networking, conf object can have the following members:

Server mode:

• key {Buffer | String} Cipher key, binary length must be 16, 24, 32 bytes.
• iv {String} Cipher IV string.
• mtu {Integer} Virtual network interface MTU 1280 ~ 1472 Typical: 1464.
• port {Integer} VPN port 1 ~ 65535.

Client mode:

• key {Buffer | String} Server cipher key, binary length must be 16, 24, 32 bytes.
• iv {String} Server cipher IV string.
• mtu {Integer} Virtual network interface MTU 1280 ~ 1472 Typical: 1464.
• port {Integer} VPN server port 1 ~ 65535.
• server {String} VPN server hostname or IP address.
• hpunching {Boolean} Whether to enable Hole Punching feature. Optional.

If the key is of String type, it must be a hex string.

Hole Punching is a technique in computer networking for establishing a direct connection between two parties in which one or both are behind firewalls or behind routers that use network address translation (NAT). For details, please refer to Hole Punchingopen in new window. Using this technology can reduce the pressure of server data forwarding, but at the same time it will bring certain unreliability.

# Example

var servconf = {
  key: Buffer.alloc(16).fill(1),
  iv: 'test iv',
  mtu: 1464,
  port: 4321
};

// VPN start server.
kidvpn.start(servconf, 'test passwd', error => {
  if (error) {
    console.error('VPN start error:', error);
  }
});

var cliconf = {
  key: Buffer.alloc(16).fill(1),
  iv: 'test iv',
  mtu: 1464,
  port: 4321,
  server: 'www.vpntest.com',
};

// VPN start client.
kidvpn.start(servconf, 'test passwd', error => {
  if (error) {
    console.error('VPN start error:', error);
  }
});

# kidvpn.stop([callback])

• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Stop the VPN network. After stopping the VPN, the channel can still be started again.

# Example

kidvpn.stop(error => {
  // Can modify the configuration
  kidvpn.start(...);
});

# kidvpn.update(iv[, callback])

• iv {String} New cipher IV string.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Update network cipher IV, this parameter can be updated regularly to ensure VPN network security. When the VPN management app is deleting the specified client, other clients and the server update the IV at the same time, so that the deleted client can no longer connect to the server.

# kidvpn.setAddr(ifaddr, callback)

• ifaddr {Object} Network interface address.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Set the VPN virtual network interface IP address.

The ifaddr must includes following elements:

• ipaddr {String} IP address of this network interface.
• netmask {String} Net mask of this network interface.
• gateway {String} Default gateway of this network interface.

# Example

kidvpn.setAddr({
  ipaddr: '192.168.111.123', netmask: '255.255.255.0', gateway: '0.0.0.0'
}, error => {
  if (error) {
    console.error('VPN set interface address error:', error);
  }
});

# kidvpn.setAddr6(ifaddr6, callback)

• ifaddr6 {Object} Network interface address.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Set the VPN virtual network interface IPv6 address.

The ifaddr6 must includes following elements:

• ip6addr {String} IP address of this network interface.
• prefix {Integer} Net mask prefix.

# Example

kidvpn.setAddr6({ ip6addr: 'fec0::02', prefix: 64 }, error => {
  if (error) {
    console.error('VPN set interface IPv6 address error:', error);
  }
});

# kidvpn.delAddr6([ifaddr6, ]callback)

• ifaddr6 {Object} Network interface address. default: delete all IPv6 address except linklocal scope.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Delete VPN virtual network interface IPv6 address.

# Example

// Delete specified
kidvpn.delAddr6({ ... }, error => { ... });

// Delete all
kidvpn.delAddr6(error => { ... });

# kidvpn.addRoute(rule, callback)

• rule {Object} Routing rules that need to be added.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Add a route entry. This route entry can be a host route or a network route. When this application exits, all previously added routing rules will be invalidated automatically, and the VPN connection will be automatically disconnected at the same time.

rule contains the following information:

• dest {String} Destination address.
• genmask {String} Netmask.
• gateway {String} Gateway address. default: 0.0.0.0 or ::
• host {Boolean} true for host routing, false for subnet routing. default: false

After successfully starting the VPN, the route sent to the VPN subnet has been automatically added, developers do not need to add this route entry, routing rules to other hosts or subnets (not in the VPN network interface subnet) need to be added manually.

If the gateway is not specified, or the gateway is 0.0.0.0 or ::, the default gateway of the VPN virtual network interface will be used.

# kidvpn.delRoute([rule, ]callback)

• rule {Object} Routing rules that need to be added. default: delete all
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Delete the previously added routing rules. When the VPN is released, the system will automatically clear all previously added routing rules.

# Example

// Delete specified
kidvpn.delRoute({ ... }, error => { ... });

// Delete all previously added
kidvpn.delRoute(error => { ... });

# kidvpn.addMap(local, wan, proto, callback)

• local {Integer} Local port.
• wan {Integer} WAN port.
• proto {String} 'tcp' or 'udp'.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.
  • index {Integer} This map rule index.

When EdgerOS includes router services, If a VPN server needs to provide services to the EdgerOS WAN port, you need to add a specified mapping rules. For example, you can use VSOA (TCP) as the VPN network management, KidVPN (UDP) as the data channel, you need to map the VSOA server and KidVPN server port is to WAN interface. If the index parameter of the callback is a negative number, it means that the current VPN is released when the mapping rule is added.

# Example

kidvpn.addMap(10088, 10088, 'udp', (error, index) => {
  // ...
});

# kidvpn.delMap(index[, callback])

• index {Integer} Map rule index.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.

Delete the previously added mapping rules. When the VPN is released, the system will automatically clear all previously added mapping rules.

# kidvpn.netMode([enable, ]callback)

• enable {Boolean} Whether to enable the NAT mode of this network.
• callback {Function} Callback.
  • error {Error} Specify the cause of the error.
  • enable {Boolean} Current NAT mode for this network.

Get or set the current NAT mode of this network.

# Example

// Get current NAT mode of this network.
kidvpn.netMode((error, enable) => {
  console.log(enable)
});

// Enable the current network NAT mode.
kidvpn.netMode(true, (error, enable) => {
  console.log(enable)
});

# KidVPN Object Events

The KidVPN Object inherits from the EventEmitter class. The following events are thrown in some specific situations.

# start

Current VPN is up and working.

# stop

• info {String} Stop working for any reason.

Current VPN has stopped working.

# add

• cli {Object} Remote client information.
  • remote {String} Remote client IP address.
  • mac {String} Remote client MAC address in virtual network.

When the current VPN is in server mode, there are clients connected.

# lost

• cli {Object} Remote client information.
  • remote {String} Remote client IP address.
  • mac {String} Remote client MAC address in virtual network.

When the current VPN is in server mode, there are clients lost.

# connect

When the current VPN is in client mode that already connected to the server.

# disconnect

When the current VPN is in client mode that disconnected from server.

The current VPN object is in client mode. After startup, the KidVPN client will keep trying to connect to the server. Developers can set a custom timeout in the application. If no connect event is received after this time, the kidvpn.stop interface will be called stop the connection. After disconnecting from the server, if the KidVPN client is not stopped, the client will also keep trying to reconnect to the server.

# certificate

• info {Object} Expires information.

When the server certificate expires, this event will be received, and the server needs to reload a new certificate. This event can only be received by privileged apps.