
INTRODUCTION
------------

The Passwd module is a module that allows the user to change their own
password.  It supports various password changing backends including
poppassd server, smbpasswd program, expect script, or sql/ldap storage.

Note that some drivers like poppassd always use clear text password
transmissions. Others may also use clear text passwords (e.g. the expect
script driver using telnet rather than ssh).   This can be considered
somewhat safe if the server is on the same machine, there are no user
interactive logins allowed on that machine, and the connection uses the
loopback (localhost) interace.  It is up to the installer to evaluate the
security implications of using this module, and to understand the
security implications of how their server and this module is configured.

Note that setting this module to allow guest access might also be
considered a security risk.  By default, guest access is disabled.
It is up to the installer to evaluate the security implications of
using this module with guest access if they choose to do so.

PREREQUISITES
-------------

The following prerequisites are REQUIRED.

  1. A successful Horde 2.x installation and all which that entails.

  2. One or more of:
     * a poppassd server installed, running, and working on a system.
     * a ldap server installed, running, and working for authentication.
     * a working smbpasswd program on the localhost.  It can access a
       remote server, but the smbpasswd binary must be on the localhost.
     * a working sql authentication system.
     * expect installed, and access to telnet or ssh to the machine
       where passwords are stored/set (could be localhost).

INSTALLING PASSWD
-----------------

Passwd is intended to be installed inside the Horde package directory.

Since Passwd is written in PHP, there is no compilation necessary;
simply expand the distribution where you want it to reside (normally
into a directory inside the Horde directory).

For example, with the Apache webserver's default document
root of '/usr/local/apache/htdocs'  and your Horde install in a directory
under that called 'horde' you would type:

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/passwd.tgz

CONFIGURING PASSWD
------------------

1. We assume that you already have a working Horde installation.

2. Configuring Passwd

   To configure passwd, change to the config/ directory of the
   installed distribution, and make copies of all of the configuration
   "dist" files without the "dist" suffix:

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Documentation on the format of those files can be found in each
   file; open each in an editor and make changes as suggested within.
   The default values are reasonable, but may not be appropriate for
   your site, so it is best to check them before proceeding.

   You must login to Horde as a Horde Administrator to finish the
   configuration of Passwd.  Use the Horde "Administration" menu item to get
   to the Administration page, and then click on the "Configuration"
   icon to get the Configuration page.  Select "Password" from the selection
   list of applications, and click on the "Configure" button.  Fill in or
   change any configuration values as needed.  When done click on "Generate
   Password Configuration" to generate the conf.php file.  If your web server
   doesn't have write permissions to the passwd configuration directory or
   file, it will not be able to write the file.  In this case, cut and
   paste the returned configuration information into the file
   passwd/config/conf.php.

3. Configuring Horde

   If there is not already a "passwd" configuration stanza in your
   horde/config/registry.php file, then you need to add one.  You want
   a stanza that looks like:

$this->applications['passwd'] = array(
    'fileroot' => dirname(__FILE__) . '/../passwd',
    'webroot' => $this->applications['horde']['webroot'] . '/passwd',
    'icon' => $this->applications['horde']['webroot'] . '/passwd/graphics/lock.gif',
    'name' => _("Password"),
    'allow_guests' => false,
    'status' => 'active'
);


4. Optional Configuration of IMP

   If you have IMP installed, and want to include Passwd in the IMP menu
   bar, you can add the application to IMP as well.  Edit the file
   horde/imp/config/conf.php and include 'passwd' in the list of menu apps,
   for example, it might look like the following:

   $conf['menu']['apps'] = array('turba','passwd');

OBTAINING SUPPORT
-----------------

There is a mailing list for support:
  sork@lists.horde.org

You can subscribe or view the archives at:
  http://lists.horde.org/mailman/listinfo/sork/


CREDITS
-------

See the seperate CREDITS file under the docs/ directory.

POPPASSD SERVER SOFTWARE
------------------------

The following are some links that users have submitted.  No warrenty
is made for the following links or any software obtained from then.  These
are all user submitted links, and have not been tested or verified.  Use
these links are your own risk!

http://www.ceti.com.pl/~kravietz/prog.html
http://www.samera.net/rpm/
http://netwinsite.com/poppassd/
http://echelon.pl/pubs/poppassd-1.8.1.tar.gz

LDAP IMPLEMENTATION INFORMATION:
--------------------------------

The module now includes experimental support for changing ldap stored
passwords.

LDAP can store passwords in multiple ways, namely:

  a. Plain text passwords
  b. SHA encrypted passwords
  c. SSHA encrypted passwords
  d. Crypt encrypted passwords
  e. MD5 encrypted passwords (using base64 encoding - md5-base64)
  f. SMD5 encrypted passwords

The SHA, SSHA, MD5, and SMD5 encryption types will require the php mhash 
extension!  To enable this you must compile php with the --with-mhash[=DIR] 
parameter to enable this extension. DIR is the mhash install directory.

Crypt cannot handle passwords longer than eight characters (it accepts them
but truncates them at 8 characters).  If you want to use longer passwords,
you may use SHA. 

The user must be able to authenticate to the ldap directory and change
his own password now (we no longer do root access to ldap).
This assumes that the ldap administrator has allowed everyone to write
their own password, something like:

access to attribute=userPassword
       by self write
       by anonymous auth
       by * none

SQL IMPLEMENTATION INFORMATION:
-------------------------------

The module now includes experimental support for changing passwords stored
in a SQL database.  The SQL driver is similar to the ldap driver except that 
it also supports MD5 encryption using hex encoding (md5-hex).  If you created
your passwords using the PHP md5() function then use md5-hex.


SMBPASSWD IMPLEMENTAION INFORMATION:
------------------------------------

To use this module, you must pass the address of your smb domain controller
on which to change the password.  This can be "localhost" for the server
that Horde runs on.  The remote system name may be passed as the NETBIOS
name, the DNS name,  or the IP address of the SMB/CIFS server to connect to.
The username is run through escapeshellcmd, so any usernames with strange
characters ($, &, etc) may not work.  I'm not sure if any of these are
even valid for smb/cifs authentication, but if so, they may not work in
this module...

Note  that if changing a Windows NT Domain password the remote machine
specified must  be  the  Primary Domain  Controller  for  the  domain
(Backup Domain Controllers only have a read-only copy of the  user
account  database  and  will not allow the password change).

Since  smbpasswd works in client-server mode communicating with a
local smbd for a non-root user then the smbd daemon must  be  running
for this to work. A common problem is to add a restriction to the
hosts that may access  the   smbd running  on  the local machine by
specifying a allow hosts or deny hosts entry in the smb.conf file
and neglecting to allow "localhost" access to the smbd.

In addition, the smbpasswd command is only useful if Samba has been
set up to use encrypted passwords.

EXPECT SCRIPT INFORMATION:
--------------------------
This code allows users to change their passwords via an expect script.
Requires the expect program and a telnet or ssh program.  You may need
to change some of the expect patterns in scripts/passwd_expect such
as the badpassword_string or success_string (as only two examples).

For security reasons, it is generally suggested to use ssh rather than
telnet for the transport, if possible.

$Horde: passwd/docs/INSTALL,v 1.26 2003/05/26 15:16:21 ericr Exp $
