plugins/password/README

   1  -----------------------------------------------------------------------
   2  Password Plugin for Roundcube
   3  -----------------------------------------------------------------------
   4
   5  Plugin that adds a possibility to change user password using many
   6  methods (drivers) via Settings/Password tab.
   7
   8  -----------------------------------------------------------------------
   9  This program is free software; you can redistribute it and/or modify
  10  it under the terms of the GNU General Public License version 2
  11  as published by the Free Software Foundation.
  12
  13  This program is distributed in the hope that it will be useful,
  14  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  GNU General Public License for more details.
  17
  18  You should have received a copy of the GNU General Public License along
  19  with this program; if not, write to the Free Software Foundation, Inc.,
  20  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21
  22  @version @package_version@
  23  @author Aleksander 'A.L.E.C' Machniak <alec@alec.pl>
  24  @author <see driver files for driver authors>
  25  -----------------------------------------------------------------------
  26
  27  1.     Configuration
  28  2.     Drivers
  29  2.1.  Database (sql)
  30  2.2.  Cyrus/SASL (sasl)
  31  2.3.  Poppassd/Courierpassd (poppassd)
  32  2.4.  LDAP (ldap)
  33  2.5.  DirectAdmin Control Panel (directadmin)
  34  2.6.  cPanel (cpanel)
  35  2.7.  XIMSS/Communigate (ximms)
  36  2.8.  Virtualmin (virtualmin)
  37  2.9.  hMailServer (hmail)
  38  2.10. PAM (pam)
  39  2.11. Chpasswd (chpasswd)
  40  2.12. LDAP - no PEAR (ldap_simple)
  41  2.13. XMail (xmail)
  42  3.     Driver API
  43
  44
  45  1. Configuration
  46  ----------------
  47
  48  Copy config.inc.php.dist to config.inc.php and set the options as described
  49  within the file.
  50
  51
  52  2. Drivers
  53  ----------
  54
  55  Password plugin supports many password change mechanisms which are
  56  handled by included drivers. Just pass driver name in 'password_driver' option.
  57
  58
  59  2.1. Database (sql)
  60  -------------------
  61
  62  You can specify which database to connect by 'password_db_dsn' option and
  63  what SQL query to execute by 'password_query'. See main.inc.php.dist file for
  64  more info.
  65
  66  Example implementations of an update_passwd function:
  67
  68  - This is for use with LMS (http://lms.org.pl) database and postgres:
  69
  70         CREATE OR REPLACE FUNCTION update_passwd(hash text, account text) RETURNS integer AS $$
  71         DECLARE
  72             res integer;
  73         BEGIN
  74             UPDATE passwd SET password = hash
  75             WHERE login = split_part(account, '@', 1)
  76                 AND domainid = (SELECT id FROM domains WHERE name = split_part(account, '@', 2))
  77             RETURNING id INTO res;
  78             RETURN res;
  79         END;
  80         $$ LANGUAGE plpgsql SECURITY DEFINER;
  81
  82  - This is for use with a SELECT update_passwd(%o,%c,%u) query
  83         Updates the password only when the old password matches the MD5 password
  84         in the database
  85
  86         CREATE FUNCTION update_password (oldpass text, cryptpass text, user text) RETURNS text
  87             MODIFIES SQL DATA
  88         BEGIN
  89             DECLARE currentsalt varchar(20);
  90             DECLARE error text;
  91             SET error = 'incorrect current password';
  92             SELECT substring_index(substr(user.password,4),_latin1'$',1) INTO currentsalt FROM users WHERE username=user;
  93             SELECT '' INTO error FROM users WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  94             UPDATE users SET password=cryptpass WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  95             RETURN error;
  96         END
  97
  98  Example SQL UPDATEs:
  99
 100  - Plain text passwords:
 101     UPDATE users SET password=%p WHERE username=%u AND password=%o AND domain=%h LIMIT 1
 102
 103  - Crypt text passwords:
 104     UPDATE users SET password=%c WHERE username=%u LIMIT 1
 105
 106  - Use a MYSQL crypt function (*nix only) with random 8 character salt
 107     UPDATE users SET password=ENCRYPT(%p,concat(_utf8'$1$',right(md5(rand()),8),_utf8'$')) WHERE username=%u LIMIT 1
 108
 109  - MD5 stored passwords:
 110     UPDATE users SET password=MD5(%p) WHERE username=%u AND password=MD5(%o) LIMIT 1
 111
 112
 113  2.2. Cyrus/SASL (sasl)
 114  ----------------------
 115
 116  Cyrus SASL database authentication allows your Cyrus+Roundcube
 117  installation to host mail users without requiring a Unix Shell account!
 118
 119  This driver only covers the "sasldb" case when using Cyrus SASL. Kerberos
 120  and PAM authentication mechanisms will require other techniques to enable
 121  user password manipulations.
 122
 123  Cyrus SASL includes a shell utility called "saslpasswd" for manipulating
 124  user passwords in the "sasldb" database.  This plugin attempts to use
 125  this utility to perform password manipulations required by your webmail
 126  users without any administrative interaction. Unfortunately, this
 127  scheme requires that the "saslpasswd" utility be run as the "cyrus"
 128  user - kind of a security problem since we have chosen to SUID a small
 129  script which will allow this to happen.
 130
 131  This driver is based on the Squirrelmail Change SASL Password Plugin.
 132  See http://www.squirrelmail.org/plugin_view.php?id=107 for details.
 133
 134  Installation:
 135
 136  Change into the drivers directory. Edit the chgsaslpasswd.c file as is
 137  documented within it.
 138
 139  Compile the wrapper program:
 140         gcc -o chgsaslpasswd chgsaslpasswd.c
 141
 142  Chown the compiled chgsaslpasswd binary to the cyrus user and group
 143  that your browser runs as, then chmod them to 4550.
 144
 145  For example, if your cyrus user is 'cyrus' and the apache server group is
 146  'nobody' (I've been told Redhat runs Apache as user 'apache'):
 147
 148         chown cyrus:nobody chgsaslpasswd
 149         chmod 4550 chgsaslpasswd
 150
 151  Stephen Carr has suggested users should try to run the scripts on a test
 152  account as the cyrus user eg;
 153
 154         su cyrus -c "./chgsaslpasswd -p test_account"
 155
 156  This will allow you to make sure that the script will work for your setup.
 157  Should the script not work, make sure that:
 158  1) the user the script runs as has access to the saslpasswd|saslpasswd2
 159    file and proper permissions
 160  2) make sure the user in the chgsaslpasswd.c file is set correctly.
 161    This could save you some headaches if you are the paranoid type.
 162
 163
 164  2.3. Poppassd/Courierpassd (poppassd)
 165  -------------------------------------
 166
 167  You can specify which host to connect to via 'password_pop_host' and
 168  what port via 'password_pop_port'. See config.inc.php.dist file for more info.
 169
 170
 171  2.4. LDAP (ldap)
 172  ----------------
 173
 174  See config.inc.php.dist file. Requires PEAR::Net_LDAP2 package.
 175
 176
 177  2.5. DirectAdmin Control Panel (directadmin)
 178  --------------------------------------------
 179
 180  You can specify which host to connect to via 'password_directadmin_host' (don't
 181  forget to use tcp:// or ssl://) and what port via 'password_direactadmin_port'.
 182  The password enforcement with plenty customization can be done directly by
 183  DirectAdmin, please see http://www.directadmin.com/features.php?id=910
 184  See config.inc.php.dist file for more info.
 185
 186
 187  2.6. cPanel (cpanel)
 188  --------------------
 189
 190  You can specify parameters for HTTP connection to cPanel's admin
 191  interface. See config.inc.php.dist file for more info.
 192
 193
 194  2.7. XIMSS/Communigate (ximms)
 195  ------------------------------
 196
 197  You can specify which host and port to connect to via 'password_ximss_host'
 198  and 'password_ximss_port'. See config.inc.php.dist file for more info.
 199
 200
 201  2.8. Virtualmin (virtualmin)
 202  ----------------------------
 203
 204  As in sasl driver this one allows to change password using shell
 205  utility called "virtualmin". See drivers/chgvirtualminpasswd.c for
 206  installation instructions. See also config.inc.php.dist file.
 207
 208
 209  2.9. hMailServer (hmail)
 210  ------------------------
 211
 212  Requires PHP COM (Windows only). For access to hMail server on remote host
 213  you'll need to define 'hmailserver_remote_dcom' and 'hmailserver_server'.
 214  See config.inc.php.dist file for more info.
 215
 216
 217  2.10. PAM (pam)
 218  ---------------
 219
 220  This driver is for changing passwords of shell users authenticated with PAM.
 221  Requires PECL's PAM exitension to be installed (http://pecl.php.net/package/PAM).
 222
 223
 224  2.11. Chpasswd (chpasswd)
 225  -------------------------
 226
 227  Driver that adds functionality to change the systems user password via
 228  the 'chpasswd' command. See config.inc.php.dist file.
 229
 230  Attached wrapper script (chpass-wrapper.py) restricts password changes
 231  to uids >= 1000 and can deny requests based on a blacklist.
 232
 233
 234  2.12.  LDAP - no PEAR (ldap_simple)
 235  -----------------------------------
 236
 237  It's rewritten ldap driver that doesn't require the Net_LDAP2 PEAR extension.
 238  It uses directly PHP's ldap module functions instead (as Roundcube does).
 239
 240  This driver is fully compatible with the ldap driver, but
 241  does not require (or uses) the
 242     $rcmail_config['password_ldap_force_replace'] variable.
 243  Other advantages:
 244     * Connects only once with the LDAP server when using the search user.
 245     * Does not read the DN, but only replaces the password within (that is
 246       why the 'force replace' is always used).
 247
 248
 249  2.13.  XMail (xmail)
 250  -----------------------------------
 251
 252  Driver for XMail (www.xmailserver.org). See config.inc.php.dist file
 253  for configuration description.
 254
 255
 256  3. Driver API
 257  -------------
 258
 259  Driver file (<driver_name>.php) must define 'password_save' function with
 260  two arguments. First - current password, second - new password. Function
 261  should return PASSWORD_SUCCESS on success or any of PASSWORD_CONNECT_ERROR,
 262  PASSWORD_CRYPT_ERROR, PASSWORD_ERROR when driver was unable to change password.
 263  Extended result (as a hash-array with 'message' and 'code' items) can be returned
 264  too. See existing drivers in drivers/ directory for examples.