Controller API

Vahid edited this page Nov 21, 2017 · 4 revisions
Clone this wiki locally

Controller API

Warning: This document may be out of date.

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.

= 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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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”.

{| class="wikitable" !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.

{| class="wikitable" !Parameter !Type !Description |- |network_ignore_list |string |List up network interfaces to be ignored in json format. i.e., “network_ignore_list” : [eth1, wlan0]. |}

= 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.

{| class="wikitable" !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.

{| class="wikitable" !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''.

{| class="wikitable" !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.

{| class="wikitable" !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.

{| class="wikitable" !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 |}