summaryrefslogtreecommitdiffstats
path: root/debian/local/Debian-PAM-MiniPolicy
diff options
context:
space:
mode:
Diffstat (limited to 'debian/local/Debian-PAM-MiniPolicy')
-rw-r--r--debian/local/Debian-PAM-MiniPolicy145
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.