Relevant BUGIDs: [tasks] 43507, 17426

Purpose of commit: documentation

Commit summary:
---------------
Generally more documentation with some cleanups and email address
sanitization.

20 files changed, 314 insertions, 120 deletions

diff --git a/doc/modules/README b/doc/modules/README
index df091939..448aefc7 100644
--- a/doc/modules/README
+++ b/doc/modules/README
@@ -10,4 +10,4 @@ used as a blank form for new module descriptions.
 Please feel free to submit amendments/comments etc. regarding these
 files to:
 
-	Andrew G. Morgan <morgan@parc.power.net>
+	Andrew G. Morgan <morgan@kernel.org>
diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml
index 061a8a21..008e49f6 100644
--- a/doc/modules/pam_cracklib.sgml
+++ b/doc/modules/pam_cracklib.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
    long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com>
 -->
 
diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml
index 6e1f2992..7d9df7e7 100644
--- a/doc/modules/pam_deny.sgml
+++ b/doc/modules/pam_deny.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The locking-out module
@@ -15,7 +15,7 @@
 pam_deny
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 current <bf/Linux-PAM/ maintainer
diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml
index 2bd97c09..4d3b4e84 100644
--- a/doc/modules/pam_filter.sgml
+++ b/doc/modules/pam_filter.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The filter module
@@ -17,7 +17,7 @@ pam_filter
 
 <tag><bf>Author:</bf></tag>
 
-Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 	
diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml
index 8c2c21d1..a9444733 100644
--- a/doc/modules/pam_ftp.sgml
+++ b/doc/modules/pam_ftp.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>Anonymous access module
@@ -15,7 +15,7 @@
 <tt/pam_ftp.so/
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 Author.
@@ -56,11 +56,11 @@ mode of access.
 
 This module intercepts the user's name and password. If the name is
 ``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up
