1API 2 3 bool pam_auth(string $username, string $password 4 [, string &$error [, $checkacctmgmt = true [, string $servicename ] ] ]) 5 bool pam_chpass(string $username, string $oldpassword, string $newpassword 6 [, string &$error [, string $servicename ] ]) 7 8 The parameters are 9 10 username - Username to check 11 password - User supplied password 12 error - Output parameter to put any error messages in 13 checkacctmgmt - Call pam_acct_mgmt() to check account expiration and access hours (requires root access!) 14 servicename - PAM service name to use (provided pam.force_servicename is not TRUE) 15 oldpassword - Current password on account 16 newpassword - Password to change to 17 18INSTALLATION 19 20 For pam_auth and pam_chpass to work, module must know about the PAM service to use. 21 22 By default, the PAM service is set to "php". It can be changed by adding the following 23 to your php.ini: 24 25 pam.servicename = "your-pam-service"; 26 27 Service name can also be, optionally, passed as a parameter to pam_auth OR pam_chpass. 28 29 You can inform the module to ignore the service name passed as a parameter and use 30 pam.servicename only, by adding the following to your php.ini: 31 32 pam.force_servicename = 1; 33 34 Next, you'll need to create a pam service file for php. If you are on linux, 35 you'll need to create the file /etc/pam.d/php. You can copy another one to work 36 off of (/etc/pam.d/login is a good choice). 37 38 Some examples that should work: 39 40 on linux: 41 42# /etc/pam.d/php 43# 44# note: both an auth and account entry are required 45 46auth sufficient /lib/security/pam_pwdb.so shadow nodelay 47account sufficient /lib/security/pam_pwdb.so 48 49 on solaris: 50 51# add to /etc/pam.conf 52 53php auth requisite /usr/lib/security/pam_authtok_get.so.1 54php auth required /usr/lib/security/pam_unix_auth.so.1 55php account required /usr/lib/security/pam_unix_account.so.1 56 57 These would authenticate out of the unix password and shadow file. However 58 please checking other /etc/pam.d/ entries, as the libraries these examples 59 point to may not be correct. 60 61 62FAQ 63 64 * What is PAM? 65 66 PAM stands for Pluggable Authentication Module. It is a system that abstracts 67 user authentication to allow arbitrary modules to handle the real work. In this 68 way, pam enabled services can use a variety of complex authentication schemes 69 without modifying the applications. For more Information, and available 70 modules, see http://www.kernel.org/pub/linux/libs/pam/. 71 72 73 * Why would I want to use PAM from PHP? 74 75 PAM gives you very flexible control over authentication. As an example, there 76 are PAM modules that will authenticate against a local shadow or password file, 77 a Windows NT domain, an SQL database, LDAP, Kerberos, Radius, and more. In 78 addition, pam modules can give you the ability to have restrictions on the 79 authentication, such as the pam_tally module which limits the number of login 80 attempts, and the pam_listfile which let's you restrict access to a list of 81 users. Please note, using pam does not mean you can securely authenticate 82 users, it simply gives you the ability to do so with proper configuration and 83 planning. 84 85 86 * How can I get pam? 87 88 If you are running linux or solaris, you already have it! Linux and Solaris 89 both natively use pam for all authentication, so you're are all set. If you are 90 on other systems, well, you're on your own. I have no idea what PAM has been 91 ported too... 92 93 94 * I'm getting an Authentication Failure error, why? 95 96 Try setting the $checkacctmgmt parameter to false to skip the pam_acct_mgmt() 97 call, note that this only checks the password and skips performing account 98 validation such as account expiration and access. Otherwise see below. 99 100 The most likely reason for this is that you are trying to authenticate via a 101 local shadow file and you do not have permission to do so. The PAM modules 102 handling shadow authentication (used on Linux and Solaris) require that the 103 application have permission to read the shadow file (makes sense, eh?). If you 104 are running php as a cgi or as a webserver module, it is executed as your 105 webservers user and group. 106 107 By default, most Linux and Solaris systems are configured to only allow the root 108 user to read the shadow file. The recommended 109 way around this is to change permissions on the shadow file so that it is group 110 readable, and chgrp the file to the a group that the webserver is in. Before 111 doing this, you should give it some serious thought as allowing your webserver 112 to read the shadow file gives hackers another way to crack away at your system. 113 114 If you decide to enable this, I stronly suggest usage of the pam_tally module 115 to limit failed logins to a reasonable number of attempts, and one of the other 116 modules which will allow you to block root and other system users. 117 118 119 * The pam_auth function doesn't return anything, whattup? 120 121 Did you remember to create an entry in the pam configuration for the php 122 service? 123 124 125 * Logs indicate pam authenticated the user, but the function doesn't return 126 true, what gives? 127 128 Make sure your pam configuration has an entry for both auth and account, if you 129 do not have both, it will not work. 130