FIREPASS VERSION 1.1.0a
=======================

ABOUT
=====

  FIREPASS is a tunneling tool which encapsulate data  flows  inside  HTTP  POST
  legal requests in order to bypass firewall  restrictions.  TCP  or  UDP  based
  protocols can be tunneled with FIREPASS. For now, both  -  client  and  server
  parts are written in Perl. The server script acts as a CGI program.
   
  To run FIREPASS you need:

     * Some box located inside the local network with Perl, and ability to  send
       HTTP messages to the external  network  (Internet),  either  directly  or
       trough an HTTP proxy;
     * An httpd server located in the external network (with  Perl  also)  where
       you  can  place / run  CGI  scripts  and  which  can  establish  outgoing
       connections (Most of the commerce hosting providers and some public  ones
       are allowing this);

  The FIREPASS key feature is that you may use several type of  installation  of
  the server part script in the external network. You do not need  to  bind  any
  port on the external box. Everything looks clear from local and external boxes
  administrators point of view. There is  only  an  usual  HTTP  dialog  between
  client and server. The only problem is that HTTP messages are send too often..
  But this is configurable in the FIREPASS client with a  special  delay  option
  between HTTP requests. It may be applied to some non time critical  protocols.
  FIREPASS may also be usable for the reverse task, when the  server  script  is
  located at the corporative web server and when client interact  with  it  from
  the external network.

  This FIREPASS version is an alpha one, so it may still  be  some  bugs...  and
  SECURITY bugs also.  Please, read  the  section  "HOW IT WORKS"  carefully  to
  understand clearly all possible  risks  you  may  be  exposed  to  when  using
  FIREPASS. I do not provide any guarantees of it's correct work.

HOW IT WORKS
============

  TCP/UDP clients                                               TCP/UDP services
   \\\                                                            ^^^
 (5)\\\(1)                                                     (3)|||
     \\\                                                          |||
  |----------|        (2)        |----------|        (2)        |----------|
  | HOST "A" | --- HTTP POST --> | Host "B" | --- HTTP POST --> | Host "C" |
  |          | <---------------- |HTTP proxy| <---------------- | httpd    |
  |----------|        (4)        |----------|        (4)        |----------|
  FIREPASS client                (optional)                     FIREPASS server
  fpclient.pl                                              /cgi-bin/fpserver.cgi

  (1) The TCP/UDP client connects to Host "A", where FIREPASS client is  running
      and listening on a TCP/UDP port as a daemon;
  (2) FIREPASS client accepts the connection, reads data, builds a connection to
      Host "C" directly or via HTTP proxy  and  sends  data  to  httpd  (to  the
      default port 80/TCP) as an  HTTP  post  request  to  the  FIREPASS  server
      script; If this is  the  first  request  for  the  current  session,  then
      FIREPASS client attaches additional HTTP header lines with  redirect  rule
      information.
  (3) FIREPASS server reads data from STDIN  (as  specified  by  CGI  protocol).
      Then, if this is the first HTTP message for the  current  session  -  fork
      Connection Manager, if not - transfers data to existing Connection Manager
      trough files in Host "C" local directory. Connection  manager  reads  data
      from local file. Builds TCP/UDP connection to  target  service  and  sends
      data. If some data may be readed from target  service,  it  reads  it  and
      transfers to the FIREPASS server CGI script trough another Host "C"  local
      file.
  (4) On each run, FIREPASS server CGI script checks  local  file  for  incoming
      data and if data is present - sends it to  the  FIREPASS  client  as  HTTP
      response message.
  (5) FIREPASS client receives data from target  service  inside  HTTP  message,
      extracts it and sends it to it's client.

      That's it! If there is no incoming/outgoing data, FIREPASS client / server
      just sends empty HTTP request/response messages.

