Document the "binding" control flag. Also rewrite the section describing

the control flags to make it clearer, and correct a mistake in the "PAM
chain execution summary" table.

1 files changed, 54 insertions, 23 deletions

diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml
index da8e847ddd..52223f6ecd 100644
--- a/en_US.ISO8859-1/articles/pam/article.sgml
+++ b/en_US.ISO8859-1/articles/pam/article.sgml
@@ -99,7 +99,7 @@
     <section id="pam-trademarks">
       <title id="pam-trademarks.title">Trademarks</title>
 
-      <para>Sun, Sun Microsystems and Solaris are trademarks or
+      <para>Sun, Sun Microsystems, SunOS and Solaris are trademarks or
 	registered trademarks of Sun Microsystems, Inc.</para>
 
       <para>UNIX and The Open Group are trademarks or registered
@@ -580,36 +580,64 @@ sshd	password	required	pam_permit.so</programlisting>
 
       <variablelist>
 	<varlistentry>
+	  <term><literal>binding</literal></term>
+	  <listitem>
+	    <para>If the module succeeds and no earlier module in the
+	      chain has failed, the chain is immediately terminated
+	      and the request is granted.  If the module fails, the
+	      rest of the chain is executed, but the request is
+	      ultimately denied.</para>
+
+	    <para>This control flag was introduced by Sun in Solaris 9
+	      (SunOS 5.9), and is also supported by OpenPAM.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
 	  <term><literal>required</literal></term>
 	  <listitem>
-	    <para>Success is required, but the chain continues no
-	      matter what this module returns, so that later modules
-	      can override it.</para>
+	    <para>If the module succeeds, the rest of the chain is
+	      executed, and the request is granted unless some other
+	      module fails.  If the module fails, the rest of the
+	      chain is also executed, but the request is ultimately
+	      denied.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>requisite</literal></term>
 	  <listitem>
-	    <para>A negative result from this module will immediately
-	      terminate the chain and deny the request.</para>
+	    <para>If the module succeeds, the rest of the chain is
+	      executed, and the request is granted unless some other
+	      module fails.  If the module fails, the chain is
+	      immediately terminated and the request is denied.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>sufficient</literal></term>
 	  <listitem>
-	    <para>A positive result from this module will immediately
-	      terminate the chain and grant the request.  On failure,
-	      the chain continues.</para>
+	    <para>If the module succeeds and no earlier module in the
+	      chain has failed, the chain is immediately terminated
+	      and the request is granted.  If the module fails, the
+	      module is ignored and the rest of the chain is
+	      executed.</para>
+
+	    <para>As the semantics of this flag may be somewhat
+	      confusing, especially when it is used for the last
+	      module in a chain, it is recommended that the
+	      <literal>binding</literal> control flag be used instead
+	      if the implementation supports it.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>optional</literal></term>
 	  <listitem>
-	    <para>A negative result from this module will be
-	      ignored.</para>
+	    <para>The module is executed, but its result is ignored.
+ 	      If all modules in a chain are marked
+ 	      <literal>optional</literal>, all requests will always be
+ 	      granted.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
@@ -619,6 +647,7 @@ sshd	password	required	pam_permit.so</programlisting>
 	and invokes each of the modules listed in the chain, in the
 	order they are listed, until it reaches the end, or determines
 	that no further processing is necessary (either because a
+	<literal>binding</literal> or
 	<literal>sufficient</literal> module succeeded, or because a
 	<literal>requisite</literal> module failed.)  The request is
 	granted if and only if at least one module was invoked, and
@@ -852,8 +881,8 @@ sshd	password	required	pam_permit.so</programlisting>
 	which they were listed in the configuration.  After each call
 	to a service function, the module type and the error code
 	returned by the service function are used to determine what
-	happens next.  With a few exceptions, which we will discuss
-	later, the following table applies:</para>
+	happens next.  With a few exceptions, which we discuss below,
+	the following table applies:</para>
 
       <table>
 	<title>PAM chain execution summary</title>
@@ -872,22 +901,28 @@ sshd	password	required	pam_permit.so</programlisting>
 	  </thead>
 	  <tbody>
 	    <row>
+	      <entry colname="type">binding</entry>
+	      <entry colname="success">if (!fail) break;</entry>
+	      <entry colname="ignore">-</entry>
+	      <entry colname="other">fail = true;</entry>
+	    </row>
+	    <row>
 	      <entry colname="type">required</entry>
 	      <entry colname="success">-</entry>
 	      <entry colname="ignore">-</entry>
-	      <entry colname="other">fail = true</entry>
+	      <entry colname="other">fail = true;</entry>
 	    </row>
 	    <row>
 	      <entry colname="type">requisite</entry>
 	      <entry colname="success">-</entry>
 	      <entry colname="ignore">-</entry>
-	      <entry colname="other">fail = true, break</entry>
+	      <entry colname="other">fail = true; break;</entry>
 	    </row>
 	    <row>
 	      <entry colname="type">sufficient</entry>
-	      <entry colname="success">if (!fail) break</entry>
+	      <entry colname="success">if (!fail) break;</entry>
 	      <entry colname="ignore">-</entry>
-	      <entry colname="other">fail = true</entry>
+	      <entry colname="other">-</entry>
 	    </row>
 	    <row>
 	      <entry colname="type">optional</entry>
@@ -913,6 +948,7 @@ sshd	password	required	pam_permit.so</programlisting>
 	<literal>PAM_NEW_AUTHTOK_REQD</literal>.</para>
 
       <para>The second exception is that &man.pam.setcred.3; treats
+        <literal>binding</literal> and
 	<literal>sufficient</literal> modules as if they were
 	<literal>required</literal>.</para>
 
@@ -920,6 +956,7 @@ sshd	password	required	pam_permit.so</programlisting>
 	&man.pam.chauthtok.3; runs the entire chain twice (once for
 	preliminary checks and once to actually set the password), and
 	in the preliminary phase it treats
+        <literal>binding</literal> and
 	<literal>sufficient</literal> modules as if they were
 	<literal>required</literal>.</para>
     </section>
@@ -983,12 +1020,6 @@ sshd	password	required	pam_permit.so</programlisting>
 	certain groups of users from a particular service.</para>
     </section>
 
-    <section id="pam-modules-kerberosIV">
-      <title id="pam-modules-kerberosIV.title">&man.pam.kerberosIV.8;</title>
-
-      <para>The &man.pam.kerberosIV.8; module</para>
-    </section>
-
     <section id="pam-modules-krb5">
       <title id="pam-modules-krb5.title">&man.pam.krb5.8;</title>