-at the `<tt/&commat;/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/
-part; these pam-items being set accordingly. The username is set to
-``<tt/ftp/''.  In this case the module succeeds.  Alternatively, the
-module sets the <tt/PAM_AUTHTOK/ item with the entered password and
-fails.
+at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/
+part; these pam-items being set accordingly. The username
+(<tt/PAM_USER/) is set to ``<tt/ftp/''.  In this case the module
+succeeds.  Alternatively, the module sets the <tt/PAM_AUTHTOK/ item
+with the entered password and fails.
 
 <p>
 The behavior of the module can be modified with the following flags:
diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml
index 8251e3dd..0d8550d4 100644
--- a/doc/modules/pam_group.sgml
+++ b/doc/modules/pam_group.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The group access module
@@ -15,7 +15,7 @@
 <tt/pam_group/
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 Author.
diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml
index c1ed7a87..78ae95dc 100644
--- a/doc/modules/pam_mail.sgml
+++ b/doc/modules/pam_mail.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The mail module
@@ -15,7 +15,7 @@
 <tt/pam_mail/
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 Author
diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml
index 90564d89..b1aa664b 100644
--- a/doc/modules/pam_nologin.sgml
+++ b/doc/modules/pam_nologin.sgml
@@ -17,7 +17,7 @@
 <tag><bf>Author:</bf></tag>
 Written by Michael K. Johnson &lt;johnsonm@redhat.com&gt;<newline>
 (based on code taken from a module written by Andrew G. Morgan
-&lt;morgan@parc.power.net&gt;).
+&lt;morgan@kernel.org&gt;).
 
 <tag><bf>Maintainer:</bf></tag>
 Michael K. Johnson &lt;johnsonm@redhat.com&gt;
diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml
index 8b201b7c..fe616ac3 100644
--- a/doc/modules/pam_permit.sgml
+++ b/doc/modules/pam_permit.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The promiscuous module
@@ -15,7 +15,7 @@
 pam_permit
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan, &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan, &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 Linux-PAM maintainer.
diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml
index 00e55a9d..69885047 100644
--- a/doc/modules/pam_rhosts.sgml
+++ b/doc/modules/pam_rhosts.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The rhosts module
diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml
index e362a2a5..f6aa8a07 100644
--- a/doc/modules/pam_rootok.sgml
+++ b/doc/modules/pam_rootok.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>The root access module
@@ -15,7 +15,7 @@
 pam_rootok
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 <bf>Linux-PAM</bf> maintainer
diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml
index 7dd43feb..a1829c16 100644
--- a/doc/modules/pam_time.sgml
+++ b/doc/modules/pam_time.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>Time control
@@ -15,7 +15,7 @@
 <tt/pam_time/
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan <tt>&lt;morgan@parc.power.net&gt;</tt>
+Andrew G. Morgan <tt>&lt;morgan@kernel.org&gt;</tt>
 
 <tag><bf>Maintainer:</bf></tag>
 Author
diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml
index 71cb07e3..286cd3f8 100644
--- a/doc/modules/pam_unix.sgml
+++ b/doc/modules/pam_unix.sgml
@@ -1,5 +1,5 @@
 <!--
-   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 
    Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
 -->
diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml
index 2ca4cc82..4c2e3e18 100644
--- a/doc/modules/pam_warn.sgml
+++ b/doc/modules/pam_warn.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 -->
 
 <sect1>Warning logger module
@@ -15,7 +15,7 @@
 <tt/pam_warn/
 
 <tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
 
 <tag><bf>Maintainer:</bf></tag>
 Author.
diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml
index 1eb62743..8c07a8b7 100644
--- a/doc/modules/pam_wheel.sgml
+++ b/doc/modules/pam_wheel.sgml
@@ -1,7 +1,7 @@
 <!--
    $Id$
    
-   This file was written by Andrew G. Morgan <morgan@parc.power.net>
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
 	from notes provided by Cristian Gafton.
 -->
 
diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
index f033dff0..87c9e6e3 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.76 2001/05/26
+<date>DRAFT v0.76 2001/12/08
 <abstract>
 This manual documents what an application developer needs to know
 about the <bf>Linux-PAM</bf> library. It describes how an application
@@ -315,30 +315,62 @@ extern int pam_set_item(pam_handle_t *pamh, int item_type,
 
 <p><descrip>
 <tag><tt/PAM_SERVICE/</tag>
-     	The service name
+
+     	The service name (which identifies that PAM stack that
+     	<tt/libpam/ will use to authenticate the program).
 
 <tag><tt/PAM_USER/</tag>
-	The user name
+
+	The username of the entity under who's identity service will
+	be given. That is, following authentication, <tt/PAM_USER/
+	identifies the local entity that gets to use the
+	service. Note, this value can be mapped from something (eg.,
+	"<tt/anonymous/") to something else (eg. "<tt/guest119/") by
+	any module in the PAM stack. As such an application should
+	consult the value of <tt/PAM_USER/ after each call to a
+	<tt/pam_*()/ function.
 
 <tag><tt/PAM_USER_PROMPT/</tag>
+
 	The string used when prompting for a user's name. The default
-value for this string is ``Please enter username: ''.
+        value for this string is ``Please enter username: ''.
 
 <tag><tt/PAM_TTY/</tag>
+
 	The terminal name: prefixed by <tt>/dev/</tt> if it is a
-device file; for graphical, X-based, applications the value for this
-item should be the <tt/&dollar;DISPLAY/ variable.
+        device file; for graphical, X-based, applications the value
+        for this item should be the <tt/&dollar;DISPLAY/ variable.
 
 <tag><tt/PAM_RUSER/</tag>
-	The requesting user's username
+
+        The requesting entity: user's username for a locally
+	requesting user or a remote requesting user - generally an
+	application or module will attempt to supply the value that is
+	most strongly authenticated (a local account before a remote
+	one. The level of trust in this value is embodied in the
+	actual authentication stack associated with the application,
+	so it is ultimately at the discretion of the system
+	administrator. It should generally match the current
+	<tt/PAM_RHOST/ value. That is, "<tt/PAM_RUSER@PAM_RHOST/"
+	should always identify the requesting user. In some cases,
+	<tt/PAM_RUSER/ may be NULL. In such situations, it is unclear
+	who the requesting entity is.
 
 <tag><tt/PAM_RHOST/</tag>
-	The requesting hostname (the hostname of the machine from which
-	the <tt/PAM_RUSER/ is requesting service)
+
+	The requesting hostname (the hostname of the machine from
+	which the <tt/PAM_RUSER/ entity is requesting service). That
+	is "<tt/PAM_RUSER@PAM_RHOST/" does identify the requesting
+	user.  "<tt/luser@localhost/" or "<tt/evil@evilcom.com/" are
+	valid "<tt/PAM_RUSER@PAM_RHOST/" examples. In some
+	applications, <tt/PAM_RHOST/ may be NULL. In such situations,
+	it is unclear where the authentication request is originating
+	from.
 
 <tag><tt/PAM_CONV/</tag>
+
 	The conversation structure (see section <ref
-id="the-conversation-function" name="below">)
+        id="the-conversation-function" name="below">).
 
 <tag><tt/PAM_FAIL_DELAY/</tag> A function pointer to redirect
         centrally managed failure delays (see section <ref
@@ -358,7 +390,7 @@ section <ref id="the-failure-delay-function" name="below">).
 
 <p>
 A successful call to this function returns <tt/PAM_SUCCESS/.  However,
-the application should expect one of the following errors:
+the application should expect at least one the following errors:
 
 <p>
 <descrip>
@@ -1134,7 +1166,11 @@ current <tt/uid/ (userid) of the running process; the identity of the
 privilege granting user is the <tt/euid/ (effective userid) of the
 running process; the identity of the user, under whose name the
 service will be executed, is given by the contents of the
-<tt/PAM_USER/ <tt/pam_get_item(3)/.
+<tt/PAM_USER/ <tt/pam_get_item(3)/. Note, modules can change the
+values of <tt/PAM_USER/ and <tt/PAM_RUSER/ during any of the
+<tt/pam_*()/ library calls. For this reason, the application should
+take care to use the <tt/pam_get_item()/ every time it wishes to
+establish who the authenticated user is (or will currently be).
 
 <p>
 For network-serving databases and other applications that provide
@@ -1563,7 +1599,7 @@ purpose at the moment. Ideas/suggestions welcome!
 
 <p>
 This document was written by Andrew G. Morgan
-(morgan@transmeta.com) with many contributions from
+(morgan@kernel.org) with many contributions from
 <!-- insert credits here -->
 <!--
  an sgml list of people to credit for their contributions to Linux-PAM
@@ -1630,9 +1666,9 @@ credited for all the good work they have done.
 <sect>Copyright information for this document
 
 <p>
-Copyright (c) Andrew G. Morgan 1996-9.  All rights reserved.
+Copyright (c) Andrew G. Morgan 1996-9,2000-1.  All rights reserved.
 <newline>
-Email: <tt>&lt;morgan@transmeta.com&gt;</tt>
+Email: <tt>&lt;morgan@kernel.org&gt;</tt>
 
 <p>
 Redistribution and use in source and binary forms, with or without
diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml
index 3490b3a5..babccb06 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.76 2001/09/12
+<date>DRAFT v0.76 2001/12/08
 <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
@@ -1375,7 +1375,7 @@ needed.
 
 <p>
 This document was written by Andrew G. Morgan
-(<tt/morgan@transmeta.com/) with many contributions from
+(<tt/morgan@kernel.org/) with many contributions from
 <!-- insert credits here -->
 <!--
  an sgml list of people to credit for their contributions to Linux-PAM
@@ -1443,9 +1443,9 @@ credited for all the good work they have done.
 <sect>Copyright information for this document
 
 <p>
-Copyright (c) Andrew G. Morgan 1996, 1997.  All rights reserved.
+Copyright (c) Andrew G. Morgan 1996-9,2000-1.  All rights reserved.
 <newline>
-Email: <tt>&lt;morgan@transmeta.com&gt;</tt>
+Email: <tt>&lt;morgan@kernel.org&gt;</tt>
 
 <p>
 Redistribution and use in source and binary forms, with or without
diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml
index d24a53a3..160e9293 100644
--- a/doc/pam_source.sgml
+++ b/doc/pam_source.sgml
@@ -46,7 +46,7 @@ DAMAGE.
 
 <title>The Linux-PAM System Administrators' Guide
 <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.75 2001/03/18
+<date>DRAFT v0.76 2001/12/08
 <abstract>
 This manual documents what a system-administrator needs to know about
 the <bf>Linux-PAM</bf> library. It covers the correct syntax of the
@@ -103,7 +103,7 @@ locally with a system file, <tt>/etc/pam.conf</tt> (or a series of
 configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a
 user request via the locally available authentication modules. The
 modules themselves will usually be located in the directory
-<tt>/usr/lib/security</tt> and take the form of dynamically loadable
+<tt>/lib/security</tt> and take the form of dynamically loadable
 object files (see <tt/dlopen(3)/).
 
 <sect>Some comments on the text<label id="text-conventions">
@@ -122,11 +122,12 @@ directly from the text.
 <p>
 As an example of the above, where it is explicit, the text assumes
 that PAM loadable object files (the <em/modules/) are to be located in
-the following directory: <tt>/usr/lib/security/</tt>. However, Red Hat
-Linux, in agreement with the Linux File System Standard (the FSSTND),
-places these files in <tt>/lib/security</tt>. Please be careful to
-perform the necessary transcription when using the examples from the
-text.
+the following directory: <tt>/lib/security/</tt>. This is generally
+the location that seems to be compatible with the Linux File System
+Standard (the FSSTND). On Solaris, which has its own licensed version
+of PAM, and some other implementations of UN*X, these files can be
+found in <tt>/usr/lib/security</tt>. Please be careful to perform the
+necessary transcription when using the examples from the text.
 
 <sect>Overview<label id="overview-section">
 
@@ -513,10 +514,10 @@ The <tt/actionI/ can be a positive integer or one of the following
 tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and
 <tt/reset/.  A positive integer, <tt/J/, when specified as the action,
 can be used to indicate that the next <em/J/ modules of the current
-type will be skipped.  In this way, the administrator can develop a
-moderately sophisticated stack of modules with a number of different
-paths of execution.  Which path is taken can be determined by the
-reactions of individual modules.
+module-type will be skipped.  In this way, the administrator can
+develop a moderately sophisticated stack of modules with a number of
+different paths of execution.  Which path is taken can be determined
+by the reactions of individual modules.
 
 <p>
 <itemize>
@@ -553,7 +554,7 @@ transport protocol inherent to the client/server application.  With
 the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible
 for an application to be configured to support binary prompts with
 compliant clients, but to gracefully fall over into an alternative
-authentication mode for older, legacy, applications.  Flexible eh?
+authentication mode for older, legacy, applications.
 
 <tag> <tt/module-path/</tag>
 
@@ -561,8 +562,8 @@ The path-name of the dynamically loadable object file; <em/the
 pluggable module/ itself. If the first character of the module path is
 `<tt>/</tt>', it is assumed to be a complete path. If this is not the
 case, the given module path is appended to the default module path:
