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