Originally by: Ben Collins , Sam Hartman Maintained by: Dmitry V. Levin Objective: To document a base set of policies regarding PAM (Pluggable Authentication Modules) usage in ALT Linux 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 pam-doc package for info on this, however it does specify behavior needed to make sure PAM modules in ALT Linux will work with your application. ================== 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 "include system-auth" directive 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_tcb.so"). This will ensure that the program continues to work even if the module location changes, since libpam itself will resolve the location. Also, module name should not contain a version suffix (eg. don't use "pam_tcb.so.2"). This will ensure that the config file continues to work even if module version suffix changes, since libpam itself will resolve the suffix. Under no circumstances should any program in ALT Linux use the pam_pwdb.so or pam_unix.so modules by default. Instead the pam_tcb.so module should be used. Note that pam_tcb provides full backwards compatibility with pam_pwdb.so and pam_unix.so, see pam_tcb(8) for details. You should also not use the pam_stack module in the pam config file. It's no longer included by default in ALT Linux so it might not work. Use "include" directive instead. The application needs to follow the following rules to make sure PAM modules work: 1) Use the same PAM handle for all operations. This means it is not OK to call pam_start once for authentication and then later with another handle for session management. Modules need to be able to store pam_data between entry points. 2) The pam_open_session and pam_setcred calls must be made in a parent process of the eventual session. They need to be able to enfluence the environment of the session. 3) If you are started as root or have root privs for some other reason, pam_open_session and pam_setcred should be called while still root. 4) Implied by 1, make sure that pam_close_session and pam_end are called in the same process or a process decended from the execution context as pam_open_session and pam_setcred. The pam_close_session call may need state stored in the handle by the open session entry point to clean up properly. The pam_finish call may need to free data (thus influencing system state in some cases) allocated in the earlier calls. ============= PAM Modules ============= Separately packaged pam modules should adhere to a few basic setup rules: 1) Packages should use the naming scheme of `pam%{_pam_name_suffix}_' Macro %set_pam_name() can be used to automate naming, eg. %set_pam_name pam_passwdqc %package -n %pam_name (results to pam0_tcb for Linux-PAM and pam2_tcb for OpenPAM). 2) The modules should be located in the directory of the most recent pam package (currently /lib/security/). 3) The module should be named as pam_.so%{_pam_so_suffix}; that is, the Linux-PAM module should not contain a version suffix while OpenPAM module should. 4) The module should be linked to libpam (-lpam) when compiled so that proper version dependencies will work. If the Linux-PAM module uses pam_misc library, it should be linked also with -lpam_misc. 5) Any new config files should be located in /etc/security/. The filename will be in the form of .conf. There are exceptions from this rule though, eg. /etc/securetty and /etc/nologin.