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 - poppass backend needs poppassd server that supports authentication
  22   used by imap server.
  23 - vmailmgrd backend needs vmailmgr php library (vmail.inc) and
  24   vmailmgrd service running on tcp port or unix socket. It also
  25   requires SquirrelMail 1.4.4 or 1.5.1.
  26
  27 CONFIGURATION
  28 Edit the file config.php to set the backend you want to use.
  29
  30 Backends can use special arrays that override default values set
  31 in backend/<yourbackend>.php. Check description of backend that
  32 you use.
  33
  34 BACKENDS
  35 - ldap
  36
  37   Default settings are supplied in backends/ldap.php.
  38
  39   You don't have to change any configuration vars in
  40   backend/ldap.php - instead, create an $cpw_ldap array in
  41   config.php containing the variable you want to override.
  42
  43   See more information in "About ldap backend" chapter.
  44
  45 - mysql
  46
  47   Default settings are supplied in backends/mysql.php.
  48
  49   You do not have to change any configuration vars in
  50   backend/mysql.php - instead, create an $cpw_mysql array in
  51   config.php containing the variable you want to override,
  52   for example:
  53
  54   To override the server name ($mysql_server), you would add
  55     $cpw_mysql['server'] = 'remote_servername';
  56   to config.php.
  57
  58   See more information in "About mysql backend" chapter.
  59
  60 - merak
  61
  62   Default settings are supplied in backends/merak.php.
  63
  64   Site configuration is controlled in config.php $cpw_merak
  65   array. You can use 'url','selfpage' and 'action' array
  66   keys to override default values.
  67
  68   * 'url'
  69     override sets address of merak interface. URL is used
  70     by webserver's libraries. If it points at localhost,
  71     plugin tries to connect to administrative interface on
  72     same machine that hosts squirrelmail scripts.
  73     Defaults to 'http://localhost:32000/'.
  74
  75   * 'selfpage'
  76     override sets page that is used to change password.
  77     Defaults to 'self.html'.
  78
  79   * 'action'
  80     override sets action that is used during password change.
  81     Defaults to 'self_edit'.
  82
  83   For example:
  84   $cpw_merak['url']='http://example.com:32000';
  85
  86
  87 - poppassd
  88
  89   Default settings are supplied in backends/poppassd.php.
  90
  91   Site configuration is controlled in config.php $cpw_poppassd
  92   array. You can use 'server' array key to override address
  93   of poppassd server. Backend uses address of imap server, if
  94   variable is set to empty string. It uses address of imap
  95   server by default.
  96
  97   For example:
  98   $cpw_poppassd['server'] = 'remote_servername';
  99
 100 - vmailmgrd
 101
 102   Default settings are supplied in backends/vmailmgrd.php.
 103
 104   Site configuration is controlled in config.php $cpw_vmailmgrd
 105   array. Backend uses 'vmail_inc_path', 'vm_tcphost',
 106   'vm_tcphost_port' and '8bitpw' array keys.
 107
 108   'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets
 109   vmailmgrd tcp service ip address or dns name. Plugin uses
 110   vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets
 111   port of vmailmrgd service. Plugin uses port 322, if it is
 112   not set. '8bitpw' controls use of 8bit passwords. If it
 113   is not set, interface does not allow new passwords with
 114   8bit symbols.
 115
 116   $cpw_vmailmgrd['vmail_inc_path'] setting is required.
 117
 118   Tested configurations:
 119   - Linux Debian Woody, vmailmgr 0.96.9, stock Woody's courier-imap
 120     with vmailmgr authentication module.
 121
 122
 123 AUTHORS:
 124 ldap backend      - Tomas Kuliavas <tokul@users.sourceforge.net>
 125                     used code from phpldapadmin and squirrelmail
 126                     ldapquery plugin.
 127 merak backend     - Edwin van Elk <Edwin@eve-software.com>
 128 mysql backend     - Thijs Kinkhorst <kink@squirrelmail.org>
 129 poppassd backend  - Seth Randall <sethr@missoulafcu.org>
 130 vmailmgrd backend - Tomas Kuliavas <tokul@users.sourceforge.net>
 131
 132 ------------------
 133 ABOUT LDAP BACKEND
 134 ------------------
 135   List of supported overrides
 136   * 'server'
 137     overrides address of ldap server. use any syntax that is supported
 138     by your php ldap extension. Defaults to address of imap server.
 139
 140   * 'port'
 141     overrides port of ldap server. Defaults to 389.
 142
 143   * 'basedn'
 144     (required) ldap basedn used for binding to ldap server. If set to
 145     empty string, blocks use of backend. Defaults to empty string.
 146
 147   * 'connect_opts'
 148     controls LDAP_OPT_* settings that are set with ldap_set_option()
 149     function. See available options at http://www.php.net/ldap-set-option.
 150     LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts']
 151     overrides. No connection options are enabled by default.
 152
 153     You can use this option only when your ldap extension supports
 154     ldap_set_option() function.
 155
 156   * 'use_tls'
 157     enables or disables use of tls in ldap connection. Requires php
 158     4.2+, php ldap extension with ssl support and PROTOCOL_VERSION => 3
 159     setting in $cpw_ldap_connect_opts. Does not enable tls by default.
 160
 161   * 'binddn'
 162     unprivileged binddn. should be able to search ldap directory and
 163     find DN used by user. Uses anonymous bind, if set to empty string.
 164     You should not use DN with write access to ldap directory here.
 165     Defaults to anonymous bind.
 166
 167   * 'bindpw'
 168     password used for unprivileged bind
 169
 170   * 'admindn'
 171     bind DN that should be able to change password.
 172     WARNING: usually user has enough privileges to change own password.
 173     If you leave default value, plugin will try to connect with dn that
 174     is detected in $cpw_ldap_username_attr=$username search and current
 175     user password will be used for authentication.
 176
 177   * 'adminpw'
 178     password for binding with 'admindn'
 179
 180   * 'userid_attr'
 181     ldap attribute that stores username. Defaults to 'uid'
 182
 183   * 'default_crypto'
 184     crypto that is used to encode new password. If set to empty string,
 185     system tries to keep same encoding/hashing algorithm. Currently
 186     backend supports:
 187     - md4 - used name 'md4'. Implemented in php mhash extension functions.
 188     - md5 - used name 'md5'. Implemented in standard php functions.
 189     - smd5 - used name 'smd5'. Implemented in php mhash extension functions.
 190       Minimal php version = 4.0.4.
 191     - ripe-md160 - used name 'rmd160'. Implemented in php mhash extension functions.
 192     - sha - used name 'sha'. Implemented in php mhash extension functions
 193       and php 4.3.0+ sha1() function. mhash extension is used only when
 194       sha1() function is unavailable.
 195     - ssha - used name 'ssha'. Implemented in php mhash extension functions.
 196       Minimal php version = 4.0.4.
 197     - md5 crypt - used name 'md5crypt'. Uses php crypt function. Depends on
 198       md5 support in system crypt libraries. Should work on linux glibc2 systems
 199       and bsd systems.
 200     - blowfish crypt - used name 'blowfish'. Uses php crypt function. Depends on
 201       blowfish support in system crypt libraries. Should work on bsd systems.
 202       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 203     - extended des crypt - used name 'extcrypt'. Uses php crypt function. Depends on
 204       extended des support in system crypt libraries. Should work on bsd systems.
 205       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 206     - standard des crypt - used name 'crypt'. Uses php crypt function. Depends on
 207       standard des support in system crypt libraries. Should work on libc systems
 208       and bsd systems.
 209     - plain text passwords - used name 'plaintext'.
 210
 211     If you use admindn, plugin should support all encryption/hashing
 212     algorithms used in your ldap server.
 213
 214     WARNINGS:
 215     * don't enforce any crypto that is not supported by ldap server, if admindn
 216       override is not used in backend configuration.
 217     * don't enforce extcrypt, md5crypt or blowfish, if they are not supported
 218       by ldap server and web server crypt libraries.
 219
 220     Safest setting options:
 221     * If web server and ldap server is on same OS, make sure that mhash
 222       extension is present in php.
 223     * If web server and ldap server is on same OS and mhash extension is
 224       not present, enforce md5 passwords or any crypt password algorithm
 225       supported by your os. Remember that standard des crypt is limited
 226       to eight symbols.  Don't use admindn override, if ldap server
 227       supports md4, rmd160, sha, ssha or smd5.
 228     * If crypt libraries differ on web server and ldap server -
 229       enforce md5 passwords or any crypt password algorithm supported by
 230       web server and ldap server. Don't use admindn override, if ldap
 231       server supports md4, rmd160, sha, ssha or smd5 and mhash extension
 232       is not present.
 233
 234   Configuration example:
 235   $cpw_ldap['basedn']='ou=users,dc=example,dc=com'; // sets base dn
 236   $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3;   // forces v3 bind protocol
 237
 238   Tested configurations:
 239   - Linux Debian Sarge, OpenLDAP v.2.1.30, Qmail LDAP 20050401a, courier-imap
 240     v.3.0.8 using qmail-ldap auth-imap authentication. ns-mta-md5 crypto is not
 241     implemented in backend.
 242
 243 -------------------
 244 ABOUT MYSQL BACKEND
 245 ------------_------
 246   List of supported overrides:
 247   * 'server'
 248     address of MySQL server. Defaults to localhost.
 249
 250   * 'database'
 251     database that stores user information. Defaults to 'email'.
 252
 253   * 'table'
 254     database table that stores user information. Defaults to 'users'.
 255
 256   * 'userid_field'
 257     field that stores user's ID. Defaults to 'id'.
 258
 259   * 'password_field'
 260     field that stores password. Defaults to 'password'.
 261
 262   * 'manager_id'
 263     username that is used to log into MySQL with (must have rights).
 264     Defaults to 'email_admin'.
 265
 266   * 'manager_pw'
 267     password that is used to log into MySQL.
 268
 269   * 'saslcrypt'
 270     boolean value that controls use of SASL (MySQL) crypt in passwords.
 271     It is not enabled by default.
 272
 273   * 'unixcrypt'
 274     boolean value that controls use of unix crypt() in passwords.
 275     Setting is ignored, if saslcrypt is enabled. It is not enabled
 276     by default.
 277
 278 If saslcrypt and unixcrypt are not enabled, plugin defaults to plaintext
 279 passwords.
 280
 281 $Id$