(Note: This readme is just a dump of the webpage, please see
	http://www.math.ohio-state.edu/~ccunning/pam_auth.html
for the latest info)

                          PHP4 Pam Authentication

  pam_auth 0.2 released 3/5/01

   I finally figured out some problems people were having, this should
   fix all errors I'm aware of. If you have problems using this, please
   let me know.

   Changes:
     * Fixed problem that caused build errors on some systems
     * Fixed possible core dumps on solaris
     * Fixed typo causing errors to not be returned
     * Added ability to set the pam servicename in the php.ini
     * It now builds as a shared module (although it won't load...)

   Go get it now: [1]pam_auth-0.2.tar.gz

  TODO

     * Add ability to change passwords (dangerous!)
     * Figure out why the shared module won't load
     * Add option to not require a valid account entry (i.e. make sure
       they don't have to have the ability to log in)

  What is it?

   This is a PHP4 extension that will allow you to simply and easily use
   php to authenticate via PAM.

  What is PAM?

   PAM stands for Pluggable Authentication Module. It is a system that
   abstracts user authentication to allow arbitrary modules to handle the
   real work. In this way, pam enabled services can use a variety of
   complex authentication schemes without modifying the applications. For
   more Information, and available modules, see
   [2]http://www.kernel.org/pub/linux/libs/pam/.

  Why would I want to use PAM from PHP?

   PAM gives you very flexible control over authentication. As an
   example, there are PAM modules that will authenticate against a local
   shadow or password file, a Windows NT domain, an SQL database, LDAP,
   Kerberos, Radius, and more. In addition, pam modules can give you the
   ability to have restrictions on the authentication, such as the
   pam_tally module which limits the number of login attempts, and the
   pam_listfile which let's you restrict access to a list of users.
   Please note, using pam does not mean you can securely authenticate
   users, it simply gives you the ability to do so with proper
   configuration and planning.

  How can I get pam?

   If you are running linux or solaris, you already have it! Linux and
   Solaris both natively use pam for all authentication, so you're are
   all set. If you are on other systems, well, you're on your own. I have
   no idea what PAM has been ported too...

  Isn't there already a php pam module?

   Yep, you can find it at [3]ftp://ftp.netexpress.net/pub/pam/.

  So, why another one?

   The above module is an excellent wrapper to the PAM API. However, for
   projects at work, I don't need the PAM API, I simply need to
   authenticate users. I figure 90% of other people out there also just
   want to authenticate. So, I wrote this to do that and that only,
   simply and without fuss. It consists of only one function, pam_auth()
   which will return true if the user is authenticated, or false if not.
   False will also issue a warning with the reason given for failure. If
   you need any of the more advanced features of PAM, get the module
   above.

  Where can I get it?

   Right here! [4]pam_auth-0.1.tar.gz

  How do I Install it?

   Very easily! Simply untar the file, and copy it to your php source
   directory in the ext/ subdirectory. In the top level of the source
   directory, run the buildconf script (i.e. ./buildconf). Then, simply
   build as usualy, specifying the --with-pam_auth flag to build it in.
   In the near future I will put up instructions for building a shared
   module, and make binary loadable modules available for Solaris and
   Linux.

  How do I configure it?

   There isn't much to configuring the extension. The default pam
   servicename is php, as of version 0.2 you can change this in the
   php.ini by adding an entry such as:

     pam_auth.servicename = "whatever";

   You will also need to configure pam if you expect this to do anything
   interesting, pam must know about your service and what it's allowed to
   do. This requires root access to the web server. If you don't have
   root access to the machine you want to set this up on, you are out of
   luck. If you are using linux, at least redhat, you can copy
   /etc/pam.d/login to /etc/pam.d/php (or whatever you chose for the
   servicename) which will give php the same authentication rules as
   telnet and rlogin. Under Solaris you'll need to add entries to
   /etc/pam.conf, again you can base this on other entries. Please note,
   I strongly advice that you read through the pam docs at
   [5]http://www.kernel.org/pub/linux/libs/pam/ so that you have a clear
   concept of what you're doing and how secure it is, specifically read
   the System Administrators Guide in the online documentation. This
   information is mostly valid for Solaris as well.

   For the lazy...

   Linux
# /etc/pam.d/php
#
# note: both an auth and account entry are required

auth            sufficient      /lib/security/pam_pwdb.so shadow nodelay
account         sufficient      /lib/security/pam_pwdb.so

   Solaris
# add to /etc/pam.conf

php             auth    required        /usr/lib/security/pam_unix.so.1
php             account required        /usr/lib/security/pam_unix.so.1

  How do I use it?

   It's very easy! Here's an example that demonstrates all the
   funcionatlity...

if (pam_auth($username, $password, &$error)) {
        echo "Yeah baby, we're authenticated!";
} else {
        echo $error;
}

   See, wasn't that easy? The function itself returns either true or
   false. The third argument is optional, if supplied it must be passed
   by reference (the & before it..). If the authentication fails, the
   error message returned by pam will be written to that variable.

  Will it work with both the CGI and Module version of PHP?

   Yep, it will work with either.

  I keep getting the error "Authentication failure", what does that mean?

   The most likely reason for this is that you are trying to authenticate
   via a local shadow file and you do not have permission to do so. The
   PAM modules handling shadow authentication (used on Linux and Solaris)
   require that the application have permission to read the shadow file
   (makes sense, eh?). If you are running php as a cgi or as a webserver
   module, it is executed as your webservers user and group. By default,
   most Linux and Solaris systems are configured to only allow the root
   user to read the shadow file. The recommended way around this is to
   change permissions on the shadow file so that it is group readable,
   and chgrp the file to the a group that the webserver is in. Before
   doing this, you should give it some serious thought as allowing your
   webserver to read the shadow file gives hackers another way to crack
   away at your system. If you decide to enable this, I stronly suggest
   usage of the pam_tally module to limit failed logins to a reasonable
   number of attempts, and one of the other modules which will allow you
   to block root and other system users.

  The pam_auth function doesn't return anything, whattup?

   Did you remember to create an entry in the pam configuration for the
   php service? Huh huh, did ya?

  Logs indicate pam authenticated the user, but the function doesn't return
  true, what gives?

   Make sure your pam configuration has an entry for both auth and
   account, if you do not have both, it will not work.

  I have a hosted account, can I use this?

   The best answer I can give is maybe... Since this can be built as a
   dynamically loadable module, you can load it yourself provided your
   hosting company allows you to do so. However, to use this you must
   configure pam, which your provider would have to do for you. I'm
   betting not many will... Theoretically, one could change the
   servicename in the source to an existing service that already is
   configure for pam, however your hosting provider might not like
   that... In the next release I will make the servicename configurable
   in the php.ini.

  Can I use it with PHP3?

   Not currently... It wouldn't be tough to backport it to PHP3, I just
   haven't done it. I might one of these days... Or if you want to, let
   me know :)

  I tried it, but I get an error about a call to undefined function. What
  gives?

   For some reason, newer version of php4 do not always seem to properly
   update the autoconf stuff when your run the buildconf script. If you
   get this error, configure php again and then look through the autoconf
   output and look for a line that says "Checking for Pam Auth support:
   yes". If you don't see it, it isn't getting built in. To fix this, run
   the command 'autoconf' in the top level php source directory, this
   should update the configure script to recognize the pam auth stuff.
   Run configure again and check for the verification in the output.

  Can I use it as a dynamically loadable shared module?

   Not yet, I haven't figure out why. As soon as I can get it to work I
   will make that version 0.3...

  Couldn't you just do this with the pam extension and some php user code?

   Yep... But, I wanted something clean without a lot of user space php
   code laying around, and that anyone could use without having to worry
   about how the PAM API works.

  Can I email you for help?

   If you have a problem directly related to the pam_auth extension, such
   as it won't build, or you have comments/suggestions, feel free to
   email me. However, I will not answer general questions about PAM, or
   about how to build php sites that handle authentication, such
   questions should be directed to the appropriate mailing lists.

  Why is this webpage so ugly and boring?

   Because I'm lazy.
     _________________________________________________________________

   Last Updated: 3-5-01 [6]ccunning@math.ohio-state.edu

References

   1. http://www.math.ohio-state.edu/~ccunning/download.php/pam_auth-0.2.tar.gz
   2. http://www.kernel.org/pub/linux/libs/pam/
   3. ftp://ftp.netexpress.net/pub/pam/
   4. http://www.math.ohio-state.edu/~ccunning/download.php/pam_auth-0.2.tar.gz
   5. http://www.kernel.org/pub/linux/libs/pam/
   6. mailto:ccunning@math.ohio-state.edu