Author: Ben Collins Objective: To document a base set of policies regarding PAM (Pluggable Authentication Modules) usage in Debian packages. =========================================================================== In order to have a consistent and stable implementation across packages that use PAM, these guidelines will help to avoid some common mistakes and be usable as a cross reference for FAQ's. This document will not go into the details of how to add PAM usage to existing code, please read the documentation in the libpam-doc package for info on this. ================== PAM Applications ================== Each application that uses PAM also must contain a file in /etc/pam.d/. This file specifies which PAM modules will be used for the common PAM functions in that application. There are several notes concerning what modules to use in this file. Most commonly, the pam_unix.so module will be all that is needed. Under some circumstances (such as ftp auth, or auth based on tty) other modules will be required. The name of this file is determined by the call to pam_start() in the application source code. The first parameter will be a string containing the "service" name (eg. "login", "httpd", etc..). Please make sure that the filename coincides with this parameter. The file should _not_ reference the full path of the modules. It only needs to reference the basename (eg. "pam_unix.so"). This will ensure that the program continues to work even if the module location changes, since libpam itself will resolve the location. Under no circumstances should any program in Debian use the pam_pwdb.so module by default. Instead the pam_unix.so module should be used. Most programs with RedHat support/default files will reference pam_pwdb.so in their example files. Do not use this. There are several problems with regard to pam_pwdb.so: 1) It attempts to reimplement glibc's NSS code. For example, if your program uses pam_pwdb.so, and the user changes /etc/nsswitch.conf to use NIS, NIS+, or LDAP, then your program will fail to work unless the user also knows to edit /etc/pwdb.conf (which is not necessary for pam_unix.so). In the case of LDAP, the program would become absolutely useless until the user modifies the pam.d file themselves to use pam_unix.so. 2) It adds to the layer of glibc function calls making it harder to debug problems. Because libpwdb masks glibc native calls, it requires being able to debug libpwdb, libpam, libc and the offending program. Note that pam_unix.so takes the same module arguments as pam_pwdb.so, so you can just replace the references. If you are not sure if the pam.d files is correctly setup, please feel free to email it to me, and I will glance it over. UPDATE: libpwdb and this libpam-pwdb have been removed from Debian as of Woody. So even if you decided to use pam_pwdb, it will be broken, so HAHA :) Currently libpam-modules is in the base setup, so it's dependency is not needed (since the library depends on the correct version). However, if any modules other than the base set in libpam-modules are used, that package must be depended on. The pam_unix.so module allows programs to verify the authentication of the uid of the calling process without any set bits (uid or gid). NOTE: this means the user executing the program, you cannot authenticate against other users without suid root (root makes sure the NIS and NIS+ works too) or at least sgid shadow (wont work in the above cases). Most notably this affects programs like apache from being able to use PAM with much success since it runs as www-data which has no priviledges and cannot use pam_unix.so to auth against other users. On the other hand is does allow program like vlock to auth (but not auth the root password). ============= PAM Modules ============= Separately packaged pam modules should adhere to a few basic setup rules: 1) Packages should use the naming scheme of `libpam-' (eg. libpam-ldap). 2) The modules should be located in the directory of the most recent libpam-modules (currently /lib/security). 3) The module should be named as pam_.so. The module should not contain a version suffix. 4) The module should be linked to libpam (-lpam) when compiled so that proper version dependencies will work. 5) Any config files should be located in /etc/security. The filename will be in the form of .conf.