plugins/change_password/README

   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$