This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Lib/Module, Next: Lib/ModuleSym, Prev: Lib/Browser, Up: Module List Lib::Module.pm ============== SYNOPSIS ======== use Lib::Module; use Lib::ModuleSym; use Lib::SymbolRef; DESCRIPTION =========== Provides a hierarchical object reference for a Perl library module, including the package name, file name, version, an array of stash references, and superclasses, if any. Module objects can be stored in a tree similar to the Perl class hierarchy. At this time, the hierarchy tree used is only two deep, because of the many different ways modules can communicate with each other. Every module is a subclass of UNIVERSAL, which is the default abstract superclass of all Perl packages. The Lib::ModuleSym.pm module provides lexical scanning and lookup, and provides cross referencing subroutines. The Lib::SymbolRef module provides tied objects that correspond to stash references, but this needs to be expanded. Running Under Perl/Tk --------------------- This module can call Tk::Event::DoOneEvent() function to provide window updates. The function usesTk() checks whether the this module is called from a program that uses Perl/Tk and returns true if running in a Tk::MainWindow, false if not. REVISION ======== $Id: Module.pm,v 0.65 2000/09/19 21:27:15 kiesling Exp $ SEE ALSO ======== The manual pages: Tk::Browser(3), perlmod(1), perlmodlib(1), perl(1).  File: pm.info, Node: Lib/ModuleSym, Next: Lib/SelfHelp, Prev: Lib/Module, Up: Module List Lexical scanning of Perl library modules. ***************************************** NAME ==== Lib::ModuleSym.pm - Lexical scanning of Perl library modules. DESCRIPTION =========== Refer to the Lib::Module(3) manual page. Running Under Perl/Tk --------------------- This module can call Tk::Event::DoOneEvent() function to provide window updates. The function usesTk() checks whether the this module is called from a program that uses Perl/Tk and returns true if running in a Tk::MainWindow, false if not. REVISION ======== $Id: ModuleSym.pm,v 0.52 2000/09/19 21:28:06 kiesling Exp $ SEE ALSO ======== Refer to the manual pages: Lib::Module(3), Tk::Browser(3), perlmod(1), perlmodlib(1), perl(1).  File: pm.info, Node: Lib/SelfHelp, Next: Lib/SymbolRef, Prev: Lib/ModuleSym, Up: Module List VERSION $Id: SelfHelp.pm,v 1.3 2000/08/19 01:04:22 kiesling Exp $ =cut ====================================================================== @ISA=qw{Exporter}; use vars qw( @ISA @EXPORT @EXPORT_OK ); @EXPORT=qw(self_help); use Tk; use Tk::MainWindow; use Tk::Button; my $defaulttextfont="*-courier-medium-r-*-*-12-*"; my $menufont="*-helvetica-medium-r-*-*-12-*"; sub self_help { my ($appfilename) = @_; my $help_text; my $helpwindow; my $textwidget; open( HELP, ("pod2text < $appfilename |") ) or $help_text = "Unable to process help text for $appfilename."; while () { $help_text .= $_; } close( HELP ); $helpwindow = new MainWindow( -title => "$appfilename Help" ); my $textframe = $helpwindow -> Frame( -container => 0, -borderwidth => 1 ) -> pack; my $buttonframe = $helpwindow -> Frame( -container => 0, -borderwidth => 1 ) -> pack; $textwidget = $textframe -> Scrolled( 'Text', -font => $defaulttextfont, -scrollbars => 'e' ) -> pack( -fill => 'both', -expand => 1 ); $textwidget -> insert( 'end', $help_text ); $buttonframe -> Button( -text => 'Close', -font => $menufont, -command => sub{$helpwindow -> DESTROY} ) -> pack; } 1;  File: pm.info, Node: Lib/SymbolRef, Next: LibWeb/Admin, Prev: Lib/SelfHelp, Up: Module List Manage tied references to symbol table hash entries. ****************************************************** NAME ==== Tk::Symbolref.pm -- Manage tied references to symbol table hash entries. SYNOPSIS ======== use Lib::Module; use Lib::ModuleSym; use Lib::SymbolRef; tie *Package::symbol, 'Lib::SymbolRef, DESCRIPTION =========== Much room for further expansion using these methods. REVISION ======== $Id: SymbolRef.pm,v 0.51 2000/09/18 20:23:59 kiesling Exp kiesling $ SEE ALSO ======== The manual pages for Lib::Module(3), Tk::Browser(3), perltie(1).  File: pm.info, Node: LibWeb/Admin, Next: LibWeb/CGI, Prev: Lib/SymbolRef, Up: Module List User authentication for libweb applications ******************************************* NAME ==== LibWeb::Admin - User authentication for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * LibWeb::Database ISA === * LibWeb::Session SYNOPSIS ======== use LibWeb::Admin; my $a = LibWeb::Admin->new(); $a->login( $user_name, $guess_password ); ... my ($user_name,$uid) = $a->get_user(); ... $a->logout(); ... $a->is_logout(); ABSTRACT ======== This class manages user authentication for web applications written based on the interfaces and frameworks defined in LibWeb, a Perl library/toolkit for programming web applications. It is responsible for managing user login, logout and new sign-up. Therefore you may want to use this module in the login script for your site. The current version of LibWeb::Admin.pm is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. MAX_LOGIN_ATTEMPT_ALLOWED) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. `Sanitize' means escaping any illegal character possibly entered by user in a HTML form. This will make Perl's taint mode happy and more importantly make your site more secure. Definition for illegal characters is given in *Note LibWeb/Core: LibWeb/Core,. All `error/help messages' mentioned can be found at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for details. DESCRIPTION =========== HANDLING USER LOGIN ------------------- Fetch the user name and password from a HTML form and pass them to login(), $a->login( $user_name, $guess ); If the password is correct and the user name exists in the database, this will send an authentication cookie to the client web browser and return 1; send an alert e-mail to the site administrator (*ADMIN_EMAIL*) and print out an error message and exit otherwise. HANDLING USER SESSION AFTER LOGIN --------------------------------- At the top of every web application that requires user authentication, my ($user_name,$uid) = $a->get_user(); to retrieve user name and user ID from cookie. This will send an alert e-mail to the site administrator (*ADMIN_EMAIL*) and redirect the user to the login page (*LM_IN*) if no authentication cookie is found or it has been tampered with. I would recommend you use LibWeb::Session instead which is specifically designed for that purpose and therefore runs a little bit faster, use LibWeb::Session; my $s = new LibWeb::Session(); my ($user_name,$uid) = $s->get_user(); LibWeb::Admin should be used by login scripts; whereas LibWeb::Session should be used by any web applications once the user has logged in. Read *Note LibWeb/Session: LibWeb/Session, for details. To update the database (set the login indicator to *LOGIN_INDICATOR*) when the user is first logged in, my ($user_name,$uid) = $s->get_user( -is_update_db => 1 ); This is probably done in `my control panel' or `my page' of some sorts which is the first script invoked after password authentication. HANDLING USER LOGOUT -------------------- $a->logout(); This will check to see if the user is logged in. Send an alert e-mail to the site administrator (*ADMIN_EMAIL*) and redirect user to the login page (*LM_IN*) if the remote user is not logged in or has no authentication cookie. Otherwise, this will flush *NUM_LOGIN_ATTEMPT* to 0 in database (indicating that the user has logged out). This will also send de-authentication cookies to nullify all authentication cookies on client web browser. Return 1 upon success. PARANOIA -------- $a->is_logout(); Check to see if authentication cookies are indeed removed from the client Web browser and return true (1). Otherwise, print an error message, send an alert e-mail to *ADMIN_EMAIL* and exit the program. ADDING NEW USER TO DATABASE --------------------------- $a->add_new_user( -user => 'user_name', -password => 'password', -email => 'user_email' ); Print out an error message and abort if, * `user_name' contains illegal characters other than `_' and `-' or * `user_name' is already registered or * `user_email' does not conform to the standard format defined in *Note LibWeb/Core: LibWeb/Core, or * `user_email' is already registered if *IS_ALLOW_MULTI_REGISTRATION* is set to 0. If the parameters pass all the tests, this will encrypt the password, add that with the user name to the database, notify the site administrator (*ADMIN_EMAIL*) by e-mail if *IS_NOTIFY_ADMIN_WHEN_ADDED_NEW_USER* is set to 1 and log that event in *FATAL_LOG* if *FATAL_LOG* is defined. Return the registered user_name upon success. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/CGI: LibWeb/CGI,, *Note LibWeb/Crypt: LibWeb/Crypt,, *Note LibWeb/Database: LibWeb/Database,, *Note LibWeb/Digest: LibWeb/Digest,, *Note LibWeb/HTML/Default: LibWeb/HTML/Default,, *Note LibWeb/Session: LibWeb/Session,, *Note LibWeb/Themes/Default: LibWeb/Themes/Default,.  File: pm.info, Node: LibWeb/CGI, Next: LibWeb/Class, Prev: LibWeb/Admin, Up: Module List Extra cgi supports for libweb applications ****************************************** NAME ==== LibWeb::CGI - Extra cgi supports for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * LibWeb::Core ISA === * CGI * LibWeb::Class SYNOPSIS ======== use LibWeb::CGI; my $q = new LibWeb::CGI(); my $parameter = $q->parameter('cgi_param_to_fetch'); my $param = $q->param('cgi_param_to_fetch'); print $q->header(); $q->redirect( -url => '/cgi-bin/logout.cgi', -cookie => 'auth=0' ); $q->send_cookie( [$cookie1, $cookie2] ); $q->sanitize( -text => $user_input, -allow => ['_', '-'] ); $q->fatal( -msg => 'Password not entered.', -alertMsg => '$user did not enter password!', -helpMsg => \('Please hit back and edit.') ); ABSTRACT ======== This class ISA the vanilla CGI.pm to provide some additional features. It is still considered to be experimental but used internally by LibWeb::Session and LibWeb::Admin. The current version of LibWeb::CGI is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. MAX_LOGIN_ATTEMPT_ALLOWED) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. `Sanitize' means escaping any illegal character possibly entered by user in a HTML form. This will make Perl's taint mode happy and more importantly make your site more secure. Definition for illegal characters is given in *Note LibWeb/Core: LibWeb/Core,. All `error/help messages' mentioned can be found at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for details. Method's parameters in square brackets means optional. DESCRIPTION =========== METHODS ------- new() args: [ -post_max=>, -disable_uploads=>, -auto_escape=> ] * `-post_max' is the ceiling on the size of POSTings, in bytes. The default for LibWeb::CGI is 100 Kilobytes. * `-disable_uploads', if non-zero, will disable file uploads completely which is the default for LibWeb::CGI. * `-auto_escape' determines whether the text and labels that you provide for form elements are escaped according to HTML rules. Non-zero value will enable auto escape, and undef will disable auto escape (default for LibWeb::CGI). header() If you provide parameter to that method, it will delegate to the vanilla CGI's header(); otherwise, it will print out "Content-Type: text/html$CRLF$CRLF" immediately (faster?). $CRLF will depend on the machine you are running LibWeb and LibWeb will determine it automatically. *parameter()* my $param = $q->parameter('cgi_parameter_to_fetch'); * `cgi_parameter_to_fetch' is the parameter passed by either `GET' or `POST' via a HTML form. * If `cgi_parameter_to_fetch' is a mandatory form value (one without `.' as prefix in the parameter's name) and it is null, it will print out an error message, abort the program and send the site administrator an alert e-mail. It is intended so save the effort to check whether the user has entered something for mandatory HTML form values. To use this nice feature, you name mandatory form value without `.' as prefix, for example, For non-mandatory form values, you name them by attaching `.' as a prefix to skip the test, for example, If you find this not really helpful, you should use the vanilla param() which is totally unaltered in LibWeb::CGI. For example, my $param = $q->param('param_to_fetch'); and LibWeb::CGI will delegate the call to the vanilla CGI's param(). Another reason to use parameter() (or not to use it) is that it automatically checks for any possible denial of service attack by calling CGI::cgi_error(). If the POST is too large, it will print out an error message and send an e-mail alerting the site administrator. CGI::cgi_error() is available since CGI 2.47 but seems to be disappeared in new release of CGI.pm 3.01 alpha (24/04/2000). *redirect()* Params: -url=> [, -cookie=> ] This will redirect the client web browser to the specified url and send it the cookie specified. An example of a cookie to pass to that method will be, $cookie1 = 'auth1=0; path=/; expires=Thu, 01-Jan-1970 00:00:01 GMT'; $cookie2 = 'auth2=0; path=/; expires=Thu, 01-Jan-1970 00:00:01 GMT'; $q->redirect( -url => '/logged_out.htm', -cookie => [ $cookie1, $cookie2 ] ); For `-cookie', you can pass either a scalar or an ARRAY reference. This method will eventually delegate to the vanilla CGI's redirect(). Why bother doing this is because the vanilla CGI's redirect() does not guarantee to work if you pass relative url; whereas LibWeb::CGI::redirect() guarantees that partial url will still work. *send_cookie()* This delegates to LibWeb::Core::send_cookie(). See *Note LibWeb/Core: LibWeb/Core,. *fatal()* This delegates to LibWeb::Core::fatal(). See *Note LibWeb/Core: LibWeb/Core,. *sanitize()* This delegates to LibWeb::Core::sanitize(). See *Note LibWeb/Core: LibWeb/Core,. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= Lincoln Stein (lstein@cshl.org) BUGS ==== Bug number 1 ------------ When you delegate subroutine calls within a cgi script, $q->param(_variable_) or $q->parameter(_variable_) may not give you the value of `_variable_' even you have passed a value for that variable in a HTML form. I do not know why. My two workarounds, * Instantiate another CGI or LibWeb::CGI object within the subroutine where you want to fetch the parameter and use that object to call param() or `parameter()', or * Initiate all CGI variables and/or fetch all CGI parameters at the beginning of your script. Bug number 2 ------------ new() args: [ -post_max=>, -disable_uploads=>, -auto_escape=> ] The `-auto_escape' doesn't seems to work as expected. Hopefully it will be resolved after I get a better understanding of how auto escape works in the vanilla CGI. Bug number 3 ------------ There is no selfloaded method in LibWeb::CGI since whenever I try to put "use SelfLoader;" in this module, it just doesn't work well with the vanilla CGI. This has to be figured out. Miscellaneous OO issues with the vanilla CGI have yet to be resolved. SEE ALSO ======== *Note CGI: CGI,, *Note LibWeb/Class: LibWeb/Class,, *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/HTML/Default: LibWeb/HTML/Default,, *Note LibWeb/HTML/Error: LibWeb/HTML/Error,.  File: pm.info, Node: LibWeb/Class, Next: LibWeb/Core, Prev: LibWeb/CGI, Up: Module List A base class for libweb modules ******************************* NAME ==== LibWeb::Class - A base class for libweb modules SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * perl 5.004 ISA === * None SYNOPSIS ======== require LibWeb::Class; @ISA = qw(LibWeb::Class); ABSTRACT ======== This class contains common object-oriented methods inherited by all LibWeb modules. It is intended to be ISA by LibWeb modules and extensions and not used by client codes outside LibWeb. The current version of LibWeb::Class is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== METHODS ------- rearrange() This is not really OO related but makes LibWeb's API look sexy. This is stolen from CGI.pm and modified. It allows smart rearrangement of parameters for named parameter calling. This does the rearrangement if the first parameter begins with a `-'. For example, sub your_class_method { my $self = shift; my ($parameter1, $parameter2, $parameter3); = $self->rearrange( ['PARA1', 'PARA2', 'PARA3'], @_ ); .... } and your method will be called as use your_class; my $object = new your_class(); $object->your_class_method( -para1 => $para1, -para2 => $para2, -para3 => $para3 ); AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= Lincoln Stein (lstein@cshl.org) BUGS ==== SEE ALSO ========  File: pm.info, Node: LibWeb/Core, Next: LibWeb/Crypt, Prev: LibWeb/Class, Up: Module List The core class for libweb modules ********************************* NAME ==== LibWeb::Core - The core class for libweb modules SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * LibWeb::Crypt * LibWeb::HTML::Error * Mail::Sendmail ISA === * LibWeb::Class SYNOPSIS ======== require LibWeb::Core; @ISA = qw(LibWeb::Core); ABSTRACT ======== This class is responsible for reading the LibWeb's rc file, handling portability issues, printing and logging error and debug messages and sending alert e-mail to the site administrator should error occur. You are not supposed to use or ISA this class directly. It is ISAed internally by other modules in LibWeb, e.g. LibWeb::Admin, LibWeb::CGI, LibWeb::Database, LibWeb::HTML::Default and LibWeb::Themes::Default. You should call the methods presented in this man page through one of those sub-classes. The current version of LibWeb::Core is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. ADMIN_EMAIL) are those variables set through LibWeb's rc file. `Sanitize' means escaping any illegal character possibly entered by user in a HTML form. This will make Perl's taint mode happy and more importantly make your site more secure. All `error/help messages' mentioned can be found at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for details. Method's parameters in square brackets means optional. DESCRIPTION =========== READING THE LIBWEB RC FILE -------------------------- You should place your LibWeb rc (config) file outside your WWW document root. The following shows how a cgi script using LibWeb will typically look like, use LibWeb::Session; use LibWeb::Database; use LibWeb::CGI; use LibWeb::Themes::Default; use LibWeb::HTML::Default; my $rc_file = '/home/me/dot_lwrc'; my $html = new LibWeb::HTML::Default($rc_file); my $themes = new LibWeb::Themes::Default(); my $session = new LibWeb::Session(); my $db = new LibWeb::Database(); my $q = new LibWeb::CGI(); ... It is recommended that you pass the absolute path of LibWeb's rc file to LibWeb::HTML::Default and make it the *first* LibWeb object initialized. This will ensure other LibWeb objects can "see" the rc file and be initialized properly. However, LibWeb::Admin, LibWeb::CGI, LibWeb::Database, LibWeb::Themes::Default, and LibWeb::Session all can take $rc_file as the argument to their new() methods (constructor). You will never need this unless you do not want LibWeb::HTML::Default to manage HTML page display for you. You still do *not* need this even if you have ISAed LibWeb::HTML::Default. The reason to ISA LibWeb::HTML::Default is to customize the normal and error HTML page display and error messages built into LibWeb. If you have ISAed LibWeb::HTML::Default, you just have to replace the following two lines, use LibWeb::HTML::Default; my $html = new LibWeb::HTML::Default($rc_file); with use MyHTML; my $html = new MyHTML($rc_file); where MyHTML is your class which ISAs LibWeb::HTML::Default. Please read *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for details. A sample rc file has been included in the ./eg directory. If you could not find it, please go to http:://libweb.sourceforge.net and download a standard LibWeb distribution. SANITY - REMOVING ILLEGAL CHARACTERS ENTERED BY USERS ----------------------------------------------------- LibWeb::Core provides *sanitize()* method to escape illegal characters entered by users in HTML forms. LibWeb's definition of illegal characters is as follows, `~!@#$%^&*,.:;?"'<>{}[]()\|/-_+=\a\n\r\t\f\e\b *sanitize()* also has the ability to escape HTML tags and detect dirty e-mail addresses (format). Please see below for details on *sanitize()*. METHODS ------- new() Params: class [, *rc_file*, *error_object*] Usage: No, you do not call LibWeb::Core::new() directly in client codes. * class is the class/package name of this package, be it a string or a reference. * *rc_file* is the absolute path to the rc file for LibWeb. * *error_object* is a reference to a perl object for printing out error/help message to users should error occur. *debug_print()* Usage: debug_print('you debug message'); * If `DEBUG' == 1, print *debug_msg* and return undef. Do nothing otherwise. *fatal()* Params: -msg [, -input=>, -helpMsg=>, -alertMsg=>, -isAlert=>, -isDisplay=>, -cookie=> ] Usage: fatal( -msg => 'You have not entered your password.', -alertMsg => "$user did not enter password!", -helpMsg => \('Please hit back and edit.') ); fatal( -alertMsg => 'Possible denial of service attack detected!', -isDisplay => 0 ); Pre: * `-msg', `-input', `-alertMsg' must be scalar and `-helpMsg' must be a SCALAR reference. `-cookie' can be a scalar or an ARRAY reference to scalars, * `-input' is the user input that triggers this fatal error, * `-helpMsg' is any instruction to guide the remote user, which can be HTML, Post: * Send `-cookie', print `-msg', `-input' and `-helpMsg' to the viewing web browser and abort the current running program if `-isDisplay' is defined and is equal to 1 (default), * if `-isAlert' is defined and is equal to 1 (default), * append `-alertMsg' to `FATAL_LOG' if `FATAL_LOG' is defined, * send an alert e-mail, with `-alertMsg' as the message body, to `ADMIN_EMAIL' if `IS_MAIL_DEBUG_TO_ADMIN' is 1, and * print `-alertMsg' to the viewing web browser if `DEBUG' is 1. *sanitize()*: sanitizes Web client inputs Params: -text=>'plain_text' || -html=>'html_text' || -email=>'email_here' [, -allow=>[characters allowed] ] Usage: $sanitized_input = sanitize( -text => $user_input, -allow => ['-', '_'] ); @sanitized_emails = sanitize( -email => [$email1,$email2, $email3] ); $sanitized_input = sanitize( -html => $user_input ); Pre: * For `-text', `-html' and `-email', each must be a scalar or an ARRAY reference to scalars, * `-allow' is an ARRAY reference to special characters allowed. It's effective only when you use it with `-text'. Post: * `-text': sanitize text by escaping all illegal characters (`~!@#$%^&*,.:;?"'<>{}[]()\|/-_+=\a\n\r\t\f\e\b), * `-html': escape all html <> tags, * `-email': sanitize email addresses. Print an error message and abort the current running program if email is dirty ( $email !~ m:(\w{1}[\w-.]*)\@([\w-.]+): ) * array is returned if want array, * this can only process one type of sanity at a time (i.e. per method call). *send_cookie()* - this one is here due to inheritance (backward?) issues not yet resolved with LibWeb::CGI. Usage: my $cookie1 = 'auth1=0; path=/; expires=Thu, 01-Jan-1970 00:00:01 GMT'; my $cookie2 = 'cook2=value; path=/'; send_cookie( $cookie1 ); # or send_cookie( [$cookie1, $cookie2] ); Pre: * Parameter must be either a scalar or an ARRAY reference to scalars, * no other HTTP headers should be sent before this in a single CGI session. Post: * Send the cookie to client Web browser. *send_mail()* Params: -to=>, -from=>, -subject=>, -msg=> [, -replyTo=>, -cc=>, -bcc=>, -smtp=> ] Pre: * `-msg' must be a SCALAR reference and others must be scalars. Post: * Send an e-mail to the recipients specified. It will try to use Mail::Sendmail and then the primitive unix sendmail if the former fails. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Admin: LibWeb/Admin,, *Note LibWeb/Class: LibWeb/Class,, *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/CGI: LibWeb/CGI,, *Note LibWeb/Crypt: LibWeb/Crypt, *Note LibWeb/Database: LibWeb/Database,, *Note LibWeb/File: LibWeb/File,, *Note LibWeb/HTML/Error: LibWeb/HTML/Error,, *Note LibWeb/HTML/Site: LibWeb/HTML/Site,, *Note LibWeb/HTML/Default: LibWeb/HTML/Default,, *Note LibWeb/Session: LibWeb/Session,, *Note LibWeb/Themes/Default: LibWeb/Themes/Default,, *Note LibWeb/Time: LibWeb/Time,.  File: pm.info, Node: LibWeb/Crypt, Next: LibWeb/Database, Prev: LibWeb/Core, Up: Module List Encryption for libweb applications ********************************** NAME ==== LibWeb::Crypt - Encryption for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * Crypt::CBC * Crypt::Blowfish (recommended), Crypt::DES or Crypt::IDEA ISA === * LibWeb::Class SYNOPSIS ======== use LibWeb::Crypt; my $c = new LibWeb::Crypt(); my $cipher = $c->encrypt_cipher( -data => $plain_text, -key => $key, -algorithm => 'Crypt::Blowfish', -format => 'hex' ); my $plain_text = $c->decrypt_cipher( -cipher => $cipher, -key => $key, -algorithm => 'Crypt::Blowfish', -format => 'hex' ); my $encrypted_pass = $c->encrypt_password('password_in_plain_text'); ABSTRACT ======== This class provides methods to * encrypt data of arbitrary length into cipher (binary or hex) by using the algorithm provided by Crypt::Blowfish, Crypt::DES or Crypt::IDEA, and chained by using Crypt::CBC, * decrypt ciphers generated by this class, * encrypt plain text password by using the perl's crypt() routine with randomly chosen salt. The current version of LibWeb::Crypt is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== METHODS ------- *encrypt_cipher()* Params: -data=>, -key=>, -algorithm=>, -format=> Pre: * `-data' is the data to be encrypted as cipher, * `-key' is the private key such the same key is needed to decrypt the cipher (sorry, I do not have a rigorous definition for that right now), * `-algorithm' must be 'Crypt::Blowfish', 'Crypt::DES' or 'Crypt::IDEA', * `-format' is the format of the cipher, which must be either 'binary' or 'hex'. Post: * Encrypt `-data' and return the cipher. Note: this makes use of the Crypt::CBC module and therefore can accept data of arbitrary length. *decrypt_cipher()* Params: -cipher=>, -key=>, -algorithm=>, -format=> Pre: * `-cipher' is the cipher to be decrypted, * `-key' is the private key such that it is the same key used to encrypt the original data of `-cipher' (sorry, I do not have a rigorous definition for that right now), * `-algorithm' must be 'Crypt::Blowfish', 'Crypt::DES' or 'Crypt::IDEA' and it must match the algorithm used when preparing the cipher, * `-format' is the format of the cipher, which must be either 'binary' or 'hex'. Post: * Decrypt `-cipher' and return the original data. *encrypt_password()* Usage: my $encrypted_password = $crypt->encrypt_password($password_in_plain_text); Encrypts the parameter (usually a password) and returns a 13-character long string using the perl's crypt() routine and randomly chosen salt. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= Lincoln Stein (lstein@cshl.org) BUGS ==== SEE ALSO ======== *Note Digest/HMAC: Digest/HMAC,, *Note Digest/SHA1: Digest/SHA1,, *Note Digest/MD5: Digest/MD5,, *Note Crypt/CBC: Crypt/CBC,, *Note Crypt/Blowfish: Crypt/Blowfish,, *Note Crypt/DES: Crypt/DES,, *Note Crypt/IDEA: Crypt/IDEA,, *Note LibWeb/Admin: LibWeb/Admin,, *Note LibWeb/Digest: LibWeb/Digest,, *Note LibWeb/Session: LibWeb/Session,.  File: pm.info, Node: LibWeb/Database, Next: LibWeb/Database/Mysql, Prev: LibWeb/Crypt, Up: Module List A generic database driver for libweb applications ************************************************* NAME ==== LibWeb::Database - A generic database driver for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * DBI ISA === * LibWeb::Core SYNOPSIS ======== use LibWeb::Database; my $db = new LibWeb::Database(); my ($sql, $user, $host, $fetch, $result); $sql = "select USER_NAME, USER_HOST ". "from USER_TABLE ". "where USER_LOGIN_STATUS = ". "LOGIN_INDICATOR"; $fetch = $db->query( -sql => $sql, -bind_cols => [\$user, \$host] ); while ( &$fetch ) { $result .= "$user $host
\n"; } $db->done(); print "Content-Type: text/html\n\n"; print "

