- Clearly mark all unwritten sections.

- Correct a factual error in the "Transactions" section (which I
   wrote mostly off the top of my head)
 - Add a note about discrepancies in the original PAM paper to the (as
   yet unwritten) "PAM Application Programming" section.
 - Fill in the sample PAM application, and make room for an (as yet
   unwritten) sample PAM module.

Sponsored by:	DARPA, NAI Labs

en_US.ISO8859-1/articles/pam/article.sgml

@@ -8,6 +8,7 @@ FreeBSD Entities//EN"> %freebsd;
 %authors;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> %mailing-lists;
 <!ENTITY % not.published "IGNORE">
+<!ENTITY pam-sample-app SYSTEM "pam-sample-app.sgml">
 ]>
 
 <!--
@@ -383,7 +384,7 @@ sshd    password required       pam_permit.so</programlisting>
     <section>
       <title>Conventions</title>
 
-      <para>This section has not yet been written.</para>
+      <para><!--XXX-->This section has not yet been written.</para>
     </section>
   </section>
 
@@ -596,8 +597,10 @@ sshd    password required       pam_permit.so</programlisting>
     <section>
       <title>Transactions</title>
 
-      <para>The lifecycle of a typical PAM transaction goes like
-        this:</para>
+      <para>The lifecycle of a typical PAM transaction is described
+        below.  Note that if this any of these steps fails, the server
+        should report a suitable error message to the client and abort
+        the transaction.</para>
 
       <orderedlist>
         <listitem>
@@ -624,12 +627,15 @@ sshd    password required       pam_permit.so</programlisting>
 
 	<listitem>
 	  <para>The server calls <function>pam_authenticate</function>
-	    to authenticate the applicant.  If
-	    <function>pam_authenticate</function> returns something
-	    else than <literal>PAM_SUCCESS</literal> or
-	    <literal>PAM_NEW_AUTHTOK_REQD</literal>, it notifies the
-	    client that the request was denied, and aborts the
-	    transaction.</para>
+	    to authenticate the applicant.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The server calls <function>pam_acct_mgmt</function> to
+	    verify that the requested account is available and valid.
+	    The <function>pam_acct_mgmt</function> function will
+	    return <literal>PAM_NEW_AUTHTOK_REQD</literal> if the
+	    account's password has expired.</para>
 	</listitem>
 
 	<listitem>
@@ -637,14 +643,7 @@ sshd    password required       pam_permit.so</programlisting>
 	    <literal>PAM_NEW_AUTHTOK_REQD</literal>, the server now
 	    calls <function>pam_chauthtok</function> to force the
 	    client to change the authentication token for the
-	    requested account.  If this fails, the server aborts the
-	    transaction.</para>
-	</listitem>
-
-	<listitem>
-	  <para>The server calls <function>pam_acct_mgmt</function> to
-	    verify that the requested account is available.  If this
-	    fails, the server aborts the transaction.</para>
+	    requested account.</para>
 	</listitem>
 
 	<listitem>
@@ -787,34 +786,56 @@ sshd    password required       pam_permit.so</programlisting>
     <section>
       <title>Policies</title>
 
-      <para></para>
+      <para><!--XXX-->This section has not yet been written.</para>
     </section>
   </section>
 
   <section id="pam-modules">
     <title id="pam-modules.title">PAM Modules</title>
 
-    <para>This chapter briefly documents the various PAM modules that
-      exist in FreeBSD.</para>
+    <para><!--XXX-->This section has not yet been written.</para>
   </section>
 
   <section id="pam-appl-prog">
     <title id="pam-appl-prog.title">PAM Application Programming</title>
 
-    <para>This chapter describes how to integrate PAM into your
-      application.</para>
+    <para><!--XXX-->This section has not yet been written.</para>
+
+    <!--
+    
+      Note that while the original PAM paper includes a sample PAM
+      application that calls pam_open_session() before pam_setcred(),
+      the Linux-PAM documentation states that pam_setcred() must be
+      called first, which makes more sense.
+
+      Also note that the example in the paper calls setgid(),
+      initgroups() and setuid() itself rather than rely on
+      pam_setcred() to do it.
+      
+      -->
+    
   </section>
 
   <section id="pam-module-prog">
     <title id="pam-module-prog.title">PAM Module Programming</title>
 
-    <para>This chapter describes how to write PAM modules.</para>
+    <para><!--XXX-->This section has not yet been written.</para>
   </section>
 
   <appendix id="pam-sample-appl">
     <title id="pam-sample-appl.title">Sample PAM application</title>
 
-    <para>Source code for a minimal &man.su.1; workalike</para>
+    <para>The following is a minimal implementation of &man.su.1;
+    using PAM.  The conversation function has been omitted for
+    simplicity.</para>
+    
+    &pam-sample-app;
+  </appendix>
+
+  <appendix id="pam-sample-module">
+    <title id="pam-sample-module.title">Sample PAM module</title>
+
+    <para><!--XXX-->This section has not yet been written.</para>
   </appendix>
 
   <appendix id="pam-further">