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. |
21 | - peardb backend needs PHP Pear DB libraries and PHP extension that |
22 | is used to connect to database. |
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: |
149 | * Qualcomm qpopper's poppassd |
150 | * poppassd-seti |
151 | poppass server with shadow password and PAM support |
152 | * courier poppassd |
153 | poppass server used with courier authentication system. |
154 | * ldap poppassd |
155 | * nis/yp poppassd |
156 | * Mercury32 poppassd - http://www.pmail.com |
157 | poppass server that is part of Mercury Mail Transport |
158 | System. |
159 | * FreeBSD includes two poppass servers in ports collection. |
160 | |
161 | |
a391f3af |
162 | - vmailmgrd |
163 | |
164 | Default settings are supplied in backends/vmailmgrd.php. |
165 | |
76063016 |
166 | Site configuration is controlled in config.php $cpw_vmailmgrd |
a391f3af |
167 | array. Backend uses 'vmail_inc_path', 'vm_tcphost', |
76063016 |
168 | 'vm_tcphost_port' and '8bitpw' array keys. |
a391f3af |
169 | |
170 | 'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets |
171 | vmailmgrd tcp service ip address or dns name. Plugin uses |
172 | vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets |
173 | port of vmailmrgd service. Plugin uses port 322, if it is |
76063016 |
174 | not set. '8bitpw' controls use of 8bit passwords. If it |
175 | is not set, interface does not allow new passwords with |
176 | 8bit symbols. |
a391f3af |
177 | |
76063016 |
178 | $cpw_vmailmgrd['vmail_inc_path'] setting is required. |
a391f3af |
179 | |
797d7708 |
180 | Tested configurations: |
181 | - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap |
182 | with vmailmgr authentication module. |
183 | |
02c81de4 |
184 | |
a391f3af |
185 | AUTHORS: |
e597520d |
186 | ldap, peardb and - Tomas Kuliavas <tokul@users.sourceforge.net> |
187 | vmailmgrd backends used code from phpldapadmin and squirrelmail |
02c81de4 |
188 | ldapquery plugin. |
a391f3af |
189 | merak backend - Edwin van Elk <Edwin@eve-software.com> |
190 | mysql backend - Thijs Kinkhorst <kink@squirrelmail.org> |
191 | poppassd backend - Seth Randall <sethr@missoulafcu.org> |
e597520d |
192 | |
27663afe |
193 | |
02c81de4 |
194 | ------------------ |
195 | ABOUT LDAP BACKEND |
196 | ------------------ |
197 | List of supported overrides |
198 | * 'server' |
e597520d |
199 | overrides address of LDAP server. use any syntax that is supported |
200 | by your PHP LDAP extension. Defaults to address of IMAP server. |
02c81de4 |
201 | |
202 | * 'port' |
e597520d |
203 | overrides port of LDAP server. Defaults to 389. |
02c81de4 |
204 | |
205 | * 'basedn' |
e597520d |
206 | (required) LDAP BaseDN used for binding to LDAP server. If set to |
207 | empty string, it blocks use of backend. Defaults to empty string. |
02c81de4 |
208 | |
209 | * 'connect_opts' |
ffa25c5c |
210 | controls LDAP_OPT_* settings that are set with ldap_set_option() |
211 | function. See available options at http://www.php.net/ldap-set-option. |
212 | LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts'] |
213 | overrides. No connection options are enabled by default. |
214 | |
e597520d |
215 | You can use this option only when your PHP LDAP extension supports |
ffa25c5c |
216 | ldap_set_option() function. |
02c81de4 |
217 | |
218 | * 'use_tls' |
e597520d |
219 | enables or disables use of TLS in LDAP connection. Requires PHP |
220 | 4.2+, PHP LDAP extension with SSL support and PROTOCOL_VERSION => 3 |
221 | setting in $cpw_ldap_connect_opts. Backend does not enable TLS by |
222 | default. |
02c81de4 |
223 | |
224 | * 'binddn' |
e597520d |
225 | unprivileged BindDN. should be able to search LDAP directory and |
02c81de4 |
226 | find DN used by user. Uses anonymous bind, if set to empty string. |
e597520d |
227 | You should not use DN with write access to LDAP directory here. |
02c81de4 |
228 | Defaults to anonymous bind. |
229 | |
230 | * 'bindpw' |
231 | password used for unprivileged bind |
232 | |
233 | * 'admindn' |
234 | bind DN that should be able to change password. |
235 | WARNING: usually user has enough privileges to change own password. |
e597520d |
236 | If you leave default value, plugin will try to connect with DN that |
02c81de4 |
237 | is detected in $cpw_ldap_username_attr=$username search and current |
238 | user password will be used for authentication. |
239 | |
240 | * 'adminpw' |
241 | password for binding with 'admindn' |
242 | |
243 | * 'userid_attr' |
e597520d |
244 | LDAP attribute that stores username. Defaults to 'uid' |
02c81de4 |
245 | |
246 | * 'default_crypto' |
247 | crypto that is used to encode new password. If set to empty string, |
248 | system tries to keep same encoding/hashing algorithm. Currently |
249 | backend supports: |
e597520d |
250 | - MD4 - used name 'md4'. Implemented in PHP Mhash extension functions. |
251 | - MD5 - used name 'md5'. Implemented in standard PHP functions. |
252 | - SMD5 - used name 'smd5'. Implemented in PHP Mhash extension functions. |
2b2e606c |
253 | Minimal php version = 4.0.4. |
e597520d |
254 | - RIPEMD-160 - used name 'rmd160'. Implemented in PHP Mhash extension functions. |
255 | - SHA - used name 'sha'. Implemented in PHP Mhash extension functions |
256 | and PHP 4.3.0+ sha1() function. Mhash extension is used only when |
2b2e606c |
257 | sha1() function is unavailable. |
e597520d |
258 | - SSHA - used name 'ssha'. Implemented in PHP Mhash extension functions. |
259 | Minimal PHP version = 4.0.4. |
260 | - MD5 crypt - used name 'md5crypt'. Uses PHP crypt function. Depends on |
261 | MD5 support in system crypt libraries. Should work on Linux glibc2 systems |
262 | and BSD systems. |
263 | - blowfish crypt - used name 'blowfish'. Uses PHP crypt function. Depends on |
264 | blowfish support in system crypt libraries. Should work on BSD systems. |
2b2e606c |
265 | Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) |
e597520d |
266 | - extended DES crypt - used name 'extcrypt'. Uses PHP crypt function. Depends on |
267 | extended DES support in system crypt libraries. Should work on BSD systems. |
2b2e606c |
268 | Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) |
e597520d |
269 | - standard DES crypt - used name 'crypt'. Uses PHP crypt function. Depends on |
270 | standard DES support in system crypt libraries. Should work on libc systems |
271 | and BSD systems. |
2b2e606c |
272 | - plain text passwords - used name 'plaintext'. |
02c81de4 |
273 | |
274 | If you use admindn, plugin should support all encryption/hashing |
e597520d |
275 | algorithms used in your LDAP server. |
02c81de4 |
276 | |
277 | WARNINGS: |
e597520d |
278 | * don't enforce any crypto that is not supported by LDAP server, if admindn |
797d7708 |
279 | override is not used in backend configuration. |
02c81de4 |
280 | * don't enforce extcrypt, md5crypt or blowfish, if they are not supported |
e597520d |
281 | by LDAP server and web server crypt libraries. |
02c81de4 |
282 | |
283 | Safest setting options: |
e597520d |
284 | * If web server and LDAP server is on same OS, make sure that Mhash |
285 | extension is present in PHP. |
286 | * If web server and LDAP server is on same OS and Mhash extension is |
287 | not present, enforce MD5 passwords or any crypt password algorithm |
288 | supported by your OS. Remember that standard DES crypt is limited |
289 | to eight symbols. Don't use admindn override, if LDAP server |
290 | supports MD4, RIPEMD-160, SHA, SSHA or SMD5. |
291 | * If crypt libraries differ on web server and LDAP server - |
292 | enforce MD5 passwords or any crypt password algorithm supported by |
293 | web server and LDAP server. Don't use admindn override, if LDAP |
294 | server supports MD4, RIPEMD-160, SHA, SSHA or SMD5 and Mhash extension |
797d7708 |
295 | is not present. |
02c81de4 |
296 | |
2b2e606c |
297 | Configuration example: |
ffcc6bc9 |
298 | $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn |
02c81de4 |
299 | $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3; // forces v3 bind protocol |
300 | |
797d7708 |
301 | Tested configurations: |
302 | - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap |
e597520d |
303 | v.3.0.8 using qmail-ldap auth-imap authentication. NS-MTA-MD5 crypto is not |
304 | implemented in backend. Crypted passwords need {crypt} prefix. |
797d7708 |
305 | |
76063016 |
306 | ------------------- |
307 | ABOUT MYSQL BACKEND |
308 | ------------_------ |
309 | List of supported overrides: |
310 | * 'server' |
311 | address of MySQL server. Defaults to localhost. |
312 | |
313 | * 'database' |
314 | database that stores user information. Defaults to 'email'. |
315 | |
316 | * 'table' |
317 | database table that stores user information. Defaults to 'users'. |
318 | |
319 | * 'userid_field' |
320 | field that stores user's ID. Defaults to 'id'. |
321 | |
322 | * 'password_field' |
323 | field that stores password. Defaults to 'password'. |
324 | |
325 | * 'manager_id' |
326 | username that is used to log into MySQL with (must have rights). |
327 | Defaults to 'email_admin'. |
328 | |
329 | * 'manager_pw' |
330 | password that is used to log into MySQL. |
331 | |
332 | * 'saslcrypt' |
333 | boolean value that controls use of SASL (MySQL) crypt in passwords. |
334 | It is not enabled by default. |
335 | |
336 | * 'unixcrypt' |
337 | boolean value that controls use of unix crypt() in passwords. |
338 | Setting is ignored, if saslcrypt is enabled. It is not enabled |
339 | by default. |
340 | |
341 | If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext |
342 | passwords. |
02c81de4 |
343 | |
27663afe |
344 | $Id$ |