File Coverage

blib/lib/CGI/Auth.pm
Criterion Covered Total %
statement 63 342 18.4
branch 23 164 14.0
condition 11 46 23.9
subroutine 6 29 20.6
pod 25 25 100.0
total 128 606 21.1


line stmt bran cond sub pod time code
1             # $Id: Auth.pm,v 1.17 2004/01/28 07:05:46 cmdrwalrus Exp $
2              
3             package CGI::Auth;
4              
5 1     1   773 use strict;
  1         2  
  1         38  
6              
7 1     1   5 use Carp;
  1         2  
  1         79  
8              
9 1     1   15 use vars qw/$VERSION/;
  1         2  
  1         60  
10             $VERSION = '3.00';
11              
12             # This delimiter cannot be a regex special character, unfortunately, since it
13             # is used with split. So, for instance, the pipe (|) is not allowed, as well
14             # as the dash (-), caret (^), dot (.), etc...
15 1     1   5 use constant DELIMITER => ':';
  1         2  
  1         4870  
16              
17             =pod
18              
19             =head1 NAME
20              
21             CGI::Auth - Simple session-based password authentication for CGI applications
22              
23             =head1 SYNOPSIS
24              
25             require CGI::Auth;
26              
27             my $auth = new CGI::Auth({
28             -authdir => 'auth',
29             -formaction => "myscript.pl",
30             -authfields => [
31             {id => 'user', display => 'User Name', hidden => 0, required => 1},
32             {id => 'pw', display => 'Password', hidden => 1, required => 1},
33             ],
34             });
35             $auth->check;
36              
37             =head1 DESCRIPTION
38              
39             C provides password authentication for web-based applications. It
40             uses server-based session files which are referred to by a parameter in all
41             links and forms inside the scripts guarded by C.
42              
43             At the beginning of each script, a C object should be created and
44             its C method called. When this happens, C checks for a
45             'session_file' CGI parameter. If that parameter exists and has a matching
46             session file in the session directory, C returns, and the rest of the
47             script can execute.
48              
49             If the session file parameter or the file itself doesn't exist, C
50             presents the user with a login form and exits the script. The login form will
51             then be submitted to the same script (specified in C<-formaction>). When
52             C is called this time, it verifies the user's login information in the
53             userfile, creates a session file and provides the session file parameter to the
54             rest of the script.
55              
56             =head1 CREATING AND CONFIGURING
57              
58             Before anything can be done with C, an object must be created:
59              
60             my $auth = new CGI::Auth( \%options );
61              
62             =head2 Parameters to C
63              
64             The C method creates and configures a C object using
65             parameters that are passed via a hash reference that can/should contain the
66             following items (optional ones are indicated):
67              
68             =over 4
69              
70             =item C<-cgi>
71              
72             I<(optional)>
73              
74             This parameter provides C with a CGI object reference so that the
75             extra overhead of creating another object can be avoided. If your script is
76             going to use CGI.pm, it is most efficient to create the CGI object and pass it
77             to C, rather than both your script and Auth having to create
78             separate objects.
79              
80             Note: As of version 2.4.3, C can now be used with C.
81             This hasn't been tested thoroughly yet, so use caution if you decide to do so.
82              
83             =item C<-admin>
84              
85             I<(optional if C<-formaction> given)>
86              
87             This parameter should be used by command-line utilities that perform
88             administration of the user database. If Auth is given this parameter, it will
89             only allow command-line execution (execution from CGI will be aborted).
90              
91             =item C<-authdir>
92              
93             I<(required)>
94              
95             Directory where Auth will look for its files. In other words, if C<-sessdir>,
96             C<-userfile>, C<-logintmpl>, C<-loginheader> or C<-loginfooter> are scalars
97             and do not begin with a slash (i.e., are not absolute paths), this directory
98             will be prepended to them.
99              
100             =item C<-sessdir>
101              
102             I<(optional, default = 'sess')>
103              
104             Directory where Auth will store session files. These files should be pruned
105             periodically (i.e., nightly or weekly) since a session file will remain here if
106             a user does not log out.
107              
108             =item C<-userfile>
109              
110             I<(optional, default = 'user.dat')>
111              
112             File containing definitions of users, including login information and any extra
113             parameters. This file will be created, edited and read by C and its
114             command-line administration tool.
115              
116             =item C<-logintmpl>
117              
118             I<(optional, excludes C<-loginheader> and C<-loginfooter> if present)>
119              
120             Template for use with C. The template can be given in one of
121             three ways:
122              
123             =over 4
124              
125             =item 1
126              
127             An C object reference,
128              
129             =item 2
130              
131             A hash containing parameters for Cnew>, or
132              
133             =item 3
134              
135             A filename (then C<-logintmplpath> can be the path parameter).
136              
137             =back
138              
139             The template must contain a form for the user to fill out, and it is
140             recommended that the form not contain any elements with names beginning with
141             'auth_', since these are reserved for C fields.
142              
143             A sample template file (C) is included in the extra subdirectory of
144             this package.
145              
146             For a list of what should be included in the template, see
147             L