diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 685 |
1 files changed, 0 insertions, 685 deletions
@@ -1,685 +0,0 @@ -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. |