New upstream version 0.76

70 files changed, 0 insertions, 13113 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
deleted file mode 100644
index 7ac74f9d..00000000
--- a/doc/.cvsignore
+++ /dev/null
@@ -1,2 +0,0 @@
-pam.sgml
-MODULES-SGML
diff --git a/doc/CREDITS b/doc/CREDITS
deleted file mode 100644
index df0eb599..00000000
--- a/doc/CREDITS
+++ /dev/null
@@ -1,49 +0,0 @@
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id$
-  -->
-Chris Adams,
-Peter Allgeyer,
-Tim Baverstock,
-Tim Berger,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Seth Chaiklin,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Emmanuel Galanos,
-Brad M. Garcia,
-Eric Hester,
-Michel D'Hooge,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Olaf Kirch,
-Marcin Korzonek,
-Stephen Langasek,
-Nicolai Langfeldt,
-Elliot Lee,
-Luke Kenneth Casson Leighton,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Robert Milkowski,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-Jan Rekorajski,
-Erik Troan,
-Theodore Ts'o,
-Jeff Uphoff,
-Myles Uyema,
-Savochkin Andrey Vladimirovich,
-Ronald Wahl,
-David Wood,
-John Wilmes,
-Joseph S. D. Yao
-and
-Alex O.  Yuriev.
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index 63c11fbf..00000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,167 +0,0 @@
-
-### $Id$
-
-include ../Make.Rules
-
-#######################################################
-
-FILES=pam pam_appl pam_modules
-FSRCS=pam.sgml pam_appl.sgml pam_modules.sgml
-
-TEXTS=txts/pam.txt txts/pam_appl.txt txts/pam_modules.txt
-HTMLS=html/pam.html html/pam_appl.html html/pam_modules.html
-PSFILES=ps/pam.ps ps/pam_appl.ps ps/pam_modules.ps
-PDFFILES=pdf/pam.pdf ps/pam_appl.pdf ps/pam_modules.pdf
-
-MODULES=$(shell ls modules/*.sgml)
-
-#######################################################
-
-dummy:
-	@echo "Making the documentation..."
-	@$(MAKE) all
-
-# note, at this time we don't include pdf files by default, but you
-# can type make pdf in this directory and see what happens in the pdf
-# subdirectory.
-
-all: htmls texts postscript
-
-htmls: $(HTMLS)
-
-$(HTMLS) : $(FSRCS)
-ifeq ($(HAVE_SGML2HTML),yes)
-	@for i in $(FILES) ; do \
-	if [ ! -f "html/$$i.html" ] || [ "$$i.sgml" -nt "html/$$i.html" ]; \
-	then \
-		cd html ; sgml2html ../$$i ; \
-		if [ $$? -ne 0 ]; then exit 1 ; fi ; \
-		cd .. ; \
-	fi ; \
-	done
-else
-	@echo XXX - you do not have the sgml2html binary installed
-endif
-
-texts: $(TEXTS)
-
-$(TEXTS) : $(FSRCS)
-ifeq ($(HAVE_SGML2TXT),yes)
-	@for i in $(FILES) ; do \
-		if [ ! -f "txts/$$i.txt" ] \
-				|| [ "$$i.sgml" -nt "txts/$$i.txt" ]; then \
-			cd txts ; sgml2txt ../$$i ; cd .. ; \
-		fi ; \
-	done
-else
-	@echo XXX - you do not have the sgml2txt binary installed
-endif
-
-postscript: $(PSFILES)
-
-$(PSFILES): $(FSRCS)
-ifneq ($(PSER),)
-	@for i in $(FILES) ; do \
-	if [ ! -f "ps/$$i.ps" ] || [ "$$i.sgml" -nt "ps/$$i.ps" ]; then \
-		cd ps ; $(PSER) ../$$i ; cd .. ; \
-	fi ; \
-	done
-else
-	@echo XXX - neither sgml2ps nor sgml2latex binaries are installed
-endif
-
-pdf: $(PDFFILES)
-
-$(PDFFILES) : $(PSFILES)
-ifeq ($(HAVE_PS2PDF),yes)
-	@for i in $(FILES) ; do \
-	if [ ! -f "pdf/$$i.pdf" ] || [ "ps/$$i.ps" -nt "ps/$$i.pdf" ]; then \
-		ps2pdf ps/$$i.ps pdf/$$i.pdf ; \
-	fi ; \
-	done
-else
-	@echo XXX - ps2pdf is not installed
-endif
-
-pam.sgml: pam_source.sgml MODULES-SGML CREDITS
-	@sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' pam_source.sgml | sed -e '/^<!\-\- insert\-file CREDITS \-\->/r CREDITS' > pam.sgml
-
-MODULES-SGML: $(MODULES)
-	@echo 'Building module text from files in modules/*.sgml'
-	@rm -f MODULES-SGML
-	@echo '<!-- modules included:' > MODULES-SGML
-	@ls modules/*.sgml >> MODULES-SGML
-	@echo '  and that is all -->' >> MODULES-SGML
-	@cat modules/*.sgml >> MODULES-SGML
-
-extraclean: clean
-
-remove:
-	cd man && for file in *.3 ; do \
-	  rm -f $(FAKEROOT)$(MANDIR)/man3/$$file ; \
-	done
-	cd man && for file in *.8 ; do \
-	  rm -f $(FAKEROOT)$(MANDIR)/man8/$$file ; \
-	done
-	cd txts && for file in *.txt; do \
-	  rm -f $(FAKEROOT)$(DOCDIR)/text/$$file ; \
-	done
-	cd ps && for file in *.ps; do \
-	  rm -f $(FAKEROOT)$(DOCDIR)/ps/$$file  ; \
-	done
-	cd html && for file in *.html; do \
-	  rm -f $(FAKEROOT)$(DOCDIR)/html/$$file ; \
-	done
-
-install: all
-ifeq ($(HAVE_SGML2TXT),yes)
-	mkdir -p $(FAKEROOT)$(DOCDIR)/text
-	for file in txts/*.txt; do \
-	  install -m 644 $$file $(FAKEROOT)$(DOCDIR)/text ; \
-	done
-endif
-ifneq ($(PSER),)
-	mkdir -p $(FAKEROOT)$(DOCDIR)/ps
-	for file in ps/*.ps; do \
-	  install -m 644 $$file $(FAKEROOT)$(DOCDIR)/ps  ; \
-	done
-	ifeq ($(HAVE_PS2PDF),yes)
-		mkdir -p $(FAKEROOT)$(DOCDIR)/pdf
-		for file in pdf/*.pdf; do \
-		  install -m 644 $$file $(FAKEROOT)$(DOCDIR)/pdf  ; \
-		done
-	endif
-endif
-ifeq ($(HAVE_SGML2HTML),yes)
-	mkdir -p $(FAKEROOT)$(DOCDIR)/html
-	for file in html/*.html; do \
-	  install -m 644 $$file $(FAKEROOT)$(DOCDIR)/html ; \
-	done
-endif
-	mkdir -p $(FAKEROOT)$(MANDIR)/man3
-	mkdir -p $(FAKEROOT)$(MANDIR)/man8
-	for file in man/*.3 ; do \
-	  install -m 644 $$file $(FAKEROOT)$(MANDIR)/man3 ; \
-	done
-	for file in man/*.8 ; do \
-	  install -m 644 $$file $(FAKEROOT)$(MANDIR)/man8 ; \
-	done
-
-spec: specs/draft-morgan-pam.raw
-	cd specs/formatter && $(MAKE)
-	specs/formatter/padout < specs/draft-morgan-pam.raw > specs/draft-morgan-pam-current.txt
-
-releasedocs: all spec
-	tar zvfc Linux-PAM-$(MAJOR_REL).$(MINOR_REL)-docs.tar.gz --exclude CVS  html ps txts specs/draft-morgan-pam-current.txt
-
-clean:
-	rm -f *~ *.bak
-	rm -f html/pam*.html
-	rm -f man/*~
-	rm -f $(TEXTS)
-	rm -f $(PSFILES) ps/missfont.log
-	rm -f pdf/*.pdf
-	rm -f MODULES-SGML pam.sgml
-	rm -f specs/draft-morgan-pam-current.txt
-	$(MAKE) -C specs/formatter clean
-
diff --git a/doc/NOTES b/doc/NOTES
deleted file mode 100644
index b0f40d47..00000000
--- a/doc/NOTES
+++ /dev/null
@@ -1,16 +0,0 @@
-Things to be added:
-
-@ modules:
-@ application:
-
-	use of
-		'user' = user to become,
-		'uid' = user requesting service
-		'euid' = privilege of current process.
-
-@ sysadmin:
-
-	included modules:
-		behavior
-	non-included modules:
-		behavior/pointers.
diff --git a/doc/figs/pam_orient.txt b/doc/figs/pam_orient.txt
deleted file mode 100644
index a8b745a1..00000000
--- a/doc/figs/pam_orient.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-
-
-
-	 +----------------+
-	 | application: X |
-         +----------------+	  /  +----------+     +================+
-       	 | authentication-[---->--\--] Linux-   |--<--| /etc/pam.conf  |
-	 |       +        [----<--/--] 	 PAM    |     |================|
-	 |[conversation()][--+    \  |          |     | X auth .. a.so |
-	 +----------------+  |    /  +-n--n-----+     | X auth .. b.so |
-	 |                |  |       __|  |           |           _____/
-	 |  service user  |  A      |  	  |           |____,-----' 
-	 |                |  |      V  	  A	        	   
-	 +----------------+  +------|-----|---------+ -----+------+
-	                        +---u-----u----+    |	   |	  |
-			        |   auth....   |--[ a ]--[ b ]--[ c ]
-				+--------------+
-				|   acct....   |--[ b ]--[ d ]
-				+--------------+
-				|   password   |--[ b ]--[ c ]
-				+--------------+
-				|   session    |--[ e ]--[ c ]
-				+--------------+
\ No newline at end of file
diff --git a/doc/html/.cvsignore b/doc/html/.cvsignore
deleted file mode 100644
index 3b358a3a..00000000
--- a/doc/html/.cvsignore
+++ /dev/null
@@ -1 +0,0 @@
-pam*.html
\ No newline at end of file
diff --git a/doc/html/index.html b/doc/html/index.html
deleted file mode 100644
index 1ffd7e38..00000000
--- a/doc/html/index.html
+++ /dev/null
@@ -1,21 +0,0 @@
-
-<HTML>
-<HEAD>
-<TITLE>Linux-PAM - Pluggable Authentication Modules for Linux</TITLE>
-</HEAD>
-<BODY>
-
-<p>
-Here is the documentation for Linux-PAM. As you will see it is
-currently not complete. However, in order of decreasing length:
-
-<ul>
-<li> <a href="pam.html">The System Administrators' Guide</a>
-<li> <a href="pam_modules.html">The Module Writers' Manual</a>
-<li> <a href="pam_appl.html">The Application developers' Manual</a>
-</ul>
-
-<hr>
-<p>
-REVISION: <tt>$Id$</tt>
-</BODY>
diff --git a/doc/man/pam.8 b/doc/man/pam.8
deleted file mode 100644
index 939a0fe9..00000000
--- a/doc/man/pam.8
+++ /dev/null
@@ -1,369 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7,2001 <morgan@kernel.org>
-.TH PAM 8 "2001 Jan 20" "Linux-PAM 0.74" "Linux-PAM Manual"
-.SH NAME
-
-Linux-PAM \- Pluggable Authentication Modules for Linux
-
-.SH SYNOPSIS
-.B /etc/pam.conf
-.sp 2
-.SH DESCRIPTION
-
-This manual is intended to offer a quick introduction to
-.BR Linux-PAM ". "
-For more information the reader is directed to the
-.BR "Linux-PAM system administrators' guide".
-
-.sp
-.BR Linux-PAM
-Is a system of libraries that handle the authentication tasks of
-applications (services) on the system.  The library provides a stable
-general interface (Application Programming Interface - API) that
-privilege granting programs (such as
-.BR login "(1) "
-and
-.BR su "(1)) "
-defer to to perform standard authentication tasks.
-
-.sp
-The principal feature of the PAM approach is that the nature of the
-authentication is dynamically configurable.  In other words, the
-system administrator is free to choose how individual
-service-providing applications will authenticate users. This dynamic
-configuration is set by the contents of the single
-.BR Linux-PAM
-configuration file
-.BR /etc/pam.conf "."
-Alternatively, the configuration can be set by individual
-configuration files located in the
-.B /etc/pam.d/
-directory.
-.IB "The presence of this directory will cause " Linux-PAM " to ignore"
-.BI /etc/pam.conf "."
-
-.sp
-From the point of view of the system administrator, for whom this
-manual is provided, it is not of primary importance to understand the
-internal behavior of the
-.BR Linux-PAM
-library.  The important point to recognize is that the configuration
-file(s)
-.I define
-the connection between applications
-.BR "" "(" services ")"
-and the pluggable authentication modules
-.BR "" "(" PAM "s)"
-that perform the actual authentication tasks.
-
-.sp
-.BR Linux-PAM
-separates the tasks of
-.I authentication
-into four independent management groups:
-.BR "account" " management; "
-.BR "auth" "entication management; "
-.BR "password" " management; "
-and
-.BR "session" " management."
-(We highlight the abbreviations used for these groups in the
-configuration file.)
-
-.sp
-Simply put, these groups take care of different aspects of a typical
-user's request for a restricted service:
-
-.sp
-.BR account " - "
-provide account verification types of service: has the user's password
-expired?; is this user permitted access to the requested service?
-
-.br
-.BR auth "entication - "
-establish the user is who they claim to be. Typically this is via some
-challenge-response request that the user must satisfy: if you are who
-you claim to be please enter your password.  Not all authentications
-are of this type, there exist hardware based authentication schemes
-(such as the use of smart-cards and biometric devices), with suitable
-modules, these may be substituted seamlessly for more standard
-approaches to authentication - such is the flexibility of
-.BR Linux-PAM "."
-
-.br
-.BR password " - "
-this group's responsibility is the task of updating authentication
-mechanisms. Typically, such services are strongly coupled to those of
-the
-.BR auth
-group. Some authentication mechanisms lend themselves well to being
-updated with such a function. Standard UN*X password-based access is
-the obvious example: please enter a replacement password.
-
-.br
-.BR session " - "
-this group of tasks cover things that should be done prior to a
-service being given and after it is withdrawn. Such tasks include the
-maintenance of audit trails and the mounting of the user's home
-directory. The
-.BR session
-management group is important as it provides both an opening and
-closing hook for modules to affect the services available to a user.
-
-.SH The configuration file(s)
-
-When a
-.BR Linux-PAM
-aware privilege granting application is started, it activates its
-attachment to the PAM-API.  This activation performs a number of
-tasks, the most important being the reading of the configuration file(s):
-.BR /etc/pam.conf "."
-Alternatively, this may be the contents of the
-.BR /etc/pam.d/
-directory.
-
-These files list the
-.BR PAM "s"
-that will do the authentication tasks required by this service, and
-the appropriate behavior of the PAM-API in the event that individual
-.BR PAM "s "
-fail.
-
-.sp
-The syntax of the
-.B /etc/pam.conf
-configuration file is as follows. The file is made
-up of a list of rules, each rule is typically placed on a single line,
-but may be extended with an escaped end of line: `\\<LF>'. Comments
-are preceded with `#' marks and extend to the next end of line.
-
-.sp
-The format of each rule is a space separated collection of tokens, the
-first three being case-insensitive:
-
-.sp
-.br
-.BR "   service  type  control  module-path  module-arguments"
-
-.sp
-The syntax of files contained in the
-.B /etc/pam.d/
-directory, are identical except for the absence of any
-.I service 
-field. In this case, the
-.I service
-is the name of the file in the
-.B /etc/pam.d/
-directory. This filename must be in lower case.
-
-.sp
-An important feature of
-.BR Linux-PAM ", "
-is that a number of rules may be
-.I stacked
-to combine the services of a number of PAMs for a given authentication
-task.
-
-.sp
-The
-.BR service
-is typically the familiar name of the corresponding application:
-.BR login
-and 
-.BR su
-are good examples. The
-.BR service "-name, " other ", "
-is reserved for giving
-.I default
-rules.  Only lines that mention the current service (or in the absence
-of such, the
-.BR other
-entries) will be associated with the given service-application.
-
-.sp
-The
-.BR type
-is the management group that the rule corresponds to. It is used to
-specify which of the management groups the subsequent module is to
-be associated with. Valid entries are:
-.BR account "; "
-.BR auth "; "
-.BR password "; "
-and
-.BR session "."
-The meaning of each of these tokens was explained above.
-
-.sp
-The third field,
-.BR control ", "
-indicates the behavior of the PAM-API should the module fail to
-succeed in its authentication task. There are two types of syntax for
-this control field: the simple one has a single simple keyword; the
-more complicated one involves a square-bracketed selection of
-.B value=action
-pairs.
-
-.sp
-For the simple (historical) syntax valid
-.BR control
-values are:
-.BR requisite
-- failure of such a PAM results in the immediate termination of the
-authentication process;
-.BR required
-- failure of such a PAM will ultimately lead to the PAM-API returning
-failure but only after the remaining
-.I stacked
-modules (for this
-.BR service
-and
-.BR type ")"
-have been invoked;
-.BR sufficient
-- success of such a module is enough to satisfy the authentication
-requirements of the stack of modules (if a prior
-.BR required
-module has failed the success of this one is
-.IR ignored "); "
-.BR optional
-- the success or failure of this module is only important if it is the
-only module in the stack associated with this
-.BR service "+" type "."
-
-.sp
-For the more complicated syntax valid
-.B control
-values have the following form:
-.sp
-.RB  [value1=action1 value2=action2 ...]
-.sp
-Where
-.B valueN
-corresponds to the return code from the function invoked in the module
-for which the line is defined. It is selected from one of these:
-.BR success ;
-.BR open_err ;
-.BR symbol_err ;
-.BR service_err ;
-.BR system_err ;
-.BR buf_err ;
-.BR perm_denied ;
-.BR auth_err ;
-.BR cred_insufficient ;
-.BR authinfo_unavail ;
-.BR user_unknown ;
-.BR maxtries ;
-.BR new_authtok_reqd ;
-.BR acct_expired ;
-.BR session_err ;
-.BR cred_unavail ;
-.BR cred_expired ;
-.BR cred_err ;
-.BR no_module_data ;
-.BR conv_err ;
-.BR authtok_err ;
-.BR authtok_recover_err ;
-.BR authtok_lock_busy ;
-.BR authtok_disable_aging ;
-.BR try_again ;
-.BR ignore ;
-.BR abort ;
-.BR authtok_expired ;
-.BR module_unknown ;
-.BR bad_item "; and"
-.BR default .
-The last of these,
-.BR default ,
-implies 'all
-.BR valueN 's
-not mentioned explicitly. Note, the full list of PAM errors is
-available in /usr/include/security/_pam_types.h . The
-.B actionN
-can be: an unsigned integer, 
-.BR J ,
-signifying an action of 'jump over the next J modules in the stack';
-or take one of the following forms:
-.br
-.B ignore
-- when used with a stack of modules, the module's return status will
-not contribute to the return code the application obtains;
-.br
-.B bad 
-- this action indicates that the return code should be thought of as
-indicative of the module failing. If this module is the first in the
-stack to fail, its status value will be used for that of the whole
-stack.
-.br
-.B die
-- equivalent to bad with the side effect of terminating the module
-stack and PAM immediately returning to the application.
-.br
-.B ok
-- this tells PAM that the administrator thinks this return code
-should contribute directly to the return code of the full stack of
-modules. In other words, if the former state of the stack would lead
-to a return of
-.BR PAM_SUCCESS ,
-the module's return code will override this value. Note, if the former
-state of the stack holds some value that is indicative of a modules
-failure, this 'ok' value will not be used to override that value.
-.br
-.B done
-- equivalent to ok with the side effect of terminating the module
-stack and PAM immediately returning to the application.
-.br
-.B reset
-- clear all memory of the state of the module stack and start again
-with the next stacked module.
-
-.sp
-.BR module-path
-- this is either the full filename of the PAM to be used by the
-application (it begins with a '/'), or a relative pathname from the
-default module location:
-.BR /lib/security/ .
-
-.sp
-.BR module-arguments
-- these are a space separated list of tokens that can be used to
-modify the specific behavior of the given PAM. Such arguments will be
-documented for each individual module.
-
-.SH "FILES"
-.BR /etc/pam.conf " - the configuration file"
-.br
-.BR /etc/pam.d/ " - the"
-.BR Linux-PAM
-configuration directory. Generally, if this directory is present, the
-.B /etc/pam.conf
-file is ignored.
-.br
-.BR /lib/libpam.so.X " - the dynamic library"
-.br
-.BR /lib/security/*.so " - the PAMs
-
-.SH ERRORS
-Typically errors generated by the
-.BR Linux-PAM
-system of libraries, will be written to
-.BR syslog "(3)."
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.br
-Contains additional features, but remains backwardly compatible with
-this RFC.
-
-.SH BUGS
-.sp 2
-None known.
-
-.SH "SEE ALSO"
-
-The three
-.BR Linux-PAM
-Guides, for
-.BR "system administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam.conf.8 b/doc/man/pam.conf.8
deleted file mode 100644
index d067b559..00000000
--- a/doc/man/pam.conf.8
+++ /dev/null
@@ -1 +0,0 @@
-.so pam.8
diff --git a/doc/man/pam.d.8 b/doc/man/pam.d.8
deleted file mode 100644
index d067b559..00000000
--- a/doc/man/pam.d.8
+++ /dev/null
@@ -1 +0,0 @@
-.so pam.8
diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3
deleted file mode 100644
index ba1bc52e..00000000
--- a/doc/man/pam_authenticate.3
+++ /dev/null
@@ -1,91 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_authenticate \- authenticate a user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_authenticate(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_authenticate
-
-.br
-Use this function to authenticate an applicant user.  It is linked
-.I dynamically
-to the authentication modules by
-.BR Linux-PAM ". "
-It is the task of these module to perform such an authentication.  The
-specific nature of the authentication is not the concern of the
-application.
-
-.br
-Following successful completion, the
-.BR name
-of the authenticated user will be present in the
-.BR Linux-PAM
-item
-.BR PAM_USER ". "
-This item may be recovered with a call to
-.BR pam_get_item "(3)."
-
-.br
-The application developer should note that the modules may request
-that the user enter their username via the conversation mechanism (see
-.BR pam_start "(3))."
-Should this be the case, the user-prompt string can be set via
-the
-.BR PAM_USER_PROMPT
-item (see
-.BR pam_set_item "(3))."
-
-.SH "RETURN VALUE"
-On success
-.BR PAM_SUCCESS
-is returned.  All other returns should be considered
-authentication failures and will be
-.I delayed
-by an amount specified with prior calls to
-.BR pam_fail_delay "(3). "
-Specific failures that demand special attention are the following:
-.TP
-.B PAM_ABORT
-the application should exit immediately. Of course,
-.BR pam_end "(3)"
-should be called first.
-
-.TP
-.B PAM_MAXTRIES
-the application has tried too many times to authenticate the
-user, authentication should not be attempted again.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-.BR pam_fail_delay "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3
deleted file mode 100644
index 63904da3..00000000
--- a/doc/man/pam_chauthtok.3
+++ /dev/null
@@ -1,101 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_chauthtok \- updating authentication tokens
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_chauthtok(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_chauthtok
-
-.br
-Use this function to rejuvenate the authentication tokens (passwords
-etc.) of an applicant user.
-
-.br
-Note, the application should not pre-authenticate the user, as this is
-performed (if required) by the
-.BR Linux-PAM
-framework.
-
-.br
-The
-.I flags
-argument can
-.I optionally
-take the value,
-.BR PAM_CHANGE_EXPIRED_AUTHTOK "."
-In such cases the framework is only required to update those
-authentication tokens that have expired. Without this argument, the
-framework will attempt to obtain new tokens for all configured
-authentication mechanisms. The details of the types and number of such
-schemes should not concern the calling application.
-
-.SH RETURN VALUE
-A successful return from this function will be indicated with
-.BR PAM_SUCCESS "."
-
-.br
-Specific errors of special interest when calling this function are
-
-.br
-.BR PAM_AUTHTOK_ERROR
-- a valid new token was not obtained
-
-.br
-.BR PAM_AUTHTOK_RECOVERY_ERR
-- old authentication token was not available
-
-.br
-.BR PAM_AUTHTOK_LOCK_BUSY
-- a resource needed to update the token was locked (try again later)
-
-.br
-.BR PAM_AUTHTOK_DISABLE_AGING
-- one or more of the authentication modules does not honor
-authentication token aging
-
-.br
-.BR PAM_TRY_AGAIN
-- one or more authentication mechanism is not prepared to update a
-token at this time
-
-.br
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(8)."
-
-.br
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3
deleted file mode 100644
index d851700c..00000000
--- a/doc/man/pam_close_session.3
+++ /dev/null
@@ -1 +0,0 @@
-.so pam_open_session.3
diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3
deleted file mode 100644
index de999f24..00000000
--- a/doc/man/pam_end.3
+++ /dev/null
@@ -1 +0,0 @@
-.so pam_start.3
diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3
deleted file mode 100644
index f6cd238a..00000000
--- a/doc/man/pam_fail_delay.3
+++ /dev/null
@@ -1,130 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual"
-.SH NAME
-
-pam_fail_delay \- request a delay on failure
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");"
-.sp 2
-.SH DESCRIPTION
-.br
-It is often possible to attack an authentication scheme by exploiting
-the time it takes the scheme to deny access to an applicant user.  In
-cases of
-.I short
-timeouts, it may prove possible to attempt a
-.I brute force
-dictionary attack -- with an automated process, the attacker tries all
-possible passwords to gain access to the system.  In other cases,
-where individual failures can take measurable amounts of time
-(indicating the nature of the failure), an attacker can obtain useful
-information about the authentication process.  These latter attacks
-make use of procedural delays that constitute a
-.I covert channel
-of useful information.
-
-.br
-To minimize the effectiveness of such attacks, it is desirable to
-introduce a random delay in a failed authentication process.
-.B Linux-PAM
-provides such a facility.  The delay occurs upon failure of the
-.BR pam_authenticate "(3) "
-and
-.BR pam_chauthtok "(3) "
-functions.  It occurs
-.I after
-all authentication modules have been called, but
-.I before
-control is returned to the service application.
-
-.br
-The function,
-.BR pam_fail_delay "(3),"
-is used to specify a required minimum for the length of the
-failure-delay; the
-.I usec
-argument.  This function can be called by the service application
-and/or the authentication modules, both may have an interest in
-delaying a reapplication for service by the user.  The length of the
-delay is computed at the time it is required.  Its length is
-pseudo-gausianly distributed about the
-.I maximum
-requested value; the resultant delay will differ by as much as 25% of
-this maximum requested value (both up and down).
-
-.br
-On return from
-.BR pam_authenticate "(3) or " pam_chauthtok "(3),"
-independent of success or failure, the new requested delay is reset to
-its default value: zero.
-
-.SH EXAMPLE
-.br
-For example, a
-.B login
-application may require a failure delay of roughly 3 seconds. It will
-contain the following code:
-.sp
-.br
-.B "     pam_fail_delay(pamh, 3000000 /* micro-seconds */ );"
-.br
-.B "     pam_authenticate(pamh, 0);"
-.sp
-.br
-if the modules do not request a delay, the failure delay will be
-between 2.25 and 3.75 seconds.
-
-.br
-However, the modules, invoked in the authentication process, may
-also request delays:
-.sp
-.br
-.RB "  (module #1)   " "pam_fail_delay(pamh, 2000000);"
-.sp
-.br
-.RB "  (module #2)   " "pam_fail_delay(pamh, 4000000);"
-.sp
-.br
-in this case, it is the largest requested value that is used to
-compute the actual failed delay: here between 3 and 5 seconds.
-
-.SH "RETURN VALUE"
-Following a successful call to
-.BR pam_fail_delay "(3), " PAM_SUCCESS
-is returned.  All other returns should be considered serious failures.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-Under consideration by the X/Open group for future inclusion in the
-PAM RFC. 1996/1/10
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_get_item.3 b/doc/man/pam_get_item.3
deleted file mode 100644
index f4f0d462..00000000
--- a/doc/man/pam_get_item.3
+++ /dev/null
@@ -1 +0,0 @@
-.so pam_set_item.3
diff --git a/doc/man/pam_open_session.3 b/doc/man/pam_open_session.3
deleted file mode 100644
index 4e63b5c4..00000000
--- a/doc/man/pam_open_session.3
+++ /dev/null
@@ -1,99 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_open/close_session \- PAM session management
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_open_session(pam_handle_t " *pamh ", int  " flags ");"
-.sp
-.BI "int pam_close_session(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-
-PAM provides management-hooks for the initialization and termination
-of a session. 
-
-.TP
-.B pam_open_session
-.br
-Use this function to signal that an authenticated user session has
-begun. It should be called only after the user is properly identified
-and (where necessary) has been granted their credentials with
-.BR pam_authenticate "(3)"
-and
-.BR pam_setcred "(3)"
-respectively.
-
-.br
-Some types of functions associated with session
-initialization are logging for the purposes of system-audit and
-mounting directories (the user's home directory for example). These
-should not concern the application. It should be noted that the
-.I effective
-uid,
-.BR geteuid "(2),"
-of the application should be of sufficient privilege to perform such
-tasks.
-
-.TP
-.B pam_close_session
-.br
-Use this function to signal that a user session has
-terminated. In general this function may not need to be located in the
-same application as the initialization function,
-.BR pam_open_session "."
-
-.br
-Typically, this function will undo the actions of
-.BR pam_open_session "."
-That is, log audit information concerning the end of the user session
-or unmount the user's home directory. Apart from having sufficient
-privilege the details of the session termination should not concern
-the calling application. It is good programming practice, however, to
-cease acting on behalf of the user on returning from this call.
-
-.SH RETURN VALUE
-A successful return from the session management functions will be
-indicated with
-.BR PAM_SUCCESS "."
-
-.br
-The specific error indicating a failure to open or close a session is
-.BR PAM_SESSION_ERR "."
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-OSF-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(3)."
-
-.br
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_set_item.3 b/doc/man/pam_set_item.3
deleted file mode 100644
index b0582778..00000000
--- a/doc/man/pam_set_item.3
+++ /dev/null
@@ -1,55 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@kernel.org>
-.TH PAM_SET_ITEM 3 "2001 Jan 21" "Linux-PAM" "App. Programmers' Manual"
-.SH NAME
-
-pam_set_item, pam_get_item \- item manipulation under PAM
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or
-.br
-.B #include <secruity/pam_modules.h>
-.sp
-.BI "int pam_set_item(pam_handle_t " *pamh ", int " item_type ", void " *item ");"
-.sp
-.BI "int pam_get_item(const pam_handle_t " *pamh ", int  " item_type ", const void " **item_p ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_set_item
-.sp
-.B pam_set_item
-
-These functions are currently undocumented in a man page, but see the
-end of this man page for more information (the PAM guides).
-
-On success
-.BR PAM_SUCCESS
-is returned, all other return values should be treated as errors.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam (8)
-and
-.BR pam_strerror "(3)."
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3
deleted file mode 100644
index 8c00fe71..00000000
--- a/doc/man/pam_setcred.3
+++ /dev/null
@@ -1,79 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
-.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual"
-.SH NAME
-
-pam_setcred \- set the credentials for the user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_setcred(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_setcred
-
-This function is used to establish, maintain and delete the
-credentials of a user. It should be called after a user has been
-authenticated and before a session is opened for the user (with
-.BR pam_open_session "(3))."
-
-It should be noted that credentials come in many forms. Examples
-include: group memberships; ticket-files; and Linux-PAM environment
-variables.  For this reason, it is important that the basic identity
-of the user is established, by the application, prior to a call to
-this function.  For example, the default
-.BR Linux-PAM
-environment variables should be set and also
-.BR initgroups "(2) "
-(or equivalent) should have been performed.
-
-.SH "VALID FLAGS"
-.TP
-.BR PAM_ESTABLISH_CRED
-initialize the credentials for the user.
-
-.TP
-.BR PAM_DELETE_CRED
-delete the user's credentials.
-
-.TP
-.BR PAM_REINITIALIZE_CRED
-delete and then initialize the user's credentials.
-
-.TP
-.BR PAM_REFRESH_CRED
-extend the lifetime of the existing credentials.
-
-.SH "RETURN VALUE"
-
-On success
-.BR PAM_SUCCESS
-is returned, all other return values should be treated as errors.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_authenticate "(3), "
-.BR pam_strerror "(3)"
-and
-.BR pam_open_session "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3
deleted file mode 100644
index 9c11fd73..00000000
--- a/doc/man/pam_start.3
+++ /dev/null
@@ -1,98 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
-.SH NAME
-
-pam_start, pam_end \- activating Linux-PAM
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
-.sp
-.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
-.sp 2
-.SH DESCRIPTION
-.TP
-.B pam_start
-Initialize the
-.I Linux-PAM
-library.  Identifying the application with a particular
-.IR service
-name.  The
-.IR user "name"
-can take the value
-.IR NULL ", "
-if not known at the time the interface is initialized.  The
-conversation structure is passed to the library via the
-.IR conv
-argument.  (For a complete description of this and other structures
-the reader is directed to the more verbose
-.IR Linux-PAM
-application developers' guide).  Upon successful initialization, an
-opaque pointer-handle for future access to the library is returned
-through the contents of the
-.IR pamh_p
-pointer.
-
-.TP
-.B pam_end
-Terminate the
-.B Linux-PAM
-library.  The service application associated with the
-.IR pamh
-handle, is terminated.  The argument,
-.IR pam_status ", "
-passes the value most recently returned to the application from the
-library; it indicates the manner in which the library should be
-shutdown.  Besides carrying a return value, this argument may be
-logically OR'd with
-.IR PAM_DATA_SILENT
-to indicate that the module should not treat the call too
-seriously. It is generally used to indicate that the current closing
-of the library is in a
-.IR fork "(2)ed"
-process, and that the parent will take care of cleaning up things that
-exist outside of the current process space (files etc.).
-
-.SH "RETURN VALUE"
-.TP
-.B pam_start
-.TP
-.B pam_end
-On success,
-.BR PAM_SUCCESS
-is returned
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.sp
-Note, the 
-.BR PAM_DATA_SILENT
-flag is pending acceptance with the DCE (as of 1996/12/4).
-
-.SH BUGS
-.sp 2
-None known.
-
-.SH "SEE ALSO"
-
-.BR fork "(2), "
-.BR pam_authenticate "(3), "
-.BR pam_acct_mgmt "(3), "
-.BR pam_open_session "(3), "
-and
-.BR pam_chauthtok "(3)."
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3
deleted file mode 100644
index 01ee0635..00000000
--- a/doc/man/pam_strerror.3
+++ /dev/null
@@ -1,51 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" ripped off from Rick Faith's getgroups man page
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
-.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual"
-.SH NAME
-
-pam_strerror \- return a textual description of a Linux-PAM error
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_strerror
-
-This function returns some text describing the
-.BR Linux-PAM
-error associated with the
-.B pam_error
-argument.
-
-.SH "RETURN VALUE"
-
-On success this function returns a description of the indicated
-error.  Should the function not recognize the error, ``Unknown
-Linux-PAM error'' is returned.
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-This function should be internationalized.
-
-.SH "SEE ALSO"
-
-.BR pam "(8). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/man/template-man b/doc/man/template-man
deleted file mode 100644
index b8159eb6..00000000
--- a/doc/man/template-man
+++ /dev/null
@@ -1,52 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual"
-.SH NAME
-
-function names \- brief summary of function
-
-.SH SYNOPSIS
-.B #include <security/pam_????.h>
-.sp
-.BI "int pam_???(pam_handle_t " pamh ", int  " flags);
-.sp 2
-.SH DESCRIPTION
-.TP
-.B pam_???
-Here goes the
-.I explanation
-it may be quite
-.IR long .
-.TP
-.SH "RETURN VALUE"
-.B pam_???
-On success...
-.BR PAM_SUCCESS
-is returned
-.TP
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(2). "
-
-.SH "CONFORMING TO"
-.B pam_???
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_??? "(2), "
-and
-.BR pam_??? "(2). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/doc/modules/README b/doc/modules/README
deleted file mode 100644
index 448aefc7..00000000
--- a/doc/modules/README
+++ /dev/null
@@ -1,13 +0,0 @@
-$Id$
-
-This directory contains a number of sgml sub-files. One for each
-documented module. They contain a description of each module and give
-some indication of its reliability.
-
-Additionally, there is a 'module.sgml-template' file which should be
-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@kernel.org>
diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template
deleted file mode 100644
index 16a93c79..00000000
--- a/doc/modules/module.sgml-template
+++ /dev/null
@@ -1,170 +0,0 @@
-<!--
-
-   $Id$
-   
-   This template file was written by Andrew G. Morgan
-					<morgan@kernel.org>
-
-[
-	Text that should be deleted/replaced, is enclosed within 
-		'[' .. ']'
-	marks. For example, this text should be deleted!
-]
-
--->
-
-<sect1> [*Familiar full name of module*, eg. The "allow all" module.]
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-[
-	insert the name of the module
-
-	Blank is not permitted.
-]
-
-<tag><bf>Author[s]:</bf></tag>
-
-[
-	Insert author names here
-
-	Blank is not permitted. If in doubt, put "unknown" if the
-	author wishes to remain anonymous, put "anonymous".
-]
-
-<tag><bf>Maintainer:</bf></tag>
-	
-[
-	Insert names and date-begun of most recent maintainer.
-]
-
-<tag><bf>Management groups provided:</bf></tag>
-
-[
-	list the subset of four management groups supported by the
-	module. Choose from: account; authentication; password;
-	session.
-
-	Blank entries are not permitted. Explicitly list all of the
-	management groups. In the future more may be added to libpam!
-]
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-
-[
-	Indicate whether this module contains code that can perform
-	reversible (strong) encryption. This field is primarily to
-	ensure that people redistributing it are not unwittingly
-	breaking laws...
-
-	Modules may also require the presence of some local library
-	that performs the necessary encryption via some standard API.
-	In this case "uses API" can be included in this field. The
-	library in question should be added to the system requirements
-	below.
-
-	Blank = no cryptography is used by module.
-]
-	
-<tag><bf>Security rating:</bf></tag>
-
-[
-	Initially, this field should be left blank. If someone takes
-	it upon themselves to test the strength of the module, it can
-	later be filled.
-
-	Blank = unknown.
-]
-
-<tag><bf>Clean code base:</bf></tag>
-
-[
-	This will probably be filled by the libpam maintainer.
-	It can be considered to be a public humiliation list. :*)
-
-	I am of the opinion that "gcc -with_all_those_flags" is
-	trying to tell us something about whether the program
-	works as intended. Since there is currently no Security
-	evaluation procedure for modules IMHO this is not a
-	completely unreasonable indication (a lower bound anyway)
-	of the reliability of a module.
-
-	This field would indicate the number and flavor of
-	warnings that gcc barfs up when trying to compile the
-	module as part of the tree. Is this too tyrannical?
-
-	Blank = Linux-PAM maintainer has not tested it :)
-]
-
-<tag><bf>System dependencies:</bf></tag>
-
-[
-	here we list config files, dynamic libraries needed, system
-	resources, kernel options.. etc.
-
-	Blank = nothing more than libc required.
-]
-
-<tag><bf>Network aware:</bf></tag>
-
-[
-	Does the module base its behavior on probing a network
-	connection? Does it expect to be protected by the
-	application?
-
-	Blank = Ignorance of network.
-]
-
-</descrip>
-
-<sect2>Overview of module
-
-[
-	some text describing the intended actions of the module
-	general comments mainly (specifics in sections
-	below).
-]
-
-[
-
-	[ now we have a <sect2> level subsection for each of the
-	  management groups. Include as many as there are groups
-	  listed above in the synopsis ]
-
-<sect2>[ Account | Authentication | Password | Session ] component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-[
-	List the supported arguments (leave their description for the
-	description below.
-
-	Blank = no arguments are read and nothing is logged to syslog
-		about any arguments that are passed. Note, this
-		behavior is contrary to the RFC!
-]
-
-<tag><bf>Description:</bf></tag>
-
-[
-	This component of the module performs the task of ...
-]
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-[
-	Here we list some doos and don'ts for this module.
-]
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_access.sgml b/doc/modules/pam_access.sgml
deleted file mode 100644
index 8a910d13..00000000
--- a/doc/modules/pam_access.sgml
+++ /dev/null
@@ -1,117 +0,0 @@
-<!--
-   
-   pam_access module docs added by Tim Berger <timb@transmeta.com>
-
--->
-
-<sect1> The access module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-
-<tt>pam_access</tt>
-
-
-<tag><bf>Author[s]:</bf></tag>
-
-Alexei Nogin &lt;alexei@nogin.dnttm.ru&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-	
-<tag><bf>Management groups provided:</bf></tag>
-
-account
-
-<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 a configuration file. By default 
-<tt>/etc/security/access.conf</tt> is used but this can be overridden. 
-
-<tag><bf>Network aware:</bf></tag>
-
-Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of
-the stdin file descriptor with <tt/ttyname()/.  Standard
-gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/
-calls.  <bf/NIS/ is used for netgroup support.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Provides logdaemon style login access control.
-
-<sect2> Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt>accessfile=<it>/path/to/file.conf</it></tt>;
-<tt>fieldsep=<it>separators</it></tt>
-
-<tag><bf>Description:</bf></tag>
-
-This module provides logdaemon style login access control based on
-login names and on host (or domain) names, internet addresses (or
-network numbers), or on terminal line names in case of non-networked
-logins. Diagnostics are reported through <tt/syslog(3)/.  Wietse
-Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with
-several changes by A. Nogin.
-
-<p> 
-The behavior of this module can be modified with the following 
-arguments: 
-<itemize> 
- 
-<item><tt>accessfile=/path/to/file.conf</tt> - 
-indicate an alternative <em/access/ configuration file to override 
-the default. This can be useful when different services need different 
-access lists. 
-
-<item><tt>fieldsep=<it>separators</it></tt> -
-this option modifies the field separator character that
-<tt/pam_access/ will recognize when parsing the access configuration
-file. For example: <tt>fieldsep=|</tt> will cause the default `:'
-character to be treated as part of a field value and `|' becomes the
-field separator. Doing this is useful in conjuction with a system that
-wants to use pam_access with X based applications, since the
-<tt/PAM_TTY/ item is likely to be of the form "hostname:0" which
-includes a `:' character in its value.
-
-</itemize> 
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Use of module is recommended, for example, on administrative machines
-such as <bf/NIS/ servers and mail servers where you need several accounts
-active but don't want them all to have login capability.
-
-For <tt>/etc/pam.d</tt> style configurations where your modules live
-in <tt>/lib/security</tt>, start by adding the following line to
-<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>,
-<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>:
-
-<tscreen>
-<verb>
-account  required       /lib/security/pam_access.so
-</verb>
-</tscreen>
-
-Note that use of this module is not effective unless your system ignores
-<tt>.rhosts</tt> files.  See the the pam_rhosts_auth documentation.
-
-A sample <tt>access.conf</tt> configuration file is included with the
-distribution.
-
-</descrip>
diff --git a/doc/modules/pam_chroot.sgml b/doc/modules/pam_chroot.sgml
deleted file mode 100644
index ec739c18..00000000
--- a/doc/modules/pam_chroot.sgml
+++ /dev/null
@@ -1,86 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Bruce Campbell <brucec@humbug.org.au>
--->
-
-<sect1>Chroot
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_chroot/
-
-<tag><bf>Author:</bf></tag>
-Bruce Campbell &lt;brucec@humbug.org.au&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author; proposed on 20/11/96 - email for status
-
-<tag><bf>Management groups provided:</bf></tag>
-account; session; authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-Unwritten.
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-Expects localhost.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module is intended to provide a transparent wrapper around the
-average user, one that puts them in a fake file-system (eg, their
-'<tt>/</tt>' is really <tt>/some/where/else</tt>).
-
-<p>
-Useful if you have several classes of users, and are slightly paranoid
-about security.  Can be used to limit who else users can see on the
-system, and to limit the selection of programs they can run.
-
-<sect2>Account component:
-
-<p>
-<em/Need more info here./
-
-<sect2>Authentication component:
-
-<p>
-<em/Need more info here./
-
-<sect2>Session component:
-
-<p>
-<em/Need more info here./
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-Arguments and logging levels for the PAM version are being worked on.
-
-<tag><bf>Description:</bf></tag>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm',
-'cp' and 'ed' in there is a bit... 
-<p>
-Don't take it to extremes (eg, you can set up a separate environment for
-each user, but its a big waste of your disk space.)
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml
deleted file mode 100644
index 008e49f6..00000000
--- a/doc/modules/pam_cracklib.sgml
+++ /dev/null
@@ -1,304 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
-   long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com>
--->
-
-<sect1>Cracklib pluggable password strength-checker
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-
-pam_cracklib
-
-<tag><bf>Author:</bf></tag>
-
-Cristian Gafton &lt;gafton@redhat.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-
-password
-
-<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 the system library <tt/libcrack/ and a system dictionary:
-<tt>/usr/lib/cracklib_dict</tt>.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module can be plugged into the <tt/password/ stack of a given
-application to provide some plug-in strength-checking for passwords.
-
-<p>
-This module works in the following manner: it first calls the
-<em>Cracklib</em> routine to check the strength of the password; if
-crack likes the password, the module does an additional set of
-strength checks.  These checks are:
-<itemize>
-
-<item> <bf/Palindrome/ -
-
-Is the new password a palindrome of the old one?
-
-<item> <bf/Case Change Only/ -
-
-Is the new password the the old one with only a change of case?
-
-<item> <bf/Similar/ -
-
-Is the new password too much like the old one?  This is primarily
-controlled by one argument, <tt/difok/ which is a number of characters
-that if different between the old and new are enough to accept the new
-password, this defaults to 10 or 1/2 the size of the new password
-whichever is smaller.
-
-To avoid the lockup associated with trying to change a long and
-complicated password, <tt/difignore/ is available. This argument can
-be used to specify the minimum length a new password needs to be
-before the <tt/difok/ value is ignored. The default value for
-<tt/difignore/ is 23.
-
-
-<item> <bf/Simple/ -
-
-Is the new password too small?  This is controlled by 5 arguments
-<tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and
-<tt/ocredit/. See the section on the arguments for the details of how
-these work and there defaults.
-
-<item> <bf/Rotated/ -
-
-Is the new password a rotated version of the old password?
-
-<item> <bf/Already used/ -
-
-Was the password used in the past?  Previously used passwords are to
-be found in /etc/security/opasswd.
-
-</itemize>
-
-<p>
-This module with no arguments will work well for standard unix
-password encryption.  With md5 encryption, passwords can be longer
-than 8 characters and the default settings for this module can make it
-hard for the user to choose a satisfactory new password.  Notably, the
-requirement that the new password contain no more than 1/2 of the
-characters in the old password becomes a non-trivial constraint.  For
-example, an old password of the form "the quick brown fox jumped over
-the lazy dogs" would be difficult to change...  In addition, the
-default action is to allow passwords as small as 5 characters in
-length.  For a md5 systems it can be a good idea to increase the
-required minimum size of a password.  One can then allow more credit
-for different kinds of characters but accept that the new password may
-share most of these characters with the old password.
-
-<sect2>Password component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/;
-<tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/;
-<tt/use_authtok/;
-
-<tag><bf>Description:</bf></tag>
-
-The action of this module is to prompt the user for a password and
-check its strength against a system dictionary and a set of rules for
-identifying poor choices.
-
-<p>
-The default action is to prompt for a single password, check its
-strength and then, if it is considered strong, prompt for the password
-a second time (to verify that it was typed correctly on the first
-occasion). All being well, the password is passed on to subsequent
-modules to be installed as the new authentication token.
-
-<p>
-The default action may be modified in a number of ways using the
-arguments recognized by the module:
-<itemize>
-
-<item> <tt/debug/ -
-
-this option makes the module write information to syslog(3) indicating
-the behavior of the module (this option does <bf/not/ write password
-information to the log file).
-
-<item> <tt/type=XXX/ -
-
-the default action is for the module to use the following prompts when
-requesting passwords: ``New UNIX password: '' and ``Retype UNIX
-password: ''. Using this option you can replace the word UNIX with
-<tt/XXX/.
-
-<item> <tt/retry=N/ -
-
-the default number of times this module will request a new password
-(for strength-checking) from the user is 1. Using this argument this
-can be increased to <tt/N/.
-
-<item> <tt/difok=N/ -
-
-This argument will change the default of 10 for the number of
-characters in the new password that must not be present in the old
-password.  In addition, if 1/2 of the characters in the new password
-are different then the new password will be accepted anyway.
-
-<item> <tt/minlen=N/ -
-
-The minimum acceptable size for the new password (plus one if credits 
-are not disabled which is the default).
-In addition to the number of characters in the new password, credit (of
-+1 in length) is given for each different kind of character (<em>other,
-upper, lower</em> and <em/digit/).  The default for this parameter is
-9 which is good for a old style UNIX password all of the same type of
-character but may be too low to exploit the added security of a md5
-system.  Note that there is a pair of length limits in
-<em>Cracklib</em> itself, a "way too short" limit of 4 which is hard
-coded in and a defined limit (6) that will be checked without
-reference to <tt>minlen</tt>.  If you want to allow passwords as short
-as 5 characters you should either not use this module or recompile
-the crack library and then recompile this module.
-
-<item> <tt/dcredit=N/ -
-
-(N >= 0) This is the maximum credit for having digits in the new password. If
-you have less than or <tt/N/ digits, each digit will count +1 towards
-meeting the current <tt/minlen/ value.  The default for <tt/dcredit/
-is 1 which is the recommended value for <tt/minlen/ less than 10.
-(N < 0) This is the minimum number of digits that must be met for a new 
-password.
-
-<item> <tt/ucredit=N/ -
-
-(N >= 0) This is the maximum credit for having upper case letters in the new
-password.  If you have less than or <tt/N/ upper case letters each
-letter will count +1 towards meeting the current <tt/minlen/ value.
-The default for <tt/ucredit/ is 1 which is the recommended value for
-<tt/minlen/ less than 10. (N < 0) This is the minimum number of upper 
-case letters that must be met for a new password.
-
-<item> <tt/lcredit=N/ -
-
-(N >= 0) This is the maximum credit for having lower case letters in the new
-password.  If you have less than or <tt/N/ lower case letters, each
-letter will count +1 towards meeting the current <tt/minlen/ value.
-The default for <tt/lcredit/ is 1 which is the recommended value for
-<tt/minlen/ less than 10. (N < 0) This is the minimum number of lower 
-case letters that must be met for a new password.
-
-<item> <tt/ocredit=N/ -
-
-(N >= 0) This is the maximum credit for having other characters in the new
-password.  If you have less than or <tt/N/ other characters, each
-character will count +1 towards meeting the current <tt/minlen/ value.
-The default for <tt/ocredit/ is 1 which is the recommended value for
-<tt/minlen/ less than 10. (N < 0) This is the minimum number of other 
-characters that must be met for a new password.
-
-<item> <tt/use_authtok/ -
-
-This argument is used to <em/force/ the module to not prompt the user
-for a new password but use the one provided by the previously stacked
-<tt/password/ module.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-<p>
-For an example of the use of this module, we show how it may be
-stacked with the password component of <tt/pam_pwdb/:
-<tscreen>
-<verb>
-#
-# These lines stack two password type modules. In this example the
-# user is given 3 opportunities to enter a strong password. The
-# "use_authtok" argument ensures that the pam_pwdb module does not
-# prompt for a password, but instead uses the one provided by
-# pam_cracklib.
-#
-passwd	password required	pam_cracklib.so retry=3
-passwd	password required	pam_pwdb.so use_authtok
-</verb>
-</tscreen>
-
-<p>
-Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the
-case that you want to use md5 password encryption:
-<tscreen>
-<verb>
-#%PAM-1.0
-#
-# These lines allow a md5 systems to support passwords of at least 14
-# bytes with extra credit of 2 for digits and 2 for others the new
-# password must have at least three bytes that are not present in the
-# old password
-#
-password  required pam_cracklib.so \
-               difok=3 minlen=15 dcredit= 2 ocredit=2
-password  required pam_pwdb.so use_authtok nullok md5
-</verb>
-</tscreen>
-
-<p>
-And here is another example in case you don't want to use credits:
-<tscreen>
-<verb>
-#%PAM-1.0
-#
-# These lines require the user to select a password with a minimum
-# length of 8 and with at least 1 digit number, 1 upper case letter,
-# and 1 other character
-#
-password  required pam_cracklib.so \
-               dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
-password  required pam_pwdb.so use_authtok nullok md5
-</verb>
-</tscreen>
-
-<p>
-In this example we simply say that the password must have a minimum 
-length of 8:
-<tscreen>
-<verb>
-#%PAM-1.0
-#
-# These lines require the user to select a password with a mimimum
-# length of 8. He gets no credits and he is not forced to use
-# digit numbers, upper case letters etc.
-#
-password  required pam_cracklib.so \
-               dcredit=0 ucredit=0 ocredit=0 lcredit=0 minlen=8
-password  required pam_pwdb.so use_authtok nullok md5
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml
deleted file mode 100644
index 6953231f..00000000
--- a/doc/modules/pam_deny.sgml
+++ /dev/null
@@ -1,177 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The locking-out module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_deny
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-current <bf/Linux-PAM/ maintainer
-
-<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>
-clean.
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module can be used to deny access. It always indicates a failure
-to the application through the PAM framework. As is commented in the
-overview section <ref id="overview-section" name="above">, this module
-might be suitable for using for default (the <tt/OTHER/) entries.
-
-<sect2>Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This component does nothing other than return a failure. The
-failure type is <tt/PAM_ACCT_EXPIRED/.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Stacking this module with type <tt/account/ will prevent the user from
-gaining access to the system via applications that refer to
-<bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/.
-
-<p>
-The following example would make it impossible to login:
-<tscreen>
-<verb>
-#
-# add this line to your other login entries to disable all accounts
-#
-login	account	 required	pam_deny.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This component does nothing other than return a failure. The failure
-type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is
-called (when the application tries to authenticate the user), and is
-<tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/
-(to establish and set the credentials of the user -- it is unlikely
-that this function will ever be called in practice).
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-To deny access to default applications with this component of the
-<tt/pam_deny/ module, you might include the following line in your
-<bf/Linux-PAM/ configuration file:
-<tscreen>
-<verb>
-#
-# add this line to your existing OTHER entries to prevent
-# authentication succeeding with default applications.
-#
-OTHER	auth	 required	pam_deny.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Password component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This component of the module denies the user the opportunity to change
-their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when
-invoked.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This module should be used to prevent an application from updating the
-applicant user's password. For example, to prevent <tt/login/ from
-automatically prompting for a new password when the old one has
-expired you should include the following line in your configuration
-file:
-<tscreen>
-<verb>
-#
-# add this line to your other login entries to prevent the login
-# application from being able to change the user's password.
-#
-login	password required	pam_deny.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This aspect of the module prevents an application from starting a
-session on the host computer.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Together with another session module, that displays a message of the
-day perhaps (<tt/pam_motd/ for example), this module can be used to
-block a user from starting a shell. We might use the following entries
-in the configuration file to inform the user it is system time:
-<tscreen>
-<verb>
-#
-# An example to see how to configure login to refuse the user a
-# session (politely)
-#
-login	session	 required	pam_motd.so \
-			motd=/etc/system_time
-login	session	 required	pam_deny.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml
deleted file mode 100644
index d795d591..00000000
--- a/doc/modules/pam_env.sgml
+++ /dev/null
@@ -1,141 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Dave Kinchlea <kinch@kinch.ark.com>
-   Ed. AGM
--->
-
-<sect1>Set/unset environment variables
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_env/
-
-<tag><bf>Author:</bf></tag>
-Dave Kinchlea &lt;kinch@kinch.ark.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Authentication (setcred)
-
-<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>
-<tt>/etc/security/pam_env.conf</tt>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module allows the (un)setting of environment variables. Supported
-is the use of previously set environment variables as well as
-<em>PAM_ITEM</em>s such as <tt>PAM_RHOST</tt>.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/conffile=/<em/configuration-file-name/;
-<tt/envfile/=<em/env-file-name/; <tt/readenv/=<em/0|1/
-
-<tag><bf>Description:</bf></tag>
-This module allows you to (un)set arbitrary environment variables
-using fixed strings, the value of previously set environment variables
-and/or <em/PAM_ITEM/s.
-
-<p>
-All is controlled via a configuration file (by default,
-<tt>/etc/security/pam_env.conf</tt> but can be overriden with
-<tt>conffile</tt> argument).  Each line starts with the variable name,
-there are then two possible options for each variable <bf>DEFAULT</bf>
-and <bf>OVERRIDE</bf>.  <bf>DEFAULT</bf> allows an administrator to
-set the value of the variable to some default value, if none is
-supplied then the empty string is assumed.  The <bf>OVERRIDE</bf>
-option tells pam_env that it should enter in its value (overriding the
-default value) if there is one to use.  <bf>OVERRIDE</bf> is not used,
-<tt>""</tt> is assumed and no override will be done.
-
-<p>
-<tscreen>
-<verb>
-VARIABLE   [DEFAULT=[value]]  [OVERRIDE=[value]]
-</verb>
-</tscreen>
-
-<p>
-(Possibly non-existent) environment variables may be used in values
-using the <tt>&dollar;&lcub;string&rcub;</tt> syntax and (possibly
-non-existent) <em/PAM_ITEM/s may be used in values using the
-<tt>&commat;&lcub;string&rcub;</tt> syntax. Both the <tt>&dollar;</tt>
-and <tt>&commat;</tt> characters can be backslash-escaped to be used
-as literal values (as in <tt>&bsol;&dollar;</tt>.  Double quotes may
-be used in values (but not environment variable names) when white
-space is needed <bf>the full value must be delimited by the quotes and
-embedded or escaped quotes are not supported</bf>.
-
-<p>
-This module can also parse a file with simple <tt>KEY=VAL</tt> pairs
-on seperate lines (<tt>/etc/environment</tt> by default). You can
-change the default file to parse, with the <em/envfile/ flag and turn
-it on or off by setting the <em/readenv/ flag to 1 or 0 respectively.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/debug/
-- write more information to <tt/syslog(3)/.
-
-<item><tt/conffile=/<em/filename/
-- by default the file <tt>/etc/security/pam_env.conf</tt> is used as
-the configuration file. This option overrides the default. You must
-supply a complete path + file name.
-
-<item><tt/envfile=/<em/filename/
-- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL
-pairs directly into the env. This option overrides the default. You must
-supply a complete path + file name.
-
-<item><tt/readenv=/<em/0|1/
-- turns on or off the reading of the file specified by envfile (0 is off,
-1 is on). By default this option is on.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-See sample <tt>pam_env.conf</tt> for more information and examples.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
-
-
-
-
-
-
-
-
-
-
diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml
deleted file mode 100644
index 4d3b4e84..00000000
--- a/doc/modules/pam_filter.sgml
+++ /dev/null
@@ -1,150 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The filter module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-
-pam_filter
-
-<tag><bf>Author:</bf></tag>
-
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-	
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-
-account; authentication; password; session
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-
-Not yet.
-
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-This module compiles cleanly on Linux based systems.
-
-<tag><bf>System dependencies:</bf></tag>
-
-To function it requires <em/filters/ to be installed on the system.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module was written to offer a plug-in alternative to programs
-like ttysnoop (XXX - need a reference). Since writing a filter that
-performs this function has not occurred, it is currently only a toy.
-The single filter provided with the module simply transposes upper and
-lower case letters in the input and output streams. (This can be very
-annoying and is not kind to termcap based editors).
-
-<sect2>Account+Authentication+Password+Session components
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/
-
-<tag><bf>Description:</bf></tag>
-
-Each component of the module has the potential to invoke the desired
-filter.  The filter is always <tt/execv(2)/d with the privilege of the
-calling application and <bf/not/ that of the user. For this reason it
-cannot usually be killed by the user without closing their session.
-
-<p>
-The behavior of the module can be significantly altered by the
-arguments passed to it in the <bf/Linux-PAM/ configuration file:
-<itemize>
-<item><tt/debug/ -
-
-this option increases the amount of information logged to
-<tt/syslog(3)/ as the module is executed.
-
-<item><tt/new_term/ -
-
-the default action of the filter is to set the <tt/PAM_TTY/ item to
-indicate the terminal that the user is using to connect to the
-application. This argument indicates that the filter should set
-<tt/PAM_TTY/ to the filtered pseudo-terminal.
-
-<item><tt/non_term/ -
-don't try to set the <tt/PAM_TTY/ item.
-
-<item><tt/runX/ -
-
-in order that the module can invoke a filter it should know when to
-invoke it. This argument is required to tell the filter when to do
-this. The arguments that follow this one are respectively the full
-pathname of the filter to be run and any command line arguments that
-the filter might expect.
-
-<p>
-Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the
-precise time that the filter is to be run. To understand this concept
-it will be useful to have read the Linux-PAM Module developer's
-guide. Basically, for each management group there are up to two ways
-of calling the module's functions.
-
-In the case of the <em/authentication/ and <em/session/ components
-there are actually two separate functions.  For the case of
-authentication, these functions are <tt/_authenticate/ and
-<tt/_setcred/ -- here <tt/run1/ means run the filter from the
-<tt/_authenticate/ function and <tt/run2/ means run the filter from
-<tt/_setcred/. In the case of the session modules, <tt/run1/ implies
-that the filter is invoked at the <tt/_open_session/ stage, and
-<tt/run2/ for <tt/_close_session/.
-
-<p>
-For the case of the account component. Either <tt/run1/ or <tt/run2/
-may be used.
-
-<p>
-For the case of the password component, <tt/run1/ is used to indicate
-that the filter is run on the first occasion <tt/_chauthtok/ is run
-(the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate
-that the filter is run on the second occasion (the
-<tt/PAM_UPDATE_AUTHTOK/ phase).
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-At the time of writing there is little real use to be made of this
-module. For fun you might try adding the following line to your
-login's configuration entries
-<tscreen>
-<verb>
-#
-# An example to see how to configure login to transpose upper and
-# lower case letters once the user has logged in(!)
-#
-login	session	 required	pam_filter.so \
-			run1 /usr/sbin/pam_filter/upperLOWER
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml
deleted file mode 100644
index a9444733..00000000
--- a/doc/modules/pam_ftp.sgml
+++ /dev/null
@@ -1,93 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>Anonymous access module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_ftp.so/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<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>
-prompts for email address of user; easily spoofed (XXX - needs work)
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-The purpose of this module is to provide a pluggable anonymous ftp
-mode of access.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/users=XXX,YYY,.../;
-<tt/ignore/
-
-<tag><bf>Description:</bf></tag>
-
-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/@/' 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:
-<itemize>
-<item><tt/debug/ -
-log more information to with <tt/syslog(3)/.
-
-<item><tt/users=XXX,YYY,.../ - 
-instead of ``<tt/ftp/'' or ``<tt/anonymous/'', provide anonymous login
-to the comma separated list of users; ``<tt/XXX,YYY,.../''. Should the
-applicant enter one of these usernames the returned username is set to
-the first in the list; ``<tt/XXX/''.
-
-<item><tt/ignore/ -
-pay no attention to the email address of the user (if supplied).
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-An example of the use of this module is provided in the configuration
-file section <ref id="configuration" name="above">. With care, this
-module could be used to provide new/temporary account anonymous
-login.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml
deleted file mode 100644
index 0d8550d4..00000000
--- a/doc/modules/pam_group.sgml
+++ /dev/null
@@ -1,108 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The group access module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_group/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-Sensitive to <em/setgid/ status of file-systems accessible to users.
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled
-with or without <tt/libpwdb/.
-
-<tag><bf>Network aware:</bf></tag>
-Only through correctly set <tt/PAM_TTY/ item.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module provides group-settings based on the user's name and the
-terminal they are requesting a given service from. It takes note of
-the time of day.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This module does not authenticate the user, but instead it grants
-group memberships (in the credential setting phase of the
-authentication module) to the user.  Such memberships are based on the
-service they are applying for. The group memberships are listed in
-text form in the <tt>/etc/security/group.conf</tt> file.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-For this module to function correctly there must be a correctly
-formatted <tt>/etc/security/groups.conf</tt> file present. The format
-of this file is as follows. Group memberships are given based on the
-service application satisfying any combination of lines in the
-configuration file. Each line (barring comments which are preceded by
-`<tt/#/' marks) has the following
-syntax:
-<tscreen>
-<verb>
-services   ;   ttys   ;   users   ;   times   ;   groups
-</verb>
-</tscreen>
-Here the first four fields share the syntax of the <tt>pam_time</tt>
-configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last
-field, the <tt/groups/ field, is a comma (or space) separated list of
-the text-names of a selection of groups. If the users application for
-service satisfies the first four fields, the user is granted membership
-of the listed groups.
-
-<p>
-As stated in above this module's usefulness relies on the file-systems
-accessible to the user.  The point being that once granted the
-membership of a group, the user may attempt to create a <em/setgid/
-binary with a restricted group ownership.  Later, when the user is not
-given membership to this group, they can recover group membership with
-the precompiled binary.  The reason that the file-systems that the user
-has access to are so significant, is the fact that when a system is
-mounted <em/nosuid/ the user is unable to create or execute such a
-binary file.  For this module to provide any level of security, all
-file-systems that the user has write access to should be mounted
-<em/nosuid/.
-
-<p>
-The <tt>pam_group</tt> module fuctions in parallel with the
-<tt>/etc/group</tt> file. If the user is granted any groups based on
-the behavior of this module, they are granted <em>in addition</em> to
-those entries <tt>/etc/group</tt> (or equivalent).
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_issue.sgml b/doc/modules/pam_issue.sgml
deleted file mode 100644
index 1f617e3b..00000000
--- a/doc/modules/pam_issue.sgml
+++ /dev/null
@@ -1,120 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Add issue file to user prompt
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_issue/
-
-<tag><bf>Author:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Authentication (pam_sm_authenticate)
-
-<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 module prepends the issue file (<em>/etc/issue</em> by default) when
-prompting for a username.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/issue=issue-file-name/; <tt/noesc/;
-
-<tag><bf>Description:</bf></tag>
-This module allows you to prepend an issue file to the username prompt. It
-also by default parses escape codes in the issue file similar to some
-common getty's (using &bsol;x format).
-<p>
-Recognized escapes:
-<itemize>
-
-<item><tt/d/
-- current date
-
-<item><tt/s/
-- operating system name
-
-<item><tt/l/
-- name of this tty
-
-<item><tt/m/
-- architecture of this system (i686, sparc, powerpc, ...)
-
-<item><tt/n/
-- hostname of this system
-
-<item><tt/o/
-- domainname of this system
-
-<item><tt/r/
-- release number of the operation system (eg. 2.2.12)
-
-<item><tt/t/
-- current time
-
-<item><tt/u/
-- number of users currently logged in
-
-<item><tt/U/
-- same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1
-user" or "10 users"
-
-<item><tt/v/
-- version/build-date of the operating system (eg. "&num;3 Mon Aug 23 14:38:16
-EDT 1999" on Linux).
-
-</itemize>
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/issue/
-- the file to output if not using the default
-
-<item><tt/noesc/
-- turns off escape code parsing
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-login  auth  pam_issue.so  issue=/etc/issue
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_krb4.sgml b/doc/modules/pam_krb4.sgml
deleted file mode 100644
index 16ce8183..00000000
--- a/doc/modules/pam_krb4.sgml
+++ /dev/null
@@ -1,126 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Derrick J. Brashear <shadow@DEMENTIA.ORG>
--->
-
-<sect1>The Kerberos 4 module.
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_krb4/
-
-<tag><bf>Author:</bf></tag>
-Derrick J. Brashear &lt;shadow@dementia.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication; password; session
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-uses API
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-libraries - <tt/libkrb/, <tt/libdes/, <tt/libcom_err/, <tt/libkadm/;
-and a set of Kerberos include files.
-
-<tag><bf>Network aware:</bf></tag>
-Gets Kerberos ticket granting ticket via a Kerberos key distribution
-center reached via the network.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module provides an interface for doing Kerberos verification of a
-user's password, getting the user a Kerberos ticket granting ticket
-for use with the Kerberos ticket granting service, destroying the
-user's tickets at logout time, and changing a Kerberos password.
-
-<sect2> Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This component of the module currently sets the user's <tt/KRBTKFILE/
-environment variable (although there is currently no way to export
-this), as well as deleting the user's ticket file upon logout (until
-<tt/PAM_CRED_DELETE/ is supported by <em/login/).
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This part of the module won't be terribly useful until we can change
-the environment from within a <tt/Linux-PAM/ module.
-
-</descrip>
-
-<sect2> Password component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/use_first_pass/; <tt/try_first_pass/
-
-<tag><bf>Description:</bf></tag>
-
-This component of the module changes a user's Kerberos password
-by first getting and using the user's old password to get
-a session key for the password changing service, then sending
-a new password to that service.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This should only be used with a real Kerberos v4 <tt/kadmind/. It
-cannot be used with an AFS kaserver unless special provisions are
-made. Contact the module author for more information.
-
-</descrip>
-
-<sect2> Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/use_first_pass/; <tt/try_first_pass/
-
-<tag><bf>Description:</bf></tag>
-
-This component of the module verifies a user's Kerberos password
-by requesting a ticket granting ticket from the Kerberos server
-and optionally using it to attempt to retrieve the local computer's
-host key and verifying using the key file on the local machine if 
-one exists.
-
-It also writes out a ticket file for the user to use later, and 
-deletes the ticket file upon logout (not until <tt/PAM_CRED_DELETE/
-is called from <em/login/).
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This module can be used with a real Kerberos server using MIT
-v4 Kerberos keys. The module or the system Kerberos libraries
-may be modified to support AFS style Kerberos keys. Currently
-this is not supported to avoid cryptography constraints.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_lastlog.sgml b/doc/modules/pam_lastlog.sgml
deleted file mode 100644
index a00f76b1..00000000
--- a/doc/modules/pam_lastlog.sgml
+++ /dev/null
@@ -1,119 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The last login module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_lastlog/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-auth
-
-<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>
-uses information contained in the <tt>/var/log/lastlog</tt> file.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This session module maintains the <tt>/var/log/lastlog</tt> file.  Adding
-an open entry when called via the <tt>pam_open_seesion()</tt> function
-and completing it when <tt>pam_close_session()</tt> is called.  This
-module can also display a line of information about the last login of
-the user.  If an application already performs these tasks, it is not
-necessary to use this module.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/nodate/; <tt/noterm/; <tt/nohost/; <tt/silent/;
-<tt/never/
-
-<tag><bf>Description:</bf></tag>
-
-<p>
-This module can be used to provide a ``Last login on ...''
-message. when the user logs into the system from what ever application
-uses the PAM libraries.  In addition, the module maintains the
-<tt>/var/log/lastlog</tt> file.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-<item><tt/debug/
-- write more information to <tt/syslog(3)/.
-
-<item><tt/nodate/
-- neglect to give the date of the last login when displaying
-information about the last login on the system.
-
-<item><tt/noterm/ 
-- neglect to diplay the terminal name on which the last login was
-attempt.
-
-<item><tt/nohost/
-- neglect to indicate from which host the last login was attempted.
-
-<item><tt/silent/
-- neglect to inform the user about any previous login: just update
-the <tt>/var/log/lastlog</tt> file.
-
-<item><tt/never/
-- if the <tt>/var/log/lastlog</tt> file does not contain any old entries
-for the user, indicate that the user has never previously logged in
-with a ``welcome..." message.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This module can be used to indicate that the user has new mail when
-they <em/login/ to the system. Here is a sample entry for your
-<tt>/etc/pam.d/XXX</tt> file:
-<tscreen>
-<verb>
-#
-# When were we last here?
-#
-session	 optional	pam_lastlog.so
-</verb>
-</tscreen>
-
-<p>
-Note, some applications may perform this function themselves. In such
-cases, this module is not necessary.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_limits.sgml b/doc/modules/pam_limits.sgml
deleted file mode 100644
index 44f057c4..00000000
--- a/doc/modules/pam_limits.sgml
+++ /dev/null
@@ -1,247 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
-   from information compiled by Cristian Gafton (author of module)
--->
-
-<sect1>The resource limits module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_limits/
-
-<tag><bf>Authors:</bf></tag>
-Cristian Gafton &lt;gafton@redhat.com&gt; <newline>
-Thanks are also due to Elliot Lee &lt;sopwith@redhat.com&gt;
-for his comments on improving this module.
-
-<tag><bf>Maintainer:</bf></tag>
-Cristian Gafton - 1996/11/20
-
-<tag><bf>Management groups provided:</bf></tag>
-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 an <tt>/etc/security/limits.conf</tt> file and kernel support
-for resource limits. Also uses the library, <tt/libpwdb/.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets
-limits on the system resources that can be obtained in a
-user-session. Its actions are dictated more explicitly through the
-configuration file discussed below.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt>conf=/path/to/file.conf</tt>; <tt>change_uid</tt>;
-<tt>utmp_early</tt>
-
-<tag><bf>Description:</bf></tag>
-
-Through the contents of the configuration file,
-<tt>/etc/security/limits.conf</tt>, resource limits are placed on
-users' sessions. Users of <tt/uid=0/ are not affected by this
-restriction.
-
-<p>
-The behavior of this module can be modified with the following
-arguments:
-<itemize>
-
-<item><tt/debug/ -
-verbose logging to <tt/syslog(3)/.
-
-<item><tt>conf=/path/to/file.conf</tt> -
-indicate an alternative <em/limits/ configuration file to the default.
-
-<item><tt/change_uid/ - 
-change real uid to the user for who the limits are set up.  Use this
-option if you have problems like login not forking a shell for user
-who has no processes. Be warned that something else may break when
-you do this.
-
-<item><tt/utmp_early/ - 
-some broken applications actually allocate a utmp entry for the user
-before the user is admitted to the system. If some of the services you
-are configuring PAM for do this, you can selectively use this module
-argument to compensate for this behavior and at the same time maintain
-system-wide consistency with a single limits.conf file.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-In order to use this module the system administrator must first create
-a <em/root-only-readable/ file (default is
-<tt>/etc/security/limits.conf</tt>).  This file describes the resource
-limits the superuser wishes to impose on users and groups. No limits
-are imposed on <tt/uid=0/ accounts.
-
-<p>
-Each line of the configuration file describes a limit for a user in
-the form:
-<tscreen>
-<verb>
-<domain>	<type>	<item>		<value>
-</verb>
-</tscreen>
-
-<p>
-The fields listed above should be filled as follows...<newline>
-<tt>&lt;domain&gt;</tt> can be:
-<itemize>
-<item> a username
-<item> a groupname, with <tt>@group</tt> syntax
-<item> the wild-card <tt/*/, for default entry
-<item> the wild-card <tt/%/, for maxlogins limit only,
-can also be used with <tt>%group</tt> syntax
-</itemize>
-
-<p>
-<tt>&lt;type&gt;</tt> can have the three values:
-<itemize>
-
-<item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits
-are set by the superuser and enforced by the Linux Kernel. The user
-cannot raise his requirement of system resources above such values.
-
-<item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits
-are ones that the user can move up or down within the permitted range
-by any pre-exisiting <em/hard/ limits. The values specified with this
-token can be thought of as <em/default/ values, for normal system
-usage.
-
-<item> <tt/-/ for enforcing both <em/soft/ and <em/hard/ limits
-together.
-
-</itemize>
-
-<p>
-<tt>&lt;item&gt;</tt> can be one of the following:
-<itemize>
-<item><tt/core/ - limits the core file size (KB)
-<item><tt/data/ - max data size (KB)
-<item><tt/fsize/ - maximum filesize (KB)
-<item><tt/memlock/ - max locked-in-memory address space (KB)
-<item><tt/nofile/ - max number of open files
-<item><tt/rss/ - max resident set size (KB)
-<item><tt/stack/ - max stack size (KB)
-<item><tt/cpu/ - max CPU time (MIN)
-<item><tt/nproc/ - max number of processes
-<item><tt/as/ - address space limit
-<item><tt/maxlogins/ - max number of logins for this user
-<item><tt/maxsyslogins/ - max number of logins on system
-<item><tt/priority/ - the priority to run user process with (negative
-values boost process priority)
-<item><tt/locks/ - max locked files (Linux 2.4 and higher)
-</itemize>
-
-<p>
-Note, if you specify a type of ``-'' but neglect to supply the
-<tt/item/ and <tt/value/ fields then the module will never enforce any
-limits on the corresponding user/group-members etc. . Note, the first
-entry of the form which applies to the authenticating user will
-override all other entries in the limits configuration file. In such
-cases, the <tt/pam_limits/ module will always return <tt/PAM_SUCCESS/.
-
-<p>
-In general, individual limits have priority over group limits, so if
-you impose no limits for <tt/admin/ group, but one of the members in
-this group have a limits line, the user will have its limits set
-according to this line.
-
-<p>
-Also, please note that all limit settings are set <em/per login/.
-They are not global, nor are they permanent; existing only for the
-duration of the session.
-
-<p>
-In the <em/limits/ configuration file, the ``<tt/#/'' character
-introduces a comment - after which the rest of the line is ignored.
-
-<p>
-The <tt/pam_limits/ module does its best to report configuration
-problems found in its configuration file via <tt/syslog(3)/.
-
-<p>
-The following is an example configuration file:
-<tscreen>
-<verb>
-# EXAMPLE /etc/security/limits.conf file:
-# =======================================
-# <domain>	<type>	<item>		<value>
-*               soft    core            0
-*               hard    rss             10000
-@student        hard    nproc           20
-@faculty        soft    nproc           20
-@faculty        hard    nproc           50
-ftp             hard    nproc           0
-@student        -       maxlogins       4
-</verb>
-</tscreen>
-Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource
-(see <tt/@faculty/) -- this establishes the <em/default/ and permitted
-<em/extreme/ level of resources that the user can obtain in a given
-service-session.
-
-<p>
-Note, that wild-cards <tt/*/ and <tt/%/ have the following meaning when
-used for maxlogins limit
-<itemize>
-<item> <tt/*/ every user
-<item> <tt/%/ all users, or entire group when <tt>%group</tt> is specified 
-</itemize>
-See the following examples:
-<tscreen>
-<verb>
-# EXAMPLE /etc/security/limits.conf file:
-# <domain>	<type>	<item>		<value>
-*               -       maxlogins       2
-@faculty        -       maxlogins       4
-%               -       maxlogins       30
-%student        -       maxlogins       10
-</verb>
-</tscreen>
-Explanation: every user can login 2 times, members of the <tt/faculty/
-group can login 4 times, there can be only 30 logins, only 10 from
-<tt/students/ group.
-
-<p>
-For the services that need resources limits (login for example) put
-the following line in <tt>/etc/pam.conf</tt> as the last line for that
-service (usually after the pam_unix session line:
-<tscreen>
-<verb>
-#
-# Resource limits imposed on login sessions via pam_limits
-#
-login   session    required     pam_limits.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml
deleted file mode 100644
index 3754f57e..00000000
--- a/doc/modules/pam_listfile.sgml
+++ /dev/null
@@ -1,138 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Michael K. Johnson <johnsonm@redhat.com>
--->
-
-<sect1>The list-file module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_listfile/
-
-<tag><bf>Author:</bf></tag>
-Elliot Lee <tt>&lt;sopwith@cuc.edu&gt;</tt>
-
-<tag><bf>Maintainer:</bf></tag>
-Red Hat Software:<newline>
-Michael K. Johnson &lt;johnsonm@redhat.com&gt;  1996/11/18<newline>
-(if unavailable, contact Elliot Lee &lt;sopwith@cuc.edu&gt;).
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-clean
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-The list-file module provides a way to deny or allow services based on
-an arbitrary file.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt>onerr=succeed|fail</tt>;
-<tt>sense=allow|deny</tt>;
-<tt>file=</tt><it>filename</it>;
-<tt>item=user|tty|rhost|ruser|group|shell</tt>
-<tt>apply=user|@group</tt>
-
-<tag><bf>Description:</bf></tag>
-
-The module gets the item of the type specified -- <tt>user</tt> specifies
-the username, <tt>PAM_USER</tt>; tty specifies the name of the terminal
-over which the request has been made, <tt>PAM_TTY</tt>; rhost specifies
-the name of the remote host (if any) from which the request was made,
-<tt>PAM_RHOST</tt>; and ruser specifies the name of the remote user
-(if available) who made the request, <tt>PAM_RUSER</tt> -- and looks for
-an instance of that item in the file <it>filename</it>.  <it>filename</it>
-contains one line per item listed.  If the item is found, then if
-<tt>sense=allow</tt>, <tt>PAM_SUCCESS</tt> is returned, causing the
-authorization request to succeed; else if <tt>sense=deny</tt>,
-<tt>PAM_AUTH_ERR</tt> is returned, causing the authorization
-request to fail.
-
-<p>
-If an error is encountered (for instance, if <it>filename</it>
-does not exist, or a poorly-constructed argument is encountered),
-then if <tt>onerr=succeed</tt>, <tt>PAM_SUCCESS</tt> is returned,
-otherwise if <tt>onerr=fail</tt>, <tt>PAM_AUTH_ERR</tt> or
-<tt>PAM_SERVICE_ERR</tt> (as appropriate) will be returned.
-
-<p>
-An additional argument, <tt>apply=</tt>, can be used to restrict the
-application of the above to a specific user
-(<tt>apply=</tt><em>username</em>) or a given group
-(<tt>apply=@</tt><em>groupname</em>).  This added restriction is only
-meaningful when used with the <tt/tty/, <tt/rhost/ and <tt/shell/
-<em/items/.
-
-<p>
-Besides this last one, all arguments should be specified; do not count
-on any default behavior, as it is subject to change.
-
-<p>
-No credentials are awarded by this module.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Classic ``ftpusers'' authentication can be implemented with this entry
-in <tt>/etc/pam.conf</tt>:
-<tscreen>
-<verb>
-#
-# deny ftp-access to users listed in the /etc/ftpusers file
-#
-ftp	auth	 required	pam_listfile.so \
-	onerr=succeed item=user sense=deny file=/etc/ftpusers
-</verb>
-</tscreen>
-Note, users listed in <tt>/etc/ftpusers</tt> file are
-(counterintuitively) <bf/not/ allowed access to the ftp service.
-
-<p>
-To allow login access only for certain users, you can use a
-<tt/pam.conf/ entry like this:
-<tscreen>
-<verb>
-#
-# permit login to users listed in /etc/loginusers
-#
-login	auth	 required	pam_listfile.so \
-	onerr=fail item=user sense=allow file=/etc/loginusers
-</verb>
-</tscreen>
-
-<p>
-For this example to work, all users who are allowed to use the login
-service should be listed in the file <tt>/etc/loginusers</tt>.  Unless
-you are explicitly trying to lock out root, make sure that when you do
-this, you leave a way for root to log in, either by listing root in
-<tt>/etc/loginusers</tt>, or by listing a user who is able to <em/su/
-to the root account.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml
deleted file mode 100644
index 78ae95dc..00000000
--- a/doc/modules/pam_mail.sgml
+++ /dev/null
@@ -1,142 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The mail module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_mail/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Authentication (credential)
-Session (open)
-
-<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>
-Default mail directory <tt>/var/spool/mail/</tt>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module looks at the user's mail directory and indicates
-whether the user has any mail in it.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/dir=/<em/directory-name/; <tt/nopen/; <tt/close/;
-<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/;
-<tt/quiet/;
-
-<tag><bf>Description:</bf></tag>
-
-This module provides the ``you have new mail'' service to the user. It
-can be plugged into any application that has credential hooks. It gives a
-single message indicating the <em/newness/ of any mail it finds in the
-user's mail folder. This module also sets the <bf/Linux-PAM/
-environment variable, <tt/MAIL/, to the user's mail directory.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-<item><tt/debug/
-- write more information to <tt/syslog(3)/.
-
-<item><tt/dir=/<em/pathname/
-- look for the users' mail in an alternative directory given by
-<em/pathname/.  The default location for mail is
-<tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is
-prefixed by a `<tt/&tilde;/', the directory is interpreted as
-indicating a file in the user's home directory.
-
-<item><tt/nopen/
-- instruct the module to <em/not/ print any mail information when the
-user's credentials are acquired. This flag is useful to get the <tt/MAIL/
-environment variable set, but to not display any information about it.
-
-<item><tt/close/
-- instruct the module to indicate if the user has any mail at the as
-the user's credentials are revoked.
-
-<item><tt/noenv/
-- do not set the <tt/MAIL/ environment variable.
-
-<item><tt/empty/
-- indicate that the user's mail directory is empty if this is found to
-be the case.
-
-<item><tt/hash=/<em/hashcount/
-- mail directory hash depth.  For example, a <em/hashcount/ of 2 would
-make the mailfile be <tt>/var/spool/mail/u/s/user</tt>.
-
-<item><tt/standard/
-- old style "You have..." format which doesn't show the mail spool being used.
-  this also implies "empty"
-
-<item><tt/quiet/
-- only report when there is new mail.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This module can be used to indicate that the user has new mail when
-they <em/login/ to the system. Here is a sample entry for your
-<tt>/etc/pam.conf</tt> file:
-<tscreen>
-<verb>
-#
-# do we have any mail?
-#
-login	session	 optional	pam_mail.so
-</verb>
-</tscreen>
-
-<p>
-Note, if the mail spool file (be it <tt>/var/spool/mail/$USER</tt> or
-a pathname given with the <tt>dir=</tt> parameter) is a directory then
-<tt>pam_mail</tt> assumes it is in the <it>Qmail Maildir</it> format.
-
-<p>
-Note, some applications may perform this function themselves. In such
-cases, this module is not necessary.
-
-</descrip>
-
-<sect2>Authentication component
-
-<p>
-Then authentication companent works the same as the session component,
-except that everything is done during the <tt>pam_setcred()</tt> phase.
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_mkhomedir.sgml b/doc/modules/pam_mkhomedir.sgml
deleted file mode 100644
index 075e16f9..00000000
--- a/doc/modules/pam_mkhomedir.sgml
+++ /dev/null
@@ -1,83 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Create home directories on initial login
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_mkhomedir/
-
-<tag><bf>Author:</bf></tag>
-Jason Gunthorpe &lt;jgg@ualberta.ca&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Management groups provided:</bf></tag>
-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>
-Creates home directories on the fly for authenticated users.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/;
-
-<tag><bf>Description:</bf></tag>
-This module is useful for distributed systems where the user account is
-managed in a central database (such as NIS, NIS+, or LDAP) and accessed
-through miltiple systems. It frees the administrator from having to create
-a default home directory on each of the systems by creating it upon the
-first succesfully authenticated login of that user. The skeleton directory
-(usually /etc/skel/) is used to copy default files and also set's a umask
-for the creation.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/skel/
-- The skeleton directory for default files to copy to the new home directory.
-
-<item><tt/umask/
-- An octal for of the same format as you would pass to the shells umask command.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-session    required   pam_mkhomedir.so skel=/etc/skel/ umask=0022
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml
deleted file mode 100644
index 8ddc6392..00000000
--- a/doc/modules/pam_motd.sgml
+++ /dev/null
@@ -1,77 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Output the motd file
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_motd/
-
-<tag><bf>Author:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Session (open)
-
-<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 module outputs the motd file (<em>/etc/motd</em> by default) upon
-successful login.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/motd=motd-file-name/;
-
-<tag><bf>Description:</bf></tag>
-This module allows you to have arbitrary motd's (message of the day)
-output after a succesful login. By default this file is <em>/etc/motd</em>,
-but is configurable to any file.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/motd/
-- the file to output if not using the default.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-login  session  pam_motd.so  motd=/etc/motd
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml
deleted file mode 100644
index 52cf02a5..00000000
--- a/doc/modules/pam_nologin.sgml
+++ /dev/null
@@ -1,81 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Michael K. Johnson <johnsonm@redhat.com>
--->
-
-<sect1>The no-login module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_nologin/
-
-<tag><bf>Author:</bf></tag>
-Written by Michael K. Johnson &lt;johnsonm@redhat.com&gt;<newline>
-
-<tag><bf>Maintainer:</bf></tag>
-
-<tag><bf>Management groups provided:</bf></tag>
-account; authentication
-
-<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>
-Provides standard Unix <em/nologin/ authentication.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-successok, file=&lt;<em/filename/&gt;
-
-<tag><bf>Description:</bf></tag>
-
-Provides standard Unix <em/nologin/ authentication.  If the file
-<tt>/etc/nologin</tt> exists, only root is allowed to log in; other
-users are turned away with an error message (and the module returns
-<tt/PAM_AUTH_ERR/ or <tt/PAM_USER_UNKNOWN/).  All users (root or
-otherwise) are shown the contents of <tt>/etc/nologin</tt>.
-
-<p>
-If the file <tt>/etc/nologin</tt> does not exist, this module defaults
-to returning <tt/PAM_IGNORE/, but the <tt/successok/ module argument
-causes it to return <tt/PAM_SUCCESS/ in this case.
-
-<p>
-The administrator can override the default nologin file with the
-<tt/file=/<em/pathname/ module argument.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-In order to make this module effective, all login methods should be
-secured by it.  It should be used as a <tt>required</tt> method listed
-before any <tt>sufficient</tt> methods in order to get standard Unix
-nologin semantics. Note, the use of <tt/successok/ module argument
-causes the module to return <tt/PAM_SUCCESS/ and as such would break
-such a configuration - failing <tt/sufficient/ modules would lead to a
-successful login because the nologin module <em/succeeded/.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml
deleted file mode 100644
index fe616ac3..00000000
--- a/doc/modules/pam_permit.sgml
+++ /dev/null
@@ -1,83 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The promiscuous module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_permit
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan, &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Linux-PAM maintainer.
-
-<tag><bf>Management groups provided:</bf></tag>
-account; authentication; password; session
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-VERY LOW. Use with extreme caution.
-
-<tag><bf>Clean code base:</bf></tag>
-Clean.
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module is very dangerous. It should be used with extreme
-caution. Its action is always to permit access. It does nothing else.
-
-<sect2>Account+Authentication+Password+Session components
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-No matter what management group, the action of this module is to
-simply return <tt/PAM_SUCCESS/ -- operation successful.
-
-<p>
-In the case of authentication, the user's name will be acquired. Many
-applications become confused if this name is unknown.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-It is seldom a good idea to use this module. However, it does have
-some legitimate uses.  For example, if the system-administrator wishes
-to turn off the account management on a workstation, and at the same
-time continue to allow logins, then she might use the following
-configuration file entry for login:
-<tscreen>
-<verb>
-#
-# add this line to your other login entries to disable account
-# management, but continue to permit users to log in...
-#
-login	account	 required	pam_permit.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml
deleted file mode 100644
index 2ee102e1..00000000
--- a/doc/modules/pam_pwdb.sgml
+++ /dev/null
@@ -1,249 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@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@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Red Hat.
-
-<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>libpwdb</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.
--->
diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml
deleted file mode 100644
index 2bc4a9cd..00000000
--- a/doc/modules/pam_radius.sgml
+++ /dev/null
@@ -1,117 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Cristian Gafton <gafton@redhat.com>
--->
-
-<sect1>The RADIUS session module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_radius/
-
-<tag><bf>Author:</bf></tag>
-Cristian Gafton &lt;gafton@redhat.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-session
-
-<tag><bf>Cryptographically sensitive:</bf></tag> 
-This module does not deal with passwords
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-gcc reports 1 warning when compiling <tt>/usr/include/rpc/clnt.h</tt>.
-Hey, is not my fault !
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-yes; this is a network module (independent of application).
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module is intended to provide the session service for users
-authenticated with a RADIUS server.  At the present stage, the only
-option supported is the use of the RADIUS server as an accounting
-server.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt/debug/ - verbose logging to <tt/syslog(3)/.
-
-<tag><bf>Description:</bf></tag>
-
-This module is intended to provide the session service for users
-authenticated with a RADIUS server. At the present stage, the only
-option supported is the use of the RADIUS server as an <em/accounting/
-server.  
-
-<p>
-(There are few things which needs to be cleared out first in
-the PAM project until one will be able to use this module and expect
-it to magically start pppd in response to a RADIUS server command to
-use PPP for this user, or to initiate a telnet connection to another
-host, or to hang and call back the user using parameters provided in
-the RADIUS server response. Most of these things are better suited for
-the radius login application. I hope to make available Real Soon (tm)
-patches for the login apps to make it work this way.)
-
-<p>
-When opening a session, this module sends an ``Accounting-Start''
-message to the RADIUS server, which will log/update/whatever a
-database for this user. On close, an ``Accounting-Stop'' message is
-sent to the RADIUS server.
-
-<p>
-This module has no other prerequisites for making it work.  One can
-install a RADIUS server just for fun and use it as a centralized
-accounting server and forget about wtmp/last/sac etc. .
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-For the services that need this module (<em/login/ for example) put
-the following line in <tt>/etc/pam.conf</tt> as the last line for that
-service (usually after the pam_unix session line):
-<tscreen>
-<verb>
-login	session	 required	pam_radius.so
-</verb>
-</tscreen>
-Replace <tt/login/ for each service you are using this module.
-
-<p>
-This module make extensive use of the API provided in libpwdb
-0.54preB or later. By default, it will read the radius server
-configuration (hostname and secret) from <tt>/etc/raddb/server</tt>.
-This is a default compiled into libpwdb, and curently there is no way to
-modify this default without recompiling libpwdb. I am working on
-extending the radius support from libpwdb to provide a possibility
-to make this runtime-configurable.
-
-Also please note that libpwdb will require also the RADIUS
-dictionary to be present (<tt>/etc/raddb/dictionary</tt>).
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
-
diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml
deleted file mode 100644
index 69885047..00000000
--- a/doc/modules/pam_rhosts.sgml
+++ /dev/null
@@ -1,164 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The rhosts module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_rhosts_auth/
-
-<tag><bf>Author:</bf></tag>
-Al Longyear &lt;longyear@netcom.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-Clean.
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module performs the standard network authentication for services,
-as used by traditional implementations of <em/rlogin/ and <em/rsh/
-etc.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/;
-<tt/privategroup/; <tt/promiscuous/; <tt/suppress/
-
-<tag><bf>Description:</bf></tag>
-
-The authentication mechanism of this module is based on the contents
-of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in
-<tt>#include &lt;netdb.h&gt;</tt>) and <tt>~/.rhosts</tt>.  Firstly,
-hosts listed in the former file are treated as equivalent to the
-localhost. Secondly, entries in the user's own copy of the latter file
-is used to map "<tt/remote-host remote-user/" pairs to that user's
-account on the current host. Access is granted to the user if their
-host is present in <tt>/etc/hosts.equiv</tt> and their remote account
-is identical to their local one, or if their remote account has an
-entry in their personal configuration file.
-
-<p>
-Some restrictions are applied to the attributes of the user's personal
-configuration file: it must be a regular file (as defined by
-<tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or
-the user; it must not be writable by any user besides its owner.
-
-<p>
-The module authenticates a remote user (internally specified by the
-item <tt/PAM_RUSER/) connecting from the remote host (internally
-specified by the item <tt/PAM_RHOST/).  Accordingly, for applications
-to be compatible this authentication module they must set these items
-prior to calling <tt/pam_authenticate()/.  The module is not capable
-of independently probing the network connection for such information.
-
-<p>
-In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is
-<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option
-should be used.  Instead, the superuser must have a correctly configured
-personal configuration file.
-
-<p>
-The behavior of the module is modified by flags:
-<itemize>
-<item>
-<tt/debug/ -
-log more information to <tt/syslog(3)/. (XXX - actually, this module
-does not do any logging currently, please volunteer to fix this!)
-
-<item>
-<tt/no_warn/ -
-do not give verbal warnings to the user about failures etc. (XXX -
-this module currently does not issue any warnings, please volunteer to
-fix this!)
-
-<item>
-<tt/no_hosts_equiv/ -
-ignore the contents of the <tt>/etc/hosts.equiv</tt> file.
-
-<item>
-<tt/hosts_equiv_rootok/ -
-allow the use of <tt>/etc/hosts.equiv</tt> for superuser.  Without this
-option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account.
-This option has no effect if the <tt>no_hosts_equiv</tt> option is used.
-
-<item>
-<tt/no_rhosts/ -
-ignore the contents of all user's personal configuration file
-<tt>~/.rhosts</tt>.
-
-<item>
-<tt/privategroup/ -
-normally, the <tt>~/.rhosts</tt> file must not be writable by anyone
-other than its owner.  This option overlooks group write access in the
-case that the group owner of this file has the same name as the
-user being authenticated.  To lessen the security problems associated
-with this option, the module also checks that the user is the only
-member of their private group.
-
-<item>
-<tt/promiscuous/ -
-A host entry of `+' will lead to all hosts being granted
-access. Without this option, '+' entries will be ignored. Note, that
-the <tt/debug/ option will syslog a warning in this latter case.
-
-<item>
-<tt/suppress/ -
-This will prevent the module from <tt/syslog(3)/ing a warning message
-when this authentication fails.  This option is mostly for keeping
-logs free of meaningless errors, in particular when the module is used
-with the <tt/sufficient/ control flag.
-
-</itemize>
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-To allow users to login from trusted remote machines, you should try
-adding the following line to your <tt>/etc/pam.conf</tt> file
-<em/before/ the line that would otherwise prompt the user for a
-password:
-<tscreen>
-<verb>
-#
-# No passwords required for users from hosts listed above.
-#
-login  auth  sufficient  pam_rhosts_auth.so no_rhosts
-</verb>
-</tscreen>
-Note, in this example, the system administrator has turned off all
-<em/personal/ <em/rhosts/ configuration files. Also note, that this module
-can be used to <em/only/ allow remote login from hosts specified in
-the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the
-above example with <tt/required/.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml
deleted file mode 100644
index f6aa8a07..00000000
--- a/doc/modules/pam_rootok.sgml
+++ /dev/null
@@ -1,85 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>The root access module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_rootok
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-<bf>Linux-PAM</bf> maintainer
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-	
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-Clean.
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module is for use in situations where the superuser wishes
-to gain access to a service without having to enter a password.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/
-
-<tag><bf>Description:</bf></tag>
-
-This module authenticates the user if their <tt/uid/ is <tt/0/.
-Applications that are created <em/setuid/-root generally retain the
-<tt/uid/ of the user but run with the authority of an enhanced
-<em/effective-/<tt/uid/. It is the real <tt/uid/ that is checked.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-In the case of the <tt/su/ application the historical usage is to
-permit the superuser to adopt the identity of a lesser user without
-the use of a password. To obtain this behavior under <tt/Linux-PAM/
-the following pair of lines are needed for the corresponding entry in
-the configuration file:
-<tscreen>
-<verb>
-#
-# su authentication. Root is granted access by default.
-#
-su	auth	 sufficient	pam_rootok.so
-su	auth	 required	pam_unix_auth.so
-</verb>
-</tscreen>
-
-<p>
-Note. For programs that are run by the superuser (or started when the
-system boots) this module should not be used to authenticate users.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_securetty.sgml b/doc/modules/pam_securetty.sgml
deleted file mode 100644
index ceb1358c..00000000
--- a/doc/modules/pam_securetty.sgml
+++ /dev/null
@@ -1,72 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Michael K. Johnson <johnsonm@redhat.com>
--->
-
-<sect1>The securetty module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_securetty/
-
-<tag><bf>Author[s]:</bf></tag>
-Elliot Lee &lt;sopwith@cuc.edu&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Red Hat Software:<newline>
-<em/currently/ Michael K. Johnson &lt;johnsonm@redhat.com&gt;<newline>
-(if unavailable, contact Elliot Lee &lt;sopwith@cuc.edu&gt;).
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<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>
-<tt>/etc/securetty</tt> file
-
-<tag><bf>Network aware:</bf></tag>
-
-Requires the application to fill in the <tt>PAM_TTY</tt> item
-correctly in order to act meaningfully.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Provides standard Unix securetty checking.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-Provides standard Unix securetty checking, which causes authentication
-for root to fail unless <tt>PAM_TTY</tt> is set to a string listed in
-the <tt>/etc/securetty</tt> file.  For all other users, it succeeds.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-For canonical usage, should be listed as a <tt>required</tt>
-authentication method before any <tt>sufficient</tt> authentication
-methods.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_tally.sgml b/doc/modules/pam_tally.sgml
deleted file mode 100644
index eeb05518..00000000
--- a/doc/modules/pam_tally.sgml
+++ /dev/null
@@ -1,191 +0,0 @@
-<!--
-
-   $Id$
-   
-   This template file was written by Andrew G. Morgan <morgan@kernel.org>
-   adapted from text provided by Tim Baverstock.
--->
-
-<sect1>The login counter (tallying) module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_tally
-
-<tag><bf>Author[s]:</bf></tag>
-Tim Baverstock
-
-<tag><bf>Maintainer:</bf></tag>
-
-<tag><bf>Management groups provided:</bf></tag>
-auth; account
-
-<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>
-A faillog file (default location /var/log/faillog)
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module maintains a count of attempted accesses, can reset count
-on success, can deny access if too many attempts fail.
-
-<p>
-pam_tally comes in two parts: <tt>pam_tally.so</tt> and
-<tt>pam_tally</tt>. The former is the PAM module and the latter, a
-stand-alone program. <tt>pam_tally</tt> is an (optional) application
-which can be used to interrogate and manipulate the counter file. It
-can display users' counts, set individual counts, or clear all
-counts. Setting artificially high counts may be useful for blocking
-users without changing their passwords. For example, one might find it
-useful to clear all counts every midnight from a cron job.
-
-<p>
-The counts file is organized as a binary-word array, indexed by
-uid. You can probably make sense of it with <tt>od</tt>, if you don't
-want to use the supplied appliction.
-
-<p>
-Note, there are some outstanding issues with this module:
-<tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database
-of usernames would be much more flexible; the `keep a count of current
-logins' bit has been <tt>#ifdef</tt>'d out and you can only reset the
-counter on successful authentication, for now.
-
-<sect3>Generic options accepted by both components
-<p>
-<itemize>
-<item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>):
-   if something weird happens, such as unable to open the file, how
-   should the module react?
-<item> <tt>file=</tt><em>/where/to/keep/counts</em>:
-   specify the file location for the counts.
-   The default location is <tt>/var/log/faillog</tt>.
-</itemize>
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
-<tt>file=</tt>/where/to/keep/counts;
-<tt>no_magic_root</tt>
-
-<tag><bf>Description:</bf></tag>
-
-<p>
-The authentication component of this module increments the attempted
-login counter.
-
-<p>
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-<p>
-The module argument <tt>no_magic_root</tt> is used to indicate that if
-the module is invoked by a user with uid=0, then the counter is
-incremented. The sys-admin should use this for daemon-launched
-services, like <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. For user
-launched services, like <tt>su</tt>, this argument should be omitted.
-
-<p>
-By way of more explanation, when a process already running as root
-tries to access some service, the access is <em>magic</em>, and
-bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing
-from root into an account otherwise blocked. However, for services
-like <tt>telnet</tt> or <tt>login</tt>, which always effectively run
-from the root account, root (ie everyone) shouldn't be granted this
-magic status, and the flag `no_magic_root' should be set in this
-situation, as noted in the summary above.
-
-</descrip>
-
-<sect2>Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
-<tt>file=</tt>/where/to/keep/counts;
-<tt>deny=</tt><em>n</em>;
-<tt>no_magic_root</tt>;
-<tt>even_deny_root_account</tt>;
-<tt>reset</tt>;
-<tt>no_reset</tt>;
-<tt>per_user</tt>;
-<tt>no_lock_time</tt>
-
-<tag><bf>Description:</bf></tag>
-
-<p>
-The account component can deny access and/or reset the attempts
-counter. It also checks to make sure that the counts file is a plain
-file and not world writable.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-<p>
-The <tt>deny=</tt><em>n</em> option is used to deny access if tally
-for this user exceeds <em>n</em>. The presence of
-<tt>deny=</tt><em>n</em> changes the default for
-<tt>reset</tt>/<tt>no_reset</tt> to <tt>reset</tt>, unless the user
-trying to gain access is root and the <tt>no_magic_root</tt> option
-has NOT been specified.
-
-<p>
-The <tt>no_magic_root</tt> option ensures that access attempts by root
-DON'T ignore deny.  Use this for daemon-based stuff, like
-<tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>.
-
-<p>
-The <tt>even_deny_root_account</tt> option is used to ensure that the
-root account can become unavailable. <bf>Note</bf> that magic root
-trying to gain root bypasses this, but normal users can be locked out.
-
-<p>
-The <tt>reset</tt> option instructs the module to reset count to 0 on
-successful entry, even for magic root. The <tt>no_reset</tt> option is
-used to instruct the module to not reset the count on successful
-entry.  This is the default unless <tt>deny</tt> exists and the user
-attempting access is NOT magic root.
-
-<p>
-If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max</tt>
-field for this user then the <tt>per_user</tt> module argument will
-ensure that the module uses this value and not the global
-<tt>deny=</tt><em>n</em> parameter.
-
-<p>
-The <tt>no_lock_time</tt> option is for ensuring that the module does
-not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this
-user.
-
-<p>
-Normally, failed attempts to access root will <bf>NOT</bf> cause the
-root account to become blocked, to prevent denial-of-service: if your
-users aren't given shell accounts and root may only login via
-<tt>su</tt> or at the machine console (not
-<tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want
-root to be blocked for some given service, use
-<tt>even_deny_root_account</tt>.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml
deleted file mode 100644
index 8c5f677f..00000000
--- a/doc/modules/pam_time.sgml
+++ /dev/null
@@ -1,166 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>Time control
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_time/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <tt>&lt;morgan@kernel.org&gt;</tt>
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-account
-
-<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 a configuration file <tt>/etc/security/time.conf</tt>
-
-<tag><bf>Network aware:</bf></tag>
-Through the <tt/PAM_TTY/ item only
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Running a well regulated system occasionally involves restricting
-access to certain services in a selective manner.  This module offers
-some time control for access to services offered by a system.  Its
-actions are determined with a configuration file.  This module can be
-configured to deny access to (individual) users based on their name,
-the time of day, the day of week, the service they are applying for
-and their terminal from which they are making their request.
-
-<sect2>Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-This module bases its actions on the rules listed in its configuration
-file: <tt>/etc/security/time.conf</tt>.  Each rule has the following
-form,
-<tscreen>
-<em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/
-</tscreen>
-In words, each rule occupies a line, terminated with a newline or the
-beginning of a comment; a `<tt/#/'.  It contains four fields separated
-with semicolons, `<tt/;/'. The fields are as follows:
-
-<p>
-<itemize>
-<item><em/services/ -
-a logic list of service names that are affected by this rule.
-
-<item><em/ttys/ -
-a logic list of terminal names indicating those terminals covered by
-the rule.
-
-<item><em/user/ -
-a logic list of usernames to which this rule applies
-
-<p>
-By a logic list we mean a sequence of tokens (associated with the
-appropriate <tt/PAM_/ item), containing no more than one wildcard
-character; `<tt/*/', and optionally prefixed with a negation operator;
-`<tt/!/'. Such a sequence is concatenated with one of two logical
-operators: <tt/&amp;/ (logical AND) and <tt/|/ (logical OR).  Two
-examples are: <tt>!morgan&amp;!root</tt>, indicating that this rule
-does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and
-<tt>tty*&amp;!ttyp*</tt>, which indicates that the rule applies only
-to console terminals but not pseudoterminals.
-
-<item><em/times/ - a logic list of times at which this rule
-applies. The format of each element is a day/time-range. The days are
-specified by a sequence of two character entries.  For example,
-<tt/MoTuSa/, indicates Monday Tuesday and Saturday.  Note that
-repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and
-<tt/MoWk/ means all weekdays bar Monday.  The two character
-combinations accepted are,
-<tscreen>
-<verb>
-Mo Tu We Th Fr Sa Su Wk Wd Al
-</verb>
-</tscreen>
-The last two of these being <em/weekend/ days and <em/all 7 days/ of
-the week respectively.
-
-<p>
-The time range part is a pair of 24-hour times, <em/HHMM/, separated
-by a hyphen -- indicating the start and finish time for the rule.  If
-the finsish time is smaller than the start time, it is assumed to
-apply on the following day. For an example, <tt/Mo1800-0300/ indicates
-that the permitted times are Monday night from 6pm to 3am the
-following morning.
-
-</itemize>
-
-<p>
-Note, that the given time restriction is only applied when the first
-three fields are satisfied by a user's application for service.
-
-<p>
-For convenience and readability a rule can be extended beyond a single
-line with a `<tt>&bsol;</tt><em/newline/'.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-The use of this module is initiated with an entry in the
-<bf/Linux-PAM/ configuration file of the following type:
-<tscreen>
-<verb>
-#
-# apply pam_time accounting to login requests
-#
-login	account	 required	pam_time.so
-</verb>
-</tscreen>
-where, here we are applying the module to the <em/login/ application.
-
-<p>
-Some examples of rules that can be placed in the
-<tt>/etc/security/time.conf</tt> configuration file are the following:
-<descrip>
-
-<tag><tt>login ; tty* &amp; !ttyp* ; !root ; !Al0000-2400</tt></tag>
-all users except for <tt/root/ are denied access to console-login at
-all times.
-
-<tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag>
-games (configured to use Linux-PAM) are only to be accessed out of
-working hours.  This rule does not apply to the user <tt/waster/.
-
-</descrip>
-
-<p>
-Note, currently there is no daemon enforcing the end of a session.
-This needs to be remedied.
-
-<p>
-Poorly formatted rules are logged as errors using <tt/syslog(3)/.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml
deleted file mode 100644
index 286cd3f8..00000000
--- a/doc/modules/pam_unix.sgml
+++ /dev/null
@@ -1,288 +0,0 @@
-<!--
-   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>
--->
-
-<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>
-
-<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 as well 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.
--->
diff --git a/doc/modules/pam_userdb.sgml b/doc/modules/pam_userdb.sgml
deleted file mode 100644
index bdbf80b8..00000000
--- a/doc/modules/pam_userdb.sgml
+++ /dev/null
@@ -1,112 +0,0 @@
-<!--
-   This file was written by Cristian Gafton <gafton@redhat.com>
--->
-
-<sect1>The userdb module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_userdb/
-
-<tag><bf>Author:</bf></tag>
-Cristian Gafton &lt;gafton@redhat.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<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 Berkeley DB.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Look up users in a .db database and verify their password against
-what is contained in that database.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/icase/;
-<tt/dump/;
-<tt/db=XXXX/;
-
-<tag><bf>Description:</bf></tag>
-
-This module is used to verify a username/password pair against values stored in
-a Berkeley DB database. The database is indexed by the username, and the data 
-fields corresponding to the username keys are the passwords, in unencrypted form,
-so caution must be exercised over the access rights to the DB database itself..
-
-The module will read the password from the user using the conversation mechanism. If
-you are using this module on top of another authetication module (like <tt/pam_pwdb/;)
-then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module.
-
-<p>
-The action of the module may be modified from this default by one or
-more of the following flags in the <tt>/etc/pam.d/&lt;service&gt;</tt> file.
-<itemize>
-<item>
-<tt/debug/ -
-Supply more debugging information to <tt/syslog(3)/.
-
-<item>
-<tt/icase/ -
-Perform the password comparisons case insensitive.
-
-<item>
-<tt/dump/ -
-dump all the entries in the database to the log (eek,
-don't do this by default!)
-
-<item>
-<tt/db=XXXX/ - 
-use the database found on pathname XXXX. Note that Berkeley DB usually adds the 
-needed filename extension for you, so you should use something like <tt>/etc/foodata</tt>
-instead of <tt>/etc/foodata.db</tt>.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> 
-on most systems) that will accept for login users whose username/password pairs are 
-provided in the <tt>/tmp/dbtest.db</tt> file:
-
-<tscreen>
-<verb>
-#%PAM-1.0
-auth       required     pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
-auth       sufficient   pam_userdb.so icase db=/tmp/dbtest
-auth       required     pam_pwdb.so shadow nullok try_first_pass
-auth       required     pam_shells.so
-account    required     pam_pwdb.so
-session    required     pam_pwdb.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml
deleted file mode 100644
index 4c2e3e18..00000000
--- a/doc/modules/pam_warn.sgml
+++ /dev/null
@@ -1,67 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
--->
-
-<sect1>Warning logger module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_warn/
-
-<tag><bf>Author:</bf></tag>
-Andrew G. Morgan &lt;morgan@kernel.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication; password
-
-<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>
-logs information about the remote user and host (if pam-items are known)
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module is principally for logging information about a
-proposed authentication or application to update a password.
-
-<sect2>Authentication+Password component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-Log the service, terminal, user, remote user and remote host to
-<tt/syslog(3)/. The items are not probed for, but instead obtained
-from the standard pam-items.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-an example is provided in the configuration file section <ref
-id="configuration" name="above">.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml
deleted file mode 100644
index 8c07a8b7..00000000
--- a/doc/modules/pam_wheel.sgml
+++ /dev/null
@@ -1,125 +0,0 @@
-<!--
-   $Id$
-   
-   This file was written by Andrew G. Morgan <morgan@kernel.org>
-	from notes provided by Cristian Gafton.
--->
-
-<sect1>The wheel module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_wheel/
-
-<tag><bf>Author:</bf></tag>
-Cristian Gafton &lt;gafton@redhat.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<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 libpwdb.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Only permit root access to members of the wheel (<tt/gid=0/) group.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/use_uid/;
-<tt/trust/;
-<tt/deny/;
-<tt/group=XXXX/
-
-<tag><bf>Description:</bf></tag>
-
-This module is used to enforce the so-called <em/wheel/ group. By
-default, it permits root access to the system if the applicant user is
-a member of the <tt/wheel/ group (first, the module checks for the
-existence of a '<tt/wheel/' group. Otherwise the module defines the
-group with group-id <tt/0/ to be the <em/wheel/ group).
-
-<p>
-The action of the module may be modified from this default by one or
-more of the following flags in the <tt>/etc/pam.conf</tt> file.
-<itemize>
-<item>
-<tt/debug/ -
-Supply more debugging information to <tt/syslog(3)/.
-
-<item>
-<tt/use_uid/ -
-This option modifies the behavior of the module by using the current
-<tt/uid/ of the process and not the <tt/getlogin(3)/ name of the user.
-This option is useful for being able to jump from one account to
-another, for example with 'su'.
-
-<item>
-<tt/trust/ -
-This option instructs the module to return <tt/PAM_SUCCESS/ should it
-find the user applying for root privilege is a member of the wheel
-group. The default action is to return <tt/PAM_IGNORE/ in this
-situation. By using the <tt/trust/ option it is possible to arrange
-for <tt/wheel/-group members to become root without typing a
-password. <bf/USE WITH CARE/.
-
-<item>
-<tt/deny/ - 
-This is used to reverse the logic of the module's behavior.
-If the user is trying to get <tt/uid=0/ access and is a member of the wheel
-group, deny access (for the wheel group, this is perhaps nonsense!):
-it is intended for use in conjunction with the <tt/group=/ argument...
-
-<item>
-<tt/group=XXXX/ -
-Instead of checking the <tt/gid=0/ group, use the user's <tt/XXXX/
-group membership for the authentication. Here, <tt/XXXX/ is the name
-of the group and <bf/not/ its numeric identifier.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-To restrict access to superuser status to the members of the
-<tt/wheel/ group, use the following entries in your configuration
-file:
-<tscreen>
-<verb>
-#
-# root gains access by default (rootok), only wheel members can 
-# become root (wheel) but Unix authenticate non-root applicants.
-#
-su	auth	 sufficient	pam_rootok.so
-su	auth	 required	pam_wheel.so
-su	auth	 required	pam_unix_auth.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
deleted file mode 100644
index 85a878a0..00000000
--- a/doc/pam_appl.sgml
+++ /dev/null
@@ -1,1782 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id$
-
-    Copyright (C) Andrew G. Morgan 1996-2001.  All rights reserved.
-
-Redistribution and use in source (sgml) and binary (derived) forms,
-with or without modification, are permitted provided that the
-following conditions are met:
-
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-ALTERNATIVELY, this product may be distributed under the terms of the
-GNU General Public License, in which case the provisions of the GNU
-GPL are required INSTEAD OF the above restrictions.  (This clause is
-necessary due to a potential bad interaction between the GNU GPL and
-the restrictions contained in a BSD-style copyright.)
-
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
- -->
-
-<article>
-
-<title>The Linux-PAM Application Developers' Guide
-<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<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
-might use the <bf>Linux-PAM</bf> library to authenticate users. In
-addition it contains a description of the funtions to be found in
-<tt/libpam_misc/ library, that can be used in general applications.
-Finally, it contains some comments on PAM related security issues for
-the application developer.
-</abstract>
-
-<toc>
-
-<sect>Introduction
-
-<sect1>Synopsis
-
-<p>
-For general applications that wish to use the services provided by
-<bf/Linux-PAM/ the following is a summary of the relevant linking
-information:
-<tscreen>
-<verb>
-#include <security/pam_appl.h>
-
-cc -o application .... -lpam -ldl
-</verb>
-</tscreen>
-
-<p>
-In addition to <tt/libpam/, there is a library of miscellaneous
-functions that make the job of writing <em/PAM-aware/ applications
-easier (this library is not covered in the DCE-RFC for PAM and is
-specific to the Linux-PAM distribution):
-<tscreen>
-<verb>
-...
-#include <security/pam_misc.h>
-
-cc -o application .... -lpam -lpam_misc -ldl
-</verb>
-</tscreen>
-
-<sect1> Description
-
-<p>
-<bf>Linux-PAM</bf> (Pluggable Authentication Modules for Linux) is a
-library that enables the local system administrator to choose how
-individual applications authenticate users.  For an overview of the
-<bf>Linux-PAM</bf> library see the <bf/Linux-PAM/ System
-Administrators' Guide.
-
-<p>
-It is the purpose of the <bf>Linux-PAM</bf> project to liberate the
-development of privilege granting software from the development of
-secure and appropriate authentication schemes.  This is accomplished
-by providing a documented library of functions that an application may
-use for all forms of user authentication management. This library
-dynamically loads locally configured authentication modules that
-actually perform the authentication tasks.
-
-<p>
-From the perspective of an application developer the information
-contained in the local configuration of the PAM library should not be
-important.  Indeed it is intended that an application treat the
-functions documented here as a ``black box'' that will deal with all
-aspects of user authentication. ``All aspects'' includes user
-verification, account management, session initialization/termination
-and also the resetting of passwords (<em/authentication tokens/).
-
-<sect>Overview
-
-<p>
-Most service-giving applications are restricted.  In other words,
-their service is not available to all and every prospective client.
-Instead, the applying client must jump through a number of hoops to
-convince the serving application that they are authorized to obtain
-service.
-
-The process of <em/authenticating/ a client is what PAM is designed to
-manage.  In addition to authentication, PAM provides account
-management, credential management, session management and
-authentication-token (password changing) management services.  It is
-important to realize when writing a PAM based application that these
-services are provided in a manner that is <bf>transparent</bf> to
-the application.  That is to say, when the application is written, no
-assumptions can be made about <em>how</em> the client will be
-authenticated.
-
-<p>
-The process of authentication is performed by the PAM library via a
-call to <tt>pam_authenticate()</tt>.  The return value of this
-function will indicate whether a named client (the <em>user</em>) has
-been authenticated.  If the PAM library needs to prompt the user for
-any information, such as their <em>name</em> or a <em>password</em>
-then it will do so.  If the PAM library is configured to authenticate
-the user using some silent protocol, it will do this too.  (This
-latter case might be via some hardware interface for example.)
-
-<p>
-It is important to note that the application must leave all decisions
-about when to prompt the user at the discretion of the PAM library.
-
-<p>
-The PAM library, however, must work equally well for different styles
-of application.  Some applications, like the familiar <tt>login</tt>
-and <tt>passwd</tt> are terminal based applications, exchanges of
-information with the client in these cases is as plain text messages.
-Graphically based applications, however, have a more sophisticated
-interface.  They generally interact with the user via specially
-constructed dialogue boxes.  Additionally, network based services
-require that text messages exchanged with the client are specially
-formatted for automated processing: one such example is <tt>ftpd</tt>
-which prefixes each exchanged message with a numeric identifier.
-
-<p>
-The presentation of simple requests to a client is thus something very
-dependent on the protocol that the serving application will use.  In
-spite of the fact that PAM demands that it drives the whole
-authentication process, it is not possible to leave such protocol
-subtleties up to the PAM library.  To overcome this potential problem,
-the application provides the PAM library with a <em>conversation</em>
-function.  This function is called from <bf>within</bf> the PAM
-library and enables the PAM to directly interact with the client.  The
-sorts of things that this conversation function must be able to do are
-prompt the user with text and/or obtain textual input from the user
-for processing by the PAM library.  The details of this function are
-provided in a later section.
-
-<p>
-For example, the conversation function may be called by the PAM library
-with a request to prompt the user for a password.  Its job is to
-reformat the prompt request into a form that the client will
-understand.  In the case of <tt>ftpd</tt>, this might involve prefixing
-the string with the number <tt>331</tt> and sending the request over
-the network to a connected client.  The conversation function will
-then obtain any reply and, after extracting the typed password, will
-return this string of text to the PAM library.  Similar concerns need
-to be addressed in the case of an X-based graphical server.
-
-<p>
-There are a number of issues that need to be addressed when one is
-porting an existing application to become PAM compliant.  A section
-below has been devoted to this: Porting legacy applications.
-
-<p>
-Besides authentication, PAM provides other forms of management.
-Session management is provided with calls to
-<tt>pam_open_session()</tt> and <tt>pam_close_session()</tt>.  What
-these functions actually do is up to the local administrator.  But
-typically, they could be used to log entry and exit from the system or
-for mounting and unmounting the user's home directory.  If an
-application provides continuous service for a period of time, it
-should probably call these functions, first open after the user is
-authenticated and then close when the service is terminated.
-
-<p>
-Account management is another area that an application developer
-should include with a call to <tt/pam_acct_mgmt()/.  This call will
-perform checks on the good health of the user's account (has it
-expired etc.). One of the things this function may check is whether
-the user's authentication token has expired - in such a case the
-application may choose to attempt to update it with a call to
-<tt/pam_chauthtok()/, although some applications are not suited to
-this task (<em>ftp</em> for example) and in this case the application
-should deny access to the user.
-
-<p>
-PAM is also capable of setting and deleting the users credentials with
-the call <tt>pam_setcred()</tt>.  This function should always be
-called after the user is authenticated and before service is offered
-to the user.  By convention, this should be the last call to the PAM
-library before the PAM session is opened.  What exactly a credential
-is, is not well defined.  However, some examples are given in the
-glossary below.
-
-<sect>The public interface to <bf>Linux-PAM</bf>
- 
-<p>
-Firstly, the relevant include file for the <bf>Linux-PAM</bf> library
-is <tt>&lt;security/pam_appl.h&gt;</tt>. It contains the definitions
-for a number of functions. After listing these functions, we collect
-some guiding remarks for programmers.
-
-<sect1>What can be expected by the application
-
-<p>
-Below we document those functions in the <bf/Linux-PAM/ library that
-may be called from an application.
-
-<sect2>Initialization of Linux-PAM
-<label id="pam-start-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_start(const char *service_name, const char *user,
-		     const struct pam_conv *pam_conversation,
-		     pam_handle_t **pamh);
-</verb>
-</tscreen>
-
-<p>
-This is the first of the <bf>Linux-PAM</bf> functions that must be
-called by an application. It initializes the interface and reads the
-system configuration file, <tt>/etc/pam.conf</tt> (see the
-<bf/Linux-PAM/ System Administrators' Guide).  Following a successful
-return (<tt/PAM_SUCCESS/) the contents of <tt/*pamh/ is a handle that
-provides continuity for successive calls to the <bf/Linux-PAM/
-library.  The arguments expected by <tt/pam_start/ are as follows: the
-<tt/service_name/ of the program, the <tt/user/name of the individual
-to be authenticated, a pointer to an application-supplied
-<tt/pam_conv/ structure and a pointer to a <tt/pam_handle_t/
-<em/pointer/.
-
-<p>
-The <tt>pam_conv</tt> structure is discussed more fully in the section
-<ref id="the-conversation-function" name="below">.  The
-<tt>pam_handle_t</tt> is a <em>blind</em> structure and the
-application should not attempt to probe it directly for information.
-Instead the <bf>Linux-PAM</bf> library provides the functions
-<tt>pam_set_item</tt> and <tt>pam_get_item</tt>.  These functions are
-documented below.
-
-<sect2>Termination of the library
-<label id="pam-end-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_end(pam_handle_t *pamh, int pam_status);
-</verb>
-</tscreen>
-
-<p>
-This function is the last function an application should call in the
-<bf>Linux-PAM</bf> library.  Upon return the handle <tt/pamh/ is no
-longer valid and all memory associated with it will be invalid (likely
-to cause a segmentation fault if accessed).
-
-<p>
-Under normal conditions the argument <tt/pam_status/ has the value
-PAM_SUCCESS, but in the event of an unsuccessful application for
-service the appropriate <bf/Linux-PAM/ error-return value should be
-used here. Note, <tt/pam_end()/ unconditionally shuts down the
-authentication stack associated with the <tt/pamh/ handle. The value
-taken by <tt/pam_status/ is used as an argument to the module specific
-callback functions, <tt/cleanup()/ (see the <bf/Linux-PAM/ <htmlurl
-url="pam_modules.html" name="Module Developers' Guide">). In this way,
-the module can be given notification of the pass/fail nature of the
-tear-down process, and perform any last minute tasks that are
-appropriate to the module before it is unlinked.
-
-<sect2>Setting PAM items
-<label id="pam-set-item-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_set_item(pam_handle_t *pamh, int item_type,
-			const void *item);
-</verb>
-</tscreen>
-
-<p>This function is used to (re)set the value of one of the following
-<bf/item_type/s:
-
-<p><descrip>
-<tag><tt/PAM_SERVICE/</tag>
-
-     	The service name (which identifies that PAM stack that
-     	<tt/libpam/ will use to authenticate the program).
-
-<tag><tt/PAM_USER/</tag>
-
-	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: ''.
-
-<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.
-
-<tag><tt/PAM_RUSER/</tag>
-
-        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/ 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">).
-
-<tag><tt/PAM_FAIL_DELAY/</tag> A function pointer to redirect
-        centrally managed failure delays (see section <ref
-        id="the-failure-delay-function" name="below">).
-
-</descrip>
-
-<p>
-For all <tt/item_type/s, other than <tt/PAM_CONV/ and
-<tt/PAM_FAIL_DELAY/, <tt/item/ is a pointer to a <tt>&lt;NUL&gt;</tt>
-terminated character string.  In the case of <tt/PAM_CONV/, <tt/item/
-points to an initialized <tt/pam_conv/ structure (see section <ref
-id="the-conversation-function" name="below">). In the case of
-<tt/PAM_FAIL_DELAY/, <tt/item/ is a function pointer: <tt/void
-(*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)/ (see
-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 at least one the following errors:
-
-<p>
-<descrip>
-<tag><tt/PAM_SYSTEM_ERR/</tag>
-        The <tt/pam_handle_t/ passed as a first argument to this
-        function was invalid.
-<tag><tt/PAM_PERM_DENIED/</tag>
-	An attempt was made to replace the conversation structure with
-        a <tt/NULL/ value.
-<tag><tt/PAM_BUF_ERR/</tag>
-	The function ran out of memory making a copy of the item.
-<tag><tt/PAM_BAD_ITEM/</tag>
-	The application attempted to set an undefined or inaccessible
-	item.
-</descrip>
-
-<sect2>Getting PAM items
-<label id="pam-get-item-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_get_item(const pam_handle_t *pamh, int item_type,
-			const void **item);
-</verb>
-</tscreen>
-
-<p>
-This function is used to obtain the value of the indicated
-<tt/item_type/.  Upon successful return, <tt/*item/ contains a pointer
-to the value of the corresponding item.  Note, this is a pointer to
-the <em/actual/ data and should <em/not/ be <tt/free()/'ed or
-over-written!
-
-<p>
-A successful call is signaled by a return value of <tt/PAM_SUCCESS/.
-However, the application should expect one of the following errors:
-
-<p>
-<descrip>
-<tag><tt/PAM_SYSTEM_ERR/</tag>
-        The <tt/pam_handle_t/ passed as a first argument to this
-        function was invalid.
-<tag><tt/PAM_PERM_DENIED/</tag>
-	The value of <tt/item/ was <tt/NULL/.
-<tag><tt/PAM_BAD_ITEM/</tag>
-	The application attempted to set an undefined or inaccessible
-	item.
-</descrip>
-
-<p>
-Note, in the case of an error, the contents of <tt/item/ is not
-modified - that is, it retains its pre-call value. One should take
-care to initialize this value prior to calling
-<tt/pam_get_item()/. Since, if its value - despite the
-<tt/pam_get_item()/ function failing - is to be used the consequences
-are undefined.
-
-<sect2>Understanding errors
-<label id="pam-strerror-section">
-
-<p>
-<tscreen>
-<verb>
-extern const char *pam_strerror(pam_handle_t *pamh, int errnum);
-</verb>
-</tscreen>
-
-<p>
-This function returns some text describing the <bf>Linux-PAM</bf>
-error associated with the argument <tt/errnum/.  If the error is not
-recognized ``<tt/Unknown Linux-PAM error/'' is returned.
-
-<sect2>Planning for delays
-<label id="the-failure-delay-function">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec);
-</verb>
-</tscreen>
-
-<p>
-This function is offered by <bf/Linux-PAM/ to facilitate time delays
-following a failed call to <tt/pam_authenticate()/ and before control
-is returned to the application. When using this function the
-application programmer should check if it is available with,
-<tscreen>
-<verb>
-#ifdef PAM_FAIL_DELAY
-    ....
-#endif /* PAM_FAIL_DELAY */
-</verb>
-</tscreen>
-
-
-<p>
-Generally, an application requests that a user is authenticated by
-<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or
-<tt/pam_chauthtok()/.  These functions call each of the <em/stacked/
-authentication modules listed in the relevant <bf/Linux-PAM/
-configuration file.  As directed by this file, one of more of the
-modules may fail causing the <tt/pam_...()/ call to return an error.
-It is desirable for there to also be a pause before the application
-continues. The principal reason for such a delay is security: a delay
-acts to discourage <em/brute force/ dictionary attacks primarily, but
-also helps hinder <em/timed/ (covert channel) attacks.
-
-<p>
-The <tt/pam_fail_delay()/ function provides the mechanism by which an
-application or module can suggest a minimum delay (of <tt/micro_sec/
-<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time
-requested with this function. Should <tt/pam_authenticate()/ fail,
-the failing return to the application is delayed by an amount of time
-randomly distributed (by up to 25%) about this longest value.
-
-<p>
-Independent of success, the delay time is reset to its zero default
-value when <bf/Linux-PAM/ returns control to the application.
-
-<p>
-For applications written with a single thread that are event driven in
-nature, <tt/libpam/ generating this delay may be undesirable. Instead,
-the application may want to register the delay in some other way. For
-example, in a single threaded server that serves multiple
-authentication requests from a single event loop, the application
-might want to simply mark a given connection as blocked until an
-application timer expires. For this reason, <bf/Linux-PAM/ supplies
-the <tt/PAM_FAIL_DELAY/ item. It can be queried and set with
-<tt/pam_get_item()/ and <tt/pam_set_item()/ respectively. The value
-used to set it should be a function pointer of the following
-prototype:
-
-<tscreen>
-<verb>
-void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
-</verb>
-</tscreen>
-
-The arguments being the <tt/retval/ return code of the module stack,
-the <tt/usec_delay/ micro-second delay that libpam is requesting and
-the <tt/appdata_ptr/ that the application has associated with the
-current <tt/pamh/ (<tt/pam_handle_t/). This last value was set by the
-application when it called <tt/pam_start/ or explicitly with
-<tt/pam_set_item(... , PAM_CONV, ...)/. Note, if <tt/PAM_FAIL_DELAY/
-is unset (or set to <tt/NULL/), then <tt/libpam/ will perform any
-delay.
-
-<sect2>Authenticating the user
-
-<p>
-<tscreen>
-<verb>
-extern int pam_authenticate(pam_handle_t *pamh, int flags);
-</verb>
-</tscreen>
-
-<p>
-This function serves as an interface to the authentication mechanisms
-of the loaded modules.  The single <em/optional/ flag, which may be
-logically OR'd with <tt/PAM_SILENT/, takes the following value,
-
-<p><descrip>
-
-<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag>
-	Instruct the authentication modules to return
-<tt/PAM_AUTH_ERR/ if the user does not have a registered
-authorization token---it is set to <tt/NULL/ in the system database.
-</descrip>
-
-<p>
-The value returned by this function is one of the following:
-
-<p><descrip>
-
-<tag><tt/PAM_AUTH_ERR/</tag>
-	The user was not authenticated
-<tag><tt/PAM_CRED_INSUFFICIENT/</tag>
-	For some reason the application does not have sufficient
-credentials to authenticate the user.
-<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag>
-	The modules were not able to access the authentication
-information. This might be due to a network or hardware failure etc.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The supplied username is not known to the authentication
-service
-<tag><tt/PAM_MAXTRIES/</tag>
-	One or more of the authentication modules has reached its
-limit of tries authenticating the user. Do not try again.
-
-</descrip>
-
-<p>
-If one or more of the authentication modules fails to load, for
-whatever reason, this function will return <tt/PAM_ABORT/.
-
-<sect2>Setting user credentials
-<label id="pam-setcred-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_setcred(pam_handle_t *pamh, int flags);
-</verb>
-</tscreen>
-
-<p>
-This function is used to set the module-specific credentials of the
-user.  It is usually called after the user has been authenticated,
-after the account management function has been called but before a
-session has been opened for the user.
-
-<p>
-A credential is something that the user possesses.  It is some
-property, such as a <em>Kerberos</em> ticket, or a supplementary group
-membership that make up the uniqueness of a given user.  On a Linux
-(or UN*X system) the user's <tt>UID</tt> and <tt>GID</tt>'s are
-credentials too.  However, it has been decided that these properties
-(along with the default supplementary groups of which the user is a
-member) are credentials that should be set directly by the application
-and not by PAM.
-
-<p>
-This function simply calls the <tt/pam_sm_setcred/ functions of each
-of the loaded modules.  Valid <tt/flags/, any one of which, may be
-logically OR'd with <tt/PAM_SILENT/, are:
-
-<p><descrip>
-<tag><tt/PAM_ESTABLISH_CRED/</tag>
-	Set the credentials for the authentication service,
-<tag><tt/PAM_DELETE_CRED/</tag>
-	Delete the credentials associated with the authentication service,
-<tag><tt/PAM_REINITIALIZE_CRED/</tag>
-	Reinitialize the user credentials, and
-<tag><tt/PAM_REFRESH_CRED/</tag>
-	Extend the lifetime of the user credentials.
-</descrip>
-
-<p>
-A successful return is signalled with <tt/PAM_SUCCESS/. Errors that
-are especially relevant to this function are the following:
-
-<p><descrip>
-<tag><tt/PAM_CRED_UNAVAIL/</tag>
-	A module cannot retrieve the user's credentials.
-<tag><tt/PAM_CRED_EXPIRED/</tag>
-	The user's credentials have expired.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to an authentication module.
-<tag><tt/PAM_CRED_ERR/</tag>
-	A module was unable to set the credentials of the user.
-</descrip>
-
-<sect2>Account management
-
-<p>
-<tscreen>
-<verb>
-extern int pam_acct_mgmt(pam_handle_t *pamh, int flags);
-</verb>
-</tscreen>
-
-<p>
-This function is typically called after the user has been
-authenticated.  It establishes whether the user's account is healthy.
-That is to say, whether the user's account is still active and whether
-the user is permitted to gain access to the system at this time.
-Valid flags, any one of which, may be logically OR'd with
-<tt/PAM_SILENT/, and are the same as those applicable to the
-<tt/flags/ argument of <tt/pam_authenticate/.
-
-<p>
-This function simply calls the corresponding functions of each of the
-loaded modules, as instructed by the configuration file,
-<tt>/etc/pam.conf</tt>.
-
-<p>
-The normal response from this function is <tt/PAM_SUCCESS/, however,
-specific failures are indicated by the following error returns:
-
-<descrip>
-<tag><tt/PAM_AUTHTOKEN_REQD/</tag>
-The user <bf/is/ valid but their authentication token has
-<em/expired/.  The correct response to this return-value is to require
-that the user satisfies the <tt/pam_chauthtok()/ function before
-obtaining service.  It may not be possible for some applications to do
-this.  In such cases, the user should be denied access until such time
-as they can update their password.
-
-<tag><tt/PAM_ACCT_EXPIRED/</tag>
-	The user is no longer permitted to access the system.
-<tag><tt/PAM_AUTH_ERR/</tag>
-	There was an authentication error.
-
-<tag><tt/PAM_PERM_DENIED/</tag>
-	The user is not permitted to gain access at this time.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to a module's account management
-component.
-
-</descrip>
-
-<sect2>Updating authentication tokens
-<label id="pam-chauthtok-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_chauthtok(pam_handle_t *pamh, const int flags);
-</verb>
-</tscreen>
-
-<p>
-This function is used to change the authentication token for a given
-user (as indicated by the state associated with the handle,
-<tt/pamh/). The following is a valid but optional flag which may be
-logically OR'd with <tt/PAM_SILENT/,
-
-<descrip>
-<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag>
-	This argument indicates to the modules that the users
-authentication token (password) should only be changed if it has
-expired.
-</descrip>
-
-<p>
-Note, if this argument is not passed, the application requires that
-<em/all/ authentication tokens are to be changed.
-
-<p>
-<tt/PAM_SUCCESS/ is the only successful return value, valid
-error-returns are:
-
-<descrip>
-<tag><tt/PAM_AUTHTOK_ERR/</tag>
-	A module was unable to obtain the new authentication token.
-	
-<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag>
-	A module was unable to obtain the old authentication token.
-
-<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag>
-	One or more of the modules was unable to change the
-authentication token since it is currently locked.
-	
-<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag>
-	Authentication token aging has been disabled for at least one
-of the modules.
-
-<tag><tt/PAM_PERM_DENIED/</tag>
-	Permission denied.
-
-<tag><tt/PAM_TRY_AGAIN/</tag>
-	Not all of the modules were in a position to update the
-authentication token(s). In such a case none of the user's
-authentication tokens are updated.
-
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to the authentication token changing
-service.
-
-</descrip>
-
-<sect2>Session initialization
-<label id="pam-open-session-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_open_session(pam_handle_t *pamh, int flags);
-</verb>
-</tscreen>
-
-<p>
-This function is used to indicate that an authenticated session has
-begun.  It is used to inform the modules that the user is currently in
-a session.  It should be possible for the <bf>Linux-PAM</bf> library
-to open a session and close the same session (see section <ref
-id="pam-close-session-section" name="below">) from different
-applications.
-
-<p>
-Currently, this function simply calls each of the corresponding
-functions of the loaded modules. The only valid flag is
-<tt/PAM_SILENT/ and this is, of course, <em/optional/.
-
-<p>
-If any of the <em/required/ loaded modules are unable to open a
-session for the user, this function will return <tt/PAM_SESSION_ERR/.
-
-<sect2>Terminating sessions
-<label id="pam-close-session-section">
-
-<p>
-<tscreen>
-<verb>
-extern int pam_close_session(pam_handle_t *pamh, int flags);
-</verb>
-</tscreen>
-
-<p>
-This function is used to indicate that an authenticated session has
-ended. It is used to inform the modules that the user is exiting a
-session. It should be possible for the <bf>Linux-PAM</bf> library to
-open a session and close the same session from different applications.
-
-<p>
-This function simply calls each of the corresponding functions of the
-loaded modules in the same order that they were invoked with
-<tt/pam_open_session()/.  The only valid flag is <tt/PAM_SILENT/ and
-this is, of course, <em/optional/.
-
-<p>
-If any of the <em/required/ loaded modules are unable to close a
-session for the user, this function will return <tt/PAM_SESSION_ERR/.
-
-<sect2>Setting PAM environment variables
-<label id="pam-putenv-section">
-
-<p>
-The <tt/libpam/ library associates with each PAM-handle (<tt/pamh/), a
-set of <it/PAM environment variables/. These variables are intended to
-hold the session environment variables that the user will inherit when
-the session is granted and the authenticated user obtains access to
-the requested service. For example, when <tt/login/ has finally given
-the user a shell, the environment (as viewed with the command
-<tt/env/) will be what <tt/libpam/ was maintaining as the PAM
-environment for that service application. Note, these variables are not
-the environment variables of the <tt/login/ application. This is
-principally for two reasons: <tt/login/ may want to have an
-environment that cannot be seen or manipulated by a user; and
-<tt/login/ (or whatever the serving application is) may be maintaining
-a number of parallel sessions, via different <tt/pamh/ values, at the
-same time and a single environment may not be appropriately shared
-between each of these. The PAM environment may contain variables
-seeded by the applicant user's client program, for example, and as
-such it is not appropriate for one applicant to interfere with the
-environment of another applicant.
-
-<p>
-<tscreen>
-<verb>
-extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
-</verb>
-</tscreen>
-
-<p>
-This function attempts to (re)set a <bf/Linux-PAM/ environment
-variable. The <tt/name_value/ argument is a single <tt/NUL/ terminated
-string of one of the following forms:
-<descrip>
-<tag>``<tt/NAME=value of variable/''</tag>
-
-In this case the environment variable of the given <tt/NAME/ is set to
-the indicated value: ``<tt/value of variable/''.  If this variable is
-already known, it is overwritten. Otherwise it is added to the
-<bf/Linux-PAM/ environment.
-
-<tag>``<tt/NAME=/''</tag>
-
-This function sets the variable to an empty value. It is listed
-separately to indicate that this is the correct way to achieve such a
-setting.
-
-<tag>``<tt/NAME/''</tag>
-
-Without an `<tt/=/' the <tt/pam_putenv()/ function will delete the
-corresponding variable from the <bf/Linux-PAM/ environment.
-
-</descrip>
-
-<p>
-Success is indicated with a return value of <tt/PAM_SUCCESS/. Failure
-is indicated by one of the following returns:
-
-<descrip>
-<tag><tt/PAM_PERM_DENIED/</tag>
-	name given is a <tt/NULL/ pointer
-
-<tag><tt/PAM_BAD_ITEM/</tag>
-	variable requested (for deletion) is not currently set
-
-<tag><tt/PAM_ABORT/</tag>
-	the <bf/Linux-PAM/ handle, <tt/pamh/, is corrupt
-
-<tag><tt/PAM_BUF_ERR/</tag>
-	failed to allocate memory when attempting update
-
-</descrip>
-
-<sect2>Getting a PAM environment variable
-<label id="pam-getenv-section">
-
-<p>
-<tscreen>
-<verb>
-extern const char *pam_getenv(pam_handle_t *pamh, const char *name);
-</verb>
-</tscreen>
-
-<p>
-Obtain the value of the indicated <bf/Linux-PAM/ environment
-variable. On error, internal failure or the unavailability of the
-given variable (unspecified), this function simply returns <tt/NULL/.
-
-<sect2>Getting the PAM environment
-<label id="pam-getenvlist-section">
-
-<p>
-<tscreen>
-<verb>
-extern const char * const *pam_getenvlist(pam_handle_t *pamh);
-</verb>
-</tscreen>
-
-<p>
-The PAM environment variables (see section <ref
-id="pam-putenv-section" name="above">) are a complete set of enviroment
-variables that are associated with a PAM-handle (<tt/pamh/). They
-represent the contents of the <it/regular/ environment variables of
-the authenticated user when service is granted.
-
-<p>
-Th function, <tt>pam_getenvlist()</tt> returns a pointer to a complete,
-<tt/malloc()/'d, copy of the PAM environment.  It is a pointer to a
-duplicated list of environment variables.  It should be noted that
-this memory will never be <tt/free()'d/ by <tt/libpam/.  Once obtained
-by a call to <tt/pam_getenvlist()/, <bf>it is the responsibility of
-the calling application</bf> to <tt/free()/ this memory.
-
-<p>
-The format of the memory is a <tt/malloc()/'d array of <tt/char */
-pointers, the last element of which is set to <tt/NULL/. Each of the
-non-<tt/NULL/ entries in this array point to a <tt/NUL/ terminated and
-<tt/malloc()/'d <tt/char/ string of the form:
-<tt/"/<it/name/<tt/=/<it/value/<tt/"/.
-
-<p>
-It is by design, and not a coincidence, that the format and contents
-of the returned array matches that required for the third argument of
-the <tt/execle(3)/ function call.
-
-<sect1>What is expected of an application
-
-<sect2>The conversation function
-<label id="the-conversation-function">
-
-<p>
-An application must provide a ``conversation function''. It is used
-for direct communication between a loaded module and the application
-and will typically provide a means for the module to prompt the user
-for a password etc. . The structure, <tt/pam_conv/, is defined by
-including <tt>&lt;security/pam_appl.h&gt</tt>; to be,
-
-<p>
-<tscreen>
-<verb>
-struct pam_conv {
-    int (*conv)(int num_msg,
-        const struct pam_message **msg,
-        struct pam_response **resp,
-        void *appdata_ptr);
-    void *appdata_ptr;
-};
-</verb>
-</tscreen>
-
-<p>
-It is initialized by the application before it is passed to the
-library.  The <em/contents/ of this structure are attached to the
-<tt/*pamh/ handle.  The point of this argument is to provide a
-mechanism for any loaded module to interact directly with the
-application program. This is why it is called a <em/conversation/
-structure.
-
-<p>
-When a module calls the referenced <tt/conv()/ function, the argument
-<tt/*appdata_ptr/ is set to the second element of this structure.
-
-<p>
-The other arguments of a call to <tt/conv()/ concern the information
-exchanged by module and application. That is to say, <tt/num_msg/
-holds the length of the array of pointers, <tt/msg/. After a
-successful return, the pointer <tt/*resp/ points to an array of
-<tt/pam_response/ structures, holding the application supplied text.
-Note, <tt/*resp/ is an <tt/struct pam_response/ array and <em/not/ an
-array of pointers.
-
-<p>
-The message (from the module to the application) passing structure is
-defined by <tt>&lt;security/pam_appl.h&gt;</tt> as:
-
-<p>
-<tscreen>
-<verb>
-struct pam_message {
-    int msg_style;
-    const char *msg;
-};
-</verb>
-</tscreen>
-
-<p>
-Valid choices for <tt/msg_style/ are:
-
-<p><descrip>
-<tag><tt/PAM_PROMPT_ECHO_OFF/</tag>
-	Obtain a string without echoing any text
-<tag><tt/PAM_PROMPT_ECHO_ON/</tag>
-	Obtain a string whilst echoing text
-<tag><tt/PAM_ERROR_MSG/</tag>
-	Display an error
-<tag><tt/PAM_TEXT_INFO/</tag>
-	Display some text.
-</descrip>
-
-<p>
-The point of having an array of messages is that it becomes possible
-to pass a number of things to the application in a single call from
-the module. It can also be convenient for the application that related
-things come at once: a windows based application can then present a
-single form with many messages/prompts on at once.
-
-<p>
-In passing, it is worth noting that there is a descrepency between the
-way Linux-PAM handles the <tt/const struct pam_message **msg/
-conversation function argument from the way that Solaris' PAM (and
-derivitives, known to include HP/UX, <em/are there others?/)
-does. Linux-PAM interprets the <tt/msg/ argument as entirely
-equivalent to the following prototype <tt/const struct pam_message
-*msg[]/ (which, in spirit, is consistent with the commonly used
-prototypes for <tt/argv/ argument to the familiar <tt/main()/
-function: <tt/char **argv/; and <tt/char *argv[]/). Said another way
-Linux-PAM interprets the <tt/msg/ argument as a pointer to an array of
-<tt/num_meg/ read only 'struct pam_message' <em/pointers/.  Solaris'
-PAM implementation interprets this argument as a pointer to a pointer
-to an array of <tt/num_meg/ <tt/pam_message/ structures.  Fortunately,
-perhaps, for most module/application developers when <tt/num_msg/ has
-a value of one these two definitions are entirely
-equivalent. Unfortunately, casually raising this number to two has led
-to unanticipated compatibility problems.
-
-<p>
-For what its worth the two known module writer work-arounds for trying
-to maintain source level compatibility with both PAM implementations
-are:
-<itemize>
-<item> never call the conversation function with <tt/num_msg/ greater
-than one.
-<item> set up <tt/msg/ as doubly referenced so both types of
-conversation function can find the messages. That is, make
-<p><tscreen>
-<verb>
-msg[n] = & (( *msg )[n])
-</verb>
-</tscreen>
-</itemize>
-<p>
-The response (from the application to the module) passing structure is
-defined by including <tt>&lt;security/pam_appl.h&gt;</tt> as:
-
-<p><tscreen><verb>
-struct pam_response {
-    char *resp;
-    int resp_retcode;
-};
-</verb></tscreen>
-
-<p>
-Currently, there are no definitions for <tt/resp_retcode/ values; the
-normal value is <tt/0/.
-
-<p>
-Prior to the 0.59 release of Linux-PAM, the length of the returned
-<tt/pam_response/ array was equal to the number of <em/prompts/ (types
-<tt/PAM_PROMPT_ECHO_OFF/ and <tt/PAM_PROMPT_ECHO_ON/) in the
-<tt/pam_message/ array with which the conversation function was
-called.  This meant that it was not always necessary for the module to
-<tt/free(3)/ the responses if the conversation function was only used
-to display some text.
-
-<p>
-Post Linux-PAM-0.59.  The number of responses is always equal to the
-<tt/num_msg/ conversation function argument.  This is slightly easier
-to program but does require that the response array is <tt/free(3)/'d
-after every call to the conversation function.  The index of the
-responses corresponds directly to the prompt index in the
-<tt/pam_message/ array.
-
-<p>
-The maximum length of the <tt/pam_msg.msg/ and <tt/pam_response.resp/
-character strings is <tt/PAM_MAX_MSG_SIZE/.  (This is not enforced by
-Linux-PAM.)
-
-<p>
-<tt/PAM_SUCCESS/ is the expected return value of this
-function.  However, should an error occur the application should not
-set <tt/*resp/ but simply return <tt/PAM_CONV_ERR/.
-
-<p>
-Note, if an application wishes to use two conversation functions, it
-should activate the second with a call to <tt/pam_set_item()/.
-
-<p>
-<bf>Notes:</bf> New item types are being added to the conversation
-protocol.  Currently Linux-PAM supports: <tt>PAM_BINARY_PROMPT</tt>
-and <tt>PAM_BINARY_MSG</tt>.  These two are intended for server-client
-hidden information exchange and may be used as an interface for
-maching-machine authentication.
-
-<sect1>Programming notes
-
-<p>
-Note, all of the authentication service function calls accept the
-token <tt/PAM_SILENT/, which instructs the modules to not send
-messages to the application. This token can be logically OR'd with any
-one of the permitted tokens specific to the individual function calls.
-<tt/PAM_SILENT/ does not override the prompting of the user for
-passwords etc., it only stops informative messages from being
-generated.
-
-<sect>Security issues of <bf>Linux-PAM</bf>
-
-<p>
-PAM, from the perspective of an application, is a convenient API for
-authenticating users. PAM modules generally have no increased
-privilege over that possessed by the application that is making use of
-it. For this reason, the application must take ultimate responsibility
-for protecting the environment in which PAM operates.
-
-<p>
-A poorly (or maliciously) written application can defeat any
-<bf/Linux-PAM/ module's authentication mechanisms by simply ignoring
-it's return values.  It is the applications task and responsibility to
-grant privileges and access to services.  The <bf/Linux-PAM/ library
-simply assumes the responsibility of <em/authenticating/ the user;
-ascertaining that the user <em/is/ who they say they are.  Care should
-be taken to anticipate all of the documented behavior of the
-<bf/Linux-PAM/ library functions.  A failure to do this will most
-certainly lead to a future security breach.
-
-<sect1>Care about standard library calls
-
-<p>
-In general, writers of authorization-granting applications should
-assume that each module is likely to call any or <em/all/ `libc'
-functions.  For `libc' functions that return pointers to
-static/dynamically allocated structures (ie. the library allocates the
-memory and the user is not expected to `<tt/free()/' it) any module
-call to this function is likely to corrupt a pointer previously
-obtained by the application.  The application programmer should either
-re-call such a `libc' function after a call to the <bf/Linux-PAM/
-library, or copy the structure contents to some safe area of memory
-before passing control to the <bf/Linux-PAM/ library.
-
-<p>
-Two important function classes that fall into this category are
-<tt>getpwnam(3)</tt> and <tt>syslog(3)</tt>.
-
-<sect1>Choice of a service name
-
-<p>
-When picking the <em/service-name/ that corresponds to the first entry
-in the <bf/Linux-PAM/ configuration file, the application programmer
-should <bf/avoid/ the temptation of choosing something related to
-<tt/argv[0]/.  It is a trivial matter for any user to invoke any
-application on a system under a different name and this should not be
-permitted to cause a security breach.
-
-<p>
-In general, this is always the right advice if the program is setuid,
-or otherwise more privileged than the user that invokes it. In some
-cases, avoiding this advice is convenient, but as an author of such an
-application, you should consider well the ways in which your program
-will be installed and used. (Its often the case that programs are not
-intended to be setuid, but end up being installed that way for
-convenience. If your program falls into this category, don't fall into
-the trap of making this mistake.)
-
-<p>
-To invoke some <tt/target/ application by another name, the user may
-symbolically link the target application with the desired name.  To be
-precise all the user need do is,
-<tscreen>
-<verb>
-ln -s /target/application ./preferred_name
-</verb>
-</tscreen>
-and then <em/run/ <tt>./preferred_name</tt>
-
-<p>
-By studying the <bf/Linux-PAM/ configuration file(s), an attacker can
-choose the <tt/preferred_name/ to be that of a service enjoying
-minimal protection; for example a game which uses <bf/Linux-PAM/ to
-restrict access to certain hours of the day.  If the service-name were
-to be linked to the filename under which the service was invoked, it
-is clear that the user is effectively in the position of dictating
-which authentication scheme the service uses.  Needless to say, this
-is not a secure situation.
-
-<p>
-The conclusion is that the application developer should carefully
-define the service-name of an application. The safest thing is to make
-it a single hard-wired name.
-
-<sect1>The conversation function
-
-<p>
-Care should be taken to ensure that the <tt/conv()/ function is
-robust. Such a function is provided in the library <tt/libpam_misc/
-(see <ref id="libpam-misc-section" name="below">).
-
-<sect1>The identity of the user
-
-<p>
-The <bf/Linux-PAM/ modules will need to determine the identity of the
-user who requests a service, and the identity of the user who grants
-the service.  These two users will seldom be the same.  Indeed there
-is generally a third user identity to be considered, the new (assumed)
-identity of the user once the service is granted.
-
-<p>
-The need for keeping tabs on these identities is clearly an issue of
-security.  One convention that is actively used by some modules is
-that the identity of the user requesting a service should be the
-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)/. 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
-their own security model (independent of the OS kernel) the above
-scheme is insufficient to identify the requesting user.
-
-<p>
-A more portable solution to storing the identity of the requesting
-user is to use the <tt/PAM_RUSER/ <tt/pam_get_item(3)/. The
-application should supply this value before attempting to authenticate
-the user with <tt/pam_authenticate()/. How well this name can be
-trusted will ultimately be at the discretion of the local
-administrator (who configures PAM for your application) and a selected
-module may attempt to override the value where it can obtain more
-reliable data. If an application is unable to determine the identity
-of the requesting entity/user, it should not call <tt/pam_set_item(3)/
-to set <tt/PAM_RUSER/.
-
-<p>
-In addition to the <tt/PAM_RUSER/ item, the application should supply
-the <tt/PAM_RHOST/ (<em/requesting host/) item. As a general rule, the
-following convention for its value can be assumed: <tt/&lt;unset&gt;/
-= unknown; <tt/localhost/ = invoked directly from the local system;
-<em/other.place.xyz/ = some component of the user's connection
-originates from this remote/requesting host. At present, PAM has no
-established convention for indicating whether the application supports
-a trusted path to communication from this host.
-
-<sect1>Sufficient resources
-
-<p>
-Care should be taken to ensure that the proper execution of an
-application is not compromised by a lack of system resources.  If an
-application is unable to open sufficient files to perform its service,
-it should fail gracefully, or request additional resources.
-Specifically, the quantities manipulated by the <tt/setrlimit(2)/
-family of commands should be taken into consideration.
-
-<p>
-This is also true of conversation prompts. The application should not
-accept prompts of arbitrary length with out checking for resource
-allocation failure and dealing with such extreme conditions gracefully
-and in a mannor that preserves the PAM API. Such tolerance may be
-especially important when attempting to track a malicious adversary.
-
-<sect>A library of miscellaneous helper functions
-<label id="libpam-misc-section">
-
-<p>
-To aid the work of the application developer a library of
-miscellaneous functions is provided.  It is called <tt/libpam_misc/,
-and contains functions for allocating memory (securely), a text based
-conversation function, and routines for enhancing the standard
-PAM-environment variable support.
-
-<sect1>Requirements
-
-<p>
-The functions, structures and macros, made available by this library
-can be defined by including <tt>&lt;security/pam_misc.h&gt;</tt>.  It
-should be noted that this library is specific to <bf/Linux-PAM/ and is
-not referred to in the defining DCE-RFC (see <ref id="bibliography"
-name="the bibliography">) below.
-
-<sect1>Macros supplied
-
-<sect2>Safe duplication of strings
-
-<p>
-<tscreen>
-<verb>
-x_strdup(const char *s)
-</verb>
-</tscreen>
-
-<p>
-This macro is a replacement for the <tt/xstrdup()/ function that was
-present in earlier versions of the library and which clashed horribly
-with a number of applications. It returns a duplicate copy of the
-<tt/NUL/ terminated string, <tt/s/. <tt/NULL/ is returned if there is
-insufficient memory available for the duplicate or if <tt/s/ is
-<tt/NULL/ to begin with.
-
-<sect1>Functions supplied
-
-<sect2>A text based conversation function
-
-<p>
-<tscreen>
-<verb>
-extern int misc_conv(int num_msg, const struct pam_message **msgm,
-		     struct pam_response **response, void *appdata_ptr);
-</verb>
-</tscreen>
-
-<p>
-This is a function that will prompt the user with the appropriate
-comments and obtain the appropriate inputs as directed by
-authentication modules.
-
-<p>
-In addition to simply slotting into the appropriate <tt/struct
-pam_conv/, this function provides some time-out facilities.  The
-function exports five variables that can be used by an application
-programmer to limit the amount of time this conversation function will
-spend waiting for the user to type something.
-
-<p>
-The five variables are as follows:
-<descrip>
-<tag><tt>extern time_t pam_misc_conv_warn_time;</tt></tag>
-
-This variable contains the <em/time/ (as returned by <tt/time()/) that
-the user should be first warned that the clock is ticking. By default
-it has the value <tt/0/, which indicates that no such warning will be
-given. The application may set its value to sometime in the future,
-but this should be done prior to passing control to the <bf/Linux-PAM/
-library.
-
-<tag><tt>extern const char *pam_misc_conv_warn_line;</tt></tag>
-
-Used in conjuction with <tt/pam_misc_conv_warn_time/, this variable is
-a pointer to the string that will be displayed when it becomes time to
-warn the user that the timeout is approaching. Its default value is
-``..&bsol;a.Time is running out...&bsol;n'', but this can be changed
-by the application prior to passing control to <bf/Linux-PAM/.
-
-<tag><tt>extern time_t pam_misc_conv_die_time;</tt></tag>
-
-This variable contains the <em/time/ (as returned by <tt/time()/) that
-the conversation will time out. By default it has the value <tt/0/,
-which indicates that the conversation function will not timeout. The
-application may set its value to sometime in the future, this should
-be done prior to passing control to the <bf/Linux-PAM/ library.
-
-<tag><tt>extern const char *pam_misc_conv_die_line;</tt></tag>
-
-Used in conjuction with <tt/pam_misc_conv_die_time/, this variable is
-a pointer to the string that will be displayed when the conversation
-times out. Its default value is ``..&bsol;a.Sorry, your time is
-up!&bsol;n'', but this can be changed by the application prior to
-passing control to <bf/Linux-PAM/.
-
-<tag><tt>extern int pam_misc_conv_died;</tt></tag>
-
-Following a return from the <bf/Linux-PAM/ libraray, the value of this
-variable indicates whether the conversation has timed out. A value of
-<tt/1/ indicates the time-out occurred.
-
-</descrip>
-
-<p>
-The following two function pointers are available for supporting binary
-prompts in the conversation function. They are optimized for the
-current incarnation of the <tt/libpamc/ library and are subject to
-change.
-<descrip>
-<tag><tt>extern int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t
-*prompt_p);</tt></tag>
-
-This function pointer is initialized to <tt/NULL/ but can be filled
-with a function that provides machine-machine (hidden) message
-exchange.  It is intended for use with hidden authentication protocols
-such as RSA or Diffie-Hellman key exchanges.  (This is still under
-development.)
-
-<tag><tt>extern int (*pam_binary_handler_free)(void *appdata,
-pamc_bp_t *delete_me);</tt></tag>
-
-This function pointer is initialized to <tt/PAM_BP_RENEW(delete_me, 0,
-0)/, but can be redefined as desired by the application.
-
-</descrip>
-
-<sect2>Transcribing an environment to that of Linux-PAM
-<p>
-<tscreen>
-<verb>
-extern int pam_misc_paste_env(pam_handle_t *pamh,
-			      const char * const * user_env);
-</verb>
-</tscreen>
-
-This function takes the supplied list of environment pointers and
-<em/uploads/ its contents to the <bf/Linux-PAM/ environment. Success
-is indicated by <tt/PAM_SUCCESS/.
-
-<sect2>Liberating a locally saved environment
-<p>
-<tscreen>
-<verb>
-extern char **pam_misc_drop_env(char **env);
-</verb>
-</tscreen>
-
-This function is defined to complement the <tt/pam_getenvlist()/
-function.  It liberates the memory associated with <tt/env/,
-<em/overwriting/ with <tt/0/ all memory before <tt/free()/ing it.
-
-<sect2>BSD like Linux-PAM environment variable setting
-<p>
-<tscreen>
-<verb>
-extern int pam_misc_setenv(pam_handle_t *pamh, const char *name,
-			   const char *value, int readonly);
-</verb>
-</tscreen>
-
-This function performs a task equivalent to <tt/pam_putenv()/, its
-syntax is, however, more like the BSD style function; <tt/setenv()/.
-The <tt/name/ and <tt/value/ are concatenated with an ``<tt/=/'' to
-form a <tt/name_value/ and passed to <tt/pam_putenv()/. If, however,
-the <bf/Linux-PAM/ variable is already set, the replacement will only
-be applied if the last argument, <tt/readonly/, is zero.
-
-<sect>Porting legacy applications
-
-<p>
-The following is extracted from an email.  I'll tidy it up later.
-
-<p>
-The point of PAM is that the application is not supposed to have any
-idea how the attached authentication modules will choose to
-authenticate the user.  So all they can do is provide a conversation
-function that will talk directly to the user(client) on the modules'
-behalf.
-
-<p>
-Consider the case that you plug a retinal scanner into the login
-program.  In this situation the user would be prompted: "please look
-into the scanner".  No username or password would be needed - all this
-information could be deduced from the scan and a database lookup.  The
-point is that the retinal scanner is an ideal task for a "module".
-
-<p>
-While it is true that a pop-daemon program is designed with the POP
-protocol in mind and no-one ever considered attaching a retinal
-scanner to it, it is also the case that the "clean" PAM'ification of
-such a daemon would allow for the possibility of a scanner module
-being be attached to it.  The point being that the "standard"
-pop-authentication protocol(s) [which will be needed to satisfy
-inflexible/legacy clients] would be supported by inserting an
-appropriate pam_qpopper module(s).  However, having rewritten popd
-once in this way any new protocols can be implemented in-situ.
-
-<p>
-One simple test of a ported application would be to insert the
-<tt/pam_permit/ module and see if the application demands you type a
-password...  In such a case, <tt/xlock/ would fail to lock the
-terminal - or would at best be a screen-saver, ftp would give password
-free access to all etc..  Neither of these is a very secure thing to
-do, but they do illustrate how much flexibility PAM puts in the hands
-of the local admin.
-
-<p>
-The key issue, in doing things correctly, is identifying what is part
-of the authentication procedure (how many passwords etc..) the
-exchange protocol (prefixes to prompts etc., numbers like 331 in the
-case of ftpd) and what is part of the service that the application
-delivers.  PAM really needs to have total control in the
-authentication "procedure", the conversation function should only
-deal with reformatting user prompts and extracting responses from raw
-input.
-
-<sect>Glossary of PAM related terms
-
-<p>
-The following are a list of terms used within this document.
-
-<p>
-<descrip>
-
-<tag>Authentication token</tag>
-Generally, this is a password.  However, a user can authenticate
-him/herself in a variety of ways.  Updating the user's authentication
-token thus corresponds to <em>refreshing</em> the object they use to
-authenticate themself with the system.  The word password is avoided
-to keep open the possibility that the authentication involves a
-retinal scan or other non-textual mode of challenge/response.
-
-<tag>Credentials</tag>
-Having successfully authenticated the user, PAM is able to establish
-certain characteristics/attributes of the user.  These are termed
-<em>credentials</em>.  Examples of which are group memberships to
-perform privileged tasks with, and <em>tickets</em> in the form of
-environment variables etc. .  Some user-credentials, such as the
-user's UID and GID (plus default group memberships) are not deemed to
-be PAM-credentials.  It is the responsibility of the application to
-grant these directly.
-
-</descrip>
-
-<sect>An example application
-
-<p>
-To get a flavor of the way a <tt/Linux-PAM/ application is written we
-include the following example. It prompts the user for their password
-and indicates whether their account is valid on the standard output,
-its return code also indicates the success (<tt/0/ for success; <tt/1/
-for failure).
-
-<p>
-<tscreen>
-<verb>
-/*
-  This program was contributed by Shane Watts
-  [modifications by AGM]
-
-  You need to add the following (or equivalent) to the /etc/pam.conf file.
-  # check authorization
-  check_user   auth       required     /usr/lib/security/pam_unix_auth.so
-  check_user   account    required     /usr/lib/security/pam_unix_acct.so
- */
-
-#include <security/pam_appl.h>
-#include <security/pam_misc.h>
-#include <stdio.h>
-
-static struct pam_conv conv = {
-    misc_conv,
-    NULL
-};
-
-int main(int argc, char *argv[])
-{
-    pam_handle_t *pamh=NULL;
-    int retval;
-    const char *user="nobody";
-
-    if(argc == 2) {
-	user = argv[1];
-    }
-
-    if(argc > 2) {
-	fprintf(stderr, "Usage: check_user [username]\n");
-	exit(1);
-    }
-
-    retval = pam_start("check_user", user, &ero;conv, &ero;pamh);
-	
-    if (retval == PAM_SUCCESS)
-        retval = pam_authenticate(pamh, 0);    /* is user really user? */
-
-    if (retval == PAM_SUCCESS)
-        retval = pam_acct_mgmt(pamh, 0);       /* permitted access? */
-
-    /* This is where we have been authorized or not. */
-
-    if (retval == PAM_SUCCESS) {
-	fprintf(stdout, "Authenticated\n");
-    } else {
-	fprintf(stdout, "Not Authenticated\n");
-    }
-
-    if (pam_end(pamh,retval) != PAM_SUCCESS) {     /* close Linux-PAM */
-	pamh = NULL;
-	fprintf(stderr, "check_user: failed to release authenticator\n");
-	exit(1);
-    }
-
-    return ( retval == PAM_SUCCESS ? 0:1 );       /* indicate success */
-}
-</verb>
-</tscreen>
-
-<sect>Files
-
-<p><descrip>
-
-<tag><tt>/usr/include/security/pam_appl.h</tt></tag>
-
-header file for <bf/Linux-PAM/ applications interface
-
-<tag><tt>/usr/include/security/pam_misc.h</tt></tag>
-
-header file for useful library functions for making applications
-easier to write
-
-<tag><tt>/usr/lib/libpam.so.*</tt></tag>
-
-the shared library providing applications with access to
-<bf/Linux-PAM/.
-
-<tag><tt>/etc/pam.conf</tt></tag>
-
-the <bf/Linux-PAM/ configuration file.
-
-<tag><tt>/usr/lib/security/pam_*.so</tt></tag>
-
-the primary location for <bf/Linux-PAM/ dynamically loadable object
-files; the modules.
-
-</descrip>
-
-<sect>See also
-<label id="bibliography">
-
-<p><itemize>
-
-<item>The <bf/Linux-PAM/
-<htmlurl url="pam.html" name="System Administrators' Guide">.
-
-<item>The <bf/Linux-PAM/
-<htmlurl url="pam_modules.html" name="Module Writers' Guide">.
-
-<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
-PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request
-For Comments 86.0, October 1995.
-
-</itemize>
-
-<sect>Notes
-
-<p>
-I intend to put development comments here... like ``at the moment
-this isn't actually supported''. At release time what ever is in
-this section will be placed in the Bugs section below! :)
-
-<p>
-<itemize>
-
-<item> <tt/pam_strerror()/ should be internationalized....
-
-<item>
-Note, the <tt/resp_retcode/ of struct <tt/pam_message/, has no
-purpose at the moment. Ideas/suggestions welcome!
-
-<item> more security issues are required....
-
-</itemize>
-
-<sect>Author/acknowledgments
-
-<p>
-This document was written by Andrew G. Morgan
-(morgan@kernel.org) with many contributions from
-<!-- insert credits here -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id$
-  -->
-Chris Adams,
-Peter Allgeyer,
-Tim Baverstock,
-Tim Berger,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Seth Chaiklin,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Emmanuel Galanos,
-Brad M. Garcia,
-Eric Hester,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Olaf Kirch,
-Marcin Korzonek,
-Stephen Langasek,
-Nicolai Langfeldt,
-Elliot Lee,
-Luke Kenneth Casson Leighton,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Robert Milkowski,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-Jan Rekorajski,
-Erik Troan,
-Theodore Ts'o,
-Jeff Uphoff,
-Myles Uyema,
-Savochkin Andrey Vladimirovich,
-Ronald Wahl,
-David Wood,
-John Wilmes,
-Joseph S. D. Yao
-and
-Alex O.  Yuriev.
-
-<p>
-Thanks are also due to Sun Microsystems, especially to Vipin Samar and
-Charlie Lai for their advice. At an early stage in the development of
-<bf/Linux-PAM/, Sun graciously made the documentation for their
-implementation of PAM available. This act greatly accelerated the
-development of <bf/Linux-PAM/.
-
-<sect>Bugs/omissions
-
-<p>
-This manual is hopelessly unfinished. Only a partial list of people is
-credited for all the good work they have done.
-
-<sect>Copyright information for this document
-
-<p>
-Copyright (c) Andrew G. Morgan 1996-9,2000-1.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@kernel.org&gt;</tt>
-
-<p>
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-<p>
-<itemize>
-
-<item>
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-<item>
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-<item>
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-</itemize>
-
-<p>
-<bf/Alternatively/, this product may be distributed under the terms of
-the GNU General Public License (GPL), in which case the provisions of
-the GNU GPL are required <bf/instead of/ the above restrictions.
-(This clause is necessary due to a potential bad interaction between
-the GNU GPL and the restrictions contained in a BSD-style copyright.)
-
-<p>
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
-<p>
-<tt>$Id$</tt>
-
-</article>
diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml
deleted file mode 100644
index c986e0a9..00000000
--- a/doc/pam_modules.sgml
+++ /dev/null
@@ -1,1505 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id$
-
-    Copyright (c) Andrew G. Morgan 1996-2001.  All rights reserved.
-
-	** some sections, in this document, were contributed by other
-	** authors. They carry individual copyrights.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-ALTERNATIVELY, this product may be distributed under the terms of the
-GNU General Public License, in which case the provisions of the GNU
-GPL are required INSTEAD OF the above restrictions.  (This clause is
-necessary due to a potential bad interaction between the GNU GPL and
-the restrictions contained in a BSD-style copyright.)
-
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
- -->
-
-<article>
-
-<title>The Linux-PAM Module Writers' Guide
-<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.76 2002/05/09
-<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
-discusses some security issues from the point of view of the module
-programmer.
-</abstract>
-
-<toc>
-
-<sect>Introduction
-
-<sect1> Synopsis
-<p>
-<tscreen>
-<verb>
-#include <security/pam_modules.h>
-
-gcc -fPIC -c pam_module-name.c
-ld -x --shared -o pam_module-name.so pam_module-name.o
-</verb>
-</tscreen>
-
-<sect1> Description
-
-<p>
-<bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a
-library that enables the local system administrator to choose how
-individual applications authenticate users.  For an overview of the
-<bf/Linux-PAM/ library see the <bf/Linux-PAM/ System Administrators'
-Guide.
-
-<p>
-A <bf/Linux-PAM/ module is a single executable binary file that can be
-loaded by the <bf/Linux-PAM/ interface library. This PAM library is
-configured locally with a system file, <tt>/etc/pam.conf</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 object files (see dlopen(3)). Alternatively, the modules can
-be statically linked into the <bf/Linux-PAM/ library; this is mostly to
-allow <bf/Linux-PAM/ to be used on platforms without dynamic linking
-available, but the two forms can be used together.  It is the
-<bf/Linux-PAM/ interface that is called by an application and it is
-the responsibility of the library to locate, load and call the
-appropriate functions in a <bf/Linux-PAM/-module.
-
-<p>
-Except for the immediate purpose of interacting with the user
-(entering a password etc..) the module should never call the
-application directly. This exception requires a "conversation
-mechanism" which is documented below.
-
-<sect>What can be expected by the module
-
-<p>
-Here we list the interface that the conventions that all
-<bf/Linux-PAM/ modules must adhere to.
-
-<sect1>Getting and setting <tt/PAM_ITEM/s and <em/data/
-
-<p>
-First, we cover what the module should expect from the <bf/Linux-PAM/
-library and a <bf/Linux-PAM/ <em/aware/ application. Essesntially this
-is the <tt/libpam.*/ library.
-
-<sect2>
-Setting data
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_set_data(pam_handle_t *pamh,
-                        const char *module_data_name,
-			void *data,
-			void (*cleanup)(pam_handle_t *pamh,
-			                void *data, int error_status) );
-</verb>
-</tscreen>
-
-<p>
-The modules may be dynamically loadable objects. In general such files
-should not contain <tt/static/ variables. This and the subsequent
-function provide a mechanism for a module to associate some data with
-the handle <tt/pamh/. Typically a module will call the
-<tt/pam_set_data()/ function to register some data under a (hopefully)
-unique <tt/module_data_name/. The data is available for use by other
-modules too but <em/not/ by an application.
-
-<p>
-The function <tt/cleanup()/ is associated with the <tt/data/ and, if
-non-<tt/NULL/, it is called when this data is over-written or
-following a call to <tt/pam_end()/ (see the Linux-PAM Application
-Developers' Guide).
-
-<p>
-The <tt/error_status/ argument is used to indicate to the module the
-sort of action it is to take in cleaning this data item. As an
-example, Kerberos creates a ticket file during the authentication
-phase, this file might be associated with a data item. When
-<tt/pam_end()/ is called by the module, the <tt/error_status/
-carries the return value of the <tt/pam_authenticate()/ or other
-<tt/libpam/ function as appropriate. Based on this value the Kerberos
-module may choose to delete the ticket file (<em/authentication
-failure/) or leave it in place.
-
-<p>
-The <tt/error_status/ may have been logically OR'd with either of the
-following two values:
-
-<p>
-<descrip>
-<tag><tt/PAM_DATA_REPLACE/</tag>
-	When a data item is being replaced (through a second call to
-<tt/pam_set_data()/) this mask is used. Otherwise, the call is assumed
-to be from <tt/pam_end()/.
-
-<tag><tt/PAM_DATA_SILENT/</tag>
-	Which indicates that the process would prefer to perform the
-<tt/cleanup()/ quietly. That is, discourages logging/messages to the
-user.
-
-</descrip>
-
-
-<sect2>
-Getting data
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_get_data(const pam_handle_t *pamh,
-			const char *module_data_name,
-			const void **data);
-</verb>
-</tscreen>
-
-<p>
-This function together with the previous one provides a method of
-associating module-specific data with the handle <tt/pamh/. A
-successful call to <tt/pam_get_data/ will result in <tt/*data/
-pointing to the data associated with the <tt/module_data_name/. Note,
-this data is <em/not/ a copy and should be treated as <em/constant/
-by the module.
-
-<p>
-Note, if there is an entry but it has the value <tt/NULL/, then this
-call returns <tt/PAM_NO_MODULE_DATA/.
-
-<sect2>
-Setting items
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_set_item(pam_handle_t *pamh,
-                        int item_type,
-			const void *item);
-</verb>
-</tscreen>
-
-<p>
-This function is used to (re)set the value of one of the
-<tt/item_type/s.  The reader is urged to read the entry for this
-function in the <bf/Linux-PAM/ application developers' manual.
-
-<p>
-In addition to the <tt/item/s listed there, the module can set the
-following two <tt/item_type/s:
-
-<p>
-<descrip>
-<tag><tt/PAM_AUTHTOK/</tag>
-
-The authentication token (often a password). This token should be
-ignored by all module functions besides <tt/pam_sm_authenticate()/ and
-<tt/pam_sm_chauthtok()/. In the former function it is used to pass the
-most recent authentication token from one stacked module to
-another. In the latter function the token is used for another
-purpose. It contains the currently active authentication token.
-
-<tag><tt/PAM_OLDAUTHTOK/</tag>
-
-The old authentication token. This token should be ignored by all
-module functions except <tt/pam_sm_chauthtok()/.
-
-</descrip>
-
-<p>
-Both of these items are reset before returning to the application.
-When resetting these items, the <bf/Linux-PAM/ library first writes
-<tt/0/'s to the current tokens and then <tt/free()/'s the associated
-memory.
-
-<p>
-The return values for this function are listed in the 
-<bf>Linux-PAM</bf> Application Developers' Guide.
-
-<sect2>
-Getting items
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_get_item(const pam_handle_t *pamh,
-			int item_type,
-			const void **item);
-</verb>
-</tscreen>
-
-<p>
-This function is used to obtain the value of the specified
-<tt/item_type/. It is better documented in the <bf/Linux-PAM/
-Application Developers' Guide. However, there are three things worth
-stressing here:
-<itemize>
-
-<item>
-Generally, if the module wishes to obtain the name of the user, it
-should not use this function, but instead perform a call to
-<tt/pam_get_user()/ (see section <ref id="pam-get-user"
-name="below">).
-
-<item>
-The module is additionally privileged to read the authentication
-tokens, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/ (see the section
-above on <tt/pam_set_data()/).
-
-<item>
-The module should <em/not/ <tt/free()/ or alter the data pointed to by
-<tt/*item/ after a successful return from <tt/pam_get_item()/. This
-pointer points directly at the data contained within the <tt/*pamh/
-structure.  Should a module require that a change is made to the this
-<tt/ITEM/ it should make the appropriate call to <tt/pam_set_item()/.
-</itemize>
-
-<sect2>The <em/conversation/ mechanism
-
-<p>
-Following the call <tt>pam_get_item(pamh,PAM_CONV,&amp;item)</tt>, the
-pointer <tt/item/ points to a structure containing an a pointer to a
-<em/conversation/-function that provides limited but direct access to
-the application.  The purpose of this function is to allow the module
-to prompt the user for their password and pass other information in a
-manner consistent with the application. For example, an X-windows
-based program might pop up a dialog box to report a login
-failure. Just as the application should not be concerned with the
-method of authentication, so the module should not dictate the manner
-in which input (output) is obtained from (presented to) to the user.
-
-<p>
-<bf>The reader is strongly urged to read the more complete description of
-the <tt/pam_conv/ structure, written from the perspective of the
-application developer, in the <bf/Linux-PAM/ Application Developers'
-Guide.</bf>
-
-<p>
-The return values for this function are listed in the 
-<bf>Linux-PAM</bf> Application Developers' Guide.
-
-<p>
-The <tt/pam_response/ structure returned after a call to the
-<tt/pam_conv/ function must be <tt/free()/'d by the module. Since the
-call to the conversation function originates from the module, it is
-clear that this <tt/pam_response/ structure could be either statically
-or dynamically (using <tt/malloc()/ etc.) allocated within the
-application. Repeated calls to the conversation function would likely
-overwrite static memory, so it is required that for a successful
-return from the conversation function the memory for the response
-structure is dynamically allocated by the application with one of the
-<tt/malloc()/ family of commands and <em/must/ be <tt/free()/'d by the
-module.
-
-<p>
-If the <tt/pam_conv/ mechanism is used to enter authentication tokens,
-the module should either pass the result to the <tt/pam_set_item()/
-library function, or copy it itself. In such a case, once the token
-has been stored (by one of these methods or another one), the memory
-returned by the application should be overwritten with <tt/0/'s, and
-then <tt/free()/'d.
-
-There is a handy macro <tt/_pam_drop_reply()/ to be found in
-<tt>&lt;security/_pam_macros.h&gt;</tt> that can be used to
-conveniently cleanup a <tt/pam_response/ structure. (Note, this
-include file is specific to the Linux-PAM sources, and whilst it will
-work with Sun derived PAM implementations, it is not generally
-distributed by Sun.)
-
-<sect2>Getting the name of a user<label id="pam-get-user">
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_get_user(pam_handle_t *pamh, 
-                        const char **user,
-			const char *prompt);
-</verb>
-</tscreen>
-
-<p>
-This is a <bf/Linux-PAM/ library function that returns the
-(prospective) name of the user. To determine the username it does the
-following things, in this order:
-<itemize>
-
-<item> checks what <tt/pam_get_item(pamh, PAM_USER, ... );/ would have
-returned. If this is not <tt/NULL/ this is what it returns. Otherwise,
-
-<item> obtains a username from the application via the <tt/pam_conv/
-mechanism, it prompts the user with the first non-<tt/NULL/ string in
-the following list:
-<itemize>
-
-<item> The <tt/prompt/ argument passed to the function
-<item> What is returned by <tt/pam_get_item(pamh,PAM_USER_PROMPT, ... );/
-<item> The default prompt: ``Please enter username: ''
-
-</itemize>
-</itemize>
-
-<p>
-By whatever means the username is obtained, a pointer to it is
-returned as the contents of <tt/*user/. Note, this memory should
-<em/not/ be <tt/free()/'d by the module. Instead, it will be liberated
-on the next call to <tt/pam_get_user()/, or by <tt/pam_end()/ when the
-application ends its interaction with <bf/Linux-PAM/.
-
-<p>
-Also, in addition, it should be noted that this function sets the
-<tt/PAM_USER/ item that is associated with the <tt/pam_[gs]et_item()/
-function.
-
-<p>
-The return value of this function is one of the following:
-<itemize>
-
-<item> <tt/PAM_SUCCESS/ - username obtained.
-
-<item> <tt/PAM_CONV_AGAIN/ - converstation did not complete and the
-caller is required to return control to the application, until such
-time as the application has completed the conversation process. A
-module calling <tt/pam_get_user()/ that obtains this return code,
-should return <tt/PAM_INCOMPLETE/ and be prepared (when invoked the
-next time) to recall <tt/pam_get_user()/ to fill in the user's name,
-and then pick up where it left off as if nothing had happened. This
-procedure is needed to support an event-driven application programming
-model.
-
-<item> <tt/PAM_CONV_ERR/ - the conversation method supplied by the
-application failed to obtain the username.
-
-</itemize>
-
-<sect2>Setting a Linux-PAM environment variable
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
-</verb>
-</tscreen>
-
-<p>
-<bf/Linux-PAM/ comes equipped with a series of functions for
-maintaining a set of <em/environment/ variables. The environment is
-initialized by the call to <tt/pam_start()/ and is <bf/erased/ with a
-call to <tt/pam_end()/.  This <em/environment/ is associated with the
-<tt/pam_handle_t/ pointer returned by the former call.
-
-<p>
-The default environment is all but empty. It contains a single
-<tt/NULL/ pointer, which is always required to terminate the
-variable-list.  The <tt/pam_putenv()/ function can be used to add a
-new environment variable, replace an existing one, or delete an old
-one.
-
-<p>
-<itemize>
-<item>Adding/replacing a variable<newline>
-
-To add or overwrite a <bf/Linux-PAM/ environment variable the value of
-the argument <tt/name_value/, should be of the following form:
-<tscreen>
-<verb>
-name_value="VARIABLE=VALUE OF VARIABLE"
-</verb>
-</tscreen>
-Here, <tt/VARIABLE/ is the environment variable's name and what
-follows the `<tt/=/' is its (new) value. (Note, that <tt/"VARIABLE="/
-is a valid value for <tt/name_value/, indicating that the variable is
-set to <tt/""/.)
-
-<item> Deleting a variable<newline>
-
-To delete a <bf/Linux-PAM/ environment variable the value of
-the argument <tt/name_value/, should be of the following form:
-<tscreen>
-<verb>
-name_value="VARIABLE"
-</verb>
-</tscreen>
-Here, <tt/VARIABLE/ is the environment variable's name and the absence
-of an `<tt/=/' indicates that the variable should be removed.
-
-</itemize>
-
-<p>
-In all cases <tt/PAM_SUCCESS/ indicates success.
-
-<sect2>Getting a Linux-PAM environment variable
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern const char *pam_getenv(pam_handle_t *pamh, const char *name);
-</verb>
-</tscreen>
-
-<p>
-This function can be used to return the value of the given
-variable. If the returned value is <tt/NULL/, the variable is not
-known.
-
-<sect2>Listing the Linux-PAM environment
-
-<p>
-Synopsis:
-<tscreen>
-<verb>
-extern char * const *pam_getenvlist(pam_handle_t *pamh);
-</verb>
-</tscreen>
-
-<p>
-This function returns a pointer to the entire <bf/Linux-PAM/
-environment array.  At first sight the <em/type/ of the returned data
-may appear a little confusing.  It is basically a <em/read-only/ array
-of character pointers, that lists the <tt/NULL/ terminated list of
-environment variables set so far.
-
-<p>
-Although, this is not a concern for the module programmer, we mention
-here that an application should be careful to copy this entire array
-before executing <tt/pam_end()/ otherwise all the variable information
-will be lost. (There are functions in <tt/libpam_misc/ for this
-purpose: <tt/pam_misc_copy_env()/ and <tt/pam_misc_drop_env()/.)
-
-<sect1>Other functions provided by <tt/libpam/
-
-<sect2>Understanding errors
-
-<p>
-<itemize>
-
-<item>
-<tt>extern const char *pam_strerror(pam_handle_t *pamh, int errnum);</tt>
-
-<p>
-This function returns some text describing the <bf/Linux-PAM/ error
-associated with the argument <tt/errnum/.  If the error is not
-recognized <tt/``Unknown Linux-PAM error''/ is returned.
-
-</itemize>
-
-<sect2>Planning for delays
-
-<p>
-<itemize>
-
-<item>
-<tt>extern int pam_fail_delay(pam_handle_t *pamh, unsigned int
-micro_sec)</tt>
-
-<p>
-This function is offered by <bf/Linux-PAM/ to facilitate time delays
-following a failed call to <tt/pam_authenticate()/ and before control
-is returned to the application. When using this function the module
-programmer should check if it is available with,
-<tscreen>
-<verb>
-#ifdef PAM_FAIL_DELAY
-    ....
-#endif /* PAM_FAIL_DELAY */
-</verb>
-</tscreen>
-
-<p>
-Generally, an application requests that a user is authenticated by
-<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or
-<tt/pam_chauthtok()/.  These functions call each of the <em/stacked/
-authentication modules listed in the <bf/Linux-PAM/ configuration
-file.  As directed by this file, one of more of the modules may fail
-causing the <tt/pam_...()/ call to return an error.  It is desirable
-for there to also be a pause before the application continues. The
-principal reason for such a delay is security: a delay acts to
-discourage <em/brute force/ dictionary attacks primarily, but also
-helps hinder <em/timed/ (cf. covert channel) attacks.
-
-<p>
-The <tt/pam_fail_delay()/ function provides the mechanism by which an
-application or module can suggest a minimum delay (of <tt/micro_sec/
-<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time
-requested with this function. Should <tt/pam_authenticate()/ fail,
-the failing return to the application is delayed by an amount of time
-randomly distributed (by up to 25%) about this longest value.
-
-<p>
-Independent of success, the delay time is reset to its zero default
-value when <bf/Linux-PAM/ returns control to the application.
-
-</itemize>
-
-<sect>What is expected of a module
-
-<p>
-The module must supply a sub-set of the six functions listed
-below. Together they define the function of a <bf/Linux-PAM
-module/. Module developers are strongly urged to read the comments on
-security that follow this list.
-
-<sect1> Overview
-
-<p>
-The six module functions are grouped into four independent management
-groups. These groups are as follows: <em/authentication/,
-<em/account/, <em/session/ and <em/password/. To be properly defined,
-a module must define all functions within at least one of these
-groups. A single module may contain the necessary functions for
-<em/all/ four groups.
-
-<sect2> Functional independence
-
-<p>
-The independence of the four groups of service a module can offer
-means that the module should allow for the possibility that any one of
-these four services may legitimately be called in any order. Thus, the
-module writer should consider the appropriateness of performing a
-service without the prior success of some other part of the module.
-
-<p>
-As an informative example, consider the possibility that an
-application applies to change a user's authentication token, without
-having first requested that <bf/Linux-PAM/ authenticate the user. In
-some cases this may be deemed appropriate: when <tt/root/ wants to
-change the authentication token of some lesser user. In other cases it
-may not be appropriate: when <tt/joe/ maliciously wants to reset
-<tt/alice/'s password; or when anyone other than the user themself
-wishes to reset their <em/KERBEROS/ authentication token. A policy for
-this action should be defined by any reasonable authentication scheme,
-the module writer should consider this when implementing a given
-module.
-
-<sect2> Minimizing administration problems
-
-<p>
-To avoid system administration problems and the poor construction of a
-<tt>/etc/pam.conf</tt> file, the module developer may define all
-six of the following functions. For those functions that would not be
-called, the module should return <tt/PAM_SERVICE_ERR/ and write an
-appropriate message to the system log. When this action is deemed
-inappropriate, the function would simply return <tt/PAM_IGNORE/.
-
-<sect2> Arguments supplied to the module
-
-<p>
-The <tt/flags/ argument of each of the following functions can be
-logically OR'd with <tt/PAM_SILENT/, which is used to inform the
-module to not pass any <em/text/ (errors or warnings) to the
-application.
-
-<p>
-The <tt/argc/ and <tt/argv/ arguments are taken from the line
-appropriate to this module---that is, with the <em/service_name/
-matching that of the application---in the configuration file (see the
-<bf/Linux-PAM/ System Administrators' Guide). Together these two
-parameters provide the number of arguments and an array of pointers to
-the individual argument tokens. This will be familiar to C programmers
-as the ubiquitous method of passing command arguments to the function
-<tt/main()/. Note, however, that the first argument (<tt/argv[0]/) is
-a true argument and <bf/not/ the name of the module.
-
-<sect1> Authentication management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_AUTH/ must be <tt/#define/'d
-prior to including <tt>&lt;security/pam_modules.h&gt;</tt>. This will
-ensure that the prototypes for static modules are properly declared.
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
-int argc, const char **argv);</tt>
-
-<p>
-This function performs the task of authenticating the user. 
-
-<p>
-The <tt/flags/ argument can be a logically OR'd with <tt/PAM_SILENT/
-and optionally take the following value:
-
-<p><descrip>
-<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag>
-	return <tt/PAM_AUTH_ERR/ if the database of authentication
-tokens for this authentication mechanism has a <tt/NULL/ entry for the
-user. Without this flag, such a <tt/NULL/ token will lead to a success
-without the user being prompted.
-</descrip>
-
-<p>
-Besides <tt/PAM_SUCCESS/ return values that can be sent by this
-function are one of the following:
-
-<descrip>
-
-<tag><tt/PAM_AUTH_ERR/</tag>
-	The user was not authenticated
-<tag><tt/PAM_CRED_INSUFFICIENT/</tag>
-	For some reason the application does not have sufficient
-credentials to authenticate the user.
-<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag>
-	The modules were not able to access the authentication
-information. This might be due to a network or hardware failure etc.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The supplied username is not known to the authentication
-service
-<tag><tt/PAM_MAXTRIES/</tag>
-	One or more of the authentication modules has reached its
-limit of tries authenticating the user. Do not try again.
-
-</descrip>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function performs the task of altering the credentials of the
-user with respect to the corresponding authorization
-scheme. Generally, an authentication module may have access to more
-information about a user than their authentication token. This
-function is used to make such information available to the
-application. It should only be called <em/after/ the user has been
-authenticated but before a session has been established.
-
-<p>
-Permitted flags, one of which, may be logically OR'd with
-<tt/PAM_SILENT/ are,
-
-<p><descrip>
-<tag><tt/PAM_ESTABLISH_CRED/</tag>
-	Set the credentials for the authentication service,
-<tag><tt/PAM_DELETE_CRED/</tag>
-	Delete the credentials associated with the authentication service,
-<tag><tt/PAM_REINITIALIZE_CRED/</tag>
-	Reinitialize the user credentials, and
-<tag><tt/PAM_REFRESH_CRED/</tag>
-	Extend the lifetime of the user credentials.
-</descrip>
-
-<p>
-Prior to <bf/Linux-PAM-0.75/, and due to a deficiency with the way the
-<tt/auth/ stack was handled in the case of the setcred stack being
-processed, the module was required to attempt to return the same error
-code as <tt/pam_sm_authenticate/ did.  This was necessary to preserve
-the logic followed by libpam as it executes the stack of
-<em/authentication/ modules, when the application called either
-<tt/pam_authenticate()/ or <tt/pam_setcred()/.  Failing to do this,
-led to confusion on the part of the System Administrator.
-
-<p>
-For <bf/Linux-PAM-0.75/ and later, libpam handles the credential stack
-much more sanely. The way the <tt/auth/ stack is navigated in order to
-evaluate the <tt/pam_setcred()/ function call, independent of the
-<tt/pam_sm_setcred()/ return codes, is exactly the same way that it
-was navigated when evaluating the <tt/pam_authenticate()/ library
-call. Typically, if a stack entry was ignored in evaluating
-<tt/pam_authenticate()/, it will be ignored when libpam evaluates the
-<tt/pam_setcred()/ function call. Otherwise, the return codes from
-each module specific <tt/pam_sm_setcred()/ call are treated as
-<tt/required/.
-
-<p>
-Besides <tt/PAM_SUCCESS/, the module may return one of the following
-errors:
-
-<p><descrip>
-<tag><tt/PAM_CRED_UNAVAIL/</tag>
-	This module cannot retrieve the user's credentials.
-<tag><tt/PAM_CRED_EXPIRED/</tag>
-	The user's credentials have expired.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to this authentication module.
-<tag><tt/PAM_CRED_ERR/</tag>
-	This module was unable to set the credentials of the user.
-</descrip>
-
-<p>
-these, non-<tt/PAM_SUCCESS/, return values will typically lead to the
-credential stack <em/failing/. The first such error will dominate in
-the return value of <tt/pam_setcred()/.
-
-</itemize>
-
-<sect1> Account management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_ACCOUNT/ must be
-<tt/#define/'d prior to including <tt>&lt;security/pam_modules.h&gt;</tt>.
-This will ensure that the prototype for a static module is properly
-declared.
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function performs the task of establishing whether the user is
-permitted to gain access at this time. It should be understood that
-the user has previously been validated by an authentication
-module. This function checks for other things. Such things might be:
-the time of day or the date, the terminal line, remote
-hostname, etc. .
-
-<p>
-This function may also determine things like the expiration on
-passwords, and respond that the user change it before continuing.
-
-<p>
-Valid flags, which may be logically OR'd with <tt/PAM_SILENT/, are the
-same as those applicable to the <tt/flags/ argument of
-<tt/pam_sm_authenticate/.
-
-<p>
-This function may return one of the following errors,
-
-<descrip>
-
-<tag><tt/PAM_ACCT_EXPIRED/</tag>
-	The user is no longer permitted access to the system.
-<tag><tt/PAM_AUTH_ERR/</tag>
-	There was an authentication error.
-<tag><tt/PAM_AUTHTOKEN_REQD/</tag>
-	The user's authentication token has expired. Before calling
-this function again the application will arrange for a new one to be
-given. This will likely result in a call to <tt/pam_sm_chauthtok()/.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to the module's account management
-component.
-	
-</descrip>
-
-</itemize>
-
-<sect1> Session management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_SESSION/ must be
-<tt/#define/'d prior to including
-<tt>&lt;security/pam_modules.h&gt;</tt>.  This will ensure that the
-prototypes for static modules are properly declared.
-
-<p>
-The following two functions are defined to handle the
-initialization/termination of a session. For example, at the beginning
-of a session the module may wish to log a message with the system
-regarding the user. Similarly, at the end of the session the module
-would inform the system that the user's session has ended.
-
-<p>
-It should be possible for sessions to be opened by one application and
-closed by another. This either requires that the module uses only
-information obtained from <tt/pam_get_item()/, or that information
-regarding the session is stored in some way by the operating system
-(in a file for example).
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is called to commence a session. The only valid, but
-optional, flag is <tt/PAM_SILENT/.
-
-<p>
-As a return value, <tt/PAM_SUCCESS/ signals success and
-<tt/PAM_SESSION_ERR/ failure.
-
-<item>
-<tt>PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is called to terminate a session. The only valid, but
-optional, flag is <tt/PAM_SILENT/.
-
-<p>
-As a return value, <tt/PAM_SUCCESS/ signals success and
-<tt/PAM_SESSION_ERR/ failure.
-
-</itemize>
-
-<sect1> Password management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_PASSWORD/ must be
-<tt/#define/'d prior to including <tt>&lt;security/pam_modules.h&gt;</tt>.
-This will ensure that the prototype for a static module is properly
-declared.
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is used to (re-)set the authentication token of the
-user. A valid flag, which may be logically OR'd with <tt/PAM_SILENT/,
-can be built from the following list,
-
-<descrip>
-<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag>
-	This argument indicates to the module that the users
-authentication token (password) should only be changed if it has
-expired. This flag is optional and <em/must/ be combined with one of
-the following two flags. Note, however, the following two options are
-<em/mutually exclusive/.
-
-<tag><tt/PAM_PRELIM_CHECK/</tag>
-	This indicates that the modules are being probed as to their
-ready status for altering the user's authentication token. If the
-module requires access to another system over some network it should
-attempt to verify it can connect to this system on receiving this
-flag. If a module cannot establish it is ready to update the user's
-authentication token it should return <tt/PAM_TRY_AGAIN/, this
-information will be passed back to the application.
-
-<tag><tt/PAM_UPDATE_AUTHTOK/</tag>
-	This informs the module that this is the call it should change
-the authorization tokens. If the flag is logically OR'd with
-<tt/PAM_CHANGE_EXPIRED_AUTHTOK/, the token is only changed if it has
-actually expired.
-
-</descrip>
-
-<p>
-Note, the <bf/Linux-PAM/ library calls this function twice in
-succession. The first time with <tt/PAM_PRELIM_CHECK/ and then, if the
-module does not return <tt/PAM_TRY_AGAIN/, subsequently with
-<tt/PAM_UPDATE_AUTHTOK/. It is only on the second call that the
-authorization token is (possibly) changed.
-
-<p>
-<tt/PAM_SUCCESS/ is the only successful return value, valid
-error-returns are:
-
-<descrip>
-<tag><tt/PAM_AUTHTOK_ERR/</tag>
-	The module was unable to obtain the new authentication token.
-	
-<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag>
-	The module was unable to obtain the old authentication token.
-
-<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag>
-	Cannot change the authentication token since it is currently
-locked.
-	
-<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag>
-	Authentication token aging has been disabled.
-
-<tag><tt/PAM_PERM_DENIED/</tag>
-	Permission denied.
-
-<tag><tt/PAM_TRY_AGAIN/</tag>
-	Preliminary check was unsuccessful. Signals an immediate return
-to the application is desired.
-
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-	The user is not known to the authentication token changing
-service.
-
-</descrip>
-
-</itemize>
-
-<sect>Generic optional arguments
-
-<p>
-Here we list the generic arguments that all modules can expect to
-be passed. They are not mandatory, and their absence should be
-accepted without comment by the module.
-
-<p>
-<descrip>
-<tag><tt/debug/</tag>
-
-Use the <tt/syslog(3)/ call to log debugging information to the system
-log files.
-
-<tag><tt/no_warn/</tag>
-
-Instruct module to not give warning messages to the application.
-
-<tag><tt/use_first_pass/</tag>
-
-The module should not prompt the user for a password. Instead, it
-should obtain the previously typed password (by a call to
-<tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/ item), and use that. If
-that doesn't work, then the user will not be authenticated. (This
-option is intended for <tt/auth/ and <tt/passwd/ modules only).
-
-<tag><tt/try_first_pass/</tag>
-
-The module should attempt authentication with the previously typed
-password (by a call to <tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/
-item). If that doesn't work, then the user is prompted for a
-password. (This option is intended for <tt/auth/ modules only).
-
-<tag><tt/use_mapped_pass/</tag>
-
-<bf/WARNING:/ coding this functionality may cause the module writer to
-break <em/local/ encryption laws. For example, in the U.S. there are
-restrictions on the export computer code that is capable of strong
-encryption.  It has not been established whether this option is
-affected by this law, but one might reasonably assume that it does
-until told otherwise.  For this reason, this option is not supported
-by any of the modules distributed with <bf/Linux-PAM/.
-
-The intended function of this argument, however, is that the module
-should take the existing authentication token from a previously
-invoked module and use it as a key to retrieve the authentication
-token for this module. For example, the module might create a strong
-hash of the <tt/PAM_AUTHTOK/ item (established by a previously
-executed module). Then, with logical-exclusive-or, use the result as a
-<em/key/ to safely store/retrieve the authentication token for this
-module in/from a local file <em/etc/. .
-
-<tag><tt/expose_account/</tag>
-
-<p>
-In general the leakage of some information about user accounts is not
-a secure policy for modules to adopt. Sometimes information such as
-users names or home directories, or preferred shell, can be used to
-attack a user's account. In some circumstances, however, this sort of
-information is not deemed a threat: displaying a user's full name when
-asking them for a password in a secured environment could also be
-called being 'friendly'. The <tt/expose_account/ argument is a
-standard module argument to encourage a module to be less discrete
-about account information as it is deemed appropriate by the local
-administrator.
-
-</descrip>
-
-<sect>Programming notes
-
-<p>
-Here we collect some pointers for the module writer to bear in mind
-when writing/developing a <bf/Linux-PAM/ compatible module.
-
-<sect1>Security issues for module creation
-
-<sect2>Sufficient resources
-
-<p>
-Care should be taken to ensure that the proper execution of a module
-is not compromised by a lack of system resources.  If a module is
-unable to open sufficient files to perform its task, it should fail
-gracefully, or request additional resources.  Specifically, the
-quantities manipulated by the <tt/setrlimit(2)/ family of commands
-should be taken into consideration.
-
-<sect2>Who's who?
-
-<p>
-Generally, the module may wish to establish the identity of the user
-requesting a service.  This may not be the same as the username
-returned by <tt/pam_get_user()/. Indeed, that is only going to be the
-name of the user under whose identity the service will be given.  This
-is not necessarily the user that requests the service.
-
-<p>
-In other words, user X runs a program that is setuid-Y, it grants the
-user to have the permissions of Z.  A specific example of this sort of
-service request is the <em/su/ program: user <tt/joe/ executes
-<em/su/ to become the user <em/jane/.  In this situation X=<tt/joe/,
-Y=<tt/root/ and Z=<tt/jane/.  Clearly, it is important that the module
-does not confuse these different users and grant an inappropriate
-level of privilege.
-
-<p>
-The following is the convention to be adhered to when juggling
-user-identities.
-
-<p>
-<itemize>
-<item>X, the identity of the user invoking the service request.
-This is the user identifier; returned by the function <tt/getuid(2)/.
-
-<item>Y, the privileged identity of the application used to grant the
-requested service.  This is the <em/effective/ user identifier;
-returned by the function <tt/geteuid(2)/.
-
-<item>Z, the user under whose identity the service will be granted.
-This is the username returned by <tt/pam_get_user(2)/ and also stored
-in the <bf/Linux-PAM/ item, <tt/PAM_USER/.
-
-<item><bf/Linux-PAM/ has a place for an additional user identity that
-a module may care to make use of. This is the <tt/PAM_RUSER/ item.
-Generally, network sensitive modules/applications may wish to set/read
-this item to establish the identity of the user requesting a service
-from a remote location.
-
-</itemize>
-
-<p>
-Note, if a module wishes to modify the identity of either the <tt/uid/
-or <tt/euid/ of the running process, it should take care to restore
-the original values prior to returning control to the <bf/Linux-PAM/
-library.
-
-<sect2>Using the conversation function
-<p>
-Prior to calling the conversation function, the module should reset
-the contents of the pointer that will return the applications
-response.  This is a good idea since the application may fail to fill
-the pointer and the module should be in a position to notice!
-
-<p>
-The module should be prepared for a failure from the conversation. The
-generic error would be <tt/PAM_CONV_ERR/, but anything other than
-<tt/PAM_SUCCESS/ should be treated as indicating failure.
-
-<sect2>Authentication tokens
-
-<p>
-To ensure that the authentication tokens are not left lying around the
-items, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/, are not available to
-the application: they are defined in
-<tt>&lt;security/pam_modules.h&gt;</tt>. This is ostensibly for
-security reasons, but a maliciously programmed application will always
-have access to all memory of the process, so it is only superficially
-enforced.  As a general rule the module should overwrite
-authentication tokens as soon as they are no longer needed.
-Especially before <tt/free()/'ing them. The <bf/Linux-PAM/ library is
-required to do this when either of these authentication token items
-are (re)set.
-
-<p>
-Not to dwell too little on this concern; should the module store the
-authentication tokens either as (automatic) function variables or
-using <tt/pam_[gs]et_data()/ the associated memory should be
-over-written explicitly before it is released. In the case of the
-latter storage mechanism, the associated <tt/cleanup()/ function
-should explicitly overwrite the <tt/*data/ before <tt/free()/'ing it:
-for example,
-
-<tscreen>
-<verb>
-/*
- * An example cleanup() function for releasing memory that was used to
- * store a password. 
- */
-
-int cleanup(pam_handle_t *pamh, void *data, int error_status)
-{
-    char *xx;
-
-    if ((xx = data)) {
-        while (*xx)
-            *xx++ = '\0';
-        free(data);
-    }
-    return PAM_SUCCESS;
-}
-</verb>
-</tscreen>
-
-<sect1>Use of <tt/syslog(3)/
-
-<p>
-Only rarely should error information be directed to the user. Usually,
-this is to be limited to ``<em/sorry you cannot login now/'' type
-messages. Information concerning errors in the configuration file,
-<tt>/etc/pam.conf</tt>, or due to some system failure encountered by
-the module, should be written to <tt/syslog(3)/ with
-<em/facility-type/ <tt/LOG_AUTHPRIV/.
-
-<p>
-With a few exceptions, the level of logging is, at the discretion of
-the module developer. Here is the recommended usage of different
-logging levels:
-
-<p>
-<itemize>
-
-<item>
-As a general rule, errors encountered by a module should be logged at
-the <tt/LOG_ERR/ level. However, information regarding an unrecognized
-argument, passed to a module from an entry in the
-<tt>/etc/pam.conf</tt> file, is <bf/required/ to be logged at the
-<tt/LOG_ERR/ level.
-
-<item>
-Debugging information, as activated by the <tt/debug/ argument to the
-module in <tt>/etc/pam.conf</tt>, should be logged at the
-<tt/LOG_DEBUG/ level.
-
-<item>
-If a module discovers that its personal configuration file or some
-system file it uses for information is corrupted or somehow unusable,
-it should indicate this by logging messages at level, <tt/LOG_ALERT/.
-
-<item>
-Shortages of system resources, such as a failure to manipulate a file
-or <tt/malloc()/ failures should be logged at level <tt/LOG_CRIT/.
-
-<item>
-Authentication failures, associated with an incorrectly typed password
-should be logged at level, <tt/LOG_NOTICE/.
-
-</itemize>
-
-<sect1> Modules that require system libraries
-
-<p>
-Writing a module is much like writing an application. You have to
-provide the "conventional hooks" for it to work correctly, like
-<tt>pam_sm_authenticate()</tt> etc., which would correspond to the
-<tt/main()/ function in a normal function.
-
-<p>
-Typically, the author may want to link against some standard system
-libraries. As when one compiles a normal program, this can be done for
-modules too: you simply append the <tt>-l</tt><em>XXX</em> arguments
-for the desired libraries when you create the shared module object. To
-make sure a module is linked to the <tt>lib<em>whatever</em>.so</tt>
-library when it is <tt>dlopen()</tt>ed, try:
-<tscreen>
-<verb>
-% gcc -shared -Xlinker -x -o pam_module.so pam_module.o -lwhatever
-</verb>
-</tscreen>
-
-<sect1> Added requirements for <em/statically/ loaded modules.
-
-<!--
-	Copyright (C) Michael K. Johnson 1996.
-	Last modified:  AGM 1996/5/31.
- -->
-
-<p>
-Modules may be statically linked into libpam. This should be true of
-all the modules distributed with the basic <bf/Linux-PAM/
-distribution.  To be statically linked, a module needs to export
-information about the functions it contains in a manner that does not
-clash with other modules.
-
-The extra code necessary to build a static module should be delimited
-with <tt/#ifdef PAM_STATIC/ and <tt/#endif/. The static code should do
-the following:
-<itemize>
-<item> Define a single structure, <tt/struct pam_module/, called
-<tt>_pam_<it>modname</it>_modstruct</tt>, where
-<tt><it>modname</it></tt> is the name of the module <bf/as used in the
-filesystem/ but without the leading directory name (generally
-<tt>/usr/lib/security/</tt> or the suffix (generally <tt/.so/).
-
-</itemize>
-
-<p>
-As a simple example, consider the following module code which defines
-a module that can be compiled to be <em/static/ or <em/dynamic/:
-
-<p>
-<tscreen>
-<verb>
-#include <stdio.h>                                    /* for NULL define */
-
-#define PAM_SM_PASSWORD         /* the only pam_sm_... function declared */
-#include <security/pam_modules.h>
-
-PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags,
-                                int argc, const char **argv)
-{
-     return PAM_SUCCESS;
-}
-
-#ifdef PAM_STATIC             /* for the case that this module is static */
-
-struct pam_module _pam_modname_modstruct = {       /* static module data */
-     "pam_modname",
-     NULL,
-     NULL,
-     NULL,
-     NULL,
-     NULL,
-     pam_sm_chauthtok,
-};
-
-#endif                                                 /* end PAM_STATIC */
-</verb>
-</tscreen>
-
-<p>
-To be linked with <em/libpam/, staticly-linked modules must be built
-from within the <tt>Linux-PAM-X.YY/modules/</tt> subdirectory of the
-<bf/Linux-PAM/ source directory as part of a normal build of the
-<bf/Linux-PAM/ system.
-
-The <em/Makefile/, for the module in question, must execute the
-<tt/register_static/ shell script that is located in the
-<tt>Linux-PAM-X.YY/modules/</tt> subdirectory. This is to ensure that
-the module is properly registered with <em/libpam/.
-
-The <bf/two/ manditory arguments to <tt/register_static/ are the
-title, and the pathname of the object file containing the module's
-code. The pathname is specified relative to the
-<tt>Linux-PAM-X.YY/modules</tt> directory. The pathname may be an
-empty string---this is for the case that a single object file needs to
-register more than one <tt/struct pam_module/. In such a case, exactly
-one call to <tt/register_static/ must indicate the object file.
-
-<p>
-Here is an example; a line in the <em/Makefile/ might look like this:
-<tscreen>
-<verb>
-register:
-ifdef STATIC
-        (cd ..; ./register_static pam_modname pam_modname/pam_modname.o)
-endif
-</verb>
-</tscreen>
-
-For some further examples, see the <tt>modules</tt> subdirectory of
-the current <bf/Linux-PAM/ distribution.
-
-<sect>An example module file
-
-<p>
-At some point, we may include a fully commented example of a module in
-this document. For now, we point the reader to these two locations in
-the public CVS repository:
-<itemize>
-<item> A module that always succeeds: <tt><htmlurl
-url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_permit/"
-name="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_permit/"
-></tt>
-<item> A module that always fails: <tt><htmlurl
-url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_deny/"
-name="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_deny/"
-></tt>
-</itemize>
-
-<sect>Files
-
-<p><descrip>
-
-<tag><tt>/usr/lib/libpam.so.*</tt></tag>
-
-the shared library providing applications with access to
-<bf/Linux-PAM/.
-
-<tag><tt>/etc/pam.conf</tt></tag>
-
-the <bf/Linux-PAM/ configuration file.
-
-<tag><tt>/usr/lib/security/pam_*.so</tt></tag>
-
-the primary location for <bf/Linux-PAM/ dynamically loadable object
-files; the modules.
-
-</descrip>
-
-<sect>See also
-
-<p><itemize>
-<item>The <bf/Linux-PAM/ System Administrators' Guide.
-<item>The <bf/Linux-PAM/ Application Writers' Guide.
-<item>
-V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE
-AUTHENTICATION MODULES'', Open Software Foundation Request For
-Comments 86.0, October 1995.
-</itemize>
-
-<sect>Notes
-
-<p>
-I intend to put development comments here... like ``at the moment
-this isn't actually supported''. At release time what ever is in
-this section will be placed in the Bugs section below! :)
-
-<p>
-<itemize>
-<item>
-Perhaps we should keep a registry of data-names as used by
-<tt/pam_[gs]et_data()/ so there are no unintentional problems due to
-conflicts?
-
-<item>
-<tt/pam_strerror()/ should be internationalized....
-
-<item>
-There has been some debate about whether <tt/initgroups()/ should be
-in an application or in a module. It was settled by Sun who stated
-that initgroups is an action of the <em/application/. The modules are
-permitted to add additional groups, however.
-
-<item>
-Refinements/futher suggestions to <tt/syslog(3)/ usage by modules are
-needed.
-
-</itemize>
-
-<sect>Author/acknowledgments
-
-<p>
-This document was written by Andrew G. Morgan
-(<tt/morgan@kernel.org/) with many contributions from
-<!-- insert credits here -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id$
-  -->
-Chris Adams,
-Peter Allgeyer,
-Tim Baverstock,
-Tim Berger,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Seth Chaiklin,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Emmanuel Galanos,
-Brad M. Garcia,
-Eric Hester,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Olaf Kirch,
-Marcin Korzonek,
-Stephen Langasek,
-Nicolai Langfeldt,
-Elliot Lee,
-Luke Kenneth Casson Leighton,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Robert Milkowski,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-Jan Rekorajski,
-Erik Troan,
-Theodore Ts'o,
-Jeff Uphoff,
-Myles Uyema,
-Savochkin Andrey Vladimirovich,
-Ronald Wahl,
-David Wood,
-John Wilmes,
-Joseph S. D. Yao
-and
-Alex O.  Yuriev.
-
-<p>
-Thanks are also due to Sun Microsystems, especially to Vipin Samar and
-Charlie Lai for their advice. At an early stage in the development of
-<bf/Linux-PAM/, Sun graciously made the documentation for their
-implementation of PAM available. This act greatly accelerated the
-development of <bf/Linux-PAM/.
-
-<sect>Bugs/omissions
-
-<p>
-Few PAM modules currently exist. Few PAM-aware applications exist.
-This document is hopelessly unfinished. Only a partial list of people is
-credited for all the good work they have done.
-
-<sect>Copyright information for this document
-
-<p>
-Copyright (c) Andrew G. Morgan 1996-2002.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@kernel.org&gt;</tt>
-
-<p>
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-<p>
-<itemize>
-
-<item>
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-<item>
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-<item>
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-</itemize>
-
-<p>
-<bf/Alternatively/, this product may be distributed under the terms of
-the GNU General Public License (GPL), in which case the provisions of
-the GNU GPL are required <bf/instead of/ the above restrictions.
-(This clause is necessary due to a potential bad interaction between
-the GNU GPL and the restrictions contained in a BSD-style copyright.)
-
-<p>
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
-<p>
-<tt>$Id$</tt>
-
-</article>
diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml
deleted file mode 100644
index 2dd5783e..00000000
--- a/doc/pam_source.sgml
+++ /dev/null
@@ -1,1160 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id$
-
-    Copyright (c) Andrew G. Morgan 1996-2002.  All rights reserved.
-
-Redistribution and use in source (sgml) and binary (derived) forms,
-with or without modification, are permitted provided that the
-following conditions are met:
-
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-ALTERNATIVELY, this product may be distributed under the terms of the
-GNU General Public License, in which case the provisions of the GNU
-GPL are required INSTEAD OF the above restrictions.  (This clause is
-necessary due to a potential bad interaction between the GNU GPL and
-the restrictions contained in a BSD-style copyright.)
-
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
- -->
-
-<article>
-
-<title>The Linux-PAM System Administrators' Guide
-<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.76 2002/06/26
-<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
-PAM configuration file and discusses strategies for maintaining a
-secure system.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Introduction
-
-<p><bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a
-suite of shared libraries that enable the local system administrator
-to choose how applications authenticate users.
-
-<p>In other words, without (rewriting and) recompiling a PAM-aware
-application, it is possible to switch between the authentication
-mechanism(s) it uses. Indeed, one may entirely upgrade the local
-authentication system without touching the applications themselves.
-
-<p>Historically an application that has required a given user to be
-authenticated, has had to be compiled to use a specific authentication
-mechanism.  For example, in the case of traditional UN*X systems, the
-identity of the user is verified by the user entering a correct
-password.  This password, after being prefixed by a two character
-``salt'', is encrypted (with crypt(3)). The user is then authenticated
-if this encrypted password is identical to the second field of the
-user's entry in the system password database (the <tt>/etc/passwd</tt>
-file).  On such systems, most if not all forms of privileges are
-granted based on this single authentication scheme. Privilege comes in
-the form of a personal user-identifier (<tt/uid/) and membership of
-various groups. Services and applications are available based on the
-personal and group identity of the user. Traditionally, group
-membership has been assigned based on entries in the
-<tt>/etc/group</tt> file.
-
-<p>
-Unfortunately, increases in the speed of computers and the
-widespread introduction of network based computing, have made once
-secure authentication mechanisms, such as this, vulnerable to
-attack. In the light of such realities, new methods of authentication
-are continuously being developed.
-
-<p>
-It is the purpose of the <bf/Linux-PAM/ project to separate the
-development of privilege granting software from the development of
-secure and appropriate authentication schemes.  This is accomplished
-by providing a library of functions that an application may use to
-request that a user be authenticated. This PAM library is configured
-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>/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">
-
-<p>
-Before proceeding to read the rest of this document, it should be
-noted that the text assumes that certain files are placed in certain
-directories.  Where they have been specified, the conventions we adopt
-here for locating these files are those of the relevant RFC (RFC-86.0,
-see <ref id="see-also-sec" name="bibliography">).  If you are using a
-distribution of Linux (or some other operating system) that supports
-PAM but chooses to distribute these files in a diferent way you should
-be careful when copying examples 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>/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">
-
-<p>
-For the uninitiated, we begin by considering an example.  We take an
-application that grants some service to users; <em/login/ is one such
-program. <em/Login/ does two things, it first establishes that the
-requesting user is whom they claim to be and second provides them with
-the requested service: in the case of <em/login/ the service is a
-command shell (<em>bash, tcsh, zsh, etc.</em>) running with the
-identity of the user.
-
-<p>
-Traditionally, the former step is achieved by the <em/login/
-application prompting the user for a password and then verifying that
-it agrees with that located on the system; hence verifying that
-as far as the system is concerned the user is who they claim to be.
-This is the task that is delegated to <bf/Linux-PAM/.
-
-<p>
-From the perspective of the application programmer (in this case the
-person that wrote the <em/login/ application), <bf/Linux-PAM/ takes
-care of this authentication task -- verifying the identity of the user.
-
-<p>
-The flexibility of <bf/Linux-PAM/ is that <em/you/, the system
-administrator, have the freedom to stipulate which authentication
-scheme is to be used.  You have the freedom to set the scheme for
-any/all PAM-aware applications on your Linux system.  That is, you can
-authenticate from anything as naive as <em/simple trust/
-(<tt/pam_permit/) to something as paranoid as a combination of a
-retinal scan, a voice print and a one-time password!
-
-<p>
-To illustrate the flexibility you face, consider the following
-situation: a system administrator (parent) wishes to improve the
-mathematical ability of her users (children). She can configure their
-favorite ``Shoot 'em up game'' (PAM-aware of course) to authenticate
-them with a request for the product of a couple of random numbers less
-than 12. It is clear that if the game is any good they will soon learn
-their <em/multiplication tables/.   As they mature, the authentication
-can be upgraded to include (long) division!
-
-<p>
-<bf/Linux-PAM/ deals with four separate types of (management)
-task. These are: <em/authentication management/; <em/account
-management/; <em/session management/; and <em/password management/.
-The association of the preferred management scheme with the behavior
-of an application is made with entries in the relevant <bf/Linux-PAM/
-configuration file.  The management functions are performed by
-<em/modules/ specified in the configuration file. The syntax for this
-file is discussed in the section <ref id="configuration"
-name="below">.
-
-<p>
-Here is a figure that describes the overall organization of
-<bf/Linux-PAM/.
-<tscreen>
-<verb>
-	 +----------------+
-	 | application: X |
-         +----------------+	  /  +----------+     +================+
-       	 | authentication-[---->--\--] Linux-   |--<--| PAM config file|
-	 |       +        [----<--/--] 	 PAM    |     |================|
-	 |[conversation()][--+    \  |          |     | X auth .. a.so |
-	 +----------------+  |    /  +-n--n-----+     | X auth .. b.so |
-	 |                |  |       __|  |           |           _____/
-	 |  service user  |  A      |  	  |           |____,-----' 
-	 |                |  |      V  	  A	        	   
-	 +----------------+  +------|-----|---------+ -----+------+
-	                        +---u-----u----+    |	   |	  |
-			        |   auth....   |--[ a ]--[ b ]--[ c ]
-				+--------------+
-				|   acct....   |--[ b ]--[ d ]
-				+--------------+
-				|   password   |--[ b ]--[ c ]
-				+--------------+
-				|   session    |--[ e ]--[ c ]
-				+--------------+
-</verb>
-</tscreen>
-By way of explanation, the left of the figure represents the
-application; application X.  Such an application interfaces with the
-<bf/Linux-PAM/ library and knows none of the specifics of its
-configured authentication method.  The <bf/Linux-PAM/ library (in the
-center) consults the contents of the PAM configuration file and loads
-the modules that are appropriate for application-X. These modules fall
-into one of four management groups (lower-center) and are stacked in
-the order they appear in the configuration file. These modules, when
-called by <bf/Linux-PAM/, perform the various authentication tasks for
-the application. Textual information, required from/or offered to the
-user, can be exchanged through the use of the application-supplied
-<em/conversation/ function.
-
-<sect1>Getting started
-
-<p>
-The following text was contributed by Seth Chaiklin:
-<tscreen>
-<verb>
-To this point, we have described how PAM should work in an
-ideal world, in which all applications are coded properly.
-However, at the present time (October 1998), this is far
-from the case.  Therefore, here are some practical considerations
-in trying to use PAM in your system.
-
-Why bother, is it really worth all the trouble?  
-
-If you running Linux as a single user system, or in an
-environment where all the users are trusted, then there 
-is no real advantage for using PAM.
-</verb>
-</tscreen>
-
-<p>
-<BF>Ed:</BF> there is actually an advantage since you can <em/dummy
-down/ the authentication to the point where you don't have
-any... Almost like Win95.
-<p>
-In a networked environment, it is clear that you need to think a
-little more about how users etc., are authenticated:]
-
-<p>
-<tscreen>
-<verb>
-If you are running Linux as a server, where several different
-services are being provided (e.g., WWW with areas restricted by
-password control, PPP), then there can be some real and interesting
-value for PAM.  In particular, through the use of modules, PAM can
-enable a program to search through several different password
-databases, even if that program is not explicitly coded for
-that particular database.  Here are some examples of the possibilities
-that this enables.
-
-   o  Apache has a module that provides PAM services.  Now
-   authentication
-      to use particular directories can be conducted by PAM, which
-      means that the range of modules that are available to PAM can
-      be used, including RADIUS, NIS, NCP (which means that Novell
-      password databases can be used).
-
-   o  pppd has a PAMified version (available from RedHat)  Now it is
-      possible to use a series of databases to authenticate ppp users.
-      In addition to the normal Linux-based password databases (such
-      as /etc/passwd and /etc/shadow), you can use PAM modules to 
-      authenticate against Novell password databases or NT-based 
-      password databases. 
-
-   o  The preceding two examples can be combined.  Imagaine that the
-      persons in your office/department are already registered with a
-      username and password in a Novell or NT LAN.  If you wanted to
-      use this database on your Linux server (for PPP access, for 
-      web access, or even for normal shell access), you can use PAM
-      to authenticate against this existing database, rather than
-      maintain a separate database on both Linux and the LAN server.
-
-
-Can I use PAM for any program that requires authentication?
-
-Yes and no.   Yes, if you have access to the source code, and can
-add the appropriate PAM functions.  No, if you do not have access 
-to the source code, and the binary does not have the PAM functions
-included.
-
-In other words, if a program is going to use PAM, then it has to
-have PAM functions explicitly coded into the program.  If they
-are not, then it is not possible to use PAM. 
-
-How can I tell whether a program has PAM coded into it or not?
-
-A quick-and-dirty (but not always reliable) method is to ldd
-<programname>
-If libpam and libpam_misc are not among the libraries that the program
-uses, then it is not going to work with PAM.  However, it is possible
-that the libraries are included, but there are still problems, because
-the PAM coding in the program does not work as it should.  So a
-more reliable method is to make the follow tests.
-
-In the /etc/pam.d directory, one needs to make a configuration file
-for the program that one wants to run.  The exact name of the
-configuration
-file is hard-coded into the program.  Usually, it is the same name as
-the
-program, but not always.  For sake of illustration, let's assume that
-the program is named "pamprog" and the name of the configuration file
-is /etc/pam.d/pamprog.
-
-In the /etc/pam.d/pamprog but the following two lines:
-
-auth    required  pam_permit.so
-auth    required  pam_warn.so
-
-
-Now try to use pamprog.  The first line in the configuration file 
-says that all users are permitted.  The second line will write a
-warning to your syslog file (or whether you syslog is writing
-
-messages).  If this test succeeds, then you know that you have
-a program that can understand pam, and you can start the more
-interesting work of deciding how to stack modules in your
-/etc/pam.d/pamprog  file.
-</verb>
-</tscreen>
-
-<sect>The Linux-PAM configuration file
-<label id="configuration">
-
-<p>
-<bf/Linux-PAM/ is designed to provide the system administrator with a
-great deal of flexibility in configuring the privilege granting
-applications of their system. The local configuration of those aspects
-of system security controlled by <tt/Linux-PAM/ is contained in one of
-two places: either the single system file, <tt>/etc/pam.conf</tt>; or
-the <tt>/etc/pam.d/</tt> directory.  In this section we discuss the
-correct syntax of and generic options respected by entries to these
-files.
-
-<sect1>Configuration file syntax
-
-<p>
-The reader should note that the <bf/Linux-PAM/ specific tokens in this
-file are case <em/insensitive/. The module paths, however, are case
-sensitive since they indicate a file's <em/name/ and reflect the case
-dependence of typical Linux file-systems. The case-sensitivity of the
-arguments to any given module is defined for each module in turn.
-
-<p>
-In addition to the lines described below, there are two <em/special/
-characters provided for the convenience of the system administrator:
-comments are preceded by a `<tt/&num;/' and extend to the
-next end-of-line; also, module specification lines may be extended
-with a `<tt/&bsol;/' escaped newline.
-
-<p>
-A general configuration line of the <tt>/etc/pam.conf</tt> file has
-the following form:
-<tscreen>
-<verb>
-service-name   module-type   control-flag   module-path   args
-</verb>
-</tscreen>
-Below, we explain the meaning of each of these tokens. The second (and
-more recently adopted) way of configuring <bf/Linux-PAM/ is via the
-contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained
-the meaning of the above tokens, we will describe this method.
-
-<p>
-<descrip>
-<tag><tt/service-name/</tag>
-The name of the service associated with this entry. Frequently the
-service name is the conventional name of the given application. For
-example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ .
-
-<p>
-There is a special <tt/service-name/, reserved for defining a default
-authentication mechanism. It has the name `<tt/OTHER/' and may be
-specified in either lower or upper case characters. Note, when there
-is a module specified for a named service, the `<tt/OTHER/' entries
-are ignored.
-
-<tag><tt/module-type/</tag>
-One of (currently) four types of module. The four types are as
-follows:
-<itemize>
-<item> <tt/auth/; this module type provides two aspects of
-authenticating the user. Firstly, it establishes that the user is who
-they claim to be, by instructing the application to prompt the user
-for a password or other means of identification. Secondly, the module
-can grant <tt/group/ membership (independently of the
-<tt>/etc/groups</tt> file discussed above) or other privileges through
-its <em/credential/ granting properties.
-
-<item> <tt/account/; this module performs non-authentication based
-account management. It is typically used to restrict/permit access to
-a service based on the time of day, currently available system
-resources (maximum number of users) or perhaps the location of the
-applicant user---`<tt/root/' login only on the console.
-
-<item> <tt/session/; primarily, this module is associated with doing
-things that need to be done for the user before/after they can be
-given service.  Such things include the logging of information
-concerning the opening/closing of some data exchange with a user,
-mounting directories, etc. .
-
-<item> <tt/password/; this last module type is required for updating the
-authentication token associated with the user. Typically, there is one
-module for each `challenge/response' based authentication (<tt/auth/)
-module-type.
-
-</itemize>
-
-<tag><tt/control-flag/</tag>
-
-The control-flag is used to indicate how the PAM library will react to
-the success or failure of the module it is associated with.  Since
-modules can be <em/stacked/ (modules of the same type execute in
-series, one after another), the control-flags determine the relative
-importance of each module.  The application is not made aware of the
-individual success or failure of modules listed in the
-`<tt>/etc/pam.conf</tt>' file.  Instead, it receives a summary
-<em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library.
-The order of execution of these modules is that of the entries in the
-<tt>/etc/pam.conf</tt> file; earlier entries are executed before later
-ones.  As of Linux-PAM v0.60, this <em/control-flag/ can be defined
-with one of two syntaxes.
-
-<p>
-The simpler (and historical) syntax for the control-flag is a single
-keyword defined to indicate the severity of concern associated with
-the success or failure of a specific module.  There are four such
-keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and
-<tt/optional/.
-
-<p>
-The Linux-PAM library interprets these keywords in the following
-manner:
-
-<itemize>
-
-<item> <tt/required/; this indicates that the success of the module is
-required for the <tt/module-type/ facility to succeed. Failure of this
-module will not be apparent to the user until all of the remaining
-modules (of the same <tt/module-type/) have been executed.
-
-<item> <tt/requisite/; like <tt/required/, however, in the case that
-such a module returns a failure, control is directly returned to the
-application.  The return value is that associated with the <em/first/
-<tt/required/ or <tt/requisite/ module to fail.  Note, this flag can be
-used to protect against the possibility of a user getting the
-opportunity to enter a password over an unsafe medium.  It is
-conceivable that such behavior might inform an attacker of valid
-accounts on a system. This possibility should be weighed against the
-not insignificant concerns of exposing a sensitive password in a
-hostile environment.
-
-<item> <tt/sufficient/; the success of this module is deemed
-`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this
-module-type has succeeded in its purpose. In the event that no
-previous <tt/required/ module has failed, no more `<em/stacked/'
-modules of this type are invoked. (Note, in this case subsequent
-<tt/required/ modules are <bf/not/ invoked.). A failure of this module
-is not deemed as fatal to satisfying the application that this
-<tt/module-type/ has succeeded.
-
-<item> <tt/optional/; as its name suggests, this <tt/control-flag/
-marks the module as not being critical to the success or failure of
-the user's application for service.  In general, <bf/Linux-PAM/
-ignores such a module when determining if the module stack will
-succeed or fail.  However, in the absence of any definite successes or
-failures of previous or subsequent stacked modules this module will
-determine the nature of the response to the application.  One example
-of this latter case, is when the other modules return something like
-<tt/PAM_IGNORE/.
-
-</itemize>
-
-<p>
-The more elaborate (newer) syntax is much more specific and gives the
-administrator a great deal of control over how the user is
-authenticated.  This form of the control flag is delimeted with square
-brackets and consists of a series of <tt/value=action/ tokens:
-<tscreen>
-<verb>
-    [value1=action1 value2=action2 ...]
-</verb>
-</tscreen>
-
-<p>
-Here, <tt/valueI/ is one of the following <em/return values/:
-<tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/;
-<tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/;
-<tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/;
-<tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/;
-<tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/;
-<tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/;
-<tt/authtok_recover_err/; <tt/authtok_lock_busy/;
-<tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/;
-<tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and
-<tt/default/.  The last of these (<tt/default/) can be used to set the
-action for those return values that are not explicitly defined.
-
-<p>
-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
-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>
-<item><tt/ignore/ - when used with a stack of modules, the module's
-  return status will not contribute to the return code the application
-  obtains.
-<item><tt/bad/ - this action indicates that the return code should be
-  thought of as indicative of the module failing. If this module is
-  the first in the stack to fail, its status value will be used for
-  that of the whole stack.
-<item><tt/die/ - equivalent to <tt/bad/ with the side effect of
-  terminating the module stack and PAM immediately returning to the
-  application.
-<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this
-  return code should contribute directly to the return code of the full
-  stack of modules. In other words, if the former state of the stack
-  would lead to a return of <tt/PAM_SUCCESS/, the module's return code
-  will override this value.  Note, if the former state of the stack
-  holds some value that is indicative of a modules failure, this 'ok'
-  value will not be used to override that value.
-<item><tt/done/ - equivalent to <tt/ok/ with the side effect of
-  terminating the module stack and PAM immediately returning to the
-  application.
-<item><tt/reset/ - clear all memory of the state of the module stack and
-  start again with the next stacked module.
-</itemize>
-
-<p>
-Each of the four keywords: <tt/required/; <tt/requisite/;
-<tt/sufficient/; and <tt/optional/, have an equivalent expression in
-terms of the <tt/[...]/ syntax. They are as follows:
-<itemize>
-<item><tt/required/ is equivalent to
-<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=bad]/
-<item><tt/requisite/ is equivalent to
-<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=die]/
-<item><tt/sufficient/ is equivalent to
-<tt/[success=done new_authtok_reqd=done default=ignore]/
-<item><tt/optional/ is equivalent to 
-<tt/[success=ok new_authtok_reqd=ok default=ignore]/
-</itemize>
-
-<p>
-Just to get a feel for the power of this new syntax, here is a taste
-of what you can do with it.  With <bf/Linux-PAM-0.63/, the notion of
-client plug-in agents was introduced.  This is something that makes it
-possible for PAM to support machine-machine authentication using the
-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.
-
-<tag> <tt/module-path/</tag>
-
-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>/lib/security</tt> (but see the notes <ref id="text-conventions"
-name="above">).
-
-<tag> <tt/args/</tag>
-
-The <tt/args/ are a list of tokens that are passed to the module when
-it is invoked. Much like arguments to a typical Linux shell command.
-Generally, valid arguments are optional and are specific to any given
-module. Invalid arguments are ignored by a module, however, when
-encountering an invalid argument, the module is required to write an
-error to <tt/syslog(3)/. For a list of <em/generic/ options see the
-next section.
-
-Note, if you wish to include spaces in an argument, you should
-surround that argument with square brackets. For example:
-<tscreen>
-<verb>
-squid auth required pam_mysql.so user=passwd_query passwd=mada \
-        db=eminence [query=select user_name from internet_service where \
-                     user_name='%u' and password=PASSWORD('%p') and \
-                     service='web_proxy']
-</verb>
-</tscreen>
-Note, when using this convention, you can include `<tt/[/' characters
-inside the string, and if you wish to include a `<tt/]/' character
-inside the string that will survive the argument parsing, you should
-use `<tt/\[/'. In other words:
-<tscreen>
-<verb>
-[..[..\]..]    -->   ..[..]..
-</verb>
-</tscreen>
-
-</descrip>
-
-<p>
-Any line in (one of) the configuration file(s), that is not formatted
-correctly, will generally tend (erring on the side of caution) to make
-the authentication process fail.  A corresponding error is written to
-the system log files with a call to <tt/syslog(3)/.
-
-<sect1>Directory based configuration
-
-<p>
-More flexible than the single configuration file, as of version 0.56,
-it is possible to configure <tt>libpam</tt> via the contents of the
-<tt>/etc/pam.d/</tt> directory.  In this case the directory is filled
-with files each of which has a filename equal to a service-name (in
-lower-case): it is the personal configuration file for the named
-service.
-
-<p>
-<bf/Linux-PAM/ can be compiled in one of two modes.  The preferred
-mode uses either <tt>/etc/pam.d/</tt> or <tt>/etc/pam.conf</tt>
-configuration but not both.  That is to say, if there is a
-<tt>/etc/pam.d/</tt> directory then libpam only uses the files
-contained in this directory.  However, in the absence of the
-<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is used
-(this is likely to be the mode your preferred distribution uses).  The
-other mode is to use both <tt>/etc/pam.d/</tt> and
-<tt>/etc/pam.conf</tt> in sequence.  In this mode, entries in
-<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>.
-
-The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of
-the <tt>/etc/pam.conf</tt> file and is made up of lines of the
-following form:
-<tscreen>
-<verb>
-module-type   control-flag   module-path   arguments
-</verb>
-</tscreen>
-The only difference being that the <tt>service-name</tt> is not
-present.   The service-name is of course the name of the given
-configuration file.  For example, <tt>/etc/pam.d/login</tt> contains
-the configuration for the <em>login</em> service.
-
-<p>
-This method of configuration has a number of advantages over the
-single file approach. We list them here to assist the reader in
-deciding which scheme to adopt:
-
-<p>
-<itemize>
-
-<item>A lower chance of misconfiguring an application. There is one
-less field to mis-type when editing the configuration files by hand.
-
-<item>Easier to maintain. One application may be reconfigured without
-risk of interfering with other applications on the system.
-
-<item>It is possible to symbolically link different services
-configuration files to a single file. This makes it easier to keep the
-system policy for access consistent across different applications.
-(It should be noted, to conserve space, it is equally possible to
-<em>hard</em> link a number of configuration files.  However, care
-should be taken when administering this arrangement as editing a hard
-linked file is likely to break the link.)
-
-<item>A potential for quicker configuration file parsing. Only the
-relevant entries are parsed when a service gets bound to its modules.
-
-<item>It is possible to limit read access to individual <bf/Linux-PAM/
-configuration files using the file protections of the filesystem.
-
-<item>Package management becomes simpler.  Every time a new
-application is installed, it can be accompanied by an
-<tt>/etc/pam.d/</tt><em>xxxxxx</em> file.
-
-</itemize>
-
-<sect1>Generic optional arguments
-
-<p>
-The following are optional arguments which are likely to be understood
-by any module. Arguments (including these) are in general
-<em/optional/.
-
-<p>
-<descrip>
-<tag><tt/debug/</tag>
-
-Use the <tt/syslog(3)/ call to log debugging information to the system
-log files.
-
-<tag> <tt/no_warn/</tag>
-
-Instruct module to not give warning messages to the application.
-
-<tag> <tt/use_first_pass/</tag>
-
-The module should not prompt the user for a password. Instead, it
-should obtain the previously typed password (from the preceding
-<tt/auth/ module), and use that. If that doesn't work, then the user
-will not be authenticated. (This option is intended for <tt/auth/
-and <tt/password/ modules only).
-
-<tag> <tt/try_first_pass/</tag>
-
-The module should attempt authentication with the previously typed
-password (from the preceding <tt/auth/ module). If that doesn't work,
-then the user is prompted for a password. (This option is intended for
-<tt/auth/ modules only).
-
-<tag> <tt/use_mapped_pass/</tag>
-
-This argument is not currently supported by any of the modules in the
-<bf/Linux-PAM/ distribution because of possible consequences
-associated with U.S. encryption exporting restrictions. Within the
-U.S., module developers are, of course, free to implement it (as are
-developers in other countries). For compatibility reasons we describe
-its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref
-id="see-also-sec" name="bibliography"> for a pointer to this document.
-
-<p>
-The <tt/use_mapped_pass/ argument instructs the module to take the
-clear text authentication token entered by a previous module (that
-requests such a token) and use it to generate an encryption/decryption
-key with which to safely store/retrieve the authentication token
-required for this module. In this way the user can enter a single
-authentication token and be quietly authenticated by a number of
-stacked modules.  Obviously a convenient feature that necessarily
-requires some reliably strong encryption to make it secure.
-This argument is intended for the <tt/auth/ and <tt/password/ module
-types only.
-
-<tag><tt/expose_account/</tag>
-
-<p>
-In general the leakage of some information about user accounts is not
-a secure policy for modules to adopt. Sometimes information such as
-users names or home directories, or preferred shell, can be used to
-attack a user's account. In some circumstances, however, this sort of
-information is not deemed a threat: displaying a user's full name when
-asking them for a password in a secured environment could also be
-called being 'friendly'. The <tt/expose_account/ argument is a
-standard module argument to encourage a module to be less discrete
-about account information as it is deemed appropriate by the local
-administrator.
-
-</descrip>
-
-<sect1>Example configuration file entries
-
-<p>
-In this section, we give some examples of entries that can be present
-in the <bf/Linux-PAM/ configuration file. As a first attempt at
-configuring your system you could do worse than to implement these.
-
-<sect2>Default policy
-
-<p>
-If a system is to be considered secure, it had better have a
-reasonably secure `<tt/OTHER/' entry. The following is a paranoid
-setting (which is not a bad place to start!):
-<tscreen>
-<verb>
-#
-# default; deny access
-#
-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
-a misconfigured system. For example, such a system is vulnerable to
-locking everyone out should the rest of the file become badly written.
-
-<p>
-The module <tt/pam_deny/ (documented in a later section) is not very
-sophisticated. For example, it logs no information when it is invoked
-so unless the users of a system contact the administrator when failing
-to execute a service application, the administrator may go for a long
-while in ignorance of the fact that his system is misconfigured.
-
-<p>
-The addition of the following line before those in the above example
-would provide a suitable warning to the administrator.
-<tscreen>
-<verb>
-#
-# default; wake up! This application is not configured
-#
-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.
-
-<p>
-On a system that uses the <tt>/etc/pam.d/</tt> configuration, the
-corresponding default setup would be achieved with the following file:
-<tscreen>
-<verb>
-#
-# default configuration: /etc/pam.d/other
-#
-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>
-file. In general, it should be clear how to transpose the remaining
-examples to this configuration scheme.
-
-<p>
-On a less sensitive computer, one on which the system administrator
-wishes to remain ignorant of much of the power of <tt/Linux-PAM/, the
-following selection of lines (in <tt>/etc/pam.conf</tt>) is likely to
-mimic the historically familiar Linux setup.
-<tscreen>
-<verb>
-#
-# default; standard UN*X access
-#
-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.
-Unfortunately, most is not all. One application that might require
-additional lines is <em/ftpd/ if you wish to enable
-<em/anonymous-ftp/.
-
-<p>
-To enable anonymous-ftp, the following lines might be used to replace
-the default (<tt/OTHER/) ones. (<bf/*WARNING*/ as of 1996/12/28 this
-does not work correctly with any ftpd. Consequently, this description
-may be subject to change or the application will be fixed.)
-<tscreen>
-<verb>
-#
-# ftpd; add ftp-specifics. These lines enable anonymous ftp over
-#       standard UN*X access (the listfile entry blocks access to
-#	users listed in /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
-ignored by a service application (here <em/ftpd/) if there are
-<em/any/ entries in <tt>/etc/pam.conf</tt> for that specified service.
-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 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 PAM in a secure
-manner.  <em>It is currently sadly lacking...suggestions are
-welcome!</em>
-
-<sect1>If something goes wrong
-
-<p>
-<bf/Linux-PAM/ has the potential to seriously change the security of
-your system.  You can choose to have no security or absolute security
-(no access permitted).  In general, <bf/Linux-PAM/ errs towards the
-latter.  Any number of configuration errors can dissable access to
-your system partially, or completely.
-
-<p>
-The most dramatic problem that is likely to be encountered when
-configuring <bf/Linux-PAM/ is that of <em>deleting</em> the
-configuration file(s): <tt>/etc/pam.d/*</tt> and/or
-<tt>/etc/pam.conf</tt>.  This will lock you out of your own system!
-
-<p>
-To recover, your best bet is to reboot the system in single user mode
-and set about correcting things from there.  The following has been
-<em>adapted</em> from a life-saving email on the subject from David
-Wood:
-<verb>
-> What the hell do I do now?
-
-OK, don't panic. The first thing you have to realize is that
-this happens to 50% of users who ever do anything with PAM.
-It happened here, not once, not twice, but three times, all
-different, and in the end, the solution was the same every
-time.
-
-First, I hope you installed LILO with a delay. If you can,
-reboot, hit shift or tab or something and type:
-
-    LILO boot: linux single
-
-(Replace 'linux' with 'name-of-your-normal-linux-image').
-This will let you in without logging in.  Ever wondered how
-easy it is to break into a linux machine from the console?
-Now you know.
-
-If you can't do that, then get yourself a bootkernel floppy
-and a root disk a-la slackware's rescue.gz.  (Red Hat's
-installation disks can be used in this mode too.)
-
-In either case, the point is to get back your root prompt.
-
-Second, I'm going to assume that you haven't completely
-nuked your pam installation - just your configuration files.
-Here's how you make your configs nice again:
-
-    cd /etc
-    mv pam.conf pam.conf.orig
-    mv pam.d pam.d.orig
-    mkdir pam.d
-    cd pam.d
-
-and then use vi to create a file called "other" in this
-directory.  It should contain the following four lines:
-
-    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
-magically start to work again.  Try it out by hitting ALT-F2
-and logging in on another virtual console.  If it doesn't
-work, you have bigger problems, or you've mistyped
-something.  One of the wonders of this system (seriously,
-perhaps) is that if you mistype anything in the conf files,
-you usually get no error reporting of any kind on the
-console - just some entries in the log file.  So look there!
-(Try 'tail /var/log/messages'.)
-
-From here you can go back and get a real configuration
-going, hopefully after you've tested it first on a machine
-you don't care about screwing up.  :/
-
-Some pointers (to make everything "right" with Red Hat...):
-
-    Install the newest pam, pamconfig, and pwdb from the
-    redhat current directory, and do it all on the same
-    command line with rpm...
-
-        rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-*
-
-    Then make sure you install (or reinstall) the newest
-    version of libc, util-linux, wuftp, and NetKit. For
-    kicks you might try installing the newest versions of
-    the affected x apps, like xlock, but I haven't gotten
-    those to work at all yet.
-
-</verb>
-
-<sect1>Avoid having a weak `other' configuration
-
-<p>
-It is not a good thing to have a weak default (<tt/OTHER/) entry.
-This service is the default configuration for all PAM aware
-applications and if it is weak, your system is likely to be vulnerable
-to attack.
-
-<p>
-Here is a sample "other" configuration file. The <em/pam_deny/ module will
-deny access and the <em/pam_warn/ module will send a syslog message to
-<tt/auth.notice/:
-
-<p>
-<tscreen>
-<verb>
-#
-# The PAM configuration file for the `other' service 
-# 
-auth      required   pam_deny.so 
-auth      required   pam_warn.so 
-account   required   pam_deny.so 
-account   required   pam_warn.so 
-password  required   pam_deny.so 
-password  required   pam_warn.so 
-session   required   pam_deny.so 
-session   required   pam_warn.so
-</verb>
-</tscreen>
-
-<sect>A reference guide for available modules
-
-<p>
-Here, we collect together some descriptions of the various modules
-available for <bf/Linux-PAM/.  In general these modules should be
-freely available.  Where this is not the case, it will be indicated.
-
-<p>
-Also please note the comments contained in the section <ref 
-id="text-conventions" name="on text conventions above"> when copying
-the examples listed below.
-
-<!-- insert-file MODULES-SGML -->
-
-<sect>Files
-
-<p><descrip>
-
-<tag><tt>/lib/libpam.so.*</tt></tag>
-
-the shared library providing applications with access to
-<bf/Linux-PAM/.
-
-<tag><tt>/etc/pam.conf</tt></tag>
-
-the <bf/Linux-PAM/ configuration file.
-
-<tag><tt>/lib/security/pam_*.so</tt></tag>
-
-the primary location for <bf/Linux-PAM/ dynamically loadable object
-files; the modules.
-
-</descrip>
-
-<sect>See also<label id="see-also-sec">
-
-<p><itemize>
-
-<item>The <bf/Linux-PAM/ Application Writers' Guide.
-
-<item>The <bf/Linux-PAM/ Module Writers' Guide.
-
-<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
-PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request
-For Comments 86.0, October 1995. See this url:
-<tt><htmlurl
-url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz"
-name="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz"></tt>
-
-</itemize>
-
-<sect>Notes
-
-<p>
-I intend to put development comments here... like ``at the moment
-this isn't actually supported''. At release time what ever is in
-this section will be placed in the Bugs section below! :)
-
-<p>
-Are we going to be able to support the <tt/use_mapped_pass/ module
-argument? Anyone know a cheap (free) good lawyer?!
-
-<p>
-<itemize>
-<item>
-This issue may go away, as Sun have investigated adding a new
-management group for mappings. In this way, libpam would have mapping
-modules that could securely store passwords using strong cryptography
-and in such a way that they need not be distributed with Linux-PAM.
-</itemize>
-
-<sect>Author/acknowledgments
-
-<p>
-This document was written by Andrew G. Morgan (morgan@kernel.org)
-with many contributions from
-<!-- insert-file CREDITS -->
-
-<p>
-Thanks are also due to Sun Microsystems, especially to Vipin Samar and
-Charlie Lai for their advice. At an early stage in the development of
-<bf/Linux-PAM/, Sun graciously made the documentation for their
-implementation of PAM available. This act greatly accelerated the
-development of <bf/Linux-PAM/.
-
-<sect>Bugs/omissions
-
-<p>
-More PAM modules are being developed all the time. It is unlikely that
-this document will ever be truely up to date!
-
-<p>
-This manual is unfinished. Only a partial list of people is credited
-for all the good work they have done.
-
-<sect>Copyright information for this document
-
-<p>
-Copyright (c) Andrew G. Morgan 1996-2002.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@kernel.org&gt;</tt>
-
-<p>
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-<p>
-<itemize>
-
-<item>
-1. Redistributions of source code must retain the above copyright
-   notice, and the entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-<item>
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-<item>
-3. The name of the author may not be used to endorse or promote
-   products derived from this software without specific prior
-   written permission.
-
-</itemize>
-
-<p>
-<bf/Alternatively/, this product may be distributed under the terms of
-the GNU General Public License (GPL), in which case the provisions of
-the GNU GPL are required <bf/instead of/ the above restrictions.
-(This clause is necessary due to a potential bad interaction between
-the GNU GPL and the restrictions contained in a BSD-style copyright.)
-
-<p>
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
-TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
-USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-DAMAGE.
-
-<p>
-<tt>$Id$</tt>
-
-</article>
diff --git a/doc/pdf/.cvsignore b/doc/pdf/.cvsignore
deleted file mode 100644
index a1363379..00000000
--- a/doc/pdf/.cvsignore
+++ /dev/null
@@ -1 +0,0 @@
-*.pdf
diff --git a/doc/pdf/README b/doc/pdf/README
deleted file mode 100644
index 82efcd46..00000000
--- a/doc/pdf/README
+++ /dev/null
@@ -1,3 +0,0 @@
-$Id$
-
-a directory for PDF versions of the documentation
diff --git a/doc/ps/.cvsignore b/doc/ps/.cvsignore
deleted file mode 100644
index fa1d1137..00000000
--- a/doc/ps/.cvsignore
+++ /dev/null
@@ -1 +0,0 @@
-pam*.ps
diff --git a/doc/ps/README b/doc/ps/README
deleted file mode 100644
index 32a833f6..00000000
--- a/doc/ps/README
+++ /dev/null
@@ -1,3 +0,0 @@
-$Id$
-
-this is the directory for the PostScript documentation
diff --git a/doc/specs/.cvsignore b/doc/specs/.cvsignore
deleted file mode 100644
index d564ba7e..00000000
--- a/doc/specs/.cvsignore
+++ /dev/null
@@ -1 +0,0 @@
-draft-morgan-pam-*.txt
diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw
deleted file mode 100644
index 45109f45..00000000
--- a/doc/specs/draft-morgan-pam.raw
+++ /dev/null
@@ -1,764 +0,0 @@
-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 (PAM) ##
-
-#$  Status of this memo
-
-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://www.kernel.org/pub/linux/libs/pam/pre/doc/
-
-As
-
-  Linux-PAM-'version'-docs.tar.gz
-
-It is also contained in the Linux-PAM tar ball.
-
-#$  Abstract
-
-This document is concerned with the definition of a general
-infrastructure for module based authentication.  The infrastructure is
-named Pluggable Authentication Modules (PAM for short).
-
-#$  Introduction
-
-Computers are tools.  They provide services to people and other
-computers (collectively we shall call these _users_ entities).  In
-order to provide convenient, reliable and individual service to
-different entities, it is common for entities to be labelled.  Having
-defined a label as referring to a some specific entity, the label is
-used for the purpose of protecting and allocating data resources.
-
-All modern operating systems have a notion of labelled entities and
-all modern operating systems face a common problem: how to
-authenticate the association of a predefined label with applicant
-entities.
-
-There are as many authentication methods as one might care to count.
-None of them are perfect and none of them are invulnerable.  In
-general, any given authentication method becomes weaker over time.  It
-is common then for new authentication methods to be developed in
-response to newly discovered weaknesses in the old authentication
-methods.
-
-The problem with inventing new authentication methods is the fact that
-old applications do not support them.  This contributes to an inertia
-that discourages the overhaul of weakly protected systems.  Another
-problem is that individuals (people) are frequently powerless to layer
-the protective authentication around their systems.  They are forced
-to rely on single (lowest common denominator) authentication schemes
-even in situations where this is far from appropriate.
-
-PAM, as discussed in this document, is a generalization of the
-approach first introduced in [#$R#{OSF_RFC_PAM}].  In short, it is a
-general framework of interfaces that abstract the process of
-authentication.  With PAM, a service provider can custom protect
-individual services to the level that they deem is appropriate.
-
-PAM has nothing explicit to say about transport layer encryption.
-Within the context of this document encryption and/or compression of
-data exchanges are application specific (strictly between client and
-server) and orthogonal to the process of authentication.
-
-#$  Definitions
-
-Here we pose the authentication problem as one of configuring defined
-interfaces between two entities.
-
-#$$#{players}  Players in the authentication process
-
-PAM reserves the following words to specify unique entities in the
-authentication process:
-
-  applicant
-	the entity (user) initiating an application for service
-	[PAM associates the PAM_RUSER _item_ with this requesting user].
-
-  arbitrator
-	the entity (user) under whose identity the service application
-	is negotiated and with whose authority service is granted.
-
-  user
-	the entity (user) whose identity is being authenticated
-	[PAM associates the PAM_USER _item_ with this identity].
-
-  server
-	the application that provides service, or acts as an
-	authenticated gateway to the requested service.  This
-	application is completely responsible for the server end of
-	the transport layer connecting the server to the client.
-	PAM makes no assumptions about how data is encapsulated for
-	exchanges between the server and the client, only that full
-	octet sequences can be freely exchanged without corruption.
-
-  client
-	application providing the direct/primary interface to
-	applicant.  This application is completely responsible
-	for the client end of the transport layer connecting the
-	server to the client.  PAM makes no assumptions about how data
-	is encapsulated for exchanges between the server and the
-	client, only that full octet sequences can be freely
-	exchanged without corruption.
-
-  module
-	authentication binary that provides server-side support for
-	some (arbitrary) authentication method.
-
-  agent
-	authentication binary that provides client-side support for
-	some (arbitrary) authentication method.
-
-Here is a diagram to help orient the reader:
-
-##               +-------+              +--------+ ##
-##      . . . . .| agent |             .| module | ##
-##      .        +-------+             .+--------+ ##
-##      V            |                 .    |      ##
-##      .            |                 V    |      ##
-## +---------+   +-------+             . +------+  ##
-## |         |   |libpamc|             . |libpam|  ##
-## |         |   +-------+             . +------+  ##
-## |applicant|       |                 .    |      ##
-## |         |   +--------+           +----------+ ##
-## |         |---| client |-----------|  server  | ##
-## +---------+   +--------+           +----------+ ##
-
-Solid lines connecting the boxes represent two-way interaction.  The
-dotted-directed lines indicate an optional connection beteween the
-plugin module (agent) and the server (applicant). In the case of the
-module, this represents the module invoking the 'conversation'
-callback function provided to libpam by the server application when it
-inititializes the libpam library. In the case of the agent, this may
-be some out-of-PAM API interaction (for example directly displaying a
-dialog box under X).
-
-#$$  Defined Data Types
-
-In this draft, we define two composite data types, the text string and
-the binary prompt. They are the data types used to communicate
-authentication requests and responses.
-
-#$$$#{text_string}  text string
-
-The text string is a simple sequence of non-NUL (NUL = 0x00)
-octets. Terminated with a single NUL (0x00) octet. The character set
-employed in the octet sequence may be negotiated out of band, but
-defaults to utf-8.
-
-## --------------------------- ##
-## [  character data  |  NUL ] ##
-## [  octet sequence  | 0x00 ] ##
-## --------------------------- ##
-
-Within the rest of this text, PAM text strings are delimited with a
-pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}.
-
-#$$$#{binary_prompt}  binary prompt
-
-A binary prompt consists of a stream of octets arranged as follows:
-
-## ---------------------------------------- ##
-## [  u32   |   u8    | (length-5 octets) ] ##
-## [ length | control |       data        ] ##
-## ---------------------------------------- ##
-
-That is, a 32-bit unsigned integer in network byte order, a single
-unsigned byte of control information and a sequence of octets of
-length (length-5). The composition of the _data_ is context dependent
-but is generally not a concern for either the server or the client. It
-is very much the concern of modules and agents.
-
-For purposes of interoperability, we define the following control
-characters as legal.
-
-## value    symbol             description           ##
-## ------------------------------------------------- ##
-## 0x01     PAM_BPC_OK       - continuation packet   ##
-## 0x02     PAM_BPC_SELECT   - initialization packet ##
-## 0x03     PAM_BPC_DONE     - termination packet    ##
-## 0x04     PAM_BPC_FAIL     - unable to execute     ##
-
-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 ##
-## 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.
-
-#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts
-
-Binary prompts of control type PAM_BPC_SELECT have a defined
-data part. It is composed of three elements:
-
-	{agent_id;'/';data}
-
-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" 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
-  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.
- 
-The '/' character is a mandatory delimiter, indicating the end of the
-agent_id. The trailing data is of a format specific to the agent with
-the given agent_id.
-
-
-#$$  Special cases
-
-In a previous section (#{players}) we identified the most general
-selection of authentication participants.  In the case of network
-authentication, it is straightforward to ascribe identities to the
-defined participants.  However, there are also special (less general)
-cases that we recognize here.
-
-The primary authentication step, when a user is directly introduced
-into a computer system (log's on to a workstation) is a special case.
-In this situation, the client and the server are generally one
-application.  Before authenticating such a user, the applicant is
-formally unknown: PAM_RUSER is NULL.
-
-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 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
-
-Here, we discuss the information exchange interfaces between the
-players in the authentication process. It should be understood that
-the server side is responsible for driving the authentication of the
-applicant. Notably, every request received by the client from the
-server must be matched with a single response from the client to the
-server.
-
-#$$#{applicant_client}  Applicant <-> client
-
-Once the client is invoked, requests to the applicant entity are
-initiated by the client application.  General clients are able to make
-the following requests directly to an applicant:
-
-   echo text string
-   echo error text string
-   prompt with text string for echo'd text string input
-   prompt with text string for concealed text string input
-
-the nature of the interface provided by the client for the benefit of
-the applicant entity is client specific and not defined by PAM.
-
-#$$#{client_agent}  Client <-> agent
-
-In general, authentication schemes require more modes of exchange than
-the four defined in the previous section (#{applicant_client}).  This
-provides a role for client-loadable agents.  The client and agent
-exchange binary-messages that can have one of the following forms:
-
-   client -> agent
-	binary prompt agent expecting binary prompt reply to client
-
-   agent -> client
-	binary prompt reply from agent to clients binary prompt
-
-Following the acceptance of a binary prompt by the agent, the agent
-may attempt to exchange information with the client before returning
-its binary prompt reply. Permitted exchanges are binary prompts of the
-following types:
-
-   agent -> client
-	set environment variable (A)
-	get environment variable (B)
-	echo text string (C)
-	echo error text string (D)
-	prompt for echo'd text string input (E)
-	prompt for concealed text string input (F)
-
-In response to these prompts, the client must legitimately respond
-with a corresponding binary prompt reply. We list a complete set of
-example exchanges, including each type of legitimate response (passes
-and a single fail):
-
-## Type | Agent request                  | Client response         ##
-## --------------------------------------------------------------- ##
-## (A)  | {13;PAM_BPC_PUTENV;"FOO=BAR"}  | {5;PAM_BPC_OK;}         ##
-##      | {10;PAM_BPC_PUTENV;"FOO="}     | {5;PAM_BPC_OK;}         ##
-##      | {9;PAM_BPC_PUTENV;"FOO"}  (*)  | {5;PAM_BPC_OK;}         ##
-##      | {9;PAM_BPC_PUTENV;"BAR"}  (*)  | {5;PAM_BPC_FAIL;}       ##
-## --------------------------------------------------------------- ##
-## (B)  | {10;PAM_BPC_GETENV;"TERM"}     | {11;PAM_BPC_OK;"vt100"} ##
-##      | {9;PAM_BPC_GETENV;"FOO"}       | {5;PAM_BPC_FAIL;}       ##
-## --------------------------------------------------------------- ##
-## (C)  | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_OK;}         ##
-##      | {12;PAM_BPC_TEXT;"hello!"}     | {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;""}       ##
-##      | {13;PAM_BPC_PROMPT;"login: "}  | {5;PAM_BPC_FAIL;}       ##
-## --------------------------------------------------------------- ##
-## (F)  | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"}    ##
-##      | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""}       ##
-##      | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;}       ##
-
-(*) Used to attempt the removal of a pre-existing environment
-variable.
-
-#$$  Client <-> server
-
-Once the client has established a connection with the server (the
-nature of the transport protocol is not specified by PAM), the server
-is responsible for driving the authentication process.
-
-General servers can request the following from the client:
-
-   (to be forwarded by the client to the applicant)
-	echo text string
-	echo error text string
-	prompt for echo'd text string response
-	prompt for concealed text string response
-
-   (to be forwarded by the client to the appropriate agent)
-	binary prompt for a binary prompt response
-
-Client side agents are required to process binary prompts.  The
-agents' binary prompt responses are returned to the server.
-
-#$$  Server <-> module
-
-Modules drive the authentication process.  The server provides a
-conversation function with which it encapsulates module-generated
-requests and exchanges them with the client. Every message sent by a
-module should be acknowledged.
-
-General conversation functions can support the following five 
-conversation requests:
-
-   echo text string
-   echo error string
-   prompt for echo'd text string response
-   prompt for concealed text string response
-   binary prompt for binary prompt response
-
-The server is responsible for redirecting these requests to the
-client.
-
-#$  C API for application interfaces (client and server)
-
-#$$  Applicant <-> client
-
-No API is defined for this interface.  The interface is considered to
-be specific to the client application.  Example applications include
-terminal login, (X)windows login, machine file transfer applications.
-
-All that is important is that the client application is able to
-present the applicant with textual output and to receive textual
-input from the applicant.  The forms of textual exchange are listed
-in an earlier section (#{applicant_client}).  Other methods of
-data input/output are better suited to being handled via an
-authentication agent.
-
-#$$  Client <-> agent
-
-The client makes use of a general API for communicating with
-agents. The client is not required to communicate directly with
-available agents, instead a layer of abstraction (in the form of a
-library: libpamc) takes care of loading and maintaining communication
-with all requested agents. This layer of abstraction will choose which
-agents to interact with based on the content of binary prompts it
-receives that have the control type PAM_BPC_SELECT.
-
-#$$$  Client <-> libpamc
-
-#$$$$  Compilation information
-
-The C-header file provided for client-agent abstraction is included
-with the following source line:
-
-	\#include <security/pam_client.h>
-
-The library providing the corresponding client-agent abstraction
-functions is, libpamc.
-
-	cc .... -lpamc
-
-#$$$$  Initializing libpamc
-
-The libpamc library is initialized with a call to the following
-function:
-
-	pamc_handle_t pamc_start(void);
-
-This function is responsible for configuring the library and
-registering the location of available agents. The location of the
-available agents on the system is implementation specific.
-
-pamc_start() function returns NULL on failure. Otherwise, the return
-value is a pointer to an opaque data type which provides a handle to
-the libpamc library. On systems where threading is available, the
-libpamc libraray is thread safe provided a single (pamc_handler_t *)
-is used by each thread.
-
-#$$$$  Client (Applicant) selection of agents
-
-For the purpose of applicant and client review of available agents,
-the following function is provided.
-
-	char **pamc_list_agents(pamc_handle_t pch);
-
-This returns a list of pointers to the agent_id's of the agents which
-are available on the system. The list is terminated by a NULL pointer.
-It is the clients responsibility to free this memory area by calling
-free() on each agent id and the block of agent_id pointers in the
-result.
-
-PAM represents a server-driven authentication model, so by default
-any available agent may be invoked in the authentication process.
-
-#$$$$$  Client demands agent
-
-If the client requires that a specific authentication agent is
-satisfied during the authentication process, then the client should
-call the following function, immediately after obtaining a
-pamc_handle_t from pamc_start().
-
-	int pamc_load(pamc_handle_t pch, const char *agent_id);
-
-agent_id is a PAM text string (see section #{agent_ids}) and is not
-suffixed with a '/' delimiter. The return value for this function is:
-
-	PAM_BPC_TRUE    - agent located and loaded.
-	PAM_BPC_FALSE   - agent is not available.
-
-Note, although the agent is loaded, no data is fed to it. The agent's
-opportunity to inform the client that it does not trust the server is
-when the agent is shutdown.
-
-#$$$$$  Client marks agent as unusable
-
-The applicant might prefer that a named agent is marked as not
-available.  To do this, the client would invoke the following function
-immediately after obtaining a pamc_handle_t from pam_start().
-
-	int pamc_disable(pamc_handle_t pch, const char *agent_id);
-
-here agent_id is a PAM text string containing an agent_id (section
-#{agent_ids}).
-
-The return value for this function is:
-
-	PAM_BPC_TRUE    - agent is disabled. This is the response
-	                  independent of whether the agent is locally
-	                  available.
-
-	PAM_BPC_FALSE   - agent cannot be disabled (this may be because
-	                  it has already been invoked).
-
-#$$$$  Allocating and manipulating binary prompts
-
-All conversation between an client and an agent takes place with
-respect to binary prompts. A binary prompt (see section #{binary_prompt}), is
-obtained, resized and deleted via the following C-macro:
-
- CREATION of a binary prompt with control X1 and data length Y1:
-
-	pamc_bp_t prompt = NULL;
-	PAM_BP_RENEW(&prompt, X1, Y1);
-
- REPLACEMENT of a binary prompt with a control X2 and data length Y2:
-
-	PAM_BP_RENEW(&prompt, X2, Y2);
-
- DELETION of a binary prompt (the referenced prompt is scrubbed):
-
-	PAM_BP_RENEW(&prompt, 0, 0);
-
-Note, the PAM_BP_RENEW macro always overwrites any prompt that you
-call it with, deleting and liberating the old contents in a secure
-fashion. Also note that PAM_BP_RENEW, when returning a prompt of data
-size Y1>0, will always append a '\0' byte to the end of the prompt (at
-data offset Y1). It is thus, by definition, acceptable to treat the
-data contents of a binary packet as a text string (see #{text_string}).
-
- FILLING a binary prompt from a memory pointer U1 from offset O1 of
-   length L1:
-
-	PAM_BP_FILL(prompt, O1, L1, U1);
-
- the CONTROL type for the packet can be obtained as follows:
-
-	control = PAM_PB_CONTROL(prompt);
-
- the LENGTH of a data within the prompt (_excluding_ its header
- information) can be obtained as follows:
-
-	length = PAM_BP_LENGTH(prompt);
-
- the total SIZE of the prompt (_including_ its header information)
- can be obtained as follows:
-
-        size = PAM_BP_SIZE(prompt);
-
- EXTRACTING data from a binary prompt from offset O2 of length L2 to
-   a memory pointer U2:
-
-	PAM_BP_EXTRACT(prompt, O2, L2, U2);
-
- If you require direct access to the raw prompt DATA, you should use
- the following macro:
-
-	__u8 *raw_data = PAM_BP_DATA(prompt);
-
-#$$$$  Client<->agent conversations
-
-All exchanges of binary prompts with agents are handled with the
-single function:
-
-	int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p);
-
-The return value for pamc_converse(...) is PAM_BPC_TRUE when there is
-a response packet and PAM_BPC_FALSE when the client is unable to
-handle the request represented by the original prompt. In this latter
-case, *prompt_p is set to NULL.
-
-This function takes a binary prompt and returns a replacement binary
-prompt that is either a request from an agent to be acted upon by the
-client or the 'result' which should be forwarded to the server. In the
-former case, the following macro will return 1 (PAM_BPC_TRUE) and in
-all other cases, 0 (PAM_BPC_FALSE):
-
-	PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt)
-
-Note, all non-NULL binary prompts returned by pamc_converse(...), are
-terminated with a '\0', even when the full length of the prompt (as
-returned by the agent) does not contain this delimiter. This is a
-defined property of the PAM_BP_RENEW macro, and can be relied upon.
-
-Important security note: in certain implementations, agents are
-implemented by executable binaries, which are transparently loaded and
-managed by the PAM client library. To ensure there is never a leakage
-of elevated privilege to an unprivileged agent, the client application
-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
-between a client and a selection of agents, the following function is
-used:
-
-	int pamc_end(pamc_handle_t *pch);
-
-Following a call to pamc_end, the pamc_handle_t will be invalid.
-
-The return value for this function is one of the following:
-
-  	PAM_BPC_TRUE	- all invoked agents are content with
-			  authentication (the server is _not_ judged
-			  _un_trustworthy by any agent)
-
-	PAM_BPC_FALSE	- one or more agents were unsatisfied at
-			  being terminated.  In general, the client
-			  should terminate its connection to the
-			  server and indicate to the applicant that
-			  the server is untrusted.
-
-#$$$ libpamc <-> agents
-
-The agents are manipulated from within libpamc. Each agent is an
-executable in its own right. This permits the agent to have access to
-sensitive data not accessible directly from the client. The mode of
-communication between libpamc and an agent is through a pair of
-pipes. The agent reads binary prompts (section #{binary_prompt})
-through its standard input file descriptor and writes response (to the
-server) binary prompts and instruction binary prompts (instructions
-for the client) through its standard output file descriptor.
-
-#$$ Client <-> server
-
-This interface is concerned with the exchange of text and binary
-prompts between the client application and the server application.  No
-API is provided for this as it is considered specific to the transport
-protocol shared by the client and the server.
-
-#$$ Server <-> modules
-
-The server makes use of a general API for communicating with
-modules. The client is not required to communicate directly with
-available modules. By abstracting the authentication interface, it
-becomes possible for the local administrator to make a run time
-decision about the authentication method adopted by the server.
-
-#$$$ Functions and definitions available to servers and modules
-
-[This section will document the following functions
-
-	pam_set_item()
-	pam_get_item()
-	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
-
-[This section will document the following pam_ calls:
-
-	pam_start
-	pam_end
-	pam_authenticate (*)
-	pam_setcred
-	pam_acct_mgmt
-	pam_open_session
-	pam_close_session
-	pam_chauthtok (*)
-
-The asterisked functions may return PAM_INCOMPLETE. In such cases, the
-application should be aware that the conversation function was called
-and that it returned PAM_CONV_AGAIN to a module. The correct action
-for the application to take in response to receiving PAM_INCOMPLETE,
-is to acquire the replies so that the next time the conversation
-function is called it will be able to provide the desired
-responses. And then recall pam_authenticate (pam_chauthtok) with the
-same arguments. Libpam will arrange that the module stack is resumed
-from the module that returned before. This functionality is required
-for programs whose user interface is maintained by an event loop. ]
-
-#$$$ libpam <-> modules
-
-[This section will document the following pam_ and pam_sm_ calls:
-
-functions provided by libpam
-
-	pam_set_data
-	pam_get_data
-
-functions provided to libpam by each module
-
-  groups:
-	AUTHENTICATION
-		pam_sm_authenticate
-		pam_sm_setcred
-	ACCOUNT
-		pam_sm_acct_mgmt
-	SESSION
-		pam_sm_open_session
-		pam_sm_close_session
-	AUTHENTICATION TOKEN MANAGEMENT
-		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
-infrastructure: everything in this document has implications for
-security.
-
-#$  Contact
-
-The email list for discussing issues related to this document is
-<pam-list@redhat.com>.
-
-#$  References
-
-[#{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@kernel.org
-
-## $Id$ ##
diff --git a/doc/specs/formatter/.cvsignore b/doc/specs/formatter/.cvsignore
deleted file mode 100644
index 8af8c897..00000000
--- a/doc/specs/formatter/.cvsignore
+++ /dev/null
@@ -1,3 +0,0 @@
-lex.yy.c
-parse.tab.c
-padout
diff --git a/doc/specs/formatter/Makefile b/doc/specs/formatter/Makefile
deleted file mode 100644
index d73258d7..00000000
--- a/doc/specs/formatter/Makefile
+++ /dev/null
@@ -1,16 +0,0 @@
-LIBS=-lfl
-
-padout: parse.tab.o
-	$(CC) -o padout parse.tab.o $(LIBS)
-
-parse.tab.o: parse.tab.c lex.yy.c
-	$(CC) -c parse.tab.c
-
-parse.tab.c: parse.y
-	bison parse.y
-
-lex.yy.c: parse.lex
-	flex parse.lex
-
-clean:
-	rm -f parse.tab.o parse.tab.c lex.yy.c padout *~ core
diff --git a/doc/specs/formatter/parse.lex b/doc/specs/formatter/parse.lex
deleted file mode 100644
index 1d5c898e..00000000
--- a/doc/specs/formatter/parse.lex
+++ /dev/null
@@ -1,11 +0,0 @@
-%%
-
-\#[\$]+[a-zA-Z]*(\=[0-9]+)?          return NEW_COUNTER;
-\#\{[a-zA-Z][a-zA-Z0-9\_]*\}         return LABEL;
-\#                                   return NO_INDENT;
-\#\#                                 return RIGHT;
-\\\#                                 return HASH;
-[^\n]                                return CHAR;
-[\n]                                 return NEWLINE;
-
-%%
diff --git a/doc/specs/formatter/parse.y b/doc/specs/formatter/parse.y
deleted file mode 100644
index 6da47d17..00000000
--- a/doc/specs/formatter/parse.y
+++ /dev/null
@@ -1,293 +0,0 @@
-
-%{
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-    
-#define MAXLINE  1000
-#define INDENT_STRING "  "
-#define PAPER_WIDTH   74
-
-    int indent=0;
-    int line=1;
-    char *last_label=NULL;
-
-    extern void yyerror(const char *x);
-    extern char *get_label(const char *label);
-    extern void set_label(const char *label, const char *target);
-    char *new_counter(const char *key);
-
-#include "lex.yy.c"
-
-%}
-
-%union {
-    int def;
-    char *string;
-}
-
-%token NEW_COUNTER LABEL HASH CHAR NEWLINE NO_INDENT RIGHT
-%type <string> stuff text
-
-%start doc
-
-%%
-
-doc:
-| doc NEWLINE {
-    printf("\n");
-    ++line;
-}
-| doc stuff NEWLINE {
-    if (strlen($2) > (PAPER_WIDTH-(indent ? strlen(INDENT_STRING):0))) {
-	yyerror("line too long");
-    }
-    printf("%s%s\n", indent ? INDENT_STRING:"", $2);
-    free($2);
-    indent = 1;
-    ++line;
-}
-| doc stuff RIGHT stuff NEWLINE {
-    char fixed[PAPER_WIDTH+1];
-    int len;
-
-    len = PAPER_WIDTH-(strlen($2)+strlen($4));
-
-    if (len >= 0) {
-	memset(fixed, ' ', len);
-	fixed[len] = '\0';
-    } else {
-	yyerror("line too wide");
-	fixed[0] = '\0';
-    }
-    printf("%s%s%s\n", $2, fixed, $4);
-    free($2);
-    free($4);
-    indent = 1;
-    ++line;
-}
-| doc stuff RIGHT stuff RIGHT stuff NEWLINE {
-    char fixed[PAPER_WIDTH+1];
-    int len, l;
-
-    len = PAPER_WIDTH-(strlen($2)+strlen($4));
-
-    if (len < 0) {
-	len = 0;
-	yyerror("line too wide");
-    }
-
-    l = len/2;
-    memset(fixed, ' ', l);
-    fixed[l] = '\0';
-    printf("%s%s%s", $2, fixed, $4);
-    free($2);
-    free($4);
-    
-    l = (len+1)/2;
-    memset(fixed, ' ', l);
-    fixed[l] = '\0';
-    printf("%s%s\n", fixed, $6);
-    free($6);
-
-    indent = 1;
-    ++line;
-}
-| doc stuff RIGHT stuff RIGHT stuff NEWLINE {
-    char fixed[PAPER_WIDTH+1];
-    int len, l;
-
-    len = PAPER_WIDTH-(strlen($2)+strlen($4));
-
-    if (len < 0) {
-	len = 0;
-	yyerror("line too wide");
-    }
-
-    l = len/2;
-    memset(fixed, ' ', l);
-    fixed[l] = '\0';
-    printf("%s%s%s", $2, fixed, $4);
-    free($2);
-    free($4);
-    
-    l = (len+1)/2;
-    memset(fixed, ' ', l);
-    fixed[l] = '\0';
-    printf("%s%s\n", fixed, $6);
-    free($6);
-
-    indent = 1;
-    ++line;
-}
-;
-
-stuff: {
-    $$ = strdup("");
-}
-| stuff text {
-    $$ = malloc(strlen($1)+strlen($2)+1);
-    sprintf($$,"%s%s", $1, $2);
-    free($1);
-    free($2);
-}
-;
-
-text: CHAR {
-    $$ = strdup(yytext);
-}
-| text CHAR {
-    $$ = malloc(strlen($1)+2);
-    sprintf($$,"%s%s", $1, yytext);
-    free($1);
-}
-| NO_INDENT {
-    $$ = strdup("");
-    indent = 0;
-}
-| HASH {
-    $$ = strdup("#");
-}
-| LABEL {
-    if (($$ = get_label(yytext)) == NULL) {
-	set_label(yytext, last_label);
-	$$ = strdup("");
-    }
-}
-| NEW_COUNTER {
-    $$ = new_counter(yytext);
-}
-;
-
-%%
-
-typedef struct node_s {
-    struct node_s *left, *right;
-    const char *key;
-    char *value;
-} *node_t;
-
-node_t label_root = NULL;
-node_t counter_root = NULL;
-
-const char *find_key(node_t root, const char *key)
-{
-    while (root) {
-	int cmp = strcmp(key, root->key);
-
-	if (cmp > 0) {
-	    root = root->right;
-	} else if (cmp) {
-	    root = root->left;
-	} else {
-	    return root->value;
-	}
-    }
-    return NULL;
-}
-
-node_t set_key(node_t root, const char *key, const char *value)
-{
-    if (root) {
-	int cmp = strcmp(key, root->key);
-	if (cmp > 0) {
-	    root->right = set_key(root->right, key, value);
-	} else if (cmp) {
-	    root->left = set_key(root->left, key, value);
-	} else {
-	    free(root->value);
-	    root->value = strdup(value);
-	}
-    } else {
-	root = malloc(sizeof(struct node_s));
-	root->right = root->left = NULL;
-	root->key = strdup(key);
-	root->value = strdup(value);
-    }
-    return root;
-}
-
-void yyerror(const char *x)
-{
-    fprintf(stderr, "line %d: %s\n", line, x);
-}
-
-char *get_label(const char *label)
-{
-    const char *found = find_key(label_root, label);
-
-    if (found) {
-	return strdup(found);
-    }
-    return NULL;
-}
-
-void set_label(const char *label, const char *target)
-{
-    if (target == NULL) {
-	yyerror("no hanging value for label");
-	target = "<??>";
-    }
-    label_root = set_key(label_root, label, target);
-}
-
-char *new_counter(const char *key)
-{
-    int i=0, j, ndollars = 0;
-    const char *old;
-    char *new;
-
-    if (key[i++] != '#') {
-	yyerror("bad index");
-	return strdup("<???>");
-    }
-
-    while (key[i] == '$') {
-	++ndollars;
-	++i;
-    }
-
-    key += i;
-    old = find_key(counter_root, key);
-    new = malloc(20*ndollars);
-
-    if (old) {
-	for (j=0; ndollars > 1 && old[j]; ) {
-	    if (old[j++] == '.' && --ndollars <= 0) {
-		break;
-	    }
-	}
-	if (j) {
-	    strncpy(new, old, j);
-	}
-	if (old[j]) {
-	    i = atoi(old+j);
-	} else {
-	    new[j++] = '.';
-	    i = 0;
-	}
-    } else {
-	j=0;
-	while (--ndollars > 0) {
-	    new[j++] = '0';
-	    new[j++] = '.';
-	}
-	i = 0;
-    }
-    new[j] = '\0';
-    sprintf(new+j, "%d", ++i);
-
-    counter_root = set_key(counter_root, key, new);
-    
-    if (last_label) {
-	free(last_label);
-    }
-    last_label = strdup(new);
-
-    return new;
-}
-
-main()
-{
-    yyparse();
-}
diff --git a/doc/specs/rfc86.0.txt b/doc/specs/rfc86.0.txt
deleted file mode 100644
index 6dd5e6ea..00000000
--- a/doc/specs/rfc86.0.txt
+++ /dev/null
@@ -1,1851 +0,0 @@
-
-
-
-
-
-
-
-
-   Open Software Foundation                              V. Samar (SunSoft)
-   Request For Comments: 86.0                         R. Schemers (SunSoft)
-   October 1995
-
-
-
-                              UNIFIED LOGIN WITH
-                    PLUGGABLE AUTHENTICATION MODULES (PAM)
-
-
-   1. INTRODUCTION
-
-      Since low-level authentication mechanisms constantly evolve, it is
-      important to shield the high-level consumers of these mechanisms
-      (system-entry services and users) from such low-level changes.  With
-      the Pluggable Authentication Module (PAM) framework, we can provide
-      pluggability for a variety of system-entry services -- not just
-      system authentication _per se_, but also for account, session and
-      password management.  PAM's ability to _stack_ authentication modules
-      can be used to integrate `login' with different authentication
-      mechanisms such as RSA, DCE, and Kerberos, and thus unify login
-      mechanisms.  The PAM framework can also provide easy integration of
-      smart cards into the system.
-
-      Modular design and pluggability have become important for users who
-      want ease of use.  In the PC hardware arena, no one wants to set the
-      interrupt vector numbers or resolve the addressing conflict between
-      various devices.  In the software arena, people also want to be able
-      to replace components easily for easy customization, maintenance, and
-      upgrades.
-
-      Authentication software deserves special attention because
-      authentication forms a very critical component of any secure computer
-      system.  The authentication infrastructure and its components may
-      have to be modified or replaced either because some deficiencies have
-      been found in the current algorithms, or because sites want to
-      enforce a different security policy than what was provided by the
-      system vendor.  The replacement and modification should be done in
-      such a way that the user is not affected by these changes.
-
-      The solution has to address not just how the applications use the new
-      authentication mechanisms in a generic fashion, but also how the user
-      will be authenticated to these mechanisms in a generic way.  The
-      former is addressed by GSS-API [Linn 93], while this RFC addresses
-      the later; these two efforts are complementary to each other.
-
-      Since most system-entry services (for example, `login', `dtlogin',
-      `rlogin', `ftp', `rsh') may want to be independent of the specific
-      authentication mechanisms used by the machine, it is important that
-      there be a framework for _plugging_ in various mechanisms.  This
-      requires that the system applications use a standard API to interact
-
-
-
-   Samar, Schemers                                                   Page 1
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      with the authentication services.  If these system-entry services
-      remain independent of the actual mechanism used on that machine, the
-      system administrator can install suitable authentication modules
-      without requiring changes to these applications.
-
-      For any security system to be successful, it has to be easy to use.
-      In the case of authentication, the single most important ease-of-use
-      characteristic is that the user should not be required to learn about
-      various ways of authentication and remember multiple passwords.
-      Ideally, there should be one all-encompassing authentication system
-      where there is only one password, but for heterogeneous sites,
-      multiple authentication mechanisms have to co-exist.  The problem of
-      integrating multiple authentication mechanisms such as Kerberos
-      [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor
-      88], is also referred to as _integrated login_, or _unified login_
-      problem.  Even if the user has to use multiple authentication
-      mechanisms, the user should not be forced to type multiple passwords.
-      Furthermore, the user should be able to use the new network identity
-      without taking any further actions.  The key here is in modular
-      integration of the network authentication technologies with `login'
-      and other system-entry services.
-
-      In this RFC we discuss the architecture and design of pluggable
-      authentication modules.  This design gives the capability to use
-      field-replaceable authentication modules along with unified login
-      capability.  It thus provides for both _pluggability_ and _ease-of-
-      use_.
-
-      The RFC is organized as follows.  We first motivate the need for a
-      generic way to authenticate the user by various system-entry services
-      within the operating system.  We describe the goals and constraints
-      of the design.  This leads to the architecture, description of the
-      interfaces, and _stacking_ of modules to get unified login
-      functionality.  We then describe our experience with the design, and
-      end with a description of future work.
-
-
-   2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS
-
-      An identification and authentication ("I&A") mechanism is used to
-      establish a user's identity the system (i.e., to a local machine's
-      operating system) and to other principals on the network.  On a
-      typical UNIX system, there are various ports of entry into the
-      system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and
-      `telnet'.  In all cases, the user has to be identified and
-      authenticated before granting appropriate access rights to the user.
-      The user identification and authentication for all these entry points
-      needs to be coordinated to ensure a secure system.
-
-      In most of the current UNIX systems, the login mechanism is based
-      upon verification of the password using the modified DES algorithm.
-
-
-
-   Samar, Schemers                                                   Page 2
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      The security of the implementation assumes that the password cannot
-      be guessed, and that the password does not go over the wire in the
-      clear.  These assumptions, however, are not universally valid.
-      Various programs are now available freely on the Internet that can
-      run dictionary attack against the encrypted password.  Further, some
-      of the network services (for example, `rlogin', `ftp', `telnet') send
-      the password over in clear, and there are "sniffer" programs freely
-      available to steal these passwords.  The classical assumptions may be
-      acceptable on a trusted network, but in an open environment there is
-      a need to use more restrictive and stronger authentication
-      mechanisms.  Examples of such mechanisms include Kerberos, RSA,
-      Diffie-Hellman, one-time password [Skey 94], and challenge-response
-      based smart card authentication systems.  Since this list will
-      continue to evolve, it is important that the system-entry services do
-      not have hard-coded dependencies on any of these authentication
-      mechanisms.
-
-
-   3. DESIGN GOALS
-
-      The goals of the PAM framework are as follows:
-
-        (a) The system administrator should be able to choose the default
-            authentication mechanism for the machine.  This can range from
-            a simple password-based mechanism to a biometric or a smart
-            card based system.
-
-        (b) It should be possible to configure the user authentication
-            mechanism on a per application basis.  For example, a site may
-            require S/Key password authentication for `telnet' access,
-            while allowing machine `login' sessions with just UNIX password
-            authentication.
-
-        (c) The framework should support the display requirements of the
-            applications.  For example, for a graphical login session such
-            as `dtlogin', the user name and the password may have to be
-            entered in a new window.  For networking system-entry
-            applications such as `ftp' and `telnet', the user name and
-            password has to be transmitted over the network to the client
-            machine.
-
-        (d) It should be possible to configure multiple authentication
-            protocols for each of those applications.  For example, one may
-            want the users to get authenticated by both Kerberos and RSA
-            authentication systems.
-
-        (e) The system administrator should be able to _stack_ multiple
-            user authentication mechanisms such that the user is
-            authenticated with all authentication protocols without
-            retyping the password.
-
-
-
-
-   Samar, Schemers                                                   Page 3
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-        (f) The architecture should allow for multiple passwords if
-            necessary to achieve higher security for users with specific
-            security requirements.
-
-        (g) The system-entry services should not be required to change when
-            the underlying mechanism changes.  This can be very useful for
-            third-party developers because they often do not have the
-            source code for these services.
-
-        (h) The architecture should provide for a _pluggable_ model for
-            system authentication, as well as for other related tasks such
-            as password, account, and session management.
-
-        (i) For backward-compatibility reasons, the PAM API should support
-            the authentication requirements of the current system-entry
-            services.
-
-      There are certain issues that the PAM framework does not specifically
-      address:
-
-        (a) We focus only on providing a generic scheme through which users
-            use passwords to establish their identities to the machine.
-            Once the identity is established, how the identity is
-            communicated to other interested parties is outside the scope
-            of this design.  There are efforts underway at IETF [Linn 93]
-            to develop a Generic Security Services Application Interface
-            (GSSAPI) that can be used by applications for secure and
-            authenticated communication without knowing the underlying
-            mechanism.
-
-        (b) The _single-signon_ problem of securely transferring the
-            identity of the caller to a remote site is not addressed.  For
-            example, the problem of delegating credentials from the
-            `rlogin' client to the other machine without typing the
-            password is not addressed by our work.  We also do not address
-            the problem of sending the passwords over the network in the
-            clear.
-
-        (c) We do not address the source of information obtained from the
-            "`getXbyY()'" family of calls (e.g., `getpwnam()').  Different
-            operating systems address this problem differently.  For
-            example, Solaris uses the name service switch (NSS) to
-            determine the source of information for the "`getXbyY()'"
-            calls.  It is expected that data which is stored in multiple
-            sources (such as passwd entries in NIS+ and the DCE registry)
-            is kept in sync using the appropriate commands (such as
-            `passwd_export').
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 4
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   4. OVERVIEW OF THE PAM FRAMEWORK
-
-      We propose that the goals listed above can be met through a framework
-      in which authentication modules can be _plugged_ independently of the
-      application.  We call this the _Pluggable Authentication Modules_
-      (PAM) framework.
-
-      The core components of the PAM framework are the authentication
-      library API (the front end) and the authentication mechanism-specific
-      modules (the back end), connected through the Service Provider
-      Interface (SPI).  Applications write to the PAM API, while the
-      authentication-system providers write to the PAM SPI and supply the
-      back end modules that are independent of the application.
-
-             ftp     telnet   login   (Applications)
-              |        |        |
-              |        |        |
-              +--------+--------+
-                       |
-                 +-----+-----+
-                 |  PAM API  |   <-- pam.conf file
-                 +-----+-----+
-                       |
-              +--------+--------+
-            UNIX   Kerberos  Smart Cards   (Mechanisms)
-
-               Figure 1: The Basic PAM Architecture
-
-      Figure 1 illustrates the relationship between the application, the
-      PAM library, and the authentication modules.  Three applications
-      (`login', `telnet' and `ftp') are shown which use the PAM
-      authentication interfaces.  When an application makes a call to the
-      PAM API, it loads the appropriate authentication module as determined
-      by the configuration file, `pam.conf'.  The request is forwarded to
-      the underlying authentication module (for example, UNIX password,
-      Kerberos, smart cards) to perform the specified operation.  The PAM
-      layer then returns the response from the authentication module to the
-      application.
-
-      PAM unifies system authentication and access control for the system,
-      and allows plugging of associated authentication modules through well
-      defined interfaces.  The plugging can be defined through various
-      means, one of which uses a configuration file, such as the one in
-      Table 1.  For each of the system applications, the file specifies the
-      authentication module that should be loaded.  In the example below,
-      `login' uses the UNIX password module, while `ftp' and `telnet' use
-      the S/Key module.
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 5
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            Table 1: A Simplified View of a Sample PAM Configuration File.
-
-                               service    module_path
-                               -------    -----------
-                               login      pam_unix.so
-                               ftp        pam_skey.so
-                               telnet     pam_skey.so
-
-      Authentication configuration is only one aspect of this interface.
-      Other critical components include account management, session
-      management, and password management.  For example, the `login'
-      program may want to verify not only the password but also whether the
-      account has aged or expired.  Generic interfaces also need to be
-      provided so that the password can be changed according to the
-      requirements of the module.  Furthermore, the application may want to
-      log information about the current session as determined by the
-      module.
-
-      Not all applications or services may need all of the above
-      components, and not each authentication module may need to provide
-      support for all of the interfaces.  For example, while `login' may
-      need access to all four components, `su' may need access to just the
-      authentication component.  Some applications may use some specific
-      authentication and password management modules but share the account
-      and session management modules with others.
-
-      This reasoning leads to a partitioning of the entire set of
-      interfaces into four areas of functionality: (1) authentication, (2)
-      account, (3) session, and (4) password.  The concept of PAM was
-      extended to these functional areas by implementing each of them as a
-      separate pluggable module.
-
-      Breaking the functionality into four modules helps the module
-      providers because they can use the system-provided libraries for the
-      modules that they are not changing.  For example, if a supplier wants
-      to provide a better version of Kerberos, they can just provide that
-      new authentication and password module, and reuse the existing ones
-      for account and session.
-
-   4.1. Module Description
-
-      More details on specific API's are described in Appendix A.  A brief
-      description of four modules follows:
-
-        (a) Authentication management: This set includes the
-            `pam_authenticate()' function to authenticate the user, and the
-            `pam_setcred()' interface to set, refresh or destroy the user
-            credentials.
-
-        (b) Account management: This set includes the `pam_acct_mgmt()'
-            function to check whether the authenticated user should be
-
-
-
-   Samar, Schemers                                                   Page 6
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            given access to his/her account.  This function can implement
-            account expiration and access hour restrictions.
-
-        (c) Session management: This set includes the `pam_open_session()'
-            and `pam_close_session()' functions for session management and
-            accounting.  For example, the system may want to store the
-            total time for the session.
-
-        (d) Password management: This set includes a function,
-            `pam_chauthtok()', to change the password.
-
-
-   5. FRAMEWORK INTERFACES
-
-      The PAM framework further provides a set of administrative interfaces
-      to support the above modules and to provide for application-module
-      communication.  There is no corresponding service provider interface
-      (SPI) for such functions.
-
-   5.1. Administrative Interfaces
-
-      Each set of PAM transactions starts with `pam_start()' and ends with
-      the `pam_end()' function.  The interfaces `pam_get_item()' and
-      `pam_set_item()' are used to read and write the state information
-      associated with the PAM transaction.
-
-      If there is any error with any of the PAM interfaces, the error
-      message can be printed with `pam_strerror()'.
-
-   5.2. Application-Module Communication
-
-      During application initialization, certain data such as the user name
-      is saved in the PAM framework layer through `pam_start()' so that it
-      can be used by the underlying modules.  The application can also pass
-      opaque data to the module which the modules will pass back while
-      communicating with the user.
-
-   5.3. User-Module Communication
-
-      The `pam_start()' function also passes conversation function that has
-      to be used by the underlying modules to read and write module
-      specific authentication information.  For example, these functions
-      can be used to prompt the user for the password in a way determined
-      by the application.  PAM can thus be used by graphical, non-
-      graphical, or networked applications.
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 7
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   5.4. Inter-Module Communication
-
-      Though the modules are independent, they can share certain common
-      information about the authentication session such as user name,
-      service name, password, and conversation function through the
-      `pam_get_item()' and `pam_set_item()' interfaces.  These API's can
-      also be used by the application to change the state information after
-      having called `pam_start()' once.
-
-   5.5. Module State Information
-
-      The PAM service modules may want to keep certain module-specific
-      state information about the session.  The interfaces `pam_get_data()'
-      and `pam_set_data()' can be used by the service modules to access and
-      update module-specific information as needed from the PAM handle.
-      The modules can also attach a cleanup function with the data.  The
-      cleanup function is executed when `pam_end()' is called to indicate
-      the end of the current authentication activity.
-
-      Since the PAM modules are loaded upon demand, there is no direct
-      module initialization support in the PAM framework.  If there are
-      certain initialization tasks that the PAM service modules have to do,
-      they should be done upon the first invocation.  However, if there are
-      certain clean-up tasks to be done when the authentication session
-      ends, the modules should use `pam_set_data()' to specify the clean-up
-      functions, which would be called when `pam_end()' is called by the
-      application.
-
-
-   6. MODULE CONFIGURATION MANAGEMENT
-
-      Table 2 shows an example of a configuration file `pam.conf' with
-      support for authentication, session, account, and password management
-      modules.  `login' has three entries: one each for authentication
-      processing, session management and account management.  Each entry
-      specifies the module name that should be loaded for the given module
-      type.  In this example, the `ftp' service uses the authentication and
-      session modules.  Note that all services here share the same session
-      management module, while having different authentication modules.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 8
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            Table 2: Configuration File (pam.conf) with Different Modules
-                     and Control Flow
-
-            service module_type control_flag module_path         options
-            ------- ----------- ------------ -----------         -------
-            login   auth        required     pam_unix_auth.so    nowarn
-            login   session     required     pam_unix_session.so
-            login   account     required     pam_unix_account.so
-            ftp     auth        required     pam_skey_auth.so    debug
-            ftp     session     required     pam_unix_session.so
-            telnet  session     required     pam_unix_session.so
-            login   password    required     pam_unix_passwd.so
-            passwd  password    required     pam_unix_passwd.so
-            OTHER   auth        required     pam_unix_auth.so
-            OTHER   session     required     pam_unix_session.so
-            OTHER   account     required     pam_unix_account.so
-
-      The first field, _service_, denotes the service (for example,
-      `login', `passwd', `rlogin').  The name `OTHER' indicates the module
-      used by all other applications that have not been specified in this
-      file.  This name can also be used if all services have the same
-      requirements.  In the example, since all the services use the same
-      session module, we could have replaced those lines with a single
-      `OTHER' line.
-
-      The second field, _module_type_, indicates the type of the PAM
-      functional module.  It can be one of `auth', `account', `session', or
-      `password' modules.
-
-      The third field, _control_flag_ determines the behavior of stacking
-      multiple modules by specifying whether any particular module is
-      _required_, _sufficient_, or _optional_.  The next section describes
-      stacking in more detail.
-
-      The fourth field, _module_path_, specifies the location of the
-      module.  The PAM framework loads this module upon demand to invoke
-      the required function.
-
-      The fifth field, _options_, is used by the PAM framework layer to
-      pass module specific options to the modules.  It is up to the module
-      to parse and interpret the options.  This field can be used by the
-      modules to turn on debugging or to pass any module specific
-      parameters such as a timeout value.  It is also used to support
-      unified login as described below.  The options field can be used by
-      the system administrator to fine-tune the PAM modules.
-
-      If any of the fields are invalid, or if a module is not found, that
-      line is ignored and the error is logged as a critical error via
-      `syslog(3)'.  If no entries are found for the given module type, then
-      the PAM framework returns an error to the application.
-
-
-
-
-   Samar, Schemers                                                   Page 9
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING
-
-      In the world of heterogeneous systems, the system administrator often
-      has to deal with the problem of integrating multiple authentication
-      mechanisms.  The user is often required to know about the
-      authentication command of the new authentication module (for example,
-      `kinit', `dce_login') after logging into the system.  This is not
-      user-friendly because it forces people to remember to type the new
-      command and enter the new password.  This functionality should be
-      invisible instead of burdening the user with it.
-
-      There are two problems to be addressed here:
-
-        (a) Supporting multiple authentication mechanisms.
-
-        (b) Providing unified login in the presence of multiple mechanisms.
-
-      In the previous section, we described how one could replace the
-      default authentication module with any other module of choice.  Now
-      we demonstrate how the same model can be extended to provide support
-      for multiple modules.
-
-   7.1. Design for Stacked Modules
-
-      One possibility was to provide hard-coded rules in `login' or other
-      applications requiring authentication services [Adamson 95].  But
-      this becomes very specific to the particular combination of
-      authentication protocols, and also requires the source code of the
-      application.  Digital's Security Integration Architecture [SIA 95]
-      addresses this problem by specifying the same list of authentication
-      modules for all applications.  Since requirements for various
-      applications can vary, it is essential that the configuration be on a
-      per-application basis.
-
-      To support multiple authentication mechanisms, the PAM framework was
-      extended to support _stacking_.  When any API is called, the back
-      ends for the stacked modules are invoked in the order listed, and the
-      result returned to the caller.  In Figure 2, the authentication
-      service of `login' is stacked and the user is authenticated by UNIX,
-      Kerberos, and RSA authentication mechanisms.  Note that in this
-      example, there is no stacking for session or account management
-      modules.
-
-
-
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                  Page 10
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-                             login
-                               |
-                      +--------+--------+
-                      |        |        |
-                   session   auth    account
-                      |        |        |
-                   +--+--+  +--+--+  +--+--+
-                   | PAM |  | PAM |  | PAM |
-                   +--+--+  +--+--+  +--+--+
-                      |        |        |
-                    UNIX     UNIX     UNIX
-                   session   auth    account
-                               |
-                            Kerberos
-                              auth
-                               |
-                              RSA
-                              auth
-
-            Figure 2: Stacking With the PAM Architecture
-
-      Stacking is specified through additional entries in the configuration
-      file shown earlier.  As shown in Table 2, for each application (such
-      as `login') the configuration file can specify multiple mechanisms
-      that have to be invoked in the specified order.  When mechanisms
-      fail, the _control_flag_ decides which error should be returned to
-      the application.  Since the user should not know which authentication
-      module failed when a bad password was typed, the PAM framework
-      continues to call other authentication modules on the stack even on
-      failure.  The semantics of the control flag are as follows:
-
-        (a) `required': With this flag, the module failure results in the
-            PAM framework returning the error to the caller _after_
-            executing all other modules on the stack.  For the function to
-            be able to return success to the application all `required'
-            modules have to report success.  This flag is normally set when
-            authentication by this module is a _must_.
-
-        (b) `optional': With this flag, the PAM framework ignores the
-            module failure and continues with the processing of the next
-            module in sequence.  This flag is used when the user is allowed
-            to login even if that particular module has failed.
-
-        (c) `sufficient': With this flag, if the module succeeds the PAM
-            framework returns success to the application immediately
-            without trying any other modules.  For failure cases, the
-            _sufficient_ modules are treated as `optional'.
-
-      Table 3 shows a sample configuration file that stacks the `login'
-      command.  Here the user is authenticated by UNIX, Kerberos, and RSA
-      authentication services.  The `required' key word for _control_flag_
-
-
-
-   Samar, Schemers                                                  Page 11
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      enforces that the user is allowed to login only if he/she is
-      authenticated by _both_ UNIX and Kerberos services.  RSA
-      authentication is optional by virtue of the `optional' key word in
-      the _control_flag_ field.  The user can still log in even if RSA
-      authentication fails.
-
-              Table 3: PAM Configuration File with Support for Stacking
-
-            service module_type control_flag module_path options
-            ------- ----------- ------------ ----------- -------
-            login   auth        required     pam_unix.so debug
-            login   auth        required     pam_kerb.so use_mapped_pass
-            login   auth        optional     pam_rsa.so  use_first_pass
-
-      Table 4 illustrates the use of the sufficient flag for the `rlogin'
-      service.  The Berkeley `rlogin' protocol specifies that if the remote
-      host is trusted (as specified in the `/etc/hosts.equiv' file or in
-      the `.rhosts' file in the home directory of the user), then the
-      `rlogin' daemon should not require the user to type the password.  If
-      this is not the case, then the user is required to type the password.
-      Instead of hard coding this policy in the `rlogin' daemon, this can
-      be expressed with the `pam.conf' file in Table 4.  The PAM module
-      `pam_rhosts_auth.so.1' implements the `.rhosts' policy described
-      above.  If a site administrator wants to enable remote login with
-      only passwords, then the first line should be deleted.
-
-            Table 4: PAM Configuration File for the rlogin service
-
-            service module_type control_flag module_path        options
-            ------- ----------- ------------ -----------        -------
-            rlogin  auth        sufficient   pam_rhosts_auth.so
-            rlogin  auth        required     pam_unix.so
-
-   7.2. Password-Mapping
-
-      Multiple authentication mechanisms on a machine can lead to multiple
-      passwords that users have to remember.  One attractive solution from
-      the ease-of-use viewpoint is to use the same password for all
-      mechanisms.  This, however, can also weaken the security because if
-      that password were to be compromised in any of the multiple
-      mechanisms, all mechanisms would be compromised at the same time.
-      Furthermore, different authentication mechanisms may have their own
-      distinctive password requirements in regards to its length, allowed
-      characters, time interval between updates, aging, locking, and so
-      forth.  These requirements make it problematic to use the same
-      password for multiple authentication mechanisms.
-
-      The solution we propose, while not precluding use of the same
-      password for every mechanism, allows for a different password for
-      each mechanism through what we call _password-mapping_.  This
-      basically means using the user's _primary_ password to encrypt the
-
-
-
-   Samar, Schemers                                                  Page 12
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      user's other (_secondary_) passwords, and storing these encrypted
-      passwords in a place where they are available to the user.  Once the
-      primary password is verified, the authentication modules would obtain
-      the other passwords for their own mechanisms by decrypting the
-      mechanism-specific encrypted password with the primary password, and
-      passing it to the authentication service.  The security of this
-      design for password-mapping assumes that the primary password is the
-      user's strongest password, in terms of its unguessability (length,
-      type and mix of characters used, etc.).
-
-      If there is any error in password-mapping, or if the mapping does not
-      exist, the user will be prompted for the password by each
-      authentication module.
-
-      To support password-mapping, the PAM framework saves the primary
-      password and provides it to stacked authentication modules.  The
-      password is cleared out before the `pam_authenticate' function
-      returns.
-
-      How the password is encrypted depends completely on the module
-      implementation.  The encrypted secondary password (also called a
-      "mapped password") can be stored in a trusted or untrusted place,
-      such as a smart card, a local file, or a directory service.  If the
-      encrypted passwords are stored in an untrusted publicly accessible
-      place, this does provide an intruder with opportunities for potential
-      dictionary attack.
-
-      Though password-mapping is voluntary, it is recommended that all
-      module providers add support for the following four mapping options:
-
-        (a) `use_first_pass': Use the same password used by the first
-            mechanism that asked for a password.  The module should not ask
-            for the password if the user cannot be authenticated by the
-            first password.  This option is normally used when the system
-            administrator wants to enforce the same password across
-            multiple modules.
-
-        (b) `try_first_pass': This is the same as `use_first_pass', except
-            that if the primary password is not valid, it should prompt the
-            user for the password.
-
-        (c) `use_mapped_pass': Use the password-mapping scheme to get the
-            actual password for this module.  One possible implementation
-            is to get the mapped-password using the XFN API [XFN 94], and
-            decrypt it with the primary password to get the module-specific
-            password.  The module should not ask for the password if the
-            user cannot be authenticated by the first password.  The XFN
-            API allows user-defined attributes (such as _mapped-password_)
-            to be stored in the _user-context_.  Using the XFN API is
-            particularly attractive because support for the XFN may be
-            found on many systems in the future.
-
-
-
-   Samar, Schemers                                                  Page 13
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-        (d) `try_mapped_pass': This is the same as `use_mapped_pass',
-            except that if the primary password is not valid, it should
-            prompt the user for the password.
-
-      When passwords get updated, the PAM framework stores both the old as
-      well as the new password to be able to inform other dependent
-      authentication modules about the change.  Other modules can use this
-      information to update the encrypted password without forcing the user
-      to type the sequence of passwords again.  The PAM framework clears
-      out the passwords before returning to the application.
-
-      Table 3 illustrates how the same password can be used by `login' for
-      authenticating to the standard UNIX login, Kerberos and RSA services.
-      Once the user has been authenticated to the primary authentication
-      service (UNIX `login' in this example) with the primary password, the
-      option `use_mapped_pass' indicates to the Kerberos module that it
-      should use the primary password to decrypt the stored Kerberos
-      password and then use the Kerberos password to get the ticket for the
-      ticket-granting-service.  After that succeeds, the option
-      `use_first_pass' indicates to the RSA module that instead of
-      prompting the user for a password, it should use the primary password
-      typed earlier for authenticating the user.  Note that in this
-      scenario, the user has to enter the password just once.
-
-      Note that if a one-time password scheme (e.g., S/Key) is used,
-      password mapping cannot apply.
-
-   7.3. Implications of Stacking on the PAM Design
-
-      Because of the stacking capability of PAM, we have designed the PAM
-      API's to not return any data to the application, except status.  If
-      this were not the case, it would be difficult for the PAM framework
-      to decide which module should return data to the application.  When
-      there is any error, the application does not know which of the
-      modules failed.  This behavior enables (even requires) the
-      application to be completely independent from the modules.
-
-      Another design decision we have made is that PAM gives only the user
-      name to all the underlying PAM modules, hence it is the
-      responsibility of the PAM modules to convert the name to their own
-      internal format.  For example, the Kerberos module may have to
-      convert the UNIX user name to a Kerberos principal name.
-
-      Stacking also forces the modules to be designed such that they can
-      occur anywhere in the stack without any side-effects.
-
-      Since modules such as the authentication and the password module are
-      very closely related, it is important they be configured in the same
-      order and with compatible options.
-
-
-
-
-
-   Samar, Schemers                                                  Page 14
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   8. INTEGRATION WITH SMART CARDS
-
-      Many networking authentication protocols require possession of a long
-      key to establish the user identity.  For ease-of-use reasons, that
-      long key is normally encrypted with the user's password so that the
-      user is not required to memorize it.  However, weak passwords can be
-      compromised through a dictionary attack and thus undermine the
-      stronger network authentication mechanism.  Furthermore, the
-      encrypted data is normally stored in a centrally accessible service
-      whose availability depends upon the reliability of the associated
-      service.  Solutions have been proposed to use a pass-phrase or one-
-      time-password, but those are much longer than the regular eight
-      character passwords traditionally used with UNIX `login'.  This makes
-      the solution user-unfriendly because it requires longer strings to be
-      remembered and typed.
-
-      For most authentication protocol implementations, the trust boundary
-      is the local machine.  This assumption may not be valid in cases
-      where the user is mobile and has to use publicly available networked
-      computers.  In such cases, it is required that the clear text of the
-      key or the password never be made available to the machine.
-
-      Smart cards solve the above problems by reducing password exposure by
-      supporting a _two factor_ authentication mechanism: the first with
-      the possession of the card, and the second with the knowledge of the
-      PIN associated with the card.  Not only can the smart cards be a
-      secure repository of multiple passwords, they can also provide the
-      encryption and authentication functions such that the long (private)
-      key is never exposed outside the card.
-
-      The PAM framework allows for integrating smart cards to the system by
-      providing a smart card specific module for authentication.
-      Furthermore, the unified login problem is simplified because the
-      multiple passwords for various authentication mechanisms can be
-      stored on the smart card itself.  This can be enabled by adding a
-      suitable key-word such as `use_smart_card' in the _options_ field.
-
-
-   9. SECURITY ISSUES
-
-      It is important to understand the impact of PAM on the security of
-      any system so that the site-administrator can make an informed
-      decision.
-
-        (a) Sharing of passwords with multiple authentication mechanisms.
-
-            If there are multiple authentication modules, one possibility
-            is to use the same password for all of them.  If the password
-            for any of the multiple authentication system is compromised,
-            the user's password in all systems would be compromised.  If
-            this is a concern, then multiple passwords might be considered
-
-
-
-   Samar, Schemers                                                  Page 15
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            at the cost of ease-of-use.
-
-        (b) Password-mapping.
-
-            This technique of encrypting all other passwords with the
-            primary password assumes that it is lot more difficult to crack
-            the primary password and that reasonable steps have been taken
-            to ensure limited availability of the encrypted primary
-            password.  If this is not done, an intruder could target the
-            primary password as the first point of dictionary attack.  If
-            one of the other modules provide stronger security than the
-            password based security, the site would be negating the strong
-            security by using password-mapping.  If this is a concern, then
-            multiple passwords might be considered at the cost of ease-of-
-            use.  If smart cards are used, they obviate the need for
-            password-mapping completely.
-
-        (c) Security of the configuration file.
-
-            Since the policy file dictates how the user is authenticated,
-            this file should be protected from unauthorized modifications.
-
-        (d) Stacking various PAM modules.
-
-            The system administrator should fully understand the
-            implications of stacking various modules that will be installed
-            on the system and their respective orders and interactions.
-            The composition of various authentication modules should be
-            carefully examined.  The trusted computing base of the machine
-            now includes the PAM modules.
-
-
-   10. EXPERIENCE WITH PAM
-
-      The PAM framework was first added in Solaris 2.3 release as a private
-      internal interface.  PAM is currently being used by several system
-      entry applications such as `login', `passwd', `su', `dtlogin',
-      `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init',
-      `sac', and `ttymon'.  We have found that PAM provides an excellent
-      framework to encapsulate the authentication-related tasks for the
-      entire system.  The Solaris 2.3 PAM API's were hence enhanced and
-      simplified to support stacking.
-
-      PAM modules have been developed for UNIX, DCE, Kerberos, S/Key,
-      remote user authentication, and dialpass authentication.  Other PAM
-      modules are under development, and integration with smart cards is
-      being planned.
-
-      Some third parties have used the PAM interface to extend the security
-      mechanisms offered by the Solaris environment.
-
-
-
-
-   Samar, Schemers                                                  Page 16
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      The PAM API has been accepted by Common Desktop Environment (CDE)
-      vendors as the API to be used for integrating the graphical interface
-      for login, `dtlogin' with multiple authentication mechanisms.
-
-
-   11. FUTURE WORK
-
-      Amongst the various components of PAM, the password component needs
-      to be carefully examined to see whether the stacking semantics are
-      particularly applicable, and how PAM should deal with partial
-      failures when changing passwords.
-
-      The _control_flag_ of the configuration file can be extended to
-      include other semantics.  For example, if the error is "name service
-      not available", one may want to retry.  It is also possible to offer
-      semantics of "return success if any of the modules return success".
-
-      In an earlier section, we had mentioned integration of smart cards
-      with PAM.  Though we feel that integration should be straight forward
-      from the PAM architecture point of view, there may be some issues
-      with implementation because the interfaces to the smart cards have
-      not yet been standardized.
-
-      One possible extension to PAM is to allow the passing of module-
-      specific data between applications and PAM modules.  For example, the
-      `login' program likes to build its new environment from a select list
-      of variables, yet the DCE module needs the `KRB5CCNAME' variable to
-      be exported to the child process.  For now we have modified the
-      `login' program to explicitly export the `KRB5CCNAME' variable.
-
-      Administrative tools are needed to help system administrators modify
-      `pam.conf', and perform sanity checks on it (i.e., a `pam_check'
-      utility).
-
-
-   12. CONCLUSION
-
-      The PAM framework and the module interfaces provide pluggability for
-      user authentication, as well as for account, session and password
-      management.  The PAM architecture can be used by `login' and by all
-      other system-entry services, and thus ensure that all entry points
-      for the system have been secured.  This architecture enables
-      replacement and modification of authentication modules in the field
-      to secure the system against the newly found weaknesses without
-      changing any of the system services.
-
-      The PAM framework can be used to integrate `login' and `dtlogin' with
-      different authentication mechanisms such as RSA and Kerberos.
-      Multiple authentication systems can be accessed with the same
-      password.  The PAM framework also provides easy integration of smart
-      cards into the system.
-
-
-
-   Samar, Schemers                                                  Page 17
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      PAM provides complementary functionality to GSS-API, in that it
-      provides mechanisms through which the user gets authenticated to any
-      new system-level authentication service on the machine.  GSS-API then
-      uses the credentials for authenticated and secure communications with
-      other application-level service entities on the network.
-
-
-   13. ACKNOWLEDGEMENTS
-
-      PAM development has spanned several release cycles at SunSoft.
-      Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and
-      implementation.  Bill Shannon and Don Stephenson helped with the PAM
-      architecture.  Rocky Wu prototyped stacking of multiple modules.
-      Paul Fronberg, Charlie Lai, and Roland Schemers made very significant
-      enhancements to the PAM interfaces and took the project to completion
-      within a very short time.  Kathy Slattery wrote the PAM
-      documentation.  John Perry integrated PAM within the CDE framework.
-
-
-   APPENDIX A. PAM API'S
-
-      This appendix gives an informal description of the various interfaces
-      of PAM.  Since the goal here is just for the reader to get a working
-      knowledge about the PAM interfaces, not all flags and options have
-      been fully defined and explained.  The API's described here are
-      subject to change.
-
-      The PAM Service Provider Interface is very similar to the PAM API,
-      except for one extra parameter to pass module-specific options to the
-      underlying modules.
-
-   A.1. Framework Layer API's
-
-            int
-            pam_start(
-                char *service_name,
-                char *user,
-                struct pam_conv *pam_conversation,
-                pam_handle_t **pamh
-            );
-
-      `pam_start()' is called to initiate an authentication transaction.
-      `pam_start()' takes as arguments the name of the service, the name of
-      the user to be authenticated, the address of the conversation
-      structure.  `pamh' is later used as a handle for subsequent calls to
-      the PAM library.
-
-      The PAM modules do not communicate directly with the user; instead
-      they rely on the application to perform all such interaction.  The
-      application needs to provide the conversation functions, `conv()',
-      and associated application data pointers through a `pam_conv'
-
-
-
-   Samar, Schemers                                                  Page 18
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      structure when it initiates an authentication transaction.  The
-      module uses the `conv()' function to prompt the user for data,
-      display error messages, or text information.
-
-            int
-            pam_end(
-                pam_handle_t *pamh,
-                int pam_status
-            );
-
-      `pam_end()' is called to terminate the PAM transaction as specified
-      by `pamh', and to free any storage area allocated by the PAM modules
-      with `pam_set_item()'.
-
-            int
-            pam_set_item(
-                pam_handle_t *pamh,
-                int item_type,
-                void *item
-            );
-
-            int
-            pam_get_item(
-                pam_handle_t *pamh,
-                int item_type,
-                void **item);
-
-      `pam_get_item()' and `pam_set_item()' allow the parameters specified
-      in the initial call to `pam_start()' to be read and updated.  This is
-      useful when a particular parameter is not available when
-      `pam_start()' is called or must be modified after the initial call to
-      `pam_start()'.  `pam_set_item()' is passed a pointer to the object,
-      `item', and its type, `item_type'.  `pam_get_item()' is passed the
-      address of the pointer, `item', which is assigned the address of the
-      requested object.
-
-      The `item_type' is one of the following:
-
-                   Table 5: Possible Values for Item_type
-
-            Item Name       Description
-            ---------       -----------
-            PAM_SERVICE     The service name
-            PAM_USER        The user name
-            PAM_TTY         The tty name
-            PAM_RHOST       The remote host name
-            PAM_CONV        The pam_conv structure
-            PAM_AUTHTOK     The authentication token (password)
-            PAM_OLDAUTHTOK  The old authentication token
-            PAM_RUSER       The remote user name
-
-
-
-
-   Samar, Schemers                                                  Page 19
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only
-      available to PAM modules and not to the applications.  They are
-      explicitly cleared out by the framework before returning to the
-      application.
-
-            char *
-            pam_strerror(
-                int errnum
-            );
-
-      `pam_strerror()' maps the error number to a PAM error message string,
-      and returns a pointer to that string.
-
-            int
-            pam_set_data(
-                pam_handle_t *pamh,
-                char *module_data_name,
-                char *data,
-                (*cleanup)(pam_handle_t *pamh, char *data,
-                           int error_status)
-            );
-
-      The `pam_set_data()' function stores module specific data within the
-      PAM handle.  The `module_data_name' uniquely specifies the name to
-      which some data and cleanup callback function can be attached.  The
-      cleanup function is called when `pam_end()' is invoked.
-
-            int
-            pam_get_data(
-                pam_handle_t *pamh,
-                char *module_data_name,
-                void **datap
-            );
-
-      The `pam_get_data()' function obtains module-specific data from the
-      PAM handle stored previously by the `pam_get_data()' function.  The
-      `module_data_name' uniquely specifies the name for which data has to
-      be obtained.  This function is normally used to retrieve module
-      specific state information.
-
-   A.2. Authentication API's
-
-            int
-            pam_authenticate(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      The `pam_authenticate()' function is called to verify the identity of
-      the current user.  The user is usually required to enter a password
-      or similar authentication token, depending upon the authentication
-
-
-
-   Samar, Schemers                                                  Page 20
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      module configured with the system.  The user in question is specified
-      by a prior call to `pam_start()', and is referenced by the
-      authentication handle, `pamh'.
-
-            int
-            pam_setcred(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      The `pam_setcred()' function is called to set the credentials of the
-      current process associated with the authentication handle, `pamh'.
-      The actions that can be denoted through `flags' include credential
-      initialization, refresh, reinitialization and deletion.
-
-   A.3. Account Management API
-
-            int
-            pam_acct_mgmt(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      The function `pam_acct_mgmt()' is called to determine whether the
-      current user's account and password are valid.  This typically
-      includes checking for password and account expiration, valid login
-      times, etc.  The user in question is specified by a prior call to
-      `pam_start()', and is referenced by the authentication handle,
-      `pamh'.
-
-   A.4. Session Management API's
-
-            int
-            pam_open_session(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      `pam_open_session()' is called to inform the session modules that a
-      new session has been initialized.  All programs which use PAM should
-      invoke `pam_open_session()' when beginning a new session.
-
-            int
-            pam_close_session(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      Upon termination of this session, the `pam_close_session()' function
-      should be invoked to inform the underlying modules that the session
-      has terminated.
-
-
-
-   Samar, Schemers                                                  Page 21
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   A.5. Password Management API's
-
-            int
-            pam_chauthtok(
-                pam_handle_t *pamh,
-                int flags
-            );
-
-      `pam_chauthtok()' is called to change the authentication token
-      associated with the user referenced by the authentication handle
-      `pamh'.  After the call, the authentication token of the user will be
-      changed in accordance with the authentication module configured on
-      the system.
-
-
-   APPENDIX B. SAMPLE PAM APPLICATION
-
-      This appendix shows a sample `login' application which uses the PAM
-      API's.  It is not meant to be a fully functional login program, as
-      some functionality has been left out in order to emphasize the use of
-      PAM API's.
-
-      #include <security/pam_appl.h>
-
-      static int login_conv(int num_msg, struct pam_message **msg,
-          struct pam_response **response, void *appdata_ptr);
-
-      static struct pam_conv pam_conv = {login_conv, NULL};
-
-      static pam_handle_t *pamh;    /* Authentication handle */
-
-      void
-      main(int argc, char *argv[], char **renvp)
-      {
-
-          /*
-           * Call pam_start to initiate a PAM authentication operation
-           */
-
-          if ((pam_start("login", user_name, &pam_conv, &pamh))
-                      != PAM_SUCCESS)
-                      login_exit(1);
-
-          pam_set_item(pamh, PAM_TTY, ttyn);
-          pam_set_item(pamh, PAM_RHOST, remote_host);
-
-          while (!authenticated && retry < MAX_RETRIES) {
-              status = pam_authenticate(pamh, 0);
-              authenticated = (status == PAM_SUCCESS);
-          }
-
-
-
-
-   Samar, Schemers                                                  Page 22
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-          if (status != PAM_SUCCESS) {
-              fprintf(stderr,"error: %s\n", pam_strerror(status));
-              login_exit(1);
-          }
-
-          /* now check if the authenticated user is allowed to login. */
-
-          if ((status = pam_acct_mgmt(pamh, 0)) != PAM_SUCCESS) {
-              if (status == PAM_AUTHTOK_EXPIRED) {
-                   status = pam_chauthtok(pamh, 0);
-                   if (status != PAM_SUCCESS)
-                       login_exit(1);
-              } else {
-                   login_exit(1);
-              }
-          }
-
-          /*
-           * call pam_open_session to open the authenticated session
-           * pam_close_session gets called by the process that
-           * cleans up the utmp entry (i.e., init)
-           */
-          if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) {
-              login_exit(status);
-          }
-
-          /* set up the process credentials */
-          setgid(pwd->pw_gid);
-
-          /*
-           * Initialize the supplementary group access list.
-           * This should be done before pam_setcred because
-           * the PAM modules might add groups during the pam_setcred call
-           */
-          initgroups(user_name, pwd->pw_gid);
-
-          status = pam_setcred(pamh, PAM_ESTABLISH_CRED);
-          if (status != PAM_SUCCESS) {
-              login_exit(status);
-          }
-
-          /* set the real (and effective) UID */
-          setuid(pwd->pw_uid);
-
-          pam_end(pamh, PAM_SUCCESS);    /* Done using PAM */
-
-          /*
-           * Add DCE/Kerberos cred name, if any.
-           * XXX - The module specific stuff should be removed from login
-           * program eventually.  This is better placed in DCE module and
-           * will be once PAM has routines for "exporting" environment
-
-
-
-   Samar, Schemers                                                  Page 23
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-           * variables.
-           */
-          krb5p = getenv("KRB5CCNAME");
-          if (krb5p != NULL) {
-              ENVSTRNCAT(krb5ccname, krb5p);
-              envinit[basicenv++] = krb5ccname;
-          }
-          environ = envinit; /* Switch to the new environment. */
-          exec_the_shell();
-
-          /* All done */
-      }
-
-      /*
-       * login_exit        - Call exit()  and terminate.
-       *              This function is here for PAM so cleanup can
-       *              be done before the process exits.
-       */
-      static void
-      login_exit(int exit_code)
-      {
-          if (pamh)
-              pam_end(pamh, PAM_ABORT);
-          exit(exit_code);
-          /*NOTREACHED*/
-      }
-
-      /*
-       * login_conv():
-       *    This is the conv (conversation) function called from
-       *    a PAM authentication module to print error messages
-       *    or garner information from the user.
-       */
-
-      static int
-      login_conv(int num_msg, struct pam_message **msg,
-          struct pam_response **response, void *appdata_ptr)
-      {
-
-          while (num_msg--) {
-              switch (m->msg_style) {
-
-              case PAM_PROMPT_ECHO_OFF:
-                  r->resp = strdup(getpass(m->msg));
-                  break;
-
-              case PAM_PROMPT_ECHO_ON:
-                  (void) fputs(m->msg, stdout);
-                  r->resp = malloc(PAM_MAX_RESP_SIZE);
-                  fgets(r->resp, PAM_MAX_RESP_SIZE, stdin);
-                  /* add code here to remove \n from fputs */
-
-
-
-   Samar, Schemers                                                  Page 24
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-                  break;
-
-              case PAM_ERROR_MSG:
-                  (void) fputs(m->msg, stderr);
-                  break;
-
-              case PAM_TEXT_INFO:
-                  (void) fputs(m->msg, stdout);
-                  break;
-
-              default:
-                      /* add code here to log error message, etc */
-                  break;
-              }
-          }
-          return (PAM_SUCCESS);
-      }
-
-
-   APPENDIX C. DCE MODULE
-
-      This appendix describes a sample implementation of a DCE PAM module.
-      In order to simplify the description, we do not address the issues
-      raised by password-mapping or stacking.  The intent is to show which
-      DCE calls are being made by the DCE module.
-
-      The `pam_sm_*()' functions implement the PAM SPI functions which are
-      called from the PAM API functions.
-
-   C.1. DCE Authentication Management
-
-      The algorithm for authenticating with DCE (not including error
-      checking, prompting for passwords, etc.) is as follows:
-
-            pam_sm_authenticate()
-            {
-                sec_login_setup_identity(...);
-                pam_set_data(...);
-                sec_login_valid_and_cert_ident(...);
-            }
-
-            pam_sm_setcred()
-            {
-                pam_get_data(...);
-                sec_login_set_context(...);
-            }
-
-      The `pam_sm_authenticate()' function for DCE uses the
-      `pam_set_data()' and `pam_get_data()' functions to keep state (like
-      the `sec_login_handle_t' context) between calls.  The following
-      cleanup function is also registered and gets called when `pam_end()'
-
-
-
-   Samar, Schemers                                                  Page 25
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      is called:
-
-            dce_cleanup()
-            {
-                if (/* PAM_SUCCESS and
-                       sec_login_valid_and_cert_ident success */) {
-                   sec_login_release_context(...);
-                } else {
-                   sec_login_purge_context(...);
-                }
-            }
-
-      If everything was successful we release the login context, but leave
-      the credentials file intact.  If the status passed to `pam_end()' was
-      not `PAM_SUCCESS' (i.e., a required module failed) we purge the login
-      context which also removes the credentials file.
-
-   C.2. DCE Account Management
-
-      The algorithm for DCE account management is as follows:
-
-            pam_sm_acct_mgmt()
-            {
-                pam_get_data(...);
-                sec_login_inquire_net_info(...);
-                /* check for expired password and account */
-                sec_login_free_net_info(...);
-            }
-
-      The `sec_login_inquire_net_info()' function is called to obtain
-      information about when the user's account and/or password are going
-      to expire.  A warning message is displayed (using the conversation
-      function) if the user's account or password is going to expire in the
-      near future, or has expired.  These warning messages can be disabled
-      using the `nowarn' option in the `pam.conf' file.
-
-   C.3. DCE Session Management
-
-      The DCE session management functions are currently empty.  They could
-      be modified to optionally remove the DCE credentials file upon
-      logout, etc.
-
-   C.4. DCE Password Management
-
-      The algorithm for DCE password management is as follows:
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                  Page 26
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            pam_sm_chauthtok
-            {
-                sec_rgy_site_open(...);
-                sec_rgy_acct_lookup(...);
-                sec_rgy_acct_passwd(...);
-                sec_rgy_site_close(...);
-            }
-
-      The `sec_rgy_acct_passwd()' function is called to change the user's
-      password in the DCE registry.
-
-
-   REFERENCES
-
-      [Adamson 95]   W. A. Adamson, J. Rees, and P. Honeyman, "Joining
-                     Security Realms: A Single Login for Netware and
-                     Kerberos", CITI Technical Report 95-1, Center for
-                     Information Technology Integration, University of
-                     Michigan, Ann Arbor, MI, February 1995.
-
-      [Diffie 76]    W. Diffie and M. E. Hellman, "New Directions in
-                     Cryptography", IEEE Transactions on Information
-                     Theory, November 1976.
-
-      [Linn 93]      J. Linn, "Generic Security Service Application
-                     Programming Interface", Internet RFC 1508, 1509, 1993.
-
-      [Rivest 78]    R. L. Rivest, A. Shamir, and L. Adleman., "A Method
-                     for Obtaining Digital Signatures and Pubic-key
-                     Cryptosystems", Communications of the ACM, 21(2),
-                     1978.
-
-      [SIA 95]       "Digital UNIX Security", Digital Equipment
-                     Corporation, Order Number AA-Q0R2C-TE, July 1995.
-
-      [Skey 94]      N. M. Haller, "The S/Key One-Time Password System",
-                     ISOC Symposium on Network and Distributed Security,
-                     1994.
-
-      [Steiner 88]   J.G. Steiner, B. C. Neuman, and J. I. Schiller,
-                     "Kerberos, An Authentication Service for Open Network
-                     Systems", in Proceedings of the Winter USENIX
-                     Conference, Dallas, Jan 1988.
-
-      [Taylor 88]    B. Taylor and D. Goldberg, "Secure Networking in the
-                     Sun Environment", Sun Microsystems Technical Paper,
-                     1988.
-
-      [XFN 94]       "Federated Naming: the XFN Specifications", X/Open
-                     Preliminary Specification, X/Open Document #P403,
-                     ISBN:1-85912-045-8, X/Open Co. Ltd., July 1994.
-
-
-
-   Samar, Schemers                                                  Page 27
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   AUTHOR'S ADDRESS
-
-   Vipin Samar                            Internet email: vipin@eng.sun.com
-   SunSoft, Inc.                                 Telephone: +1-415-336-1002
-   2550 Garcia Avenue
-   Mountain View, CA 94043
-   USA
-
-   Roland J. Schemers III              Internet email: schemers@eng.sun.com
-   SunSoft, Inc.                                 Telephone: +1-415-336-1035
-   2550 Garcia Avenue
-   Mountain View, CA 94043
-   USA
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                  Page 28
-
-
-
-
-
-
diff --git a/doc/specs/std-agent-id.raw b/doc/specs/std-agent-id.raw
deleted file mode 100644
index d5fbdd56..00000000
--- a/doc/specs/std-agent-id.raw
+++ /dev/null
@@ -1,95 +0,0 @@
-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
diff --git a/doc/txts/.cvsignore b/doc/txts/.cvsignore
deleted file mode 100644
index f35c3921..00000000
--- a/doc/txts/.cvsignore
+++ /dev/null
@@ -1 +0,0 @@
-pam*.txt
diff --git a/doc/txts/README b/doc/txts/README
deleted file mode 100644
index 540b09b5..00000000
--- a/doc/txts/README
+++ /dev/null
@@ -1,3 +0,0 @@
-$Id$
-
-This is a directory for text versions of the pam documentation