Apache::Htpasswd(3) Manage Unix crypt-style password file.

SYNOPSIS


use Apache::Htpasswd;
$foo = new Apache::Htpasswd("path-to-file");
$foo = new Apache::Htpasswd({passwdFile => "path-to-file",
ReadOnly => 1}
);
# Add an entry
$foo->htpasswd("zog", "password");
# Change a password
$foo->htpasswd("zog", "new-password", "old-password");
# Change a password without checking against old password
$foo->htpasswd("zog", "new-password", {'overwrite' => 1});
# Check that a password is correct
$foo->htCheckPassword("zog", "password");
# Fetch an encrypted password
$foo->fetchPass("foo");
# Delete entry
$foo->htDelete("foo");
# If something fails, check error
$foo->error;
# Write in the extra info field
$foo->writeInfo("login", "info");
# Get extra info field for a user
$foo->fetchInfo("login");

DESCRIPTION

This module comes with a set of methods to use with htaccess password files. These files (and htaccess) are used to do Basic Authentication on a web server.

The passwords file is a flat-file with login name and their associated crypted password. You can use this for non-Apache files if you wish, but it was written specifically for .htaccess style files.

FUNCTIONS

Apache::Htpasswd->new(...);
As of version 1.5.4 named params have been added, and it is suggested that you use them from here on out. 

        Apache::Htpasswd->new("path-to-file");

``path-to-file'' should be the path and name of the file containing the login/password information. 

        Apache::Htpasswd->new({passwdFile => "path-to-file",
                               ReadOnly   => 1,
                               UseMD5     => 1,
                             });

This is the prefered way to instantiate an object. The 'ReadOnly' param is optional, and will open the file in read-only mode if used. The 'UseMD5' is also optional: it will force MD5 password under Unix.

If you want to support plain un-encrypted passwords, then you need to set the UsePlain option (this is NOT recommended, but might be necesary in some situations)

error;
If a method returns an error, or a method fails, the error can be retrieved by calling error()
htCheckPassword("login", "password");
Finds if the password is valid for the given login.

Returns 1 if passes. Returns 0 if fails.

htpasswd("login", "password");
This will add a new user to the password file. Returns 1 if succeeds. Returns undef on failure.
htDelete("login")
Delete users entry in password file.

Returns 1 on success Returns undef on failure.

htpasswd("login", "new-password", "old-password");
If the old-password matches the login's password, then it will replace it with new-password. If the old-password is not correct, will return 0.
htpasswd("login", "new-password", {'overwrite' => 1});
Will replace the password for the login. This will force the password to be changed. It does no verification of old-passwords.

Returns 1 if succeeds Returns undef if fails

fetchPass("login");
Returns encrypted password if succeeds. Returns 0 if login is invalid. Returns undef otherwise.
fetchInfo("login");
Returns additional information if succeeds. Returns 0 if login is invalid. Returns undef otherwise.
fetchUsers();
Will return either a list of all the user names, or a count of all the users.

The following will return a list: my @users = $Htpasswd->fetchUsers();

The following will return the count: my $user_count = $Htpasswd->fetchUsers();

writeInfo("login", "info");
Will replace the additional information for the login. Returns 0 if login is invalid. Returns undef otherwise.
CryptPasswd("password", "salt");
Will return an encrypted password using 'crypt'. If salt is ommitted, a salt will be created.

INSTALLATION

You install Apache::Htpasswd, as you would install any perl module library, by running these commands: 

   perl Makefile.PL
   make
   make test
   make install
   make clean

If you are going to use MD5 encrypted passwords, you need to install Crypt::PasswdMD5.

If you need to support SHA1 encrypted passwords, you need to install Digest::SHA and MIME::Base64.

DOCUMENTATION

POD style documentation is included in the module. These are normally converted to manual pages and installed as part of the ``make install'' process. You should also be able to use the 'perldoc' utility to extract and read documentation from the module files directly.

AVAILABILITY

The latest version of Apache::Htpasswd should always be available from: 

    $CPAN/modules/by-authors/id/K/KM/KMELTZ/

Visit <URL:http://www.perl.com/CPAN/> to find a CPAN site near you.

CHANGES

Revision 1.8.0 Added proper PREREQ_PM

Revision 1.7.0 Handle SHA1 and plaintext. Also change the interface for allowing change of password without first checking old password. IF YOU DON'T READ THE DOCS AND SEE I DID THIS DON'T EMAIL ME!

Revision 1.6.0 Handle Blowfish hashes when that's the mechanism crypt() uses.

Revision 1.5.9 MD5 for *nix with new UseMD5 arg for new()

Revision 1.5.8 Bugfix to htpasswd().

Revision 1.5.7 MD5 for Windows, and other minor changes.

Revision 1.5.6 Minor enhancements.

Revision 1.5.5 2002/08/14 11:27:05 Newline issue fixed for certain conditions.

Revision 1.5.4 2002/07/26 12:17:43 kevin doc fixes, new fetchUsers method, new ReadOnly option, named params for new(), various others

Revision 1.5.3 2001/05/02 08:21:18 kevin Minor bugfix

Revision 1.5.2 2001/04/03 09:14:57 kevin Really fixed newline problem :)

Revision 1.5.1 2001/03/26 08:25:38 kevin Fixed another newline problem

Revision 1.5 2001/03/15 01:50:12 kevin Fixed bug to remove newlines

Revision 1.4 2001/02/23 08:23:46 kevin Added support for extra info fields

Revision 1.3 2000/04/04 15:00:15 meltzek Made file locking safer to avoid race conditions. Fixed typo in docs.

Revision 1.2 1999/01/28 22:43:45 meltzek Added slightly more verbose error croaks. Made sure error from htCheckPassword is only called when called directly, and not by $self.

Revision 1.1 1998/10/22 03:12:08 meltzek Slightly changed how files lock. Made more use out of carp and croak. Made sure there were no ^M's as per Randal Schwartz's request.

BUGS

None known at time of writting.

AUTHOR INFORMATION

Copyright 1998..2005, Kevin Meltzer. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.

This is released under the same terms as Perl itself.

Address bug reports and comments to: [email protected]

The author makes no warranties, promises, or gaurentees of this software. As with all software, use at your own risk.

LAST SEARCHED