Skip to content

Controller API

Jump to bottom
younajung edited this page Jul 18, 2014 · 21 revisions

IPOP-Tincan provides a JSON-RPC API over UDP which enables developers to extend the functionality of SocialVPN/GroupVPN. This page explain the function calls available through the API.

Table of Contents

Function: register_svc

This function is designed to allow IPOP-Tincan to register to a backend service which will be used to discover social peers and bootstrap encrypted P2P connections. We currently only support XMPP service, hence this is basically the XMPP username and password. Future versions may extend this API to support services other than XMPP, and authentication mechanisms to XMPP other than username/password.

Parameter Type Description
username string the username used to login to the XMPP service (e.g. username@gmail.com)
password string the password used to login to the XMPP service
host string the host name or IP address of the XMPP server (e.g. talk.google.com

Function: set_local_ip

This call configures the VNIC and set the UID of the local peer. This call is important and has to be done first because it also triggers the creation of a X.509 certificate and configures the virtual NIC and operating system for packet flow.

Parameter Type Description
uid string the unique identifier for the local peer (e.g. hexdigest of the sha1 hash). The uid, encoded as a hexadecimal string, is 40 Bytes long.
ip4 string the IPv4 address for the ipop tap virtual NIC
ip6 string the IPv6 address for the ipop tap virtual NIC
ip4_mask integer the prefix length, in bits, for the network mask in the IPv4 address (e.g. 16 means a.b.c.d/16 allowing for a network of size 2^16)
ip6_mask integer the prefix length, in bits, for the network mask in the IPv6 address. This is usually set to 64
subnet_mask integer the prefix length for the network mask in the IPv4 address of the local router. This parameter is relevant for router mode - in router mode, an IPOP-Tincan node routes packets for more than one IP address; this parameter specifies the subnet it should route for. If not in router mode, you must set this parameter to 32 (a netmask of 32 gives a network size of 1, i.e. IPOP-TinCan only routes for its local address).

Function: get_state

This is a very important call because it allows developers to query the state of IPOP-TinCan. In return, IPOP-TinCan replies (through the use of notifications) with the state of the local peer and each remote peer. The first notification sent to the controller is the “local_state” (see section 4.10) which tells the controller state information about the local user - such as UID and IPv4 address. Afterwards, a separate “peer_state” notification (see section 4.11) is sent to the controller for each remote peer containing information such as IPv4/IPv6 address and online status. The controller can provide the UID of a particular peer; in that case, only the “peer_state” of the specified user is returned to the controller. If no uid is provided, then the “peer_state” of every remote peer is returned to the controller.

Parameter Type Description
uid string the unique identifier of the remote peer that we want state information about. If this is an empty string, then all state is returned.

Function: create_link

This call creates P2P TinCan link with a peer, with encryption if so specified. It requires that the controller provides the 40-byte hexadecimal encoded UID of the remote peer, and the peer’s X.509 fingerprint, along with optional STUN/TURN credentials. The X.509 fingerprint is generated by IPOP-TinCan once the `set_local_ip` call is made. The `get_state` call returns the X509 fingerprint as part of the local_state notification.

Parameter Type Description
overlay_id integer IPOP-TinCan will support multiple overlays in the future (e.g. XMPP, Gnunet) so we need an ID for each overlay. Currently, we only support two hardcoded IDs (0 for controller, 1 for XMPP service). For now, always set this to 1.
uid string every user has a unique identifier that is determined by the controller. This identifier has to be a 40-byte long hexadecimal string. In the GroupVPN controller we use the sha1 hash of the IPv4 address; in the SocialVPN controller, we use a random identifier.
fpr string this is the X.509 fingerprint (hash of X.509 certificate) of the user. This is obtained from the `get_state` api call described below. IPOP-TinCan generates an X.509 certificate once the `set_local_ip` call is made.
stun string this parameter specifies the STUN server that will be used for this connection (e.g. stun.google.com:19302). You can provide an empty string for this parameter, but the connection will only succeed if one of the two peers are not behind a NAT.
turn string this parameter specifies the TURN server that will be used for this connection (e.g. ip-of-turn-server:port). This can be an empty string and is only required if both peers are behind symmetric NATs.
turn_user string the username for accessing the TURN server, can be empty string.
turn_pass string the password for accessing the TURN server, can be empty string.
cas string a specifically formatted string that contain a list of IP addresses and connection credentials necessary for bootstrapping an ICE connection. This is generated by IPOP-TinCan.
sec boolean this parameter specifies whether or not the connection should be encrypted.

Function: set_remote_ip

This call builds the forwarding table for IPOP-TinCan. It maps IP addresses to remote peer UIDs. The aforementioned “create_link” function causes IPOP-TinCan to create a P2P connection associated with the remote peer’s UID. This function thus allows IPOP-TinCan to know which P2P connection to forward the IP packets.

Parameter Type Description
uid string the unique identifier of the remote peer
ip4 string the IPv4 address that the remote peer is mapped to. The address needs to fall within the subnet of the VNIC defined in the create_link call.
ip6 string the IPv6 address that the remote peer is mapped to. It should fall within the subnet of the ipop virtual NIC defined in the create_link call.

Function: trim_link

This trim call provides a mechanism to force the removal of TinCan P2P links from a node. This occurs regardless of whether peers are online or offline. Link trimming is important in resource-constrained devices, and to create scalable routing overlays.

Parameter Type Description
uid string the unique identifier of the remote peer specifying which P2P connection to trim.

Function: set_cb_endpoint

IPOP-Tincan currently notifies the controller of two main events: 1) a connection request/reply and 2) a link state change (i.e from online to offline). This call registers the endpoint at the controller that IPOP-Tincan sends the notifications to.

