squirrelmail/plugins/change_password/README

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$