Relevant BUGIDs: 129775

Purpose of commit: bugfix

Commit summary:
---------------
This bugfix leads to backwardly incompatable behavior with earlier
releases of Linux-PAM.

Note, this cleans up the setcred/session and chauthtok stacks in
such a way that it is no longer preferred that the setcred module
always return the same error code as the auth components of said
modules did.

This means behavior should be a great deal more sane. It also gives
meaning to the unique return codes that are available to pam_sm_setcred.
[I'm sure that when we add support for credential relevant events,
 this change will be critical.]

2 files changed, 30 insertions, 15 deletions

diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
index b1010203..9149ecd5 100644
--- a/doc/pam_appl.sgml
+++ b/doc/pam_appl.sgml
@@ -46,7 +46,7 @@ DAMAGE.
 
 <title>The Linux-PAM Application Developers' Guide
 <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.74 2001/01/21
+<date>DRAFT v0.75 2001/02/04
 <abstract>
 This manual documents what an application developer needs to know
 about the <bf>Linux-PAM</bf> library. It describes how an application
@@ -218,9 +218,9 @@ PAM is also capable of setting and deleting the users credentials with
 the call <tt>pam_setcred()</tt>.  This function should always be
 called after the user is authenticated and before service is offered
 to the user.  By convention, this should be the last call to the PAM
-library before service is given to the user.  What exactly a
-credential is, is not well defined.  However, some examples are given
-in the glossary below.
+library before the PAM session is opened.  What exactly a credential
+is, is not well defined.  However, some examples are given in the
+glossary below.
 
 <sect>The public interface to <bf>Linux-PAM</bf>
  
@@ -565,7 +565,7 @@ extern int pam_setcred(pam_handle_t *pamh, int flags);
 <p>
 This function is used to set the module-specific credentials of the
 user.  It is usually called after the user has been authenticated,
-after the account management function has been called and after a
+after the account management function has been called but before a
 session has been opened for the user.
 
 <p>
diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml
index 694eff85..8afd01fa 100644
--- a/doc/pam_modules.sgml
+++ b/doc/pam_modules.sgml
@@ -49,7 +49,7 @@ DAMAGE.
 
 <title>The Linux-PAM Module Writers' Guide
 <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.74 2001/01/21
+<date>DRAFT v0.75 2001/02/04
 <abstract>
 This manual documents what a programmer needs to know in order to
 write a module that conforms to the <bf/Linux-PAM/ standard. It also
@@ -693,7 +693,7 @@ scheme. Generally, an authentication module may have access to more
 information about a user than their authentication token. This
 function is used to make such information available to the
 application. It should only be called <em/after/ the user has been
-authenticated and after a session has been established.
+authenticated but before a session has been established.
 
 <p>
 Permitted flags, one of which, may be logically OR'd with
@@ -711,16 +711,26 @@ Permitted flags, one of which, may be logically OR'd with
 </descrip>
 
 <p>
-Generally, the module should attempt to return the same error code as
-<tt/pam_sm_authenticate/ did.  This will preserve the logic followed
-by libpam as it executes the stack of <em/authentication/ modules,
-when the application calls <tt/pam_authenticate()/ and
-<tt/pam_setcred()/.  Failing to do this, will lead to much confudion
-on the part of the System administrator.
+Prior to <bf/Linux-PAM-0.75/, and due to a deficiency with the way the
+<tt/auth/ stack was handled in the case of the setcred stack being
+processed, the module was required to attempt to return the same error
+code as <tt/pam_sm_authenticate/ did.  This was necessary to preserve
+the logic followed by libpam as it executes the stack of
+<em/authentication/ modules, when the application called either
+<tt/pam_authenticate()/ or <tt/pam_setcred()/.  Failing to do this,
+led to confusion on the part of the System Administrator.
 
 <p>
-<bf>The following text is depreciated.  Some thought needs to be given to
-how the credential setting modules are supposed to be stacked...</bf>
+For <bf/Linux-PAM-0.75/ and later, libpam handles the credential stack
+much more sanely. The way the <tt/auth/ stack is navigated in order to
+evaluate the <tt/pam_setcred()/ function call, independent of the
+<tt/pam_sm_setcred()/ return codes, is exactly the same way that it
+was navigated when evaluating the <tt/pam_authenticate()/ library
+call. Typically, if a stack entry was ignored in evaluating
+<tt/pam_authenticate()/, it will be ignored when libpam evaluates the
+<tt/pam_setcred()/ function call. Otherwise, the return codes from
+each module specific <tt/pam_sm_setcred()/ call are treated as
+<tt/required/.
 
 <p>
 Besides <tt/PAM_SUCCESS/, the module may return one of the following
@@ -737,6 +747,11 @@ errors:
 	This module was unable to set the credentials of the user.
 </descrip>
 
+<p>
+these, non-<tt/PAM_SUCCESS/, return values will typically lead to the
+credential stack <em/failing/. The first such error will dominate in
+the return value of <tt/pam_setcred()/.
+
 </itemize>
 
 <sect1> Account management