Apache::Htpasswd.3pm

Langue: en

Version: 2006-05-17 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Apache::Htpasswd - 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::SHA1 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: kmeltz@cpan.org

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

SEE ALSO

Apache::Htgroup, Crypt::PasswdMD5, Digest::SHA1, MIME::Base64