Diffstat (limited to 'debian/local/Debian-PAM-MiniPolicy')
1 files changed, 161 insertions, 0 deletions
diff --git a/debian/local/Debian-PAM-MiniPolicy b/debian/local/Debian-PAM-MiniPolicy
new file mode 100644
@@ -0,0 +1,161 @@
+Author: Ben Collins <firstname.lastname@example.org>
+Modified by: Sam Hartman <email@example.com>
+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, 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-session, common-account and common-password. Under some
+circumstances (such as ftp auth, or auth based on tty) other modules
+will be required.
+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 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
+ 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
+You should also not use the pam_stack module in the pam config file.
+It's not currently in Debian so it won't work. While I cannot stop
+someone from packaging pam_stack for Debian, I will try to convince
+them that it is not the direction we want. Pam_stack (among other
+faults) uses different pam handles for each step in the process--the
+handle used for session management is not the same as the handle used
+for authentication. This breaks several modules. We will have an
+alternate solution for shared PAM configuration across modules.
+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.
+Applications need to depend on libpam-runtime (>= 0.76-14) to
+guarantee that /etc/pam.d/common-* exist.
+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).
+The application needs to follow the following rules to make sure PAM
+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
+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
+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
+ 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.
+ 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.