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 Probably, you need to set some config vars in the backend too
  30 (backend/<yourbackend>.php).
  31
  32 BACKENDS
  33 - ldap
  34
  35   Default settings are supplied in backends/ldap.php.
  36
  37   You don't have to change any configuration vars in
  38   backend/ldap.php - instead, create an $cpw_ldap array in
  39   config.php containing the variable you want to override.
  40
  41   See more information in "About ldap backend" chapter.
  42
  43 - mysql
  44
  45   Default settings are supplied in backends/mysql.php.
  46
  47   You do not have to change any configuration vars in
  48   backend/mysql.php - instead, create an array in config.php
  49   containing the variable you want to override, for example:
  50
  51   To override the server name ($mysql_server), you would add
  52     $mysql['server'] = 'remote_servername';
  53   to config.php.
  54
  55
  56 - merak
  57
  58   Default settings are supplied in backends/merak.php.
  59
  60
  61 - poppassd
  62
  63   Default settings are supplied in backends/poppassd.php.
  64
  65
  66 - vmailmgrd
  67
  68   Default settings are supplied in backends/vmailmgrd.php.
  69
  70   Site configuration is controlled in config.php $vmailmgrd
  71   array. Backend uses 'vmail_inc_path', 'vm_tcphost',
  72   'vm_tcphost_port' and 'cpw_vmailmgrd_8bitpw' array keys.
  73
  74   'vmail_inc_path' sets path to vmail.inc. 'vm_tcphost' sets
  75   vmailmgrd tcp service ip address or dns name. Plugin uses
  76   vmailmgrd socket, if it is not set. 'vm_tcphost_port' sets
  77   port of vmailmrgd service. Plugin uses port 322, if it is
  78   not set. 'cpw_vmailmgrd_8bitpw' controls use of 8bit
  79   passwords. If it is not set, interface does not allow new
  80   passwords with 8bit symbols.
  81
  82   $vmailmgrd['vmail_inc_path'] setting is required.
  83
  84
  85 AUTHORS:
  86 ldap backend      - Tomas Kuliavas <tokul@users.sourceforge.net>
  87                     used code from phpldapadmin and squirrelmail
  88                     ldapquery plugin.
  89 merak backend     - Edwin van Elk <Edwin@eve-software.com>
  90 mysql backend     - Thijs Kinkhorst <kink@squirrelmail.org>
  91 poppassd backend  - Seth Randall <sethr@missoulafcu.org>
  92 vmailmgrd backend - Tomas Kuliavas <tokul@users.sourceforge.net>
  93
  94 ------------------
  95 ABOUT LDAP BACKEND
  96 ------------------
  97   List of supported overrides
  98   * 'server'
  99     overrides address of ldap server. use any syntax that is supported
 100     by your php ldap extension. Defaults to address of imap server.
 101
 102   * 'port'
 103     overrides port of ldap server. Defaults to 389.
 104
 105   * 'basedn'
 106     (required) ldap basedn used for binding to ldap server. Empty
 107     string blocks use of backend. Defaults to empty string.
 108
 109   * 'connect_opts'
 110     controls LDAP_OPT_* settings that are set with ldap_set_option()
 111     function. See available options at http://www.php.net/ldap-set-option.
 112     LDAP_OPT_ prefix must be omitted in $cpw_ldap['connect_opts']
 113     overrides. No connection options are enabled by default.
 114
 115     You can use this option only when your ldap extension supports
 116     ldap_set_option() function.
 117
 118   * 'use_tls'
 119     enables or disables use of tls in ldap connection. Requires php
 120     4.2+, php ldap extension with ssl support and PROTOCOL_VERSION => 3
 121     setting in $cpw_ldap_connect_opts. Does not enable tls by default.
 122
 123   * 'binddn'
 124     unprivileged binddn. should be able to search ldap directory and
 125     find DN used by user. Uses anonymous bind, if set to empty string.
 126     You should not use DN with write access to ldap directory here.
 127     Defaults to anonymous bind.
 128
 129   * 'bindpw'
 130     password used for unprivileged bind
 131
 132   * 'admindn'
 133     bind DN that should be able to change password.
 134     WARNING: usually user has enough privileges to change own password.
 135     If you leave default value, plugin will try to connect with dn that
 136     is detected in $cpw_ldap_username_attr=$username search and current
 137     user password will be used for authentication.
 138
 139   * 'adminpw'
 140     password for binding with 'admindn'
 141
 142   * 'userid_attr'
 143     ldap attribute that stores username. Defaults to 'uid'
 144
 145   * 'default_crypto'
 146     crypto that is used to encode new password. If set to empty string,
 147     system tries to keep same encoding/hashing algorithm. Currently
 148     backend supports:
 149     - md5 - used name 'md5'. Implemented in standard php functions.
 150     - smd5 - used name 'smd5'. Implemented in php mhash extension functions.
 151       Minimal php version = 4.0.4.
 152     - sha - used name 'sha'. Implemented in php mhash extension functions
 153       and php 4.3.0+ sha1() function. mhash extension is used only wheh
 154       sha1() function is unavailable.
 155     - ssha - used name 'ssha'. Implemented in php mhash extension functions.
 156       Minimal php version = 4.0.4.
 157     - md5 crypt - used name 'md5crypt'. Uses php crypt function. Depends on
 158       md5 support in system crypt libraries. Should work on linux glibc2 systems
 159       and bsd systems.
 160     - blowfish crypt - used name 'blowfish'. Uses php crypt function. Depends on
 161       blowfish support in system crypt libraries. Should work on bsd systems.
 162       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 163     - extended des crypt - used name 'extcrypt'. Uses php crypt function. Depends on
 164       extended des support in system crypt libraries. Should work on bsd systems.
 165       Is not supported by glibc 2.3.2. (Tested on OpenBSD 3.5)
 166     - standard des crypt - used name 'crypt'. Uses php crypt function. Depends on
 167       standard des support in system crypt libraries. Should work on libc systems
 168       and bsd systems.
 169     - plain text passwords - used name 'plaintext'.
 170
 171     If you use admindn, plugin should support all encryption/hashing
 172     algorithms used in your ldap server.
 173
 174     WARNINGS:
 175     * don't enforce any crypto that is not supported by ldap server.
 176     * don't enforce extcrypt, md5crypt or blowfish, if they are not supported
 177       by ldap server and web server crypt libraries.
 178
 179     Safest setting options:
 180     * If web server and ldap server is on same OS, make sure that mhash
 181       extension is present in php.
 182     * If web server and ldap server is on same OS and mhash extension is
 183       not present, enforce md5 passwords or any crypt password algorithm
 184       supported by your os. Remember that standard des crypt is limited
 185       to eight symbols.  Don't use admindn override, if ldap server
 186       supports sha, ssha or smd5.
 187     * If crypt libraries differ on web server and ldap server -
 188       enforce md5 passwords or any crypt password algorithm supported by
 189       web server and ldap server. Don't use admindn override, if ldap
 190       server supports sha, ssha or smd5 and mhash extension is not
 191       present.
 192
 193   Configuration example:
 194   $cpw_ldap['base_dn']='ou=users,dc=example,dc=com'; // sets base dn
 195   $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3;   // forces v3 bind protocol
 196
 197
 198 $Id$