doc update

[squirrelmail.git] / 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.
- merak backend needs php curl extension.
- poppass 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.
Probably, you need to set some config vars in the backend too
(backend/<yourbackend>.php).

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 array in config.php 
  containing the variable you want to override, for example:

  To override the server name ($mysql_server), you would add
    $mysql['server'] = 'remote_servername';
  to config.php.


- merak

  Default settings are supplied in backends/merak.php.


- poppassd

  Default settings are supplied in backends/poppassd.php.


- vmailmgrd

  Default settings are supplied in backends/vmailmgrd.php.
  
  Site configuration is controlled in config.php $vmailmgrd 
  array. Backend uses 'vmail_inc_path', 'vm_tcphost', 
  'vm_tcphost_port' and 'cpw_vmailmgrd_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. 'cpw_vmailmgrd_8bitpw' controls use of 8bit 
  passwords. If it is not set, interface does not allow new 
  passwords with 8bit symbols.

  $vmailmgrd['vmail_inc_path'] setting is required.


AUTHORS:
ldap backend      - Tomas Kuliavas <tokul@users.sourceforge.net>
                    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>
vmailmgrd backend - Tomas Kuliavas <tokul@users.sourceforge.net>

------------------
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. Empty 
    string 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 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. 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:
    - 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.
    - sha - used name 'sha'. Implemented in php mhash extension functions 
      and php 4.3.0+ sha1() function. mhash extension is used only wheh 
      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.
    * 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 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 sha, ssha or smd5 and mhash extension is not 
      present.

  Configuration example:
  $cpw_ldap['base_dn']='ou=users,dc=example,dc=com'; // sets base dn
  $cpw_ldap['connect_opts']['PROTOCOL_VERSION']=3;   // forces v3 bind protocol


$Id$