-------------------------------------------------------------------
               Libwhisker official release v1.3
-------------------------------------------------------------------

What is libwhisker:

Libwhisker is a Perl module geared specificly for HTTP testing.
Libwhisker has a few design principles:

- Portable: runs with 0 changes on Unix, Windows, etc.
- Flexible: designed with a 'no rules' approach
- Contained: does not require any external Perl modules
- Localized: does not require installation to use


-------------------------------------------------------------------
  README README README README README README README README README
-------------------------------------------------------------------

"How do I run/use libwhisker?"

Libwhisker is not a program to run.  It's a library for people to
make programs with.  There is nothing to 'run' in libwhisker.  If
you're looking for a CGI scanner (whisker), you're in the wrong
place.  Whisker is separate from libwhisker.


-------------------------------------------------------------------
               Information on libwhisker library
-------------------------------------------------------------------

Libwhisker's 'no rules' approach:

Since the intent of this library is to use it in testing and
quality assurance situations, odds are the library will need to be
capable of handling protocol malformities and other wackiness.  
Many existing Perl libraries are not flexible when you try to break 
the protocol--they assume you want to make a legitimate request.
Libwhisker, on the other hand, is designed to not impose any rules
on the software, thus allowing it to do whatever it really wants
to do, including stuff not normally considered 'legal' or 'sane'.

-------------------------------------------------------------------

What libwhisker can do for you:

Do you have a demonstration program, application, or exploit that
interacts over HTTP?  Well, using libwhisker means your program:

- Can communicate over HTTP 0.9, 1.0, and 1.1
- Use persistant connections (keep-alives)
- Has proxy support
- Has anti-IDS support
- Has SSL support
- Can handle chunked encoding
- Has nonblock/timeout support built in (platform-dependant...)

That way you don't have to code it all yourself--use libwhisker
and all those features are transparently available automatically.
So call now, operators are standing by.

-------------------------------------------------------------------

Why not use other perl modules?

Libwhisker actually combines the functionality LWP, URI, HTML::Parser,
MIME::Base64, and a handful of other modules into a single file that is
approximately 60k (when POD is stripped).

One of the annoyances of LWP et. al. is that they require local system
installation before they can be used--and that installation typically
requires compilation of C code files.  This can be a problem if you have a
system that lacks a compiler (commercial unix platforms, Windows, etc),
and it also makes portability very difficult.  Libwhisker is 100% native
Perl, so no additional compilers are necessary.  It's one single 60k text
file (i.e. very portable), which doesn't have to actually be
installed--just put it in the same directory as your perl script and go!  
And since libwhisker doesn't require external modules to work, that means
you should be good to go with a perl binary, the LW.pm file, and your perl
script--nothing else needed!  Great for those 'security audit' situations
where installing an entire perl distribution on a target system is out of
the question...

Of course, that doesn't mean that you shouldn't use LWP.  Just keep in
mind that LWP (and other modules, in general) were written to follow
proper RFC protocols.  This is fine and dandy, but if you're writing
exploits, sometimes you need to purposefully break some aspect of the
protocol, and typically the published Perl modules don't provide the
capabilities to do this.

And lastly, libwhisker has been benchmarked against LWP--and it's been
found to be almost three times as fast.

-------------------------------------------------------------------

How to use libwhisker:

Use the included api_demo.pl script to see how to make a basic request
using the library.  Otherwise, there is embedded POD documentation
for most of the functions within LW.pm.

You should be able to use the LW.pm by including it in the 
same directory as the script that requires it.  Otherwise run
"perl Makefile.pl install" to install it into your local perl 
module site directory.

To use SSL support, you will need Net::SSLeay or Crypt::SSLeay, as
well as OpenSSL installed.  libwhisker will still work without any 
of them, you just won't have any SSL support.  And technically 
libwhisker will still work without Socket support, but it's very 
limited then.

-------------------------------------------------------------------

Libwhisker is under the GPL.

That means it's free for use and redistribution under the terms of
the GNU Public License (version 2).  A copy is included with the
development source distribution, or from http://www.gnu.org/

If you wish to (re)use libwhisker code in a commercial product,
please contact me at rfp@wiretrip.net.

-------------------------------------------------------------------

Tested platforms:

libwhisker has been successfully ran on:
- RedHat linux, using perl 5.005 and higher
- ActiveState Perl for Windows, based on perl 5.6.x and 5.005

libwhisker does *not* run with perl 5.004 and earlier, due to the substr()
command taking 3 or less arguments (libwhisker uses the 4 argument version
in multiple places).  It's possible to use substr() as an lvalue, to
emulate the newer 4th argument, but perl prior to 5.005 is documented as
having memory leaks when doing that.  A possible future TODO is to find
a way around this and back-port libwhisker to earlier versions of perl.

-------------------------------------------------------------------

Feedback about libwhisker:

Send it to me directly at rfp@wiretrip.net, or toss it out on the
whisker-devel mailing list, whisker-devel@lists.sourceforge.net.
You can subscribe by going to the mailing list section at
http://sourceforge.net/projects/whisker/

-------------------------------------------------------------------

