From 5fec6de4216883e625d7e166f862985d00c99d4a Mon Sep 17 00:00:00 2001 From: thomascube Date: Sat, 27 Nov 2010 14:09:03 +0000 Subject: Copy plugins to release branch --- plugins/password/README | 262 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 plugins/password/README (limited to 'plugins/password/README') diff --git a/plugins/password/README b/plugins/password/README new file mode 100644 index 000000000..a31a0e076 --- /dev/null +++ b/plugins/password/README @@ -0,0 +1,262 @@ + ----------------------------------------------------------------------- + Password Plugin for Roundcube + ----------------------------------------------------------------------- + + Plugin that adds a possibility to change user password using many + methods (drivers) via Settings/Password tab. + + ----------------------------------------------------------------------- + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License version 2 + as published by the Free Software Foundation. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + + @version @package_version@ + @author Aleksander 'A.L.E.C' Machniak + @author + ----------------------------------------------------------------------- + + 1. Configuration + 2. Drivers + 2.1. Database (sql) + 2.2. Cyrus/SASL (sasl) + 2.3. Poppassd/Courierpassd (poppassd) + 2.4. LDAP (ldap) + 2.5. DirectAdmin Control Panel (directadmin) + 2.6. cPanel (cpanel) + 2.7. XIMSS/Communigate (ximms) + 2.8. Virtualmin (virtualmin) + 2.9. hMailServer (hmail) + 2.10. PAM (pam) + 2.11. Chpasswd (chpasswd) + 2.12. LDAP - no PEAR (ldap_simple) + 2.13. XMail (xmail) + 3. Driver API + + + 1. Configuration + ---------------- + + Copy config.inc.php.dist to config.inc.php and set the options as described + within the file. + + + 2. Drivers + ---------- + + Password plugin supports many password change mechanisms which are + handled by included drivers. Just pass driver name in 'password_driver' option. + + + 2.1. Database (sql) + ------------------- + + You can specify which database to connect by 'password_db_dsn' option and + what SQL query to execute by 'password_query'. See main.inc.php.dist file for + more info. + + Example implementations of an update_passwd function: + + - This is for use with LMS (http://lms.org.pl) database and postgres: + + CREATE OR REPLACE FUNCTION update_passwd(hash text, account text) RETURNS integer AS $$ + DECLARE + res integer; + BEGIN + UPDATE passwd SET password = hash + WHERE login = split_part(account, '@', 1) + AND domainid = (SELECT id FROM domains WHERE name = split_part(account, '@', 2)) + RETURNING id INTO res; + RETURN res; + END; + $$ LANGUAGE plpgsql SECURITY DEFINER; + + - This is for use with a SELECT update_passwd(%o,%c,%u) query + Updates the password only when the old password matches the MD5 password + in the database + + CREATE FUNCTION update_password (oldpass text, cryptpass text, user text) RETURNS text + MODIFIES SQL DATA + BEGIN + DECLARE currentsalt varchar(20); + DECLARE error text; + SET error = 'incorrect current password'; + SELECT substring_index(substr(user.password,4),_latin1'$',1) INTO currentsalt FROM users WHERE username=user; + SELECT '' INTO error FROM users WHERE username=user AND password=ENCRYPT(oldpass,currentsalt); + UPDATE users SET password=cryptpass WHERE username=user AND password=ENCRYPT(oldpass,currentsalt); + RETURN error; + END + + Example SQL UPDATEs: + + - Plain text passwords: + UPDATE users SET password=%p WHERE username=%u AND password=%o AND domain=%h LIMIT 1 + + - Crypt text passwords: + UPDATE users SET password=%c WHERE username=%u LIMIT 1 + + - Use a MYSQL crypt function (*nix only) with random 8 character salt + UPDATE users SET password=ENCRYPT(%p,concat(_utf8'$1$',right(md5(rand()),8),_utf8'$')) WHERE username=%u LIMIT 1 + + - MD5 stored passwords: + UPDATE users SET password=MD5(%p) WHERE username=%u AND password=MD5(%o) LIMIT 1 + + + 2.2. Cyrus/SASL (sasl) + ---------------------- + + Cyrus SASL database authentication allows your Cyrus+Roundcube + installation to host mail users without requiring a Unix Shell account! + + This driver only covers the "sasldb" case when using Cyrus SASL. Kerberos + and PAM authentication mechanisms will require other techniques to enable + user password manipulations. + + Cyrus SASL includes a shell utility called "saslpasswd" for manipulating + user passwords in the "sasldb" database. This plugin attempts to use + this utility to perform password manipulations required by your webmail + users without any administrative interaction. Unfortunately, this + scheme requires that the "saslpasswd" utility be run as the "cyrus" + user - kind of a security problem since we have chosen to SUID a small + script which will allow this to happen. + + This driver is based on the Squirrelmail Change SASL Password Plugin. + See http://www.squirrelmail.org/plugin_view.php?id=107 for details. + + Installation: + + Change into the drivers directory. Edit the chgsaslpasswd.c file as is + documented within it. + + Compile the wrapper program: + gcc -o chgsaslpasswd chgsaslpasswd.c + + Chown the compiled chgsaslpasswd binary to the cyrus user and group + that your browser runs as, then chmod them to 4550. + + For example, if your cyrus user is 'cyrus' and the apache server group is + 'nobody' (I've been told Redhat runs Apache as user 'apache'): + + chown cyrus:nobody chgsaslpasswd + chmod 4550 chgsaslpasswd + + Stephen Carr has suggested users should try to run the scripts on a test + account as the cyrus user eg; + + su cyrus -c "./chgsaslpasswd -p test_account" + + This will allow you to make sure that the script will work for your setup. + Should the script not work, make sure that: + 1) the user the script runs as has access to the saslpasswd|saslpasswd2 + file and proper permissions + 2) make sure the user in the chgsaslpasswd.c file is set correctly. + This could save you some headaches if you are the paranoid type. + + + 2.3. Poppassd/Courierpassd (poppassd) + ------------------------------------- + + You can specify which host to connect to via 'password_pop_host' and + what port via 'password_pop_port'. See config.inc.php.dist file for more info. + + + 2.4. LDAP (ldap) + ---------------- + + See config.inc.php.dist file. Requires PEAR::Net_LDAP2 package. + + + 2.5. DirectAdmin Control Panel (directadmin) + -------------------------------------------- + + You can specify which host to connect to via 'password_directadmin_host' + and what port via 'password_direactadmin_port'. See config.inc.php.dist file + for more info. + + + 2.6. cPanel (cpanel) + -------------------- + + You can specify parameters for HTTP connection to cPanel's admin + interface. See config.inc.php.dist file for more info. + + + 2.7. XIMSS/Communigate (ximms) + ------------------------------ + + You can specify which host and port to connect to via 'password_ximss_host' + and 'password_ximss_port'. See config.inc.php.dist file for more info. + + + 2.8. Virtualmin (virtualmin) + ---------------------------- + + As in sasl driver this one allows to change password using shell + utility called "virtualmin". See drivers/chgvirtualminpasswd.c for + installation instructions. + + + 2.9. hMailServer (hmail) + ------------------------ + + Requires PHP COM (Windows only). For access to hMail server on remote host + you'll need to define 'hmailserver_remote_dcom' and 'hmailserver_server'. + See config.inc.php.dist file for more info. + + + 2.10. PAM (pam) + --------------- + + This driver is for changing passwords of shell users authenticated with PAM. + Requires PECL's PAM exitension to be installed (http://pecl.php.net/package/PAM). + + + 2.11. Chpasswd (chpasswd) + ------------------------- + + Driver that adds functionality to change the systems user password via + the 'chpasswd' command. See config.inc.php.dist file. + + Attached wrapper script (chpass-wrapper.py) restricts password changes + to uids >= 1000 and can deny requests based on a blacklist. + + + 2.12. LDAP - no PEAR (ldap_simple) + ----------------------------------- + + It's rewritten ldap driver that doesn't require the Net_LDAP2 PEAR extension. + It uses directly PHP's ldap module functions instead (as Roundcube does). + + This driver is fully compatible with the ldap driver, but + does not require (or uses) the + $rcmail_config['password_ldap_force_replace'] variable. + Other advantages: + * Connects only once with the LDAP server when using the search user. + * Does not read the DN, but only replaces the password within (that is + why the 'force replace' is always used). + + + 2.13. XMail (xmail) + ----------------------------------- + + Driver for XMail (www.xmailserver.org). See config.inc.php.dist file + for configuration description. + + + 3. Driver API + ------------- + + Driver file (.php) must define 'password_save' function with + two arguments. First - current password, second - new password. Function + may return PASSWORD_SUCCESS on success or any of PASSWORD_CONNECT_ERROR, + PASSWORD_CRYPT_ERROR, PASSWORD_ERROR when driver was unable to change password. + See existing drivers in drivers/ directory for examples. + -- cgit v1.2.3