Vortex TUNNEL programming manual (C API)

Introduction

This manual shows you how to use the TUNNEL profile (RFC3620) implemented in Vortex Library, to allow performing BEEP connections through a BEEP proxy running also the TUNNEL profile.

The main idea behind BEEP is to allow you writing new network application protocols in an easy way reusing as much as possible mechanisms already tested in the past. In the same direction, the TUNNEL profile allows you to provide proxy support, with its all associated security advantages, to any protocol layered on top of BEEP.

The TUNNEL profile design is simple and elegant. You configure a TUNNEL to be created to the remote endpoint, and once establish the link, endpoint-to-endpoint, a new BEEP session is negotiated, allowing to create channels as it were no proxy in the middle.

TUNNEL profile requirements

You must compile Vortex Library with TUNNEL support. Please refer to the installation manual: Installing and Using Vortex Library

Creating a connection to the remote endpoint: setting a TUNNEL.

The TUNNEL profile is only used to establish the endpoint-to-endpoint connection. Once created, channels are created and used as usual. In fact, creating connection (VortexConnection) with TUNNEL returns the same object.

Here is a simple example creating a connection, using a BEEP proxy:

 VortexTunnelSettings * settings;
 VortexConnection     * connection;
 
 // create a tunnel settings holder
 settings = vortex_tunnel_settings_new ();

 // configure the tunnel
 vortex_tunnel_settings_add_hop (settings,
                                 TUNNEL_IP4, "80.43.98.134"
                                 TUNNEL_PORT, "55000",
                                 TUNNEL_END_CONF);
 
 vortex_tunnel_settings_add_hop (settings,
                                 TUNNEL_IP4, "192.168.0.133",
                                 TUNNEL_PORT, "604",
                                 TUNNEL_END_CONF);
 
 // create the connection using tunnel settings
 connection = vortex_tunnel_new (settings, NULL, NULL);
 if (! vortex_connection_is_ok (connection, axl_false)) {
       // manage tunnel creation error 
 }
 
 // tunnel created!

Let's see what's happens here:

1. First, a empty tunnel settings is created with: vortex_tunnel_settings_new

2. Then, we configure the remote end point to connect to. Note this is not the actual BEEP proxy server in our network. In this case, we want to connect to the remote BEEP peer located at 80.43.98.134, running at the tcp port: 55000.

3. Finally, we configured the next hop to use, in this case, our local network BEEP proxy, which is located at the well known BEEP TUNNEL port: 192.168.0.133:604.

Once the connection is created, you can use the usual API to create channels and to exchange data over those channels. A connection created by the TUNNEL API works with the same properties: you must close them using vortex_connection_close when no longer needed.

The example also shows that a settings configuration can be reused as many times as required. Once finished, it is also required to call: vortex_tunnel_settings_free.

Configuring next hop in inverse order

As you might note with previous example, the hop configuration first set the remote end point, and then the proxy to use. This is because every time you configure a next hop, this is added to the hop list to be traversed in the first position.

So, to create a tunnel with the following configuration:

    [BEEP PROXY 1] -> [BEEP PROXY 2] -> [ENDPOINT]

You must build the tunnel setting in the inverse order, that is, calling to vortex_tunnel_settings_add_hop with the address of "ENDPOINT", followed by "BEEP PROXY2" and "BEEP PROXY1".

Are there any BEEP TUNNEL server already implemented?

Sure, you can use mod-tunnel from turbulence. It currently provides full TUNNEL support, including TUNNEL_ENDPOINT and TUNNEL_URI tunnel configurations.