package WWW::Authen::Simple;
# $Source: /usr/local/cvs/WWW-Authen-Simple/pm/Simple.pm,v $
# $Revision: 1.24 $
# $Date: 2004/05/12 03:21:32 $
# $Author: jmiller $
use 5.00503;
use strict;
use Digest::MD5 ();
use Carp;
use CGI qw(:standard);
use lib './';
use vars qw($VERSION $REVISION);
$REVISION = sprintf "%d.%03d", q$Revision: 1.24 $ =~ /(\d+)/g;
$VERSION = '1.22';
# Config for table layout and such.
# we'll provide methods to override this, so that WWW:A:S can
# adapt to other systems
my $conf = {
session_table => {
_table => 'sessions', # table name
login => 'username', # username field
address => 'address', # remote address field
ticket => 'ticket', # session ticket field
point => 'point', # timestamp point field
},
user_table => {
_table => 'Users', # table name
uid => 'uid', # user unique id field
login => 'login', # username field
passwd => 'passwd', # password field
status => 'disabled', # status field
# sub ref to determine if status value is active
_active_status => sub { return 1 if ($_[0] != 1); },
# sub ref to determine if status value is disabled
_disabled_status => sub { return 1 if ($_[0] == 1); },
},
# group statement is used to get the groups. It should
# fetch a groupname, groupid, and an accessbit.
# If you don't want to use the accessbit field, just stick
# the groupid field there as well.
# %uid% will be replaced with a quoted uid value for the user.
# here's an alternate statement, to give you some ideas:
# SELECT groupname, gid, gid FROM Users WHERE uid = %uid%
group_statement => 'SELECT g.Name, ug.gid, ug.accessbit
FROM Groups g, UserGroups ug
WHERE g.gid = ug.gid AND ug.uid = %uid%',
# subroutine ref used to encrypt password for db storage
'crypt' => sub { return Digest::MD5::md5_base64($_[0]); }
};
sub new
{
my ($this) = shift;
my $class = ref($this) || $this;
my $self = {};
bless( $self, $class );
my %opts = @_;
$self->conf($conf);
my $debug = (defined($opts{debug}) && ($opts{debug} =~ /^\d+$/))
? $opts{debug} : 0;
$self->debug($debug);
my $expire_seconds = (defined($opts{expire_seconds}) && ($opts{expire_seconds} =~ /^\d+$/))
? $opts{expire_seconds} : 3600;
$self->expire_seconds($expire_seconds);
my $cleanup_seconds = (defined($opts{cleanup_seconds}) && ($opts{cleanup_seconds} =~ /^\d+$/))
? $opts{cleanup_seconds} : 43200;
$self->cleanup_seconds($cleanup_seconds);
$self->cookie_domain($opts{cookie_domain});
$self->db($opts{db}) if($opts{db});
return $self;
}
sub db
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
$self->{_db} = $_[0];
return $self->{_db};
} else {
return $self->{_db};
}
}
sub cookie_domain
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
$self->{_cookie_domain} = $_[0];
return $self->{_cookie_domain};
} else {
return $self->{_cookie_domain};
}
}
sub expire_seconds
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
croak "expire must be a possitive integer" unless ($_[0] =~ /^\d+$/);
$self->{_expire_seconds} = $_[0];
return $self->{_expire_seconds};
} else {
return $self->{_expire_seconds};
}
}
sub cleanup_seconds
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
croak "expire must be a possitive integer" unless ($_[0] =~ /^\d+$/);
$self->{_cleanup_seconds} = $_[0];
return $self->{_cleanup_seconds};
} else {
return $self->{_cleanup_seconds};
}
}
sub debug
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
$self->{_debug} = $_[0];
return $self->{_debug};
} else {
return $self->{_debug};
}
}
sub cleanup
{
ref(my $self = shift) or croak "instance variable needed";
my $cleanup_point = time() - $self->cleanup_seconds();
$self->db->do( 'DELETE FROM '.
$self->conf->{session_table}{_table} .
' WHERE '.
$self->conf->{session_table}{point} .
' < ' .
$self->db->quote($cleanup_point) );
}
sub username
{
ref(my $self = shift) or croak "instance variable needed";
return $self->{_store}{username} if($self->{_store}{username});
return undef;
}
sub uid
{
ref(my $self = shift) or croak "instance variable needed";
return $self->{_store}{uid} if($self->{_store}{username});
return undef;
}
sub logged_in
{
ref(my $self = shift) or croak "instance variable needed";
return 1 if($self->{_store}{username});
return undef unless(($self->{_store}{login_called}) && ($self->{_store}{username}));
return 0;
}
sub groups
{
ref(my $self = shift) or croak "instance variable needed";
# load groups for this user if we haven't loaded them already
unless (defined $self->{_store}{_groups})
{
$self->_load_groups();
}
my @return_array;
foreach my $group (keys %{$self->{_store}{_groups}})
{
push(@return_array,$group); # group could be a name or gid
}
return @return_array;
}
sub _load_groups
{
ref(my $self = shift) or croak "instance variable needed";
my $group_statement = $self->conf->{group_statement};
# inject uid
my $q_uid = $self->db->quote( $self->{_store}{uid} );
$group_statement =~ s/\%uid\%/$q_uid/g;
my $get_groups = $self->db->prepare( $group_statement )
or croak "Unable to prepare group select statement '$group_statement'";
$get_groups->execute
or croak "Unable to execute group select statement '$group_statement'";
while (my ($name,$gid,$accessbit) = $get_groups->fetchrow_array)
{
$self->{_store}{_groups}{$name} = $accessbit;
$self->{_store}{_groups}{$gid} = $accessbit;
}
$get_groups->finish;
}
sub in_group
{
ref(my $self = shift) or croak "instance variable needed";
my ($group,$rw) = @_;
my $rwbit;
if ($rw && ($rw =~ /^\d+$/))
{ # it's a number
$rwbit = $rw;
} elsif ($rw && ($rw =~ /^(r|w)/i)) {
# it's a name (should be either "r", "w", or "rw"
$rwbit += 1 if ($rw =~ /r/i);
$rwbit += 2 if ($rw =~ /w/i);
} else {
# just return the bits, since they didn't ask for something
$rwbit = 0;
}
# load groups for this user if we haven't loaded them already
unless (defined $self->{_store}{_groups})
{
$self->_load_groups();
}
# $group can be either a gid or a group name.
# we just make sure we don't name any of our groups w/ numbers
if (defined $self->{_store}{_groups}{$group})
{ # they're in the group they asked for
# either return the accessbits,
# or true/false if they specified a $rw bit
if ($rwbit)
{ # we check the access bit in here (using bitwise AND)
warn "in_group(G[$group] rw[$rwbit])\n\tstored rwbit[".$self->{_store}{_groups}{$group}."]\n\tRV[".(($self->{_store}{_groups}{$group} & $rwbit) == $rwbit)."]\n" if $self->debug();
return (($self->{_store}{_groups}{$group} & $rwbit) == $rwbit);
} else {
# just return the access bit
return $self->{_store}{_groups}{$group};
}
} else {
return 0; # zero is no read, no write
}
}
sub login
{
ref(my $self = shift) or croak "instance variable needed";
my ($login,$passwd) = @_;
my $cgi = new CGI;
my $remote_address = $ENV{REMOTE_ADDR};
$self->{_store}{login_called} = 1;
if ($login && $passwd)
{ # if neither are null, they're trying to login.
my ($uid,$local_passwd,$status) = $self->_get_user_info($login);
# invalid login (user doesn't exist)
return (0,$login) unless $uid;
# invalid login (account is disabled)
return (0,$login) if &{$self->conf->{user_table}{_disabled_status}}($status);
my $crypt_passwd = $self->_getcrypt($passwd);
if ($crypt_passwd eq $local_passwd)
{
# they're authenticated... need to update local session, set cookie ticket for them, and return "1" for logged in
my $new_ticket = $self->_ticket;
my $point = time;
$self->{_store}{username} = $login;
$self->{_store}{uid} = $uid;
$self->_set_session($login,$remote_address,$new_ticket,$point);
return (1,$login,$uid);
} else {
return (0,$login); # invalid login (passwd doesn't match)
}
}
my $remote_login = $cgi->cookie('login');
my $remote_ticket = $cgi->cookie('ticket');
if ($remote_login && $remote_ticket)
{ # they've logged in before (or are spoofing)
my $get_ticket = $self->db->prepare(
'SELECT '.
$self->conf->{session_table}{ticket} .', '.
$self->conf->{session_table}{point} .
' FROM '.
$self->conf->{session_table}{_table} .
' WHERE '.
$self->conf->{session_table}{login} .' = '.
$self->db->quote($remote_login) .
' AND '.
$self->conf->{session_table}{address} .' = '.
$self->db->quote($remote_address)
) or croak "Unable to prepare get_ticket statement";
$get_ticket->execute()
or croak "Unable to execute get_ticket statement";
my ($local_ticket,$local_point) = $get_ticket->fetchrow_array();
$get_ticket->finish;
my $point = time;
if ($local_ticket && ($remote_ticket eq $local_ticket))
{
if ($local_point > ($point - $self->expire_seconds()))
{ # valid ticket, continue sesson
# keep using existing ticket, update point on it
# set remote cookie's (so they don't time out)
# return logged in signal
# make sure they're not disabled
my ($uid,$local_passwd,$status) = $self->_get_user_info($remote_login);
return (0,$remote_login) if &{$self->conf->{user_table}{_disabled_status}}($status);
my $point = time;
$self->_set_session($remote_login,$remote_address,$local_ticket,$point);
$self->{_store}{username} = $remote_login;
$self->{_store}{uid} = $uid;
return (1,$remote_login,$uid);
} else {
# login has expired
return (-1,$remote_login); #login expired
}
} else {
# invalid ticket (username cookie matched, ticket cookie didn't)
return (0,$remote_login); # invalid login
}
} else {
# didn't try to login, and no cookies set
return (0,0);
}
}
sub conf
{
ref(my $self = shift) or croak "instance variable needed";
if (@_)
{
$self->{_conf} = $_[0];
return $self->{_conf};
} else {
return $self->{_conf};
}
return $self->{_conf};
}
sub _get_user_info
{
ref(my $self = shift) or croak "instance variable needed";
my $login = shift;
my $get_user_info = $self->db->prepare(
'SELECT '.
$self->conf->{user_table}{uid} .', '.
$self->conf->{user_table}{passwd} .', '.
$self->conf->{user_table}{status} .
' FROM '.
$self->conf->{user_table}{_table} .
' WHERE '.
$self->conf->{user_table}{login} . ' = ' .
$self->db->quote($login) )
or croak "Unable to prepare get_user_info statement";
$get_user_info->execute
or croak "Unable to execute get_user_info statement";
my ($uid,$local_passwd,$status) = $get_user_info->fetchrow_array();
$get_user_info->finish;
return ($uid,$local_passwd,$status);
}
sub logout
{
ref(my $self = shift) or croak "instance variable needed";
my $cgi = new CGI;
my $login = $self->username() || $cgi->cookie('login');
my $remote_address = $ENV{REMOTE_ADDR};
if ($login && $remote_address)
{
$self->_set_session($login,$remote_address,'*',0);
}
# clear out the stored data
$self->{_store}{username} = '';
$self->{_store}{uid} = '';
# leave _groups hash ref so that we don't try to reload them
# but clear all access bits, removing the users access
foreach my $group (keys %{$self->{_store}{_groups}})
{
$self->{_store}{_groups}{$group} = '0';
}
}
sub _set_cookie
{
ref(my $self = shift) or croak "instance variable needed";
my ($login,$ticket,$point) = @_;
my ($login_cookie,$ticket_cookie);
my $base_cookie = '; domain=' . $self->cookie_domain();
if ($point == 0)
{ # if they hit logout, then try to expire their local cookie
$base_cookie .= '; max-age=0';
} else {
$base_cookie .= '; max-age=' . $self->expire_seconds();
}
$base_cookie .= '; path=/';
$base_cookie .= '; version=1';
print 'Set-Cookie: login=' . $login . $base_cookie . "\n";
print 'Set-Cookie: ticket=' . $ticket . $base_cookie . "\n";
}
sub _set_session
{
ref(my $self = shift) or croak "instance variable needed";
my ($login,$address,$ticket,$point) = @_;
$self->_set_cookie($login,$ticket,$point);
# set local session
my $get_ticket = $self->db->prepare(
'SELECT '.
$self->conf->{session_table}{ticket} .
' FROM '.
$self->conf->{session_table}{_table} .
' WHERE '.
$self->conf->{session_table}{login} . ' = '.
$self->db->quote($login) .
' AND '.
$self->conf->{session_table}{address} . ' = '.
$self->db->quote($address) )
or croak "Unable to prepare get_ticket statement";
$get_ticket->execute()
or croak "Unable to execute get_ticket statement";
my ($local_ticket) = $get_ticket->fetchrow_array();
$get_ticket->finish;
if ($local_ticket)
{ # a session has already been stored for this user/addy
$self->db->do(
'UPDATE '.
$self->conf->{session_table}{_table} .
' SET '.
$self->conf->{session_table}{ticket} .' = '.
$self->db->quote($ticket) .', '.
$self->conf->{session_table}{point} .' = '.
$self->db->quote($point) .
' WHERE '.
$self->conf->{session_table}{login} .' = '.
$self->db->quote($login) .
' AND '.
$self->conf->{session_table}{address} .' = '.
$self->db->quote($address) )
or croak "Unable to update session table for login[$login] address[$address]";
} else {
# set a new local session
$self->db->do(
'INSERT INTO '.
$self->conf->{session_table}{_table} .
' ('.
$self->conf->{session_table}{login} .', '.
$self->conf->{session_table}{address} .', '.
$self->conf->{session_table}{ticket} .', '.
$self->conf->{session_table}{point} .
') VALUES ('.
$self->db->quote($login) .', '.
$self->db->quote($address) .', '.
$self->db->quote($ticket) .', '.
$self->db->quote($point) .')'
) or croak "Unable to insert session for login[$login] address[$address]";
}
}
sub _ticket
{
my $length = 128;
my $ticket;
while($length-- > 0)
{
$ticket .= chr(rand(256));
}
return Digest::MD5::md5_hex($ticket);
}
sub _getcrypt
{
ref(my $self = shift) or croak "instance variable needed";
my $pass = shift;
return &{$self->conf->{'crypt'}}($pass);
}
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
WWW::Authen::Simple - Cookie based session and authentication module using database backend. Also provides group based authorization.
=head1 SYNOPSIS
use WWW::Authen::Simple;
my $simple = WWW::Authen::Simple->new(
db => $DBI_handle,
cookie_domain => 'cookie_domain'
);
# Alternitively, any of the methods to set variables may also be
# used directly in the constructor
$simple->logout() if $cgi->param('logout');
$simple->login( $cgi->param('login'), $cgi->param('pass') );
if ($simple->logged_in()) {
if ($simple->in_group('Admin','rw')) {
&do_admin_page();
} else {
&do_something();
}
} else {
print redirect('/login.pl');
}
=head1 ABSTRACT
WWW::Authen::Simple provides another way to do cookie based sessions and authentication. It's goal is to provide a very simple API to handle sessions and authentication.
The database layout has been abstracted, so you should be able to fit this into whatever database layout you currently use, or use the provided default to base your application.
NOTE: the database abstraction is configured by a hash. If changes to it's structure are needed, you currently have to rebuild the entire hash, and pass it in (ie. there is no API to make it easy to change yet).
=head1 REQUIRES
DBI and an appropriate DBD driver for your database
Digest::MD5 (standard perl module)
CGI
In most common situations, you'll also want to have:
A web server (untested on windows, but it should work)
cgi-bin or mod-perl access
Perl: Perl 5.00503 or later must be installed on the web server.
=head1 INSTALLATION
The module can be installed using the standard Perl procedure:
perl Makefile.PL
make
make test
make install # you need to be root
Windows users without a working "make" can get nmake from:
ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
=head1 METHODS
=over
=item C<$simple = WWW::Authen::Simple-E<gt>new();>
This creates a new Simple object.
Optionally, you can pass in a hash with configuration information.
See the method descriptions for more detail on what they mean.
=over 2
cookie_domain => 'www.somedomain.com', # required
db => $DBI_handle, # required
expire_seconds => 3600, # optional. default 3600
cleanup_seconds => 43200, # optional. default 43200
debug => 0, # optional. default 0
conf => $config_hash_ref, # optional. defaults hardcoded.
=back
=item C<$simple-E<gt>db( $DBIx_PDlib_object );>
Required. Database Handle from DBIx::PDlib;
=item C<$simple-E<gt>cookie_domain( 'www.some_domain.com' );>
Required. The Domain your authenticating into. Needed to store the cookie info.
=item C<$simple-E<gt>login( $login, $password );>
If $login and $password are undef (not set / not passed in), it checks the users cookies for a valid ticket. Otherwise, checks the username/password against the database.
Returns:
(0,$login) : inactive account, user doesn't exist,
password doesn't match, or invalid ticket
(1,$login,$uid) : login successful
(-1,$login) : login expired
(0,0) : no user/pass sent, no cookies exist.
=item C<$simple-E<gt>logout();>
Logs the current user out by nulling out their session ticket in the database.
=item C<$simple-E<gt>logged_in();>
Returns 1 if the user is logged in. Returns undef is login() was called, but the user failed authentication. Returns 0 (zero) if the login() hasn't been called yet.
=item C<$simple-E<gt>uid();>
Get the current session user id.
=item C<$simple-E<gt>username();>
Get the current session username.
=item C<$simple-E<gt>groups();>
Returns an array of all groups names and group id's the user belongs to.
=item C<$simple-E<gt>in_group($group,$rw);>
$group can be the group name, or the group id.
$rw (optional) can be:
1 : Read access for the group.
2 : Write access for the group.
3 : Both read and write access for the group.
r : Read access for the group.
w : Write access for the group.
rw : Both read and write access for the group.
If called without the $rw option, it returns the raw access bits (will be true if the user is in the group and has any level of access: read, write, or both).
If called with the $rw option, returns true if the user is in the group, and has that level of access. Returns false otherwise.
=item C<$simple-E<gt>debug( [0|1|2] );>
Optional.
Sets the debugging bit. 1 turns it on, 0 turns it off. 2 will print out verbose messages to STDERR.
=item C<$simple-E<gt>cleanup();>
Cleans out the old sessions from the session database. Should be called once in a while from a cron script. The frequency of calls to this is up to you, and it's need depends on how heavy your usage is. If you never call cleanup(), it won't be the end of the world... things will keep working just fine.
=item C<$simple-E<gt>cleanup_seconds($integer_seconds);>
How old a session entry should be before it get's cleaned out. Defaults to 43200 seconds (12 hours).
=item C<$simple-E<gt>conf($conf);>
$conf is optional. Set's the config hash if it's passed in.
Returns the config hash.
Config hash is structured like so:
$conf = {
session_table => {
_table => 'sessions', # table name
login => 'username', # username field
address => 'address', # remote address field
ticket => 'ticket', # session ticket field
point => 'point', # timestamp point field
},
user_table => {
_table => 'Users', # table name
uid => 'uid', # user unique id field
login => 'login', # username field
passwd => 'passwd', # password field
status => 'disabled', # status field
# sub ref to determine if status value is active
_active_status => sub { return 1 if ($_[0] != 1); },
# sub ref to determine if status value is disabled
_disabled_status => sub { return 1 if ($_[0] == 1); },
},
# group statement is used to get the groups. It should
# fetch a groupname, groupid, and an accessbit.
# If you don't want to use the accessbit field, just stick
# the groupid field there as well.
# %uid% will be replaced with a quoted uid value for the user.
# here's an alternate statement, to give you some ideas:
# SELECT groupname, gid, gid FROM Users WHERE uid = %uid%
group_statement => 'SELECT g.Name, ug.gid, ug.accessbit
FROM Groups g, UserGroups ug
WHERE ug.uid = %uid%',
# subroutine ref used to encrypt password for db storage
'crypt' => sub { return Digest::MD5::md5_base64($_[0]); }
};
=back
=head1 SEE ALSO
"examples" subdirectory of this distribution.
Averist.pm: http://www.nongnu.org/averist/ : A more flexable session/auth module.
CGI::Session: http://search.cpan.org/dist/CGI-Session
Apache::Session: http://search.cpan.org/dist/Apache-Session
CGI::Session::Auth: http://search.cpan.org/dist/CGI-Session-Auth
=head1 TODO
Tests need written.
Session storage abstraction.
Authentication method abstraction.
=head1 AUTHORS
Josh I. Miller, E<lt>jmiller@purifieddata.netE<gt>
Seth T. Jackson, E<lt>sjackson@purifieddata.netE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright 2003 by Seth Jackson
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut