PAM is dead, long live PAM!
authorJoerg Sonnenberger <joerg@dragonflybsd.org>
Wed, 13 Jul 2005 22:04:06 +0000 (22:04 +0000)
committerJoerg Sonnenberger <joerg@dragonflybsd.org>
Wed, 13 Jul 2005 22:04:06 +0000 (22:04 +0000)
143 files changed:
contrib/libpam/CHANGELOG [deleted file]
contrib/libpam/Copyright [deleted file]
contrib/libpam/FREEBSD-Xlist [deleted file]
contrib/libpam/FREEBSD-upgrade [deleted file]
contrib/libpam/Makefile [deleted file]
contrib/libpam/README [deleted file]
contrib/libpam/TODO [deleted file]
contrib/libpam/defs/debian.defs [deleted file]
contrib/libpam/defs/redhat4.defs [deleted file]
contrib/libpam/defs/solaris-2.1.5.defs [deleted file]
contrib/libpam/defs/suse.defs [deleted file]
contrib/libpam/doc/CREDITS [deleted file]
contrib/libpam/doc/Makefile [deleted file]
contrib/libpam/doc/NOTES [deleted file]
contrib/libpam/doc/figs/pam_orient.txt [deleted file]
contrib/libpam/doc/html/index.html [deleted file]
contrib/libpam/doc/man/pam.8 [deleted file]
contrib/libpam/doc/man/pam.conf.8 [deleted file]
contrib/libpam/doc/man/pam.d.8 [deleted file]
contrib/libpam/doc/man/pam_authenticate.3 [deleted file]
contrib/libpam/doc/man/pam_chauthtok.3 [deleted file]
contrib/libpam/doc/man/pam_close_session.3 [deleted file]
contrib/libpam/doc/man/pam_end.3 [deleted file]
contrib/libpam/doc/man/pam_fail_delay.3 [deleted file]
contrib/libpam/doc/man/pam_open_session.3 [deleted file]
contrib/libpam/doc/man/pam_setcred.3 [deleted file]
contrib/libpam/doc/man/pam_start.3 [deleted file]
contrib/libpam/doc/man/pam_strerror.3 [deleted file]
contrib/libpam/doc/man/template-man [deleted file]
contrib/libpam/doc/modules/pam_access.sgml [deleted file]
contrib/libpam/doc/modules/pam_issue.sgml [deleted file]
contrib/libpam/doc/modules/pam_mkhomedir.sgml [deleted file]
contrib/libpam/doc/modules/pam_motd.sgml [deleted file]
contrib/libpam/doc/modules/pam_tally.sgml [deleted file]
contrib/libpam/doc/modules/pam_unix.sgml [deleted file]
contrib/libpam/doc/modules/pam_userdb.sgml [deleted file]
contrib/libpam/doc/pam_appl.sgml [deleted file]
contrib/libpam/doc/pam_modules.sgml [deleted file]
contrib/libpam/doc/pam_source.sgml [deleted file]
contrib/libpam/doc/specs/rfc86.0.txt [deleted file]
contrib/libpam/libpam/Makefile [deleted file]
contrib/libpam/libpam/include/security/_pam_compat.h [deleted file]
contrib/libpam/libpam/include/security/_pam_macros.h [deleted file]
contrib/libpam/libpam/include/security/_pam_types.h [deleted file]
contrib/libpam/libpam/include/security/pam_appl.h [deleted file]
contrib/libpam/libpam/include/security/pam_malloc.h [deleted file]
contrib/libpam/libpam/include/security/pam_modules.h [deleted file]
contrib/libpam/libpam/pam_account.c [deleted file]
contrib/libpam/libpam/pam_auth.c [deleted file]
contrib/libpam/libpam/pam_data.c [deleted file]
contrib/libpam/libpam/pam_delay.c [deleted file]
contrib/libpam/libpam/pam_dispatch.c [deleted file]
contrib/libpam/libpam/pam_end.c [deleted file]
contrib/libpam/libpam/pam_env.c [deleted file]
contrib/libpam/libpam/pam_handlers.c [deleted file]
contrib/libpam/libpam/pam_item.c [deleted file]
contrib/libpam/libpam/pam_log.c [deleted file]
contrib/libpam/libpam/pam_malloc.c [deleted file]
contrib/libpam/libpam/pam_map.c [deleted file]
contrib/libpam/libpam/pam_misc.c [deleted file]
contrib/libpam/libpam/pam_password.c [deleted file]
contrib/libpam/libpam/pam_private.h [deleted file]
contrib/libpam/libpam/pam_second.c [deleted file]
contrib/libpam/libpam/pam_session.c [deleted file]
contrib/libpam/libpam/pam_start.c [deleted file]
contrib/libpam/libpam/pam_static.c [deleted file]
contrib/libpam/libpam/pam_strerror.c [deleted file]
contrib/libpam/libpam/pam_tokens.h [deleted file]
contrib/libpam/libpam_misc/Makefile [deleted file]
contrib/libpam/libpam_misc/help_env.c [deleted file]
contrib/libpam/libpam_misc/include/security/pam_misc.h [deleted file]
contrib/libpam/libpam_misc/misc_conv.c [deleted file]
contrib/libpam/libpam_misc/pam_misc.h [deleted file]
contrib/libpam/libpam_misc/xstrdup.c [deleted file]
contrib/libpam/libpamc/License [deleted file]
contrib/libpam/libpamc/Makefile [deleted file]
contrib/libpam/libpamc/include/security/pam_client.h [deleted file]
contrib/libpam/libpamc/libpamc.h [deleted file]
contrib/libpam/libpamc/pamc_client.c [deleted file]
contrib/libpam/libpamc/pamc_converse.c [deleted file]
contrib/libpam/libpamc/pamc_load.c [deleted file]
contrib/libpam/libpamc/test/agents/secret@here [deleted file]
contrib/libpam/libpamc/test/modules/Makefile [deleted file]
contrib/libpam/libpamc/test/modules/pam_secret.c [deleted file]
contrib/libpam/libpamc/test/regress/Makefile [deleted file]
contrib/libpam/libpamc/test/regress/run_test.sh [deleted file]
contrib/libpam/libpamc/test/regress/test.libpamc.c [deleted file]
contrib/libpam/libpamc/test/regress/test.secret@here [deleted file]
contrib/libpam/modules/pam_deny/Makefile [deleted file]
contrib/libpam/modules/pam_deny/README [deleted file]
contrib/libpam/modules/pam_deny/pam_deny.c [deleted file]
contrib/libpam/modules/pam_ftp/Makefile [deleted file]
contrib/libpam/modules/pam_ftp/README [deleted file]
contrib/libpam/modules/pam_ftp/pam_ftp.c [deleted file]
contrib/libpam/modules/pam_issue/Makefile [deleted file]
contrib/libpam/modules/pam_issue/pam_issue.c [deleted file]
contrib/libpam/modules/pam_mail/README [deleted file]
contrib/libpam/modules/pam_mkhomedir/Makefile [deleted file]
contrib/libpam/modules/pam_mkhomedir/pam_mkhomedir.c [deleted file]
contrib/libpam/modules/pam_motd/Makefile [deleted file]
contrib/libpam/modules/pam_motd/pam_motd.c [deleted file]
contrib/libpam/modules/pam_nologin/Makefile [deleted file]
contrib/libpam/modules/pam_nologin/README [deleted file]
contrib/libpam/modules/pam_nologin/pam_nologin.c [deleted file]
contrib/libpam/modules/pam_permit/Makefile [deleted file]
contrib/libpam/modules/pam_permit/README [deleted file]
contrib/libpam/modules/pam_permit/pam_permit.c [deleted file]
contrib/libpam/modules/pam_rhosts/Makefile [deleted file]
contrib/libpam/modules/pam_rhosts/README [deleted file]
contrib/libpam/modules/pam_rhosts/pam_rhosts_auth.c [deleted file]
contrib/libpam/modules/pam_rootok/Makefile [deleted file]
contrib/libpam/modules/pam_rootok/README [deleted file]
contrib/libpam/modules/pam_rootok/pam_rootok.c [deleted file]
contrib/libpam/modules/pam_securetty/Makefile [deleted file]
contrib/libpam/modules/pam_securetty/README [deleted file]
contrib/libpam/modules/pam_securetty/pam_securetty.c [deleted file]
contrib/libpam/modules/pam_shells/Makefile [deleted file]
contrib/libpam/modules/pam_shells/README [deleted file]
contrib/libpam/modules/pam_shells/pam_shells.c [deleted file]
contrib/libpam/modules/pam_tally/faillog.h [deleted file]
contrib/libpam/modules/pam_tally/pam_tally_app.c [deleted file]
contrib/libpam/modules/pam_unix/bigcrypt.c [deleted file]
contrib/libpam/modules/pam_unix/lckpwdf.-c [deleted file]
contrib/libpam/modules/pam_unix/md5.c [deleted file]
contrib/libpam/modules/pam_unix/md5.h [deleted file]
contrib/libpam/modules/pam_unix/md5_crypt.c [deleted file]
contrib/libpam/modules/pam_unix/support.h [deleted file]
contrib/libpam/modules/pam_unix/unix_chkpwd.c [deleted file]
contrib/libpam/modules/pam_unix/yppasswd.h [deleted file]
contrib/libpam/modules/pam_unix/yppasswd_xdr.c [deleted file]
contrib/libpam/modules/pam_userdb/Makefile [deleted file]
contrib/libpam/modules/pam_userdb/README [deleted file]
contrib/libpam/modules/pam_userdb/conv.c [deleted file]
contrib/libpam/modules/pam_userdb/create.pl [deleted file]
contrib/libpam/modules/pam_userdb/pam_userdb.c [deleted file]
contrib/libpam/modules/pam_userdb/pam_userdb.h [deleted file]
contrib/libpam/modules/pam_warn/Makefile [deleted file]
contrib/libpam/modules/pam_warn/README [deleted file]
contrib/libpam/modules/pam_warn/pam_warn.c [deleted file]
contrib/libpam/modules/pam_wheel/Makefile [deleted file]
contrib/libpam/modules/pam_wheel/README [deleted file]
contrib/libpam/modules/pam_wheel/pam_wheel.c [deleted file]
contrib/libpam/modules/register_static [deleted file]

