FIREPASS VERSION 1.0.2a

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. C versions will be published soon..
   
  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

  Sorry for this slightly uncomfortable installation procedure, I hope  to  make
  it more user friendlier in the future... Too many bugs to fight with now.. :)

  - Server host (httpd):
    * Place FIREPASS server script  'fpserver/fpserver.cgi'  under  target  host
      'cgi-bin' directory, check path to perl;
    * Create 2 directories 'inout' and 'log' (for example in /var/tmp directory)
      `chmod 777 inout log` or
      `chown nobody:nobody inout log && chmod 700 inout log`
      - fpserver.cgi should be able to read/write files inside these directories;
    * Update configuration header in fpserver.cgi;
    ----------------------------------------------------------- fpserver.cgi ---
    ...
    my $inoutdir = "/var/tmp/inout"; # Path to existing data exchange directory
    my $logdir = "/var/tmp/log";     # Path to existing log directory
    my $logf = "fpserver.log";       # Log file name
    my $inm = "_in.dat";             # Echange files masks
    my $outm = "_out.dat";
    my $lockm = ".lock";
    my $log = "no";                  # ("no" | "yes") Create log file?
    my $useacl = "yes";              # ("no" | "yes") Use access list?
    my @ALLOW = qw (
            127.0.0.1
            111.222.33.4
    );                               # Access list, one IP on each line
    my $initdelay = .3;              # New connection initialization delay (sec)
    my $checkdelay = .3;             # Data exchange files check delay
    my $faketype = "text/html";
    my $fakepage = qq (
            <html>
            <body></body>
            </html>
    );                               # HTML page for browsers requests
    my $readsize    = 20480; 
    ----------------------------------------------------------- fpserver.cgi ---
    Minimal changes you should make here:
    + Set <$inoutdir> and <$logdir> (if <$log> = "yes") to your new directories;
    + Add FIREPASS client host ip to <@ALLOW> or Set <$useacl> to "no";
    Optional:
    + Try to play with <$initdelay>  and  <$checkdelay>  variables  if  you  are
      unhappy with FIREPASS performance.

  - Client host:
     * Check conf/fpclient.conf  - Configuration directives;
             conf/fpclient.rules - Redirect rules;
     * Check path to perl in the FIREPASS client script -  fpclient.pl,  you  do
       not need to do any changes in this file configuration section.

  Ughhh.. seems that you are ready to use your tunnel now ;)

    -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 your_apache.com/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.
