CGI::Htauth.pm - Authentication services for CGI scripts.
use CGI; # Sadly, CGI::Minimal is not enough use CGI::FormBuilder; # usually; Htauth will use it anyway use CGI::Htauth; # :-) my $CGI = new CGI; # necessary when using Htauth &initialise_htauth($CGI); # before any text gets output ! &header($CGI->param('maintask') || $ENV{SCRIPT_NAME}); &authenticate(<<EOT); dbdir /var/run/htauth allow 127.0.0.1 # trust localhost logins deny 10.0.123.* # lock out Sales PCs password 10.*.*.* timeout=900 # password login on local net challenge 123.234.*.* timeout=600 # for Sydney office challenge *.*.*.* timeout=0 # just useable for travellers EOT if ($AUTH_USER eq 'fred') { # fred has logged in by password or challenge-response ... my $form = CGI::FormBuilder->new( params => $CGI, # necessary when also using Htauth ! keepextras => 1, # necessary when also using Htauth ! method => 'POST', # necessary when also using Htauth ! fields => [qw(thisfield thatfield theotherfield email)], validate => {email => 'EMAIL'}, ); if (!$form->submitted || !$form->validate) { &output($form->render); # Must use output not print ! &footer(); } &do_fred_stuff(); } else { &do_other_stuff(); } sub header { output "<HTML><HEAD><TITLE>$_[$[]</TITLE></HEAD><BODY>\n"; } sub footer { output "<HR></BODY></HTML>\n"; }
This Perl library provides authentication services useable by CGI scripts. Several levels of authentication can be imposed, depending on the IP address or hostname of the client.
Then authentication is performed by calling the subroutine authenticate according to a configuration specified its argument.
The calling program must unfailingly use output instead of the usual print so that Htauth can encrypt the HTML text if necessary. The calling program must also call &initialise_htauth($CGI); before any text is output, so that Htauth knows whether to print the text immediately or to save it up for later encryption. If the calling program uses CGI::FormBuilder, the options "params => $CGI", "keepextras => 1" and method => 'POST' must always be present. It is not essential, but will make presentation slicker, if the calling program has subroutines (in package main) called &header($title) and &footer to output (using output, remember...) the HTML header and footer.
CGI::Htauth.pm uses CGI.pm (CGI::Minimal.pm lacks the delete method), uses Crypt::Tea.pm in order to communicate securely with JavaScript-capable browsers, and uses CGI::FormBuilder.pm to manage the data entry. Very often the cgi programmer will be using CGI::FormBuilder.pm anyway, to write the application.
Version 1.21, #COMMENT#
The argument $CGI is a reference to a CGI object. This must be called before any text is output to inform Htauth of the state of the parameters.
The argument $config_txt is either a multiline text string, or the name of a file containing such a string. IP addresses (indicated as IPADDR) may contain * which matches any string of up to three digits. The second argument is again the reference to the CGI object.
The first config line that matches the client IP address $ENV{REMOTE_ADDR} will determine the type of authentication to which the client is subject. If the user has logged in, either by password or by challenge-response, then the (exported) Perl variable $AUTH_USER is set to the username.
Access will be allowed from any IP address matching the $ip pattern.
Access will be denied from any IP address matching the $ip pattern.
Access from any IP address matching the $ip pattern is met with a Username-and-Password login request. This data travels over the network in cleartext (unless you are using https). If the Password is valid, then a temporary session key is generated, which is passed back to the next invocation by hidden form variables.
This routine uses various FORM variables beginning with htauth_ and applications would be wise to avoid creating FORM variables beginning with htauth_ as these may produce Unpredictable Consequences.
Access from any IP address matching the $ip pattern is met with a Username request and a One-time-key challenge. This data travels over the network in cleartext (unless you are using https). If the Password is valid, then a temporary session key is generated, which is passed back to the next invocation by hidden form variables. A new temporary session key is generated every invocation, so the user will not be able to use the browser's Back key.
If the session is within 30 seconds of timing out, a new One-time-key challenge is issued instead. Thus setting the timeout to less than 30 seconds (e.g. to 0, the default) causes a One-time-key challenge to be issued on every page.
The argument $dbdir is the directory in which the password databases will be set up. If it doesn't exist, it should be createable. It must be writeable by the httpd user, eg nobody or wwwrun.
The argument $username is the Htauth-username whose password is to be changed. This username will be created if it doesn't yet exist.
The argument $password is the new password.
Like everything on the web, CGI::Htauth.pm must do its stuff by manipulating frames, forms and query variables. The names it reserves for its own use all begin with htauth_ so applications should avoid creating frames, forms, query variables or JavaScript variables or methods beginning with htauth_ as these may have Unpredictable Consequences.
is the almost invisible top frame which occurs in JavaScript login; it contains nothing but the hidden forms htauth_form0 (to submit), htauth_form1 (to log in again) and htauth_form2 (to log out)
is the main frame which occurs in JavaScript login; it contains the application as seen by the user.
is the hidden form which is filled out by JavaScript with the encrypted data htauth_t and the response htauth_r, and is really submitted when the user thinks they're submitting the application form visible in htauth_frame1. This form is also used, with htauth_x = change, to change password.
is the hidden form with a TARGET of the main (parent) FRAMESET, which causes Htauth to ask for a new login.
is the hidden form with a TARGET of the main (parent) FRAMESET, which logs the user out and restarts the entire script with no variables.
is the form used during non-JavaScript login which asks for username and password.
is the form in htauth_frame1 which just asks for username, used during login on a JavaScript-capable browser; it also sniffs to see is JavaScript is enabled.
is a sniffer variable, which the browser sets to 'yes' if JavaScript is actually enabled.
is the form which just asks for password, residing in htauth_frame1 and used during password login on a JavaScript-enabled browser
is a Password as entered by user; it only gets transmitted to the server if the user does not have a JavaScript-enabled browser.
is the challenge issued by the server during the JavaScript password login dialogue.
is a Session Key, generated at login by Htauth, which is used during a login session.
is the browser's Response to a challenge by the server; it is used both during challenge-response login, and during the JavaScript password login dialogue.
is stuff encrypted by Crypt::Tea in the browser
is a hold-all for other commands such as change password, log out, etc etc
is used during a JavaScript login session; it is set to the document BGCOLOR by JavaScript in the browser, and is used by Htauth to set a background colour for all its dialogue which fits the decor of the application.
is likewise set to the document TEXT by JavaScript in the browser, and is used by Htauth to set a foreground colour for its dialogues.
Currently challenge-response is not really implemented.
Several more config directives are tempting, for example: some built-in way of insisting on a minimum password length, logdir to allow logging of logins and logouts, perhaps other modes to specify use of Crypt::Tea during login for security but then an unencrypted session to lighten the CPU load on the server, or to allow only JavaScript browsers so that the password can never be betrayed.
Perhaps for a session, the challenge could be used together with the password as the encryption key, to make cryptanalyisis harder for someone prepared to sniff multiple login sessions.
User admin functions could be much more pre-packaged and complete.
Peter J Billam <computing@pjb.com.au>
Based on and older module called htauth.pm which used htui.pm to handle the user interface, instead of Nathan Wiger's CGI::FormBuilder.pm. Thanks also to Neil Watkiss for MakeMaker packaging.
http://www.cpan.org/SITES.html, http://www.pjb.com.au/, CGI.pm, CGI::FormBuilder.pm, Crypt::Tea.pm, perl(1).
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install CGI::Htauth, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Htauth
CPAN shell
perl -MCPAN -e shell install CGI::Htauth
For more information on module installation, please visit the detailed CPAN module installation guide.