diff options
Diffstat (limited to 'debian/local/Debian-PAM-MiniPolicy')
| -rw-r--r-- | debian/local/Debian-PAM-MiniPolicy | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/debian/local/Debian-PAM-MiniPolicy b/debian/local/Debian-PAM-MiniPolicy new file mode 100644 index 0000000..8cba0ae --- /dev/null +++ b/debian/local/Debian-PAM-MiniPolicy @@ -0,0 +1,145 @@ +Author: Ben Collins <bcollins@debian.org> +Modified by: Sam Hartman <hartmans@debian.org>, + Steve Langasek <vorlon@debian.org> + +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 that. However, it does specify behavior needed to make sure PAM +modules in Debian 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, this file should use the +@include directive to include common-auth, common-account, and +common-password, and one of either common-session or +common-session-noninteractive. + +The selection of common-session or common-session-noninteractive is based +on whether the service provides "shell-like" interactive capabilities to +the user (e.g.: login, ssh, gdm) or is a non-interactive session or a +session mediated by a structured protocol (e.g.: cron, cups, samba, ppp). +This allows a service to avoid calling some modules, such as +pam_ck_connector, that only make sense in an interactive context and should +be avoided otherwise. It is expected that the modules used for +noninteractive sessions will always be a subset of those used for +interactive sessions. + +Under some circumstances (such as ftp auth, or auth based on tty) other +service-specific modules will need to be listed in the service's /etc/pam.d +file. + +Here is an example of a PAM configuration file that just includes the +common module fragments: + + # + # /etc/pam.d/other - specify the PAM fallback behaviour + # + # Note that this file is used for any unspecified service; for example + #if /etc/pam.d/cron specifies no session modules but cron calls + #pam_open_session, the session module out of /etc/pam.d/other is + #used. If you really want nothing to happen then use pam_permit.so or + #pam_deny.so as appropriate. + + # We fall back to the system default in /etc/pam.d/common-* + # + + @include common-auth + @include common-account + @include common-password + @include common-session + +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 the value of this parameter used in your +application. + +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. + + +Packages which configure their services by default to use modules other than +those provided by /etc/pam.d/common-* must depend on the package providing +those modules. E.g., /etc/pam.d/login includes the line: + + session required pam_limits.so + +therefore it must depend on libpam-modules, which provides +/lib/security/pam_limits.so. + +Applications need to depend on libpam-runtime to guarantee that +/etc/pam.d/common-* exist. + +Applications that use common-session-noninteractive must depend +on libpam-runtime for this file. + + +The pam_unix.so module allows programs to authenticate the uid of the +calling process without being setuid or setgid. NOTE: this means the user +executing the program; you cannot authenticate other users without suid +root (root makes sure the NIS and NIS+ works too) or at least sgid shadow +(won't work in the above cases). Most notably this affects programs like +apache being able to use PAM since it runs as www-data which has no +privileges and cannot use pam_unix.so to authenticate other users. On the +other hand it does allow programs like vlock to authenticate. + +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 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 influence 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 descended 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_end 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 `libpam-<name>' (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_<name>.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 <name>.conf. |