|author||Steve Langasek <firstname.lastname@example.org>||2009-08-18 17:57:04 -0700|
|committer||Steve Langasek <email@example.com>||2019-01-08 19:42:00 -0800|
proofread / reflow the mini-policy
Diffstat (limited to 'debian')
1 files changed, 37 insertions, 37 deletions
diff --git a/debian/local/Debian-PAM-MiniPolicy b/debian/local/Debian-PAM-MiniPolicy
index c7304380..84b020ca 100644
@@ -12,20 +12,20 @@ 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
+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.
-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
+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
The selection of common-session or common-session-noninteractive is based
@@ -39,9 +39,11 @@ noninteractive sessions will always be a subset of those used for
Under some circumstances (such as ftp auth, or auth based on tty) other
-modules will be required.
+service-specific modules will need to be listed in the service's /etc/pam.d
-Here is an example of a PAM configuration file that just includes the common module fragments:
+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
@@ -63,7 +65,8 @@ Here is an example of a PAM configuration file that just includes the common mod
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 filename coincides with the value of this parameter used in your
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
@@ -81,7 +84,7 @@ solution for shared PAM configuration across modules, in the form of
the @include directive.
-Currently libpam-modules is in the base setup, so it's dependency is not
+Currently libpam-modules is in the base setup, so its 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.
@@ -92,39 +95,36 @@ guarantee that /etc/pam.d/common-* exist.
Applications that use common-session-noninteractive must depend
on libpam-runtime (>= 1.0.1-11) for this file.
-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 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
-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
+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
+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.