
* 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 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 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. 


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

Yep!


* I'm getting an Authentication Failure error, why?

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. 


* 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.
