summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorThorsten Kukuk <kukuk@thkukuk.de>2006-06-28 14:41:18 +0000
committerThorsten Kukuk <kukuk@thkukuk.de>2006-06-28 14:41:18 +0000
commit95e6b22ccd72741a4b651deae208b184086f2e52 (patch)
tree0bc38582d9ebe760b8ddc8645cd581d9fa552ed6 /doc
parent504eedccf7e1d222092c6005fdc13705ab5d26b8 (diff)
Relevant BUGIDs:
Purpose of commit: cleanup Commit summary: --------------- * doc/CREDITS: Removed. * doc/NOTES: Removed. * doc/pam_appl.sgml: Removed. * doc/pam_modules.sgml: Removed. * doc/pam_source.sgml: Removed. * doc/figs/pam_orient.txt: Removed. * doc/figs: Removed. * configure.in: Remove checks for sgml2* progrs, add sag, adg and mwg Makefiles. * doc/Makefile.am: Remove references to sgml, add sag, adg and mwg directories.
Diffstat (limited to 'doc')
-rw-r--r--doc/CREDITS49
-rw-r--r--doc/Makefile.am118
-rw-r--r--doc/NOTES16
-rw-r--r--doc/figs/pam_orient.txt23
-rw-r--r--doc/pam_appl.sgml1777
-rw-r--r--doc/pam_modules.sgml1505
-rw-r--r--doc/pam_source.sgml1152
7 files changed, 4 insertions, 4636 deletions
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.am b/doc/Makefile.am
index dd4cb520..c1e2586f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,143 +2,33 @@
# Copyright (c) 2005, 2006 Thorsten Kukuk <kukuk@suse.de>
#
-SUBDIRS = man specs
+SUBDIRS = man specs sag adg mwg
-FILES=pam pam_appl pam_modules
-FSRCS=$(srcdir)/pam_appl.sgml $(srcdir)/pam_modules.sgml
+CLEANFILES = *~
-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 pdf/pam_appl.pdf pdf/pam_modules.pdf
-
-MODULES=$(shell ls $(srcdir)/modules/*.sgml)
-
-CLEANFILES = *~ */*~ $(TEXTS) $(PSFILES) $(PDFFILES) html/pam*.html \
- ps/missfont.log MODULES-SGML pam.sgml
-
-EXTRA_DIST = $(FSRCS) CREDITS NOTES figs/pam_orient.txt pdf/README \
- ps/README html/index.html txts/README \
- pam_source.sgml $(MODULES) modules/module.sgml-template \
- modules/README
+EXTRA_DIST = pdf/README html/index.html txts/README
#######################################################
-all: html text postscript pdf
-
-html: $(HTMLS)
-
-$(HTMLS) : $(FSRCS) $(srcdir)/pam.sgml
- @echo 'Building html documentation from files in modules/*.sgml'
-if HAVE_SGML2HTML
- @for i in $(FILES) ; do \
- if [ ! -f "html/$$i.html" ] || [ "$(srcdir)/$$i.sgml" -nt "html/$$i.html" ]; \
- then \
- mkdir -p html ; \
- cd html ; sgml2html ../$(srcdir)/$$i ; \
- if [ $$? -ne 0 ]; then exit 1 ; fi ; \
- cd .. ; \
- fi ; \
- done
-else
- @echo XXX - you do not have the sgml2html binary installed
-endif
-
-text: $(TEXTS)
-
-$(TEXTS) : $(FSRCS) $(srcdir)/pam.sgml
- @echo 'Building text documentation from files in modules/*.sgml'
-if HAVE_SGML2TXT
- @for i in $(FILES) ; do \
- if [ ! -f "txts/$$i.txt" ] \
- || [ "$(srcdir)/$$i.sgml" -nt "txts/$$i.txt" ]; then \
- mkdir -p txts ; \
- cd txts ; sgml2txt ../$(srcdir)/$$i ; cd .. ; \
- fi ; \
- done
-else
- @echo XXX - you do not have the sgml2txt binary installed
-endif
-
-postscript: $(PSFILES)
-
-$(PSFILES): $(FSRCS) $(srcdir)/pam.sgml
- @echo 'Building postscript documentation from files in modules/*.sgml'
-if HAVE_SGML2PS
- @for i in $(FILES) ; do \
- if [ ! -f "ps/$$i.ps" ] || [ "$(srcdir)/$$i.sgml" -nt "ps/$$i.ps" ]; then \
- mkdir -p ps ; \
- cd ps ; $(PSER) ../$(srcdir)/$$i ; cd .. ; \
- fi ; \
- done
-else
- @echo XXX - neither sgml2ps nor sgml2latex binaries are installed
-endif
-
-pdf: $(PDFFILES)
-
-$(PDFFILES) : $(PSFILES)
- @echo 'Building PDF documentation from files in modules/*.sgml'
-if HAVE_SGML2PS
-if HAVE_PS2PDF
- @for i in $(FILES) ; do \
- if [ ! -f "pdf/$$i.pdf" ] || [ "ps/$$i.ps" -nt "ps/$$i.pdf" ]; then \
- mkdir -p pdf ; \
- ps2pdf ps/$$i.ps pdf/$$i.pdf ; \
- fi ; \
- done
-else
- @echo XXX - ps2pdf is not installed
-endif
-else
- @echo XXX - neither sgml2ps nor sgml2latex binaries are installed
-endif
-
-$(srcdir)/pam.sgml: $(srcdir)/pam_source.sgml MODULES-SGML CREDITS
- @sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' $(srcdir)/pam_source.sgml |\
- sed -e '/^<!\-\- insert\-file CREDITS \-\->/r CREDITS' > $(srcdir)/pam.sgml
-
-MODULES-SGML: $(MODULES)
- @echo 'Building module text from files in modules/*.sgml'
- @rm -f MODULES-SGML
- @echo '<!-- modules included:' > MODULES-SGML
- @ls $(srcdir)/modules/*.sgml >> MODULES-SGML
- @echo ' and that is all -->' >> MODULES-SGML
- @cat $(srcdir)/modules/*.sgml >> MODULES-SGML
-
-extraclean: clean
-
install-data-local:
$(mkinstalldirs) $(DESTDIR)$(DOCDIR)
-if HAVE_SGML2TXT
$(mkinstalldirs) $(DESTDIR)$(DOCDIR)/text
for file in txts/*.txt; do \
$(INSTALL_DATA) $$file $(DESTDIR)$(DOCDIR)/text; \
done
-endif
-if HAVE_SGML2PS
- $(mkinstalldirs) $(DESTDIR)$(DOCDIR)/ps
- for file in ps/*.ps; do \
- $(INSTALL_DATA) $$file $(DESTDIR)$(DOCDIR)/ps; \
- done
-if HAVE_PS2PDF
$(mkinstalldirs) $(DESTDIR)$(DOCDIR)/pdf
for file in pdf/*.pdf; do \
$(INSTALL_DATA) $$file $(DESTDIR)$(DOCDIR)/pdf; \
done
-endif
-endif
-if HAVE_SGML2HTML
$(mkinstalldirs) $(DESTDIR)$(DOCDIR)/html
for file in html/*.html; do \
$(INSTALL_DATA) $$file $(DESTDIR)$(DOCDIR)/html; \
done
-endif
releasedocs: all
tar zvfc ../Linux-PAM-$(VERSION)-docs.tar.gz \
--exclude CVS --exclude .cvsignore --exclude '.#*' \
- --exclude README html ps txts pdf \
+ --exclude README html txts pdf \
specs/draft-morgan-pam-current.txt specs/rfc86.0.txt
tar jvfc ../Linux-PAM-$(VERSION)-docs.tar.bz2 \
--exclude CVS --exclude .cvsignore --exclude '.#*' \
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/pam_appl.sgml b/doc/pam_appl.sgml
deleted file mode 100644
index a80bcbb6..00000000
--- a/doc/pam_appl.sgml
+++ /dev/null
@@ -1,1777 +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 whose 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>
-In the case of an error, the contents of <tt/item/ is set to <tt/NULL/.
-
-<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 872e4d7d..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_NEW_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 bc091ed6..00000000
--- a/doc/pam_source.sgml
+++ /dev/null
@@ -1,1152 +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.77 2002/07/10
-<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 Red Hat) 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/,
-<tt/optional/ and <tt/include/.
-
-<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/.
-
-<item> <tt/include/; this tells PAM to include all lines of given type
-from the configuration file specified as an argument to this control.
-The whole idea is to create few "systemwide" pam configs and include
-parts of them in application pam configs.
-
-
-</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. :/
-
-</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>