README
1NAME
2 Apache::Htpasswd - Manage Unix crypt-style password file.
3
4SYNOPSIS
5 use Apache::Htpasswd;
6
7 $foo = new Apache::Htpasswd("path-to-file");
8
9 # Add an entry
10 $foo->htpasswd("zog", "password");
11
12 # Change a password
13 $foo->htpasswd("zog", "new-password", "old-password");
14
15 # Change a password without checking against old password
16 # The 1 signals that the change is being forced.
17
18 $foo->htpasswd("zog", "new-password", 1);
19
20 # Check that a password is correct
21 $pwdFile->htCheckPassword("zog", "password");
22
23 # Fetch an encrypted password
24 $foo->fetchPass("foo");
25
26 # Delete entry
27 $foo->htDelete("foo");
28
29 # If something fails, check error
30 $foo->error;
31
32 # Write in the extra info field
33 $foo->writeInfo("login", "info");
34
35 # Get extra info field for a user
36 $foo->fetchInfo("login");
37
38DESCRIPTION
39 This module comes with a set of methods to use with htaccess password
40 files. These files (and htaccess) are used to do Basic Authentication on
41 a web server.
42
43 The passwords file is a flat-file with login name and their associated
44 crypted password. You can use this for non-Apache files if you wish, but
45 it was written specifically for .htaccess style files.
46
47 FUNCTIONS
48
49 htaccess->new("path-to-file");
50 "path-to-file" should be the path and name of the file containing
51 the login/password information.
52
53 error;
54 If a method returns an error, or a method fails, the error can be
55 retrived by calling error()
56
57 htCheckPassword("login", "password");
58 Finds if the password is valid for the given login.
59
60 Returns 1 if passes. Returns 0 if fails.
61
62 htpasswd("login", "password");
63 This will add a new user to the password file. Returns 1 if
64 succeeds. Returns undef on failure.
65
66 htDelete("login")
67 Delete users entry in password file.
68
69 Returns 1 on success Returns undef on failure.
70
71 htpasswd("login", "new-password", "old-password");
72 If the *old-password* matches the *login's* password, then it will
73 replace it with *new-password*. If the *old-password* is not
74 correct, will return 0.
75
76 htpasswd("login", "new-password", 1);
77 Will replace the password for the login. This will force the
78 password to be changed. It does no verification of old-passwords.
79
80 Returns 1 if succeeds Returns undef if fails
81
82 fetchPass("login");
83 Returns *encrypted* password if succeeds. Returns 0 if login is
84 invalid. Returns undef otherwise.
85
86 fetchInfo("login");
87 Returns additional information if succeeds. Returns 0 if login is
88 invalid. Returns undef otherwise.
89
90 writeInfo("login", "info");
91 Will replace the additional information for the login. Returns 0 if
92 login is invalid. Returns undef otherwise.
93
94 CryptPasswd("password", "salt");
95 Will return an encrypted password using 'crypt'. If *salt* is
96 ommitted, a salt will be generated.
97
98INSTALLATION
99 You install Apache::Htpasswd, as you would install any perl module
100 library, by running these commands:
101
102 perl Makefile.PL
103 make
104 make test
105 make install
106 make clean
107
108DOCUMENTATION
109 POD style documentation is included in the module. These are normally
110 converted to manual pages and installed as part of the "make install"
111 process. You should also be able to use the 'perldoc' utility to extract
112 and read documentation from the module files directly.
113
114AVAILABILITY
115 The latest version of Apache::Htpasswd should always be available from:
116
117 $CPAN/modules/by-authors/id/K/KM/KMELTZ/
118
119 Visit <URL:http://www.perl.com/CPAN/> to find a CPAN site near you.
120
121CHANGES
122
123 Revision 1.5.7 2004/08/23 09:05:12 Made generated salt more
124 random. Tidied up the code a bit. Also added use of Crypt::PasswdMD5
125 for Apache on MSWin for use of (modified) MD5 passwords on that
126 platform.
127
128 Revision 1.5.5 2002/08/14 11:27:05 Newline issue fixed for certain conditions.
129
130 Revision 1.5.4 2002/07/26 12:17:43 kevin doc fixes, new fetchUsers method,
131 new ReadOnly option, named params for new(), various others
132
133 Revision 1.5.3 2001/05/02 08:21:18 kevin Minor bugfix
134
135 Revision 1.5.2 2001/04/03 09:14:57 kevin Really fixed newline problem :)
136
137 Revision 1.5.1 2001/03/26 08:25:38 kevin Fixed newline problem
138
139 Revision 1.5 2001/03/15 01:50:12 kevin Fixed small bug for newlines
140
141 Revision 1.4 2001/02/23 08:23:46 kevin Added support for extra info
142 fields
143
144 Revision 1.3 2000/04/04 15:00:15 meltzek Made file locking safer to
145 avoid race conditions. Fixed typo in docs.
146
147 Revision 1.2 1999/01/28 22:43:45 meltzek Added slightly more verbose
148 error croaks. Made sure error from htCheckPassword is only called when
149 called directly, and not by $self.
150
151 Revision 1.1 1998/10/22 03:12:08 meltzek Slightly changed how files
152 lock. Made more use out of carp and croak. Made sure there were no ^M's
153 as per Randal Schwartz's request.
154
155BUGS
156 None knows at time of writting.
157
158AUTHOR INFORMATION
159 Copyright 1998..2004, Kevin Meltzer. All rights reserved. It may be used
160 and modified freely, but I do request that this copyright notice remain
161 attached to the file. You may modify this module as you wish, but if you
162 redistribute a modified version, please attach a note listing the
163 modifications you have made.
164
165 This is released under the same terms as Perl itself.
166
167 Address bug reports and comments to: perlguy@perlguy.com
168
169 The author makes no warranties, promises, or gaurentees of this
170 software. As with all software, use at your own risk.
171
172SEE ALSO
173 the Apache::Htgroup manpage
174
175