SourceForge.net Logo

NetCallback 1.3.1

Forwarding TCP and UDP ports behind a firewall

Copyright © 2001 Alexander V. Konstantinou (akonstan@acm.org)

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 2 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, write to the Free Software Foundation Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Contents

Overview

NetCallback is a Java application permitting the export of TCP and UDP ports behind a firewall to hosts outside the firewall. This may be useful in some special cases, for example, centralized control of test (demo) networks, or connection to applets running in browsers.

NetCallback consists of a public and a private server. The public server executes on a host outside the firewall and is responsible for receiving port forwarding connection requests. The private server executes on a host behind the firewall and is responsible for contacting the public server and connecting the protected TCP and/or UDP service to the public server clients. The connection between public and private server may be optionally encrypted using SSL.

Note that firewalls exist to protect internal services from external access, and therefore one should be very careful before creating a hole in one! As stated in the copyright statement, 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.

Users are responsible for checking their network use policy for possible violations before using this software. Use at your own risk!

Protocol

The NetCallback service requires the execution of two network daemons. The first daemon executes on a host behind the firewall and is called PrivateServer. The second daemon executes on a host outside the firewall and is called PublicServer.

The PublicServer is invoked with three port numbers. The first port number is used to receive the connection request from the PrivateServer (service port). The second port number is the one used by clients to connect to the TCP port forwarding endpoint (redirect port), and the third for UDP.

The PrivateServer is invoked with the host name and service port number of PublicServer. Additionally, the PrivateServer must be provided with both the address and port number of a TCP and/or a UDP internal service that needs to be exported.

Connect Protocol

The protocol interactions are illustrated in the diagram below (order is important!):
  1. A protected service running on a protected host and bound to a port must be chosen (as the target for redirection).
  2. A PublicServer must be started on a public host with a service and a redirect port.
  3. A PrivateServer must be started on a host that can access both the target host, as well as the public host.
  4. Once the PrivateServer is started, it will connect to the PublicServer's service port.

netcallback connect diagram

TCP Tunneling Protocol

At this point, the NetCallback service is ready to accept client TCP redirect requests:
  1. A client host connects to the PublicServer redirect port
  2. The PublicServer binds to a temporary port and waits for a connection (on a separate thread)
  3. The PublicServer uses the established connection with the PrivateServer (from step 4) to request a callback connection on the temporary port.
  4. The PrivateServer connects to the PublicHost temporary port
  5. The PublicServer starts bridging traffic between the temporary port and the redirect port (actually the anonymous socket created when the client connected in step 5).
  6. The PrivateServer connects to the target host
  7. The PrivateServer starts bridging traffic between the target host and the temporary port sockets.

netcallback TCP diagram

At this point two way communication has been established. The tunnel is automatically torn down when either the client, or the target host close the connection.

UDP Tunneling Protocol

In parallel, the NetCallback service is ready to accept client UDP redirect requests:

netcallback TCP send diagram

  1. The client host sends a UDP datagram addressed to the PublicServer UDP redirect port
  2. The PublicServer writes the datagram's source address/port and payload to the PrivateServer over the established connection (TCP/SSL)
  3. The PrivateServer consults its internal state and checks to see if a UDP socket has been created to forward requests from the given client (identified by the address/port combination). If one has not been created yet, it is initiated and a thread for receiving datagrams addressed to this socket is created.

    The reason that each client must have its own UDP socket is to determine the destination of returned UDP datagrams (as will be shown in the next diagram)

  4. The UDP socket is used to send the payload to the TargetHost

netcallback TCP receive diagram

  1. The UDP service on the TargetHost possibly replies to the UDP datagram by sending a datagram addressed to the PrivateServer at the client-specific socket (i.e. port).
  2. Upon receipt the dedicated PrivateServer thread for this socket (which knows the real destination) writes the actual destination address/port and payload over the shared TCP/SSL connection.
  3. Upon receipt of the streamed datagram in the PublicServer, a datagram with the specified information (address/port/payload) is transmitted.

