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