-<tt>/usr/lib/security</tt> (but see the notes <ref
-id="text-conventions" name="above">).
+<tt>/lib/security</tt> (but see the notes <ref id="text-conventions"
+name="above">).
 
 <tag> <tt/args/</tag>
 
@@ -740,10 +741,10 @@ setting (which is not a bad place to start!):
 #
 # default; deny access
 #
-OTHER	auth	 required	/usr/lib/security/pam_deny.so
-OTHER	account	 required	/usr/lib/security/pam_deny.so
-OTHER	password required	/usr/lib/security/pam_deny.so
-OTHER	session	 required	/usr/lib/security/pam_deny.so
+OTHER	auth	 required	pam_deny.so
+OTHER	account	 required	pam_deny.so
+OTHER	password required	pam_deny.so
+OTHER	session	 required	pam_deny.so
 </verb>
 </tscreen>
 Whilst fundamentally a secure default, this is not very sympathetic to
@@ -765,8 +766,8 @@ would provide a suitable warning to the administrator.
 #
 # default; wake up! This application is not configured
 #
-OTHER	auth	 required	/usr/lib/security/pam_warn.so
-OTHER	password required	/usr/lib/security/pam_warn.so
+OTHER	auth	 required	pam_warn.so
+OTHER	password required	pam_warn.so
 </verb>
 </tscreen>
 Having two ``<tt/OTHER auth/'' lines is an example of stacking.
