summaryrefslogtreecommitdiff
path: root/doc/en/README
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en/README')
-rw-r--r--doc/en/README685
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.