AF - Active Port Forwarder 0.8.4 - README Copyright (C) 2003-2007 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 3.1 Usage 3.2 Commands 3.3 States 3.3.1 Users 3.3.2 Clients 3.4 Relay mode 4. HTTP PROXY TUNNELS 5. LOGGING 6. MODULES 7. MULTI TUNNELS 8. EXAMPLES 8.1 tcp mode 8.2 reverse udp mode 9. 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 [host:]port - users connect to it (default: 50127) -m, --manageport - manage [host:]port - afclient connects to it (default: 50126) -V, --version - display version number -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: server-cert.pem) -A, --cacerfile - the name of the file with CA certificates (if used, require clients to have valid certificates) -d, --cerdepth - the maximum depth of valid certificate-chains -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) --maxidle - the maximum idle time for the client's connection (default: disabled) -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 to connect users with clients (default: 1) Available strategies: 1. fill first client before go to next -p, --proto - type of server (tcp|udp) - what protocol it will be operating for (default: tcp) -b, --baseport - listenports are temporary and differ for each client -a, --audit - additional information about connections are logged --nossl - ssl is not used to transfer data (but it's still used to establish a connection) (default: ssl is used) --nozlib - zlib is not used to compress data (default: zlib is used) --dnslookups - try to obtain dns names of the computers rather than their numeric IP Logging: -o, --log - log choosen information to file/socket -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 HTTP PROXY: -P, --enableproxy - enable http proxy mode 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) --localname - local machine name for connection with afserver (used to bind socket to different interfaces) --localport - local port name for connection with afserver (used to bind socket to different addressees) --localdesname - local machine name for connections with destination application (used to bind socket to different interfaces) -V, --version - display version number -h, --help - prints this help Authorization: -i, --id - sends the id string to afserver --pass - set the password used for client identification (default: no password) --ignorepkeys - ignore invalid server's public keys Configuration: -k, --keyfile - the name of the file with RSA key (default: client.rsa) -c, --cerfile - the name of the file with certificate (default: no certificate used) -f, --cfgfile - the name of the file with the configuration for the active forwarder (client) -s, --storefile - the name of the file with stored public keys (default: known_hosts) -D, --dateformat - format of the date printed in logs (see 'man strftime' for details) (default: %d.%m.%Y %H:%M:%S) -K, --keep-alive N - send keepalive packets every N seconds (default: not send keepalive packets) Auto-reconnection: --ar-start - enable auto-reconnection when afserver is not reachable on start (default: disabled) --ar-quit - enable auto-reconnection after normal afserver quit (default: disabled) --noar - disable auto-reconnection after premature afserver quit (default: enabled) -A, --ar-tries N - try N times to reconnect (default: unlimited) -T, --ar-delay N - wait N seconds between reconnect tries (default: 5) Modes: -u, --udpmode - udp mode - client will use udp protocol to communicate with the hostname:portnum -U, --reverseudp - reverse udp forwarding. Udp packets will be forwarded from hostname:portnum to the server name:manageport -r, --remoteadmin - remote administration mode. (using '-p #port' will force afclient to use port rather than stdin-stdout) Logging: -o, --log - log choosen information to file/socket -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 HTTP/HTTPS PROXY: -S, --use-https - use https proxy instead of http proxy -P, --proxyname - the name of the machine with proxy server -X, --proxyport - the port used by proxy server (default: 8080) -C, --pa-cred U:P - the user (U) and password (P) used in proxy authorization -B, --pa-t-basic - the Basic type of proxy authorization (default) ================================================================================ ======================== 3. REMOTE ADMINISTRATION ======================== 3.1 Usage --------- 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. 3.2 Commands ------------ 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 timeout N X set timeout value in X realm audit {0|1} X set audit mode in X realm dnslookups {0|1} X set dnslookups mode in X realm dateformat S set dateformat kuser S kick user named S kclient N kick client with number N 3.3 States ---------- 3.3.1 Users ----------- Connected users can be in several states: running user is properly connected and can send/receive data opening user is connected to afserver, but afclient hasn't confirmed connection with the destination. There is no traffic allowed in this situation. opening (closed) user was in 'opening' state, but 'kuser' command has been used and it's now queued for closing as soon as afclient will be ready to confirm this stopped user wasn't responsible, so all the packets addressed to it are queued. Afclient is informed to not receive any packets for this user. closing connection with user has been lost. Afclient has to confirm user deletion unknown probably afserver internal state has been corrupted. 3.3.2 Clients ------------- Connected clients can be in several states: running client is properly connected and can serve user's requests ssl handshake connection with client has been initialized and now ssl routines are negotiating all the details needed to establish secure tunnel. This stage with 'authorization' must not exceed the time set by 'timeout' option. authorization ssl tunnel is ready and afclient has to authorize itself to the afserver. This stage with 'ssl handshake' must not exceed the time set by 'timeout' option. unknown probably afserver internal state has been corrupted. 3.4 Relay mode -------------- 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. HTTP PROXY TUNNELS ===================== Afclient can communicate with afserver via HTTP proxy. In order to use this feature, afserver must be started with '-P, --enableproxy' option. Afclient must specify the proxy host ('-P, --proxyname' option) and port ('-X, --proxyport' option). Afclient with HTTP proxy mode enabled can still accept connections from afclients, which don't use HTTP proxy mode. ================================================================================ ========== 5. LOGGING ========== Logging can be enabled by '-o, --log' option. The argument to this option must be in the form: target,description,msgdesc Where target is file or sock description is filename or host,port msgdesc is the subset of: LOG_T_ALL, LOG_T_USER, LOG_T_CLIENT, LOG_T_INIT, LOG_T_MANAGE, LOG_T_MAIN, LOG_I_ALL, LOG_I_CRIT, LOG_I_DEBUG, LOG_I_DDEBUG, LOG_I_INFO, LOG_I_NOTICE, LOG_I_WARNING, LOG_I_ERR written without spaces. Example: file,filename,LOG_T_MANAGE,LOG_I_ALL ================================================================================ ========== 6. 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. ================================================================================ ================ 7. MULTI TUNNELS ================ Since version 0.8 it's possible to transfer multiple tunnels in the one afclient <-> afserver connection. On the afserver we have to specify multiple listen ports with the same manage port. When we set several '-p' options on the afclient, the new user connections will be distributed according to the sequence of the options, i.e. new user connecting to the second UsrCli pair (with the same manage ports) will be transferred to the destination pointed by the second '-p' option. ================================================================================ =========== 8. EXAMPLES =========== 8.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. 8.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 :. ================================================================================ ================ 9. 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. Thanks to Joshua Judson Rosen for the patch adding certificate-based authentication to the APF. 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-2007 jeremian . See the file COPYING for details. In addition, as a special exception, the copyright holders give permission to link the code of portions of this program with the OpenSSL library under certain conditions as described in each individual source file, and distribute linked combinations including the two.