William Herrera > Authen-Users-0.17 > Authen::Users

Download:
Authen-Users-0.17.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.17   Source  

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;

group Scalar. The group of users. Used to classify authorizations, etc. User names may be the same if the groups are different, but in any given group the users must have unique names.
user

Scalar. User name.

password

Scalar. SHA digest of user's password.

fullname

Scalar. The user's 'real' or full name.

email

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.

syntax highlighting: