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/<yourbackend>.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 <tokul@users.sourceforge.net>
vmailmgrd backends used code from phpldapadmin and squirrelmail
ldapquery plugin.
merak backend - Edwin van Elk <Edwin@eve-software.com>
mysql backend - Thijs Kinkhorst <kink@squirrelmail.org>
poppassd backend - Seth Randall <sethr@missoulafcu.org>
------------------
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$