The following users have logged in: $result"; ABSTRACT ======== As long as you have the proper DBD installed for your database, you can use this class to interact with your database in your LibWeb applications. The current version of LibWeb::Database is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. USER_TABLE) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. Method's parameters in square brackets means optional. DESCRIPTION =========== *do()* Params: -sql => Pre: * `-sql' is a valid sql statement. Post: * Return the number of rows affected by the SQL statement, `-sql'. query() Params: -sql=>, -bind_cols=> [, -want_hash=> ] Pre: * `-sql' is the sql statement to perform the query, * `-bind_cols' is an ARRAY reference to SCALAR references to fields to be bound in the table specified in `-sql', * `-want_hash' indicates whether the returning function (a reference) is a reference to DBI's fetchrow_hashref() or fetchrow_arrayref(). Post: * Returns a reference to a fetching function based on `-sql'. A reference to DBI's fetchrow_arrayref() is returned if `-want_hash' is not defined; otherwise a reference to DBI's fetchrow_hashref() is returned. finish() Finish a statement execution. disconnect() Disconnect the current database session. *done()* Finish a statement execution and disconnect the current database session. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== `DBI' in this node, *Note LibWeb/Core: LibWeb/Core,.  File: pm.info, Node: LibWeb/Database/Mysql, Next: LibWeb/Digest, Prev: LibWeb/Database, Up: Module List Mysql database API for libweb applications ****************************************** NAME ==== LibWeb::Database::Mysql - Mysql database API for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::Database SYNOPSIS ======== use LibWeb::Database::Mysql; my $db = new LibWeb::Database::Mysql(); my ($where, $count); $where = 'LOGIN_STATUS = LOGGED_IN'; $count = $db->get_count( -table => USER_TABLE, -where => $where ); print "Content-Type: text/html\n\n"; print "$count users have logged in."; ABSTRACT ======== This class provides enhanced support to MySQL database interaction in you LibWeb applications. This class also ISAs LibWeb::Database so you can use all the methods provided in LibWeb::Database via objects created from this class. See *Note LibWeb/Database: LibWeb/Database,. This module is still in the stage of planning as you can tell from the number of methods available. The current version of LibWeb::Database::Mysql is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. USER_TABLE) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. Method's parameters in square brackets means optional. DESCRIPTION =========== METHODS ------- *get_count()* Params: -table =>, -where => Pre: * `-table' is a scalar indicating a database table's name, * `-where' is a scalar describing the `where' phrase of a SQL query. Post: * Return the number of counts satisfying the criteria specified in the `-where' parameter. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Database: LibWeb/Database,.  File: pm.info, Node: LibWeb/Digest, Next: LibWeb/File, Prev: LibWeb/Database/Mysql, Up: Module List Digest generation for libweb applications ***************************************** NAME ==== LibWeb::Digest - Digest generation for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * Digest::HMAC * Digest::SHA1 * Digest::MD5 ISA === * LibWeb::Class SYNOPSIS ======== use LibWeb::Digest; my $d = new LibWeb::Digest(); my $mac = $d->generate_MAC( -data => $data, -key => $key, -algorithm => 'Digest::SHA1', -format => 'b64' ); my $digest = $d->generate_digest( -data => $data, -key => $key, -algorithm => 'Digest::MD5', -format => 'b64' ); ABSTRACT ======== This class provides methods to * Generate message authenticity check (MAC) code which is mostly used in authentication cookies sent to browsers, and * generate digest code (binary, hex or B64) by using the algorithm provided by either Digest::MD5 or Digest::SHA1, The current version of LibWeb::Digest is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== GENERATING A MAC FOR USER/SESSION AUTHENTICATION ------------------------------------------------ The following discussion on MAC is extracted from a WWW security FAQ written by Lincoln Stein, http://www.w3.org/Security/Faq/wwwsf7.html#Q66 "If possible, cookies should contain information that allows the system to verify that the person using them is authorized to do so. A popular scheme is to include the following information in cookies: 1.the session ID or authorization information 2.the time and date the cookie was issued 3.an expiration time 4.the IP address of the browser the cookie was issued to 5.a message authenticity check (MAC) code By incorporating an expiration date and time into the cookie, system designers can limit the potential damage that a hijacked cookie can do. If the cookie is intercepted, it can only be used for a finite time before it becomes invalid. The idea of including the browser's IP address into the cookie is that the cookie will only be accepted if the stored IP address matches the IP address of the browser submitting it. This makes it difficult for an interloper to hijack the cookie, because it is hard (although not impossible) to spoof an IP address. The MAC code is there to ensure that none of the fields of the cookie have been tampered with. There are many ways to compute a MAC, most of which rely on one-way hash algorithms such as MD5 or SHA to create a unique fingerprint for the data within the cookie. Here's a simple but relatively secure technique that uses MD5: MAC = MD5("secret key " + MD5("session ID" + "issue date" + "expiration time" + "IP address" + "secret key") ) This algorithm first performs a string concatenation of all the data fields in the cookie, then adds to it a secret string known only to the Web server. The whole is then passed to the MD5 function to create a unique hash. This value is again concatenated with the secret key, and the whole thing is rehashed. (The second round of MD5 hashing is necessary in order to avoid an attack in which additional data is appended to the end of the cookie and a new hash recalculated by the attacker.) This hash value is now incorporated into the cookie data. Later, when the cookie is returned to the server, the software should verify that the cookie hasn't expired and is being returned by the proper IP address. Then it should regenerate the MAC from the data fields, and compare that to the MAC in the cookie. If they match, there's little chance that the cookie has been tampered with." - Lincoln Stein. In fact, this is the technique used by LibWeb to handle user/session authentication via cookies. LibWeb::Admin and LibWeb::Session use LibWeb::Digest::generate_MAC() to generate MACs. LibWeb::Digest::generate_MAC() uses Digest::HMAC and uses either Digest::MD5 or Digest::SHA1 as the digest algorithm. METHODS ------- *generate_MAC()* Params: -data=>, -key=>, -algorithm=>, -format=> Pre: * `-data' is the data from which the MAC is to be generated, * `-key' is the private key such that the MAC generated is unique to that key (sorry, I do not have a rigorous definition for that right now), * `-algorithm' must be either 'Digest::MD5' or 'Digest::SHA1', * `-format' is the format of the generated MAC, which must be 'binary', 'hex' or 'b64'. Post: * Generate a MAC and return it. *generate_digest()* Params: -data=>, -key=>, -algorithm=>, -format=> Pre: * `-data' is the data from which the digest is to be generated, * `-key' is the private key such that the digest generated is unique to that key (sorry, I do not have a rigorous definition for that right now), * `-algorithm' must be either 'Digest::MD5' or 'Digest::SHA1', * `-format' is the format of the digest, which must be 'binary', 'hex' or 'b64'. Post: * Generate a digest and return it. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= Lincoln Stein (lstein@cshl.org) BUGS ==== SEE ALSO ======== *Note Digest/HMAC: Digest/HMAC,, *Note Digest/SHA1: Digest/SHA1,, *Note Digest/MD5: Digest/MD5,, *Note Crypt/CBC: Crypt/CBC,, *Note Crypt/Blowfish: Crypt/Blowfish,, *Note Crypt/DES: Crypt/DES,, *Note Crypt/IDEA: Crypt/IDEA,, *Note LibWeb/Admin: LibWeb/Admin,, *Note LibWeb/Crypt: LibWeb/Crypt,, *Note LibWeb/Session: LibWeb/Session,.  File: pm.info, Node: LibWeb/File, Next: LibWeb/HTML/Default, Prev: LibWeb/Digest, Up: Module List File manipulations for libweb applications ****************************************** NAME ==== LibWeb::File - File manipulations for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::Class SYNOPSIS ======== use LibWeb::File; my $fh = new LibWeb::File(); $lines = $fh->read_lines_from_file( -file => '/home/me/file1' ); $fh->write_lines_to_file( -file => '/home/me/file2', -lines => $lines ); ABSTRACT ======== This class provides several methods to manipulate text files. The current version of LibWe LibWeb::File is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== METHODS ------- *read_lines_from_file()* Params: -file => Open, read all lines, close `-file' and return the lines in an ARRAY reference. *write_lines_to_file()* Params: -file =>, -lines => Pre: * `-lines' is an ARRAY reference to lines which are scalars. Post: * Overwrite `-file' with the lines. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Class: LibWeb/Class,.  File: pm.info, Node: LibWeb/HTML/Default, Next: LibWeb/HTML/Error, Prev: LibWeb/File, Up: Module List HTML display for libweb applications ************************************ NAME ==== LibWeb:: - HTML display for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::HTML::Standard * LibWeb::HTML::Error * LibWeb::Themes::Default SYNOPSIS ======== use LibWeb::HTML::Default; my $rc_file = '/absolute/path/to/dot_lwrc'; my $html = new LibWeb::HTML::Default($rc_file); $html->fatal( -msg => 'You have not typed in the stock symbol.', -alertMsg => 'Try to view stock quotes without a symbol.', -helpMsg => $html->hit_back_and_edit() ) unless ($stock_symbol); my $display = $html->display( -content => [ $news, $stock_quotes, $weather ], -sheader=> [ $tabbed_navigation_bar ], -lpanel=> [ $banner_ad ], -rpanel=> [ $back_issues, $downloads ], -header=> undef, -footer=> undef ); print "Content-Type: text/html\n\n"; print $$display; I pass the absolute path to my LibWeb's rc (config) file to `LibWeb::HTML::Default::new()' so that LibWeb can do things according to my site's preferences. A sample rc file is included in the eg directory, if you could not find that, go to the following address to down load a standard distribution of LibWeb, http://libweb.sourceforge.net This synopsis also demonstrated how I have handled error by calling the `fatal()' method. For the display() call, I passed undef to `-header' and `-footer' to demonstrate how to tell the display to use default header and footer. Finally, I de-referenced `$display' (by appending `$' in front of the variable) to print out the HTML page. Please see the synopsis of *Note LibWeb/Themes/Default: LibWeb/Themes/Default, to see how I have prepared `$news, $weather, $stock_quotes, $back_issues and $tabbed_navigation_bar'. If I would like to customize the HTML display of LibWeb, I would have ISAed LibWeb::HTML::Default, say a class called `MyHTML' and I just have to replace the following two lines, use LibWeb::HTML::Default; my $html = new LibWeb::HTML::Default( $rc_file ); with use MyHTML; my $html = new MyHTML( $rc_file ); A sample MyHTML.pm is included in the distribution for your hacking pleasure. ABSTRACT ======== This class is a sub-class of LibWeb::HTML::Standard, LibWeb::HTML::Error and LibWeb::Themes::Default and therefore it handles both standard and error display (HTML) for a LibWeb application. To customize the behavior of display(), `display_error()' and built-in error/help messages, you can make a sub-class of LibWeb::HTML::Default (an example can be found in the eg directory. If you could not find it, download a standard distribution from the following address). In the sub-class you made, you can also add your own error messages. You may want to take a look at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, to see what error messages are built into LibWeb. To override the standard error messages, you re-define them in the sub-class you made. The current version of LibWeb::HTML::Default is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= All `error/help messages' mentioned can be found at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Error/help messages are used when you call LibWeb::Core::fatal, see *Note LibWeb/Core: LibWeb/Core, for details. Method's parameters in square brackets means optional. DESCRIPTION =========== new() Params: class, *rc_file* Usage: my $html = new LibWeb::HTML::Default( $rc_file ); Pre: * class is the class/package name of this package, be it a string or a reference. * *rc_file* is the absolute path to the rc file for LibWeb. display() This implements the base class method: LibWeb::HTML::Standard::display(). Params: -content=>, [ -sheader=>, -lpanel=>, -rpanel=>, -header=>, -footer=> ] Pre: * `-content', `-sheader', `-lpanel', `-rpanel', `-header' and `-footer' each must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references, * if the elements are ARRAY references, then the elements in those ARRAY references must be scalars and NOT references, * `-content' default is `content()', * `-sheader' stands for "sub header" and default is `sheader()', * `-lpanel' default is `lpanel()', * `-rpanel' default is `rpanel()', * `-header' default is header(), * `-footer' default is `footer()'. Post: * Return a SCALAR reference to a formatted HTML page suitable for display to a Web browser. Each of the following methods return an ARRAY reference to partial HTML. These are the defaults used by the display() method. header() *sheader()* *lpanel()* *content()* *rpanel()* *footer()* AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/HTML/Error: LibWeb/HTML/Error,, *Note LibWeb/HTML/Standard: LibWeb/HTML/Standard,, *Note LibWeb/Themes/Default: LibWeb/Themes/Default,.