1 Master Change Password plugin
2 -----------------------------
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.
13 - SquirrelMail 1.4.3 or later. (plugin is included in SquirrelMail
14 1.5.0 and later versions).
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 (v.1.6.0 or newer) and
22 PHP extension that is used to connect to database.
23 - poppassd backend needs poppassd server that supports authentication
25 - vmailmgrd backend needs vmailmgr PHP library (vmail.inc) and
26 vmailmgrd service running on tcp port or unix socket. It also
27 requires SquirrelMail 1.4.4 or 1.5.1.
30 Edit the file config.php to set the backend you want to use.
32 Backends can use special arrays that override default values set
33 in backend/<yourbackend>.php. Check description of backend that
39 Default settings are supplied in backends/ldap.php.
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.
45 See more information in "About LDAP backend" chapter.
49 Default settings are supplied in backends/mysql.php.
51 You do not have to change any configuration vars in
52 backend/mysql.php - instead, create an $cpw_mysql array in
53 config.php containing the variable you want to override,
56 To override the server name ($mysql_server), you would add
57 $cpw_mysql['server'] = 'remote_servername';
60 See more information in "About MySQL backend" chapter.
64 Default settings are supplied in backends/merak.php.
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.
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
74 same machine that hosts SquirrelMail scripts.
75 Defaults to 'http://localhost:32000/'.
78 override sets page that is used to change password.
79 Defaults to 'self.html'.
82 override sets action that is used during password change.
83 Defaults to 'self_edit'.
86 $cpw_merak['url']='http://example.com:32000';
90 Default settings are supplied in backends/peardb.php.
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
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.
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
127 * plain-md5 - passwords are hashed with MD5 and use {plain-md5}
129 * digest-md5 - hash stores MD5 hash of username:domain:password
130 string and is prefixed with {digest-md5} string.
132 Tested configurations:
133 * Dovecot 0.99.14 with mysql authentication module.
137 Default settings are supplied in backends/poppassd.php.
139 Site configuration is controlled in config.php $cpw_poppassd
140 array. You can use 'server' array key to override address
141 of poppassd server. Backend uses address of IMAP server, if
142 variable is set to empty string. It uses address of IMAP
146 $cpw_poppassd['server'] = 'remote_servername';
148 Available poppass servers:
149 * Qualcomm qpopper's poppassd -
150 http://www.eudora.com/products/unsupported/qpopper/index.html
151 original implementation of poppass protocol
153 * poppassd-seti - http://echelon.pl/pubs/poppassd.html
154 poppass server with shadow password and PAM support
156 * courierpassd - http://www.arda.homeunix.net/store/
157 poppass server used with courier authentication system.
159 * ldap poppassd - http://works.agni.com/ldap-poppassd.html
160 poppass server for LDAP
162 * yppoppassd - http://cns.georgetown.edu/~ric/software/yppoppassd/
163 poppass server for NIS/YP
165 * kpoppassd - http://kpoppassd.sourceforge.net/
166 poppass server for Kerberos
168 * Mercury32 poppassd - http://www.pmail.com/
169 poppass server that is part of Mercury Mail Transport
172 * FreeBSD includes two poppass servers in ports collection.
173 http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppassd
174 http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppwd
179 Default settings are supplied in backends/vmailmgrd.php.
181 Site configuration is controlled in config.php $cpw_vmailmgrd
182 array. Backend uses 'vmail_inc_path', 'vm_tcphost',
183 'vm_tcphost_port' and '8bitpw' array keys.
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
189 not set. '8bitpw' controls use of 8bit passwords. If it
190 is not set, interface does not allow new passwords with
193 $cpw_vmailmgrd['vmail_inc_path'] setting is required.
195 Tested configurations:
196 - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap
197 with vmailmgr authentication module.
201 ldap, peardb and - Tomas Kuliavas <tokul@users.sourceforge.net>
202 vmailmgrd backends used code from phpldapadmin and squirrelmail
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>
212 List of supported overrides
214 overrides address of LDAP server. use any syntax that is supported
215 by your PHP LDAP extension. Defaults to address of IMAP server.
218 overrides port of LDAP server. Defaults to 389.
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.
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.
230 You can use this option only when your PHP LDAP extension supports
231 ldap_set_option() function.
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
240 unprivileged BindDN. should be able to search LDAP directory and
241 find DN used by user. Uses anonymous bind, if set to empty string.
242 You should not use DN with write access to LDAP directory here.
243 Defaults to anonymous bind.
246 password used for unprivileged bind
249 bind DN that should be able to change password.
250 WARNING: usually user has enough privileges to change own password.
251 If you leave default value, plugin will try to connect with DN that
252 is detected in $cpw_ldap_username_attr=$username search and current
253 user password will be used for authentication.
256 password for binding with 'admindn'
259 LDAP attribute that stores username. Defaults to 'uid'
262 crypto that is used to encode new password. If set to empty string,
263 system tries to keep same encoding/hashing algorithm. Currently
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.
268 Minimal php version = 4.0.4.
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
272 sha1() function is unavailable.
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
278 - blowfish crypt - used name 'blowfish'. Uses PHP crypt function. Depends on
279 blowfish support in system crypt libraries. Should work on BSD systems.
280 Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
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.
283 Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
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
287 - plain text passwords - used name 'plaintext'.
289 If you use admindn, plugin should support all encryption/hashing
290 algorithms used in your LDAP server.
293 * don't enforce any crypto that is not supported by LDAP server, if admindn
294 override is not used in backend configuration.
295 * don't enforce extcrypt, md5crypt or blowfish, if they are not supported
296 by LDAP server and web server crypt libraries.
298 Safest setting options:
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
312 Configuration example:
313 $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn
314 $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3; // forces v3 bind protocol
316 Tested configurations:
317 - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap
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.
324 List of supported overrides:
326 address of MySQL server. Defaults to localhost.
329 database that stores user information. Defaults to 'email'.
332 database table that stores user information. Defaults to 'users'.
335 field that stores user's ID. Defaults to 'id'.
338 field that stores password. Defaults to 'password'.
341 username that is used to log into MySQL with (must have rights).
342 Defaults to 'email_admin'.
345 password that is used to log into MySQL.
348 boolean value that controls use of SASL (MySQL) crypt in passwords.
349 It is not enabled by default.
352 boolean value that controls use of unix crypt() in passwords.
353 Setting is ignored, if saslcrypt is enabled. It is not enabled
356 If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext