Copy plugins to release branch

1 files changed, 264 insertions, 0 deletions

diff --git a/plugins/password/README b/plugins/password/README
new file mode 100644
index 000000000..d9280fb03
--- /dev/null
+++ b/plugins/password/README
@@ -0,0 +1,264 @@
+ -----------------------------------------------------------------------
+ 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 <alec@alec.pl>
+ @author <see driver files for driver authors>
+ -----------------------------------------------------------------------
+
+ 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' (don't 
+ forget to use tcp:// or ssl://) and what port via 'password_direactadmin_port'.
+ The password enforcement with plenty customization can be done directly by 
+ DirectAdmin, please see http://www.directadmin.com/features.php?id=910
+ 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. See also config.inc.php.dist file.
+
+
+ 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 (<driver_name>.php) must define 'password_save' function with
+ two arguments. First - current password, second - new password. Function
+ should return PASSWORD_SUCCESS on success or any of PASSWORD_CONNECT_ERROR,
+ PASSWORD_CRYPT_ERROR, PASSWORD_ERROR when driver was unable to change password.
+ Extended result (as a hash-array with 'message' and 'code' items) can be returned
+ too. See existing drivers in drivers/ directory for examples.