AF - Active Port Forwarder 0.6 - README Copyright (C) 2003,2004,2005 jeremian - ================================================================= ================================================================================ GRAY-WORLD.NET / Active Port Forwarder ====================================== The Active Port Forwarder program is part of the Gray-World.net projects. Our Gray-World Team presents on the http://gray-world.net website the projects and publications we are working on which are related to the NACS (Network Access Control System) bypassing research field and to the computer and network security topics. ================================================================================ ======= SUMMARY ======= INTRO 1. INSTALLATION 1.1 Instructions 1.2 Required libs 1.3 Tested platforms 2. USAGE 2.1 afserver 2.2 afclient 3. REMOTE ADMINISTRATION 4. MODULES 5. EXAMPLES 5.1 tcp mode 5.2 reverse udp mode 6. BUGS/PROBLEMS NOTES THANKS ================================================================================ ===== INTRO ===== Active port forwarder is a software tool for secure port forwarding. It uses ssl to increase security of communication between a server and a client. Originally, it was developed to forward data point to point. However, the need for bypassing firewalls in order to connect to internally located computers influenced the further development of the project. AF is dedicated for people, who don't have an external ip number and want to make some services available across the net. Moreover, zlib is used to compress the transferred data. Using one, permanent data/control channel with flow control / packet buffering provides good performance and reasonably small latency. Multiple clients allow to create more sophisticated tunneling scheme. ================================================================================ =============== 1. INSTALLATION =============== 1.1 Instructions ---------------- 1. Download the compressed sources from http://www.gray-world.net/pr_af.shtml 2. Unpack them with tar zxvf 3. Type "./configure" 4. Type "make" 5. Type "make install" while logged as root 6. If something goes wrong - mail the author or post a message on http://gray-world.net/board/ 1.2 Required libs ----------------- 1. openssl - http://www.openssl.org/ 2. zlib - http://www.gzip.org/zlib/ 1.3 Tested platforms -------------------- 1. Linux: Gentoo, Slackware, Mandrake - built without any problems 2. Windows: win32 - cygwin version is available on the project homepage ================================================================================ ======== 2. USAGE ======== 2.1 afserver ------------ Basic options: -n, --hostname - it's used when creating listening sockets (default: '') -l, --listenport - listening port number - users connect to it (default: 50127) -m, --manageport - manage port number - second part of the active port forwarder connects to it (default: 50126) -h, --help - prints this help Authorization: --pass - set the password used for client identification (default: no password) Configuration: -c, --cerfile - the name of the file with certificate (default: cacert.pem) -k, --keyfile - the name of the file with RSA key (default: server.rsa) -f, --cfgfile - the name of the file with the configuration for the active forwarder (server) -D, --dateformat - format of the date printed in logs (see 'man strftime' for details) (default: %d.%m.%Y %H:%M:%S) -t, --timeout - the timeout value for the client's connection (default: 5) -u, --users - the amount of users allowed to use this server (default: 5) -C, --clients - the number of allowed clients to use this server (default: 1) -r, --realm - set the realm name (default: none) -R, --raclients - the number of allowed clients in remote administration mode to use this server (default: 1) -U, --usrpcli - the number of allowed users per client (default: $users) -M, --climode - strategy used for connecting users with clients (default: 1) Available strategies: 1. fill first client before go to next -p, --proto - type of server (tcp|udp) - for which protocol it will be operating (default: tcp) -b, --baseport - listenports are temporary and differ for each client --nossl - ssl is not used for transferring data (but it's still used to establish a connection) (default: ssl is used) --nozlib - zlib is not used for compressing data (default: zlib is used) --dnslookups - try to obtain dns names of the computers rather than their numeric IP Logging: -O, --heavylog - logging everything to a logfile -o, --lightlog - logging some data to a logfile -S, --heavysocklog - logging everything to a localport -s, --lightsocklog - logging some data to a localport -v, --verbose - to be verbose - program won't enter the daemon mode (use several times for greater effect) IP family: -4, --ipv4 - use ipv4 only -6, --ipv6 - use ipv6 only 2.2 afclient ------------ Basic options: -n, --servername - where the second part of the active port forwarder is running (required) -m, --manageport - manage port number - server must be listening on it (default: 50126) -d, --hostname - the name of this host/remote host - the final destination of the packets (default: the name returned by hostname function) -p, --portnum - the port we are forwarding connection to (required) -h, --help - prints this help Authorization: -i, --id - send the id string to afserver --pass - set the password used for client identification (default: no password) Configuration: -k, --keyfile - the name of the file with RSA key (default: client.rsa) -D, --dateformat - format of the date printed in logs (see 'man strftime' for details) (default: %d.%m.%Y %H:%M:%S) Modes: -u, --udpmode - udp mode - client will use udp protocol to communicate with the hostname -U, --reverseudp - reverse udp forwarding. Udp packets will be forwarded from hostname:portnum (-p) to the server name:portnum (-m) -r, --remoteadmin - remote administration mode. (using '-p #port' will force afclient to use port rather then stdin-stdout) Logging: -O, --heavylog - logging everything to a logfile -o, --lightlog - logging some data to a logfile -S, --heavysocklog - logging everything to a localport -s, --lightsocklog - logging some data to a localport -v, --verbose - to be verbose - program won't enter the daemon mode (use several times for greater effect) IP family: -4, --ipv4 - use ipv4 only -6, --ipv6 - use ipv6 only Modules: -l, --load - load a module for user's packets filtering -L, --Load - load a module for service's packets filtering ================================================================================ ======================== 3. REMOTE ADMINISTRATION ======================== Afclient can be started in remote administration mode by '-r, --remoteadmin' option. Required option: '-n, --servername NAME'. After successful authorization stdin/stdout is used to communicate with user. All the commands parsing is done by afserver. Currently available commands are: help display help lcmd lists available commands info prints info about server rshow display realms cshow X display clients in X realm ushow X display users in X realm quit quit connection Afclient with '-p, --portnum PORT' option listens for connection from user at NAME:PORT. NAME is set by '-d, --hostname' option or hostname() function, when the option is missing. When user quits (close the connection or send 'quit' command), afclient exits. ================================================================================ ========== 4. MODULES ========== Afclient can use external modules for user's packets filtering ('-l, --load') and service's packets filtering ('-L, --Load'). Module file has to declare three functions: char* info(void); info() return values: - info about module Example: char* info(void) { return "Module tester v0.1"; } int allow(char* host, char* port); allow() return values: 0 - allow to connect !0 - drop the connection Example: int allow(char* host, char* port) { return 0; /* allow to connect */ } int filter(char* host, unsigned char* message, int* length); filter() return values: 0 - allow to transfer 1 - drop the packet 2 - drop the connection 3 - release the module 4 - drop the packet and release the module 5 - drop the connection and release the module Example: int filter(char* host, unsigned char* message, int* length) { int i; for (i = 1; i < *length; ++i) { if (message[i-1] == 'M') { if (message[i] == '1') { return 1; /* ignored */ } if (message[i] == '2') { return 2; /* dropped */ } if (message[i] == '3') { return 3; /* release */ } if (message[i] == '4') { return 4; /* ignored + release */ } if (message[i] == '5') { return 5; /* dropped + release */ } } } return 0; /* allow to transfer */ } Modules have to be compiled with '-fPIC -shared' options. ================================================================================ =========== 5. EXAMPLES =========== 5.1 tcp mode ------------ local network |FireWall| Internet || || User 1 || /(tcp) AF Client <---Encrypted/Compressed channel---> AF Server / || | \(tcp) /(tcp) || (tcp)| User 2 / || \ Http server || User 3 || The use of it is extremely simple. Let's suppose we want to create a http server on our computer and we are behind a masquerade or a firewall: 1) We have to find some machine on the net with an external ip and a shell account. 2) Use "make" to compile everything on that machine. (you can freely remove the afclient and client.rsa files) 3) You can edit the config file or just type from the console (to use the config type -f ) : $ ./afserver This will work, if you want to use default values: - hostname will be taken from hostname function (it would be ideally, if there is appropriate registration in /etc/hosts) - server will be listening for users on port 50127 - server will be listening for client on port 50126 - server will be for maximum 5 users - server will forward tcp packets - there will be no logging and no verbose messages - there will be no password identification - ip protocol family will be unspecified 4) We use "make" on our machine (we can delete everything apart from afclient and client.rsa) 5) We are typing from the console: $ ./afclient -n -p 80 Where is a string like : 'bastion.univ.gda.pl' or '153.19.7.200' 6) We can now enter with a web-browser to: :50127 and we will enter to our computer in the fact. 5.2 reverse udp mode -------------------- local network |FireWall| Internet || (udp) || User 1-------AF Client || /(tcp) AF Client <---Encrypted/Compressed channel---> AF Server / || | /(udp) || (tcp)| / || / Game server || AF Client-------User 2 || (udp) Let's see how to use af to forward udp packets. Suppose we want to create a game server on our computer (udp port 27960 on our machine): 1) - 4) is the same like in example 1. (but we add option: -p udp) 5) We are typing from the console: $ ./afclient -u -n -p 27960 Where is a name (or ip) of a host where our server is running. 6) Connecting to our game is more complicated. The user must use afclient to do this. He has to specify the server he is connecting to and the port, which his program will be listening on: $ ./afclient -U -d -p -n \ -m Where is the name of the user machine (who wants to connect to our game). is the port he will be connecting to. is the name of the host where our server is running. is the port on which the server is listening for users. In order to connect to our game, the user has to connect to :. ================================================================================ ================ 6. BUGS/PROBLEMS ================ There are no known/open bugs at the moment. ================================================================================ ===== NOTES ===== Active port forwarder is still under development, so please sent any comments, bugs notices and suggestions about it to If you have some problems or want to share your opinions with others, feel free to post a message at http://gray-world.net/board/ ================================================================================ ====== THANKS ====== Big thanks to the GW Team: to Alex and Simon for testing AF and a lot of advices. Thanks to Ilia Perevezentsev who read and corrected the README file. Thanks to Marco Solari for a lot of requests, suggestions and ideas. And thanks for using this software! LICENSE ------- Active Port Forwarder is distributed under the terms of the GNU General Public License v2.0 and is copyright (C) 2003,2004,2005 jeremian . See the file COPYING for details.