From 547e42fc5cb7c0208eeb002809c3d270334af114 Mon Sep 17 00:00:00 2001 From: "Andrew G. Morgan" Date: Mon, 5 Feb 2001 06:50:41 +0000 Subject: 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.] --- doc/pam_appl.sgml | 10 +++++----- doc/pam_modules.sgml | 35 +++++++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 15 deletions(-) (limited to 'doc') 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. 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 -- cgit v1.2.3