@@ -779,12 +780,12 @@ corresponding default setup would be achieved with the following file:
 #
 # default configuration: /etc/pam.d/other
 #
-auth	 required	/usr/lib/security/pam_warn.so
-auth	 required	/usr/lib/security/pam_deny.so
-account	 required	/usr/lib/security/pam_deny.so
-password required	/usr/lib/security/pam_warn.so
-password required	/usr/lib/security/pam_deny.so
-session	 required	/usr/lib/security/pam_deny.so
+auth	 required	pam_warn.so
+auth	 required	pam_deny.so
+account	 required	pam_deny.so
+password required	pam_warn.so
+password required	pam_deny.so
+session	 required	pam_deny.so
 </verb>
 </tscreen>
 This is the only explicit example we give for an <tt>/etc/pam.d/</tt>
@@ -799,12 +800,12 @@ mimic the historically familiar Linux setup.
 <tscreen>
 <verb>
 #
-# default; standard UNIX access
+# default; standard UN*X access
 #
-OTHER	auth	 required	/usr/lib/security/pam_unix_auth.so
-OTHER	account	 required	/usr/lib/security/pam_unix_acct.so
-OTHER	password required	/usr/lib/security/pam_unix_passwd.so
-OTHER	session	 required	/usr/lib/security/pam_unix_session.so
+OTHER	auth	 required	pam_unix.so
+OTHER	account	 required	pam_unix.so
+OTHER	password required	pam_unix.so
+OTHER	session	 required	pam_unix.so
 </verb>
 </tscreen>
 In general this will provide a starting place for most applications.
