The tunnel service consists of an interface for setting up connections to a proxy server. The proxy server then accepts connetions and relays them to the server. This can be used to get past NAT and other firewall restrictions, and to hide the real IP address of the server from clients.

Tunnel
{
string openTunnel()
string getTunnelAddress(string uri)
}

The openTunnel() method establishes a new tunnel. It returns a URI specifying where the server should connect to in order to use the tunnel.

The getTunnelAddress method takes the URI returned by openTunnel and returns a URI specifying where clients should connect in order to use the tunnel.

Sample usage:

The reference implementation of the Tunnel service is a TCP tunneling service. It requires one open tunnel for each incoming connection. While a Tunnel service using an SSH, WebMUX, or EGTP backend could allow for multiple incoming connections to be served over a single open tunnel, the TCP tunnel serves as an exmaple of how to use the service.

First, the server calls openTunnel() to open a new tunnel. This method returns a URI, for example "tcp://tristero.sourceforge.net:8010". The server then checks to make sure that the URI is of a reasonable type which it can handle. Since this is a TCP tunnel, it is safe to assume that any server attempting to access the service knows how to make a TCP connection. So the server parses the URI and then makes an outgoing connection to the given address, in this case a TCP connection to host tristero.sourceforge.net and port 8010. Now that a connection to the tunnel has been established, incoming connections can be serviced.

However, the server needs to know what address to advertise. So the server calls getTunnelAddress("tcp://tristero.sourceforge.net:8010") and the method returns the address to advertise, for example "tcp://tristero.sourceforge.net:8011". Since the server presumably wants to service HTTP connections (after all, all Tristero communications are done over HTTP), it should reformat this as an HTTP URL, producing "http://tristero.sourceforge.net:8011/". The server can now advertise this URL to clients that might wish to use its services.

A client which has the URL can make a normal HTTP connection to the proxy server (tristero.sourceforge.net). The packets will be relayed from the client, through the proxy server, down the open tunnel, and to the server. Packets from the server will be relayed up the tunnel, through the proxy server, and to the client. When either the client or server closes the connection, the proxy server closes the tunnel and drops all connections.
Utilizing this service, one can run a server both anonymously and from behind a firewall.