NAME
Authen::Users - DBI Based User Authentication
DESCRIPTION
General password authentication using DBI-capable databases. Currently supports MySQL and SQLite databases. The default is to use a SQLite database to store and access user information.
This module is not an authentication protocol. For that see something such as Authen::AuthenDBI.
RATIONALE
After several web sites were written which required ongoing DBI or .htpassword file tweaking for user authentication, it seemed we needed a default user password database that would contain not only the user name and password but also such things as the information needed to reset lost passwords. Thus, this module, designed to be as much as possible a drop-in for your website authorization scripting needs.
SYNOPSIS
use Authen::Users;
my $authen = new Athen::Users(dbtype => 'SQLite', dbname => 'mydbname');
// for backward compatibility use the call below: my $authen = new Athen::Users( dbtype => 'SQLite', dbname => 'mydbname', NO_SALT => 1 );
my $a_ok = $authen->authenticate($group, $user, $password);
my $result = $authen->add_user( $group, $user, $password, $fullname, $email, $question, $answer);
METHODS
- new
-
Create a new Authen::Users object.
my $authen = new Authen::Users(dbname => 'Authentication');
Defaults are dbname => SQLIte, authen_table => authentication, create => 0 (off), digest => SHA1.
my $authen = new Authen::Users( dbtype => 'SQLite', dbname => 'authen.db', create => 1, authen_table => 'authen_table', digest => 512 );
my $authen = new Authen::Users( dbtype => 'MySQL', dbname => 'authen.db', dbpass => 'myPW', authen_table => 'authen_table', dbhost => 'mysql.server.org', digest => 256 );
Takes a hash of arguments:
- dbtype
-
The type of database. Currently supports 'SQLite' and 'MySQL'. Defaults to SQLite.
- dbname
-
The name of the database. Required for all database types.
- authen_table
-
The name of the table containing the user data.
NOTE: If this is omitted, defaults to a table called 'authentication' in the database. If the argument 'create' is passed with a true value, and the authen_table argument is omitted, then a new empty table called 'authentication' will be created in the database.
The SQL compatible table is currently as follows:
groop VARCHAR(15)-
Group of the user. This may signify authorization (trust) level, or could be used to allow one authorization database to serve several applications or sites.
user VARCHAR(30)-
User name
password VARCHAR(60)-
Password, as SHA digest
fullname VARCHAR(40)-
Full name of user
email VARCHAR(40)-
User email
question VARCHAR(120)-
Challenge question
answer VARCHAR(80)-
Challenge answer
creation VARCHAR(12)-
Row insertion timestamp
modified VARCHAR(12)-
Row modification timestamp
pw_timestamp VARCHAR(12)-
Password modification timestamp
gukey VARCHAR (46)-
Internal use: key made of user and group--kept unique
For convenience, the database has fields to store for each user an email address and a question and answer for user verification if a password is lost.
- create
-
If true in value, causes the named authen_table to be created if it was not already present when the database was opened.
- dbpass
-
The password for the account. Not used by SQLite. Sometimes needed otherwise.
- dbhost
-
The name of the host for the database. Not used by SQLite. Needed if the database is hosted on a remote server.
- digest
-
The algorithm used for the SHA digest. Currently supports SHA1 and SHA2. Defaults to SHA1. Supported values are 1 for SHA1, 256 for SHA-256, 384 for SHA-384, and 512 for SHA-512. See documentation for Digest::SHA for more information. Given that in most cases SHA1 is much more random than most user-typed passwords, any of the above algorithms should be more than sufficient, since most attacks on passwords would likely be dictionary-based, not purely brute force. In recognition that some uses of the package might use long, random passwords, there is the option of up to 512-bit SHA2 digests.
- <BREAK WITH BACKWARD COMPATIBILITY IN VERSION 0.16 and above>
-
In version 0.16 and above, a random salt is added to the digest in order to partially defeat hacking passwords with pre-computed rainbow tables. To use later versions of Authen::Users with older SQL tables created by previous versions, you MUST specify the named parameter NO_SALT => 1 in your call to new.
- OBJECT METHODS
- authenticate
-
Authenticate a user. Users may have the same user name as long as they are not also in the same authentication group. Therefore, the user's group should be included in all calls to authenticate the user by password. Passwords are stored as SHA digests, so the authentication is of the digests.
- add_user
- user_add
-
Add a user to the database. Synonym: user_add.
The arguments are as follows:
$authen->add_user($group, $user, $password, $fullname, $email, $question, $answer) or die $authen->error;
- user
-
Scalar. User name.
- password
-
Scalar. SHA digest of user's password.
- fullname
-
Scalar. The user's 'real' or full name.
-
Scalar. User's email address.
- question
-
Scalar. A question used, for example, for identifying the user if they lose their password.
- answer
-
Scalar. The correct answer to $question.
Note: it is up to the user of the module to determine how the fields after group, user, and password fields are used, or if they are used at all.
- update_user_all
-
Update all fields for a given group and user:
$authen->update_user_all($group, $user, $password, $fullname, $email, $question, $answer) or die "Could not update $user: " . $authen->errstr();
- update_user_password
-
$authen->update_user_password($group, $user, $password) or die "Cannot update password for group $group and user $user: $authen->errstr";
Update the password.
- update_user_fullname
-
$authen->update_user_fullname($group, $user, $fullname) or die "Cannot update fullname for group $group and user $user: $authen->errstr";
Update the full name.
- update_user_email
-
$authen->update_user_email($group, $user, $email) or die "Cannot update email for group $group and user $user: $authen->errstr";
Update the email address.
- update_user_question_answer
-
$authen->update_user_question_answer($group, $user, $question, $answer) or die "Cannot update question and answer for group $group and user $user: $authen->errstr";
Update the challenge question and its answer.
- delete_user
-
$authen->delete_user($group, $user) or die "Cannot delete user in group $group with username $user: $authen->errstr";
Delete the user entry.
- count_group
-
$authen->count_group($group) or die "Cannot count group $group: $authen->errstr";
Return the number of entries in group $group.
- get_group_members
-
$authen->get_group_members($group) or die "Cannot retrieve list of group $group: $authen->errstr";
Return a reference to a list of the user members of group $group.
- user_info
-
$authen->user_info($group, $user) or die "Cannot retrieve information about $user in group $group: $authen->errstr";
Return a reference to a list of the information about $user in $group.
- user_info_hashref
-
my $href = $authen->user_info_hashref($group, $user) or die "Cannot retrieve information about $user in group $group: $authen->errstr"; print "The email for $user in $group is $href->{email}";
Return a reference to a hash of the information about $user in $group, with the field names as keys of the hash.
- get_user_fullname
-
$authen->get_user_fullname($group, $user) or die "Cannot retrieve full name of $user in group $group: $authen->errstr";
Return the user full name entry.
- get_user_email
-
$authen->get_user_email($group, $user) or die "Cannot retrieve email of $user in group $group: $authen->errstr";
Return the user email entry.
- get_user_question_answer
-
$authen->get_user_question_answer($group, $user) or die "Cannot retrieve question and answer for $user in group $group: $authen->errstr";
Return the user question and answer entries.
- get_password_change_time
-
$authen->get_password_change_time($group, $user) or die "Cannot retrieve password timestamp for $user in group $group: $authen->errstr";
There is a timestamp associated with changes in passwords. This may be used to expire passwords that need to be periodically changed. The logic used to do password expiration, if any, is up to the code using the module.
- errstr
-
print $auth->errstr();
Returns the last database error, if any.
- error
-
print $auth->error;
Returns the last class internal error message, if any; if none, returns the last database DBI error, if any.
- not_in_table
-
$auth->not_in_table($group, $user);
True if $user in group $group is NOT already an entry. Useful to rule out an existing user name when adding a user.
- is_in_table
-
$auth->is_in_table($group, $user);
True if $user in group $group is already in the database.
- validate
-
$auth->validate($group, $user, $password);
True if the item is a valid entry; internal use
BUGS
On installation, "make test" may fail if Perl support for MySql or SQLite is installed, but the database itself is not running or is otherwise not available for use by the installing user. MySql by default has a 'test' database which is required under "make test." "Forcing" installation may work around this.
AUTHOR
William Herrera (wherrera@skylightview.com)
SUPPORT
Questions, feature requests and bug reports should go to wherrera@skylightview.com
COPYRIGHT
Copyright (C) 2004, 2008 William Hererra. All Rights Reserved.This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.