diff --git a/contrib/libpam/CHANGELOG b/contrib/libpam/CHANGELOG
deleted file mode 100644 (file)
index c825460..0000000
+++ /dev/null
@@ -1,1093 +0,0 @@
-
-$Id$
-$FreeBSD: src/contrib/libpam/CHANGELOG,v 1.1.1.1.6.2 2001/06/11 15:28:09 markm Exp $
-$DragonFly: src/contrib/libpam/Attic/CHANGELOG,v 1.2 2003/06/17 04:24:02 dillon Exp $
-
------------------------------
-
-0.66: whenever
-
-TODO
-  - need to supply a backward compatability path for syslog & friends
-  - need to make pam_system_log() thread safe.
-  - need to make logging fix available to non-Linux PAM libraries
-  - need to change modules to make use of new logging API.
-  - document PAM_INCOMPLETE changes
-  - document pam_system_log() changes
-  - verify that the PAM_INCOMPLETE interface is sensible.   Can we
-    catch errors? should we permit item changing etc between
-    pam_authenticate re-invocations?
-  - verify that the PAM_INCOMPLETE interface works
-  - add PAM_INCOMPLETE support to modules
-  - verify that 
-  - work on RFC.
-
-0.65: Sun Apr  5 22:29:09 PDT 1998 <morgan@linux.kernel.org>
-
-* added event driven programming extensions to libpam
- - added PAM_INCOMPLETE handling to libpam/pam_dispatch.c
- - added PAM_CONV_AGAIN which is a new conversation response that
-   should be mapped to PAM_INCOMPLETE by the module.
- - ensured that the pam_get_user() function can resume
- - changes to pam_strerror to accommodate above return codes
- - clean up _pam_former_state at pam_end()
- - ensured that former state is correctly initialized
- - added resumption tests to pam_authenticate(), pam_chauthtok()
- - added PAM_FAIL_DELAY item for pausing on failure
-
-* improved _pam_macros.h so that macros can be used as single commands
-  (Andrey)
-
-* reimplemented logging to avoid bad interactions with libc.  Added
-  new functions, pam_[,v]system_log() to libpam's API.  A programmer
-  can check for this function's availablility by checking if
-  HAVE_PAM_SYSTEM_LOG is #defined.
-
-* removed the reduce conflict from pam_conv1 creation -- I can sleep
-  again now. :^]
-
-* made building of static and dynamic libpam separate.  This is
-  towards making it possible to build both under Solaris (for Derrick)
-
-* made USE_CRACKLIB a condition in unix module (Luke Kenneth Casson Leighton)
-
-* automated (quiet) config installation (Andrey)
-
-0.64: Thu Feb 19 23:30:24 PST 1998 Andrew Morgan <morgan@linux.kernel.org>
-
-* miscellaneous patches for building under Solaris (Derrick J Brashear)
-
-* removed STATIC support from a number of module Makefiles.  Notably,
-  these modules are those that use libpwdb and caused difficulties
-  satisfying the build process. (Please submit patches to fix this...;)
-
-* reomved the union for binary packet conversations from
-  (_pam_types.h).  This is now completely implemented in libpam_client.
-
-* Andrey's patch for working environment variable handling in
-  sh_secret module.
-
-* made the libpam_misc conversation function a bit more flexible with
-  respect to binary conversations.
-
-* added top level define (DEBUG_REL) for compiling in the form of
-  a debugging release.  I use this on a Red Hat 4.2 system with little
-  chance of crashing the system as a whole.  (Andrey has another
-  implementation of this -- with a spec file to match..)
-
-0.63: Wed Jan 28 22:55:30 PST 1998 Andrew Morgan <morgan@linux.kernel.org>
-
-* added libpam_client "convention" library.  This makes explicit the
-  use of PAM_BINARY_PROMPT.  It is a first cut, so don't take it too
-  seriously yet.  Comments/suggestions for improvements are very
-  welcome.  Note, this library does not compile by default.  It will
-  be enabled when it is judged stable.  The library comes with two
-  module/agent pairs and can be used with ssh using a patch available
-  from my pre-release directory [where you got this file.]
-
-* backward compatibility patch for libpam/pam_handlers.c (PAM_IGNORE
-  was working with neither "requistie" nor "required") and a DEBUG'ing
-  compile time bug with pam_dispatch.c (Savochkin Andrey Vladimirovich)
-
-* minor Makefile change from (Savochkin Andrey Vladimirovich)
-
-* added pam_afsauth, pam_afspass, pam_restrict, and pam_syslog hooks
-  (Derrick J Brashear)
-
-* pam_access use of uname(2) problematic (security problem
-  highlighted by Olaf Kirch).
-
-* pam_listfile went a bit crazy reading group membersips (problem
-  highlighted by Olaf Kirch and patched independently by Cristian
-  Gafton and Savochkin Andrey Vladimirovich)
-
-* compatibility hooks for solaris and hpux (Derrick J Brashear)
-
-* 64 bit Linux/alpha bug fixed in pam_rhosts (Andrew D. Isaacson)
-
-0.62: Wed Jan 14 14:10:55 PST 1998   Andrew Morgan <morgan@linux.kernel.org>
-
-* Derrick J Brashear's patches: adds the HP stuff missed in the first
-  patch; adds SunOS support; adds support for the Solaris native ld
-  instead of requiring gnu ld.
-
-* last line of .rhosts file need not contain a newline. (Bug reported by
-  Thompson Freeman.)
-
-0.61: Thu Jan  8 22:57:44 PST 1998  Andrew Morgan <morgan@linux.kernel.org>
-
-* complete rewrite of the "control flag" logic.  Formerly, we were
-  limited to four flags: requisite, required, sufficient, optional.
-  We can now use these keywords _and_ a great deal more besides.
-  The extra logic was inspired by Vipin Samar, a preliminary patch was
-  written by Andy Berkheimer, but I "had some ideas of my own" and
-  that's what I've actually included.  The basic idea is to allow the
-  admin to custom build a control flag with a series of token=value
-  pairs inside square brackets.  Eg., '[default=die success=ok]' which
-  is pretty close to a synonym for 'requisite'.  I'll try to document it
-  better in the sys-admin guide but I'm pretty sure it is a change for
-  the better....  If what is in the sys-admin guide is not good enough
-  for you, just take a look at the source for libpam ;^)
-
-0.59: Thu Jan  8 22:27:22 PST 1998 Andrew Morgan <morgan@linux.kernel.org>
-
-* better handling of empty lines in .rhosts file.  (Formerly, we asked
-  the nameserver about them!) Fix from Hugh Daschbach.
-
-* _broke_some_binary_compatibility_ with previous versions to become
-  compliant with X/Open's XSSO spec.  Specifically, this has been
-  by changing the prototype for pam_strerror().
-
-* altered the convention for the conversation mechanism to agree
-  with that of Sun.  (number of responses 'now=' number of messages
-  with help from Cristian for finding a bug.. Cristian also found a
-  nasty speradic segfault bug -- Thanks!)
-
-* added NIS+ support to pam_unix_*
-
-* fixed a "regular file checking" problem with the ~/.rhosts sanity
-  check.  Added "privategroup" option to permit group write permission
-  on the ~/.rhosts file in the case that the group owner has the same
-  name as the authenticating user.  :*) "promiscuous" and "suppress"
-  were not usable!
-
-* added glibc compatibility to pam_rhosts_auth (protected __USE_MISC
-  with #ifndef since my libc already defines it!).
-
-* Security fix from Savochkin Andrey Vladimirovich with suggested
-  modification from Olaf Seibert.
-
-* preC contains mostly code clean-ups and a number of changes to
-  _pam_macros.
-
-0.58: whenever
-
-* pam_getenvlist() has a more robust definition (XSSO) than was previously
-  thought.  It would seem that we no longer need pam_misc_copy_env()
-  which was there to provide the robustness that pam_getenvlist()
-  lacked before...
-
-  Accordingly, I have REMOVED the prototype from libpam_misc. (The
-  function, however, will remain in the library as a wrapper for
-  legacy apps, but will likely be removed from libpam_misc-1.0.) PLEASE
-  FIX YOUR APPS *BEFORE* WE GET THERE!
-
-* Alexy Nogin reported garbage output from pam_env in the case of
-  a non-existent environment variable.
-
-* 'fixed' pwdb compilation for pam_wheel.  Not very cleanly
-  done.. Mmmm. Should really clean up the entire source tree...
-
-* added prototypes for mapping functions
-
-                       <**WARNING**>
-
-  various constants have had there names changed.  Numerical values have
-  been retained but be aware some source old modules/applications will
-  need to be fixed before recompilation.
-
-                       </**WARNING**>
-
-* appended documentation to README for pam_rhosts module (Nicolai
-  Langfeldt).
-
-* verified X/Open compatibility of header files - note, where we differ
-  it is at the level of compilation warnings and the use of 'const char *'
-  instead of 'char *'.  Previously, Sun(X/open) have revised their spec
-  to be more 'const'-ervative in the light of comments from Linux-PAM
-  development.
-
-* Ooops! PAM_AUTHTOKEN_REQD should have been PAM_NEW_AUTHTOK_REQD.
-
-       changed: pam_pwdb(pam_unix_acct) (also bug fix for
-       _shadow_acct_mgmt_exp() return value), pam_stress,
-       libpam/pam_dispatch, blank, xsh.
-
-* New: PAM_AUTHTOK_EXPIRED - password has expired.
-
-* Ooops! PAM_CRED_ESTABLISH (etc.) should have been PAM_ESTABLISH_CRED
-  etc... (changed - this may break some people's modules - PLEASE TAKE
-  NOTE!)
-       changed: pam_group, pam_mail, blank, xsh; module and appl
-       docs, pam_setcred manual page.
-
-* renamed internal _pam_handle structure to be pam_handle as per XSSO.
-
-* added PAM_RADIO_TYPE  (for multiple choice input method).  Also
-  added PAM_BINARY_{MSG,PROMPT} (for interaction out of sight of user
-  - this could be used for RSA type authentication but is currently
-  just there for experimental purposes).  The _BINARY_ types are now
-  usable with hooks in the libpam_misc conversation function. Still
-  have to add PAM_RADIO_TYPE.
-
-* added pam_access module (Alexei Nogin)
-
-* added documentation for pam_lastlog.  Also modified the module to
-  not (by default) print "welcome to your new account" when it cannot
-  find a utmp entry for the user (you can turn this on with the
-  "never" argument).
-
-* small correction to the pam_fail_delay manual page.  Either the appl or
-  the modules header file will prototype this function.
-
-* added "bigcrypt" (DEC's C2) algorithm(0) to pam_pwdb. (Andy Phillips)
-
-* *BSD tweaking for various #include's etc. (pam_lastlog, pam_rhosts,
-  pam_wheel, libpam/pam_handlers). (Michael Smith)
-
-* added configuration directory $SCONFIGED for module specific
-  configuration files.
-
-* added two new "linked" man pages (pam.conf(8) and pam.d(8))
-
-* included a reasonable default for /etc/pam.conf (which can be
-  translated to /etc/pam.d/* files with the pam_conv1 binary)
-
-* fixed the names of the new configuration files in
-   conf/pam_conv1/pam_conv.y
-
-* fixed make check.
-
-* pam_lastlog fixed to handle UID in virgin part of /var/log/lastlog
-  (bug report from Ronald Wahl).
-
-* grammar fix in pam_cracklib
-
-* segfault avoided in pam_pwdb (getting user). Updating of passwords
-  that are directed to a "new" database are more robust now (bug noted
-  by Michael K. Johnson).  Added "unix" module argument for migrating
-  passwords from another database to /etc/passwd. (documentation
-  updated).  Removed "bad username []" warning for empty passwords -
-  on again if you supply the 'debug' module argument.
-
-* ctrl-D respected in conversation function (libpam_misc)
-
-* Removed -DPAM_FAIL_DELAY_ON from top-level Makefile. Nothing in
-  the distribution uses it.  I guess this change happened a while
-  back, basically I'm trying to make the module parts of the
-  distribution "source compatible" with the RFC definition of PAM.
-  This implementation of PAM is a superset of that definition. I have
-  added the following symbols to the Linux-PAM header files:
-
-       PAM_DATA_SILENT (see _pam_types.h)
-       HAVE_PAM_FAIL_DELAY (see _pam_types.h)
-       PAM_DATA_REPLACE (see _pam_modules.h)
-
-  Any module (or application) that wants to utilize these features,
-  should check (#ifdef) for these tokens before using the associated
-  functionality.  (Credit to Michael K. Johnson for pointing out my
-  earlier omission: not documenting this change :*)
-
-* first stab at making modules more independent of full library
-  source.  Modules converted:
-       pam_deny
-       pam_permit
-       pam_lastlog
-       pam_pwdb
-
-* pam_env.c: #include <errno.h> added to ease GNU libc use. (Michael
-  K. Johnson)
-
-* pam_unix_passwd fixes to shadow aging code (Eliot Frank)
-
-* added README for pam_tally
-
-0.57: Fri Apr  4 23:00:45 PST 1997  Andrew Morgan <morgan@parc.power.net>
-
-* added "nodelay" argument to pam_pwdb.  This can be used to turn off
-  the call to pam_fail_delay that takes effect when the user fails to
-  authenticate themself.
-
-* added "suppress" argument to pam_rhosts_auth module. This will stop
-  printing the "rlogin failure message" when the user does not have a
-  .rhosts file.
-
-* Extra fixes for FAKEROOT in Makefiles (Savochkin Andrey
-  Vladimirovich)
-
-* pam_tally added to tree courtesy of Tim Baverstock
-
-* pam_rhosts_auth was failing to read NFS mounted .rhosts
-  files. (Fixed by Peter Allgeyer). Refixed and further enhanced
-  (netgroups) by Nicolai Langfeldt. [Credit also to G.Wilford for some
-  changes that were not actually included..]
-
-* optional (#ifdef PAM_READ_BOTH_CONFS) support for parsing of pam.d/
-  AND pam.conf files (Elliot Lee).
-
-* Added (and signed) Cristian's PGP key. (I've never met him, but I am
-  convinced the key belongs to the guy that is making the PAM rpms and
-  also producing libpwdb. Please note, I will not be signing anyone
-  else's key without a personal introduction..)
-
-* fixed erroneous syslog warning in pam_listfile (Savochkin Andrey
-  Vladimirovich, whole file reformatted by Cristian)
-
-* modified pam_securetty to return PAM_IGNORE in the case that the user's
-  name is not known to the system (was previously, PAM_USER_UNKNOWN). The
-  Rationale is that pam_securetty's sole purpose is to prevent superuser
-  login anywhere other than at the console. It is not its concern that the
-  user is unknown - only that they are _not_ root. Returning
-  PAM_IGNORE, however, insures that the pam_securetty can never be used to
-  "authenticate" a non-existent user. (Cristian Gafton with bug report from
-  Roger Hu)
-
-* Modified pam_nologin to display the no-login message when the user
-  is not known. The return value in this case is still PAM_USER_UNKNOWN.
-  (Bug report from Cristian Gafton)
-
-* Added NEED_LCKPWD for pam_unix/ This is used to define the locking
-  functions and should only be turned on if you don't have them in
-  your libc.
-
-* tidied up pam_lastlog and pam_pwdb: removed function that was never used.
-
-* Note for package maintainers: I have added $(FAKEROOT) to the list of
-  environment variables.  This should help greatly when you build PAM
-  in a subdirectory.  I've gone through the tree and tried to make
-  everything compatible with it.
-
-* added pam_env (courtesy of Dave Kinchlea)
-
-* removed pam_passwd+ from the tree.  It has not been maintained in a
-  long time and running a shell script was basically insecure. I've
-  indicated where you can pick up the source if you want it.
-
-* #define HAVE_PAM_FAIL_DELAY . Applications can conditionally compile
-  with this if they want to see if the facility is available. It is
-  now always available. (corresponding compilation cleanups..)
-
-* _pam_sanitize() added to pam_misc. It purges the PAM_AUTHTOK and
-  PAM_OLDAUTHTOK items. (calls replaced in pam_auth and pam_password)
-
-* pam_rhosts now knows about the '+' entry. Since I think this is a
-  dangerous thing, I have required that the sysadmin supply the
-  "promiscuous" flag for it in the corresponding configuration file
-  before it will work.
-
-* FULL_LINUX_PAM_SOURCE_TREE exported from the top level make file.
-  If you want to build a module, you can test for this to determine if
-  it should take its directions from above or supply default locations
-  for installation. Etc.
-
-0.56: Sat Feb 15 12:21:01 PST 1997 <morgan@parc.power.net>
-
-* pam_handlers.c can now interpret the pam.d/ service config tree:
-       - if /etc/pam.d/ exists /etc/pam.conf is IGNORED
-         (otherwise /etc/pam.conf is treated as before)
-       - given /etc/pam.d/
-         . config files are named (in lower case) by service-name
-         . config files have same syntax as /etc/pam.conf except       
-           that the "service-name" field is not present. (there
-           are thus three manditory fields (and arguments are
-           optional):
-
-               module-type  control-flag  module-path  optional-args...
-
-           )
-
-* included conf/pam_conv1 for converting pam.conf to a pam.d/ version
-  1.0 directory tree. This program reads a pam.conf file on the
-  standard input stream and creates ./pam.d/ (in the local directory)
-  and fills it with ./pam.d/"service-name" files.
-
-       *> Note: It will fail if ./pam.d/ already exists.
-
-  PLEASE REPORT ANY BUGS WITH THIS CONVERSION PROGRAM... It currently
-  cannot retain comments from the old conf file, so take care to do this
-  by hand. Also, please email me with the fix that makes the
-  shift/reduce conflict go away...
-
-* Added default module path to libpam for modules (see pam_handlers.c)
-  it makes use of Makfile defined symbol: DEFAULT_MODULE_PATH which is
-  inhereted from the defs/* variable $(SECUREDIR). Removed module
-  paths from the sample pam.conf file as they are no longer needed.
-
-* pam_pwdb can now verify read protected passwords when it is not run
-  by root.  This is via a helper binary that is setuid root.
-
-* pam_permit now prompts for a username if it is not already determined
-
-* pam_rhosts now honors "debug" and no longer hardwire's "root" as the
-  superuser's name.
-
-* pam_securetty now honors the "debug" flag
-
-* trouble parsing extra spaces fixed in pam_time and pam_group
-
-* added Michael K. Johnson's PGP key to the pgp.keys.asc list
-
-* pam_end->env not being free()'d: fixed
-
-* manuals relocated to section 3
-
-* fixed bug in pam_mail.c, and enhanced to recognize '~' as a prefix
-  to indicate the $HOME of the user (courtesy David
-  Kinchlea). *Changed* from a "session" module to an "auth"
-  module. It cannot be used to authenticate a user, but it can be used
-  in setting credentials.
-
-* fixed a stupid bug in pam_warn.. Only PAM_SERVICE was being read :*(
-
-* pam_radius rewritten to exclusively make use of libpwdb. (minor fix
-  to Makefile for cleaning up - AGM)
-
-* pam_limits extended to limit the total number of logins on a system
-  at any given time.
-
-* libpam and libpam_misc use $(MAJOR_REL) and $(MINOR_REL) to set their
-  version numbers [defined in top level makefile]
-
-* bugfix in sed command in defs/redhat.defs (AGM's fault)
-
-* The following was related to a possibility of buffer overruns in
-  the syslogging code: removed fixed length array from syslogging
-  function in the following modules [capitalized the log identifier
-  so the sysadmin can "know" these are fixed on the local system],
-
-       pam_ftp, pam_stress, pam_rootok, pam_securetty,
-       pam_listfile, pam_shells, pam_warn, pam_lastlog
-  and
-       pam_unix_passwd (where it was definitely _not_ exploitable)
-
-0.55: Sat Jan  4 14:43:02 PST 1997, Andrew Morgan <morgan@parc.power.net>
-
-* added "requisite" control_flag to /etc/pam.conf syntax. [See
-  Sys. Admin. Guide for explanation] changes to pam_handlers.c
-
-* completely new handling of garbled pam.conf lines. The modus
-  operandi now is to assume that any errors in the line are minor.
-  Errors of this sort should *most definitely* lead to the module
-  failing, however, just ignoring the line (as was the case
-  previously) can lead to gaping security holes(! Not foreseen by the
-  RFC). The "motivation" for the RFC's comments about ignoring garbled
-  lines is present in spirit in the new code: basically a garbled line
-  is treated like an instance of the pam_deny.so module.
-  changes to pam_handlers.c and pam_dispatch.c .
-
-* patched libpam, to (a) call _pam_init_handlers from pam_start() and
-  (b) to log a text error if there are no modules defined for a given
-  service when a call to a module is requested. [pam_start() and
-  pam_dispatch() were changed].
-
-* patched pam_securetty to deal with "/dev/" prefix on PAM_TTY item.
-
-* reorganized the modules/Makefile to include *ALL* modules. It is now
-  the responsibility of the modules themselves to test whether they can
-  be compiled locally or not.
-
-* modified pam_group to add to the getgroups() list rather than overwrite
-  it. [In the case of "HAVE_LIBPWDB" we use the pwdb_..() calls to
-  translate the group names.]. Module now pays attention to
-  PAM_CRED_.. flag(!)
-
-* identified and removed bugs in field reading code of pam_time and
-  (thus) pam_group.
-
-* Cristian's patches to pam_listfile module, corresponding change to
-  documentation.
-
-* I've discovered &ero; for sgml!
-  Added pam_time documentation to the admin guide.
-
-* added manual pages: pam.8, pam_start.2(=pam_end.2),
-  pam_authenticate.2, pam_setcred.2, pam_strerror.2,
-  pam_open_session.2(=pam_close_session.2) and pam_chauthtok.2 .
-
-* added new modules:
-
-       - pam_mail (tells the user if they have any new mail
-         and sets their MAIL env variable)
-       - pam_lastlog (reports on the last time this user called
-         this module)
-
-* new module hooks provided.
-
-* added a timeout feature to the conversation function in
-  libpam_misc. Documented it in the application developers' guide.
-
-* fixed bug in pam_misc_paste_env() function..
-
-* slight modifications to wheel and rhosts writeup.
-
-* more security issues added to module and application guides.
-
---
-Things present but not mentioned in previous release (sorry)
-
-* pam_pwdb module now resets the "last_change" entry before updating a
-  password.
---
-
-Sat Nov 30 19:30:20 PST 1996, Andrew Morgan <morgan@parc.power.net>
-
-* added environment handling to libpam. involved change to _pam_types.h
-  also added supplementary functions to libpam_misc
-
-* added pam_radius - Cristian
-
-* slight speed up for pam_rhosts
-
-* significantly enhanced sys-admin documentation (8 p -> 41 p in
-  PostScript). Added to other documentation too.  Mostly the changes
-  in the other docs concern the new PAM-environment support, there is
-  also some coverage of libpam_misc in the App. Developers' guide.
-
-* Cristian's patches to pam_limits and pam_pwdb. Fixing bugs. (MORE added)
-  
-* adopted Cristian's _pam_macros.h file to help with common macros and
-  debugging stuff, gone through tree tidying up debugging lines to use
-  this [not complete].
-
-       - for consistency replaced DROP() with _pam_drop()
-
-* commented memory debugging in top level makefile
-
-* added the following modules
-
-    - pam_warn log information to syslog(3) about service application
-    - pam_ftp  if user is 'ftp' then set PAM_RUSER/PAM_RHOST with password
-    (comment about nologin added to last release's notes)
-
-* modified the pam_listfile module. It now declares a meaningful static
-  structure name.
-
-Sun Nov 10 13:26:39 PST 1996, Andrew Morgan <morgan@parc.power.net>
-
-               **PLEASE *RE*AMEND YOUR PERSONAL LINKS**
-
-  ------->  http://parc.power.net/morgan/Linux-PAM/index.html  <-------
-
-               **PLEASE *RE*AMEND YOUR PERSONAL LINKS**
-
-A brief summary of what has changed:
-
-* many modules have been modified to accomodate fixing the pam_get_user()
-  change. Please take note if you have a module in this distribution.
-
-* pam_unix is now the pam_unix that Red Hat has been using and which
-  should be fairly well debugged.
-
-   - I've added some #ifdef's to make it compile for me, and also
-     updated it with respect to the libpam-0.53, so have a look at the
-     .../modules/pam_unix/Makefile to enable cracklib and shadow features
-
-       ** BECAUSE OF THIS, I cannot guarantee this code works as it **
-       ** did for Red Hat. Please test and report any problems.     **
-
-* the pam_unix of .52 (renamed to pam_pwdb) has been enhanced and made
-  more flexible with by implementing it with respect to the new
-  "Password Database Library" see
-
-       http://parc.power.net/morgan/libpwdb/index.html
-
-  modules included in this release that require this library to
-  function are the following:
-
-       - pam_pwdb (ne pam_unix-0.52 + some enhancements)
-       - pam_wheel
-       - pam_limits
-       - pam_nologin
-
-* Added some optional code for memory debugging. In order to support
-  this you have to enable MEMORY_DEBUG in the top level makefile and
-  also #define MEMORY_DEBUG in your applications when they are compiled.
-  The extra code resides in libpam (compiled if MEMORY_DEBUG is defined)
-  and the macros for malloc etc. are to be found at the end of
-  _pam_types.h
-
-* used above code to locate two memory leaks in pam_unix module and two
-  in libpam (pam_handlers.h)
-
-* pam_get_user() now sets the PAM_USER item. After reading the Sun
-  manual page again, it was clear that it should do this. Various
-  modules have been assuming this and now I have modified most of them
-  to account for this change. Additionally, pam_get_user() is now
-  located in the module include file; modules are supposed to be the
-  ones that use it(!) [Note, this is explicitly contrary to the Sun
-  manual page, but in the spirit of the Linux distribution to date.]
-
-* replaced -D"LINUX" with -D"LINUX_PAM" as this is more explicit and less
-  likely to be confused with -D"linux".
-  Also, modified the libpam #include files to behave more like the Sun
-  ones #ifndef LINUX_PAM.
-
-* removed <bf/ .. / from documentation titles. This was not giving
-  politically correct html..
------ My vvvvvvvvvvvvvvvvvvv was a long time ago ;*] -----
-
-Wed Sep  4 23:57:19 PDT 1996 (Andrew Morgan <morgan@physics.ucla.edu>
-
-0. Before I begin, Linux-PAM has a new primary distribution site (kindly
-donated by Power Net Inc., Los Angeles)
-
-               **PLEASE AMMEND YOUR PERSONAL LINKS**
-
-      ------->  http://www.power.net/morgan/Linux-PAM  <-------
-
-               **PLEASE AMMEND YOUR PERSONAL LINKS**
-
-1. I'm hoping to make the next release a bug-fix release... So please find
-   all the bugs(! ;^)
-
-2. here are the changes for .52:
-
-* minor changes to module documentation [Incidently, it is now
-  available on-line from the WWW page above]. More changes to follow in
-  the next two releases. PLEASE EMAIL me or the list if there is
-  anything that isn't clear!
-
-* completely changed the unix module. Now a single module for all four
-  management groups (this meant that I could define all functions as
-  static that were not part of the pam_sm_... scheme. AGM)
-
-  - Shadow support added
-PASSWD  - Elliot's account management included, and enhanced by Cristian Gafton.
-  - MD5 password support added by Cristian Gafton.
-  - maxtries for authentication now enforced.
-  - Password changing function in pam_unix now works!
-    Although obviously, I'm not going to *guarantee* it ;^) .
-  - stole Marek's locking code from the Red Hat unix module.
-    [ If you like you can #ifdef it in or out ... ]
-
-    You can configure the module more from its Makefile in
-    0.52/modules/pam_unix/
-
-    If you are nervous that it will destroy your /etc/passwd or shadow
-    files then EDIT the 0.52/modules/pam_unix/pam_unix_pass.-c file.
-    Here is the warning comment from this file...
-
--------------8<-----------------
-/*                           <WARNING>
- *
- * Uncomment the following #define if you are paranoid, and do not
- * want to risk losing your /etc/passwd or shadow files.
- * It works for me (AGM) but there are no guarantees.
- *
- *                          </WARNING>
- */
-/* #define TMP__FILE */
-------------->8-----------------
-
-  *** If anyone has any trouble, please *say*. Your problem will be
-      fixed in the next release. Also please feel free to scour the
-      code for race conditions etc... 
-
-[* The above change requires that you purge your /usr/lib/security
-   directory of the old pam_unix_XXX.so modules: they will NOT be deleted
-   with a 'make remove'.]
-
-* the prototype for the cleanup function supplied to pam_set_data used
-  to return "int". According to Sun it should be "void". CHANGED.
-
-* added some definitions for the 'error_status' mask values that are
-  passed to the cleanup function associated with each
-  module-data-item. These numbers were needed to keep up with changing
-  a data item (see for example the code in pam_unix/support.-c that
-  manages the maximum number of retries so far). Will see what Sun says
-  (current indications are positive); this may be undone before 1.0 is
-  released.  Here are the definitions (from pam_modules.h).
-
-#define PAM_DATA_SILENT    0x40000000     /* used to suppress messages... */
-#define PAM_DATA_REPLACE   0x20000000     /* used when replacing a data item */
-
-* Changed the .../conf/pam.conf file. It now points to the new
-  pam_unix module for 'su' and 'passwd' [can get these as SimpleApps --
-  I use them for testing. A more extensive selection of applications is
-  available from Red Hat...]
-
-* corrected a bug in pam_dispatch. Basically, the problem was that if
-  all the modules were "sufficient" then the return value for this
-  function was never set. The net effect was that _pam_dispatch_aux
-  returned success when all the sufficient modules failed. :^( I think
-  this is the correct fix to a problem that the Red Hat folks had
-  found...
-
-sopwith* Removed advisory locking from libpam (thanks for the POSIX patch
-  goes to Josh Wilmes's, my apologies for not using it in the
-  end.). Advisory locking did not seem sufficiently secure for libpam.
-  Thanks to Werner Almesberger for identifying the corresponding "denial
-  of service attack". :*(
-
-* related to fix, have introduced a lock file /var/lock/subsys/PAM
-  that can be used to indicate the system should pay attention to
-  advisory locking on /etc/pam.conf file. To implement this you need to
-  define PAM_LOCKING though. (see .52/libpam)
-
-* modified pam_fail_delay() function. Couldn't find the "not working"
-  problem indicated by Michael, but modified it to do pseudo-random
-  delays based on the values indicated by pam_fail_delay() -- the
-  function "that may eventually go away"... Although Sun is warming to
-  the idea.
-
-* new modules include:
-
-       pam_shells    - authentication for users with a shell listed in
-                       /etc/shells. Erik Troan <ewt@redhat.com>
-
-       pam_listfile  - authentication based on the contents of files.
-                       Set to be more general than the above in the
-                       future. UNTESTED. Elliot Lee <@redhat.com>
-                       [Note, this module compiles with a non-trivial
-                       warning: AGM]
-
-Thu Aug  8 22:32:15 PDT 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* modified makefiles to take more of their installation instructions
-  from the top level makefile. Desired for integration into the Debian
-  distribution, and generally a good idea.
-
-* fixed memory arithmetic in pam_handlers
-  -- still need to track down why failure to load modules can lead to
-  authentication succeding..
-
-* added tags for new modules (smartcards from Alex -- just a promise
-  at this stage) and a new module from Elliot Lee; pam_securetty
-
-* I have not had time to smooth out the wrinkles with it, but Alex's
-  pam_unix modifications are provided in pam_unix-alex (in the modules
-  directory) they will not be compiled by 'make all' and I can't even
-  say if they do compile... I will try to look at them for .52 but, in
-  the mean time please feel free to study/fix/discuss what is there.
-
-* pam_rhosts module. Removed code for manually setting the ruser
-  etc. This was not very secure.
-
-* [remade .ps docs to be in letter format -- my printer complains
-  about a4]
-
-Sunday July, 7 12:45:00 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* No longer accompanying the Linux-PAM release with apps installed.
-  [Will provide what was here in a separate package.. (soon)
-lib   Also see http://www.redhat.com/pam for some more (in .rpm form...)]
-
-* renamed libmisc to libpam_misc. It is currently configured to only compile
-  the static library. For some strange reason (perhaps someone can
-  investigate) my Linux 2.0.0 kernel with RedHat 3.0.3 system
-  segfaults when I compile it to be a dynamic library. The segfault
-  seems to be inside the call to the ** dl_XXX ** function...!?
-
-  There is a simple flag in the libpam_misc/Makefile to turn on dynamic
-  compiles.
-
-* Added a little unofficial code for delay support in libpam (will probably
-  disappear later..) There is some documentation for it in the pam_modules
-  doc now. That will obviously go too.
-
-* rewritten pam_time to use *logic* to specify the stringing together of
-  users/times/terminals etc.. (what was there before was superficially
-  logical but basically un-predictable!)
-
-* added pam_group. Its syntax is almost identical to pam_time but it
-  has another field added; a list of groups to make the user a member
-  of if they pass the previous tests. It seems to not co-exist too well
-  with the groups in the /etc/group but I hope to have that fixed by
-  the next release...
-
-* minor re-formatting of pam_modules documentation
-
-* removed ...// since it wasn't being used and didn't look like it
-  would be!
-
-GCCSunday 23 22:35:00 PST 1996   (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* The major change is the addition of a new module: pam_time for
-  restricting access on terminals at given times for indicated users
-  it comes with its own configuration file /etc/security/time.conf
-  and the sample file simply restricts 'you' from satisfying the blank
-  application if they try to use blank from any tty*
-
-* Small changes include
-- altered pam.conf to demonstrate above new module (try typing username: you)
-- very minor changes to the docs (pam_appl and pam_modules)
-
-Saturday June 2 01:40:00 PST 1996  (Andrew Morgan <morgan@physics.ucla.edu>)
-
-*** PLEASE READ THE README, it has changed ***
-
-* NOTE, 'su' exhibits a "system error", when static linking is
-  used. This is because the pam_unix_... module currently only has
-  partial static linking support. This is likely to change on Monday
-  June 3, when Alex makes his latest version availible. I will include
-  the updated module in next release.
-
-changes for .42:
-
-* modified the way in which libpam/pam_modules.h defines prototypes for
-  the pam_sm_ functions. Now the module must declare which functions it
-  is to provide *before* the #include <security/pam_modules.h> line.
-  (for contrasting examples, see the pam_deny and pam_rootok modules)
-  This removed the ugly hack of defining functions that are never called
-  to overcome  warnings... This seems much tidier.
-insterted* updated the TODO list. (changed mailing list address)
-* updated README in .../modules to reflect modifications to static
-  compliation protocol
-* modified the pam_modules documentation to describe this.
-* corrected last argument of pam_get_item( ... ) in
-  pam_appl/modules.sgml, to "const void **".
-* altered GNU GPL's in the documentation, and various other parts of
-  the distribution. *Please check* that any code you are responsible for
-  is corrected.
-* Added ./Copyright (please check that it is acceptable)
-* updated ./README to make current and indicate the new mailing list
-  address
-* have completely rewritten pam_filter. It now runs modular filter
-  executables (stored in /usr/sbin/pam_filter/) This should make it
-  trivial for others to write their own filters.. If you want yours
-  included in the distribution please email the list/me.
-* changes to libpam; there was a silly bug with multiple arguments on a
-  pam.conf line that was broken with a '\<LF>'.
-* 'su' rearranged code (to make better use of PAM)
-  *Also* now uses POSIX signals--this should help the Alpha port.
-* 'passwd' now uses getlogin() to determine who's passwords to change.
-
-Sunday May 26 9:00:00 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* fixed module makefiles to create needed dynamic/static subdirectories
-
-Saturday May 25 20:30:27.8 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* LOTS has changed regarding how the modules/libpam are built.
-*  Michael's mostly complete changes for static support--see below
-  (Andrew got a little carried away and automated the static linking
-  of modules---bugs are likely mine ;( )
-* Thanks mostly to Michael, libpam now compiles without a single warning :^]
-* made static modules/library optional.
-CFLAGS* added 'make sterile' to top level makefile. This does extraclean and remove
-* added Michael and Joseph to documentation credits (and a subsection for
-  future documentation of static module support in pam_modules.sgml)
-* libpam; many changes to makefiles and also automated the inclusion of
-  static module objects in pam_static.c
-* modified modules for automated static/dynamic support. Added static & 
-  dynamic subdirectories, as instructed by Michael
-* removed an annoying syslog message from pam_filter: "parent exited.."
-* updated todo list (anyone know anything about svgalib/X? we probably should
-  have some support for these...)
-
-Friday May 24 16:30:15 EDT 1996 (Michael K. Johnson <johnsonm@redhat.com>)
-
-* Added first (incomplete) cut at static support.
-  This includes:
-   . changes in libpam, including a new file, pam_static.c
-   . changes to modules including exporting struct of function pointers
-   . static and dynamic linking can be combined
-   . right now, the only working combinations are just dynamic
-     linking and dynamic libpam.so with static modules linked
-     into libpam.so.  That's on the list of things to fix...
-   . modules are built differently depending on whether they
-     are static or dynamic.  Therefore, there are two directories
-     under each module directory, one for static, and one for
-     dynamic modules.
-* Fixed random brokenness in the Makefiles.  [ foo -nt bar ] is
-  rather redundant in a makefile, for instance.  Also, passing
-   on the command line is broken because it cannot be
-  overridden in any way (even adding important parts) in lower-level
-  makefiles.
-* Unfortunately, fixing some of the brokenness meant that I used
-  GNU-specific stuff.  However, I *think* that there was GNU-specific
-  stuff already.  And I think that we should just use the GNU
-  extensions, because any platform that GNU make doesn't port to
-  easily will be hard to port to anyway.  It also won't be likely
-passwd  to handle autoconf, which was Ted's suggestion for getting
-  around limitations in standard make...
-  For now, I suggest that we just use some simple GNU-specific
-  extensions.
-
-Monday May 20 22:00:00 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* added some text to pam_modules.sgml
-* corrected Marek's name in all documentation
-* made pam_stress conform to chauthtok conventions -- ie can now request
-  old password before proceeding.
-* included Alex's latest unix module
-* included Al's + password strength checking module
-* included pam_rootok module
-* fixed too many bugs in libpam.. all subtly related to the argument lists
-  or use of syslog. Added more debugging lines here too.
-* fixed the pam.conf file
-* deleted pam_test module. It is pretty old and basically superceeded
-  by pam_stress
-
-Friday May 9 1:00:00 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* updated documentaion, added Al Longyear to credits and corrected the
-  spelling of Jeff's name(!). Most changes to pam.sgml (even added a figure!)
-* new module pam_rhosts_auth (from Al Longyear)
-* new apps rlogind and ftpd (a patch) from Al.
-* modified 'passwd' to not call pam_authenticate (note, none of the
-  modules respect this convention yet!)
-* fixed bug in libpam that caused trouble if the last line of a
-  pam.conf file ends with a module name and no newline character
-* also made more compatable with documentation, in that bad lines in
-  pam.conf are now ignored rather than causing libpam to return an
-  error to the app.
-* libpam now overwrites the AUTHTOKs when returning from
-  pam_authenticate and pam_chauthtok calls (as per Sun/RFC too)
-* libpam is now installed as libpam.so.XXX in a way that ldconfig can
-  handle!
-
-
-Wednesday May 1 22:00:00 PST 1996 (Andrew Morgan <morgan@physics.ucla.edu>)
-
-* removed .../test directory, use .../examples from now on.
-* added .../apps directory for fully functional applications
-  - the apps directory contains directories that actually contain the apps.
-    the idea is to make application compilation conditional on the presence
-    of the directory. Note, there are entries in the Makefile for
-    'login' and 'ftpd' that are ready for installation... Email me if
-    you want to reserve a directory name for an application you are
-    working on...
-* similar changes to .../modules makefile [entries for pam_skey and
-  pam_kerberos created---awaiting the directories.] Email me if you
-  want to register another module...
-* minor changes to docs.. Not really worth reprinting them quite yet!
-  [save the trees]
-* added misc_conv to libmisc. it is a generic conversation function
-  for text based applications. [would be nice to see someone create
-  an Xlib and/or svgalib version]
-* fixed ctrl-z/c bug with pam_filter module [try xsh with the default
-  pam.conf file]
-* added 'required' argument to 'pam_stress' module.
-* added a TODO list... other suggestions to the list please.
-
-Saturday April 7 00:00:00 PST 1996 ( Andrew Morgan <morgan@physics.ucla.edu> )
-
-* Alex and Marek please note I have altered _pam_auth_unix a little, to
-  make it get the passwords with the "proper method" (and also fixed it
-  to not have as many compiler warnings)
-* updated the conf/pam.conf file
-* added new example application examples/xsh.c (like blank but invokes
-  /bin/sh)
-* Marc's patches for examples/blank.c (and AGM's too)
-* fixed stacking of modules in libpam/pam_handlers.c
-* fixed RESETing in libpam/pam_item.c
-* added new module modules/pam_filter/ to demonstrate the possibility
-  of inserting an arbitrary filter between the terminal and the
-  application that could do customized logging etc... (see use of
-  bin/xsh as defined in conf/pam.conf)
-
-
-Saturday March 16 19:00:00 PST 1996 ( Andrew Morgan <morgan@physics.ucla.edu> )
-
-These notes are for 0.3 I don't think I've left anything important
-out, but I will use emacs 'C-x v a' next time! (Thanks Jeff)
-
-       * not much has changed with the functionality of the Linux-PAM lib
-         .../libpam
-               - pam_password calls module twice with different arguments
-               - added const to some of the function arguments
-               - added PAM_MAX_MES_ to <security/_pam_types.h>
-               - was a lot over zealous about purging old passwords...
-                 I have removed much of this from source to make it
-                 more compatible with SUN.
-               - moved some PAM_... tokens to pam_modules.h from _pam_types.h
-                 (no-one should notice)
-
-       * added three modules: pam_permit pam_deny pam_stress
-         no prizes for guessing what the first two do. The third is
-         a reasonably complete (functional) module. Is intended for testing
-         applications with.
-
-       * fixed a few pieces of examples/blank.c so that it works (with
-         pam_stress)
-
-       * ammended the documentation. Looking better, but suggestions/comments
-         very welcome!
-
-Sunday March 10 10:50:00 PST 1996 ( Andrew Morgan <morgan@physics.ucla.edu> )
-
-These notes are for Linux-PAM release 0.21.  They cover what's changed
-since I relased 0.2.
-
-       * am now using RCS
-       * substantially changed ./README
-       * fixed bug reading \\\n in pam.conf file
-       * small changes to documentation
-       * added `blank' application to ./examples (could be viewed as
-         a `Linux-PAM aware' application template.)
-       * oops. now including pam_passwd.o and pam_session.o in pamlib.so
-       * compute md5 checksums for all the source when making a release
-           - added `make check' and `make RCScheck' to compute md5 checksums
-       * create a second tar file with all the RCS files in.
-       * removed the .html and .txt docs, supplying sgml sources instead.
-           - see README for info on where to get .ps files
-
-Thursday March 6 0:44:?? PST 1996 ( Andrew Morgan <morgan@physics.ucla.edu> )
-
-These notes are for Linux-PAM release 0.2.  They cover what's changed
-since Marc Ewing relased 0.1.
-
-**** Please note. All of the directories in this release have been modified
-**** slightly to conform to the new pamlib. A couple of new directories have
-**** been added. As well as some documentation. If some of your code
-**** was in the previous release. Feel free to update it, but please
-**** try to conform to the new headers and Makefiles.
-
-* Andrew Morgan (morgan@physics.ucla.edu) is making this release
- availible, Marc has been busy...!
-
-* Marc's pam-0.1/lib has been (quietly) enhanced and integrated into
- Alex Yurie's collected tree of library and module code
- (linux-pam.prop.1.tar.gz). Most of the changes are to do with error
- checking. Some more robustness in the reading of the pam.conf file
- and the addition of the pam_get_user() function.
-
-* The pam_*.h files have been reorganized to logically enforce the
- separation of modules from applications. [Don't panic! Apart from
- changing references of the form
-
-       #include "pam_appl.h"
-
- to
-
-       #include <security/pam_appl.h>
-
- The reorganization should be backwardly compatable (ie. a module
- written for SUN will be as compatable as it was before with the
- previous version ;)~ ]
-
- (All of the source in this tree now conforms to this scheme...)
-
- The new reorganization means that modules can be compiled with a
- single header, <security/pam_modules.h>, and applications with
- <security/pam_appl.h>.
-
-* I have tried to remove all the compiler warnings from the updated
- "pamlib/*.c" files. On my system, (with a slightly modified <dlfcn.h>
- email me if it interests you..) there are only two warnings that
- remain: they are that ansi does not permit void --> fn ptr
- assignment. K&Rv2 doesn't mention this....? As a matter of principle,
- if anyone knows how to get rid of that warning... please
- tell. Thanks! "-pedantic"
-
-* you can "make all" as a plain user, but
-
-* to "make install" you must be root. The include files are placed in
- /usr/include/security. The libpam.so library is installed in /usr/lib
- and the modules in /usr/lib/security. The two test binaries
- are installed in the Linux-PAM-0.2/bin directory and a chance is given to
- replace your /etc/pam.conf file with the one in Linux-PAM-0.2/conf.
-
-* I have included some documentation (pretty preliminary at the
-moment) which I have been working on in .../doc .
-
-I have had a little trouble with the modules, but atleast there are no
-segfaults! Please try it out and discuss your results... I actually
-hope it all works for you. But, Email any bugs/suggestions to the
-Linux-PAM list: linux-pam@mit.edu .....
-
-Regards,
-
-Andrew Morgan
-(morgan@physics.ucla.edu)
-
-
-Sat Feb 17 17:30:24 EST 1996 (Alexander O. Yuriev alex@bach.cis.temple.edu)
-
-       * conf directory created with example of pam_conf
-       * stable code from pam_unix is added to modules/pam_unix
-       * test/test.c now requests username and password and attempts
-         to perform authentication
-
diff --git a/contrib/libpam/Copyright b/contrib/libpam/Copyright
deleted file mode 100644 (file)
index 2f27a2e..0000000
+++ /dev/null
@@ -1,41 +0,0 @@
-Unless otherwise *explicitly* stated the following text describes the
-licensed conditions under which the contents of this Linux-PAM release
-may be distributed:
-
--------------------------------------------------------------------------
-Redistribution and use in source and binary forms of Linux-PAM, with
-or without modification, are permitted provided that the following
-conditions are met:
-
-1. Redistributions of source code must retain any existing copyright
-   notice, and this entire permission notice in its entirety,
-   including the disclaimer of warranties.
-
-2. Redistributions in binary form must reproduce all prior and current
-   copyright notices, this list of conditions, and the following
-   disclaimer in the documentation and/or other materials provided
-   with the distribution.
-
-3. The name of any author may not be used to endorse or promote
-   products derived from this software without their 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 conflict 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(S) 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.
--------------------------------------------------------------------------
-
diff --git a/contrib/libpam/FREEBSD-Xlist b/contrib/libpam/FREEBSD-Xlist
deleted file mode 100644 (file)
index 3311032..0000000
+++ /dev/null
@@ -1,18 +0,0 @@
-*.a
-*.asc
-*.o
-*.so
-*.tar.gz
-*/.[a-zA-Z]*
-*/CONFIGURE_COMMAND
-*/bin/pam_conv1
-*/blank
-*/blank
-*/check_user
-*/check_user
-*/default.defs
-*/dynamic
-*/pam_conv1/pam_conv1
-*/upperLOWER/upperLOWER
-*/xsh
-*/xsh
diff --git a/contrib/libpam/FREEBSD-upgrade b/contrib/libpam/FREEBSD-upgrade
deleted file mode 100644 (file)
index 3f3b379..0000000
+++ /dev/null
@@ -1,9 +0,0 @@
-To strip down a new version of Linux PAM for import, extract
-the files like this:
-
-    tar -xvzf pam-xxx.tar.gz -X FREEBSD-Xlist
-
-If you decide to bring in more of the files, import them -- don't
-use "cvs add".  And please remember to adjust the contents of
-"FREEBSD-Xlist" so that it reflects what is really imported from
-the vendor.
diff --git a/contrib/libpam/Makefile b/contrib/libpam/Makefile
deleted file mode 100644 (file)
index 33eaae0..0000000
+++ /dev/null
@@ -1,284 +0,0 @@
-##
-## $Id: Makefile,v 1.31 1997/04/05 07:04:25 morgan Exp morgan $
-## $FreeBSD: src/contrib/libpam/Makefile,v 1.1.1.1.6.2 2001/06/11 15:28:09 markm Exp $
-## $DragonFly: src/contrib/libpam/Attic/Makefile,v 1.2 2003/06/17 04:24:02 dillon Exp $
-##
-## $Log: Makefile,v $
-##
-##
-
-# major and minor numbers of this release
-MAJOR_REL=0
-MINOR_REL=65
-DEBUG_REL=no
-#DEBUG_REL=yes
-
-# this should be the name of this directory
-RELNAME = Linux-PAM-$(MAJOR_REL).$(MINOR_REL)
-
-# this is the name of the archive file
-DISTFILE = $(RELNAME).tar.gz
-
-# define this to indicate to subdirectories that they are part of the 
-# full source tree.
-FULL_LINUX_PAM_SOURCE_TREE=yes
-export FULL_LINUX_PAM_SOURCE_TREE
-
-DYNLOAD="dl"
-DYNTYPE="so"
-
-# Comment out either line to disable that type of linking for *modules only*
-# Both at once is a legal configuration!
-DYNAMIC=-DPAM_DYNAMIC
-#STATIC=-DPAM_STATIC
-
-# Comment out these lines to disable building dynamic/static libpam.*
-DYNAMIC_LIBPAM=yes
-#STATIC_LIBPAM=yes
-
-# All combinations of the above four variable definitions are legal,
-# however, not defining either dynamic or static modules and yet
-# creating a some flavor of LIBPAM will make an authentication library
-# that always fails!
-
-# Here we indicate which libraries are present on the local system
-# they control the building of some modules in this distribution
-# Note, these definitions are all "export"ed below...
-
-HAVE_PWDBLIB=no
-HAVE_CRACKLIB=no
-HAVE_AFSLIBS=no
-HAVE_KRBLIBS=no
-
-# NB. The following is the generic defines for compilation.
-# They can be overridden in the default.defs file below
-#
-WARNINGS = -ansi -D_POSIX_SOURCE -Wall -Wwrite-strings \
-        -Wpointer-arith -Wcast-qual -Wcast-align \
-        -Wtraditional -Wstrict-prototypes -Wmissing-prototypes \
-        -Wnested-externs -Winline -Wshadow -pedantic
-PIC=-fPIC
-
-# Mode to install shared libraries with
-SHLIBMODE=644
-
-#
-# Conditional defines..
-#
-
-ifdef DYNAMIC
-# need the dynamic library functions
-LIBDL=-l$(DYNLOAD)
-ifdef STATIC_LIBPAM
-# needed because pam_xxx() fn's are now in statically linked library
-RDYNAMIC = -rdynamic
-endif
-endif
-
-# Here we include the defines for the preferred operating system
-# these include things like CC, CFLAGS and destination directories 
-# etc.. By default, this is a symbolic link to one of the .defs files
-# the .../defs/ directory. Please take a moment to check that you are
-# using the correct one.
-
-include default.defs
-
-# to turn on the fprintf(stderr, ..) debugging lines throughout the
-# distribution uncomment this line
-#EXTRAS += -DDEBUG
-
-# For serious memory allocation tracing uncomment the following
-#MEMORY_DEBUG=-DMEMORY_DEBUG
-
-#######################################################################
-# The pam_unix module in this file will not work on NIS based systems.#
-#######################################################################
-
-# ////////////////////////////////////////////////////
-# // You should not modify anything below this line //
-# ////////////////////////////////////////////////////
-
-# the sub-directories to make things in
-
-DIRS = modules libpam conf libpam_misc examples
-
-#
-# basic defines
-#
-
-INCLUDEDIR=-I$(shell pwd)/include
-PAMLIB=-L$(shell pwd)/libpam
-PAMMISCLIB=-L$(shell pwd)/libpam_misc
-ifeq ($(DEBUG_REL),yes)
- PAMLIB += -lpamd
- PAMMISCLIB += -lpamd_misc
-else
- PAMLIB += -lpam
- PAMMISCLIB += -lpam_misc
-endif
-
-
-# This is Linux-PAM and not a version from Sun etc..
-# [Note, this does not describe the operating system you are using
-# only that you are compiling the "Linux" (read FREE) implementation
-# of Pluggable Authentication Modules.
-EXTRAS += -DLINUX_PAM
-
-#
-# build composite defines
-#
-
-LOADLIBES = $(PAMLIB) $(RDYNAMIC) $(PAMMISCLIB) $(LIBDL) $(ULIBS)
-
-CFLAGS += $(EXTRAS) $(MEMORY_DEBUG) $(WARNINGS) $(INCLUDEDIR) $(PIC)
-ifneq ($(strip $(OS)),)
-CFLAGS += -D$(OS)
-endif
-ifneq ($(strip $(ARCH)),)
-CFLAGS += -D$(ARCH)
-endif
-
-#
-# export the libraries-available info; the modules should know how
-# to deal with this...
-#
-export HAVE_PWDBLIB            
-export HAVE_CRACKLIB
-export HAVE_AFSLIBS
-export HAVE_KRBLIBS
-
-#
-# generic exports
-#
-export MAJOR_REL                # the major release of this distribution
-export MINOR_REL               # the minor release of this distribution
-export DEBUG_REL               # for installing a debugging version of PAM
-export OS                      # operating system
-export ARCH                    # architecture
-export CC                      # the C compiler
-export INSTALL                 # to do instalations with
-export MKDIR                   # to ensure directories exist
-export CFLAGS                  # CC flags used to compile everything
-export LD_D                    # build a shared object file (module)
-export LD_L                    # build a shared library (e.g. libpam)
-export USESONAME               # does shlib link command require soname option
-export SOSWITCH                        # shlib lib soname switch name
-export NEEDSONAME              # does shared library link need versioned lib
-export LD                      # build a generic library
-export LDCONFIG                        # rebuild the shared libraries
-export AR                      # build a static library
-export RANLIB                  # reorder a static library
-export LOADLIBES               # libraries needed for application linking
-export PAMLIB                  # where to find the local libpam.xx file
-export DYNTYPE                 # which suffix is used for libraries
-export SHLIBMODE               # file mode for shared objects
-#
-# where to install things
-#
-export FAKEROOT                        # for package maintainers
-#
-export PREFIX                  # basic prefix for all other directories
-export SUPLEMENTED             # where to store module helper binaries
-export LIBDIR                  # where libpam and libpam_misc go
-export SECUREDIR               # where the modules will be placed
-export INCLUDED                        # where to store pam---.h files
-export CONFIGED                        # where pam.conf and pam.d/ go
-export SCONFIGED               # where modules' config files go
-
-#
-# Conditional exporting ( ... these go on for a while... )
-#
-ifdef DYNAMIC 
-export DYNAMIC
-endif
-ifdef STATIC
-export STATIC
-endif
-ifdef DYNAMIC_LIBPAM
-export DYNAMIC_LIBPAM
-endif
-ifdef STATIC_LIBPAM
-export STATIC_LIBPAM
-endif
-ifdef MEMORY_DEBUG
-export MEMORY_DEBUG
-endif
-
-##
-## the rules
-##
-
-all: .freezemake
-       @for i in $(DIRS) ; do \
-               $(MAKE) -C $$i all ; \
-               if [ $$? -ne 0 ]; then break ; fi ; \
-       done
-
-.freezemake:
-# Do nothing
-
-.old_freezemake: Makefile
-       @touch .freezemake
-       @echo "*WARNING*: If you are running a system that is dependent"
-       @echo "  on PAM to work. DO NOT make sterile NOR make remove."
-       @echo "  These options will delete the PAM files on your system"
-       @echo "  and make it unusable!"
-       @echo ""
-       @echo "If you are in any doubt, just do 'make all' (or just"
-       @echo "'make'). It is likely that this is the SAFEST thing to do...."
-       @exit 1
-
-install:
-       @for i in $(DIRS) ; do \
-               $(MAKE) -C $$i install ; \
-               if [ $$? -ne 0 ]; then break ; fi ; \
-       done
-       install ./doc/man/*.3 $(PREFIX)/man/man3/
-       install ./doc/man/*.8 $(PREFIX)/man/man8/
-
-sterile: .freezemake
-       @$(MAKE) remove
-       @$(MAKE) extraclean
-
-remove: .freezemake
-       @for i in $(DIRS) ; do \
-               $(MAKE) -C $$i remove ; \
-       done
-
-clean:
-       @rm -f *~ core
-       @for i in $(DIRS) ; do \
-               $(MAKE) -C $$i clean ; \
-       done
-
-extraclean:
-       @for i in $(DIRS) doc; do \
-               $(MAKE) -C $$i extraclean ; \
-       done
-
-check:
-       @$(MAKE) -C conf check
-
-RCScheck:
-       @$(MAKE) -C conf RCScheck
-
-# this can be used to see what hasn't been check'd into RCS
-
-open:
-       @find . \( -type f -a -perm 644 \) -print
-
-release:
-       @egrep '^DEBUG\_REL\=yes' Makefile|grep -v grep > /dev/null ;\
-               if [ $$? -eq 0 ]; then \
-               echo "You should first set DEBUG_REL to no" ; exit 1 ; fi
-       $(MAKE) extraclean
-       rm -f .freezemake
-       touch .filelist .RCSlist
-       chmod 600 .filelist .RCSlist
-       cd .. ; find $(RELNAME) \! -type d -print | fgrep -v RCS | fgrep -v 'conf/.md5sum' > $(RELNAME)/.filelist
-       cd .. ; find $(RELNAME) -type f -print | fgrep RCS | fgrep -v 'conf/.RCSsum' > $(RELNAME)/.RCSlist
-       chmod 400 .filelist .RCSlist
-       $(MAKE) check
-       $(MAKE) RCScheck
-       (cat .filelist ; echo $(RELNAME)/conf/.md5sum) | (cd .. ; tar -cz -f$(DISTFILE) -T-)
-       (cat .RCSlist ; echo $(RELNAME)/conf/.RCSsum) | (cd .. ; tar -cz -fRCS+$(DISTFILE) -T-)
diff --git a/contrib/libpam/README b/contrib/libpam/README
deleted file mode 100644 (file)
index d78dc2e..0000000
+++ /dev/null
@@ -1,169 +0,0 @@
-#
-# $Id: README,v 1.14 1997/04/05 07:04:46 morgan Exp $
-# $FreeBSD: src/contrib/libpam/README,v 1.1.1.1.6.2 2001/06/11 15:28:09 markm Exp $
-# $DragonFly: src/contrib/libpam/Attic/README,v 1.2 2003/06/17 04:24:02 dillon Exp $
-#
-
-Hello!
-
-Thanks for downloading Linux-PAM-0.65.
-
---------------------------------------------------------------------
-Before you begin:
-
-  * This distribution requires GNU's Make
-  * It requires GNU's C-compiler: gcc (and 'ld')
-  * it also requires the GNU shell: bash
-  * some of the modules require the presence of libpwdb see redhat
-  * two modules have some need for libcrack too..
-
---------------------------------------------------------------------
-[
-Zeroth (optional) thing to do: check the detatched "pgp" signature for
-this distribution file, it should be signed by
-
-Type Bits/KeyID    Date       User ID
-pub  1024/2A398175 1996/11/17 Andrew G. Morgan <morgan@linux.kernel.org>
-]
-
-First thing to do (I assume you have successfully unpacked it!) is to
-run:
-
-    make check                           [ requires md5sum to be present ]
-
-This will also check that the distribution has arrived intact. [
-Later, If you change some things, running this command from this
-directory will show you what files you have altered. ]
-
-If you choose to get and install the RCS files that accompany this
-release, you may also run
-
-       make RCScheck
-
-from this directory.
-
-Next, you should check the symbolic link
-
-       .../Linux-PAM-X.YY/default.defs
-
-points to the file that best describes your system. The various *.defs
-files that are included in this distribution are to be found in the
-directory:
-
-       .../Linux-PAM-X.YY/defs/
-
-This should configure the distribution to compile on your system. The
-default is the version I use for maintaining the distribution. [If you
-don't find one that suits your needs, please try to create one, email
-it to me and I will include it in a future release.]
-
-If you are running an ELF based Linux system you should be able to
-compile the distribution straight from the box. If you are running an
-a.out based system, then some of the functionality of Linux-PAM will
-be unavailable to you. Instead, you must switch the DYNAMIC variables
-*off* in your "defs" file: comment out the DYNAMIC and DYNAMIC_LIBPAM
-defines and uncomment the STATIC and STATIC_LIBPAM defines. NOTE, for
-ELF based systems, almost any combination of these four definitions is
-legal... If you have ELF, I recommend the default however.
-
-Second, try to compile it. Use the following command in *this*
-directory:
-
-       make
-
-[ or 'make all' if you prefer ]. The first time you type make, it is
-likely to complain. This is to remind you to remove any libraries from
-previous versions of the distribution that are likely to confuse this
-make... Type 'make' again.
-
-Before you do the third thing. You should think about whether you want
-the default configuration scripts to be installed or not. If you have
-a working PAM based system you probably do *not* want this.. Whatever,
-before Linux-PAM installs the default scripts you will be prompted as
-to whether it is a good idea. Be sure to say NO if you are worried!
-** You have been warned. **
-
-Third, to install the stuff you need to be root. Do the following:
-
-       su -c "make install"
-
-If everything has worked as intended there should now be
-
-       some executables                in      ./bin/
-       some filters for pam_filter     in      /usr/sbin/pam_filter/
-       some configuration files:
-               /etc/pam.conf
-               /etc/security/*.conf
-       libpam_misc.a (static library)  in      /usr/lib/
-
-In addition:
-
-    if dynamically linked:
-
-       libpam.so.XXX (shared library)          in      /usr/lib/
-       libpam_misc.so.XXX (shared library)     in      /usr/lib/
-       pam_*.so (modules)                      in      /usr/lib/security/
-
-    if statically linked:
-
-       libpam.a (static library)       in      /usr/lib/
-
-[These are the default directories that I use. Your own system may
-differ as specified in your XXX.defs file.]
-
-NOTES:
-
-* The documentation, what there is of it, is in ./doc. I am only
-including the sgml format source-files. But try to make .ps files
-available from the above http address. To locally use these sgml files
-you should have linuxdoc-sgml installed. Sorry, but I'm conserving net
-bandwidth by only including sources!
-
-* The source for each module is to be found in ./modules/XXX. If you
-want to add a new one, make a directory like XXX for it. Add the name
-(XXX) to MODDIRS in ./modules/Makefile and hopefully it will become
-part of the overall make. Note, the Makefile in ./modules/ is now
-smart enough to check if the directory is there before it changes into
-it; If you want to start working on a module, send me its name and I
-will add it to the "official" Makefile.. This way, you should be able
-to insert your developing module into any new release, and not have to
-worry at first about letting it out to the public. This may also give
-other people some idea about whether a module is currently being
-worked on or not.
-
-* Currently, you have to 'make' binaries from this directory. 'make
-clean', however, works in any directory that has a Makefile.
-
-* Also, you can 'make remove' (as root) from *this* directory and it
-will delete the various installed files dotted around the system. THIS
-IS A VERY BAD IDEA IF YOUR SYSTEM DEPENDS ON PAM TO WORK!!!
-
-* 'make sterile' does 'make remove' and then 'make extraclean', this
-might be required if you are alternating your choice of
-STATIC(_LIBPAM) and DYNAMIC(_LIBPAM) compilation. SEE COMMENT IN
-UPPERCASE IN PARAGRAPH ABOVE!!!!
-
-Best wishes
-
-Andrew Morgan
-
-Email bugs/comments to: the Linux-PAM list <pam-list@redhat.com>
-or me <morgan@linux.kernel.org>
-
-To see about joining the mailing list, send the following email:
---------------------------------
-To: pam-list-request@redhat.com
-Subject: help
-<empty text>
---------------------------------
-
-Additionally, some Linux-PAM files have been known to be found at one
-or more of the following places (they are not always the most up to
-date...):
-
-http://www.redhat.com/linux-info/pam/
-
-ftp://bach.cis.temple.edu/pub/People/Alex/private/PAM
-ftp://ftp.redhat.com/pub/misc/
-ftp://linux.nrao.edu/pub/linux/ALPHA/PAM/
-ftp://tsx-11.mit.edu/pub/linux/ALPHA/PAM/
diff --git a/contrib/libpam/TODO b/contrib/libpam/TODO
deleted file mode 100644 (file)
index 5ed6acb..0000000
+++ /dev/null
@@ -1,59 +0,0 @@
-$Id: TODO,v 1.10 1997/02/15 19:30:51 morgan Exp morgan $
-
-Here are some things to think about if you are interested in
-contributing to the Linux-PAM effort.
-
-1. If you have a suggestion mail the pam-list!
-
-2. TODO:               Comments
-   -----               --------
-
- [modules]
-
-pam_time               should log an error if it denies access.
-
-pam_smartcard??        It has already started to happen. (Alex Yuriev has a
-                       smart-card module...)
-
-pam_floppy??           A alternative login mechanism might involve
-                       authenticating with a personal specially
-                       formatted floppy!? (got to make some use of
-                       all those strange Linux incompatible floppies
-                       I keep getting from ISPs ;^)
-
-pam_???                        If you are interested in another type of
-                       authentication method--just make a module!
-                       If you want it registered/some help, email the
-                       list.
-
- [misc]
-
-SVGA & X-conv          Currently, libpam-misc contains a text-only
-                       conversation function. A graphical one,
-                       for X or SVGA would be very welcome,
-                       [Ben Buxton is working on an X one (as of
-                       1996/12/1)] applications like xlock
-                       etc.. would benefit from this.
-
-
-Issues that need to be resolved:
---------------------------------
-
-- can we support the use_mapped_pass flag without running into problems
-  with ITAR rules? [this problem is likely to mutate. The DCE-RFC
-  people are considering the addition of a mapping module type - one
-  that other modules can use to safely store passwords...]
-
-  - anyone know where someone to email for FREE legal advice/support?
-
------------ 
-Comments to <pam-list@redhat.com>
-(administrative requests to <pam-list-request@redhat.com> use
-
-   Subject: help
-   <empty_message>
-
-)
------------ 
-Andrew Morgan <morgan@linux.kernel.org>.
-http://linux.kernel.org/pub/linux/libs/pam/index.html
diff --git a/contrib/libpam/defs/debian.defs b/contrib/libpam/defs/debian.defs
deleted file mode 100644 (file)
index 19ba466..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-##
-# defs for Debian
-# Ben Collins <bcollins@debian.org>
-##
-# this file indicates the compiler and the various hardware/OS dependent
-# flags for installation. It also defines the various destinations of
-# installed files on the system.
-##
-
-CFLAGS := -O2 -I${shell pwd}/include # -D__NO_STRING_INLINES
-ifneq (,$(findstring $(DEB_BUILD_OPTIONS),debug DEBUG Debug))
-  CFLAGS += -g
-endif
-
-OS             := $(shell dpkg-architecture -qDEB_BUILD_GNU_SYSTEM)
-ARCH           := $(shell dpkg-architecture -qDEB_BUILD_GNU_CPU)
-CC             := gcc
-INSTALL        := install
-MKDIR          := mkdir -p
-ULIBS          :=
-LD             := ld
-LD_D           := gcc -shared -Xlinker -x
-LD_L           := $(LD) -x -shared 
-AR             := ar -cr
-RANLIB         := ranlib
-PREFIX         :=
-LIBDIR         := $(PREFIX)/lib
-USESONAME      := yes
-SOSWITCH       := -soname
-LINKLIBS       := -lc -L${shell pwd}/libpam -L${shell pwd}/libpam_misc
-NEEDSONAME     := no
-LDCONFIG       := /sbin/ldconfig
-FAKEROOT       :=
-SUPLEMENTED    := $(PREFIX)/sbin
-SECUREDIR      := $(LIBDIR)/security
-INCLUDED       := /usr/include/security
-CONFIGED       := /etc
-SCONFIGED      := /etc/security
-EXTRALS                := -lnsl -lcrypt
-WARNINGS       := -Wall
diff --git a/contrib/libpam/defs/redhat4.defs b/contrib/libpam/defs/redhat4.defs
deleted file mode 100644 (file)
index 219abeb..0000000
+++ /dev/null
@@ -1,35 +0,0 @@
-##
-# defs for Red Hat Linux
-# Michael K. Johnson <johnsonm@redhat.com>
-##
-# this file indicates the compiler and the various hardware/OS dependent
-# flags for installation. It also defines the various destinations of
-# installed files on the system.
-#
-# This file is the version used for Red Hat Linux.
-
-OS=linux
-ARCH=$(shell rpm --showrc | grep '^build arch' | sed 's/^.*: //g')
-CC=gcc
-INSTALL=install
-MKDIR=mkdir -p
-CFLAGS=$(RPM_OPT_FLAGS) -pipe -g
-ULIBS=#-lefence
-LD=ld
-LD_D=gcc -shared -Xlinker -x
-LD_L=$(LD) -x -shared 
-USESONAME=yes
-SOSWITCH=-soname
-LINKLIBS=-lc
-NEEDSONAME=no
-LDCONFIG=/sbin/ldconfig
-AR=ar -cr
-RANLIB=ranlib
-FAKEROOT=$(RPM_BUILD_ROOT)
-PREFIX=
-SUPLEMENTED=$(PREFIX)/sbin
-LIBDIR=$(PREFIX)/lib
-SECUREDIR=$(LIBDIR)/security
-INCLUDED=/usr/include/security
-CONFIGED=/etc
-SCONFIGED=/etc/security
diff --git a/contrib/libpam/defs/solaris-2.1.5.defs b/contrib/libpam/defs/solaris-2.1.5.defs
deleted file mode 100644 (file)
index 4624b60..0000000
+++ /dev/null
@@ -1,45 +0,0 @@
-##
-#  Solaris defs contributed by Josh Wilmes <josh@makita.jpl.nasa.gov>
-##
-# this file indicates the compiler and the various hardware/OS dependent
-# flags for installation. It also defines the various destinations of
-# installed files on the system.
-#
-# This file is the default version. Please look in .../defs/ for your
-# preferred OS/vendor.
-
-# Please note that the linker used must be the GNU ld, not the native Sun
-# linker.  It is fairly common for the gnu linker (/usr/ccs/bin/ld) to be
-# configured as the default linker for gcc.  To tell gcc to use the
-# gnu linker, you need to set the GCC_EXEC_PREFIX environment variable
-# to point at the directory where the gnu linker is installed.  Here's
-# what I do:
-# $ mkdir /tmp/foo
-# $ ln -s /path/to/gnu/ld /tmp/foo/ld
-# $ export GCC_EXEC_PREFIX=/tmp/foo/
-# $ export PATH=/tmp/foo:$PATH
-
-OS=solaris
-ARCH=sun
-CC=gcc
-INSTALL=install
-MKDIR=mkdir -p
-CFLAGS=-O7 -pipe -g -D__EXTENSIONS__ -Dsolaris
-ULIBS=
-LD_D=gcc -shared -Xlinker -x  
-LD=ld                                      
-LD_L=$(LD) -G
-USESONAME=yes
-SOSWITCH=-h
-NEEDSONAME=no
-LDCONFIG=/sbin/echo
-AR=ar -cr
-RANLIB=ranlib
-FAKEROOT=
-PREFIX=/usr
-SUPLEMENTED=$(PREFIX)/sbin
-LIBDIR=$(PREFIX)/lib
-SECUREDIR=$(LIBDIR)/security
-INCLUDED=/usr/include/security
-CONFIGED=/etc
-SCONFIGED=/etc/security
diff --git a/contrib/libpam/defs/suse.defs b/contrib/libpam/defs/suse.defs
deleted file mode 100644 (file)
index 1fc6b74..0000000
+++ /dev/null
@@ -1,36 +0,0 @@
-##
-# defs for SuSE Linux
-# Thorsten Kukuk <kukuk@suse.de>
-##
-# this file indicates the compiler and the various hardware/OS dependent
-# flags for installation. It also defines the various destinations of
-# installed files on the system.
-#
-# This file is the version used for SuSE Linux.
-
-OS=linux
-ARCH=$(shell rpm --showrc | grep 'build arch' | grep -v "compatible" | sed 's/^.*: //g')
-CC=gcc
-INSTALL=install
-MKDIR=mkdir -p
-CFLAGS=$(RPM_OPT_FLAGS) -pipe -D_REENTRANT
-ULIBS=#-lefence
-LD=ld
-LD_D=gcc -shared -Xlinker -x
-LD_L=$(LD) -x -shared
-USESONAME=yes
-SOSWITCH=-soname
-LINKLIBS=-lc
-NEEDSONAME=yes
-LDCONFIG=/sbin/ldconfig
-AR=ar -cr
-RANLIB=ranlib
-FAKEROOT=$(RPM_BUILD_ROOT)
-PREFIX=
-SUPLEMENTED=$(PREFIX)/sbin
-LIBDIR=$(PREFIX)/lib
-SECUREDIR=$(LIBDIR)/security
-INCLUDED=/usr/include/security
-CONFIGED=/etc
-SCONFIGED=/etc/security
-EXTRALS=-lcrypt
diff --git a/contrib/libpam/doc/CREDITS b/contrib/libpam/doc/CREDITS
deleted file mode 100644 (file)
index 2b3e3d1..0000000
+++ /dev/null
@@ -1,39 +0,0 @@
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $
- $FreeBSD: src/contrib/libpam/doc/CREDITS,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $
- $DragonFly: src/contrib/libpam/doc/Attic/CREDITS,v 1.2 2003/06/17 04:24:02 dillon Exp $
-  -->
-Peter Allgeyer,
-Tim Baverstock,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Eric Hester,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Nicolai Langfeldt,
-Elliot Lee,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-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/contrib/libpam/doc/Makefile b/contrib/libpam/doc/Makefile
deleted file mode 100644 (file)
index aa6db6e..0000000
+++ /dev/null
@@ -1,79 +0,0 @@
-
-### $Id: Makefile,v 1.9 1997/01/04 21:55:52 morgan Exp $
-### $FreeBSD: src/contrib/libpam/doc/Makefile,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $
-### $DragonFly: src/contrib/libpam/doc/Attic/Makefile,v 1.2 2003/06/17 04:24:02 dillon Exp $
-
-TXTER=sgml2txt
-HTMLER=sgml2html
-# older distributions use, sgml2ps
-PSER=sgml2latex -p
-
-FILES=pam pam_appl pam_modules
-FSRCS=pam.sgml pam_appl.sgml pam_modules.sgml
-
-TEXTS=txts/pam.txt txts/pam_appl.txt txts/pam_modules.txt
-HTMLS=html/pam.html html/pam_appl.html html/pam_modules.html
-PSFILES=ps/pam.ps ps/pam_appl.ps ps/pam_modules.ps
-
-MODULES=$(shell ls modules/*.sgml)
-
-#######################################################
-
-dummy:
-       @echo "Making the documentation..."
-       @make all
-
-all: htmls texts postscript
-
-htmls: $(HTMLS)
-
-$(HTMLS) : $(FSRCS)
-       @for i in $(FILES) ; do \
-       if [ ! -f "html/$$i.html" ] || [ "$$i.sgml" -nt "html/$$i.html" ]; \
-       then \
-               cd html ; $(HTMLER) ../$$i ; \
-               if [ $$? -ne 0 ]; then exit 1 ; fi ; \
-               cd .. ; \
-       fi ; \
-       done
-
-texts: $(TEXTS)
-
-$(TEXTS) : $(FSRCS)
-       @for i in $(FILES) ; do \
-               if [ ! -f "txts/$$i.txt" ] \
-                               || [ "$$i.sgml" -nt "txts/$$i.txt" ]; then \
-                       cd txts ; $(TXTER) ../$$i ; cd .. ; \
-               fi ; \
-       done
-
-postscript: $(PSFILES)
-
-$(PSFILES): $(FSRCS)
-       @for i in $(FILES) ; do \
-       if [ ! -f "ps/$$i.ps" ] || [ "$$i.sgml" -nt "ps/$$i.ps" ]; then \
-               cd ps ; $(PSER) ../$$i ; cd .. ; \
-       fi ; \
-       done
-
-pam.sgml: pam_source.sgml MODULES-SGML
-       @sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' pam_source.sgml > pam.sgml
-
-MODULES-SGML: $(MODULES)
-       @echo 'Building module text from files in modules/*.sgml'
-       @rm -f MODULES-SGML
-       @echo '<!-- modules included:' > MODULES-SGML
-       @ls modules/*.sgml >> MODULES-SGML
-       @echo '  and that is all -->' >> MODULES-SGML
-       @cat modules/*.sgml >> MODULES-SGML
-
-extraclean: clean
-
-clean:
-       rm -f *~ *.bak
-       rm -f html/pam*.html
-       rm -f man/*~
-       rm -f $(TEXTS)
-       rm -f $(PSFILES)
-       rm -f MODULES-SGML pam.sgml
-
diff --git a/contrib/libpam/doc/NOTES b/contrib/libpam/doc/NOTES
deleted file mode 100644 (file)
index b0f40d4..0000000
+++ /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/contrib/libpam/doc/figs/pam_orient.txt b/contrib/libpam/doc/figs/pam_orient.txt
deleted file mode 100644 (file)
index a8b745a..0000000
+++ /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/contrib/libpam/doc/html/index.html b/contrib/libpam/doc/html/index.html
deleted file mode 100644 (file)
index 7d0c6fe..0000000
+++ /dev/null
@@ -1,23 +0,0 @@
-
-<HTML>
-<HEAD>
-<TITLE>Linux-PAM - Pluggable Authentication Modules for Linux</TITLE>
-</HEAD>
-<BODY>
-
-<p>
-Here is the documentation for Linux-PAM. As you will see it is
-currently not complete. However, in order of decreasing length:
-
-<ul>
-<li> <a href="pam.html">The System Administrators' Guide</a>
-<li> <a href="pam_modules.html">The Module Writers' Manual</a>
-<li> <a href="pam_appl.html">The Application developers' Manual</a>
-</ul>
-
-<hr>
-<p>
-REVISION: <tt>$Id: index.html,v 1.4 1996/11/21 06:51:01 morgan Exp $</tt>
-REVISION: <tt>$FreeBSD: src/contrib/libpam/doc/html/index.html,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $</tt>
-REVISION: <tt>$DragonFly: src/contrib/libpam/doc/html/Attic/index.html,v 1.2 2003/06/17 04:24:02 dillon Exp $</tt>
-</BODY>
diff --git a/contrib/libpam/doc/man/pam.8 b/contrib/libpam/doc/man/pam.8
deleted file mode 100644 (file)
index 8f8c6a9..0000000
+++ /dev/null
@@ -1,275 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam.8,v 1.2 1997/02/15 18:37:27 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam.8,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam.8,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
-.TH PAM 8 "1997 Feb 9" "PAM 0.56" "PAM Manual"
-.SH NAME
-
-PAM \- Pluggable Authentication Modules
-
-.SH SYNOPSIS
-.B /etc/pam.conf
-.sp 2
-.SH DESCRIPTION
-
-This manual is intended to offer a quick introduction to
-.BR PAM ". "
-For more information the reader is directed to the
-.BR "Linux-PAM system administrators' guide".
-
-.sp
-.BR PAM
-Is a system of libraries that handle the authentication tasks of
-applications (services) on the system.  The library provides a stable
-general interface (Application Programming Interface - API) that
-privilege granting programs (such as
-.BR login "(1) "
-and
-.BR su "(1)) "
-defer to to perform standard authentication tasks.
-
-.sp
-The principal feature of the PAM approach is that the nature of the
-authentication is dynamically configurable.  In other words, the
-system administrator is free to choose how individual
-service-providing applications will authenticate users. This dynamic
-configuration is set by the contents of the single
-.BR PAM
-configuration file
-.BR /etc/pam.conf "."
-Alternatively, the configuration can be set by individual
-configuration files located in the
-.B /etc/pam.d/
-directory.
-.IB "The presence of this directory will cause " PAM " to ignore"
-.BI /etc/pam.conf "."
-
-.sp
-From the point of view of the system administrator, for whom this
-manual is provided, it is not of primary importance to understand the
-internal behavior of the
-.BR PAM
-library.  The important point to recognize is that the configuration
-file(s)
-.I define
-the connection between applications
-.BR "" "(" services ")"
-and the pluggable authentication modules
-.BR "" "(" PAM "s)"
-that perform the actual authentication tasks.
-
-.sp
-.BR PAM
-separates the tasks of
-.I authentication
-into four independent management groups:
-.BR "account" " management; "
-.BR "auth" "entication management; "
-.BR "password" " management; "
-and
-.BR "session" " management."
-(We highlight the abbreviations used for these groups in the
-configuration file.)
-
-.sp
-Simply put, these groups take care of different aspects of a typical
-user's request for a restricted service:
-
-.sp
-.BR account " - "
-provide account verification types of service: has the user's password
-expired?; is this user permitted access to the requested service?
-
-.br
-.BR auth "entication - "
-establish the user is who they claim to be. Typically this is via some
-challenge-response request that the user must satisfy: if you are who
-you claim to be please enter your password.  Not all authentications
-are of this type, there exist hardware based authentication schemes
-(such as the use of smart-cards and biometric devices), with suitable
-modules, these may be substituted seamlessly for more standard
-approaches to authentication - such is the flexibility of
-.BR PAM "."
-
-.br
-.BR password " - "
-this group's responsibility is the task of updating authentication
-mechanisms. Typically, such services are strongly coupled to those of
-the
-.BR auth
-group. Some authentication mechanisms lend themselves well to being
-updated with such a function. Standard UN*X password-based access is
-the obvious example: please enter a replacement password.
-
-.br
-.BR session " - "
-this group of tasks cover things that should be done prior to a
-service being given and after it is withdrawn. Such tasks include the
-maintenance of audit trails and the mounting of the user's home
-directory. The
-.BR session
-management group is important as it provides both an opening and
-closing hook for modules to affect the services available to a user.
-
-.SH The configuration file(s)
-
-When a
-.BR PAM
-aware privilege granting application is started, it activates its
-attachment to the PAM-API.  This activation performs a number of
-tasks, the most important being the reading of the configuration file(s):
-.BR /etc/pam.conf "."
-Alternatively, this may be the contents of the
-.BR /etc/pam.d/
-directory.
-
-These files list the
-.BR PAM "s"
-that will do the authentication tasks required by this service, and
-the appropriate behavior of the PAM-API in the event that individual
-.BR PAM "s "
-fail.
-
-.sp
-The syntax of the
-.B /etc/pam.conf
-configuration file is as follows. The file is made
-up of a list of rules, each rule is typically placed on a single line,
-but may be extended with an escaped end of line: `\\<LF>'. Comments
-are preceded with `#' marks and extend to the next end of line.
-
-.sp
-The format of each rule is a space separated collection of tokens, the
-first three being case-insensitive:
-
-.sp
-.br
-.BR "   service  type  control  module-path  module-arguments"
-
-.sp
-The syntax of files contained in the
-.B /etc/pam.d/
-directory, are identical except for the absence of any
-.I service 
-field. In this case, the
-.I service
-is the name of the file in the
-.B /etc/pam.d/
-directory. This filename must be in lower case.
-
-.sp
-An important feature of
-.BR PAM ", "
-is that a number of rules may be
-.I stacked
-to combine the services of a number of PAMs for a given authentication
-task.
-
-.sp
-The
-.BR service
-is typically the familiar name of the corresponding application:
-.BR login
-and 
-.BR su
-are good examples. The
-.BR service "-name, " other ", "
-is reserved for giving
-.I default
-rules.  Only lines that mention the current service (or in the absence
-of such, the
-.BR other
-entries) will be associated with the given service-application.
-
-.sp
-The
-.BR type
-is the management group that the rule corresponds to. It is used to
-specify which of the management groups the subsequent module is to
-be associated with. Valid entries are:
-.BR account "; "
-.BR auth "; "
-.BR password "; "
-and
-.BR session "."
-The meaning of each of these tokens was explained above.
-
-.sp
-The third field,
-.BR control ", "
-indicates the behavior of the PAM-API should the module fail to
-succeed in its authentication task. Valid
-.BR control
-values are:
-.BR requisite
-- failure of such a PAM results in the immediate termination of the
-authentication process;
-.BR required
-- failure of such a PAM will ultimately lead to the PAM-API returning
-failure but only after the remaining
-.I stacked
-modules (for this
-.BR service
-and
-.BR type ")"
-have been invoked;
-.BR sufficient
-- success of such a module is enough to satisfy the authentication
-requirements of the stack of modules (if a prior
-.BR required
-module has failed the success of this one is
-.IR ignored "); "
-.BR optional
-- the success or failure of this module is only important if it is the
-only module in the stack associated with this
-.BR service "+" type "."
-
-.sp
-.BR module-path
-- this is the full filename of the PAM to be used by the application
-
-.sp
-.BR module-arguments
-- these are a space separated list of tokens that can be used to
-modify the specific behavior of the given PAM. Such arguments will be
-documented for each individual module.
-
-.SH "FILES"
-.BR /etc/pam.conf " - the configuration file"
-.br
-.BR /etc/pam.d/ " - the"
-.BR PAM
-configuration directory. If this directory is present, the
-.B /etc/pam.conf
-file is ignored.
-.br
-.BR /usr/lib/libpam.so.X " - the dynamic library"
-.br
-.BR /usr/lib/pam_*.so " - the PAMs
-
-.SH ERRORS
-Typically errors generated by the
-.BR PAM
-system of libraries, will be written to
-.BR syslog "(3)."
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.br
-Contains additional features, currently under consideration by the
-DCE-RFC committee.
-
-.SH BUGS
-.sp 2
-None known.
-
-.SH "SEE ALSO"
-
-The three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam.conf.8 b/contrib/libpam/doc/man/pam.conf.8
deleted file mode 100644 (file)
index 07bfaab..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam.conf.8,v 1.1.1.1.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam.conf.8,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.so man8/pam.8
diff --git a/contrib/libpam/doc/man/pam.d.8 b/contrib/libpam/doc/man/pam.d.8
deleted file mode 100644 (file)
index 040ce0b..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam.d.8,v 1.1.1.1.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam.d.8,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.so man8/pam.8
diff --git a/contrib/libpam/doc/man/pam_authenticate.3 b/contrib/libpam/doc/man/pam_authenticate.3
deleted file mode 100644 (file)
index 0c3c595..0000000
+++ /dev/null
@@ -1,93 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_authenticate.3,v 1.2 1997/02/15 18:39:59 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_authenticate.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_authenticate.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_authenticate \- authenticate a user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_authenticate(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_authenticate
-
-.br
-Use this function to authenticate an applicant user.  It is linked
-.I dynamically
-to the authentication modules by
-.BR PAM ". "
-It is the task of these module to perform such an authentication.  The
-specific nature of the authentication is not the concern of the
-application.
-
-.br
-Following successful completion, the
-.BR name
-of the authenticated user will be present in the
-.BR PAM
-item
-.BR PAM_USER ". "
-This item may be recovered with a call to
-.BR pam_get_item "(3)."
-
-.br
-The application developer should note that the modules may request
-that the user enter their username via the conversation mechanism (see
-.BR pam_start "(3))."
-Should this be the case, the user-prompt string can be set via
-the
-.BR PAM_USER_PROMPT
-item (see
-.BR pam_set_item "(3))."
-
-.SH "RETURN VALUE"
-On success
-.BR PAM_SUCCESS
-is returned.  All other returns should be considered
-authentication failures and will be
-.I delayed
-by an amount specified with prior calls to
-.BR pam_fail_delay "(3). "
-Specific failures that demand special attention are the following:
-.TP
-.B PAM_ABORT
-the application should exit immediately. Of course,
-.BR pam_end "(3)"
-should be called first.
-
-.TP
-.B PAM_MAXTRIES
-the application has tried too many times to authenticate the
-user, authentication should not be attempted again.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-.BR pam_fail_delay "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_chauthtok.3 b/contrib/libpam/doc/man/pam_chauthtok.3
deleted file mode 100644 (file)
index 9d685be..0000000
+++ /dev/null
@@ -1,103 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_chauthtok.3,v 1.2 1997/02/15 18:42:23 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_chauthtok.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_chauthtok.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_chauthtok \- updating authentication tokens
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_chauthtok(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_chauthtok
-
-.br
-Use this function to rejuvenate the authentication tokens (passwords
-etc.) of an applicant user.
-
-.br
-Note, the application should not pre-authenticate the user, as this is
-performed (if required) by the
-.BR PAM
-framework.
-
-.br
-The
-.I flags
-argument can
-.I optionally
-take the value,
-.BR PAM_CHANGE_EXPIRED_AUTHTOK "."
-In such cases the framework is only required to update those
-authentication tokens that have expired. Without this argument, the
-framework will attempt to obtain new tokens for all configured
-authentication mechanisms. The details of the types and number of such
-schemes should not concern the calling application.
-
-.SH RETURN VALUE
-A successful return from this function will be indicated with
-.BR PAM_SUCCESS "."
-
-.br
-Specific errors of special interest when calling this function are
-
-.br
-.BR PAM_AUTHTOK_ERROR
-- a valid new token was not obtained
-
-.br
-.BR PAM_AUTHTOK_RECOVERY_ERR
-- old authentication token was not available
-
-.br
-.BR PAM_AUTHTOK_LOCK_BUSY
-- a resource needed to update the token was locked (try again later)
-
-.br
-.BR PAM_AUTHTOK_DISABLE_AGING
-- one or more of the authentication modules does not honor
-authentication token aging
-
-.br
-.BR PAM_TRY_AGAIN
-- one or more authentication mechanism is not prepared to update a
-token at this time
-
-.br
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(8)."
-
-.br
-Also, see the three
-.BR PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_close_session.3 b/contrib/libpam/doc/man/pam_close_session.3
deleted file mode 100644 (file)
index cada03c..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_close_session.3,v 1.1.1.1.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_close_session.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.so man3/pam_open_session.3
diff --git a/contrib/libpam/doc/man/pam_end.3 b/contrib/libpam/doc/man/pam_end.3
deleted file mode 100644 (file)
index ec76490..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_end.3,v 1.1.1.1.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_end.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.so man3/pam_start.3
diff --git a/contrib/libpam/doc/man/pam_fail_delay.3 b/contrib/libpam/doc/man/pam_fail_delay.3
deleted file mode 100644 (file)
index 7a96184..0000000
+++ /dev/null
@@ -1,132 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_fail_delay.3,v 1.2 1997/02/15 18:47:46 morgan Exp morgan $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_fail_delay.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_fail_delay.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "PAM 0.56" "Programmers' Manual"
-.SH NAME
-
-pam_fail_delay \- request a delay on failure
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");"
-.sp 2
-.SH DESCRIPTION
-.br
-It is often possible to attack an authentication scheme by exploiting
-the time it takes the scheme to deny access to an applicant user.  In
-cases of
-.I short
-timeouts, it may prove possible to attempt a
-.I brute force
-dictionary attack -- with an automated process, the attacker tries all
-possible passwords to gain access to the system.  In other cases,
-where individual failures can take measurable amounts of time
-(indicating the nature of the failure), an attacker can obtain useful
-information about the authentication process.  These latter attacks
-make use of procedural delays that constitute a
-.I covert channel
-of useful information.
-
-.br
-To minimize the effectiveness of such attacks, it is desirable to
-introduce a random delay in a failed authentication process.
-.B PAM
-provides such a facility.  The delay occurs upon failure of the
-.BR pam_authenticate "(3) "
-and
-.BR pam_chauthtok "(3) "
-functions.  It occurs
-.I after
-all authentication modules have been called, but
-.I before
-control is returned to the service application.
-
-.br
-The function,
-.BR pam_fail_delay "(3),"
-is used to specify a required minimum for the length of the
-failure-delay; the
-.I usec
-argument.  This function can be called by the service application
-and/or the authentication modules, both may have an interest in
-delaying a reapplication for service by the user.  The length of the
-delay is computed at the time it is required.  Its length is
-pseudo-gausianly distributed about the
-.I maximum
-requested value; the resultant delay will differ by as much as 25% of
-this maximum requested value (both up and down).
-
-.br
-On return from
-.BR pam_authenticate "(3) or " pam_chauthtok "(3),"
-independent of success or failure, the new requested delay is reset to
-its default value: zero.
-
-.SH EXAMPLE
-.br
-For example, a
-.B login
-application may require a failure delay of roughly 3 seconds. It will
-contain the following code:
-.sp
-.br
-.B "     pam_fail_delay(pamh, 3000000 /* micro-seconds */ );"
-.br
-.B "     pam_authenticate(pamh, 0);"
-.sp
-.br
-if the modules do not request a delay, the failure delay will be
-between 2.25 and 3.75 seconds.
-
-.br
-However, the modules, invoked in the authentication process, may
-also request delays:
-.sp
-.br
-.RB "  (module #1)   " "pam_fail_delay(pamh, 2000000);"
-.sp
-.br
-.RB "  (module #2)   " "pam_fail_delay(pamh, 4000000);"
-.sp
-.br
-in this case, it is the largest requested value that is used to
-compute the actual failed delay: here between 3 and 5 seconds.
-
-.SH "RETURN VALUE"
-Following a successful call to
-.BR pam_fail_delay "(3), " PAM_SUCCESS
-is returned.  All other returns should be considered serious failures.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-Under consideration by the X/Open group for future inclusion in the
-PAM RFC. 1996/1/10
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_open_session.3 b/contrib/libpam/doc/man/pam_open_session.3
deleted file mode 100644 (file)
index 8ed54f9..0000000
+++ /dev/null
@@ -1,101 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_open_session.3,v 1.2 1997/02/15 18:49:02 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_open_session.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_open_session.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_open/close_session \- PAM session management
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_open_session(pam_handle_t " *pamh ", int  " flags ");"
-.sp
-.BI "int pam_close_session(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-
-PAM provides management-hooks for the initialization and termination
-of a session. 
-
-.TP
-.B pam_open_session
-.br
-Use this function to signal that an authenticated user session has
-begun. It should be called only after the user is properly identified
-and (where necessary) has been granted their credentials with
-.BR pam_authenticate "(3)"
-and
-.BR pam_setcred "(3)"
-respectively.
-
-.br
-Some types of functions associated with session
-initialization are logging for the purposes of system-audit and
-mounting directories (the user's home directory for example). These
-should not concern the application. It should be noted that the
-.I effective
-uid,
-.BR geteuid "(2),"
-of the application should be of sufficient privilege to perform such
-tasks.
-
-.TP
-.B pam_close_session
-.br
-Use this function to signal that a user session has
-terminated. In general this function may not need to be located in the
-same application as the initialization function,
-.BR pam_open_session "."
-
-.br
-Typically, this function will undo the actions of
-.BR pam_open_session "."
-That is, log audit information concerning the end of the user session
-or unmount the user's home directory. Apart from having sufficient
-privilege the details of the session termination should not concern
-the calling application. It is good programming practice, however, to
-cease acting on behalf of the user on returning from this call.
-
-.SH RETURN VALUE
-A successful return from the session management functions will be
-indicated with
-.BR PAM_SUCCESS "."
-
-.br
-The specific error indicating a failure to open or close a session is
-.BR PAM_SESSION_ERR "."
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-OSF-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(3)."
-
-.br
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_setcred.3 b/contrib/libpam/doc/man/pam_setcred.3
deleted file mode 100644 (file)
index 06d7fb4..0000000
+++ /dev/null
@@ -1,81 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_setcred.3,v 1.1.1.1 1998/07/09 22:10:18 jdp Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_setcred.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_setcred.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
-.TH PAM_SETCRED 3 "1997 July 6" "PAM 0.58" "App. Programmers' Manual"
-.SH NAME
-
-pam_setcred \- set the credentials for the user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_setcred(pam_handle_t " *pamh ", int  " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_setcred
-
-This function is used to establish, maintain and delete the
-credentials of a user. It should be called after a user has been
-authenticated and before a session is opened for the user (with
-.BR pam_open_session "(3))."
-
-It should be noted that credentials come in many forms. Examples
-include: group memberships; ticket-files; and PAM environment
-variables.  For this reason, it is important that the basic identity
-of the user is established, by the application, prior to a call to
-this function.  For example, the default
-.BR PAM
-environment variables should be set and also
-.BR initgroups "(2) "
-(or equivalent) should have been performed.
-
-.SH "VALID FLAGS"
-.TP
-.BR PAM_ESTABLISH_CRED
-initialize the credentials for the user.
-
-.TP
-.BR PAM_DELETE_CRED
-delete the user's credentials.
-
-.TP
-.BR PAM_REINITIALIZE_CRED
-delete and then initialize the user's credentials.
-
-.TP
-.BR PAM_REFRESH_CRED
-extend the lifetime of the existing credentials.
-
-.SH "RETURN VALUE"
-
-On success
-.BR PAM_SUCCESS
-is returned, all other return values should be treated as errors.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_authenticate "(3), "
-.BR pam_strerror "(3)"
-and
-.BR pam_open_session "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_start.3 b/contrib/libpam/doc/man/pam_start.3
deleted file mode 100644 (file)
index 36eb4ad..0000000
+++ /dev/null
@@ -1,100 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: pam_start.3,v 1.2 1997/02/15 18:51:54 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_start.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_start.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_START 3 "1997 Feb 15" "PAM 0.56" "Application Programmers' Manual"
-.SH NAME
-
-pam_start, pam_end \- activating PAM
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
-.sp
-.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
-.sp 2
-.SH DESCRIPTION
-.TP
-.B pam_start
-Initialize the
-.I PAM
-library.  Identifying the application with a particular
-.IR service
-name.  The
-.IR user "name"
-can take the value
-.IR NULL ", "
-if not known at the time the interface is initialized.  The
-conversation structure is passed to the library via the
-.IR conv
-argument.  (For a complete description of this and other structures
-the reader is directed to the more verbose
-.IR PAM
-application developers' guide).  Upon successful initialization, an
-opaque pointer-handle for future access to the library is returned
-through the contents of the
-.IR pamh_p
-pointer.
-
-.TP
-.B pam_end
-Terminate the
-.B PAM
-library.  The service application associated with the
-.IR pamh
-handle, is terminated.  The argument,
-.IR pam_status ", "
-passes the value most recently returned to the application from the
-library; it indicates the manner in which the library should be
-shutdown.  Besides carrying a return value, this argument may be
-logically OR'd with
-.IR PAM_DATA_SILENT
-to indicate that the module should not treat the call too
-seriously. It is generally used to indicate that the current closing
-of the library is in a
-.IR fork "(2)ed"
-process, and that the parent will take care of cleaning up things that
-exist outside of the current process space (files etc.).
-
-.SH "RETURN VALUE"
-.TP
-.B pam_start
-.TP
-.B pam_end
-On success,
-.BR PAM_SUCCESS
-is returned
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.sp
-Note, the 
-.BR PAM_DATA_SILENT
-flag is pending acceptance with the DCE (as of 1996/12/4).
-
-.SH BUGS
-.sp 2
-None known.
-
-.SH "SEE ALSO"
-
-.BR fork "(2), "
-.BR pam_authenticate "(3), "
-.BR pam_acct_mgmt "(3), "
-.BR pam_open_session "(3), "
-and
-.BR pam_chauthtok "(3)."
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/pam_strerror.3 b/contrib/libpam/doc/man/pam_strerror.3
deleted file mode 100644 (file)
index d19c9ab..0000000
+++ /dev/null
@@ -1,51 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" ripped off from Rick Faith's getgroups man page
-.\" $Id: pam_strerror.3,v 1.2 1997/02/15 18:53:04 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/pam_strerror.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_strerror.3,v 1.2 2003/06/17 04:24:03 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_STRERROR 3 "1997 Feb 15" "PAM 0.56" "Programmers' Manual"
-.SH NAME
-
-pam_strerror \- return a textual description of a PAM error
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "const char *pam_strerror(" int " pam_error);
-.sp 2
-.SH DESCRIPTION
-.B pam_strerror
-
-This function returns a pointer to a line of text describing the
-.BR PAM
-error passed as its sole argument.
-
-.SH "RETURN VALUE"
-
-On success this function returns a description of the indicated
-error.  Should the function not recognize the error, ``Unknown
-PAM error'' is returned.
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-This function should be internationalized.
-
-.SH "SEE ALSO"
-
-.BR pam "(8). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/man/template-man b/contrib/libpam/doc/man/template-man
deleted file mode 100644 (file)
index 7d5f94e..0000000
+++ /dev/null
@@ -1,54 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id: template-man,v 1.1 1997/01/04 18:25:13 morgan Exp $
-.\" $FreeBSD: src/contrib/libpam/doc/man/template-man,v 1.1.1.1.6.2 2001/06/11 15:28:11 markm Exp $
-.\" $DragonFly: src/contrib/libpam/doc/man/Attic/template-man,v 1.2 2003/06/17 04:24:03 dillon Exp $
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual"
-.SH NAME
-
-function names \- brief summary of function
-
-.SH SYNOPSIS
-.B #include <security/pam_????.h>
-.sp
-.BI "int pam_???(pam_handle_t " pamh ", int  " flags);
-.sp 2
-.SH DESCRIPTION
-.TP
-.B pam_???
-Here goes the
-.I explanation
-it may be quite
-.IR long .
-.TP
-.SH "RETURN VALUE"
-.B pam_???
-On success...
-.BR PAM_SUCCESS
-is returned
-.TP
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(2). "
-
-.SH "CONFORMING TO"
-.B pam_???
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_??? "(2), "
-and
-.BR pam_??? "(2). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
diff --git a/contrib/libpam/doc/modules/pam_access.sgml b/contrib/libpam/doc/modules/pam_access.sgml
deleted file mode 100644 (file)
index 00c7ea1..0000000
+++ /dev/null
@@ -1,108 +0,0 @@
-<!--
-   
-   pam_access module docs added by Tim Berger <timb@transmeta.com>
-
--->
-
-<sect1> The access module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-
-<tt>pam_access</tt>
-
-
-<tag><bf>Author[s]:</bf></tag>
-
-Alexei Nogin &lt;alexei@nogin.dnttm.ru&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-       
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-
-account
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag> 
-Requires a configuration file. By default 
-<tt>/etc/security/access.conf</tt> is used but this can be overridden. 
-
-<tag><bf>Network aware:</bf></tag>
-
-Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of
-the stdin file descriptor with <tt/ttyname()/.  Standard
-gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/
-calls.  <bf/NIS/ is used for netgroup support.
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Provides logdaemon style login access control.
-
-<sect2> Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tt>accessfile=<it>/path/to/file.conf</it></tt>
-
-<tag><bf>Description:</bf></tag>
-
-This module provides logdaemon style login access control based on
-login names and on host (or domain) names, internet addresses (or
-network numbers), or on terminal line names in case of non-networked
-logins. Diagnostics are reported through <tt/syslog(3)/.  Wietse
-Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with
-several changes by A. Nogin.
-
-<p> 
-The behavior of this module can be modified with the following 
-arguments: 
-<itemize> 
-<item><tt>accessfile=/path/to/file.conf</tt> - 
-indicate an alternative <em/access/ configuration file to override 
-the default. This can be useful when different services need different 
-access lists. 
-</itemize> 
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Use of module is recommended, for example, on administrative machines
-such as <bf/NIS/ servers and mail servers where you need several accounts
-active but don't want them all to have login capability.
-
-For <tt>/etc/pam.d</tt> style configurations where your modules live
-in <tt>/lib/security</tt>, start by adding the following line to
-<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>,
-<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>:
-
-<tscreen>
-<verb>
-account  required       /lib/security/pam_access.so
-</verb>
-</tscreen>
-
-Note that use of this module is not effective unless your system ignores
-<tt>.rhosts</tt> files.  See the the pam_rhosts_auth documentation.
-
-A sample <tt>access.conf</tt> configuration file is included with the
-distribution.
-
-</descrip>
diff --git a/contrib/libpam/doc/modules/pam_issue.sgml b/contrib/libpam/doc/modules/pam_issue.sgml
deleted file mode 100644 (file)
index 1f617e3..0000000
+++ /dev/null
@@ -1,120 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Add issue file to user prompt
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_issue/
-
-<tag><bf>Author:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Authentication (pam_sm_authenticate)
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module prepends the issue file (<em>/etc/issue</em> by default) when
-prompting for a username.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/issue=issue-file-name/; <tt/noesc/;
-
-<tag><bf>Description:</bf></tag>
-This module allows you to prepend an issue file to the username prompt. It
-also by default parses escape codes in the issue file similar to some
-common getty's (using &bsol;x format).
-<p>
-Recognized escapes:
-<itemize>
-
-<item><tt/d/
-- current date
-
-<item><tt/s/
-- operating system name
-
-<item><tt/l/
-- name of this tty
-
-<item><tt/m/
-- architecture of this system (i686, sparc, powerpc, ...)
-
-<item><tt/n/
-- hostname of this system
-
-<item><tt/o/
-- domainname of this system
-
-<item><tt/r/
-- release number of the operation system (eg. 2.2.12)
-
-<item><tt/t/
-- current time
-
-<item><tt/u/
-- number of users currently logged in
-
-<item><tt/U/
-- same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1
-user" or "10 users"
-
-<item><tt/v/
-- version/build-date of the operating system (eg. "&num;3 Mon Aug 23 14:38:16
-EDT 1999" on Linux).
-
-</itemize>
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/issue/
-- the file to output if not using the default
-
-<item><tt/noesc/
-- turns off escape code parsing
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-login  auth  pam_issue.so  issue=/etc/issue
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/modules/pam_mkhomedir.sgml b/contrib/libpam/doc/modules/pam_mkhomedir.sgml
deleted file mode 100644 (file)
index 075e16f..0000000
+++ /dev/null
@@ -1,83 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Create home directories on initial login
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_mkhomedir/
-
-<tag><bf>Author:</bf></tag>
-Jason Gunthorpe &lt;jgg@ualberta.ca&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Management groups provided:</bf></tag>
-Session
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Creates home directories on the fly for authenticated users.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/;
-
-<tag><bf>Description:</bf></tag>
-This module is useful for distributed systems where the user account is
-managed in a central database (such as NIS, NIS+, or LDAP) and accessed
-through miltiple systems. It frees the administrator from having to create
-a default home directory on each of the systems by creating it upon the
-first succesfully authenticated login of that user. The skeleton directory
-(usually /etc/skel/) is used to copy default files and also set's a umask
-for the creation.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/skel/
-- The skeleton directory for default files to copy to the new home directory.
-
-<item><tt/umask/
-- An octal for of the same format as you would pass to the shells umask command.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-session    required   pam_mkhomedir.so skel=/etc/skel/ umask=0022
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/modules/pam_motd.sgml b/contrib/libpam/doc/modules/pam_motd.sgml
deleted file mode 100644 (file)
index 8ddc639..0000000
+++ /dev/null
@@ -1,77 +0,0 @@
-<!--
-
-Ben Collins <bcollins@debian.org>
-
--->
-
-<sect1>Output the motd file
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_motd/
-
-<tag><bf>Author:</bf></tag>
-Ben Collins &lt;bcollins@debian.org&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author
-
-<tag><bf>Management groups provided:</bf></tag>
-Session (open)
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module outputs the motd file (<em>/etc/motd</em> by default) upon
-successful login.
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/motd=motd-file-name/;
-
-<tag><bf>Description:</bf></tag>
-This module allows you to have arbitrary motd's (message of the day)
-output after a succesful login. By default this file is <em>/etc/motd</em>,
-but is configurable to any file.
-
-<p>
-The behavior of this module can be modified with one of the following
-flags:
-
-<p>
-<itemize>
-
-<item><tt/motd/
-- the file to output if not using the default.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-login  session  pam_motd.so  motd=/etc/motd
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/modules/pam_tally.sgml b/contrib/libpam/doc/modules/pam_tally.sgml
deleted file mode 100644 (file)
index aca41bb..0000000
+++ /dev/null
@@ -1,191 +0,0 @@
-<!--
-
-   $Id: pam_tally.sgml,v 1.1 2001/02/11 07:52:56 agmorgan Exp $
-   
-   This template file was written by Andrew G. Morgan <morgan@kernel.org>
-   adapted from text provided by Tim Baverstock.
--->
-
-<sect1>The login counter (tallying) module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_tally
-
-<tag><bf>Author[s]:</bf></tag>
-Tim Baverstock
-
-<tag><bf>Maintainer:</bf></tag>
-
-<tag><bf>Management groups provided:</bf></tag>
-auth; account
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-A faillog file (default location /var/log/faillog)
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This module maintains a count of attempted accesses, can reset count
-on success, can deny access if too many attempts fail.
-
-<p>
-pam_tally comes in two parts: <tt>pam_tally.so</tt> and
-<tt>pam_tally</tt>. The former is the PAM module and the latter, a
-stand-alone program. <tt>pam_tally</tt> is an (optional) application
-which can be used to interrogate and manipulate the counter file. It
-can display users' counts, set individual counts, or clear all
-counts. Setting artificially high counts may be useful for blocking
-users without changing their passwords. For example, one might find it
-useful to clear all counts every midnight from a cron job.
-
-<p>
-The counts file is organized as a binary-word array, indexed by
-uid. You can probably make sense of it with <tt>od</tt>, if you don't
-want to use the supplied appliction.
-
-<p>
-Note, there are some outstanding issues with this module:
-<tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database
-of usernames would be much more flexible; the `keep a count of current
-logins' bit has been <tt>#ifdef</tt>'d out and you can only reset the
-counter on successful authentication, for now.
-
-<sect3>Generic options accepted by both components
-<p>
-<itemize>
-<item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>):
-   if something weird happens, such as unable to open the file, how
-   should the module react?
-<item> <tt>file=</tt><em>/where/to/keep/counts</em>:
-   specify the file location for the counts.
-   The default location is <tt>/var/log/faillog</tt>.
-</itemize>
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
-<tt>file=</tt>/where/to/keep/counts;
-<tt>no_magic_root</tt>
-
-<tag><bf>Description:</bf></tag>
-
-<p>
-The authentication component of this module increments the attempted
-login counter.
-
-<p>
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-<p>
-The module argument <tt>no_magic_root</tt> is used to indicate that if
-the module is invoked by a user with uid=0, then the counter is
-incremented. The sys-admin should use this for daemon-launched
-services, like <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. For user
-launched services, like <tt>su</tt>, this argument should be omitted.
-
-<p>
-By way of more explanation, when a process already running as root
-tries to access some service, the access is <em>magic</em>, and
-bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing
-from root into an account otherwise blocked. However, for services
-like <tt>telnet</tt> or <tt>login</tt>, which always effectively run
-from the root account, root (ie everyone) shouldn't be granted this
-magic status, and the flag `no_magic_root' should be set in this
-situation, as noted in the summary above.
-
-</descrip>
-
-<sect2>Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>);
-<tt>file=</tt>/where/to/keep/counts;
-<tt>deny=</tt><em>n</em>;
-<tt>no_magic_root</tt>;
-<tt>even_deny_root_account</tt>;
-<tt>reset</tt>;
-<tt>no_reset</tt>;
-<tt>per_user</tt>;
-<tt>no_lock_time</tt>
-
-<tag><bf>Description:</bf></tag>
-
-<p>
-The account component can deny access and/or reset the attempts
-counter. It also checks to make sure that the counts file is a plain
-file and not world writable.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-<p>
-The <tt>deny=</tt><em>n</em> option is used to deny access if tally
-for this user exceeds <em>n</em>. The presence of
-<tt>deny=</tt><em>n</em> changes the default for
-<tt>reset</tt>/<tt>no_reset</tt> to <tt>reset</tt>, unless the user
-trying to gain access is root and the <tt>no_magic_root</tt> option
-has NOT been specified.
-
-<p>
-The <tt>no_magic_root</tt> option ensures that access attempts by root
-DON'T ignore deny.  Use this for daemon-based stuff, like
-<tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>.
-
-<p>
-The <tt>even_deny_root_account</tt> option is used to ensure that the
-root account can become unavailable. <bf>Note</bf> that magic root
-trying to gain root bypasses this, but normal users can be locked out.
-
-<p>
-The <tt>reset</tt> option instructs the module to reset count to 0 on
-successful entry, even for magic root. The <tt>no_reset</tt> option is
-used to instruct the module to not reset the count on successful
-entry.  This is the default unless <tt>deny</tt> exists and the user
-attempting access is NOT magic root.
-
-<p>
-If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max</tt>
-field for this user then the <tt>per_user</tt> module argument will
-ensure that the module uses this value and not the global
-<tt>deny=</tt><em>n</em> parameter.
-
-<p>
-The <tt>no_lock_time</tt> option is for ensuring that the module does
-not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this
-user.
-
-<p>
-Normally, failed attempts to access root will <bf>NOT</bf> cause the
-root account to become blocked, to prevent denial-of-service: if your
-users aren't given shell accounts and root may only login via
-<tt>su</tt> or at the machine console (not
-<tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want
-root to be blocked for some given service, use
-<tt>even_deny_root_account</tt>.
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/modules/pam_unix.sgml b/contrib/libpam/doc/modules/pam_unix.sgml
deleted file mode 100644 (file)
index 71cb07e..0000000
+++ /dev/null
@@ -1,288 +0,0 @@
-<!--
-   This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
-
-   Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
--->
-
-<sect1>The Unix Password module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-pam_unix
-
-<tag><bf>Author:</bf></tag>
-
-<tag><bf>Maintainer:</bf></tag>
-
-<tag><bf>Management groups provided:</bf></tag>
-account; authentication; password; session
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-This is the standard Unix authentication module. It uses standard calls
-from the system's libraries to retrieve and set account information as
-well as authentication. Usually this is obtained from the /etc/passwd
-and the /etc/shadow file as well if shadow is enabled.
-
-<sect2>Account component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/; <tt/audit/
-
-<tag><bf>Description:</bf></tag>
-
-The <tt/debug/ argument makes the accounting functions of this module
-<tt/syslog(3)/ more information on its actions. (Remaining arguments
-supported by the other functions of this module are silently ignored,
-but others are logged as errors through <tt/syslog(3)/). The <tt/audit/
-argument causes even more logging.
-
-Based on the following <tt/shadow/ elements:
-<tt/expire/;
-<tt/last_change/;
-<tt/max_change/;
-<tt/min_change/;
-<tt/warn_change/,
-this module performs the task of establishing the status of the user's
-account and password. In the case of the latter, it may offer advice
-to the user on changing their password or, through the
-<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
-they have established a new password. The entries listed above are
-documented in the <em/GNU Libc/ info documents. Should the user's record
-not contain one or more of these entries, the corresponding <em/shadow/
-check is not performed.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-In its accounting mode, this module can be inserted as follows:
-<tscreen>
-<verb>
-#
-# Ensure users account and password are still active
-#
-login  account  required       pam_unix.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/audit/;
-<tt/use_first_pass/;
-<tt/try_first_pass/;
-<tt/nullok/;
-<tt/nodelay/
-
-<tag><bf>Description:</bf></tag>
-
-The <tt/debug/ argument makes the authentication functions of this
-module <tt/syslog(3)/ more information on its actions. The <tt/audit/
-causes even more information to be logged.
-
-<p>
-The default action of this module is to not permit the user access to
-a service if their <em/official/ password is blank. The <tt/nullok/
-argument overrides this default.
-
-<p>
-When given the argument <tt/try_first_pass/, before prompting the user
-for their password, the module first tries the previous stacked
-<tt/auth/-module's password in case that satisfies this module as
-well. The argument <tt/use_first_pass/ forces the module to use such a
-recalled password and will never prompt the user - if no password is
-available or the password is not appropriate, the user will be denied
-access.
-
-<p>
-The argument, <tt>nodelay</tt>, can be used to discourage the
-authentication component from requesting a delay should the
-authentication as a whole fail.  The default action is for the module
-to request a delay-on-failure of the order of one second.
-
-<p>
-Remaining arguments, supported by the other functions of this module,
-are silently ignored. Other arguments are logged as errors through
-<tt/syslog(3)/.
-
-<p>
-A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's
-password when it is stored in a read protected database.  This binary
-is very simple and will only check the password of the user invoking
-it.  It is called transparently on behalf of the user by the
-authenticating component of this module.  In this way it is possible
-for applications like <em>xlock</em> to work without being setuid-root.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-The correct functionality of this module is dictated by having an
-appropriate <tt>/etc/nsswitch.conf</tt> file, the user
-databases specified there dictate the source of the authenticated
-user's record.
-<p>
-In its authentication mode, this module can be inserted as follows:
-<tscreen>
-<verb>
-#
-# Authenticate the user
-#
-login   auth  required       pam_unix.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Password component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/audit/;
-<tt/nullok/;
-<tt/not_set_pass/;
-<tt/use_authtok/;
-<tt/try_first_pass/;
-<tt/use_first_pass/;
-<tt/md5/;
-<tt/bigcrypt/;
-<tt/shadow/;
-<tt/nis/;
-<tt/remember/
-
-<tag><bf>Description:</bf></tag>
-
-This part of the <tt/pam_unix/ module performs the task of updating
-the user's password.
-
-<p>
-In the case of conventional unix databases (which store the password
-encrypted) the <tt/md5/ argument is used to do the encryption with the
-MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
-As an alternative to this, the <tt/bigcrypt/ argument can be used to
-encrypt more than the first 8 characters of a password with DEC's
-(Digital Equipment Cooperation) `C2' extension to the standard UNIX
-<tt/crypt()/ algorithm.
-
-<p>
-The <tt/nullok/ argument is used to permit the changing of a password
-<em/from/ an empty one. Without this argument, empty passwords are
-treated as account-locking ones.
-
-<p>
-The argument <tt/use_first_pass/ is used to lock the choice of old and
-new passwords to that dictated by the previously stacked <tt/password/
-module.  The <tt/try_first_pass/ argument is used to avoid the user
-having to re-enter an old password when <tt/pam_unix/ follows a module
-that possibly shared the user's old password - if this old password is
-not correct the user will be prompted for the correct one.  The
-argument <tt/use_authtok/ is used to <em/force/ this module to set the
-new password to the one provided by the previously stacked
-<tt/password/ module (this is used in an example of the stacking of
-the <em/Cracklib/ module documented above).
-
-<p>
-The <tt/not_set_pass/ argument is used to inform the module that it is
-not to pay attention to/make available the old or new passwords from/to
-other (stacked) password modules.
-
-<p>
-The <tt/debug/ argument makes the password functions of this module
-<tt/syslog(3)/ more information on its actions. Other arguments may be
-logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes
-even more information to be logged.
-
-<p>
-With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC
-for setting new passwords.
-
-<p>
-The <tt/remember/ argument takes one value. This is the number of most
-recent passwords to save for each user. These are saved in
-<tt>/etc/security/opasswd</tt> in order to force password change history
-and keep the user from alternating between the same password too frequently.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-Standard usage:
-<tscreen>
-<verb>
-#
-# Change the users password
-#
-passwd   password   required   pam_unix.so
-</verb>
-</tscreen>
-
-<p>
-An example of the stacking of this module with respect to the
-pluggable password checking module, <tt/pam_cracklib/:
-<tscreen>
-<verb>
-#
-# Change the users password
-#
-passwd   password   required   pam_cracklib.so retry=3 minlen=6 difok=3
-passwd   password   required   pam_unix.so use_authtok nullok md5
-</verb>
-</tscreen>
-
-</descrip>
-
-<sect2>Session component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-
-<tag><bf>Description:</bf></tag>
-
-No arguments are recognized by this module component. Its action is
-simply to log the username and the service-type to
-<tt/syslog(3)/. Messages are logged at the beginning and end of the
-user's session.
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-The use of the session modules is straightforward:
-<tscreen>
-<verb>
-#
-# session opening and closing
-#
-login  session  required       pam_unix.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/modules/pam_userdb.sgml b/contrib/libpam/doc/modules/pam_userdb.sgml
deleted file mode 100644 (file)
index bdbf80b..0000000
+++ /dev/null
@@ -1,112 +0,0 @@
-<!--
-   This file was written by Cristian Gafton <gafton@redhat.com>
--->
-
-<sect1>The userdb module
-
-<sect2>Synopsis
-
-<p>
-<descrip>
-
-<tag><bf>Module Name:</bf></tag>
-<tt/pam_userdb/
-
-<tag><bf>Author:</bf></tag>
-Cristian Gafton &lt;gafton@redhat.com&gt;
-
-<tag><bf>Maintainer:</bf></tag>
-Author.
-
-<tag><bf>Management groups provided:</bf></tag>
-authentication
-
-<tag><bf>Cryptographically sensitive:</bf></tag>
-       
-<tag><bf>Security rating:</bf></tag>
-
-<tag><bf>Clean code base:</bf></tag>
-
-<tag><bf>System dependencies:</bf></tag>
-Requires Berkeley DB.
-
-<tag><bf>Network aware:</bf></tag>
-
-</descrip>
-
-<sect2>Overview of module
-
-<p>
-Look up users in a .db database and verify their password against
-what is contained in that database.
-
-<sect2>Authentication component
-
-<p>
-<descrip>
-
-<tag><bf>Recognized arguments:</bf></tag>
-<tt/debug/;
-<tt/icase/;
-<tt/dump/;
-<tt/db=XXXX/;
-
-<tag><bf>Description:</bf></tag>
-
-This module is used to verify a username/password pair against values stored in
-a Berkeley DB database. The database is indexed by the username, and the data 
-fields corresponding to the username keys are the passwords, in unencrypted form,
-so caution must be exercised over the access rights to the DB database itself..
-
-The module will read the password from the user using the conversation mechanism. If
-you are using this module on top of another authetication module (like <tt/pam_pwdb/;)
-then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module.
-
-<p>
-The action of the module may be modified from this default by one or
-more of the following flags in the <tt>/etc/pam.d/&lt;service&gt;</tt> file.
-<itemize>
-<item>
-<tt/debug/ -
-Supply more debugging information to <tt/syslog(3)/.
-
-<item>
-<tt/icase/ -
-Perform the password comparisons case insensitive.
-
-<item>
-<tt/dump/ -
-dump all the entries in the database to the log (eek,
-don't do this by default!)
-
-<item>
-<tt/db=XXXX/ - 
-use the database found on pathname XXXX. Note that Berkeley DB usually adds the 
-needed filename extension for you, so you should use something like <tt>/etc/foodata</tt>
-instead of <tt>/etc/foodata.db</tt>.
-
-</itemize>
-
-<tag><bf>Examples/suggested usage:</bf></tag>
-
-This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> 
-on most systems) that will accept for login users whose username/password pairs are 
-provided in the <tt>/tmp/dbtest.db</tt> file:
-
-<tscreen>
-<verb>
-#%PAM-1.0
-auth       required     pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
-auth       sufficient   pam_userdb.so icase db=/tmp/dbtest
-auth       required     pam_pwdb.so shadow nullok try_first_pass
-auth       required     pam_shells.so
-account    required     pam_pwdb.so
-session    required     pam_pwdb.so
-</verb>
-</tscreen>
-
-</descrip>
-
-<!--
-End of sgml insert for this module.
--->
diff --git a/contrib/libpam/doc/pam_appl.sgml b/contrib/libpam/doc/pam_appl.sgml
deleted file mode 100644 (file)
index 19d85ff..0000000
+++ /dev/null
@@ -1,1569 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id: pam_appl.sgml,v 1.16 1997/04/05 06:49:14 morgan Exp morgan $
- $FreeBSD: src/contrib/libpam/doc/pam_appl.sgml,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $
- $DragonFly: src/contrib/libpam/doc/Attic/pam_appl.sgml,v 1.2 2003/06/17 04:24:02 dillon Exp $
-
-    Copyright (C) Andrew G. Morgan 1996, 1997.  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@linux.kernel.org</tt>
-<date>DRAFT v0.63 1998/1/18
-<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
-</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
-</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
-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 will 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 service is given to the user.  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>
-Here 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 service application
-the approprite <bf/Linux-PAM/ error-return value should be used
-here.
-attempt its purpose is to be passed as an argument to the
-module specific function <tt/cleanup()/ (see the <bf/Linux-PAM/
-<htmlurl url="pam_modules.html" name="Module Developers' Guide">).
-
-<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
-
-<tag><tt/PAM_USER/</tag>
-       The user name
-
-<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_RHOST/</tag>
-       The remote host name
-
-<tag><tt/PAM_CONV/</tag>
-       The conversation structure (see section <ref
-id="the-conversation-function" name="below">)
-
-<tag><tt/PAM_RUSER/</tag>
-       The remote user name
-
-<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: ''.
-
-</descrip>
-
-<p>
-For all <tt/item_type/s, other than <tt/PAM_CONV/, <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">).
-
-<p>
-A successful call to this function returns <tt/PAM_SUCCESS/.  However,
-the application should expect one of the following errors:
-
-<p>
-<descrip>
-<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 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!  A successful call is signaled by a return value of
-<tt/PAM_SUCCESS/.  If an attempt is made to get an undefined item,
-<tt/PAM_BAD_ITEM/ is returned.
-
-<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
-
-<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 HAVE_PAM_FAIL_DELAY
-    ....
-#endif /* HAVE_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 calls each of the <em/stacked/
-authentication modules listed in the <tt>/etc/pam.conf</tt> 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.
-
-<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 and after 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 access to 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 module 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 module 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>
-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 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>
-<tscreen>
-<verb>
-extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
-</verb>
-</tscreen>
-
-<p>
-<em>
-Warning, the environment support in <bf/Linux-PAM/ is based solely
-on a six line email from the developers at Sun. Its interface is
-likely to be generally correct, however, the details are likely to be
-changed as more information becomes available.
-</em>
-
-<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
-correspoding 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>
-<em>
-Warning, the environment support in <bf/Linux-PAM/ is based solely
-on a six-line email from the developers at Sun. Its interface is
-likely to be generally correct, however, the details are likely to be
-changed as more information becomes available.
-</em>
-
-<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>
-<em>
-Warning, the environment support in <bf/Linux-PAM/ is based solely
-on a six line email from the developers at Sun. Its interface is
-likely to be generally correct, however, the details are likely to be
-changed as more information becomes available.
-</em>
-
-<p>
-This function returns a pointer to the complete <tt/Linux-PAM/
-environment.  It is a pointer to a <em/read-only/ list of
-<em/read-only/ environment variables.  It should be noted that this
-memory will become invalid after a call to <tt/pam_end()/ (see the
-section <ref id="pam-end-section" name="above">).  If application
-wishes to make use of this list after such a call, it should first
-make a copy of all the set variables. (A function that performs such a
-transcription is to be found in <tt/libpam_misc/.)
-
-<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>
-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 (and in the interests of compatibility with
-Sunsoft).  The number of resposes 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>
-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 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 <tt>/etc/pam.conf</tt> 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 -- this should not be
-permitted to cause a security breach.
-
-<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,
-<tt>/etc/pam.conf</tt>, 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.  Basically, 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(2)/.
-
-<p>
-In addition the identity of a remote user, requesting the service from
-a distant location, will be placed in the <tt/PAM_RUSER/ item.
-
-<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.
-
-<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>Functions supplied
-
-<sect2>Safe string duplication
-
-<p>
-<tscreen>
-<verb>
-extern char *xstrdup(const char *s)
-</verb>
-</tscreen>
-Return 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=NULL/.
-
-<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.
-
-<tag><tt>extern int (*pam_binary_handler_fn)(const union pam_u_packet_p send,
-                     union pam_u_packet_p *receive);</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.)
-
-</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>Saving the Linux-PAM environment for later use
-<p>
-<tscreen>
-<verb>
-extern char **pam_misc_copy_env(pam_handle_t *pamh);
-</verb>
-</tscreen>
-
-This function returns a pointer to a list of environment variables
-that are a direct copy of the <bf/Linux-PAM/ environment.  The memory
-associated with these variables are the responsibility of the
-application and should be liberated with a call to
-<tt/pam_misc_drop_env()/.
-
-<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_misc_copy_env()/
-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 attatched 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 attatching 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 attatched 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 "proceedure", 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@transmeta.com) with many contributions from
-<!-- insert credits here -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $
-  -->
-Peter Allgeyer,
-Tim Baverstock,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Eric Hester,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Nicolai Langfeldt,
-Elliot Lee,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-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, 1997.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@transmeta.com&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: pam_appl.sgml,v 1.16 1997/04/05 06:49:14 morgan Exp morgan $</tt>
-
-</article>
diff --git a/contrib/libpam/doc/pam_modules.sgml b/contrib/libpam/doc/pam_modules.sgml
deleted file mode 100644 (file)
index 8499721..0000000
+++ /dev/null
@@ -1,1427 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id: pam_modules.sgml,v 1.19 1997/04/05 06:49:14 morgan Exp morgan $
- $FreeBSD: src/contrib/libpam/doc/pam_modules.sgml,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $
- $DragonFly: src/contrib/libpam/doc/Attic/pam_modules.sgml,v 1.2 2003/06/17 04:24:02 dillon Exp $
-
-    Copyright (c) Andrew G. Morgan 1996, 1997.  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@transmeta.com</tt>
-<date>DRAFT v0.59 1997/10/17
-<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 -lpam
-</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>
-(*This paragraph is currently under advisement with Sun*) 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 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 (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 <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>
-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.
-
-<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 either 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.
-
-<p>
-The return values for this function are listed in the 
-<bf>Linux-PAM</bf> Application Developers' Guide.
-
-<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.
-
-<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/ (0.54+) 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 HAVE_PAM_FAIL_DELAY
-    ....
-#endif /* HAVE_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 calls each of the <em/stacked/
-authentication modules listed in the <tt>/etc/pam.conf</tt> 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.
-
-</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 append such information to the application. It
-should only be called <em/after/ the user has been authenticated.
-
-<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>
-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>
-
-</itemize>
-
-<sect1> Account management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_ACCOUNT/ must be
-<tt/#define/'d prior to including <tt>&lt;security/pam_modules.h&gt;</tt>.
-This will ensure that the prototype for a static module is properly
-declared.
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function performs the task of establishing whether the user is
-permitted to gain access at this time. It should be understood that
-the user has previously been validated by an authentication
-module. This function checks for other things. Such things might be:
-the time of day or the date, the terminal line, remote
-hostname, etc. .
-
-<p>
-This function may also determine things like the expiration on
-passwords, and respond that the user change it before continuing.
-
-<p>
-Valid flags, which may be logically OR'd with <tt/PAM_SILENT/, are the
-same as those applicable to the <tt/flags/ argument of
-<tt/pam_sm_authenticate/.
-
-<p>
-This function may return one of the following errors,
-
-<descrip>
-
-<tag><tt/PAM_ACCT_EXPIRED/</tag>
-       The user is no longer permitted access to the system.
-<tag><tt/PAM_AUTH_ERR/</tag>
-       There was an authentication error.
-<tag><tt/PAM_AUTHTOKEN_REQD/</tag>
-       The user's authentication token has expired. Before calling
-this function again the application will arrange for a new one to be
-given. This will likely result in a call to <tt/pam_sm_chauthtok()/.
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-       The user is not known to the module's account management
-component.
-       
-</descrip>
-
-</itemize>
-
-<sect1> Session management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_SESSION/ must be
-<tt/#define/'d prior to including
-<tt>&lt;security/pam_modules.h&gt;</tt>.  This will ensure that the
-prototypes for static modules are properly declared.
-
-<p>
-The following two functions are defined to handle the
-initialization/termination of a session. For example, at the beginning
-of a session the module may wish to log a message with the system
-regarding the user. Similarly, at the end of the session the module
-would inform the system that the user's session has ended.
-
-<p>
-It should be possible for sessions to be opened by one application and
-closed by another. This either requires that the module uses only
-information obtained from <tt/pam_get_item()/, or that information
-regarding the session is stored in some way by the operating system
-(in a file for example).
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is called to commence a session. The only valid, but
-optional, flag is <tt/PAM_SILENT/.
-
-<p>
-As a return value, <tt/PAM_SUCCESS/ signals success and
-<tt/PAM_SESSION_ERR/ failure.
-
-<item>
-<tt>PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is called to terminate a session. The only valid, but
-optional, flag is <tt/PAM_SILENT/.
-
-<p>
-As a return value, <tt/PAM_SUCCESS/ signals success and
-<tt/PAM_SESSION_ERR/ failure.
-
-</itemize>
-
-<sect1> Password management
-
-<p>
-To be correctly initialized, <tt/PAM_SM_PASSWORD/ must be
-<tt/#define/'d prior to including <tt>&lt;security/pam_modules.h&gt;</tt>.
-This will ensure that the prototype for a static module is properly
-declared.
-
-<p>
-<itemize>
-
-<item>
-<tt>PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int
-argc, const char **argv);</tt>
-
-<p>
-This function is used to (re-)set the authentication token of the
-user. A valid flag, which may be logically OR'd with <tt/PAM_SILENT/,
-can be built from the following list,
-
-<descrip>
-<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag>
-       This argument indicates to the module that the users
-authentication token (password) should only be changed if it has
-expired. This flag is optional and <em/must/ be combined with one of
-the following two flags. Note, however, the following two options are
-<em/mutually exclusive/.
-
-<tag><tt/PAM_PRELIM_CHECK/</tag>
-       This indicates that the modules are being probed as to their
-ready status for altering the user's authentication token. If the
-module requires access to another system over some network it should
-attempt to verify it can connect to this system on receiving this
-flag. If a module cannot establish it is ready to update the user's
-authentication token it should return <tt/PAM_TRY_AGAIN/, this
-information will be passed back to the application.
-
-<tag><tt/PAM_UPDATE_AUTHTOK/</tag>
-       This informs the module that this is the call it should change
-the authorization tokens. If the flag is logically OR'd with
-<tt/PAM_CHANGE_EXPIRED_AUTHTOK/, the token is only changed if it has
-actually expired.
-
-</descrip>
-
-<p>
-Note, the <bf/Linux-PAM/ library calls this function twice in
-succession. The first time with <tt/PAM_PRELIM_CHECK/ and then, if the
-module does not return <tt/PAM_TRY_AGAIN/, subsequently with
-<tt/PAM_UPDATE_AUTHTOK/. It is only on the second call that the
-authorization token is (possibly) changed.
-
-<p>
-<tt/PAM_SUCCESS/ is the only successful return value, valid
-error-returns are:
-
-<descrip>
-<tag><tt/PAM_AUTHTOK_ERR/</tag>
-       The module was unable to obtain the new authentication token.
-       
-<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag>
-       The module was unable to obtain the old authentication token.
-
-<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag>
-       Cannot change the authentication token since it is currently
-locked.
-       
-<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag>
-       Authentication token aging has been disabled.
-
-<tag><tt/PAM_PERM_DENIED/</tag>
-       Permission denied.
-
-<tag><tt/PAM_TRY_AGAIN/</tag>
-       Preliminary check was unsuccessful. Signals an immediate return
-to the application is desired.
-
-<tag><tt/PAM_USER_UNKNOWN/</tag>
-       The user is not known to the authentication token changing
-service.
-
-</descrip>
-
-</itemize>
-
-<sect>Generic optional arguments
-
-<p>
-Here we list the generic arguments that all modules can expect to
-be passed. They are not mandatory, and their absence should be
-accepted without comment by the module.
-
-<p>
-<descrip>
-<tag><tt/debug/</tag>
-
-Use the <tt/syslog(3)/ call to log debugging information to the system
-log files.
-
-<tag><tt/no_warn/</tag>
-
-Instruct module to not give warning messages to the application.
-
-<tag><tt/use_first_pass/</tag>
-
-The module should not prompt the user for a password. Instead, it
-should obtain the previously typed password (by a call to
-<tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/ item), and use that. If
-that doesn't work, then the user will not be authenticated. (This
-option is intended for <tt/auth/ and <tt/passwd/ modules only).
-
-<tag><tt/try_first_pass/</tag>
-
-The module should attempt authentication with the previously typed
-password (by a call to <tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/
-item). If that doesn't work, then the user is prompted for a
-password. (This option is intended for <tt/auth/ modules only).
-
-<tag><tt/use_mapped_pass/</tag>
-
-<bf/WARNING:/ coding this functionality may cause the module writer to
-break <em/local/ encryption laws. For example, in the U.S. there are
-restrictions on the export computer code that is capable of strong
-encryption.  It has not been established whether this option is
-affected by this law, but one might reasonably assume that it does
-until told otherwise.  For this reason, this option is not supported
-by any of the modules distributed with <bf/Linux-PAM/.
-
-The intended function of this argument, however, is that the module
-should take the existing authentication token from a previously
-invoked module and use it as a key to retrieve the authentication
-token for this module. For example, the module might create a strong
-hash of the <tt/PAM_AUTHTOK/ item (established by a previously
-executed module). Then, with logical-exclusive-or, use the result as a
-<em/key/ to safely store/retrieve the authentication token for this
-module in/from a local file <em/etc/. .
-
-</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.
-
-<p>
-<sect>An example module file
-
-<p>
-<em>
-perhaps this should point to a place in the file structure!?
-</em>
-
-<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@transmeta.com/) with many contributions from
-<!-- insert credits here -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
-  -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $
-  -->
-Peter Allgeyer,
-Tim Baverstock,
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Oliver Crow,
-Chris Dent,
-Marc Ewing,
-Cristian Gafton,
-Eric Hester,
-Roger Hu,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Nicolai Langfeldt,
-Elliot Lee,
-Al Longyear,
-Ingo Luetkebohle,
-Marek Michalkiewicz,
-Aleph One,
-Martin Pool,
-Sean Reifschneider,
-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, 1997.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@transmeta.com&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: pam_modules.sgml,v 1.19 1997/04/05 06:49:14 morgan Exp morgan $</tt>
-
-</article>
diff --git a/contrib/libpam/doc/pam_source.sgml b/contrib/libpam/doc/pam_source.sgml
deleted file mode 100644 (file)
index 51dcab4..0000000
+++ /dev/null
@@ -1,987 +0,0 @@
-<!doctype linuxdoc system>
-
-<!--
-
- $Id: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $
- $FreeBSD: src/contrib/libpam/doc/pam_source.sgml,v 1.1.1.1.6.2 2001/06/11 15:28:10 markm Exp $
- $DragonFly: src/contrib/libpam/doc/Attic/pam_source.sgml,v 1.2 2003/06/17 04:24:02 dillon Exp $
-
-    Copyright (c) Andrew G. Morgan 1996,1997.  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@linux.kernel.org</tt>
-<date>DRAFT v0.59 1998/1/7
-<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>/usr/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 (Red Hat
-is one such distribution), 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>/usr/lib/security/</tt>. However, Red Hat
-Linux, in agreement with the Linux File System Standard (the FSSTND),
-places these files in <tt>/lib/security</tt>. Please be careful to
-perform the necessary transcription when using the examples from the
-text.
-
-<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>
-Traditinally, 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 the
-so 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 configuaration 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.
-
-<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   arguments
-</verb>
-</tscreen>
-Below, we explain the meaning of each of these tokens. The second (and
-more recently adopted) way of configuring <bf/Linux-PAM/ is via the
-contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained
-the meaning of the above tokens, we will describe this method.
-
-<p>
-<descrip>
-<tag><tt/service-name/</tag>
-The name of the service associated with this entry. Frequently the
-service name is the conventional name of the given application. For
-example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ .
-
-<p>
-There is a special <tt/service-name/, reserved for defining a default
-authentication mechanism. It has the name `<tt/OTHER/' and may be
-specified in either lower or upper case characters. Note, when there
-is a module specified for a named service, the `<tt/OTHER/' entries
-are ignored.
-
-<tag><tt/module-type/</tag>
-One of (currently) four types of module. The four types are as
-follows:
-<itemize>
-<item> <tt/auth/; this module type provides two aspects of
-authenticating the user. Firstly, it establishes that the user is who
-they claim to be, by instructing the application to prompt the user
-for a password or other means of identification. Secondly, the module
-can grant <tt/group/ membership (independently of the
-<tt>/etc/groups</tt> file discussed above) or other privileges through
-its <em/credential/ granting properties.
-
-<item> <tt/account/; this module performs non-authentication based
-account management. It is typically used to restrict/permit access to
-a service based on the time of day, currently available system
-resources (maximum number of users) or perhaps the location of the
-applicant user---`<tt/root/' login only on the console.
-
-<item> <tt/session/; primarily, this module is associated with doing
-things that need to be done for the user before/after they can be
-given service.  Such things include the logging of information
-concerning the opening/closing of some data exchange with a user,
-mounting directories, etc. .
-
-<item> <tt/password/; this last module type is required for updating the
-authentication token associated with the user. Typically, there is one
-module for each `challenge/response' based authentication (<tt/auth/)
-module-type.
-
-</itemize>
-
-<tag><tt/control-flag/</tag>
-
-The control-flag is used to indicate how the PAM library will react to
-the success or failure of the module it is associated with.  Since
-modules can be <em/stacked/ (modules of the same type execute in
-series, one after another), the control-flags determine the relative
-importance of each module.  The application is not made aware of the
-individual success or failure of modules listed in the
-`<tt>/etc/pam.conf</tt>' file.  Instead, it receives a summary
-<em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library.
-The order of execution of these modules is that of the entries in the
-<tt>/etc/pam.conf</tt> file; earlier entries are executed before later
-ones.  As of Linux-PAM v0.60, this <em/control-flag/ can be defined
-with one of two syntaxes.
-
-<p>
-The simpler (and historical) syntax for the control-flag is a single
-keyword defined to indicate the severity of concern associated with
-the success or failure of a specific module.  There are four such
-keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and
-<tt/optional/.
-
-<p>
-The Linux-PAM library interprets these keywords in the following
-manner:
-
-<itemize>
-
-<item> <tt/required/; this indicates that the success of the module is
-required for the <tt/module-type/ facility to succeed. Failure of this
-module will not be apparent to the user until all of the remaining
-modules (of the same <tt/module-type/) have been executed.
-
-<item> <tt/requisite/; like <tt/required/, however, in the case that
-such a module returns a failure, control is directly returned to the
-application.  The return value is that associated with the <em/first/
-<tt/required/ or <tt/requisite/ module to fail.  Note, this flag can be
-used to protect against the possibility of a user getting the
-opportunity to enter a password over an unsafe medium.  It is
-conceivable that such behavior might inform an attacker of valid
-accounts on a system. This possibility should be weighed against the
-not insignificant concerns of exposing a sensitive password in a
-hostile environment.
-
-<item> <tt/sufficient/; the success of this module is deemed
-`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this
-module-type has succeeded in its purpose. In the event that no
-previous <tt/required/ module has failed, no more `<em/stacked/'
-modules of this type are invoked. (Note, in this case subsequent
-<tt/required/ modules are <bf/not/ invoked.). A failure of this module
-is not deemed as fatal to satisfying the application that this
-<tt/module-type/ has succeeded.
-
-<item> <tt/optional/; as its name suggests, this <tt/control-flag/
-marks the module as not being critical to the success or failure of
-the user's application for service. However, in the absence of any
-successes of previous or subsequent stacked modules this module will
-determine the nature of the response to the application.
-
-</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 set explicitly.
-
-<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
-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>
-<bf>Note, at time of writing, this newer syntax is so new that I don't
-want to write too much about it.  Please play with this.  Report all
-the bugs and make suggestions for new actions (etc.).</bf>
-
-<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>/usr/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.
-
-</descrip>
-
-<p>
-Any line in (one of) the confiuration 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.  The other mode (and the one currently supported by Red Hat 4.2)
-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.
-
-</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       /usr/lib/security/pam_deny.so
-OTHER  account  required       /usr/lib/security/pam_deny.so
-OTHER  password required       /usr/lib/security/pam_deny.so
-OTHER  session  required       /usr/lib/security/pam_deny.so
-</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       /usr/lib/security/pam_warn.so
-OTHER  password required       /usr/lib/security/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       /usr/lib/security/pam_warn.so
-auth    required       /usr/lib/security/pam_deny.so
-account         required       /usr/lib/security/pam_deny.so
-password required      /usr/lib/security/pam_warn.so
-password required      /usr/lib/security/pam_deny.so
-session         required       /usr/lib/security/pam_deny.so
-</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 UNIX access
-#
-OTHER  auth     required       /usr/lib/security/pam_unix_auth.so
-OTHER  account  required       /usr/lib/security/pam_unix_acct.so
-OTHER  password required       /usr/lib/security/pam_unix_passwd.so
-OTHER  session  required       /usr/lib/security/pam_unix_session.so
-</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 UNIX access (the listfile entry blocks access to
-#      users listed in /etc/ftpusers)
-#
-ftpd   auth    sufficient  /usr/lib/security/pam_ftp.so
-ftpd   auth    required    /usr/lib/security/pam_unix_auth.so use_first_pass
-ftpd   auth    required    /usr/lib/security/pam_listfile.so \
-                       onerr=succeed item=user sense=deny file=/etc/ftpusers
-</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 UNIX authentication module that it
-is not to prompt for a password but rely one already having been
-obtained by the ftp module.
-
-<p>
-The standard UNIX modules, used above, are strongly tied to using the
-default `<tt/libc/' user database functions (see for example, <tt/man
-getpwent/).  It is the opinion of the author that these functions are
-not sufficently flexible to make full use of the power of
-<bf/Linux-PAM/.  For this reason, and as a small plug, I mention in
-passing that there is a pluggable replacement for the <tt/pam_unix_../
-modules; <tt/pam_pwdb/. See the section below for a more complete
-description.
-
-
-<sect>Security issues of Linux-PAM
-
-<p>
-This section will discuss good practices for using Linux-PAM in a
-secure manner.  <em>It is currently sadly lacking...suggestions are
-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_auth.so
-    account  required       pam_unix_acct.so
-    password required       pam_unix_passwd.so
-    session  required       pam_unix_session.so
-
-Now you have the simplest possible PAM configuration that
-will work the way you're used to.  Everything should
-magically start to work again.  Try it out by hitting ALT-F2
-and logging in on another virtual console.  If it doesn't
-work, you have bigger problems, or you've mistyped
-something.  One of the wonders of this system (seriously,
-perhaps) is that if you mistype anything in the conf files,
-you usually get no error reporting of any kind on the
-console - just some entries in the log file.  So look there!
-(Try 'tail /var/log/messages'.)
-
-From here you can go back and get a real configuration
-going, hopefully after you've tested it first on a machine
-you don't care about screwing up.  :/
-
-Some pointers (to make everything "right" with Red Hat...):
-
-    Install the newest pam, pamconfig, and pwdb from the
-    redhat current directory, and do it all on the same
-    command line with rpm...
-
-        rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-*
-
-    Then make sure you install (or reinstall) the newest
-    version of libc, util-linux, wuftp, and NetKit. For
-    kicks you might try installing the newest versions of
-    the affected x apps, like xlock, but I haven't gotten
-    those to work at all yet.
-
-</verb>
-
-<sect1>Avoid having a weak `other' configuration
-
-<p>
-It is not a good thing to have a weak default (<tt/OTHER/) entry.
-This service is the default configuration for all PAM aware
-applications and if it is weak, your system is likely to be vulnerable
-to attack.
-
-<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>/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="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.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt"
-name="http://www.pilgrim.umass.edu/pub/osf&lowbar;dce/RFC/rfc86.0.txt"></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@parc.power.net)
-with many contributions from
-<!-- insert credits here -->
-<!--
- an sgml list of people to credit for their contributions to Linux-PAM
- $Id: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $
-  -->
-Craig S. Bell,
-Derrick J. Brashear,
-Ben Buxton,
-Oliver Crow,
-Marc Ewing,
-Cristian Gafton,
-Eric Hester,
-Eric Jacksch,
-Michael K. Johnson,
-David Kinchlea,
-Elliot Lee,
-Al Longyear,
-Marek Michalkiewicz,
-Aleph One,
-Sean Reifschneider,
-Eric Troan,
-Theodore Ts'o,
-Jeff Uphoff,
-Ronald Wahl,
-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>
-More PAM modules are being developed all the time. It is unlikely that
-this document will ever be truely up to date!
-
-<p>
-Currently there is no documentation for PAM-aware applications.
-
-<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.  All rights reserved.
-<newline>
-Email: <tt>&lt;morgan@parc.power.net&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: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $</tt>
-
-</article>
diff --git a/contrib/libpam/doc/specs/rfc86.0.txt b/contrib/libpam/doc/specs/rfc86.0.txt
deleted file mode 100644 (file)
index 6dd5e6e..0000000
+++ /dev/null
@@ -1,1851 +0,0 @@
-
-
-
-
-
-
-
-
-   Open Software Foundation                              V. Samar (SunSoft)
-   Request For Comments: 86.0                         R. Schemers (SunSoft)
-   October 1995
-
-
-
-                              UNIFIED LOGIN WITH
-                    PLUGGABLE AUTHENTICATION MODULES (PAM)
-
-
-   1. INTRODUCTION
-
-      Since low-level authentication mechanisms constantly evolve, it is
-      important to shield the high-level consumers of these mechanisms
-      (system-entry services and users) from such low-level changes.  With
-      the Pluggable Authentication Module (PAM) framework, we can provide
-      pluggability for a variety of system-entry services -- not just
-      system authentication _per se_, but also for account, session and
-      password management.  PAM's ability to _stack_ authentication modules
-      can be used to integrate `login' with different authentication
-      mechanisms such as RSA, DCE, and Kerberos, and thus unify login
-      mechanisms.  The PAM framework can also provide easy integration of
-      smart cards into the system.
-
-      Modular design and pluggability have become important for users who
-      want ease of use.  In the PC hardware arena, no one wants to set the
-      interrupt vector numbers or resolve the addressing conflict between
-      various devices.  In the software arena, people also want to be able
-      to replace components easily for easy customization, maintenance, and
-      upgrades.
-
-      Authentication software deserves special attention because
-      authentication forms a very critical component of any secure computer
-      system.  The authentication infrastructure and its components may
-      have to be modified or replaced either because some deficiencies have
-      been found in the current algorithms, or because sites want to
-      enforce a different security policy than what was provided by the
-      system vendor.  The replacement and modification should be done in
-      such a way that the user is not affected by these changes.
-
-      The solution has to address not just how the applications use the new
-      authentication mechanisms in a generic fashion, but also how the user
-      will be authenticated to these mechanisms in a generic way.  The
-      former is addressed by GSS-API [Linn 93], while this RFC addresses
-      the later; these two efforts are complementary to each other.
-
-      Since most system-entry services (for example, `login', `dtlogin',
-      `rlogin', `ftp', `rsh') may want to be independent of the specific
-      authentication mechanisms used by the machine, it is important that
-      there be a framework for _plugging_ in various mechanisms.  This
-      requires that the system applications use a standard API to interact
-
-
-
-   Samar, Schemers                                                   Page 1
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      with the authentication services.  If these system-entry services
-      remain independent of the actual mechanism used on that machine, the
-      system administrator can install suitable authentication modules
-      without requiring changes to these applications.
-
-      For any security system to be successful, it has to be easy to use.
-      In the case of authentication, the single most important ease-of-use
-      characteristic is that the user should not be required to learn about
-      various ways of authentication and remember multiple passwords.
-      Ideally, there should be one all-encompassing authentication system
-      where there is only one password, but for heterogeneous sites,
-      multiple authentication mechanisms have to co-exist.  The problem of
-      integrating multiple authentication mechanisms such as Kerberos
-      [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor
-      88], is also referred to as _integrated login_, or _unified login_
-      problem.  Even if the user has to use multiple authentication
-      mechanisms, the user should not be forced to type multiple passwords.
-      Furthermore, the user should be able to use the new network identity
-      without taking any further actions.  The key here is in modular
-      integration of the network authentication technologies with `login'
-      and other system-entry services.
-
-      In this RFC we discuss the architecture and design of pluggable
-      authentication modules.  This design gives the capability to use
-      field-replaceable authentication modules along with unified login
-      capability.  It thus provides for both _pluggability_ and _ease-of-
-      use_.
-
-      The RFC is organized as follows.  We first motivate the need for a
-      generic way to authenticate the user by various system-entry services
-      within the operating system.  We describe the goals and constraints
-      of the design.  This leads to the architecture, description of the
-      interfaces, and _stacking_ of modules to get unified login
-      functionality.  We then describe our experience with the design, and
-      end with a description of future work.
-
-
-   2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS
-
-      An identification and authentication ("I&A") mechanism is used to
-      establish a user's identity the system (i.e., to a local machine's
-      operating system) and to other principals on the network.  On a
-      typical UNIX system, there are various ports of entry into the
-      system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and
-      `telnet'.  In all cases, the user has to be identified and
-      authenticated before granting appropriate access rights to the user.
-      The user identification and authentication for all these entry points
-      needs to be coordinated to ensure a secure system.
-
-      In most of the current UNIX systems, the login mechanism is based
-      upon verification of the password using the modified DES algorithm.
-
-
-
-   Samar, Schemers                                                   Page 2
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      The security of the implementation assumes that the password cannot
-      be guessed, and that the password does not go over the wire in the
-      clear.  These assumptions, however, are not universally valid.
-      Various programs are now available freely on the Internet that can
-      run dictionary attack against the encrypted password.  Further, some
-      of the network services (for example, `rlogin', `ftp', `telnet') send
-      the password over in clear, and there are "sniffer" programs freely
-      available to steal these passwords.  The classical assumptions may be
-      acceptable on a trusted network, but in an open environment there is
-      a need to use more restrictive and stronger authentication
-      mechanisms.  Examples of such mechanisms include Kerberos, RSA,
-      Diffie-Hellman, one-time password [Skey 94], and challenge-response
-      based smart card authentication systems.  Since this list will
-      continue to evolve, it is important that the system-entry services do
-      not have hard-coded dependencies on any of these authentication
-      mechanisms.
-
-
-   3. DESIGN GOALS
-
-      The goals of the PAM framework are as follows:
-
-        (a) The system administrator should be able to choose the default
-            authentication mechanism for the machine.  This can range from
-            a simple password-based mechanism to a biometric or a smart
-            card based system.
-
-        (b) It should be possible to configure the user authentication
-            mechanism on a per application basis.  For example, a site may
-            require S/Key password authentication for `telnet' access,
-            while allowing machine `login' sessions with just UNIX password
-            authentication.
-
-        (c) The framework should support the display requirements of the
-            applications.  For example, for a graphical login session such
-            as `dtlogin', the user name and the password may have to be
-            entered in a new window.  For networking system-entry
-            applications such as `ftp' and `telnet', the user name and
-            password has to be transmitted over the network to the client
-            machine.
-
-        (d) It should be possible to configure multiple authentication
-            protocols for each of those applications.  For example, one may
-            want the users to get authenticated by both Kerberos and RSA
-            authentication systems.
-
-        (e) The system administrator should be able to _stack_ multiple
-            user authentication mechanisms such that the user is
-            authenticated with all authentication protocols without
-            retyping the password.
-
-
-
-
-   Samar, Schemers                                                   Page 3
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-        (f) The architecture should allow for multiple passwords if
-            necessary to achieve higher security for users with specific
-            security requirements.
-
-        (g) The system-entry services should not be required to change when
-            the underlying mechanism changes.  This can be very useful for
-            third-party developers because they often do not have the
-            source code for these services.
-
-        (h) The architecture should provide for a _pluggable_ model for
-            system authentication, as well as for other related tasks such
-            as password, account, and session management.
-
-        (i) For backward-compatibility reasons, the PAM API should support
-            the authentication requirements of the current system-entry
-            services.
-
-      There are certain issues that the PAM framework does not specifically
-      address:
-
-        (a) We focus only on providing a generic scheme through which users
-            use passwords to establish their identities to the machine.
-            Once the identity is established, how the identity is
-            communicated to other interested parties is outside the scope
-            of this design.  There are efforts underway at IETF [Linn 93]
-            to develop a Generic Security Services Application Interface
-            (GSSAPI) that can be used by applications for secure and
-            authenticated communication without knowing the underlying
-            mechanism.
-
-        (b) The _single-signon_ problem of securely transferring the
-            identity of the caller to a remote site is not addressed.  For
-            example, the problem of delegating credentials from the
-            `rlogin' client to the other machine without typing the
-            password is not addressed by our work.  We also do not address
-            the problem of sending the passwords over the network in the
-            clear.
-
-        (c) We do not address the source of information obtained from the
-            "`getXbyY()'" family of calls (e.g., `getpwnam()').  Different
-            operating systems address this problem differently.  For
-            example, Solaris uses the name service switch (NSS) to
-            determine the source of information for the "`getXbyY()'"
-            calls.  It is expected that data which is stored in multiple
-            sources (such as passwd entries in NIS+ and the DCE registry)
-            is kept in sync using the appropriate commands (such as
-            `passwd_export').
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 4
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   4. OVERVIEW OF THE PAM FRAMEWORK
-
-      We propose that the goals listed above can be met through a framework
-      in which authentication modules can be _plugged_ independently of the
-      application.  We call this the _Pluggable Authentication Modules_
-      (PAM) framework.
-
-      The core components of the PAM framework are the authentication
-      library API (the front end) and the authentication mechanism-specific
-      modules (the back end), connected through the Service Provider
-      Interface (SPI).  Applications write to the PAM API, while the
-      authentication-system providers write to the PAM SPI and supply the
-      back end modules that are independent of the application.
-
-             ftp     telnet   login   (Applications)
-              |        |        |
-              |        |        |
-              +--------+--------+
-                       |
-                 +-----+-----+
-                 |  PAM API  |   <-- pam.conf file
-                 +-----+-----+
-                       |
-              +--------+--------+
-            UNIX   Kerberos  Smart Cards   (Mechanisms)
-
-               Figure 1: The Basic PAM Architecture
-
-      Figure 1 illustrates the relationship between the application, the
-      PAM library, and the authentication modules.  Three applications
-      (`login', `telnet' and `ftp') are shown which use the PAM
-      authentication interfaces.  When an application makes a call to the
-      PAM API, it loads the appropriate authentication module as determined
-      by the configuration file, `pam.conf'.  The request is forwarded to
-      the underlying authentication module (for example, UNIX password,
-      Kerberos, smart cards) to perform the specified operation.  The PAM
-      layer then returns the response from the authentication module to the
-      application.
-
-      PAM unifies system authentication and access control for the system,
-      and allows plugging of associated authentication modules through well
-      defined interfaces.  The plugging can be defined through various
-      means, one of which uses a configuration file, such as the one in
-      Table 1.  For each of the system applications, the file specifies the
-      authentication module that should be loaded.  In the example below,
-      `login' uses the UNIX password module, while `ftp' and `telnet' use
-      the S/Key module.
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 5
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            Table 1: A Simplified View of a Sample PAM Configuration File.
-
-                               service    module_path
-                               -------    -----------
-                               login      pam_unix.so
-                               ftp        pam_skey.so
-                               telnet     pam_skey.so
-
-      Authentication configuration is only one aspect of this interface.
-      Other critical components include account management, session
-      management, and password management.  For example, the `login'
-      program may want to verify not only the password but also whether the
-      account has aged or expired.  Generic interfaces also need to be
-      provided so that the password can be changed according to the
-      requirements of the module.  Furthermore, the application may want to
-      log information about the current session as determined by the
-      module.
-
-      Not all applications or services may need all of the above
-      components, and not each authentication module may need to provide
-      support for all of the interfaces.  For example, while `login' may
-      need access to all four components, `su' may need access to just the
-      authentication component.  Some applications may use some specific
-      authentication and password management modules but share the account
-      and session management modules with others.
-
-      This reasoning leads to a partitioning of the entire set of
-      interfaces into four areas of functionality: (1) authentication, (2)
-      account, (3) session, and (4) password.  The concept of PAM was
-      extended to these functional areas by implementing each of them as a
-      separate pluggable module.
-
-      Breaking the functionality into four modules helps the module
-      providers because they can use the system-provided libraries for the
-      modules that they are not changing.  For example, if a supplier wants
-      to provide a better version of Kerberos, they can just provide that
-      new authentication and password module, and reuse the existing ones
-      for account and session.
-
-   4.1. Module Description
-
-      More details on specific API's are described in Appendix A.  A brief
-      description of four modules follows:
-
-        (a) Authentication management: This set includes the
-            `pam_authenticate()' function to authenticate the user, and the
-            `pam_setcred()' interface to set, refresh or destroy the user
-            credentials.
-
-        (b) Account management: This set includes the `pam_acct_mgmt()'
-            function to check whether the authenticated user should be
-
-
-
-   Samar, Schemers                                                   Page 6
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            given access to his/her account.  This function can implement
-            account expiration and access hour restrictions.
-
-        (c) Session management: This set includes the `pam_open_session()'
-            and `pam_close_session()' functions for session management and
-            accounting.  For example, the system may want to store the
-            total time for the session.
-
-        (d) Password management: This set includes a function,
-            `pam_chauthtok()', to change the password.
-
-
-   5. FRAMEWORK INTERFACES
-
-      The PAM framework further provides a set of administrative interfaces
-      to support the above modules and to provide for application-module
-      communication.  There is no corresponding service provider interface
-      (SPI) for such functions.
-
-   5.1. Administrative Interfaces
-
-      Each set of PAM transactions starts with `pam_start()' and ends with
-      the `pam_end()' function.  The interfaces `pam_get_item()' and
-      `pam_set_item()' are used to read and write the state information
-      associated with the PAM transaction.
-
-      If there is any error with any of the PAM interfaces, the error
-      message can be printed with `pam_strerror()'.
-
-   5.2. Application-Module Communication
-
-      During application initialization, certain data such as the user name
-      is saved in the PAM framework layer through `pam_start()' so that it
-      can be used by the underlying modules.  The application can also pass
-      opaque data to the module which the modules will pass back while
-      communicating with the user.
-
-   5.3. User-Module Communication
-
-      The `pam_start()' function also passes conversation function that has
-      to be used by the underlying modules to read and write module
-      specific authentication information.  For example, these functions
-      can be used to prompt the user for the password in a way determined
-      by the application.  PAM can thus be used by graphical, non-
-      graphical, or networked applications.
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 7
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   5.4. Inter-Module Communication
-
-      Though the modules are independent, they can share certain common
-      information about the authentication session such as user name,
-      service name, password, and conversation function through the
-      `pam_get_item()' and `pam_set_item()' interfaces.  These API's can
-      also be used by the application to change the state information after
-      having called `pam_start()' once.
-
-   5.5. Module State Information
-
-      The PAM service modules may want to keep certain module-specific
-      state information about the session.  The interfaces `pam_get_data()'
-      and `pam_set_data()' can be used by the service modules to access and
-      update module-specific information as needed from the PAM handle.
-      The modules can also attach a cleanup function with the data.  The
-      cleanup function is executed when `pam_end()' is called to indicate
-      the end of the current authentication activity.
-
-      Since the PAM modules are loaded upon demand, there is no direct
-      module initialization support in the PAM framework.  If there are
-      certain initialization tasks that the PAM service modules have to do,
-      they should be done upon the first invocation.  However, if there are
-      certain clean-up tasks to be done when the authentication session
-      ends, the modules should use `pam_set_data()' to specify the clean-up
-      functions, which would be called when `pam_end()' is called by the
-      application.
-
-
-   6. MODULE CONFIGURATION MANAGEMENT
-
-      Table 2 shows an example of a configuration file `pam.conf' with
-      support for authentication, session, account, and password management
-      modules.  `login' has three entries: one each for authentication
-      processing, session management and account management.  Each entry
-      specifies the module name that should be loaded for the given module
-      type.  In this example, the `ftp' service uses the authentication and
-      session modules.  Note that all services here share the same session
-      management module, while having different authentication modules.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                   Page 8
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            Table 2: Configuration File (pam.conf) with Different Modules
-                     and Control Flow
-
-            service module_type control_flag module_path         options
-            ------- ----------- ------------ -----------         -------
-            login   auth        required     pam_unix_auth.so    nowarn
-            login   session     required     pam_unix_session.so
-            login   account     required     pam_unix_account.so
-            ftp     auth        required     pam_skey_auth.so    debug
-            ftp     session     required     pam_unix_session.so
-            telnet  session     required     pam_unix_session.so
-            login   password    required     pam_unix_passwd.so
-            passwd  password    required     pam_unix_passwd.so
-            OTHER   auth        required     pam_unix_auth.so
-            OTHER   session     required     pam_unix_session.so
-            OTHER   account     required     pam_unix_account.so
-
-      The first field, _service_, denotes the service (for example,
-      `login', `passwd', `rlogin').  The name `OTHER' indicates the module
-      used by all other applications that have not been specified in this
-      file.  This name can also be used if all services have the same
-      requirements.  In the example, since all the services use the same
-      session module, we could have replaced those lines with a single
-      `OTHER' line.
-
-      The second field, _module_type_, indicates the type of the PAM
-      functional module.  It can be one of `auth', `account', `session', or
-      `password' modules.
-
-      The third field, _control_flag_ determines the behavior of stacking
-      multiple modules by specifying whether any particular module is
-      _required_, _sufficient_, or _optional_.  The next section describes
-      stacking in more detail.
-
-      The fourth field, _module_path_, specifies the location of the
-      module.  The PAM framework loads this module upon demand to invoke
-      the required function.
-
-      The fifth field, _options_, is used by the PAM framework layer to
-      pass module specific options to the modules.  It is up to the module
-      to parse and interpret the options.  This field can be used by the
-      modules to turn on debugging or to pass any module specific
-      parameters such as a timeout value.  It is also used to support
-      unified login as described below.  The options field can be used by
-      the system administrator to fine-tune the PAM modules.
-
-      If any of the fields are invalid, or if a module is not found, that
-      line is ignored and the error is logged as a critical error via
-      `syslog(3)'.  If no entries are found for the given module type, then
-      the PAM framework returns an error to the application.
-
-
-
-
-   Samar, Schemers                                                   Page 9
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING
-
-      In the world of heterogeneous systems, the system administrator often
-      has to deal with the problem of integrating multiple authentication
-      mechanisms.  The user is often required to know about the
-      authentication command of the new authentication module (for example,
-      `kinit', `dce_login') after logging into the system.  This is not
-      user-friendly because it forces people to remember to type the new
-      command and enter the new password.  This functionality should be
-      invisible instead of burdening the user with it.
-
-      There are two problems to be addressed here:
-
-        (a) Supporting multiple authentication mechanisms.
-
-        (b) Providing unified login in the presence of multiple mechanisms.
-
-      In the previous section, we described how one could replace the
-      default authentication module with any other module of choice.  Now
-      we demonstrate how the same model can be extended to provide support
-      for multiple modules.
-
-   7.1. Design for Stacked Modules
-
-      One possibility was to provide hard-coded rules in `login' or other
-      applications requiring authentication services [Adamson 95].  But
-      this becomes very specific to the particular combination of
-      authentication protocols, and also requires the source code of the
-      application.  Digital's Security Integration Architecture [SIA 95]
-      addresses this problem by specifying the same list of authentication
-      modules for all applications.  Since requirements for various
-      applications can vary, it is essential that the configuration be on a
-      per-application basis.
-
-      To support multiple authentication mechanisms, the PAM framework was
-      extended to support _stacking_.  When any API is called, the back
-      ends for the stacked modules are invoked in the order listed, and the
-      result returned to the caller.  In Figure 2, the authentication
-      service of `login' is stacked and the user is authenticated by UNIX,
-      Kerberos, and RSA authentication mechanisms.  Note that in this
-      example, there is no stacking for session or account management
-      modules.
-
-
-
-
-
-
-
-
-
-
-
-
-   Samar, Schemers                                                  Page 10
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-                             login
-                               |
-                      +--------+--------+
-                      |        |        |
-                   session   auth    account
-                      |        |        |
-                   +--+--+  +--+--+  +--+--+
-                   | PAM |  | PAM |  | PAM |
-                   +--+--+  +--+--+  +--+--+
-                      |        |        |
-                    UNIX     UNIX     UNIX
-                   session   auth    account
-                               |
-                            Kerberos
-                              auth
-                               |
-                              RSA
-                              auth
-
-            Figure 2: Stacking With the PAM Architecture
-
-      Stacking is specified through additional entries in the configuration
-      file shown earlier.  As shown in Table 2, for each application (such
-      as `login') the configuration file can specify multiple mechanisms
-      that have to be invoked in the specified order.  When mechanisms
-      fail, the _control_flag_ decides which error should be returned to
-      the application.  Since the user should not know which authentication
-      module failed when a bad password was typed, the PAM framework
-      continues to call other authentication modules on the stack even on
-      failure.  The semantics of the control flag are as follows:
-
-        (a) `required': With this flag, the module failure results in the
-            PAM framework returning the error to the caller _after_
-            executing all other modules on the stack.  For the function to
-            be able to return success to the application all `required'
-            modules have to report success.  This flag is normally set when
-            authentication by this module is a _must_.
-
-        (b) `optional': With this flag, the PAM framework ignores the
-            module failure and continues with the processing of the next
-            module in sequence.  This flag is used when the user is allowed
-            to login even if that particular module has failed.
-
-        (c) `sufficient': With this flag, if the module succeeds the PAM
-            framework returns success to the application immediately
-            without trying any other modules.  For failure cases, the
-            _sufficient_ modules are treated as `optional'.
-
-      Table 3 shows a sample configuration file that stacks the `login'
-      command.  Here the user is authenticated by UNIX, Kerberos, and RSA
-      authentication services.  The `required' key word for _control_flag_
-
-
-
-   Samar, Schemers                                                  Page 11
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      enforces that the user is allowed to login only if he/she is
-      authenticated by _both_ UNIX and Kerberos services.  RSA
-      authentication is optional by virtue of the `optional' key word in
-      the _control_flag_ field.  The user can still log in even if RSA
-      authentication fails.
-
-              Table 3: PAM Configuration File with Support for Stacking
-
-            service module_type control_flag module_path options
-            ------- ----------- ------------ ----------- -------
-            login   auth        required     pam_unix.so debug
-            login   auth        required     pam_kerb.so use_mapped_pass
-            login   auth        optional     pam_rsa.so  use_first_pass
-
-      Table 4 illustrates the use of the sufficient flag for the `rlogin'
-      service.  The Berkeley `rlogin' protocol specifies that if the remote
-      host is trusted (as specified in the `/etc/hosts.equiv' file or in
-      the `.rhosts' file in the home directory of the user), then the
-      `rlogin' daemon should not require the user to type the password.  If
-      this is not the case, then the user is required to type the password.
-      Instead of hard coding this policy in the `rlogin' daemon, this can
-      be expressed with the `pam.conf' file in Table 4.  The PAM module
-      `pam_rhosts_auth.so.1' implements the `.rhosts' policy described
-      above.  If a site administrator wants to enable remote login with
-      only passwords, then the first line should be deleted.
-
-            Table 4: PAM Configuration File for the rlogin service
-
-            service module_type control_flag module_path        options
-            ------- ----------- ------------ -----------        -------
-            rlogin  auth        sufficient   pam_rhosts_auth.so
-            rlogin  auth        required     pam_unix.so
-
-   7.2. Password-Mapping
-
-      Multiple authentication mechanisms on a machine can lead to multiple
-      passwords that users have to remember.  One attractive solution from
-      the ease-of-use viewpoint is to use the same password for all
-      mechanisms.  This, however, can also weaken the security because if
-      that password were to be compromised in any of the multiple
-      mechanisms, all mechanisms would be compromised at the same time.
-      Furthermore, different authentication mechanisms may have their own
-      distinctive password requirements in regards to its length, allowed
-      characters, time interval between updates, aging, locking, and so
-      forth.  These requirements make it problematic to use the same
-      password for multiple authentication mechanisms.
-
-      The solution we propose, while not precluding use of the same
-      password for every mechanism, allows for a different password for
-      each mechanism through what we call _password-mapping_.  This
-      basically means using the user's _primary_ password to encrypt the
-
-
-
-   Samar, Schemers                                                  Page 12
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      user's other (_secondary_) passwords, and storing these encrypted
-      passwords in a place where they are available to the user.  Once the
-      primary password is verified, the authentication modules would obtain
-      the other passwords for their own mechanisms by decrypting the
-      mechanism-specific encrypted password with the primary password, and
-      passing it to the authentication service.  The security of this
-      design for password-mapping assumes that the primary password is the
-      user's strongest password, in terms of its unguessability (length,
-      type and mix of characters used, etc.).
-
-      If there is any error in password-mapping, or if the mapping does not
-      exist, the user will be prompted for the password by each
-      authentication module.
-
-      To support password-mapping, the PAM framework saves the primary
-      password and provides it to stacked authentication modules.  The
-      password is cleared out before the `pam_authenticate' function
-      returns.
-
-      How the password is encrypted depends completely on the module
-      implementation.  The encrypted secondary password (also called a
-      "mapped password") can be stored in a trusted or untrusted place,
-      such as a smart card, a local file, or a directory service.  If the
-      encrypted passwords are stored in an untrusted publicly accessible
-      place, this does provide an intruder with opportunities for potential
-      dictionary attack.
-
-      Though password-mapping is voluntary, it is recommended that all
-      module providers add support for the following four mapping options:
-
-        (a) `use_first_pass': Use the same password used by the first
-            mechanism that asked for a password.  The module should not ask
-            for the password if the user cannot be authenticated by the
-            first password.  This option is normally used when the system
-            administrator wants to enforce the same password across
-            multiple modules.
-
-        (b) `try_first_pass': This is the same as `use_first_pass', except
-            that if the primary password is not valid, it should prompt the
-            user for the password.
-
-        (c) `use_mapped_pass': Use the password-mapping scheme to get the
-            actual password for this module.  One possible implementation
-            is to get the mapped-password using the XFN API [XFN 94], and
-            decrypt it with the primary password to get the module-specific
-            password.  The module should not ask for the password if the
-            user cannot be authenticated by the first password.  The XFN
-            API allows user-defined attributes (such as _mapped-password_)
-            to be stored in the _user-context_.  Using the XFN API is
-            particularly attractive because support for the XFN may be
-            found on many systems in the future.
-
-
-
-   Samar, Schemers                                                  Page 13
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-        (d) `try_mapped_pass': This is the same as `use_mapped_pass',
-            except that if the primary password is not valid, it should
-            prompt the user for the password.
-
-      When passwords get updated, the PAM framework stores both the old as
-      well as the new password to be able to inform other dependent
-      authentication modules about the change.  Other modules can use this
-      information to update the encrypted password without forcing the user
-      to type the sequence of passwords again.  The PAM framework clears
-      out the passwords before returning to the application.
-
-      Table 3 illustrates how the same password can be used by `login' for
-      authenticating to the standard UNIX login, Kerberos and RSA services.
-      Once the user has been authenticated to the primary authentication
-      service (UNIX `login' in this example) with the primary password, the
-      option `use_mapped_pass' indicates to the Kerberos module that it
-      should use the primary password to decrypt the stored Kerberos
-      password and then use the Kerberos password to get the ticket for the
-      ticket-granting-service.  After that succeeds, the option
-      `use_first_pass' indicates to the RSA module that instead of
-      prompting the user for a password, it should use the primary password
-      typed earlier for authenticating the user.  Note that in this
-      scenario, the user has to enter the password just once.
-
-      Note that if a one-time password scheme (e.g., S/Key) is used,
-      password mapping cannot apply.
-
-   7.3. Implications of Stacking on the PAM Design
-
-      Because of the stacking capability of PAM, we have designed the PAM
-      API's to not return any data to the application, except status.  If
-      this were not the case, it would be difficult for the PAM framework
-      to decide which module should return data to the application.  When
-      there is any error, the application does not know which of the
-      modules failed.  This behavior enables (even requires) the
-      application to be completely independent from the modules.
-
-      Another design decision we have made is that PAM gives only the user
-      name to all the underlying PAM modules, hence it is the
-      responsibility of the PAM modules to convert the name to their own
-      internal format.  For example, the Kerberos module may have to
-      convert the UNIX user name to a Kerberos principal name.
-
-      Stacking also forces the modules to be designed such that they can
-      occur anywhere in the stack without any side-effects.
-
-      Since modules such as the authentication and the password module are
-      very closely related, it is important they be configured in the same
-      order and with compatible options.
-
-
-
-
-
-   Samar, Schemers                                                  Page 14
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-   8. INTEGRATION WITH SMART CARDS
-
-      Many networking authentication protocols require possession of a long
-      key to establish the user identity.  For ease-of-use reasons, that
-      long key is normally encrypted with the user's password so that the
-      user is not required to memorize it.  However, weak passwords can be
-      compromised through a dictionary attack and thus undermine the
-      stronger network authentication mechanism.  Furthermore, the
-      encrypted data is normally stored in a centrally accessible service
-      whose availability depends upon the reliability of the associated
-      service.  Solutions have been proposed to use a pass-phrase or one-
-      time-password, but those are much longer than the regular eight
-      character passwords traditionally used with UNIX `login'.  This makes
-      the solution user-unfriendly because it requires longer strings to be
-      remembered and typed.
-
-      For most authentication protocol implementations, the trust boundary
-      is the local machine.  This assumption may not be valid in cases
-      where the user is mobile and has to use publicly available networked
-      computers.  In such cases, it is required that the clear text of the
-      key or the password never be made available to the machine.
-
-      Smart cards solve the above problems by reducing password exposure by
-      supporting a _two factor_ authentication mechanism: the first with
-      the possession of the card, and the second with the knowledge of the
-      PIN associated with the card.  Not only can the smart cards be a
-      secure repository of multiple passwords, they can also provide the
-      encryption and authentication functions such that the long (private)
-      key is never exposed outside the card.
-
-      The PAM framework allows for integrating smart cards to the system by
-      providing a smart card specific module for authentication.
-      Furthermore, the unified login problem is simplified because the
-      multiple passwords for various authentication mechanisms can be
-      stored on the smart card itself.  This can be enabled by adding a
-      suitable key-word such as `use_smart_card' in the _options_ field.
-
-
-   9. SECURITY ISSUES
-
-      It is important to understand the impact of PAM on the security of
-      any system so that the site-administrator can make an informed
-      decision.
-
-        (a) Sharing of passwords with multiple authentication mechanisms.
-
-            If there are multiple authentication modules, one possibility
-            is to use the same password for all of them.  If the password
-            for any of the multiple authentication system is compromised,
-            the user's password in all systems would be compromised.  If
-            this is a concern, then multiple passwords might be considered
-
-
-
-   Samar, Schemers                                                  Page 15
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-            at the cost of ease-of-use.
-
-        (b) Password-mapping.
-
-            This technique of encrypting all other passwords with the
-            primary password assumes that it is lot more difficult to crack
-            the primary password and that reasonable steps have been taken
-            to ensure limited availability of the encrypted primary
-            password.  If this is not done, an intruder could target the
-            primary password as the first point of dictionary attack.  If
-            one of the other modules provide stronger security than the
-            password based security, the site would be negating the strong
-            security by using password-mapping.  If this is a concern, then
-            multiple passwords might be considered at the cost of ease-of-
-            use.  If smart cards are used, they obviate the need for
-            password-mapping completely.
-
-        (c) Security of the configuration file.
-
-            Since the policy file dictates how the user is authenticated,
-            this file should be protected from unauthorized modifications.
-
-        (d) Stacking various PAM modules.
-
-            The system administrator should fully understand the
-            implications of stacking various modules that will be installed
-            on the system and their respective orders and interactions.
-            The composition of various authentication modules should be
-            carefully examined.  The trusted computing base of the machine
-            now includes the PAM modules.
-
-
-   10. EXPERIENCE WITH PAM
-
-      The PAM framework was first added in Solaris 2.3 release as a private
-      internal interface.  PAM is currently being used by several system
-      entry applications such as `login', `passwd', `su', `dtlogin',
-      `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init',
-      `sac', and `ttymon'.  We have found that PAM provides an excellent
-      framework to encapsulate the authentication-related tasks for the
-      entire system.  The Solaris 2.3 PAM API's were hence enhanced and
-      simplified to support stacking.
-
-      PAM modules have been developed for UNIX, DCE, Kerberos, S/Key,
-      remote user authentication, and dialpass authentication.  Other PAM
-      modules are under development, and integration with smart cards is
-      being planned.
-
-      Some third parties have used the PAM interface to extend the security
-      mechanisms offered by the Solaris environment.
-
-
-
-
-   Samar, Schemers                                                  Page 16
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      The PAM API has been accepted by Common Desktop Environment (CDE)
-      vendors as the API to be used for integrating the graphical interface
-      for login, `dtlogin' with multiple authentication mechanisms.
-
-
-   11. FUTURE WORK
-
-      Amongst the various components of PAM, the password component needs
-      to be carefully examined to see whether the stacking semantics are
-      particularly applicable, and how PAM should deal with partial
-      failures when changing passwords.
-
-      The _control_flag_ of the configuration file can be extended to
-      include other semantics.  For example, if the error is "name service
-      not available", one may want to retry.  It is also possible to offer
-      semantics of "return success if any of the modules return success".
-
-      In an earlier section, we had mentioned integration of smart cards
-      with PAM.  Though we feel that integration should be straight forward
-      from the PAM architecture point of view, there may be some issues
-      with implementation because the interfaces to the smart cards have
-      not yet been standardized.
-
-      One possible extension to PAM is to allow the passing of module-
-      specific data between applications and PAM modules.  For example, the
-      `login' program likes to build its new environment from a select list
-      of variables, yet the DCE module needs the `KRB5CCNAME' variable to
-      be exported to the child process.  For now we have modified the
-      `login' program to explicitly export the `KRB5CCNAME' variable.
-
-      Administrative tools are needed to help system administrators modify
-      `pam.conf', and perform sanity checks on it (i.e., a `pam_check'
-      utility).
-
-
-   12. CONCLUSION
-
-      The PAM framework and the module interfaces provide pluggability for
-      user authentication, as well as for account, session and password
-      management.  The PAM architecture can be used by `login' and by all
-      other system-entry services, and thus ensure that all entry points
-      for the system have been secured.  This architecture enables
-      replacement and modification of authentication modules in the field
-      to secure the system against the newly found weaknesses without
-      changing any of the system services.
-
-      The PAM framework can be used to integrate `login' and `dtlogin' with
-      different authentication mechanisms such as RSA and Kerberos.
-      Multiple authentication systems can be accessed with the same
-      password.  The PAM framework also provides easy integration of smart
-      cards into the system.
-
-
-
-   Samar, Schemers                                                  Page 17
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      PAM provides complementary functionality to GSS-API, in that it
-      provides mechanisms through which the user gets authenticated to any
-      new system-level authentication service on the machine.  GSS-API then
-      uses the credentials for authenticated and secure communications with
-      other application-level service entities on the network.
-
-
-   13. ACKNOWLEDGEMENTS
-
-      PAM development has spanned several release cycles at SunSoft.
-      Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and
-      implementation.  Bill Shannon and Don Stephenson helped with the PAM
-      architecture.  Rocky Wu prototyped stacking of multiple modules.
-      Paul Fronberg, Charlie Lai, and Roland Schemers made very significant
-      enhancements to the PAM interfaces and took the project to completion
-      within a very short time.  Kathy Slattery wrote the PAM
-      documentation.  John Perry integrated PAM within the CDE framework.
-
-
-   APPENDIX A. PAM API'S
-
-      This appendix gives an informal description of the various interfaces
-      of PAM.  Since the goal here is just for the reader to get a working
-      knowledge about the PAM interfaces, not all flags and options have
-      been fully defined and explained.  The API's described here are
-      subject to change.
-
-      The PAM Service Provider Interface is very similar to the PAM API,
-      except for one extra parameter to pass module-specific options to the
-      underlying modules.
-
-   A.1. Framework Layer API's
-
-            int
-            pam_start(
-                char *service_name,
-                char *user,
-                struct pam_conv *pam_conversation,
-                pam_handle_t **pamh
-            );
-
-      `pam_start()' is called to initiate an authentication transaction.
-      `pam_start()' takes as arguments the name of the service, the name of
-      the user to be authenticated, the address of the conversation
-      structure.  `pamh' is later used as a handle for subsequent calls to
-      the PAM library.
-
-      The PAM modules do not communicate directly with the user; instead
-      they rely on the application to perform all such interaction.  The
-      application needs to provide the conversation functions, `conv()',
-      and associated application data pointers through a `pam_conv'
-
-
-
-   Samar, Schemers                                                  Page 18
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      structure when it initiates an authentication transaction.  The
-      module uses the `conv()' function to prompt the user for data,
-      display error messages, or text information.
-
-            int
-            pam_end(
-                pam_handle_t *pamh,
-                int pam_status
-            );
-
-      `pam_end()' is called to terminate the PAM transaction as specified
-      by `pamh', and to free any storage area allocated by the PAM modules
-      with `pam_set_item()'.
-
-            int
-            pam_set_item(
-                pam_handle_t *pamh,
-                int item_type,
-                void *item
-            );
-
-            int
-            pam_get_item(
-                pam_handle_t *pamh,
-                int item_type,
-                void **item);
-
-      `pam_get_item()' and `pam_set_item()' allow the parameters specified
-      in the initial call to `pam_start()' to be read and updated.  This is
-      useful when a particular parameter is not available when
-      `pam_start()' is called or must be modified after the initial call to
-      `pam_start()'.  `pam_set_item()' is passed a pointer to the object,
-      `item', and its type, `item_type'.  `pam_get_item()' is passed the
-      address of the pointer, `item', which is assigned the address of the
-      requested object.
-
-      The `item_type' is one of the following:
-
-                   Table 5: Possible Values for Item_type
-
-            Item Name       Description
-            ---------       -----------
-            PAM_SERVICE     The service name
-            PAM_USER        The user name
-            PAM_TTY         The tty name
-            PAM_RHOST       The remote host name
-            PAM_CONV        The pam_conv structure
-            PAM_AUTHTOK     The authentication token (password)
-            PAM_OLDAUTHTOK  The old authentication token
-            PAM_RUSER       The remote user name
-
-
-
-
-   Samar, Schemers                                                  Page 19
-
-
-
-
-
-
-
-   OSF-RFC 86.0                      PAM                       October 1995
-
-
-
-      Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only
-      available to PAM modules and not to the applications.  They are
-      explicitly cleared out by the framework before returning to the
-      application.
-
-            char *
-            pam_strerror(
-                int errnum
-            );
-
-      `pam_strerror()' maps the error number to a PAM error message string,
-      and returns a pointer to that string.
-
-            int
-            pam_set_data(
-                pam_handle_t *pamh,
-                char *module_data_name,
-                char *data,
-                (*cleanup)(pam_handle_t *pamh, char *data,
-                           int error_status)
-            );
-