Improve documentation of the sufficient and requisite control values. (Red Hat Bug...

diff --git a/ChangeLog b/ChangeLog
index 21f4e8a25ed8a7f6cbdd6d06b6ab1615dd348f83..07f9f8b9b2a8181fadd385d5a9b1aa14315e70fb 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,7 +1,12 @@
+2011-09-30  Tomas Mraz  <tm@t8m.info>
+
+       * doc/man/pam.conf-syntax.xml: Improve documentation of the
+       sufficient and requisite control values. (Red Hat Bug #742413)
+
 2011-08-25  Tomas Mraz  <tm@t8m.info>
 
        * modules/pam_access/pam_access.c (user_match): Fix the split
-         on @ in the user field. (Red Hat Bug #732081)
+       on @ in the user field. (Red Hat Bug #732081)
 
        * modules/pam_loginuid/pam_loginuid.c: Correct the FSF address.
 

diff --git a/doc/man/pam.conf-syntax.xml b/doc/man/pam.conf-syntax.xml
index bea84d91c8c91ba76d892d0a9205ef913b1fb8bb..da7cfb70fddf80dc5d09b3dff01e20664f13bca0 100644 (file)
--- a/doc/man/pam.conf-syntax.xml
+++ b/doc/man/pam.conf-syntax.xml
@@ -143,7 +143,8 @@
           <para>
             like <emphasis>required</emphasis>, however, in the case that
             such a module returns a failure, control is directly returned
-            to the application. The return value is that associated with
+            to the application or to the superior PAM stack.
+            The return value is that associated with
             the first required or requisite module to fail. Note, this flag
             can be used to protect against the possibility of a user getting
             the opportunity to enter a password over an unsafe medium. It is
@@ -158,14 +159,12 @@
         <term>sufficient</term>
         <listitem>
           <para>
-            success of such a module is enough to satisfy the
-            authentication requirements of the stack of modules (if a
-            prior <emphasis>required</emphasis> module has failed the
-            success of this one is <emphasis>ignored</emphasis>). A failure
-            of this module is not deemed as fatal to satisfying the
-            application that this type has succeeded. If the module succeeds 
-            the PAM framework returns success to the application immediately
-            without trying any other modules.
+            if such a module succeeds and no prior <emphasis>required</emphasis>
+            module has failed the PAM framework returns success to
+            the application or to the superior PAM stack immediately without
+            calling any further modules in the stack. A failure of a
+            <emphasis>sufficient</emphasis> module is ignored and processing
+            of the PAM module stack continues unaffected.
           </para>
         </listitem>
       </varlistentry>