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

BUGS

210       None known at time of writting.
211

AUTHOR INFORMATION

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