Usage

PublicServer java -jar netcallback.jar -public { -ssl } -servicePort <port> { -tcpPort <port> } { -udpPort <port> }
-ssl optional flag to enable SSL communication between servers
-servicePort port port used to receive private server communications
-tcpPort port clients use this TCP port to use tunnel
-udpPort port clients use this UDP port to use tunnel
PrivateServer java -jar netcallback.jar -private { -ssl } -service <host> <port> { -tcp <host> <port> } { -udp <host> <port> }
-ssl optional flag to enable SSL communication between servers
-service host port name and port of host executing public server
-tcp host port TCP redirection target host and port
-udp host port UDP redirection target host and port

Public server examples executing on host "free" (without SSL/with SSL):

java -jar netcallback.jar -public -servicePort 1234 -tcpPort 8080 -udpPort 1616

java -jar -Djavax.net.ssl.trustStore=keystore -Djavax.net.ssl.keyStore=keystore -Djavax.net.ssl.keyStorePassword="testing" netcallback.jar -public -ssl -servicePort 1234 -tcpPort 8080 -udpPort 16161

Private server examples executing contacting public server on host "free" and exposing the telnet service on host "protected" (without SSL/with SSL):

java -jar netcallback.jar -private -service free 1234 -tcp protected 80 -udp protected 161

java -jar -Djavax.net.ssl.trustStore=keystore -Djavax.net.ssl.keyStore=keystore -Djavax.net.ssl.keyStorePassword="testing" netcallback.jar -private -ssl -service free 1234 -tcp protected 80 -udp protected 161

Web-access (TCP) and SNMP access (UDP) forwarding examples (UNIX)

lynx http://free:8080
snmpwalk -v 1 -p 1616 free public

Secure Socket Layer (SSL) Support

NetCallback supports encrypted socket communications using the Java Secure Socket Extension (JSSE). SSL is used to encrypt communication between the PublicServer and the PrivateServer, however, the connection between the PrivateServer and the private host, as well as the connection between the PublicServer and the client are NOT ENCRYPTED!.
  1. Download the Java JSSE from the URL http://java.sun.com/products/jsse/ (Starting with JDK1.4 SSL support is a standard part of Java2 and does not need to be downloaded).

  2. Unzip the downloaded package and follow the installation instructions. In particular, verify that (again, if your running JDK 1.4 or above you don't need to perform these steps):

  3. Create an RSA public/private key to be used in the session using the keytool utility found in $JAVA_HOME/bin. Bold items indicate user input (clearly users should pick a different password and user identity!):
    keytool -genkey -v -keyalg RSA -keystore keystore
    Enter keystore password:  testing
    What is your first and last name?
      [Unknown]:  Alexander Konstantinou
    What is the name of your organizational unit?
      [Unknown]:  Computer Science
    What is the name of your organization?
      [Unknown]:  Columbia University
    What is the name of your City or Locality?
      [Unknown]:  New York
    What is the name of your State or Province?
      [Unknown]:  NY
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is <CN=Alexander Konstantinou, OU=Computer Science, O=Columbia University, L=New York, ST=NY, C=US> correct?
      [no]:  yes
    
    Generating 1024 bit RSA key pair and self-signed certificate (MD5WithRSA)
    	for: CN=Alexander Konstantinou, OU=Computer Science, O=Columbia University, L=New York, ST=NY, C=US
    Enter key password for <mykey>
    	(RETURN if same as keystore password):  
    [Saving keystore]
    
    
  4. Invoke the Java interpeter for the PublicServer (-public) and the PrivateServer (-private) with the following three flags:

Requirements

History

Downloading

The latest version of NetCallback can be found at the URL http://netcallback.sourceforge.net/

The download package includes the NetCallback source code and binary files as well as the current documentation. It is available in two formats: ZIP (Windows) and TAR/GZIP (Unix).


Please address comments/questions to akonstan@acm.org

$Id: README.html,v 1.3 2004/02/16 02:12:50 akonstan Exp $