Master Change Password plugin ----------------------------- WHAT'S THIS? This plugin is a general framework for enabling the user to change his/her password. It allows for different backend to perform this task on different systems. STATUS Development REQUIREMENTS: - SquirrelMail 1.4.3 or later. (plugin is included in SquirrelMail 1.5.0 and later versions). - ldap backend needs PHP LDAP extension. It might need PHP Mhash extension and system crypt libraries that support crypto used on LDAP server. It might need PHP LDAP extension with SSL support, if LDAP server requires it. - mysql backend needs PHP MySQL extension and PHP 4.3 or later. - merak backend needs PHP Curl extension. - peardb backend needs PHP Pear DB libraries (v.1.6.0 or newer) and PHP extension that is used to connect to database. - poppassd backend needs poppassd server that supports authentication used by IMAP server. - vmailmgrd backend needs vmailmgr PHP library (vmail.inc) and vmailmgrd service running on tcp port or unix socket. It also requires SquirrelMail 1.4.4 or 1.5.1. CONFIGURATION Edit the file config.php to set the backend you want to use. Backends can use special arrays that override default values set in backend/.php. Check description of backend that you use. BACKENDS - ldap Default settings are supplied in backends/ldap.php. You don't have to change any configuration vars in backend/ldap.php - instead, create an $cpw_ldap array in config.php containing the variable you want to override. See more information in "About LDAP backend" chapter. - mysql Default settings are supplied in backends/mysql.php. You do not have to change any configuration vars in backend/mysql.php - instead, create an $cpw_mysql array in config.php containing the variable you want to override, for example: To override the server name ($mysql_server), you would add $cpw_mysql['server'] = 'remote_servername'; to config.php. See more information in "About MySQL backend" chapter. - merak Default settings are supplied in backends/merak.php. Site configuration is controlled in config.php $cpw_merak array. You can use 'url','selfpage' and 'action' array keys to override default values. * 'url' override sets address of merak interface. URL is used by webserver's libraries. If it points at localhost, plugin tries to connect to administrative interface on same machine that hosts SquirrelMail scripts. Defaults to 'http://localhost:32000/'. * 'selfpage' override sets page that is used to change password. Defaults to 'self.html'. * 'action' override sets action that is used during password change. Defaults to 'self_edit'. For example: $cpw_merak['url']='http://example.com:32000'; - peardb Default settings are supplied in backends/peardb.php. Site configuration is controlled in config.php $cpw_peardb array. Used configuration overrides: * 'dsn' - (required) DSN used for connection to database. See PHP Pear DB manual. * 'connect_opts' - (optional) Pear DB connection options. See PHP Pear DB manual. * 'table' - (required) table that stores user information. * 'uid_field' - (optional) field that stores username. Defaults to 'userid'. * 'domain_field' - (optional) field that stores domain information. Used for setups that split username into user and domain parts. Option is ignored if set to empty string. Defaults to empty string. * 'password_field' - (optional) field that stores password. Defaults to 'password'. * 'crypted_passwd' - (optional) boolean variable that is used to switch between plaintext and encoded passwords. If variable is set to false, backend works with plain text passwords. If variable is set to true, backend tries to detect crypto used in password and uses detected crypto. Backend defaults to plain text passwords. * 'debug' - (optional) boolean variable that is used to control display of debugging information. If set to true, backend might display more information about connection errors. Debug information can contain SQL connection options and password information. Don't enable it on production system. Backend disables display of debug information by default. Supported password schemas: * plaintext - passwords are stored as clear text. * crypt - passwords use system crypt libraries. Backend should be able to use standard DES, extended DES, MD5 crypt and blowfish algorithms, if system libraries support them. {crypt} prefix is optional. * plain-md5 - passwords are hashed with MD5 and use {plain-md5} prefix. * digest-md5 - hash stores MD5 hash of username:domain:password string and is prefixed with {digest-md5} string. Tested configurations: * Dovecot 0.99.14 with mysql authentication module. - poppassd Default settings are supplied in backends/poppassd.php. Site configuration is controlled in config.php $cpw_poppassd array. You can use 'server' array key to override address of poppassd server. Backend uses address of IMAP server, if variable is set to empty string. It uses address of IMAP server by default. For example: $cpw_poppassd['server'] = 'remote_servername'; Available poppass servers: * Qualcomm qpopper's poppassd - http://www.eudora.com/products/unsupported/qpopper/index.html original implementation of poppass protocol * poppassd-seti - http://echelon.pl/pubs/poppassd.html poppass server with shadow password and PAM support * courierpassd - http://www.arda.homeunix.net/store/ poppass server used with courier authentication system. * ldap poppassd - http://works.agni.com/ldap-poppassd.html poppass server for LDAP * yppoppassd - http://cns.georgetown.edu/~ric/software/yppoppassd/ poppass server for NIS/YP * kpoppassd - http://kpoppassd.sourceforge.net/ poppass server for Kerberos * Mercury32 poppassd - http://www.pmail.com/ poppass server that is part of Mercury Mail Transport System. * FreeBSD includes two poppass servers in ports collection. http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppassd http://www.freebsd.org/cgi/cvsweb.cgi/ports/mail/poppwd - vmailmgrd Default settings are supplied in backends/vmailmgrd.php. Site configuration is controlled in config.php $cpw_vmailmgrd array. Backend uses 'vmail_inc_path', 'vm_tcphost', 'vm_tcphost_port' and '8bitpw' array keys. 'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets vmailmgrd tcp service ip address or dns name. Plugin uses vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets port of vmailmrgd service. Plugin uses port 322, if it is not set. '8bitpw' controls use of 8bit passwords. If it is not set, interface does not allow new passwords with 8bit symbols. $cpw_vmailmgrd['vmail_inc_path'] setting is required. Tested configurations: - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap with vmailmgr authentication module. AUTHORS: ldap, peardb and - Tomas Kuliavas vmailmgrd backends used code from phpldapadmin and squirrelmail ldapquery plugin. merak backend - Edwin van Elk mysql backend - Thijs Kinkhorst poppassd backend - Seth Randall ------------------ ABOUT LDAP BACKEND ------------------ List of supported overrides * 'server' overrides address of LDAP server. use any syntax that is supported by your PHP LDAP extension. Defaults to address of IMAP server. * 'port' overrides port of LDAP server. Defaults to 389. * 'basedn' (required) LDAP BaseDN used for binding to LDAP server. If set to empty string, it blocks use of backend. Defaults to empty string. * 'connect_opts' controls LDAP_OPT_* settings that are set with ldap_set_option() function. See available options at http://www.php.net/ldap-set-option. LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts'] overrides. No connection options are enabled by default. You can use this option only when your PHP LDAP extension supports ldap_set_option() function. * 'use_tls' enables or disables use of TLS in LDAP connection. Requires PHP 4.2+, PHP LDAP extension with SSL support and PROTOCOL_VERSION => 3 setting in $cpw_ldap_connect_opts. Backend does not enable TLS by default. * 'binddn' unprivileged BindDN. should be able to search LDAP directory and find DN used by user. Uses anonymous bind, if set to empty string. You should not use DN with write access to LDAP directory here. Defaults to anonymous bind. * 'bindpw' password used for unprivileged bind * 'admindn' bind DN that should be able to change password. WARNING: usually user has enough privileges to change own password. If you leave default value, plugin will try to connect with DN that is detected in $cpw_ldap_username_attr=$username search and current user password will be used for authentication. * 'adminpw' password for binding with 'admindn' * 'userid_attr' LDAP attribute that stores username. Defaults to 'uid' * 'default_crypto' crypto that is used to encode new password. If set to empty string, system tries to keep same encoding/hashing algorithm. Currently backend supports: - MD4 - used name 'md4'. Implemented in PHP Mhash extension functions. - MD5 - used name 'md5'. Implemented in standard PHP functions. - SMD5 - used name 'smd5'. Implemented in PHP Mhash extension functions. Minimal php version = 4.0.4. - RIPEMD-160 - used name 'rmd160'. Implemented in PHP Mhash extension functions. - SHA - used name 'sha'. Implemented in PHP Mhash extension functions and PHP 4.3.0+ sha1() function. Mhash extension is used only when sha1() function is unavailable. - SSHA - used name 'ssha'. Implemented in PHP Mhash extension functions. Minimal PHP version = 4.0.4. - MD5 crypt - used name 'md5crypt'. Uses PHP crypt function. Depends on MD5 support in system crypt libraries. Should work on Linux glibc2 systems and BSD systems. - blowfish crypt - used name 'blowfish'. Uses PHP crypt function. Depends on blowfish support in system crypt libraries. Should work on BSD systems. Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) - extended DES crypt - used name 'extcrypt'. Uses PHP crypt function. Depends on extended DES support in system crypt libraries. Should work on BSD systems. Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5) - standard DES crypt - used name 'crypt'. Uses PHP crypt function. Depends on standard DES support in system crypt libraries. Should work on libc systems and BSD systems. - plain text passwords - used name 'plaintext'. If you use admindn, plugin should support all encryption/hashing algorithms used in your LDAP server. WARNINGS: * don't enforce any crypto that is not supported by LDAP server, if admindn override is not used in backend configuration. * don't enforce extcrypt, md5crypt or blowfish, if they are not supported by LDAP server and web server crypt libraries. Safest setting options: * If web server and LDAP server is on same OS, make sure that Mhash extension is present in PHP. * If web server and LDAP server is on same OS and Mhash extension is not present, enforce MD5 passwords or any crypt password algorithm supported by your OS. Remember that standard DES crypt is limited to eight symbols. Don't use admindn override, if LDAP server supports MD4, RIPEMD-160, SHA, SSHA or SMD5. * If crypt libraries differ on web server and LDAP server - enforce MD5 passwords or any crypt password algorithm supported by web server and LDAP server. Don't use admindn override, if LDAP server supports MD4, RIPEMD-160, SHA, SSHA or SMD5 and Mhash extension is not present. Configuration example: $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3; // forces v3 bind protocol Tested configurations: - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap v.3.0.8 using qmail-ldap auth-imap authentication. NS-MTA-MD5 crypto is not implemented in backend. Crypted passwords need {crypt} prefix. ------------------- ABOUT MYSQL BACKEND ------------_------ List of supported overrides: * 'server' address of MySQL server. Defaults to localhost. * 'database' database that stores user information. Defaults to 'email'. * 'table' database table that stores user information. Defaults to 'users'. * 'userid_field' field that stores user's ID. Defaults to 'id'. * 'password_field' field that stores password. Defaults to 'password'. * 'manager_id' username that is used to log into MySQL with (must have rights). Defaults to 'email_admin'. * 'manager_pw' password that is used to log into MySQL. * 'saslcrypt' boolean value that controls use of SASL (MySQL) crypt in passwords. It is not enabled by default. * 'unixcrypt' boolean value that controls use of unix crypt() in passwords. Setting is ignored, if saslcrypt is enabled. It is not enabled by default. If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext passwords. $Id$