Parameter Type Description
ip string the IP address of the controller
port integer the port number of the controller

Function: send_msg

This call allows the controller to send an arbitrary message to another peer via the overlay (i.e. XMPP service) specified by the overlay_id. This serves as a secondary out-of-band channel to bootstrap P2P connections. Note: this call is not intended to be used for the datapath flow of IP packets between nodes - it is a control path call.

Parameter Type Description
overlay_id integer this parameter specifies which overlay should be used to send the message. This should be set to 1 because we only support send_msg over the XMPP overlay.
uid string the unique identifier of the remote peer that will receive the message

Function: set_logging

By default, IPOP-Tincan prints various debugging messages to stdout. This call allows developers to select the level of logging.

Parameter Type Description
logging integer sets the logging severity, 0 = no logging, 1 = error logging, 2 = info logging

Function: set_switchmode

This mode configures whether IPOP should handle ARP messages picked from the tap interface to the controller or not. If set to enabled (1), ARP request/response messages are forwarded to controllers, and the controller broadcasts this message as JSON formatted RPC to all the other IPOP peers looking for given IP address. If found, remote ARP reply message is received and local ARP reply message is generated to solicit this IP address. In the operating system’s perspective, this IP address is associated with IPOP tap device. Then, IP packets can be transferred through IPOP network as if they were in the same network layer. As a result, when IPOP tap device is attached to a linux bridge, it works as a gateway toward IPOP network for the all the network interfaces that attached to the linux bridge. If this mode is disabled, IPOP discards ARP messages. It is disabled by default.

Parameter Type Description
switchmode bool Switchmode is enabled by setting this parameter as 1.

Function: set_translation

This function allows the controller to enable/disable TinCan’s IPv4 address translation feature, which is necessary for SocialVPN. The SocialVPN controller sets this value to 1, while the GroupVPN controller set this value to 0. In SocialVPN, IPv4 addresses are not globally unique and translation is necessary to map all friends’ IPv4 addresses to a local address.

Parameter Type Description
translation int If set to 0, then you are running on GroupVPN mode, if set to 1 then you are running in SocialVPN mode.

Function: set_trimpolicy

If it is enabled, relay connections are removed among connection candidates, if there are STUN connections available.

Parameter Type Description
trim_enabled bool If set to true, relay connections are trimmed once a STUN connection candidate is available.

Function: echo_request

This function call works as a ping message allowing an external process to monitor whether TinCan is responsive or not. Once TinCan receives this message, it sends back “echo_reply” message to the controller.

Parameter Type Description
msg string The message contents send back to controller in “echo_reply” message.

Function: echo_reply

