27663afe |
1 | Master Change Password plugin |
2 | ----------------------------- |
3 | |
4 | WHAT'S THIS? |
5 | This plugin is a general framework for enabling the user to |
6 | change his/her password. It allows for different backend |
7 | to perform this task on different systems. |
8 | |
9 | STATUS |
10 | Development |
11 | |
fe90e5e4 |
12 | REQUIREMENTS: |
e597520d |
13 | - SquirrelMail 1.4.3 or later. (plugin is included in SquirrelMail |
fe90e5e4 |
14 | 1.5.0 and later versions). |
e597520d |
15 | - ldap backend needs PHP LDAP extension. It might need PHP |
16 | Mhash extension and system crypt libraries that support crypto |
17 | used on LDAP server. It might need PHP LDAP extension with SSL |
18 | support, if LDAP server requires it. |
19 | - mysql backend needs PHP MySQL extension. |
20 | - merak backend needs PHP Curl extension. |
7bdb9b31 |
21 | - peardb backend needs PHP Pear DB libraries (v.1.6.0 or newer) and |
22 | PHP extension that is used to connect to database. |
e597520d |
23 | - poppassd backend needs poppassd server that supports authentication |
24 | used by IMAP server. |
25 | - vmailmgrd backend needs vmailmgr PHP library (vmail.inc) and |
2b2e606c |
26 | vmailmgrd service running on tcp port or unix socket. It also |
27 | requires SquirrelMail 1.4.4 or 1.5.1. |
fe90e5e4 |
28 | |
27663afe |
29 | CONFIGURATION |
30 | Edit the file config.php to set the backend you want to use. |
76063016 |
31 | |
32 | Backends can use special arrays that override default values set |
33 | in backend/<yourbackend>.php. Check description of backend that |
34 | you use. |
27663afe |
35 | |
36 | BACKENDS |
02c81de4 |
37 | - ldap |
38 | |
39 | Default settings are supplied in backends/ldap.php. |
40 | |
41 | You don't have to change any configuration vars in |
42 | backend/ldap.php - instead, create an $cpw_ldap array in |
43 | config.php containing the variable you want to override. |
44 | |
e597520d |
45 | See more information in "About LDAP backend" chapter. |
02c81de4 |
46 | |
4165198d |
47 | - mysql |
48 | |
49 | Default settings are supplied in backends/mysql.php. |
50 | |
51 | You do not have to change any configuration vars in |
76063016 |
52 | backend/mysql.php - instead, create an $cpw_mysql array in |
53 | config.php containing the variable you want to override, |
54 | for example: |
4165198d |
55 | |
56 | To override the server name ($mysql_server), you would add |
76063016 |
57 | $cpw_mysql['server'] = 'remote_servername'; |
4165198d |
58 | to config.php. |
59 | |
e597520d |
60 | See more information in "About MySQL backend" chapter. |
27663afe |
61 | |
a391f3af |
62 | - merak |
27663afe |
63 | |
a391f3af |
64 | Default settings are supplied in backends/merak.php. |
27663afe |
65 | |
76063016 |
66 | Site configuration is controlled in config.php $cpw_merak |
67 | array. You can use 'url','selfpage' and 'action' array |
68 | keys to override default values. |
69 | |
70 | * 'url' |
71 | override sets address of merak interface. URL is used |
72 | by webserver's libraries. If it points at localhost, |
73 | plugin tries to connect to administrative interface on |
e597520d |
74 | same machine that hosts SquirrelMail scripts. |
76063016 |
75 | Defaults to 'http://localhost:32000/'. |
76 | |
77 | * 'selfpage' |
78 | override sets page that is used to change password. |
79 | Defaults to 'self.html'. |
80 | |
81 | * 'action' |
82 | override sets action that is used during password change. |
83 | Defaults to 'self_edit'. |
84 | |
85 | For example: |
86 | $cpw_merak['url']='http://example.com:32000'; |
87 | |
e597520d |
88 | - peardb |
89 | |
90 | Default settings are supplied in backends/peardb.php. |
91 | |
92 | Site configuration is controlled in config.php $cpw_peardb |
93 | array. Used configuration overrides: |
94 | * 'dsn' - (required) DSN used for connection to database. |
95 | See PHP Pear DB manual. |
96 | * 'connect_opts' - (optional) Pear DB connection options. |
97 | See PHP Pear DB manual. |
98 | * 'table' - (required) table that stores user information. |
99 | * 'uid_field' - (optional) field that stores username. |
100 | Defaults to 'userid'. |
101 | * 'domain_field' - (optional) field that stores domain |
102 | information. Used for setups that split username into |
103 | user and domain parts. Option is ignored if set to empty |
104 | string. Defaults to empty string. |
105 | * 'password_field' - (optional) field that stores password. |
106 | Defaults to 'password'. |
107 | * 'crypted_passwd' - (optional) boolean variable that is |
108 | used to switch between plaintext and encoded passwords. |
109 | If variable is set to false, backend works with plain |
110 | text passwords. If variable is set to true, backend |
111 | tries to detect crypto used in password and uses |
112 | detected crypto. Backend defaults to plain text |
113 | passwords. |
114 | * 'debug' - (optional) boolean variable that is used to control |
115 | display of debugging information. If set to true, backend |
116 | might display more information about connection errors. |
117 | Debug information can contain SQL connection options and |
118 | password information. Don't enable it on production system. |
119 | Backend disables display of debug information by default. |
120 | |
121 | Supported password schemas: |
122 | * plaintext - passwords are stored as clear text. |
123 | * crypt - passwords use system crypt libraries. Backend should be |
124 | able to use standard DES, extended DES, MD5 crypt and blowfish |
125 | algorithms, if system libraries support them. {crypt} prefix |
126 | is optional. |
127 | * plain-md5 - passwords are hashed with MD5 and use {plain-md5} |
128 | prefix. |
129 | * digest-md5 - hash stores MD5 hash of username:domain:password |
130 | string and is prefixed with {digest-md5} string. |
131 | |
132 | Tested configurations: |
133 | * Dovecot 0.99.14 with mysql authentication module. |
27663afe |
134 | |
a391f3af |
135 | - poppassd |
136 | |
137 | Default settings are supplied in backends/poppassd.php. |
138 | |
76063016 |
139 | Site configuration is controlled in config.php $cpw_poppassd |
140 | array. You can use 'server' array key to override address |
e597520d |
141 | of poppassd server. Backend uses address of IMAP server, if |
142 | variable is set to empty string. It uses address of IMAP |
76063016 |
143 | server by default. |
144 | |
145 | For example: |
146 | $cpw_poppassd['server'] = 'remote_servername'; |
a391f3af |
147 | |
e597520d |
148 | Available poppass servers: |
7bdb9b31 |
149 | * Qualcomm qpopper's poppassd - |
150 | http://www.eudora.com/products/unsupported/qpopper/index.html |
151 | original implementation of poppass protocol |
152 | |
153 | * poppassd-seti - http://echelon.pl/pubs/poppassd.html |
e597520d |
154 | poppass server with shadow password and PAM support |
7bdb9b31 |
155 | |
156 | * courierpassd - http://www.arda.homeunix.net/store/ |
e597520d |
157 | poppass server used with courier authentication system. |
7bdb9b31 |
158 | |
159 | * ldap poppassd - http://works.agni.com/ldap-poppassd.html |
160 | poppass server for LDAP |
161 | |
162 | * yppoppassd - http://cns.georgetown.edu/~ric/software/yppoppassd/ |
163 | poppass server for NIS/YP |
164 | |
165 | * kpoppassd - http://kpoppassd.sourceforge.net/ |
166 | poppass server for Kerberos |
167 | |
168 | * Mercury32 poppassd - http://www.pmail.com/ |
e597520d |
169 | poppass server that is part of Mercury Mail Transport |
170 | System. |
7bdb9b31 |
171 | |
e597520d |
172 | * FreeBSD includes two poppass servers in ports collection. |
7bdb9b31 |
173 | http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppassd |
174 | http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppwd |
e597520d |
175 | |
176 | |
a391f3af |
177 | - vmailmgrd |
178 | |
179 | Default settings are supplied in backends/vmailmgrd.php. |
180 | |
76063016 |
181 | Site configuration is controlled in config.php $cpw_vmailmgrd |
a391f3af |
182 | array. Backend uses 'vmail_inc_path', 'vm_tcphost', |
76063016 |
183 | 'vm_tcphost_port' and '8bitpw' array keys. |
a391f3af |
184 | |
185 | 'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets |
186 | vmailmgrd tcp service ip address or dns name. Plugin uses |
187 | vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets |
188 | port of vmailmrgd service. Plugin uses port 322, if it is |
76063016 |
189 | not set. '8bitpw' controls use of 8bit passwords. If it |
190 | is not set, interface does not allow new passwords with |
191 | 8bit symbols. |
a391f3af |
192 | |
76063016 |
193 | $cpw_vmailmgrd['vmail_inc_path'] setting is required. |
a391f3af |
194 | |
797d7708 |
195 | Tested configurations: |
196 | - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap |
197 | with vmailmgr authentication module. |
198 | |
02c81de4 |
199 | |
a391f3af |
200 | AUTHORS: |
e597520d |
201 | ldap, peardb and - Tomas Kuliavas <tokul@users.sourceforge.net> |
202 | vmailmgrd backends used code from phpldapadmin and squirrelmail |
02c81de4 |
203 | ldapquery plugin. |
a391f3af |
204 | merak backend - Edwin van Elk <Edwin@eve-software.com> |
205 | mysql backend - Thijs Kinkhorst <kink@squirrelmail.org> |
206 | poppassd backend - Seth Randall <sethr@missoulafcu.org> |
e597520d |
207 | |
27663afe |
208 | |
02c81de4 |
209 | ------------------ |
210 | ABOUT LDAP BACKEND |
211 | ------------------ |
212 | List of supported overrides |
213 | * 'server' |
e597520d |
214 | overrides address of LDAP server. use any syntax that is supported |
215 | by your PHP LDAP extension. Defaults to address of IMAP server. |
02c81de4 |
216 | |
217 | * 'port' |
e597520d |
218 | overrides port of LDAP server. Defaults to 389. |
02c81de4 |
219 | |
220 | * 'basedn' |
e597520d |
221 | (required) LDAP BaseDN used for binding to LDAP server. If set to |
222 | empty string, it blocks use of backend. Defaults to empty string. |
02c81de4 |
223 | |
224 | * 'connect_opts' |
ffa25c5c |
225 | controls LDAP_OPT_* settings that are set with ldap_set_option() |
226 | function. See available options at http://www.php.net/ldap-set-option. |
227 | LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts'] |
228 | overrides. No connection options are enabled by default. |
229 | |
e597520d |
230 | You can use this option only when your PHP LDAP extension supports |
ffa25c5c |
231 | ldap_set_option() function. |
02c81de4 |
232 | |
233 | * 'use_tls' |
e597520d |
234 | enables or disables use of TLS in LDAP connection. Requires PHP |
235 | 4.2+, PHP LDAP extension with SSL support and PROTOCOL_VERSION => 3 |
236 | setting in $cpw_ldap_connect_opts. Backend does not enable TLS by |
237 | default. |
02c81de4 |
238 | |
239 | * 'binddn' |
e597520d |
240 | unprivileged BindDN. should be able to search LDAP directory and |
02c81de4 |
241 | find DN used by user. Uses anonymous bind, if set to empty string. |
e597520d |
242 | You should not use DN with write access to LDAP directory here. |
02c81de4 |
243 | Defaults to anonymous bind. |
244 | |
245 | * 'bindpw' |
246 | password used for unprivileged bind |
247 | |
248 | * 'admindn' |
249 | bind DN that should be able to change password. |
250 | WARNING: usually user has enough privileges to change own password. |
e597520d |
251 | If you leave default value, plugin will try to connect with DN that |
02c81de4 |
252 | is detected in $cpw_ldap_username_attr=$username search and current |
253 | user password will be used for authentication. |
254 | |
255 | * 'adminpw' |
256 | password for binding with 'admindn' |
257 | |
258 | * 'userid_attr' |
e597520d |
259 | LDAP attribute that stores username. Defaults to 'uid' |
02c81de4 |
260 | |
261 | * 'default_crypto' |
262 | crypto that is used to encode new password. If set to empty string, |
263 | system tries to keep same encoding/hashing algorithm. Currently |
264 | backend supports: |
e597520d |
265 | - MD4 - used name 'md4'. Implemented in PHP Mhash extension functions. |
266 | - MD5 - used name 'md5'. Implemented in standard PHP functions. |
267 | - SMD5 - used name 'smd5'. Implemented in PHP Mhash extension functions. |
2b2e606c |
268 | Minimal php version = 4.0.4. |
e597520d |
269 | - RIPEMD-160 - used name 'rmd160'. Implemented in PHP Mhash extension functions. |
270 | - SHA - used name 'sha'. Implemented in PHP Mhash extension functions |
271 | and PHP 4.3.0+ sha1() function. Mhash extension is used only when |
2b2e606c |
272 | sha1() function is unavailable. |
e597520d |
273 | - SSHA - used name 'ssha'. Implemented in PHP Mhash extension functions. |
274 | Minimal PHP version = 4.0.4. |
275 | - MD5 crypt - used name 'md5crypt'. Uses PHP crypt function. Depends on |
276 | MD5 support in system crypt libraries. Should work on Linux glibc2 systems |
277 | and BSD systems. |
278 | - blowfish crypt - used name 'blowfish'. Uses PHP crypt function. Depends on |
279 | blowfish support in system crypt libraries. Should work on BSD systems. |
2b2e606c |
280 | Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) |
e597520d |
281 | - extended DES crypt - used name 'extcrypt'. Uses PHP crypt function. Depends on |
282 | extended DES support in system crypt libraries. Should work on BSD systems. |
2b2e606c |
283 | Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) |
e597520d |
284 | - standard DES crypt - used name 'crypt'. Uses PHP crypt function. Depends on |
285 | standard DES support in system crypt libraries. Should work on libc systems |
286 | and BSD systems. |
2b2e606c |
287 | - plain text passwords - used name 'plaintext'. |
02c81de4 |
288 | |
289 | If you use admindn, plugin should support all encryption/hashing |
e597520d |
290 | algorithms used in your LDAP server. |
02c81de4 |
291 | |
292 | WARNINGS: |
e597520d |
293 | * don't enforce any crypto that is not supported by LDAP server, if admindn |
797d7708 |
294 | override is not used in backend configuration. |
02c81de4 |
295 | * don't enforce extcrypt, md5crypt or blowfish, if they are not supported |
e597520d |
296 | by LDAP server and web server crypt libraries. |
02c81de4 |
297 | |
298 | Safest setting options: |
e597520d |
299 | * If web server and LDAP server is on same OS, make sure that Mhash |
300 | extension is present in PHP. |
301 | * If web server and LDAP server is on same OS and Mhash extension is |
302 | not present, enforce MD5 passwords or any crypt password algorithm |
303 | supported by your OS. Remember that standard DES crypt is limited |
304 | to eight symbols. Don't use admindn override, if LDAP server |
305 | supports MD4, RIPEMD-160, SHA, SSHA or SMD5. |
306 | * If crypt libraries differ on web server and LDAP server - |
307 | enforce MD5 passwords or any crypt password algorithm supported by |
308 | web server and LDAP server. Don't use admindn override, if LDAP |
309 | server supports MD4, RIPEMD-160, SHA, SSHA or SMD5 and Mhash extension |
797d7708 |
310 | is not present. |
02c81de4 |
311 | |
2b2e606c |
312 | Configuration example: |
ffcc6bc9 |
313 | $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn |
02c81de4 |
314 | $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3; // forces v3 bind protocol |
315 | |
797d7708 |
316 | Tested configurations: |
317 | - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap |
e597520d |
318 | v.3.0.8 using qmail-ldap auth-imap authentication. NS-MTA-MD5 crypto is not |
319 | implemented in backend. Crypted passwords need {crypt} prefix. |
797d7708 |
320 | |
76063016 |
321 | ------------------- |
322 | ABOUT MYSQL BACKEND |
323 | ------------_------ |
324 | List of supported overrides: |
325 | * 'server' |
326 | address of MySQL server. Defaults to localhost. |
327 | |
328 | * 'database' |
329 | database that stores user information. Defaults to 'email'. |
330 | |
331 | * 'table' |
332 | database table that stores user information. Defaults to 'users'. |
333 | |
334 | * 'userid_field' |
335 | field that stores user's ID. Defaults to 'id'. |
336 | |
337 | * 'password_field' |
338 | field that stores password. Defaults to 'password'. |
339 | |
340 | * 'manager_id' |
341 | username that is used to log into MySQL with (must have rights). |
342 | Defaults to 'email_admin'. |
343 | |
344 | * 'manager_pw' |
345 | password that is used to log into MySQL. |
346 | |
347 | * 'saslcrypt' |
348 | boolean value that controls use of SASL (MySQL) crypt in passwords. |
349 | It is not enabled by default. |
350 | |
351 | * 'unixcrypt' |
352 | boolean value that controls use of unix crypt() in passwords. |
353 | Setting is ignored, if saslcrypt is enabled. It is not enabled |
354 | by default. |
355 | |
356 | If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext |
357 | passwords. |
02c81de4 |
358 | |
27663afe |
359 | $Id$ |