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