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 and PHP extension that
  22   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   * poppassd-seti
 151       poppass server with shadow password and PAM support
 152   * courier poppassd
 153       poppass server used with courier authentication system.
 154   * ldap poppassd
 155   * nis/yp poppassd
 156   * Mercury32 poppassd - http://www.pmail.com
 157       poppass server that is part of Mercury Mail Transport
 158       System.
 159   * FreeBSD includes two poppass servers in ports collection.
 160
 161
 162 - vmailmgrd
 163
 164   Default settings are supplied in backends/vmailmgrd.php.
 165
 166   Site configuration is controlled in config.php $cpw_vmailmgrd
 167   array. Backend uses 'vmail_inc_path', 'vm_tcphost',
 168   'vm_tcphost_port' and '8bitpw' array keys.
 169
 170   'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets
 171   vmailmgrd tcp service ip address or dns name. Plugin uses
 172   vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets
 173   port of vmailmrgd service. Plugin uses port 322, if it is
 174   not set. '8bitpw' controls use of 8bit passwords. If it
 175   is not set, interface does not allow new passwords with
 176   8bit symbols.
 177
 178   $cpw_vmailmgrd['vmail_inc_path'] setting is required.
 179
 180   Tested configurations:
 181   - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap
 182     with vmailmgr authentication module.
 183
 184
 185 AUTHORS:
 186 ldap, peardb and  - Tomas Kuliavas <tokul@users.sourceforge.net>
 187 vmailmgrd backends  used code from phpldapadmin and squirrelmail
 188                     ldapquery plugin.
 189 merak backend     - Edwin van Elk <Edwin@eve-software.com>
 190 mysql backend     - Thijs Kinkhorst <kink@squirrelmail.org>
 191 poppassd backend  - Seth Randall <sethr@missoulafcu.org>
 192
 193
 194 ------------------
 195 ABOUT LDAP BACKEND
 196 ------------------
 197   List of supported overrides
 198   * 'server'
 199     overrides address of LDAP server. use any syntax that is supported
 200     by your PHP LDAP extension. Defaults to address of IMAP server.
 201
 202   * 'port'
 203     overrides port of LDAP server. Defaults to 389.
 204
 205   * 'basedn'
 206     (required) LDAP BaseDN used for binding to LDAP server. If set to
 207     empty string, it blocks use of backend. Defaults to empty string.
 208
 209   * 'connect_opts'
 210     controls LDAP_OPT_* settings that are set with ldap_set_option()
 211     function. See available options at http://www.php.net/ldap-set-option.
 212     LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts']
 213     overrides. No connection options are enabled by default.
 214
 215     You can use this option only when your PHP LDAP extension supports
 216     ldap_set_option() function.
 217
 218   * 'use_tls'
 219     enables or disables use of TLS in LDAP connection. Requires PHP
 220     4.2+, PHP LDAP extension with SSL support and PROTOCOL_VERSION => 3
 221     setting in $cpw_ldap_connect_opts. Backend does not enable TLS by
 222     default.
 223
 224   * 'binddn'
 225     unprivileged BindDN. should be able to search LDAP directory and
 226     find DN used by user. Uses anonymous bind, if set to empty string.
 227     You should not use DN with write access to LDAP directory here.
 228     Defaults to anonymous bind.
 229
 230   * 'bindpw'
 231     password used for unprivileged bind
 232
 233   * 'admindn'
 234     bind DN that should be able to change password.
 235     WARNING: usually user has enough privileges to change own password.
 236     If you leave default value, plugin will try to connect with DN that
 237     is detected in $cpw_ldap_username_attr=$username search and current
 238     user password will be used for authentication.
 239
 240   * 'adminpw'
 241     password for binding with 'admindn'
 242
 243   * 'userid_attr'
 244     LDAP attribute that stores username. Defaults to 'uid'
 245
 246   * 'default_crypto'
 247     crypto that is used to encode new password. If set to empty string,
 248     system tries to keep same encoding/hashing algorithm. Currently
 249     backend supports:
 250     - MD4 - used name 'md4'. Implemented in PHP Mhash extension functions.
 251     - MD5 - used name 'md5'. Implemented in standard PHP functions.
 252     - SMD5 - used name 'smd5'. Implemented in PHP Mhash extension functions.
 253       Minimal php version = 4.0.4.
 254     - RIPEMD-160 - used name 'rmd160'. Implemented in PHP Mhash extension functions.
 255     - SHA - used name 'sha'. Implemented in PHP Mhash extension functions
 256       and PHP 4.3.0+ sha1() function. Mhash extension is used only when
 257       sha1() function is unavailable.
 258     - SSHA - used name 'ssha'. Implemented in PHP Mhash extension functions.
 259       Minimal PHP version = 4.0.4.
 260     - MD5 crypt - used name 'md5crypt'. Uses PHP crypt function. Depends on
 261       MD5 support in system crypt libraries. Should work on Linux glibc2 systems
 262       and BSD systems.
 263     - blowfish crypt - used name 'blowfish'. Uses PHP crypt function. Depends on
 264       blowfish support in system crypt libraries. Should work on BSD systems.
 265       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 266     - extended DES crypt - used name 'extcrypt'. Uses PHP crypt function. Depends on
 267       extended DES support in system crypt libraries. Should work on BSD systems.
 268       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 269     - standard DES crypt - used name 'crypt'. Uses PHP crypt function. Depends on
 270       standard DES support in system crypt libraries. Should work on libc systems
 271       and BSD systems.
 272     - plain text passwords - used name 'plaintext'.
 273
 274     If you use admindn, plugin should support all encryption/hashing
 275     algorithms used in your LDAP server.
 276
 277     WARNINGS:
 278     * don't enforce any crypto that is not supported by LDAP server, if admindn
 279       override is not used in backend configuration.
 280     * don't enforce extcrypt, md5crypt or blowfish, if they are not supported
 281       by LDAP server and web server crypt libraries.
 282
 283     Safest setting options:
 284     * If web server and LDAP server is on same OS, make sure that Mhash
 285       extension is present in PHP.
 286     * If web server and LDAP server is on same OS and Mhash extension is
 287       not present, enforce MD5 passwords or any crypt password algorithm
 288       supported by your OS. Remember that standard DES crypt is limited
 289       to eight symbols.  Don't use admindn override, if LDAP server
 290       supports MD4, RIPEMD-160, SHA, SSHA or SMD5.
 291     * If crypt libraries differ on web server and LDAP server -
 292       enforce MD5 passwords or any crypt password algorithm supported by
 293       web server and LDAP server. Don't use admindn override, if LDAP
 294       server supports MD4, RIPEMD-160, SHA, SSHA or SMD5 and Mhash extension
 295       is not present.
 296
 297   Configuration example:
 298   $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn
 299   $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3;   // forces v3 bind protocol
 300
 301   Tested configurations:
 302   - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap
 303     v.3.0.8 using qmail-ldap auth-imap authentication. NS-MTA-MD5 crypto is not
 304     implemented in backend. Crypted passwords need {crypt} prefix.
 305
 306 -------------------
 307 ABOUT MYSQL BACKEND
 308 ------------_------
 309   List of supported overrides:
 310   * 'server'
 311     address of MySQL server. Defaults to localhost.
 312
 313   * 'database'
 314     database that stores user information. Defaults to 'email'.
 315
 316   * 'table'
 317     database table that stores user information. Defaults to 'users'.
 318
 319   * 'userid_field'
 320     field that stores user's ID. Defaults to 'id'.
 321
 322   * 'password_field'
 323     field that stores password. Defaults to 'password'.
 324
 325   * 'manager_id'
 326     username that is used to log into MySQL with (must have rights).
 327     Defaults to 'email_admin'.
 328
 329   * 'manager_pw'
 330     password that is used to log into MySQL.
 331
 332   * 'saslcrypt'
 333     boolean value that controls use of SASL (MySQL) crypt in passwords.
 334     It is not enabled by default.
 335
 336   * 'unixcrypt'
 337     boolean value that controls use of unix crypt() in passwords.
 338     Setting is ignored, if saslcrypt is enabled. It is not enabled
 339     by default.
 340
 341 If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext
 342 passwords.
 343
 344 $Id$