This message is complementary to “echo_request”. Upon the receipt of “echo_request” message, the expected behavior for both the TinCan and controller is to reply back with “echo_reply” message echoing the same “msg”.

Parameter Type Description
msg string The “msg” contents has the exactly same payload with the “echo_request” msg.

Function: set_network_ignore_list

As a default, IPOP tries to create STUN connection by using all available network interfaces. This can be inefficient and also produce much verbose logging messages by trying to create connection through network interfaces without public internet access. This call allows the controller to identify network interfaces that should be ignored.

Parameter Type Description
network_ignore_list string List up network interfaces to be ignored in json format. i.e., “network_ignore_list” : [eth1,].

Notification: local_state

This notification is sent to the controller as a result of the get_state function call. It contains information about the local node.

Parameter Type Description
type string set to local_state to indicate that it contains information about the local node
_uid string the UID of the local node
_ip4 string the IPv4 address of the local node
_ip6 string the IPv6 address of the local node
_fpr string the X.509 certificate fingerprint of the local node

Notification: peer_state

This notification is sent to the controller as a result of the get_state function call. It contains information about a single peer node.

Parameter Type Description
type string set to peer_state to indicate that it contains information about the peer node
uid string the UID of the peer node
ip4 string the IPv4 address of the peer node
ip6 string the IPv6 address of the peer node
fpr string the X.509 certificate fingerprint of the peer node
status string set to either online or offline. Online is defined as the TinCan P2P link is active - i.e. keep-alive messages sent over the TinCan link have been acknowledged by the destination. If no link has been created, or if keep-alive messages have not been received within a period of time managed by libjingle (15 seconds by default), the status is offline
security string set to either none or dtls. It indicates whether the P2P connection is encrypted or not
stats string This attribute only available in GroupVPN. It lists connection candidates and traffic records. Candidates are in array form and attributes of candidates are listed below. Attributes are associative array form in JSON format: 1) best_conn: True, if this candidate is best connection, 2)local_addr: reflective or relay transport address of candidates. In most cases, it is the public address of NAT with ports that the IPOP is binding to, 3)local_type: Local IPOP node NAT traversal type, 4) new_conn: True, if it is new connection, 5) readable: True, if this connection is readable, 6) recv_bytes_second: Byte received for last one seconds, 7) recv_total_bytes: Total byte received since the connection is created, 8) rem_addr: reflective or relay transport address of candidates remote peer. It is usually the public transport address of NAT that the remote peer is binding to, 9) rem_type: remote peer NAT traversal type rtt: Round trip time, 10) sent_bytes_second: Byte sent for last one seconds, 11) sent_total_bytes: Total byte sent since the connection is created, 12) timeout: True, if this binding timed out, 13) writable: True if writable
xmpp_time int the number of seconds since the local node receives an XMPP presence message from the remote peer. Presence messages serve as an indicator that the node is ready to accept TinCan connections. The controller can use the XMPP time to determine when to trigger a connection request to a node

Notification: con_stat

This notification is sent to the controller when a TinCan P2P link changes state either from unknown to online or offline.

Parameter Type Description
type string set to con_stat to indicate that it contains connection status information.
uid string the UID of the peer node
data string set to the current status either online, offline, or unknown. Unknown means the connection has just been initialized

Notification: con_req

This notification is sent by a controller through the XMPP overlay when a node wants to initiate a TinCan connection with a remote peer. The controller determines the policy for connection creation. This connection request should trigger a connection respond on the receiving controller if it agrees to create a connection with the requestor.

Parameter Type Description
type string set to con_req to indicate that it is a connection request
uid string the UID of the peer node
data string contains the X.509 fingerprint of the peer node and optionally followed by ICE information containing public IP address, credentials, and connection type

Notification: con_resp

This notification is sent back through the XMPP server as a reply to the connection request event described above. The response message is almost identical to the connection request except for the message type. Once a connection response is received, then nodes can start creating their TinCan connections.

Parameter Type Description
type string set to con_resp to indicate that it is a connection response
uid string the UID of the peer node
data string contains the X.509 fingerprint of the peer node and followed by ICE information containing public IP address, credentials, and connection type
Clone this wiki locally