-*- README -*- LibWeb-0.01 - A Perl library/toolkit for building Web applications. Copyright (c) 2000 Colin Kong. See LibWeb::Core, COPYING and LICENSE for usage and distribution rights. ____________________________________________________________________ | | | CONTENTS | |--------------------------------------------------------------------| | | | * Dependencies of libweb | | | | * Installation | | | | * A note on ``make test'' | | | | * After installation: running sample scripts | | | | * Security issues | | | | * Uninstallation | | | | * If you have problems | | | |____________________________________________________________________| DEPENDENCIES OF LIBWEB ---------------------- The following non-standard perl's libraries are required, * Digest * Crypt::CBC * Crypt::Blowfish (recommended) or Crypt::DES or Crypt::IDEA * DBI and the specific DBD for your database. You do not need the above mentioned libraries if you plan not to use the user/session management and database APIs of LibWeb, namely LibWeb::Admin, LibWeb::Crypt, LibWeb::Database and LibWeb::Session. INSTALLATION ------------ In short, on your command line, perl Makefile.PL make make test make install This will install the LibWeb package to standard locations on your machine. You can check the values of these standard variables on your system with perl '-V:install.*' And to check the sequence in which the library directories are searched by perl, run perl -le 'print join $/, @INC' If the above doesn't work for you, try: cp -R LibWeb /usr/local/lib/perl5 [ or cp it to other standard perl place on your machine ] For installing into non-standard location, use the PREFIX and LIB attribute. PREFIX and LIB can be used to set several INSTALL* attributes in one go. The quickest way to install LibWeb into a non-standard place might be (I recommend this) perl Makefile.PL LIB=~/path_to/my_lib This will install the module's architecture-independent files into ~/path_to/my_lib, the architecture-dependent files into ~/path_to/my_lib/$archname/auto. Another way to specify many INSTALL directories with a single parameter is PREFIX. perl Makefile.PL PREFIX=~ This will replace the string specified by $Config{prefix} in all $Config{install*} values. Read Perl's Config, ExtUtils::MakeMaker and ExtUtils::MM_Unix manpage for more information. A NOTE ON ``make test'' ----------------------- ``make test'' may generate some non-test or dependencies related error messages if perl cannot find/load any necessary perl library. By default, ``make test'' will look for modules in these locations, 1. '..','../blib/lib','../blib/arch' (with respect to ./t), and 2. LIB=~ (that is the make switch you specified if you intended to install LibWeb into non-standard location, e.g. `perl Makefile.PL LIB=~/path_to/my_lib'), and 3. the standard @INC. To check the standard @INC in which the library directories are searched by perl, run perl -le 'print join $/, @INC' ``make test'' simply prepends 1. and 2. to the standard @INC. If 1., 2. and 3. do not cover the paths into which you have installed perl's standard library and LibWeb's dependencies (e.g. Crypt::Blowfish and DBI ...etc. See the DEPENDENCES section of this README for more information), you have to change the ``use lib ...'' line on top of every ./t/*.t test script. E-mail me if you do not know how to do this. Hopefully, this will be resolved in next release of LibWeb. AFTER INSTALLATION: RUNNING SAMPLE SCRIPTS ------------------------------------------ Six samples can be found in ./eg, * MyHTML.pm * USER_LOG.sql * USER_PROFILE.sql * dot_lwrc * lm.cgi * testing.cgi To use LibWeb and run the sample scripts, 1. You must first edit dot_lwrc and place it *outside* (for security reasons) your web document root, 2. This step can be ignored if you intend not to use the users/sessions management and database APIs of LibWeb (namely LibWeb::Admin, LibWeb::Crypt, LibWeb::Database and LibWeb::Session). Create the USER_PROFILE and USER_LOG table. For example if your database is MySQL and `your_db_name' is your database's name, mysql -p your_db_name < USER_LOG.sql mysql -p your_db_name < USR_PROFILE.sql This will create both the USER_LOG AND USER_PROFILE tables. If you want to otherwise change the table names, edit these scripts before creating the tables and also you have to edit LibWeb's rc file accordingly since `USER_LOG' and `USER_PROFILE' are the defaults in the rc file. If you have enough privilege, you should create a separate database for LibWeb and then create the two tables. 3. After you have configured the rc file (e.g. dot_lwrc) and created database tables, you should edit `testing.cgi', upload it to your cgi-bin, chmod 755 it and run it by using a browser. What to edit in `testing.cgi'? First, edit the first line so that it points to the perl interpreter on your server; for example, replace #!/usr/bin/perl -w with #!/usr/local/bin/perl -w and finally edit several variables between the line ``# Begin edit.'' and the line ``# End edit.''. 4. `lm.cgi' is a sample login script. Edit and run it as you have done with `testing.cgi'. `lm.cgi' can be invoked via a browser in two main ways, one for logging in and another for logging out, http://www.your_site.org/cgi-bin/lm.cgi and http://www.your_site.org/cgi-bin/lm.cgi?.a=logout 5. MyHTML is a sample perl class. It demonstrates how to (ISA) make a sub-class of LibWeb::HTML::Default to customize the HTML display of Libweb applications. Read the man page for LibWeb::HTML::Default for details. Source codes for other full-blown LibWeb applications are available at http://leaps.sourceforge.net SECURITY ISSUES --------------- LibWeb's user and session management (authentication via cookie) is vulnerable to the recently found ``redirect'' attack. The only fix I can think of is to check the referer of HTTP header rigorously. However this is not implemented in LibWeb-0.01 because ``referer'' can easily be faked too. Hopefully this can be resolved in future releases. A discussion of the ``redirect'' attack is available at http://lwn.net/2000/features/Redirect.phtml You should frequently change the values for following attributes in the rc file, RAND_RANGE MAC_KEY CIPHER_KEY DIGEST_KEY If people know the values of all these keys, they can create a bogus authentication cookie themselves and fool the LibWeb's authentication scheme. So change these values frequently as you would with any password. I do not know how long those keys should be since it's not very clearly documented in the Crypt and Digest modules used by LibWeb. For my site, I make them reasonably long (no rigorous definition). I would really appreciate any comment and suggestion on that and other not yet addressed security issues. UNINSTALLATION -------------- In short, on your command line (after ``make install''), make uninstall if you have installed LibWeb into standard place (i.e. you have typed `perl Makefile.PL'), or make Uninstall if you have installed LibWeb into non-standard places (i.e. you have typed something like `perl Makefile.PL LIB=~/path_to/my_lib'). I believe in both cases an apology will be printed to you saying that you have to remove the installed files manually. Hopefully this will be resolved in next release of LibWeb. I am sorry. Any good perl modules packager? IF YOU HAVE PROBLEMS -------------------- First, read the FAQ and messages on message boards at http://libweb.sourceforge.net If you can't fix it your self please post details to libweb-devel@lists.sourceforge.net You can also cc them to me at colin.kong@toronto.edu Please include: 1. A complete log of a complete build, e.g.: perl Makefile.PL (do a make realclean first) make make test make test TEST_VERBOSE=1 (if any of the t/* tests fail) 2. The output of perl -V