@@ -821,13 +822,13 @@ may be subject to change or the application will be fixed.)
 <verb>
 #
 # ftpd; add ftp-specifics. These lines enable anonymous ftp over
-#       standard UNIX access (the listfile entry blocks access to
+#       standard UN*X access (the listfile entry blocks access to
 #	users listed in /etc/ftpusers)
 #
-ftpd	auth	sufficient  /usr/lib/security/pam_ftp.so
-ftpd	auth	required    /usr/lib/security/pam_unix_auth.so use_first_pass
-ftpd	auth	required    /usr/lib/security/pam_listfile.so \
-			onerr=succeed item=user sense=deny file=/etc/ftpusers
+ftpd	auth	sufficient  pam_ftp.so
+ftpd	auth	required    pam_unix_auth.so use_first_pass
+ftpd	auth	required    pam_listfile.so \
+	onerr=succeed item=user sense=deny file=/etc/ftpusers
 </verb>
 </tscreen>
 Note, the second line is necessary since the default entries are
@@ -837,15 +838,15 @@ Again, this is an example of authentication module stacking.  Note the
 use of the <tt/sufficient/ control-flag. It says that ``if this module
 authenticates the user, ignore the subsequent <tt/auth/
 modules''. Also note the use of the ``<tt/use_first_pass/''
-module-argument, this instructs the UNIX authentication module that it
-is not to prompt for a password but rely one already having been
-obtained by the ftp module.
+module-argument, this instructs the UN*X authentication module that it
+is not to prompt for a password but rely on one already having been
+obtained by the <tt/pam_ftp/ module.
 
 <sect>Security issues of Linux-PAM
 
 <p>
-This section will discuss good practices for using Linux-PAM in a
-secure manner.  <em>It is currently sadly lacking...suggestions are
+This section will discuss good practices for using PAM in a secure
+manner.  <em>It is currently sadly lacking...suggestions are
 welcome!</em>
 
 <sect1>If something goes wrong
@@ -906,10 +907,10 @@ Here's how you make your configs nice again:
 and then use vi to create a file called "other" in this
 directory.  It should contain the following four lines:
 
-    auth     required       pam_unix_auth.so
-    account  required       pam_unix_acct.so
-    password required       pam_unix_passwd.so
-    session  required       pam_unix_session.so
+    auth     required       pam_unix.so
+    account  required       pam_unix.so
+    password required       pam_unix.so
+    session  required       pam_unix.so
 
 Now you have the simplest possible PAM configuration that
 will work the way you're used to.  Everything should
