Renamed readme file to be displayed on github.

1 files changed, 685 insertions, 2 deletions

diff --git a/README.md b/README.md
index a1fdec2..e9f5b20 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,685 @@
-apf
-===
+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.