| 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 | |
| 12 | REQUIREMENTS: |
| 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 |
| 24 | used by IMAP server. |
| 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. |
| 28 | |
| 29 | CONFIGURATION |
| 30 | Edit the file config.php to set the backend you want to use. |
| 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. |
| 35 | |
| 36 | BACKENDS |
| 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 | |
| 45 | See more information in "About LDAP backend" chapter. |
| 46 | |
| 47 | - mysql |
| 48 | |
| 49 | Default settings are supplied in backends/mysql.php. |
| 50 | |
| 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, |
| 54 | for example: |
| 55 | |
| 56 | To override the server name ($mysql_server), you would add |
| 57 | $cpw_mysql['server'] = 'remote_servername'; |
| 58 | to config.php. |
| 59 | |
| 60 | See more information in "About MySQL backend" chapter. |
| 61 | |
| 62 | - merak |
| 63 | |
| 64 | Default settings are supplied in backends/merak.php. |
| 65 | |
| 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 |
| 74 | same machine that hosts SquirrelMail scripts. |
| 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 | |
| 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. |
| 134 | |
| 135 | - poppassd |
| 136 | |
| 137 | Default settings are supplied in backends/poppassd.php. |
| 138 | |
| 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 |
| 143 | server by default. |
| 144 | |
| 145 | For example: |
| 146 | $cpw_poppassd['server'] = 'remote_servername'; |
| 147 | |
| 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 |
| 152 | |
| 153 | * poppassd-seti - http://echelon.pl/pubs/poppassd.html |
| 154 | poppass server with shadow password and PAM support |
| 155 | |
| 156 | * courierpassd - http://www.arda.homeunix.net/store/ |
| 157 | poppass server used with courier authentication system. |
| 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/ |
| 169 | poppass server that is part of Mercury Mail Transport |
| 170 | System. |
| 171 | |
| 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 |
| 175 | |
| 176 | |
| 177 | - vmailmgrd |
| 178 | |
| 179 | Default settings are supplied in backends/vmailmgrd.php. |
| 180 | |
| 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. |
| 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 |
| 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. |
| 192 | |
| 193 | $cpw_vmailmgrd['vmail_inc_path'] setting is required. |
| 194 | |
| 195 | Tested configurations: |
| 196 | - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap |
| 197 | with vmailmgr authentication module. |
| 198 | |
| 199 | |
| 200 | AUTHORS: |
| 201 | ldap, peardb and - Tomas Kuliavas <tokul@users.sourceforge.net> |
| 202 | vmailmgrd backends used code from phpldapadmin and squirrelmail |
| 203 | ldapquery plugin. |
| 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> |
| 207 | |
| 208 | |
| 209 | ------------------ |
| 210 | ABOUT LDAP BACKEND |
| 211 | ------------------ |
| 212 | List of supported overrides |
| 213 | * 'server' |
| 214 | overrides address of LDAP server. use any syntax that is supported |
| 215 | by your PHP LDAP extension. Defaults to address of IMAP server. |
| 216 | |
| 217 | * 'port' |
| 218 | overrides port of LDAP server. Defaults to 389. |
| 219 | |
| 220 | * 'basedn' |
| 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. |
| 223 | |
| 224 | * 'connect_opts' |
| 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 | |
| 230 | You can use this option only when your PHP LDAP extension supports |
| 231 | ldap_set_option() function. |
| 232 | |
| 233 | * 'use_tls' |
| 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. |
| 238 | |
| 239 | * 'binddn' |
| 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. |
| 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. |
| 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. |
| 254 | |
| 255 | * 'adminpw' |
| 256 | password for binding with 'admindn' |
| 257 | |
| 258 | * 'userid_attr' |
| 259 | LDAP attribute that stores username. Defaults to 'uid' |
| 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: |
| 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 |
| 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. |
| 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 |
| 286 | and BSD systems. |
| 287 | - plain text passwords - used name 'plaintext'. |
| 288 | |
| 289 | If you use admindn, plugin should support all encryption/hashing |
| 290 | algorithms used in your LDAP server. |
| 291 | |
| 292 | WARNINGS: |
| 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. |
| 297 | |
| 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 |
| 310 | is not present. |
| 311 | |
| 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 |
| 315 | |
| 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. |
| 320 | |
| 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. |
| 358 | |
| 359 | $Id$ |