@@ -990,7 +991,7 @@ the examples listed below.
 
 <p><descrip>
 
-<tag><tt>/usr/lib/libpam.so.*</tt></tag>
+<tag><tt>/lib/libpam.so.*</tt></tag>
 
 the shared library providing applications with access to
 <bf/Linux-PAM/.
@@ -999,7 +1000,7 @@ the shared library providing applications with access to
 
 the <bf/Linux-PAM/ configuration file.
 
-<tag><tt>/usr/lib/security/pam_*.so</tt></tag>
+<tag><tt>/lib/security/pam_*.so</tt></tag>
 
 the primary location for <bf/Linux-PAM/ dynamically loadable object
 files; the modules.
diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw
index 46db0013..45109f45 100644
--- a/doc/specs/draft-morgan-pam.raw
+++ b/doc/specs/draft-morgan-pam.raw
@@ -1,17 +1,18 @@
-PAM working group                 ##              A.G. Morgan
-Internet Draft:                   ##          October 6, 1999
-Document: draft-morgan-pam-07.txt ##
-Expires: June 13, 2000            ##
-Obsoletes: draft-morgan-pam-06.txt##
+Open-PAM working group            ##              A.G. Morgan
+Internet Draft:                   ##              Dec 8, 2001
+Document: draft-morgan-pam-08.txt ##
+Expires: June 8, 2002             ##
+Obsoletes: draft-morgan-pam-07.txt##
 
-## Pluggable Authentication Modules ##
+## Pluggable Authentication Modules (PAM) ##
 
 #$  Status of this memo
 
-This document is an draft specification. The latest version of this
-draft may be obtained from here:
+This document is a draft specification. Its contents are subject to
+change with revision. The latest version of this draft may be obtained
+from here:
 
-  http://linux.kernel.org/pub/linux/libs/pam/pre/doc/
+  http://www.kernel.org/pub/linux/libs/pam/pre/doc/
 
 As
 
@@ -187,12 +188,14 @@ The following control characters are only legal for exchanges between
 an agent and a client (it is the responsibility of the client to
 enforce this rule in the face of a rogue server):
 
-## 0x41     PAM_BPC_GETENV   - obtain client env.var ##
-## 0x42     PAM_BPC_PUTENV   - set client env.var    ##
-## 0x43     PAM_BPC_TEXT     - display message       ##
-## 0x44     PAM_BPC_ERROR    - display error message ##
-## 0x45     PAM_BPC_PROMPT   - echo'd text prompt    ##
-## 0x46     PAM_BPC_PASS     - non-echo'd text prompt##
+## 0x41     PAM_BPC_GETENV   - obtain client env.var  ##
+## 0x42     PAM_BPC_PUTENV   - set client env.var     ##
+## 0x43     PAM_BPC_TEXT     - display message        ##
+## 0x44     PAM_BPC_ERROR    - display error message  ##
+## 0x45     PAM_BPC_PROMPT   - echo'd text prompt     ##
+## 0x46     PAM_BPC_PASS     - non-echo'd text prompt ##
+## 0x46     PAM_BPC_STATUS   - ping all active clients##
+## 0x47     PAM_BPC_ABORT    - please abort session   ##
 
 Note, length is always equal to the total length of the binary
 prompt and represented by a network ordered unsigned 32 bit integer.
@@ -211,10 +214,10 @@ regexp:
 
 and has a specific form for each independent agent.
 
-o Agent_ids that do not contain an at-sign (@) are reserved to be
-  assigned by IANA (Internet Assigned Numbers Authority). Names of
-  this format MUST NOT be used without first registering with IANA.
-  Registered names MUST NOT contain an at-sign (@).
+o Agent_ids that do not contain an at-sign (@) are to be considered as
+  representing some authentication mode that is a "public
+  standard" see reference [#$R#{PAM_STD_AGENTIDS}]. Registered names
+  MUST NOT contain an at-sign (@).
 
 o Anyone can define additional agents by using names in the format
   name@domainname, e.g. "ouragent@example.com". The part following
