Fix for security token missing in newmail plugin (#2919418).
[squirrelmail.git] / plugins / change_password / README
CommitLineData
27663afe 1Master Change Password plugin
2-----------------------------
3
4WHAT'S THIS?
5This plugin is a general framework for enabling the user to
6change his/her password. It allows for different backend
7to perform this task on different systems.
8
9STATUS
10Development
11
fe90e5e4 12REQUIREMENTS:
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.
8f16b6ce 19- mysql backend needs PHP MySQL extension and PHP 4.3 or later.
e597520d 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 29CONFIGURATION
30Edit the file config.php to set the backend you want to use.
76063016 31
32Backends can use special arrays that override default values set
33in backend/<yourbackend>.php. Check description of backend that
34you use.
27663afe 35
36BACKENDS
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 200AUTHORS:
e597520d 201ldap, peardb and - Tomas Kuliavas <tokul@users.sourceforge.net>
202vmailmgrd backends used code from phpldapadmin and squirrelmail
02c81de4 203 ldapquery plugin.
a391f3af 204merak backend - Edwin van Elk <Edwin@eve-software.com>
205mysql backend - Thijs Kinkhorst <kink@squirrelmail.org>
206poppassd backend - Seth Randall <sethr@missoulafcu.org>
e597520d 207
27663afe 208
02c81de4 209------------------
210ABOUT 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-------------------
322ABOUT 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
356If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext
357passwords.
02c81de4 358
27663afe 359$Id$