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 1.2
  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
  34  2.6.   cPanel
  35  2.7.   XIMSS (Communigate)
  36  3.     Driver API
  37
  38
  39  1. Configuration
  40  ----------------
  41
  42  Copy config.inc.php.dist to config.inc.php and set the options as described
  43  within the file.
  44
  45
  46  2. Drivers
  47  ----------
  48
  49  Password plugin supports many password change mechanisms which are
  50  handled by included drivers. Just pass driver name in 'password_driver' option.
  51
  52
  53  2.1. Database (sql)
  54  -------------------
  55
  56  You can specify which database to connect by 'password_db_dsn' option and
  57  what SQL query to execute by 'password_query'. See main.inc.php file for
  58  more info.
  59
  60  Example implementations of an update_passwd function:
  61
  62  - This is for use with LMS (http://lms.org.pl) database and postgres:
  63
  64         CREATE OR REPLACE FUNCTION update_passwd(hash text, account text) RETURNS integer AS $$
  65         DECLARE
  66             res integer;
  67         BEGIN
  68             UPDATE passwd SET password = hash
  69             WHERE login = split_part(account, '@', 1)
  70                 AND domainid = (SELECT id FROM domains WHERE name = split_part(account, '@', 2))
  71             RETURNING id INTO res;
  72             RETURN res;
  73         END;
  74         $$ LANGUAGE plpgsql SECURITY DEFINER;
  75
  76  - This is for use with a SELECT update_passwd(%o,%c,%u) query
  77         Updates the password only when the old password matches the MD5 password
  78         in the database
  79
  80         CREATE FUNCTION update_password (oldpass text, cryptpass text, user text) RETURNS text
  81             MODIFIES SQL DATA
  82         BEGIN
  83             DECLARE currentsalt varchar(20);
  84             DECLARE error text;
  85             SET error = 'incorrect current password';
  86             SELECT substring_index(substr(user.password,4),_latin1'$',1) INTO currentsalt FROM users WHERE username=user;
  87             SELECT '' INTO error FROM users WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  88             UPDATE users SET password=cryptpass WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  89             RETURN error;
  90         END
  91
  92  Example SQL UPDATEs:
  93
  94  - Plain text passwords:
  95     UPDATE users SET password=%p WHERE username=%u AND password=%o AND domain=%h LIMIT 1
  96
  97  - Crypt text passwords:
  98     UPDATE users SET password=%c WHERE username=%u LIMIT 1
  99
 100  - Use a MYSQL crypt function (*nix only) with random 8 character salt
 101     UPDATE users SET password=ENCRYPT(%p,concat(_utf8'$1$',right(md5(rand()),8),_utf8'$')) WHERE username=%u LIMIT 1
 102
 103  - MD5 stored passwords:
 104     UPDATE users SET password=MD5(%p) WHERE username=%u AND password=MD5(%o) LIMIT 1
 105
 106
 107  2.2. Cyrus/SASL (sasl)
 108  ----------------------
 109
 110  Cyrus SASL database authentication allows your Cyrus+RoundCube
 111  installation to host mail users without requiring a Unix Shell account!
 112
 113  This driver only covers the "sasldb" case when using Cyrus SASL. Kerberos
 114  and PAM authentication mechanisms will require other techniques to enable
 115  user password manipulations.
 116
 117  Cyrus SASL includes a shell utility called "saslpasswd" for manipulating
 118  user passwords in the "sasldb" database.  This plugin attempts to use
 119  this utility to perform password manipulations required by your webmail
 120  users without any administrative interaction. Unfortunately, this
 121  scheme requires that the "saslpasswd" utility be run as the "cyrus"
 122  user - kind of a security problem since we have chosen to SUID a small
 123  script which will allow this to happen.
 124
 125  This driver is based on the Squirrelmail Change SASL Password Plugin.
 126  See http://www.squirrelmail.org/plugin_view.php?id=107 for details.
 127
 128  Installation:
 129
 130  Change into the drivers directory. Edit the chgsaslpasswd.c file as is
 131  documented within it.
 132
 133  Compile the wrapper program:
 134         gcc -o chgsaslpasswd chgsaslpasswd.c
 135
 136  Chown the compiled chgsaslpasswd binary to the cyrus user and group
 137  that your browser runs as, then chmod them to 4550.
 138
 139  For example, if your cyrus user is 'cyrus' and the apache server group is
 140  'nobody' (I've been told Redhat runs Apache as user 'apache'):
 141
 142         chown cyrus:nobody chgsaslpasswd
 143         chmod 4550 chgsaslpasswd
 144
 145  Stephen Carr has suggested users should try to run the scripts on a test
 146  account as the cyrus user eg;
 147
 148         su cyrus -c "./chgsaslpasswd -p test_account"
 149
 150  This will allow you to make sure that the script will work for your setup.
 151  Should the script not work, make sure that:
 152  1) the user the script runs as has access to the saslpasswd|saslpasswd2
 153    file and proper permissions
 154  2) make sure the user in the chgsaslpasswd.c file is set correctly.
 155    This could save you some headaches if you are the paranoid type.
 156
 157
 158  2.3. Poppassd/Courierpassd (poppassd)
 159  -------------------------------------
 160
 161  You can specify which host to connect to via 'password_pop_host' and
 162  what port via 'password_pop_port'. See config.inc.php file for more info.
 163
 164
 165  2.4. LDAP (ldap)
 166  ----------------
 167
 168  See config.inc.php file. Requires PEAR::Net_LDAP2 package.
 169
 170
 171  2.5. DirectAdmin Control Panel
 172  -------------------------------------
 173
 174  You can specify which host to connect to via 'password_directadmin_host'
 175  and what port via 'password_direactadmin_port'. See config.inc.php file
 176  for more info.
 177
 178
 179  2.6. cPanel
 180  -----------
 181
 182  You can specify parameters for HTTP connection to cPanel's admin
 183  interface. See config.inc.php file for more info.
 184
 185
 186  2.7. XIMSS (Communigate)
 187  -------------------------------------
 188
 189  You can specify which host and port to connect to via 'password_ximss_host'
 190  and 'password_ximss_port'. See config.inc.php file for more info.
 191
 192
 193  3. Driver API
 194  -------------
 195
 196  Driver file (<driver_name>.php) must define 'password_save' function with
 197  two arguments. First - current password, second - new password. Function
 198  may return PASSWORD_SUCCESS on success or any of PASSWORD_CONNECT_ERROR,
 199  PASSWORD_CRYPT_ERROR, PASSWORD_ERROR when driver was unable to change password.
 200  See existing drivers in drivers/ directory for examples.