INSTALL
=======

  Inside `` - shell commands.

  SERVER HOST (httpd)
  -------------------

    * Place FIREPASS server script  'fpserver/fpserver.cgi' and  'fpserver/conf'
      directory under target host 'cgi-bin' directory, check path to perl in the
      fpserver.cgi (default /bin/perl);

    * Create 2 directories - 'inout' and 'log' (for example into /var/tmp)

        `chmod 777 inout log` or
        `chown <httpd_user>:<httpd_group> inout log && chmod 700 inout log`

      fpserver.cgi should be able to read/write files inside these directories;

    * Update FIREPASS server configuration files:

      conf/fpserver.conf  : Configuration file;
      conf/fpserver.allow : Access list file.

    * Run fpserver.cgi with 'configure' option and path to fpserver.conf file:

        `./fpserver.cgi configure conf/fpserver.conf`

      After configure fpcnf.cache file will be created nearby the fpserver.cgi.

  CLIENT HOST
  -----------

    * Check path to perl in the FIREPASS client script fpclient.pl;
    * Update FIREPASS client configuration files:

      conf/fpclient.conf  : Configuration directives;
      conf/fpclient.rules : Redirect rules;
      conf/fpserver.allow : Access list file.

  All pathes in the '.conf' files  should be absolute or relative to the  script
  file location.

  -NOTE-------------------------------------------------------------------------
    Some httpds (Russian Apache for example) may modify data before pass  it  to
    CGI script to support server  default  cyrillic  encoding.  Data  flow  gets
    corrupted because of this. Turn off this web server "feature".
    For Russian Apache add next lines to httpd.conf file:

    <Location /cgi-bin/fpserver.cgi>
         CharsetDisable On
    </Location>
  
    ..and restart httpd
  ----------------------------------------------------------------------------

USAGE
=====

  Run FIREPASS client:
  ./fpclient.pl conf/fpclient.conf [SERVER]/cgi-bin/fpserver.cgi

PLATFORMS
=========

  I've tested it with:
     * SunOS 5.8 + Perl 5.005_03;
     * Mandrake Linux (kernel version 2.4.19) + Perl 5.8.0;

  I'm hope, that FIREPASS would work with any UNIX platform, even may be in  WIN
  environment (not tested yet). If not, contact me and i will try to help you.

EXAMPLES
========

  I'm succesfully use FIREPASS to tunnel next protocols:
     * TELNET; not too fast ;)
     * HTTP; Seems to work for me.  I  recommend  you  to  use  HTTP/1.0  +  non
       "Keep-Alive"   connection  from   your  favourite   browser  to   prevent
       unnecessary FIREPASS traffic.
     * ICQ;  Some  problems   were  here..  While  application  level  handshake
       procedure ICQ tries to establish more than 12 tcp connections in the same
       time. Some HTTP proxies (and one i play with also) may not allow  such  a
       great number of connections from one IP. Thats why proxy can answer  with
       HTTP  "Forbidden"  message   on  the  next   connection  attemp.  I  make
       walkaround: while keeping connection to ICQ client alive, FIREPASS client
       keep trying to build connection trough HTTP proxy, until it gets HTTP/200
       response. Actually, ICQ sometimes works and sometimes not..   Because  of
       HTTP/404 "Not found" errors from login.icq.com server without any  reason
       (from my point of view). If there is someone familiar with  ICQ  protocol
       here, write me email to discuss this problem.

LICENSE
=======

  Firepass is distributed under the terms of the GNU General Public License v2.0
  See the file COPYING for details.

AUTHOR
======

  Alex Dyatlov <alex@gray-world.net>

  Project homepage: http://gray-world.net
  Firepass Message board is also available at http://gray-world.net/board/
  Feature requests and bug reports are welcome!

THANKS
======

  Simon Castro <scastro@entreelibre.com>
    French README. FIREPASS testing. English spelling mistakes checking.
    
  Hadi El-Khoury <helkhoury@entreelibre.com>
    English spelling mistakes checking.
