1 files changed, 289 insertions, 0 deletions
diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml
new file mode 100644
index 00000000..792362ed
--- /dev/null
+++ b/doc/modules/pam_unix.sgml
@@ -0,0 +1,289 @@
+<!--
+   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+
+   Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
+-->
+
+<sect1>The Unix Password module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_unix
+
+<tag><bf>Author:</bf></tag>
+
+<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>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This is the standard Unix authentication module. It uses standard calls
+from the system's libraries to retrieve and set account information as
+well as authentication. Usually this is obtained from the /etc/passwd
+and the /etc/shadow file aswell if shadow is enabled.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/audit/
+
+<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)/). The <tt/audit/
+argument causes even more logging.
+
+Based on the following <tt/shadow/ elements:
+<tt/expire/;
+<tt/last_change/;
+<tt/max_change/;
+<tt/min_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/GNU Libc/ info documents. 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_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/audit/;
+<tt/use_first_pass/;
+<tt/try_first_pass/;
+<tt/nullok/;
+<tt/nodelay/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the authentication functions of this
+module <tt/syslog(3)/ more information on its actions. The <tt/audit/
+causes even more information to be logged.
+
+<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>unix_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.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The correct functionality of this module is dictated by having an
+appropriate <tt>/etc/nsswitch.conf</tt> file, the user
+databases specified there dictate the source of the authenticated
+user's record.
+<p>
+In its authentication mode, this module can be inserted as follows:
+<tscreen>
+<verb>
+#
+# Authenticate the user
+#
+login   auth  required       pam_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/audit/;
+<tt/nullok/;
+<tt/not_set_pass/;
+<tt/use_authtok/;
+<tt/try_first_pass/;
+<tt/use_first_pass/;
+<tt/md5/;
+<tt/bigcrypt/;
+<tt/shadow/;
+<tt/nis/;
+<tt/remember/
+
+<tag><bf>Description:</bf></tag>
+
+This part of the <tt/pam_unix/ module performs the task of updating
+the user's password.
+
+<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/ argument 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_unix/ 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)/. The <tt/audit/ argument causes
+even more information to be logged.
+
+<p>
+With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC
+for setting new passwords.
+
+<p>
+The <tt/remember/ argument takes one value. This is the number of most
+recent passwords to save for each user. These are saved in
+<tt>/etc/security/opasswd</tt> in order to force password change history
+and keep the user from alternating between the same password too frequently.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Standard usage:
+<tscreen>
+<verb>
+#
+# Change the users password
+#
+passwd   password   required   pam_unix.so
+</verb>
+</tscreen>
+
+<p>
+An example of the stacking of this module with respect to the
+pluggable password checking module, <tt/pam_cracklib/:
+<tscreen>
+<verb>
+#
+# Change the users password
+#
+passwd   password   required   pam_cracklib.so retry=3 minlen=6 difok=3
+passwd   password   required   pam_unix.so use_authtok nullok md5
+</verb>
+</tscreen>
+
+</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>
+#
+# session opening and closing
+#
+login	session	 required	pam_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->