From ea488580c42e8918445a945484de3c8a5addc761 Mon Sep 17 00:00:00 2001
From: "Andrew G. Morgan" <morgan@kernel.org>
Date: Tue, 20 Jun 2000 22:10:38 +0000
Subject: Initial revision

---
 doc/modules/pam_pwdb.sgml | 252 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 252 insertions(+)
 create mode 100644 doc/modules/pam_pwdb.sgml

(limited to 'doc/modules/pam_pwdb.sgml')

diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml
new file mode 100644
index 00000000..022cfe57
--- /dev/null
+++ b/doc/modules/pam_pwdb.sgml
@@ -0,0 +1,252 @@
+<!--
+   $Id$
+   
+   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+-->
+
+<sect1>The Password-Database module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_pwdb
+
+<tag><bf>Author:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt; <newline>
+and Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Authors.
+
+<tag><bf>Management groups provided:</bf></tag>
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+	
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires properly configured <tt/libpwdb/
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is a pluggable replacement for the <tt/pam_unix_../
+modules. It uses the generic interface of the <em/Password Database/
+library
+<tt><htmlurl
+url="http://linux.kernel.org/morgan/libpwdb/index.html"
+name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the accounting functions of this module
+<tt/syslog(3)/ more information on its actions. (Remaining arguments
+supported by the other functions of this module are silently ignored,
+but others are logged as errors through <tt/syslog(3)/).
+
+Based on the following <tt/pwdb_element/s:
+<tt/expire/;
+<tt/last_change/;
+<tt/max_change/;
+<tt/defer_change/;
+<tt/warn_change/,
+this module performs the task of establishing the status of the user's
+account and password. In the case of the latter, it may offer advice
+to the user on changing their password or, through the
+<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
+they have established a new password. The entries listed above are
+documented in the <em/Password Database Library Guide/ (see pointer
+above). Should the user's record not contain one or more of these
+entries, the corresponding <em/shadow/ check is not performed.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In its accounting mode, this module can be inserted as follows:
+<tscreen>
+<verb>
+#
+# Ensure users account and password are still active
+#
+login	account	 required	pam_pwdb.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/use_first_pass/;
+<tt/try_first_pass/;
+<tt/nullok/;
+<tt/nodelay/;
+<tt/likeauth/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the authentication functions of this
+module <tt/syslog(3)/ more information on its actions.
+
+<p>
+The default action of this module is to not permit the user access to
+a service if their <em/official/ password is blank. The <tt/nullok/
+argument overrides this default.
+
+<p>
+When given the argument <tt/try_first_pass/, before prompting the user
+for their password, the module first tries the previous stacked
+<tt/auth/-module's password in case that satisfies this module as
+well. The argument <tt/use_first_pass/ forces the module to use such a
+recalled password and will never prompt the user - if no password is
+available or the password is not appropriate, the user will be denied
+access.
+
+<p>
+The argument, <tt>nodelay</tt>, can be used to discourage the
+authentication component from requesting a delay should the
+authentication as a whole fail.  The default action is for the module
+to request a delay-on-failure of the order of one second.
+
+<p>
+Remaining arguments, supported by the other functions of this module,
+are silently ignored. Other arguments are logged as errors through
+<tt/syslog(3)/.
+
+<p>
+A helper binary, <tt>pwdb_chkpwd</tt>, is provided to check the user's
+password when it is stored in a read protected database.  This binary
+is very simple and will only check the password of the user invoking
+it.  It is called transparently on behalf of the user by the
+authenticating component of this module.  In this way it is possible
+for applications like <em>xlock</em> to work without being setuid-root.
+
+<p>
+The <tt>likeauth</tt> argument makes the module return the same value
+when called as a credential setting module and an authentication
+module.  This will help libpam take a sane path through the auth
+component of your configuration file.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The correct functionality of this module is dictated by having an
+appropriate <tt>/etc/pwdb.conf</tt> file, the user
+databases specified there dictate the source of the authenticated
+user's record.
+
+</descrip>
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/;
+<tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/;
+<tt/shadow/; <tt/radius/; <tt/unix/
+
+<tag><bf>Description:</bf></tag>
+
+This part of the <tt/pam_pwdb/ module performs the task of updating
+the user's password.  Thanks to the flexibility of <tt/libpwdb/ this
+module is able to move the user's password from one database to
+another, perhaps securing the user's database entry in a dynamic
+manner (<em/this is very ALPHA code at the moment!/) - this is the
+purpose of the <tt/shadow/, <tt/radius/ and <tt/unix/ arguments.
+
+<p>
+In the case of conventional unix databases (which store the password
+encrypted) the <tt/md5/ argument is used to do the encryption with the
+MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
+As an alternative to this, the <tt/bigcrypt/ argument can be used to
+encrypt more than the first 8 characters of a password with DEC's
+(Digital Equipment Cooperation) `C2' extension to the standard UNIX
+<tt/crypt()/ algorithm.
+
+<p>
+The <tt/nullok/ module is used to permit the changing of a password
+<em/from/ an empty one. Without this argument, empty passwords are
+treated as account-locking ones.
+
+<p>
+The argument <tt/use_first_pass/ is used to lock the choice of old and
+new passwords to that dictated by the previously stacked <tt/password/
+module.  The <tt/try_first_pass/ argument is used to avoid the user
+having to re-enter an old password when <tt/pam_pwdb/ follows a module
+that possibly shared the user's old password - if this old password is
+not correct the user will be prompted for the correct one.  The
+argument <tt/use_authtok/ is used to <em/force/ this module to set the
+new password to the one provided by the previously stacked
+<tt/password/ module (this is used in an example of the stacking of
+the <em/Cracklib/ module documented above).
+
+<p>
+The <tt/not_set_pass/ argument is used to inform the module that it is
+not to pay attention to/make available the old or new passwords from/to
+other (stacked) password modules.
+
+<p>
+The <tt/debug/ argument makes the password functions of this module
+<tt/syslog(3)/ more information on its actions. Other arguments may be
+logged as erroneous to <tt/syslog(3)/.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+An example of the stacking of this module with respect to the
+pluggable password checking module, <tt/pam_cracklib/, is given in
+that modules section above.
+</descrip>
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+No arguments are recognized by this module component. Its action is
+simply to log the username and the service-type to
+<tt/syslog(3)/. Messages are logged at the beginning and end of the
+user's session.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The use of the session modules is straightforward:
+<tscreen>
+<verb>
+#
+# pwdb - unix like session opening and closing
+#
+login	session	 required	pam_pwdb.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
-- 
cgit v1.2.3