"Fossies" - the Fresh Open Source Software Archive

Member "roundcubemail-1.4.2/plugins/password/README" (1 Jan 2020, 16254 Bytes) of package /linux/www/roundcubemail-1.4.2.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README": 1.3.10_vs_1.4.0.

    1  -----------------------------------------------------------------------
    2  Password Plugin for Roundcube
    3  -----------------------------------------------------------------------
    4  Plugin that adds a possibility to change user password using many
    5  methods (drivers) via Settings/Password tab.
    6  -----------------------------------------------------------------------
    7  This program is free software: you can redistribute it and/or modify
    8  it under the terms of the GNU General Public License as published by
    9  the Free Software Foundation, either version 3 of the License, or
   10  (at your option) any later version.
   11 
   12  This program is distributed in the hope that it will be useful,
   13  but WITHOUT ANY WARRANTY; without even the implied warranty of
   14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   15  GNU General Public License for more details.
   16 
   17  You should have received a copy of the GNU General Public License
   18  along with this program. If not, see http://www.gnu.org/licenses/.
   19 
   20  @author Aleksander Machniak <alec@alec.pl>
   21  @author <see driver files for driver authors>
   22  -----------------------------------------------------------------------
   23 
   24  1.      Configuration
   25  2.      Drivers
   26  2.1.    Password Change Drivers
   27  2.1.1.  Database (sql)
   28  2.1.2.  Cyrus/SASL (sasl)
   29  2.1.3.  Poppassd/Courierpassd (poppassd)
   30  2.1.4.  LDAP (ldap)
   31  2.1.5.  DirectAdmin Control Panel (directadmin)
   32  2.1.6.  cPanel
   33  2.1.6.1.  cPanel WHM (cpanel)
   34  2.1.6.2.  cPanel Webmail (cpanel_webmail)
   35  2.1.7.  XIMSS/Communigate (ximms)
   36  2.1.8.  Virtualmin (virtualmin)
   37  2.1.9.  hMailServer (hmail)
   38  2.1.10. PAM (pam)
   39  2.1.11. Chpasswd (chpasswd)
   40  2.1.12. LDAP - no PEAR (ldap_simple)
   41  2.1.13. XMail (xmail)
   42  2.1.14. Pw (pw_usermod)
   43  2.1.15. domainFACTORY (domainfactory)
   44  2.1.16. DBMail (dbmail)
   45  2.1.17. Expect (expect)
   46  2.1.18. Samba (smb)
   47  2.1.19. Vpopmail daemon (vpopmaild)
   48  2.1.20. Plesk (Plesk RPC-API)
   49  2.1.21. Kpasswd
   50  2.1.22. Modoboa
   51  2.1.23. LDAP - Password Modify Extended Operation (ldap_exop)
   52  2.2.    Password Strength Drivers
   53  2.2.1.  Zxcvbn
   54  3.      Driver API
   55  4.      Sudo setup
   56 
   57 
   58  1. Configuration
   59  ----------------
   60 
   61  Copy config.inc.php.dist to config.inc.php and set the options as described
   62  within the file.
   63 
   64 
   65  2. Drivers
   66  ----------
   67 
   68 
   69  2.1. Password Change Drivers
   70  ----------------------------
   71 
   72  Password plugin supports many password change mechanisms which are
   73  handled by included drivers. Just pass driver name in 'password_driver' option.
   74 
   75 
   76  2.1.1. Database (sql)
   77  ---------------------
   78 
   79  You can specify which database to connect by 'password_db_dsn' option and
   80  what SQL query to execute by 'password_query'. See config.inc.php.dist file for
   81  more info.
   82 
   83  Example implementations of an update_passwd function:
   84 
   85  - This is for use with LMS (http://lms.org.pl) database and postgres:
   86 
   87     CREATE OR REPLACE FUNCTION update_passwd(hash text, account text) RETURNS integer AS $$
   88     DECLARE
   89             res integer;
   90     BEGIN
   91         UPDATE passwd SET password = hash
   92         WHERE login = split_part(account, '@', 1)
   93             AND domainid = (SELECT id FROM domains WHERE name = split_part(account, '@', 2))
   94         RETURNING id INTO res;
   95         RETURN res;
   96     END;
   97     $$ LANGUAGE plpgsql SECURITY DEFINER;
   98 
   99  - This is for use with a SELECT update_passwd(%o,%c,%u) query
  100    Updates the password only when the old password matches the MD5 password
  101    in the database
  102 
  103     CREATE FUNCTION update_password (oldpass text, cryptpass text, user text) RETURNS text
  104         MODIFIES SQL DATA
  105     BEGIN
  106         DECLARE currentsalt varchar(20);
  107         DECLARE error text;
  108         SET error = 'incorrect current password';
  109         SELECT substring_index(substr(user.password,4),_latin1'$',1) INTO currentsalt FROM users WHERE username=user;
  110         SELECT '' INTO error FROM users WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  111         UPDATE users SET password=cryptpass WHERE username=user AND password=ENCRYPT(oldpass,currentsalt);
  112         RETURN error;
  113     END
  114 
  115  Example SQL UPDATEs:
  116 
  117  - Plain text passwords:
  118     UPDATE users SET password=%p WHERE username=%u AND password=%o AND domain=%h LIMIT 1
  119 
  120  - Crypt text passwords:
  121     UPDATE users SET password=%c WHERE username=%u LIMIT 1
  122 
  123  - Use a MYSQL crypt function (*nix only) with random 8 character salt
  124     UPDATE users SET password=ENCRYPT(%p,concat(_utf8'$1$',right(md5(rand()),8),_utf8'$')) WHERE username=%u LIMIT 1
  125 
  126  - MD5 stored passwords:
  127     UPDATE users SET password=MD5(%p) WHERE username=%u AND password=MD5(%o) LIMIT 1
  128 
  129 
  130  2.1.2. Cyrus/SASL (sasl)
  131  ------------------------
  132 
  133  Cyrus SASL database authentication allows your Cyrus+Roundcube
  134  installation to host mail users without requiring a Unix Shell account!
  135 
  136  This driver only covers the "sasldb" case when using Cyrus SASL. Kerberos
  137  and PAM authentication mechanisms will require other techniques to enable
  138  user password manipulations.
  139 
  140  Cyrus SASL includes a shell utility called "saslpasswd" for manipulating
  141  user passwords in the "sasldb" database.  This plugin attempts to use
  142  this utility to perform password manipulations required by your webmail
  143  users without any administrative interaction. Unfortunately, this
  144  scheme requires that the "saslpasswd" utility be run as the "cyrus"
  145  user - kind of a security problem since we have chosen to SUID a small
  146  script which will allow this to happen.
  147 
  148  This driver is based on the Squirrelmail Change SASL Password Plugin.
  149  See http://www.squirrelmail.org/plugin_view.php?id=107 for details.
  150 
  151  Installation:
  152 
  153  Change into the helpers directory. Edit the chgsaslpasswd.c file as is
  154  documented within it.
  155 
  156  Compile the wrapper program:
  157     gcc -o chgsaslpasswd chgsaslpasswd.c
  158 
  159  Chown the compiled chgsaslpasswd binary to the cyrus user and group
  160  that your browser runs as, then chmod them to 4550.
  161 
  162  For example, if your cyrus user is 'cyrus' and the apache server group is
  163  'nobody' (I've been told Redhat runs Apache as user 'apache'):
  164 
  165     chown cyrus:nobody chgsaslpasswd
  166     chmod 4550 chgsaslpasswd
  167 
  168  Stephen Carr has suggested users should try to run the scripts on a test
  169  account as the cyrus user eg;
  170 
  171     su cyrus -c "./chgsaslpasswd -p test_account"
  172 
  173  This will allow you to make sure that the script will work for your setup.
  174  Should the script not work, make sure that:
  175  1) the user the script runs as has access to the saslpasswd|saslpasswd2
  176    file and proper permissions
  177  2) make sure the user in the chgsaslpasswd.c file is set correctly.
  178    This could save you some headaches if you are the paranoid type.
  179 
  180 
  181  2.1.3. Poppassd/Courierpassd (poppassd)
  182  ---------------------------------------
  183 
  184  You can specify which host to connect to via 'password_pop_host' and
  185  what port via 'password_pop_port'. See config.inc.php.dist file for more info.
  186 
  187 
  188  2.1.4. LDAP (ldap)
  189  ------------------
  190 
  191  See config.inc.php.dist file. Requires PEAR::Net_LDAP2 package.
  192 
  193 
  194  2.1.5. DirectAdmin Control Panel (directadmin)
  195  ----------------------------------------------
  196 
  197  You can specify which host to connect to via 'password_directadmin_host' (don't
  198  forget to use tcp:// or ssl://) and what port via 'password_direactadmin_port'.
  199  The password enforcement with plenty customization can be done directly by
  200  DirectAdmin, please see http://www.directadmin.com/features.php?id=910
  201  See config.inc.php.dist file for more info.
  202 
  203 
  204  2.1.6. cPanel
  205  -------------
  206 
  207  cPanel offers various APIs. The `cpanel` driver is configured with and admin
  208  account. It can change user's passwords without access to the current password.
  209  See the next section.
  210 
  211  The `cpanel_webmail` driver authenticates as the current user and does not need
  212  an admin account. See 2.6.2.
  213 
  214 
  215  2.1.6.1. cPanel WHM (cpanel)
  216  ----------------------------
  217 
  218  Install cPanel XMLAPI Client Class into Roundcube program/lib directory
  219  or any other place in PHP include path. You can get the class from
  220  https://raw.github.com/CpanelInc/xmlapi-php/master/xmlapi.php
  221 
  222  You can configure parameters for connection to cPanel's API interface.
  223  See config.inc.php.dist file for more info.
  224 
  225 
  226  2.1.6.2. cPanel Webmail (cpanel_webmail)
  227  ----------------------------------------
  228 
  229  Specify the host to connect to via 'password_webmail_cpanel_host'. This driver
  230  comes with a minimal UAPI implementation and does not use the external xmlapi
  231  class. It requires php-curl extension.
  232 
  233  See config.inc.php.dist file for more info.
  234 
  235 
  236  2.1.7. XIMSS/Communigate (ximms)
  237  --------------------------------
  238 
  239  You can specify which host and port to connect to via 'password_ximss_host'
  240  and 'password_ximss_port'. See config.inc.php.dist file for more info.
  241 
  242 
  243  2.1.8. Virtualmin (virtualmin)
  244  ------------------------------
  245 
  246  As in sasl driver this one allows to change password using shell
  247  utility called "virtualmin". See helpers/chgvirtualminpasswd.c for
  248  installation instructions. Requires virtualmin >= 4.09.
  249 
  250 
  251  2.1.9. hMailServer (hmail)
  252  --------------------------
  253 
  254  Requires PHP COM (Windows only). For access to hMail server on remote host
  255  you'll need to define 'hmailserver_remote_dcom' and 'hmailserver_server'.
  256  See config.inc.php.dist file for more info.
  257 
  258 
  259  2.1.10. PAM (pam)
  260  -----------------
  261 
  262  This driver is for changing passwords of shell users authenticated with PAM.
  263  Requires PECL's PAM extension to be installed (http://pecl.php.net/package/PAM).
  264 
  265 
  266  2.1.11. Chpasswd (chpasswd)
  267  ---------------------------
  268 
  269  Driver that adds functionality to change the systems user password via
  270  the 'chpasswd' command. See config.inc.php.dist file.
  271 
  272  Attached wrapper script (helpers/chpass-wrapper.py) restricts password changes
  273  to uids >= 1000 and can deny requests based on a blacklist.
  274 
  275 
  276  2.1.12.  LDAP - no PEAR (ldap_simple)
  277  -------------------------------------
  278 
  279  It's rewritten ldap driver that doesn't require the Net_LDAP2 PEAR extension.
  280  It uses directly PHP's ldap module functions instead (as Roundcube does).
  281 
  282  This driver is fully compatible with the ldap driver, but
  283  does not require (or uses) the
  284     $config['password_ldap_force_replace'] variable.
  285  Other advantages:
  286     * Connects only once with the LDAP server when using the search user.
  287     * Does not read the DN, but only replaces the password within (that is
  288       why the 'force replace' is always used).
  289 
  290 
  291  2.1.13.  XMail (xmail)
  292  ----------------------
  293 
  294  Driver for XMail (www.xmailserver.org). See config.inc.php.dist file
  295  for configuration description.
  296 
  297 
  298  2.1.14.  Pw (pw_usermod)
  299  ------------------------
  300 
  301  Driver to change the systems user password via the 'pw usermod' command.
  302  See config.inc.php.dist file for configuration description.
  303 
  304 
  305  2.1.15.  domainFACTORY (domainfactory)
  306  -------------------------------------
  307 
  308  Driver for the hosting provider domainFACTORY (www.df.eu).
  309  No configuration options.
  310 
  311 
  312  2.1.16.  DBMail (dbmail)
  313  ------------------------
  314 
  315  Driver that adds functionality to change the users DBMail password.
  316  It only works with dbmail-users on the same host where Roundcube runs
  317  and requires shell access and gcc in order to compile the binary
  318  (see instructions in chgdbmailusers.c file).
  319  See config.inc.php.dist file for configuration description.
  320 
  321  Note: DBMail users can also use sql driver.
  322 
  323 
  324  2.1.17.  Expect (expect)
  325  ------------------------
  326 
  327  Driver to change user password via the 'expect' command.
  328  See config.inc.php.dist file for configuration description.
  329 
  330 
  331  2.1.18.  Samba (smb)
  332  --------------------
  333 
  334  Driver to change Samba user password via the 'smbpasswd' command.
  335  See config.inc.php.dist file for configuration description.
  336 
  337 
  338  2.1.19. Vpopmail daemon (vpopmaild)
  339  -------------------------------------
  340 
  341  Driver for the daemon of vpopmail. Vpopmail is used with qmail to
  342  enable virtual users that are saved in a database and not in /etc/passwd.
  343 
  344  Set $config['password_vpopmaild_host'] to the host where vpopmaild runs.
  345 
  346  Set $config['password_vpopmaild_port'] to the port of vpopmaild.
  347 
  348  Set $config['password_vpopmaild_timeout'] to the timeout used for the TCP
  349  connection to vpopmaild (You may want to set it higher on busy servers).
  350 
  351 
  352  2.1.20. Plesk (Plesk RPC-API)
  353  -----------------------------
  354 
  355  Driver for changing Passwords via Plesk RPC-API. This Driver also works with
  356  Parallels Plesk Automation (PPA).
  357 
  358  You need to allow the IP of the Roundcube-Server for RPC-Calls in the Panel.
  359 
  360  Set $config['password_plesk_host'] to the Hostname / IP where Plesk runs
  361  Set your Admin or RPC User: $config['password_plesk_user']
  362  Set the Password of the User: $config['password_plesk_pass']
  363  Set $config['password_plesk_rpc_port']  for the RPC-Port. Usually its 8443
  364  Set the RPC-Path in $config['password_plesk_rpc_path']. Normally this is: enterprise/control/agent.php.
  365 
  366 
  367  2.1.21. Kpasswd
  368  ---------------
  369 
  370  Driver to change the password in Kerberos environments via the 'kpasswd' command.
  371  See config.inc.php.dist file for configuration description.
  372 
  373 
  374  2.1.22. Modoboa
  375  ---------------
  376 
  377  Driver to change the password in Modoboa servers.
  378  See config.inc.php.dist file for configuration description.
  379 
  380 
  381  2.1.23. LDAP - Password Modify Extended Operation (ldap_exop)
  382  -------------------------------------------------------------
  383  
  384  Modified version of ldap_simple.
  385  Password is changed using ldap_exop_passwd operation.
  386  PHP >= 7.2 required.
  387  
  388  
  389  2.2. Password Strength Drivers
  390  ------------------------------
  391 
  392  Password plugin supports many password strength checking mechanisms which are
  393  handled by included drivers. Just pass driver name in 'password_strength_driver' option.
  394 
  395 
  396  2.2.1. Zxcvbn
  397  -------------
  398 
  399  Driver to use the Zxcvbn library to check password strength. Requires zxcvbn-php library.
  400  The library is not distributed with Roundcube (see composer.json-dist).
  401  Note: Required PHP's memory_limit >= 24M.
  402 
  403  Set $config['password_zxcvbn_min_score'] to define minimum acceptable password strength score.
  404 
  405 
  406  3. Driver API
  407  -------------
  408 
  409  Driver file (<driver_name>.php) must define rcube_<driver_name>_password class. Drivers should
  410  provide one or both of a public save() or check_strength() method.
  411 
  412  All password changing drivers (used in config `password_driver` - the password driver) must have
  413  a save() method. The same driver can also contain a check_strength() method or a separate driver
  414  containing this method can be used in `password_strength_driver` (the strength driver). To enable
  415  strength checks ensure `password_check_strength` is set to true.
  416 
  417  The save() method, used for changing the password has three arguments:
  418  First - current password, second - new password, third - current username.
  419  This method should return PASSWORD_SUCCESS on success or any of PASSWORD_CONNECT_ERROR,
  420  PASSWORD_CRYPT_ERROR, PASSWORD_ERROR when driver was unable to change password.
  421  Extended result (as a hash-array with 'message' and 'code' items) can be returned
  422  too. See existing drivers in drivers/ directory for examples.
  423 
  424  Optionally a password driver can contain a compare() method which has three arguments:
  425  First - current password, second - test password, third - compare type.
  426  Compare type: PASSWORD_COMPARE_CURRENT - when comparing the test password with current password.
  427  PASSWORD_COMPARE_NEW - when comparing the current password with the test password.
  428  For PASSWORD_COMPARE_CURRENT it should return error text if user entered and real current password
  429  DO NOT MATCH. For PASSWORD_COMPARE_NEW it should return error text if user entered and real current
  430  password DO MATCH. Else it should return null (no error).
  431 
  432  The check_strength() method, used for checking password strength has one argument: new password.
  433  This method should return an array with tho elements:
  434    - Score: integer from 1 (week) to 5 (strong)
  435    - Reason for the score (optional)
  436 
  437  Optionally a strength driver can contain a strength_rules() method. This has no arguments
  438  and returns a string, or array of strings explaining the password strength rules.
  439 
  440 
  441  4. Sudo setup
  442  -------------
  443 
  444  Some drivers that execute system commands (like chpasswd) require use of sudo command.
  445  Here's a sample for CentOS 7:
  446 
  447  # cat <<END >/etc/sudoers.d/99-roundcubemail
  448  apache ALL=NOPASSWD:/usr/sbin/chpasswd
  449  Defaults:apache !requiretty
  450  <<END
  451 
  452  Note: on different systems the username (here 'apache') may be different, e.g. www.
  453  Note: on some systems the disabling tty line may not be needed.