@@ -248,8 +251,23 @@ Some client-server implementations (telnet for example) provide
 effective full tty connections. In these cases, the four simple text
 string prompting cases (see below) can be handled as in the primary
 login step. In other words, the server absorbs most of the overhead of
-propagating authentication messages. In these cases, there is special
-client/server support for handling binary prompts.
+propagating authentication messages. In these cases, there needs to be
+special client/server support for handling binary prompts.
+
+In some circumstances, a legacy network transfer protocol can carry
+authentication information. In such cases, a desire to support legacy
+clients (with no client-side support for PAM) will neccessitate the
+'hardcoding' of an agent protocol into the server application. Whilst
+against the spirit of PAM, this special casing can be managed by the
+server's 'conversation function' (see below). The guiding principle
+when implementing such support is for the application developer to
+relegate the authentication process to the PAM module -- simply
+performing a transcription of data from binary-prompt to legacy
+network 'packet' and visa-versa for propagating replies back to the
+driving PAM module. A common case of this is with network protocols
+that define an initialization packet of "user+password". In such cases
+one should attempt to support the "userpass" agent-id and its defined
+protocol.
 
 #$  Defined interfaces for information flow
 
@@ -318,8 +336,8 @@ and a single fail):
 ## (C)  | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_OK;}         ##
 ##      | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_FAIL;}       ##
 ## --------------------------------------------------------------- ##
-## (D)  | {11;PAM_BPC_TEXT;"ouch!"}      | {5;PAM_BPC_OK;}         ##
-##      | {11;PAM_BPC_TEXT;"ouch!"}      | {5;PAM_BPC_FAIL;}       ##
+## (D)  | {11;PAM_BPC_ERROR;"ouch!"}     | {5;PAM_BPC_OK;}         ##
+##      | {11;PAM_BPC_ERROR;"ouch!"}     | {5;PAM_BPC_FAIL;}       ##
 ## --------------------------------------------------------------- ##
 ## (E)  | {13;PAM_BPC_PROMPT;"login: "}  | {9;PAM_BPC_OK;"joe"}    ##
 ##      | {13;PAM_BPC_PROMPT;"login: "}  | {6;PAM_BPC_OK;""}       ##
@@ -570,6 +588,23 @@ should go to some effort to lower its level of privilege. It remains
 the responsibility of the applicant and the client to ensure that it
 is not compromised by a rogue agent.
 
+#$$$$  Status of agents
+
+	int pamc_status(pamc_handle_t *pch, pamc_bp_t *prompt_p);
+
+At any time, the client may ping all active agents for their status
+(with a PAM_BPC_STATUS binary prompt). If any agent replies with
+PAM_BPC_ABORT, the client is responsible for terminating the
+connection to the server and then terminating all agents with a call
+to pamc_end(). In such cases, the return value of pamc_status() is
+PAM_BPC_FALSE.
+
+If the return status of pamc_status() is PAM_BPC_TRUE and *prompt_p is
+non-NULL, then an agent is requesting access to a server module.
+
+XXX - how this information gets propagated to the server, and
+      ultimately to the server's module is yet to be determined.
+
 #$$$$  Termination of agents
 
 When closing the authentication session and severing the connection
@@ -627,6 +662,11 @@ decision about the authentication method adopted by the server.
 	pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)
 	pam_get_env(pam_handle_t *pamh, const char *varname)
 	pam_strerror(pam_handle_t *pamh, int pam_errno)
+
+Event driven support (XXX work in progress)
+
+	pam_register_event() - app or module associates an event poller/handler
+	pam_select_event()   - query for any outstanding event and act on any
 ]
 
 #$$$ Server <-> libpam
@@ -677,6 +717,24 @@ functions provided to libpam by each module
 		pam_sm_chauthtok
 ]
 
+#$$$ The conversation function
+
+The server application, as part of its initialization of libpam,
+provides a conversation function for use by modules and libpam. The
+purpose of the conversation function is to enable direct communication
+to the applicant ultimately via the client and selected agents.
+
+[ this section will contain a definition for the conversation
+  function, the conversation structure (appdata etc), and legitimate
+  return codes for the application supplied function.
+
+	PAM_SUCCESS           - ok conversation completed
+	PAM_CONV_ERR          - conversation failed
+	PAM_CONV_AGAIN        - application needs control to complete conv
+	PAM_CONV_RECONSIDER   - application believes module should check if
+	                        it still needs to converse for this info
+ ]
+
 #$  Security considerations
 
 This document is devoted to standardizing authentication
