diff options
Diffstat (limited to 'doc/en/README')
| -rw-r--r-- | doc/en/README | 685 |
1 files changed, 685 insertions, 0 deletions
diff --git a/doc/en/README b/doc/en/README new file mode 100644 index 0000000..e9f5b20 --- /dev/null +++ b/doc/en/README @@ -0,0 +1,685 @@ +AF - Active Port Forwarder 0.8.4 - README +Copyright (C) 2003-2007 jeremian - <jeremian [at] poczta.fm> +================================================================= + +================================================================================ + +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 <cfgfile>) : + $ ./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 <name of the server> -p 80 + Where <name of the server> is a string like : 'bastion.univ.gda.pl' or + '153.19.7.200' + +6) We can now enter with a web-browser to: <name of the server>: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 <name of the server> -p 27960 + Where <name of the server> 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 <hostname> -p <portnum> -n <name of the server> \ + -m <server port> + Where <hostname> is the name of the user machine (who wants to connect to our + game). <portnum> is the port he will be connecting to. <name of the server> + is the name of the host where our server is running. <server port> is the + port on which the server is listening for users. In order to connect to our + game, the user has to connect to <hostname>:<portnum>. + +================================================================================ + +================ +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 <jeremian [at] poczta.fm> + +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 <alex [at] gray-world.net> + and Simon <scastro [at] entreelibre.com> for testing AF and a lot of advices. + + Thanks to Ilia Perevezentsev <iliaper [at] mail.ru> who read and corrected the +README file. + + Thanks to Marco Solari <marco.solari [at] koinesistemi.it> for a lot of +requests, suggestions and ideas. + + Thanks to Joshua Judson Rosen <rozzin [at] geekspace.com> 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 <jeremian + [at] poczta.fm>. 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. |