Apache::Htpasswd(3pm)

1Htpasswd(3)           User Contributed Perl Documentation          Htpasswd(3)
2
3
4

NAME

6       Apache::Htpasswd - Manage Unix crypt-style password file.
7

SYNOPSIS

9           use Apache::Htpasswd;
10
11           $foo = new Apache::Htpasswd("path-to-file");
12
13           $foo = new Apache::Htpasswd({passwdFile => "path-to-file",
14                                        ReadOnly   => 1}
15                                       );
16
17           # Add an entry
18           $foo->htpasswd("zog", "password");
19
20           # Change a password
21           $foo->htpasswd("zog", "new-password", "old-password");
22
23           # Change a password without checking against old password
24
25           $foo->htpasswd("zog", "new-password", {'overwrite' => 1});
26
27           # Check that a password is correct
28           $foo->htCheckPassword("zog", "password");
29
30           # Fetch an encrypted password
31           $foo->fetchPass("foo");
32
33           # Delete entry
34           $foo->htDelete("foo");
35
36           # If something fails, check error
37           $foo->error;
38
39           # Write in the extra info field
40           $foo->writeInfo("login", "info");
41
42           # Get extra info field for a user
43           $foo->fetchInfo("login");
44

DESCRIPTION

46       This module comes with a set of methods to use with htaccess password
47       files. These files (and htaccess) are used to do Basic Authentication
48       on a web server.
49
50       The passwords file is a flat-file with login name and their associated
51       crypted password. You can use this for non-Apache files if you wish,
52       but it was written specifically for .htaccess style files.
53
54   FUNCTIONS
55       Apache::Htpasswd->new(...);
56           As of version 1.5.4 named params have been added, and it is
57           suggested that you use them from here on out.
58
59                   Apache::Htpasswd->new("path-to-file");
60
61           "path-to-file" should be the path and name of the file containing
62           the login/password information.
63
64                   Apache::Htpasswd->new({passwdFile => "path-to-file",
65                                          ReadOnly   => 1,
66                                          UseMD5     => 1,
67                                        });
68
69           This is the prefered way to instantiate an object. The 'ReadOnly'
70           param is optional, and will open the file in read-only mode if
71           used. The 'UseMD5' is also optional: it will force MD5 password
72           under Unix.
73
74           If you want to support plain un-encrypted passwords, then you need
75           to set the UsePlain option (this is NOT recommended, but might be
76           necesary in some situations)
77
78       error;
79           If a method returns an error, or a method fails, the error can be
80           retrieved by calling error()
81
82       htCheckPassword("login", "password");
83           Finds if the password is valid for the given login.
84
85           Returns 1 if passes.  Returns 0 if fails.
86
87       htpasswd("login", "password");
88           This will add a new user to the password file.  Returns 1 if
89           succeeds.  Returns undef on failure.
90
91       htDelete("login")
92           Delete users entry in password file.
93
94           Returns 1 on success Returns undef on failure.
95
96       htpasswd("login", "new-password", "old-password");
97           If the old-password matches the login's password, then it will
98           replace it with new-password. If the old-password is not correct,
99           will return 0.
100
101       htpasswd("login", "new-password", {'overwrite' => 1});
102           Will replace the password for the login. This will force the
103           password to be changed. It does no verification of old-passwords.
104
105           Returns 1 if succeeds Returns undef if fails
106
107       fetchPass("login");
108           Returns encrypted password if succeeds.  Returns 0 if login is
109           invalid.  Returns undef otherwise.
110
111       fetchInfo("login");
112           Returns additional information if succeeds.  Returns 0 if login is
113           invalid.  Returns undef otherwise.
114
115       fetchUsers();
116           Will return either a list of all the user names, or a count of all
117           the users.
118
119           The following will return a list: my @users =
120           $Htpasswd->fetchUsers();
121
122           The following will return the count: my $user_count =
123           $Htpasswd->fetchUsers();
124
125       writeInfo("login", "info");
126           Will replace the additional information for the login.  Returns 0
127           if login is invalid.  Returns undef otherwise.
128
129       CryptPasswd("password", "salt");
130           Will return an encrypted password using 'crypt'. If salt is
131           ommitted, a salt will be created.
132

INSTALLATION

134       You install Apache::Htpasswd, as you would install any perl module
135       library, by running these commands:
136
137          perl Makefile.PL
138          make
139          make test
140          make install
141          make clean
142
143       If you are going to use MD5 encrypted passwords, you need to install
144       Crypt::PasswdMD5.
145
146       If you need to support SHA1 encrypted passwords, you need to install
147       Digest::SHA and MIME::Base64.
148

DOCUMENTATION

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

AVAILABILITY

156       The latest version of Apache::Htpasswd should always be available from:
157
158           $CPAN/modules/by-authors/id/K/KM/KMELTZ/
159
160       Visit <URL:http://www.perl.com/CPAN/> to find a CPAN site near you.
161

CHANGES

163       Revision 1.9.0  SHA dependency changes
164
165       Revision 1.8.0  Added proper PREREQ_PM
166
167       Revision 1.7.0  Handle SHA1 and plaintext. Also change the interface
168       for allowing change of password without first checking old password. IF
169       YOU DON'T READ THE DOCS AND SEE I DID THIS DON'T EMAIL ME!
170
171       Revision 1.6.0  Handle Blowfish hashes when that's the mechanism
172       crypt() uses.
173
174       Revision 1.5.9  MD5 for *nix with new UseMD5 arg for new()
175
176       Revision 1.5.8  Bugfix to htpasswd().
177
178       Revision 1.5.7  MD5 for Windows, and other minor changes.
179
180       Revision 1.5.6  Minor enhancements.
181
182       Revision 1.5.5  2002/08/14 11:27:05 Newline issue fixed for certain
183       conditions.
184
185       Revision 1.5.4  2002/07/26 12:17:43 kevin doc fixes, new fetchUsers
186       method, new ReadOnly option, named params for new(), various others
187
188       Revision 1.5.3  2001/05/02 08:21:18 kevin Minor bugfix
189
190       Revision 1.5.2  2001/04/03 09:14:57 kevin Really fixed newline problem
191       :)
192
193       Revision 1.5.1  2001/03/26 08:25:38 kevin Fixed another newline problem
194
195       Revision 1.5  2001/03/15 01:50:12 kevin Fixed bug to remove newlines
196
197       Revision 1.4  2001/02/23 08:23:46 kevin Added support for extra info
198       fields
199
200       Revision 1.3  2000/04/04 15:00:15 meltzek Made file locking safer to
201       avoid race conditions. Fixed typo in docs.
202
203       Revision 1.2  1999/01/28 22:43:45  meltzek Added slightly more verbose
204       error croaks. Made sure error from htCheckPassword is only called when
205       called directly, and not by $self.
206
207       Revision 1.1  1998/10/22 03:12:08  meltzek Slightly changed how files
208       lock.  Made more use out of carp and croak.  Made sure there were no
209       ^M's as per Randal Schwartz's request.
210

BUGS

212       None known at time of writting.
213

AUTHOR INFORMATION

215       Copyright 1998..2005, Kevin Meltzer.  All rights reserved.  It may be
216       used and modified freely, but I do request that this copyright notice
217       remain attached to the file.  You may modify this module as you wish,
218       but if you redistribute a modified version, please attach a note
219       listing the modifications you have made.
220
221       This is released under the same terms as Perl itself.
222
223       Address bug reports and comments to: kmeltz@cpan.org
224
225       The author makes no warranties, promises, or gaurentees of this
226       software. As with all software, use at your own risk.
227