@@ -693,10 +751,14 @@ The email list for discussing issues related to this document is
 [#{OSF_RFC_PAM}]  OSF RFC 86.0, "Unified Login with Pluggable Authentication
      Modules (PAM)", October 1995
 
+[#{PAM_STD_AGENTIDS}] Definitions for standard agents, "REGISTERED
+     AGENTS AND THEIR AGENT-ID'S", to be found here:
+
+## http://www.kernel.org/pub/linux/libs/pam/pre/doc/std-agent-ids.txt ##
+
 #$  Author's Address
 
 Andrew G. Morgan
-Email: morgan@ftp.kernel.org
+Email: morgan@kernel.org
 
 ## $Id$ ##
-
diff --git a/doc/specs/std-agent-id.raw b/doc/specs/std-agent-id.raw
new file mode 100644
index 00000000..d5fbdd56
--- /dev/null
+++ b/doc/specs/std-agent-id.raw
@@ -0,0 +1,95 @@
+PAM working group                 ##              A.G. Morgan
+
+## $Id$ ##
+
+## Pluggable Authentication Modules ##
+
+## REGISTERED AGENTS AND THEIR AGENT-ID'S ##
+
+#$ Purpose of this document
+
+#$$#{definition}  Definition of an agent-id
+
+The most complete version of a "PAM agent-id" is contained in this
+reference [#$R#{PAM_RFC2}]. A copy of a recent definition is
+reproduced here for convenience. The reader is recommended to consult
+reference [#{PAM_RFC2}] for definitions of other terms that are
+used in this document.
+
+## -------------- ##
+
+The agent_id is a sequence of characters satisfying the following
+regexp:
+
+	/^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/
+
+and has a specific form for each independent agent.
+
+o Agent_ids that do not contain an at-sign (@) are to be considered as
+  representing some authentication mode that is a "public
+  standard". Registered names MUST NOT contain an at-sign (@).
+
+o Anyone can define additional agents by using names in the format
+  name@domainname, e.g. "ouragent@example.com". The part following
+  the at-sign MUST be a valid fully qualified internet domain name
+  [RFC-1034] controlled by the person or organization defining the
+  name. (Said another way, if you control the email address that
+  your agent has as an identifier, they you are entitled to use
+  this identifier.) It is up to each domain how it manages its local
+  namespace.
+
+## -------------- ##
+
+#$ Registered agent-id's
+
+The structure of this section is a single subsection for each
+registered agent-id. This section includes a full definition of binary
+prompts accepted by the agent and example responses of said
+agent. Using the defining section alone, it should be possible for a
+third party to create a conforming agent and modules that can
+interoperate with other implementations of these objects.
+
+*$ "userpass" - the user+password agent
+
+Many legacy authentication systems are hardcoded to support one and
+only one authentication method. Namely,
+
+   username: joe
+   password: <secret>
+
+Indeed, this authentication method is often embedded into parts of the
+transport protocol. The "user+password" agent with PAM agent-id:
+
+   "userpass"
+
+Is intended to support this legacy authentication scheme. The protocol
+for binary prompt exchange with this 'standard agent' is as follows:
+
+Case 1: module does not know the username, but expects the agent to
+ obtain this information and also the user's password:
+
+   module: {LENGTH;PAM_BP_SELECT;userpass;'/'}
+   agent: {}
+
+Case 2: module has suggested username, but would like agent to confirm
+ it and gather password:
+
+   module: {}
+   agent: {}
+
+Case 3: module knows username and will not permit the agent to change it:
+
+   module: {}
+   agent: {}
+
+#$  References
+
+[#{PAM_RFC2}] Internet draft, "Pluggable Authentication Modules
+  (PAM)", available here:
+
+# http://linux.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt #
+
+#$  Author's Address
+
+Andrew G. Morgan
+Email: morgan@kernel.org