v0.6

  - Fixed: default password incompatibilities from config file
  - Added: "client's id" option
  - Lightly Modified: verbose mode
  - Added: temporary listen ports
  - Fixed: bug in printing "client's id"
  - Added: 'dateformat' option to set format of the date in the logs
  - Modified: command line option and config file behaviour
  - Added: logging to a socket
  - Fixed: parsing config file
  - Fixed: major bug in packet buffering
  - Added: several clients-users in one realm
  - Modified: default hostname used by afserver
  - Modified: server listening behaviour (for clients)
  - Fixed: bug in checking options values
  - Modified: verbose mode
  - Modified: client initial connection to server
  - Added: connection time / uptime statistics
  - Added: first version of remote administration (statistics only)
  - Fixed: major bug in remove_client routine
  - Added: 'raclients' option
  - Added: use of automake/autoconf
  - Added: creating ~/.apf directory
  - Modified: the way of creating/managing keys/certificates
  - Added: 'dnslookups' option
  - Modified: usage functions
  - Fixed: no handling of missing 'listen' option after 'newrealm' in config file
  - Added: 'quit' command in remote administration mode
  - Modified: logging error messages during initialization
  - Modified: 'newrealm' changed to 'realm' in config file
  - Added: realm names
  - Modified: connection time / uptime
  - Added: client names / unique numbers
  - Added: user unique numbers
  - Fixed: segmentation fault after 'quit' command

1 files changed, 479 insertions, 0 deletions

diff --git a/doc/en/README b/doc/en/README
new file mode 100644
index 0000000..0e49c3e
--- /dev/null
+++ b/doc/en/README
@@ -0,0 +1,479 @@
+AF - Active Port Forwarder 0.6 - README
+Copyright (C) 2003,2004,2005 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
+4. MODULES
+5. EXAMPLES
+  5.1 tcp mode
+  5.2 reverse udp mode
+6. 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 port number - users connect
+                        to it (default: 50127)
+  -m, --manageport    - manage port number - second part of the active
+                        port forwarder connects to it (default: 50126)
+  -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: cacert.pem)
+  -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)
+  -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 for connecting users with clients
+                        (default: 1)
+                      Available strategies:
+                        1. fill first client before go to next
+
+  -p, --proto         - type of server (tcp|udp) - for which protocol it will
+                        be operating (default: tcp)
+  -b, --baseport      - listenports are temporary and differ for each client
+  --nossl             - ssl is not used for transferring data (but it's still
+                        used to establish a connection) (default: ssl is used)
+  --nozlib            - zlib is not used for compressing data (default:
+                        zlib is used)
+  --dnslookups        - try to obtain dns names of the computers rather than
+                        their numeric IP
+
+ Logging:
+
+  -O, --heavylog      - logging everything to a logfile
+  -o, --lightlog      - logging some data to a logfile
+  -S, --heavysocklog  - logging everything to a localport
+  -s, --lightsocklog  - logging some data to a localport
+  -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
+
+  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)
+  -h, --help          - prints this help
+
+ Authorization:
+
+  -i, --id            - send the id string to afserver
+  --pass              - set the password used for client identification
+                        (default: no password)
+
+ Configuration:
+
+  -k, --keyfile       - the name of the file with RSA key (default: client.rsa)
+  -D, --dateformat    - format of the date printed in logs (see 'man strftime'
+                        for details) (default: %d.%m.%Y %H:%M:%S)
+
+ Modes:
+
+  -u, --udpmode       - udp mode - client will use udp protocol to
+                        communicate with the hostname
+  -U, --reverseudp    - reverse udp forwarding. Udp packets will be forwarded
+                        from hostname:portnum (-p) to the server name:portnum
+                        (-m)
+  -r, --remoteadmin   - remote administration mode. (using '-p #port' will
+                        force afclient to use port rather then stdin-stdout)
+
+ Logging:
+
+  -O, --heavylog      - logging everything to a logfile
+  -o, --lightlog      - logging some data to a logfile
+  -S, --heavysocklog  - logging everything to a localport
+  -s, --lightsocklog  - logging some data to a localport
+  -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
+
+================================================================================
+
+========================
+3. REMOTE ADMINISTRATION
+========================
+
+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.
+
+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
+
+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. 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.
+
+================================================================================
+
+===========
+5. EXAMPLES
+===========
+
+  5.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.
+
+  5.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>.
+
+================================================================================
+
+================
+6. 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.
+
+ 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,2004,2005  jeremian  <jeremian
+  [at] poczta.fm>. See the file COPYING for details.
+