search

htwg-konstanz / UCE

Universal Connection Establishment
GNU General Public License v3.0
48 stars 18 forks source link

readme 

Copyright (c) 2012 HTWG Konstanz, 

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

UCE - Universal Connection Establishment

THIS PROJECT IS NO LONGER MAINTAINED.

Universal Connection Establishment (UCE) is a framework for firewall and NAT traversal techniques that is designed to provide universal IP connectivity with minimal administrative and configuration overhead.

Current build status:

Build Status

NAT introduction

Network Address (and Port) Translation (NAT / NAPT) allows address sharing of public IP addresses and hiding private networks from the public. The downside is that NAT breaks the end-to-end principle and prevents incoming pakets that are not related to outgoing traffic from traversing the NAT device. As a result, hosts behind NAT are not reachable from the public internet. For an explanation of NAT and it's terminology see RFC2663. This is especially problematic for P2P applications that require direct connections between participating peers.

One can distinguish between NAT mapping, that is how a NAT maps public endpoints (IP, Port) to private endpoints, and NAT filtering, that is how the NAT deals with incoming pakets and connection requests. Four strategies are common (see RFC5128 for more explanation):

The mapping and filtering behavior on a NAT device is usually called the NAT behavior. There can be multiple NAT devices between two peers, the sum of all NAT behaviors on the path is called NAT situation. The NAT situation is decisive for the success of NAT traversal strategies.

NAT Traversal Components

NAT traversal describes the process of traversing NAT devices from the outside world with the intend of enabling incoming pakets that are unrelated to outoing traffic.

The following NAT traversal techniques have been proposed in literature. See P2PNat, RFC5128.

There are other solutions like NAT-PMP or SOCKS which are not discussed here. A good overview can be found on Wikipedia.

So what's UCE and what's different

UCE tries to unify a multitude of NAT traversal techniques in one library (and application) that is able to guarantee connectivity in basically any network environment. It tries to collect information about the NAT situation and then uses some logic to find the best suitable NAT traversal method.

In that regard it is quite similar to ICE or ANTS. ICE, however, is only defined for UDP-based media streams whereas UCE focuses entirely on TCP. ANTS promises similar behavior for TCP. Unfortunately, there is no implementation publicly available. You can test their NAT-Analyzer (you can also download the code there if you look closely)

An essential part of UCE is exposure to Java RMI. That allows building RMI applications over NAT and firewall boundaries.

Contents

All modules and bundles are located in a flat hierarchy parallel to parent. Modules are components of UCE. Bundles are different from modules in the way that they extend and bundle modules to new releases. E.g. 'UCE Messages' is a module that implements all the core messages, while 'UCE Core' is a bundle that bundles all UCE core functionality to one release.

State of UCE

UCE originates from a BMBF funded research project. Most components are in a proof-of-concept or prototype state. See the project page for detailed information, references, publications and presentations.

Currently implemented are the NAT traversal techniques mentioned above as well as the connectivity manager, a modular mediator, STUN and relay server. There are no plans from our side to extend this for support of further techniques.

Clone and build UCE

Test the connectivity manager demo

You should now have a running CLI-based chat between the (NATed) peers.

BEWARE The demo application uses a built-in mediator and STUN server IP. These servers are hosted by us and might not always be available.

To see how to integrate UCE into your own application see the connectivitymanager.demo implementation. It boils down to do sth like the following:

    import de.fhkn.in.uce.connectivitymanager.connection.UCESocket;
    import de.fhkn.in.uce.connectivitymanager.connection.UCEUnsecureSocketFactory;

    UCESocket socketTpPartner = UCEUnsecureSocketFactory.getInstance().createTargetSocket(targetId);
    socketTpPartner.connect();

Build your own bundle

Run your own mediator

The mediator is now working on your own machine. To use it from the connectivity manager, you hava to change the mediator.properties. Unfortunately it does not currently work to change the system properties from the command line. To change the mediator.properties goto the directory:

connectivitymanager/src/main/resources/de/fhkn/in/uce/connectivitymanager/mediatorconnection/

Edit the file mediator.properties like this:

mediator.ip=<your mediator ip>
mediator.port=<your mediator port>
mediator.keepalive=600

Afterwards you have to rebuild the connectivity manager and the demo.

Similarly, you can also change the plugin directory location of the connectivity manager and the mediator. Just look into the appropriate resources directories, find the registry / techniqueregistry dirs and change the file nattraversalregistry.properties.

Run the master server

NOTE

The properties will be read and overwritten in the following ascending order:

properties file < system properties < command line arguments

To start the master server correctly the following arguments need to be set:

StunFirstIP
StunSecondIP
RelayPort           (optional)
MediatorPort
MediatorIteration
MediatorLifeTime

Plugin development

If you want to use your own plugins, please provide them in the corresponding plugins/ folder in the mediator and connectivitymanager.demo. For the mediator it should look like this:

./core-1.0.jar
./jcip-annotations-1.0.jar
./log4j-1.2.17.jar
./mediator-1.0.jar
./plugininterface-1.0.jar
./slf4j-api-1.6.1.jar
./slf4j-log4j12-1.6.6.jar
./stun-1.0.jar
./plugins/
    directconnection.mediator-1.0.jar
    directconnection.message-1.0.jar
    holepunching.mediator-1.0.jar
    holepunching.message-1.0.jar
    relaying.mediator-1.0.jar
    relaying.message-1.0.jar
    reversal.mediator-1.0.jar
    reversal.message-1.0.jar

And for the demo it should look like this:

./connectivitymanager.demo-1.0-jar-with-dependencies.jar
./plugins/
    directconnection.message-1.0.jar
    directconnection-1.0.jar
    holepunching.message-1.0.jar
    holepunching-1.0.jar
    relaying.message-1.0.jar
    relaying-1.0.jar
    reversal.message-1.0.jar
    reversal-1.0.jar

How it works

A target behind NAT that wants to be publicly available registers with a publicly available mediator. In addition a public UCE STUN server can be used to investigate the NAT behavior. A client that wants to connect needs to know the mediator and the registered target ID. The cnnectivity manager on the source side decides in which sequence NAT traversal techniques should be tried and using the mediator issues connection requests and starts connecting. As a last resort, relaying is tried.

What's left to do and how to contribute

Although UCE work has proven to work quite well in our tests there are some open issues.

If you like to contribute and think that you could deal with one of the issues above, or you have your own ideas / improvements, just fork the repo, do your stuff and send us a pull request. Also feel free to contact the project maintainer at any time.

Credits