summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrew G. Morgan <morgan@kernel.org>2000-06-20 22:10:38 +0000
committerAndrew G. Morgan <morgan@kernel.org>2000-06-20 22:10:38 +0000
commitea488580c42e8918445a945484de3c8a5addc761 (patch)
treec992f3ba699caafedfadc16af38e6359c3c24698
Initial revision
-rw-r--r--.cvsignore4
-rw-r--r--CHANGELOG1244
-rw-r--r--Copyright41
-rw-r--r--Makefile283
-rw-r--r--README167
-rw-r--r--bin/.cvsignore3
-rw-r--r--bin/README45
-rw-r--r--conf/.cvsignore2
-rw-r--r--conf/Makefile34
-rwxr-xr-xconf/install178
-rwxr-xr-xconf/install_conf36
-rwxr-xr-xconf/md5itall51
-rwxr-xr-xconf/mkdirp50
-rw-r--r--conf/pam.conf126
-rw-r--r--conf/pam_conv1/.cvsignore3
-rw-r--r--conf/pam_conv1/Makefile41
-rw-r--r--conf/pam_conv1/README10
-rw-r--r--conf/pam_conv1/pam_conv.lex42
-rw-r--r--conf/pam_conv1/pam_conv.y203
-rw-r--r--defs/debian.defs40
-rw-r--r--defs/hpux.defs36
-rw-r--r--defs/linux.defs32
-rw-r--r--defs/morgan.defs36
-rw-r--r--defs/redhat.defs36
-rw-r--r--defs/redhat4.defs35
-rw-r--r--defs/solaris-2.1.5.defs45
-rw-r--r--defs/solaris.defs48
-rw-r--r--defs/sunos.defs37
-rw-r--r--defs/suse.defs36
-rw-r--r--doc/.cvsignore2
-rw-r--r--doc/CREDITS48
-rw-r--r--doc/Makefile101
-rw-r--r--doc/NOTES16
-rw-r--r--doc/figs/pam_orient.txt23
-rw-r--r--doc/html/.cvsignore1
-rw-r--r--doc/html/index.html21
-rw-r--r--doc/man/pam.8279
-rw-r--r--doc/man/pam.conf.81
-rw-r--r--doc/man/pam.d.81
-rw-r--r--doc/man/pam_authenticate.391
-rw-r--r--doc/man/pam_chauthtok.3101
-rw-r--r--doc/man/pam_close_session.31
-rw-r--r--doc/man/pam_end.31
-rw-r--r--doc/man/pam_fail_delay.3130
-rw-r--r--doc/man/pam_open_session.399
-rw-r--r--doc/man/pam_setcred.379
-rw-r--r--doc/man/pam_start.398
-rw-r--r--doc/man/pam_strerror.351
-rw-r--r--doc/man/template-man52
-rw-r--r--doc/modules/README13
-rw-r--r--doc/modules/module.sgml-template170
-rw-r--r--doc/modules/pam_access.sgml93
-rw-r--r--doc/modules/pam_chroot.sgml86
-rw-r--r--doc/modules/pam_cracklib.sgml259
-rw-r--r--doc/modules/pam_deny.sgml179
-rw-r--r--doc/modules/pam_env.sgml141
-rw-r--r--doc/modules/pam_filter.sgml150
-rw-r--r--doc/modules/pam_ftp.sgml93
-rw-r--r--doc/modules/pam_group.sgml108
-rw-r--r--doc/modules/pam_issue.sgml120
-rw-r--r--doc/modules/pam_krb4.sgml126
-rw-r--r--doc/modules/pam_lastlog.sgml119
-rw-r--r--doc/modules/pam_limits.sgml197
-rw-r--r--doc/modules/pam_listfile.sgml138
-rw-r--r--doc/modules/pam_mail.sgml137
-rw-r--r--doc/modules/pam_mkhomedir.sgml83
-rw-r--r--doc/modules/pam_motd.sgml77
-rw-r--r--doc/modules/pam_nologin.sgml75
-rw-r--r--doc/modules/pam_permit.sgml83
-rw-r--r--doc/modules/pam_pwdb.sgml252
-rw-r--r--doc/modules/pam_radius.sgml117
-rw-r--r--doc/modules/pam_rhosts.sgml164
-rw-r--r--doc/modules/pam_rootok.sgml85
-rw-r--r--doc/modules/pam_securetty.sgml72
-rw-r--r--doc/modules/pam_time.sgml166
-rw-r--r--doc/modules/pam_unix.sgml289
-rw-r--r--doc/modules/pam_userdb.sgml112
-rw-r--r--doc/modules/pam_warn.sgml67
-rw-r--r--doc/modules/pam_wheel.sgml125
-rw-r--r--doc/pam_appl.sgml1643
-rw-r--r--doc/pam_modules.sgml1476
-rw-r--r--doc/pam_source.sgml1173
-rw-r--r--doc/ps/.cvsignore1
-rw-r--r--doc/ps/README3
-rw-r--r--doc/ps/missfont.log36
-rw-r--r--doc/specs/.cvsignore1
-rw-r--r--doc/specs/draft-morgan-pam.raw702
-rw-r--r--doc/specs/formatter/.cvsignore3
-rw-r--r--doc/specs/formatter/Makefile16
-rw-r--r--doc/specs/formatter/parse.lex11
-rw-r--r--doc/specs/formatter/parse.y293
-rw-r--r--doc/specs/rfc86.0.txt1851
-rw-r--r--doc/txts/.cvsignore1
-rw-r--r--doc/txts/README3
-rw-r--r--examples/.cvsignore3
-rw-r--r--examples/Makefile42
-rw-r--r--examples/blank.c182
-rw-r--r--examples/check_user.c71
-rw-r--r--examples/test.c105
-rw-r--r--examples/vpass.c47
-rw-r--r--examples/xsh.c148
-rw-r--r--libpam/.cvsignore2
-rw-r--r--libpam/Makefile162
-rw-r--r--libpam/include/security/_pam_compat.h122
-rw-r--r--libpam/include/security/_pam_macros.h166
-rw-r--r--libpam/include/security/_pam_types.h316
-rw-r--r--libpam/include/security/pam_appl.h92
-rw-r--r--libpam/include/security/pam_malloc.h79
-rw-r--r--libpam/include/security/pam_modules.h195
-rw-r--r--libpam/pam_account.c13
-rw-r--r--libpam/pam_auth.c67
-rw-r--r--libpam/pam_data.c105
-rw-r--r--libpam/pam_delay.c168
-rw-r--r--libpam/pam_dispatch.c282
-rw-r--r--libpam/pam_end.c72
-rw-r--r--libpam/pam_env.c389
-rw-r--r--libpam/pam_handlers.c896
-rw-r--r--libpam/pam_item.c304
-rw-r--r--libpam/pam_log.c382
-rw-r--r--libpam/pam_malloc.c404
-rw-r--r--libpam/pam_map.c85
-rw-r--r--libpam/pam_misc.c305
-rw-r--r--libpam/pam_password.c52
-rw-r--r--libpam/pam_private.h312
-rw-r--r--libpam/pam_second.c46
-rw-r--r--libpam/pam_session.c41
-rw-r--r--libpam/pam_start.c112
-rw-r--r--libpam/pam_static.c141
-rw-r--r--libpam/pam_strerror.c112
-rw-r--r--libpam/pam_tokens.h111
-rw-r--r--libpam_misc/.cvsignore7
-rw-r--r--libpam_misc/Makefile96
-rw-r--r--libpam_misc/help_env.c118
-rw-r--r--libpam_misc/misc_conv.c344
-rw-r--r--libpam_misc/pam_misc.h56
-rw-r--r--libpam_misc/xstrdup.c31
-rw-r--r--libpamc/.cvsignore3
-rw-r--r--libpamc/License42
-rw-r--r--libpamc/Makefile110
-rw-r--r--libpamc/include/security/pam_client.h186
-rw-r--r--libpamc/libpamc.h63
-rw-r--r--libpamc/pamc_client.c189
-rw-r--r--libpamc/pamc_converse.c211
-rw-r--r--libpamc/pamc_load.c477
-rwxr-xr-xlibpamc/test/agents/secret@here305
-rw-r--r--libpamc/test/modules/Makefile9
-rw-r--r--libpamc/test/modules/pam_secret.c670
-rw-r--r--libpamc/test/regress/Makefile7
-rwxr-xr-xlibpamc/test/regress/run_test.sh6
-rw-r--r--libpamc/test/regress/test.libpamc.c334
-rwxr-xr-xlibpamc/test/regress/test.secret@here152
-rw-r--r--modules/Makefile70
-rw-r--r--modules/README55
-rw-r--r--modules/dont_makefile19
-rwxr-xr-xmodules/download-all30
-rw-r--r--modules/pam_access/.cvsignore1
-rw-r--r--modules/pam_access/Makefile106
-rw-r--r--modules/pam_access/README40
-rw-r--r--modules/pam_access/access.conf52
-rwxr-xr-xmodules/pam_access/install_conf46
-rw-r--r--modules/pam_access/pam_access.c424
-rw-r--r--modules/pam_cracklib/.cvsignore1
-rw-r--r--modules/pam_cracklib/Makefile118
-rw-r--r--modules/pam_cracklib/README21
-rw-r--r--modules/pam_cracklib/pam_cracklib.c776
-rw-r--r--modules/pam_deny/.cvsignore1
-rw-r--r--modules/pam_deny/Makefile131
-rw-r--r--modules/pam_deny/README4
-rw-r--r--modules/pam_deny/pam_deny.c100
-rw-r--r--modules/pam_env/.cvsignore1
-rw-r--r--modules/pam_env/Makefile111
-rw-r--r--modules/pam_env/README72
-rwxr-xr-xmodules/pam_env/install_conf46
-rw-r--r--modules/pam_env/pam_env.c839
-rw-r--r--modules/pam_env/pam_env.conf-example72
-rw-r--r--modules/pam_filter/.cvsignore2
-rw-r--r--modules/pam_filter/.upperLOWER1
-rw-r--r--modules/pam_filter/Makefile140
-rw-r--r--modules/pam_filter/README94
-rw-r--r--modules/pam_filter/include/pam_filter.h32
-rw-r--r--modules/pam_filter/pam_filter.c738
-rw-r--r--modules/pam_filter/upperLOWER/.cvsignore1
-rw-r--r--modules/pam_filter/upperLOWER/Makefile64
-rw-r--r--modules/pam_filter/upperLOWER/upperLOWER.c174
-rw-r--r--modules/pam_ftp/.cvsignore1
-rw-r--r--modules/pam_ftp/Makefile88
-rw-r--r--modules/pam_ftp/README18
-rw-r--r--modules/pam_ftp/pam_ftp.c299
-rw-r--r--modules/pam_group/.cvsignore1
-rw-r--r--modules/pam_group/Makefile98
-rw-r--r--modules/pam_group/group.conf60
-rwxr-xr-xmodules/pam_group/install_conf46
-rw-r--r--modules/pam_group/pam_group.c843
-rw-r--r--modules/pam_issue/.cvsignore1
-rw-r--r--modules/pam_issue/Makefile86
-rw-r--r--modules/pam_issue/pam_issue.c265
-rw-r--r--modules/pam_lastlog/.cvsignore1
-rw-r--r--modules/pam_lastlog/Makefile112
-rw-r--r--modules/pam_lastlog/pam_lastlog.c463
-rw-r--r--modules/pam_limits/.cvsignore1
-rw-r--r--modules/pam_limits/Makefile98
-rw-r--r--modules/pam_limits/README87
-rwxr-xr-xmodules/pam_limits/install_conf46
-rw-r--r--modules/pam_limits/limits.skel42
-rw-r--r--modules/pam_limits/pam_limits.c635
-rw-r--r--modules/pam_listfile/.cvsignore1
-rw-r--r--modules/pam_listfile/Makefile84
-rw-r--r--modules/pam_listfile/README25
-rw-r--r--modules/pam_listfile/pam_listfile.c437
-rw-r--r--modules/pam_mail/.cvsignore1
-rw-r--r--modules/pam_mail/Makefile113
-rw-r--r--modules/pam_mail/README17
-rw-r--r--modules/pam_mail/pam_mail.c504
-rw-r--r--modules/pam_mkhomedir/.cvsignore1
-rw-r--r--modules/pam_mkhomedir/Makefile90
-rw-r--r--modules/pam_mkhomedir/pam_mkhomedir.c370
-rw-r--r--modules/pam_motd/.cvsignore1
-rw-r--r--modules/pam_motd/Makefile90
-rw-r--r--modules/pam_motd/pam_motd.c119
-rw-r--r--modules/pam_nologin/.cvsignore1
-rw-r--r--modules/pam_nologin/Makefile86
-rw-r--r--modules/pam_nologin/README12
-rw-r--r--modules/pam_nologin/pam_nologin.c130
-rw-r--r--modules/pam_permit/.cvsignore1
-rw-r--r--modules/pam_permit/Makefile132
-rw-r--r--modules/pam_permit/README4
-rw-r--r--modules/pam_permit/pam_permit.c128
-rw-r--r--modules/pam_pwdb/.cvsignore2
-rw-r--r--modules/pam_pwdb/BUGS14
-rw-r--r--modules/pam_pwdb/CHANGELOG10
-rw-r--r--modules/pam_pwdb/Makefile193
-rw-r--r--modules/pam_pwdb/README41
-rw-r--r--modules/pam_pwdb/TODO34
-rw-r--r--modules/pam_pwdb/bigcrypt.-c114
-rw-r--r--modules/pam_pwdb/md5.c270
-rw-r--r--modules/pam_pwdb/md5.h34
-rw-r--r--modules/pam_pwdb/md5_crypt.c153
-rw-r--r--modules/pam_pwdb/pam_pwdb.c256
-rw-r--r--modules/pam_pwdb/pam_unix_acct.-c298
-rw-r--r--modules/pam_pwdb/pam_unix_auth.-c131
-rw-r--r--modules/pam_pwdb/pam_unix_md.-c73
-rw-r--r--modules/pam_pwdb/pam_unix_passwd.-c404
-rw-r--r--modules/pam_pwdb/pam_unix_pwupd.-c260
-rw-r--r--modules/pam_pwdb/pam_unix_sess.-c118
-rw-r--r--modules/pam_pwdb/pwdb_chkpwd.c204
-rw-r--r--modules/pam_pwdb/support.-c938
-rw-r--r--modules/pam_radius/.cvsignore1
-rw-r--r--modules/pam_radius/Makefile99
-rw-r--r--modules/pam_radius/README58
-rw-r--r--modules/pam_radius/pam_radius.c193
-rw-r--r--modules/pam_radius/pam_radius.h38
-rw-r--r--modules/pam_rhosts/.cvsignore1
-rw-r--r--modules/pam_rhosts/Makefile98
-rw-r--r--modules/pam_rhosts/README57
-rw-r--r--modules/pam_rhosts/pam_rhosts_auth.c829
-rw-r--r--modules/pam_rootok/.cvsignore1
-rw-r--r--modules/pam_rootok/Makefile117
-rw-r--r--modules/pam_rootok/README18
-rw-r--r--modules/pam_rootok/pam_rootok.c109
-rw-r--r--modules/pam_securetty/.cvsignore1
-rw-r--r--modules/pam_securetty/Makefile83
-rw-r--r--modules/pam_securetty/README9
-rw-r--r--modules/pam_securetty/pam_securetty.c191
-rw-r--r--modules/pam_shells/.cvsignore1
-rw-r--r--modules/pam_shells/Makefile84
-rw-r--r--modules/pam_shells/README10
-rw-r--r--modules/pam_shells/pam_shells.c133
-rw-r--r--modules/pam_stress/.cvsignore1
-rw-r--r--modules/pam_stress/Makefile115
-rw-r--r--modules/pam_stress/README66
-rw-r--r--modules/pam_stress/pam_stress.c565
-rw-r--r--modules/pam_tally/.cvsignore2
-rw-r--r--modules/pam_tally/Makefile109
-rw-r--r--modules/pam_tally/README95
-rw-r--r--modules/pam_tally/faillog.h55
-rw-r--r--modules/pam_tally/pam_tally.c689
-rw-r--r--modules/pam_tally/pam_tally_app.c7
-rw-r--r--modules/pam_time/.cvsignore1
-rw-r--r--modules/pam_time/Makefile98
-rw-r--r--modules/pam_time/README43
-rwxr-xr-xmodules/pam_time/install_conf46
-rw-r--r--modules/pam_time/pam_time.c612
-rw-r--r--modules/pam_time/time.conf64
-rw-r--r--modules/pam_unix/.cvsignore4
-rw-r--r--modules/pam_unix/CHANGELOG55
-rw-r--r--modules/pam_unix/Makefile155
-rw-r--r--modules/pam_unix/README39
-rw-r--r--modules/pam_unix/bigcrypt.c119
-rw-r--r--modules/pam_unix/lckpwdf.-c117
-rw-r--r--modules/pam_unix/md5.c256
-rw-r--r--modules/pam_unix/md5.h35
-rw-r--r--modules/pam_unix/md5_crypt.c149
-rwxr-xr-xmodules/pam_unix/need_nsl.sh7
-rw-r--r--modules/pam_unix/pam_unix_acct.c210
-rw-r--r--modules/pam_unix/pam_unix_auth.c220
-rw-r--r--modules/pam_unix/pam_unix_passwd.c985
-rw-r--r--modules/pam_unix/pam_unix_sess.c138
-rw-r--r--modules/pam_unix/support.c821
-rw-r--r--modules/pam_unix/support.h139
-rw-r--r--modules/pam_unix/unix_chkpwd.c324
-rw-r--r--modules/pam_unix/yppasswd.h51
-rw-r--r--modules/pam_unix/yppasswd_xdr.c41
-rw-r--r--modules/pam_userdb/.cvsignore1
-rw-r--r--modules/pam_userdb/Makefile81
-rw-r--r--modules/pam_userdb/README30
-rw-r--r--modules/pam_userdb/conv.c125
-rw-r--r--modules/pam_userdb/create.pl23
-rwxr-xr-xmodules/pam_userdb/libdbfound.sh15
-rw-r--r--modules/pam_userdb/pam_userdb.c302
-rw-r--r--modules/pam_userdb/pam_userdb.h61
-rw-r--r--modules/pam_warn/.cvsignore1
-rw-r--r--modules/pam_warn/Makefile102
-rw-r--r--modules/pam_warn/README26
-rw-r--r--modules/pam_warn/pam_warn.c132
-rw-r--r--modules/pam_wheel/.cvsignore1
-rw-r--r--modules/pam_wheel/Makefile86
-rw-r--r--modules/pam_wheel/README33
-rw-r--r--modules/pam_wheel/pam_wheel.c275
-rwxr-xr-xmodules/register_static49
-rw-r--r--pgp.keys.asc103
320 files changed, 48373 insertions, 0 deletions
diff --git a/.cvsignore b/.cvsignore
new file mode 100644
index 0000000..31265a3
--- /dev/null
+++ b/.cvsignore
@@ -0,0 +1,4 @@
+default.defs
+.freezemake
+.filelist
+include \ No newline at end of file
diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644
index 0000000..59da5b6
--- /dev/null
+++ b/CHANGELOG
@@ -0,0 +1,1244 @@
+
+$Id$
+
+-----------------------------
+
+TODO:
+
+ - autoconf the modules?
+ - sanitize use of md5 throughout distribution.. Make a static
+ library for helping to develop modules that contains it and other
+ stuff. Also add sha-1 and ripemd-160 digest algorithms.
+ - once above is done. remove hacks from the secret@here module etc..
+ - remove prototype for gethostname in pam_access.c (Derrick)
+ - document PAM_INCOMPLETE 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 (auth seems ok..)
+ - add PAM_INCOMPLETE support to modules (partially added to pam_pwdb)
+ - work on RFC.
+ - do we still need to remove openlog/closelog from modules..?
+ - auth and acct support in pam_cracklib, "yes, I know the password
+ you just typed was valid, I just don't think it was very strong..."
+
+0.73: please submit patches for this section with actual code/doc
+ patches!
+
+Planning to include:
+
+ - some autoconf support and other outstanding changes from Jan..
+ - some outstanding changes from Ben
+ - add in the pam_cap and pam_netid modules
+
+0.72: Mon Dec 13 22:41:11 PST 1999
+
+* patches from Debian (Ben Collins): pam_ftp supports event driven
+ conversations now; pwdb_chkpwd cleanup; pam_warn static compile fix;
+ user_db compiler warnings removed; debian defs file; pam_mail can
+ now be used as a session module
+* ndbm compilation option for user_db module (fix explained by Richard Khoo)
+* pam_cracklib bug fix
+* packaging fixes & build from scratch stuff (Konst Bulatnikov & Frodo
+ Looijaard)
+* -ldl appended to the libpam.so compilation make rule. (Charles Seeger)
+* Red Hat security patch for pam_pwdb forwarded by Debian! (Ben
+ Collins. Fix provided by Andrey as it caught the problem earlier in the
+ code.)
+* heuristic to prevent leaking filedescriptors to an agent. [This needs
+ to be better supported perhaps by an additional libpamc API function?]
+* pam_userdb segfault fix from (Ben Collins)
+* PAM draft spec extras added at request of 'sen_ml'
+
+0.71: Sun Nov 7 20:21:19 PST 1999
+
+* added -lc to linker pass for pam_nologin module (glibc is weird).
+* various header changes to lower the number of warnings on glibc
+ systems (Dan Yefimov)
+* merged a bunch of Debian fixes/patches/documentation (Ben Collins)
+ things touched: libpam (minor); doc/modules/pam_unix.sgml; pam_env
+ (plus docs); pam_mkhomedir (new module for new home directories on
+ the fly...); pam_motd (new module); pam_limits (adjust to match
+ docs); pam_issue (new module + doc) [Some of these were also
+ submitted by Thorsten Kukuk]
+* small hack to lower the number of warnings that pam_client.h was
+ generating.
+* debian and SuSE apparently can use the pam_ftp module, so
+ removed the obsolete comment about this from the docs. (Thorsten
+ Kukuk)
+
+0.70: Fri Oct 8 22:05:30 PDT 1999
+
+* bug fix for parsing of value=action tokens in libpam/pam_misc.c was
+ segfaulting (Jan Rekorajski and independently Matthew Melvin)
+* numerous fixes from Thorsten Kukuk (icluding much needed fixes for
+ bitrot in modules and some documentation) that got included in SuSE 6.2.
+* reentrancy issues in pam_unix and pam_cracklib resolved (Jan Rekorajski)
+* added hosts_equiv_rootok module option to pam_rhosts module (Tim Berger)
+* added comment about 'expose_account' module argument to admin and
+ module writers' docs (request from Michael K Johnson).
+* myriad of bug fixes for libpamc - library now built by default and
+ works with the biomouse fingerprint scanner agent/module
+ (distributed separately).
+
+0.69: Sun Aug 1 20:25:37 PDT 1999
+
+* c++ header #ifdef'ing for pam_appl.h (Tuomo Pyhala)
+* added pam_userdb module (Cristian Gafton)
+* minor documentation changes
+* added in revised pam_client library (libpamc). Not installed by
+ default yet, since the example agent/module combo is not very secure.
+* glibc fixes (Thorsten Kukuk, Adam J. Richter)
+
+0.68: Sun Jul 4 23:04:13 PDT 1999
+
+* completely new pam_unix module from Jan Rekorajski and Stephen Langasek
+* Jan Rekorajski pam_mail - support for Maildir format mailboxes
+* Jan Rekorajski pam_cracklib - support for old password comparison
+* Jan Rekorajski bug fix for pam_pwdb setcred reusing auth retval
+* Andrey's pam_tally patch (lstat -> fstat)
+* Robert Milkowski's additional pam_tally patches to **change format of
+ /var/log/faillog** to one from shadow-utils, add new option "per_user"
+ for pam_tally module, failure time logging, support for fail_line
+ field, and support for fail_locktime field with new option
+ no_lock_time.
+* pam_tally: clean up the tally application too.
+* Marcin Korzonek added process priority settings to pam_limits (bonus
+ points for adding to documentation!)
+* Andrey's pam_pwdb patch (cleanup + md5 endian fubar fix)
+* more binary prompt preparations (make misc conv more compatible with spec)
+* modified callback hook for fail delay to be more useful with event
+ driven applications (changed function prototype - suspect no one
+ will notice). Documented this in app developer guide.
+* documentation for pam_access from Tim Berger
+* syntax fixes for the documentation - a long time since I've built it :*(
+ added some more names to the CREDITS file.
+
+0.67: Sat Jun 19 14:01:24 PDT 1999
+
+* [dropped libpam_client - libpamc will be in the next release and
+ conforms to the developing spec in doc/specs/draft-morgan-pam.raw.
+ Sorry if you are keeping a PAM tree in CVS. CVS is a pain for
+ directories, but this directory was actually not referenced by
+ anything so the disruption should be light.]
+* updates to pam_tally from Tim
+* multiple updates from Stephen Langasek to pam_unix
+* pam_filter had some trouble compiling (bug report from Sridhar)
+* pam_wheel now attempts to identify the wheel group for the local
+ system instead of blindly assuming it is gid=0. In the case that
+ there is no "wheel" group, we default to assuming gid=0 is what was
+ meant - former behavior. (courtesy of Sridhar)
+* NIS+ changes to pam_unix module from Dmitry O Panov
+* hopefully, a fix for redefinition of LOG_AUTHPRIV (bug report Luke
+ Kenneth Casson Leighton)
+* fix for minor typo in pam_wheel documentation (Jacek Kopecky)
+* slightly more explanation of the [x=y] pam.conf syntax in the sys
+ admin guide.
+
+0.66: Mon Dec 28 20:22:23 PST 1998 <morgan@linux.kernel.org>
+
+* Started using cvs to keep track of changes to Linux-PAM. This will
+ likely break some of the automated building stuff (RPMs etc..).
+* security bug fix to pam_unix and pam_tally from Andrey.
+* modules make file is now more automatic. It should be possible to
+ unpack an external module in the modules directory and have it automatically
+ added to the build process. Also added a modules/download-all script
+ that will make such downloading easier. I'm happy to receive patches to
+ this file, informing the distribution of places from which to enrich itself.
+* removed pam_system_log stuff. Thought about it long and hard: a
+ bad idea. If libc cannot guarantee a thread safe syslog, it needs
+ to be fixed and compatibility with other PAM libraries was
+ unnecessarily strained.
+* SAG documentation changes: Seth Chaiklin
+* rhosts: problems with NIS lookup failures with the root-uid check.
+ As a work-around, I've partially eliminated the need for the lookup
+ by supplying two new arguments: no_uid_check, superuser=<username>.
+ As a general rule this is more pluggable, since this module might be
+ used as an authentication scheme for a network service that does not
+ need root privilege...
+* authenticate retval -> setcred for pam_pwdb (likeauth arg).
+* pam_pwdb event driven support
+* non openlog pam_listfile logging
+* BUGFIX: close filedescriptor in pam_group and pam_time (Emmanuel Galanos)
+* Chris Adams' mailhash change for pam_mail module
+* fixed malloc failure check in pam_handlers.c (follow up to comment
+ by Brad M. Garcia).
+* update to _pam_compat.h (Brad M. Garcia)
+* support static modules in libpam again (Brad M. Garcia)
+* libpam/pam_misc.c for egcs to grok the code (Brad M. Garcia)
+* added a solaris-2.5.1 defs file (revived by Derrick J Brashear)
+* pam_listfile logs failed attempts
+* added a comment (Michael K Johnson pointed it out) about sgml2latex
+ having a new syntax. I'll make it the change real when I upgrade...
+* a little more text to the RFC, spelling fix from William J Buffam.
+* minor changes to pam_securetty to accommodate event driven support.
+
+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/Copyright b/Copyright
new file mode 100644
index 0000000..2f27a2e
--- /dev/null
+++ b/Copyright
@@ -0,0 +1,41 @@
+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/Makefile b/Makefile
new file mode 100644
index 0000000..7a5923e
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,283 @@
+##
+## $Id$
+##
+##
+
+# major and minor numbers of this release
+MAJOR_REL=0
+MINOR_REL=72
+DEBUG_REL=no
+#DEBUG_REL=yes
+
+# this should be the name of this directory (under CVS)
+DISTNAME = Linux-PAM
+# this should be the name of this directory (when generating the release)
+RELNAME = $(DISTNAME)-$(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=yes
+HAVE_CRACKLIB=yes
+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=755
+
+#
+# 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 libpamc 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 LINKLIBS # libraries to append when making dynamic libs
+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
+export EXTRALS # libraries that some modules need
+export LIBDL # extra library for libpam.so
+#
+# 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 headers
+
+ @for i in $(DIRS) ; do \
+ $(MAKE) -C $$i all ; \
+ if [ $$? -ne 0 ]; then break ; fi ; \
+ done
+
+.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
+
+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
+
+headers:
+ @mkdir -p include/security && cd include/security \
+ && ln -fs ../../libpam/include/security/*.h . \
+ && ln -fs ../../libpam_misc/*.h . \
+ && ln -fs ../../libpamc/include/security/*.h .
+
+cl_headers:
+ @cd include/security ; rm -f *.h
+
+extraclean:
+ make cl_headers
+ @for i in $(DIRS) doc ; do \
+ $(MAKE) -C $$i extraclean ; \
+ done
+
+check:
+ @$(MAKE) -C conf check
+
+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
+ chmod 600 .filelist
+ cd .. ; find $(RELNAME) \! -type d -print | fgrep -v 'conf/.md5sum' > $(RELNAME)/.filelist
+ chmod 400 .filelist
+ $(MAKE) check
+ (cat .filelist ; echo $(RELNAME)/conf/.md5sum) | (cd .. ; tar -cz -f$(DISTFILE) -T-)
diff --git a/README b/README
new file mode 100644
index 0000000..8f98821
--- /dev/null
+++ b/README
@@ -0,0 +1,167 @@
+#
+# $Id$
+#
+
+Hello!
+
+Thanks for downloading Linux-PAM.
+
+--------------------------------------------------------------------
+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/bin/.cvsignore b/bin/.cvsignore
new file mode 100644
index 0000000..2769a41
--- /dev/null
+++ b/bin/.cvsignore
@@ -0,0 +1,3 @@
+blank
+xsh
+check_user
diff --git a/bin/README b/bin/README
new file mode 100644
index 0000000..6ab61b7
--- /dev/null
+++ b/bin/README
@@ -0,0 +1,45 @@
+##
+# $Id$
+##
+# $Log$
+# Revision 1.1 2000/06/20 22:10:44 agmorgan
+# Initial revision
+#
+# Revision 1.1.1.1 1998/07/12 05:17:14 morgan
+# Linux PAM sources pre-0.66
+#
+# Revision 1.6 1997/02/15 19:21:08 morgan
+# fixed email
+#
+# Revision 1.5 1996/08/09 05:29:43 morgan
+# trimmed in line with the removal of applications from the distribution
+#
+#
+##
+
+(now we are getting networked apps, be careful to try and test on a
+securely isolated system!)
+
+N=2 <-- blank xsh
+
+Following a 'make install' (which should be done as root) in the
+parent directory this directory will contain $N binaries. The source
+for these programs is in ../examples. They are various short programs
+to use and otherwise test-drive the Linux-PAM libraries/modules with.
+
+These programs grant no privileges, but they give an idea of how well
+the modules are working.
+
+blank is new as of Linux-PAM-0.21. If you are writing/modifying an
+application it might be a place to start...
+
+xsh is new as of Linux-PAM-0.31, it is identical to blank, but invokes
+/bin/sh if the user is authenticated.
+
+[other apps are to be found in SimplePAMApps and many more on Red
+Hat's server.. http://www.redhat.com/]
+
+Best wishes
+
+Andrew
+(morgan@parc.power.net)
diff --git a/conf/.cvsignore b/conf/.cvsignore
new file mode 100644
index 0000000..9372475
--- /dev/null
+++ b/conf/.cvsignore
@@ -0,0 +1,2 @@
+.ignore_age
+.md5sum
diff --git a/conf/Makefile b/conf/Makefile
new file mode 100644
index 0000000..d829a38
--- /dev/null
+++ b/conf/Makefile
@@ -0,0 +1,34 @@
+#
+# $Id$
+#
+#
+
+dummy:
+ @echo "*** This is not a top level Makefile!"
+
+##########################################################
+
+all:
+ $(MAKE) -C pam_conv1 all
+
+install: $(FAKEROOT)$(CONFIGED)/pam.conf
+ $(MAKE) -C pam_conv1 install
+
+$(FAKEROOT)$(CONFIGED)/pam.conf: ./pam.conf
+ bash -f ./install_conf
+
+remove:
+ rm -f $(FAKEROOT)$(CONFIGED)/pam.conf
+ $(MAKE) -C pam_conv1 remove
+
+check:
+ bash -f ./md5itall
+
+lclean:
+ rm -f core *~ .ignore_age
+
+clean: lclean
+ $(MAKE) -C pam_conv1 clean
+
+extraclean: lclean
+ $(MAKE) -C pam_conv1 extraclean
diff --git a/conf/install b/conf/install
new file mode 100755
index 0000000..2eae367
--- /dev/null
+++ b/conf/install
@@ -0,0 +1,178 @@
+#!/bin/sh
+#
+# [This file was lifted from an X distribution. There was no explicit
+# copyright in the file, but the following text was associated with it.
+# should anyone from the X Consortium wish to alter the following
+# text. Please email <morgan@parc.power.net> Thanks. ]
+#
+# --------------------------
+# The X Consortium maintains and distributes the X Window System and
+# related software and documentation in coordinated releases. A release
+# consists of two distinct parts:
+#
+# 1) Specifications and Sample implementations of X Consortium
+# standards, and
+#
+# 2) software and documentation contributed by the general X Consortium
+# community.
+#
+# The timing and contents of a release are determined by the Consortium
+# staff based on the needs and desires of the Members and the advice of
+# the Advisory Board, tempered by the resource constraints of the
+# Consortium.
+#
+# Members have access to all X Consortium produced software and
+# documentation prior to release to the public. Each Member can receive
+# pre-releases and public releases at no charge. In addition, Members
+# have access to software and documentation while it is under
+# development, and can periodically request snapshots of the development
+# system at no charge.
+#
+# The X Consortium also maintains an electronic mail system for
+# reporting problems with X Consortium produced software and
+# documentation. Members have access to all bug reports, as well as all
+# software patches as they are incrementally developed by the Consortium
+# staff between releases.
+#
+# In general, all materials included in X Consortium releases are
+# copyrighted and contain permission notices granting unrestricted use,
+# sales and redistribution rights provided that the copyrights and the
+# permission notices are left intact. All materials are provided "as
+# is," without express or implied warranty.
+# --------------------------
+#
+# This accepts bsd-style install arguments and makes the appropriate calls
+# to the System V install.
+#
+
+flags=""
+dst=""
+src=""
+dostrip=""
+owner=""
+mode=""
+
+while [ x$1 != x ]; do
+ case $1 in
+ -c) shift
+ continue;;
+
+ -m) flags="$flags $1 $2 "
+ mode="$2"
+ shift
+ shift
+ continue;;
+
+ -o) flags="$flags -u $2 "
+ owner="$2"
+ shift
+ shift
+ continue;;
+
+ -g) flags="$flags $1 $2 "
+ shift
+ shift
+ continue;;
+
+ -s) dostrip="strip"
+ shift
+ continue;;
+
+ *) if [ x$src = x ]
+ then
+ src=$1
+ else
+ dst=$1
+ fi
+ shift
+ continue;;
+ esac
+done
+
+case "$mode" in
+"")
+ ;;
+*)
+ case "$owner" in
+ "")
+ flags="$flags -u root"
+ ;;
+ esac
+ ;;
+esac
+
+if [ x$src = x ]
+then
+ echo "$0: no input file specified"
+ exit 1
+fi
+
+if [ x$dst = x ]
+then
+ echo "$0: no destination specified"
+ exit 1
+fi
+
+
+# set up some variable to be used later
+
+rmcmd=""
+srcdir="."
+
+# if the destination isn't a directory we'll need to copy it first
+
+if [ ! -d $dst ]
+then
+ dstbase=`basename $dst`
+ cp $src /tmp/$dstbase
+ rmcmd="rm -f /tmp/$dstbase"
+ src=$dstbase
+ srcdir=/tmp
+ dst="`echo $dst | sed 's,^\(.*\)/.*$,\1,'`"
+ if [ x$dst = x ]
+ then
+ dst="."
+ fi
+fi
+
+
+# If the src file has a directory, copy it to /tmp to make install happy
+
+srcbase=`basename $src`
+
+if [ "$src" != "$srcbase" -a "$src" != "./$srcbase" ]
+then
+ cp $src /tmp/$srcbase
+ src=$srcbase
+ srcdir=/tmp
+ rmcmd="rm -f /tmp/$srcbase"
+fi
+
+# do the actual install
+
+if [ -f /usr/sbin/install ]
+then
+ installcmd=/usr/sbin/install
+elif [ -f /etc/install ]
+then
+ installcmd=/etc/install
+else
+ installcmd=install
+fi
+
+# This rm is commented out because some people want to be able to
+# install through symbolic links. Uncomment it if it offends you.
+rm -f $dst/$srcbase
+(cd $srcdir ; $installcmd -f $dst $flags $src)
+
+if [ x$dostrip = xstrip ]
+then
+ strip $dst/$srcbase
+fi
+
+# and clean up
+
+$rmcmd
+
+exit
+
diff --git a/conf/install_conf b/conf/install_conf
new file mode 100755
index 0000000..db650a0
--- /dev/null
+++ b/conf/install_conf
@@ -0,0 +1,36 @@
+#!/bin/bash
+
+CONFILE="$FAKEROOT"$CONFIGED/pam.conf
+IGNORE_AGE=./.ignore_age
+CONF=./pam.conf
+
+echo
+
+if [ -f "$IGNORE_AGE" ]; then
+ echo "you don't want to be bothered with the age of your $CONFILE file"
+ yes="n"
+elif [ ! -f "$CONFILE" ] || [ "$CONF" -nt "$CONFILE" ]; then
+ if [ -f "$CONFILE" ]; then
+ echo "\
+An older Linux-PAM configuration file already exists ($CONFILE)"
+ WRITE=overwrite
+ fi
+ echo -n "\
+Do you wish to copy the $CONF file in this distribution
+to $CONFILE ? (y/n) [n] "
+ read yes
+else
+ yes=n
+fi
+
+if [ "$yes" = "y" ]; then
+ echo " copying $CONF to $CONFILE"
+ cp $CONF $CONFILE
+else
+ touch "$IGNORE_AGE"
+ echo " Skipping $CONF installation"
+fi
+
+echo
+
+exit 0
diff --git a/conf/md5itall b/conf/md5itall
new file mode 100755
index 0000000..14cd7c0
--- /dev/null
+++ b/conf/md5itall
@@ -0,0 +1,51 @@
+#!/bin/bash
+#
+# $Id$
+#
+# $Log$
+# Revision 1.1 2000/06/20 22:10:45 agmorgan
+# Initial revision
+#
+# Revision 1.1.1.1 1998/07/12 05:17:14 morgan
+# Linux PAM sources pre-0.66
+#
+#
+# Created by Andrew G. Morgan (morgan@parc.power.net)
+#
+
+MD5SUM=md5sum
+CHKFILE1=./.md5sum
+CHKFILE2=./.md5sum-new
+
+which $MD5SUM > /dev/null
+result=$?
+
+if [ -x "$MD5SUM" ] || [ $result -eq 0 ]; then
+ rm -f $CHKFILE2
+ echo -n "computing md5 checksums."
+ for x in `cat ../.filelist` ; do
+ (cd ../.. ; $MD5SUM $x) >> $CHKFILE2
+ echo -n "."
+ done
+ echo
+ if [ -f "$CHKFILE1" ]; then
+ echo "\
+---> Note, since the last \`make check', the following file(s) have changed:
+==========================================================================="
+ diff $CHKFILE1 $CHKFILE2
+ if [ $? -eq 0 ]; then
+ echo "\
+--------------------------- Nothing has changed ---------------------------"
+ fi
+ echo "\
+==========================================================================="
+ fi
+ rm -f "$CHKFILE1"
+ mv "$CHKFILE2" "$CHKFILE1"
+ chmod 400 "$CHKFILE1"
+else
+ echo "\
+Please install \`$MD5SUM'.
+[It is used to check the integrity of this distribution]
+---> no check done."
+fi
diff --git a/conf/mkdirp b/conf/mkdirp
new file mode 100755
index 0000000..b0e04b0
--- /dev/null
+++ b/conf/mkdirp
@@ -0,0 +1,50 @@
+#!/bin/sh
+#
+# this is a wrapper for difficult mkdir programs...
+#
+
+for d in $*
+do
+ if [ ! -d $d ]; then
+ mkdir -p $d
+ if [ $? -ne 0 ]; then exit $? ; fi
+ fi
+done
+
+exit 0
+
+##########################################################################
+# if your mkdir does not support the -p option delete the above lines and
+# use what follows:
+--------------------
+#!/bin/sh
+
+#VERBOSE=yes
+Cwd=`pwd`
+
+for d in $*
+do
+ if [ "`echo $d|cut -c1`" != "/" ]; then
+ x=`pwd`/$d
+ else
+ x=$d
+ fi
+ x="`echo $x|sed -e 'yX/X X'`"
+ cd /
+ for s in $x
+ do
+ if [ -d $s ]; then
+ if [ -n "$VERBOSE" ]; then echo -n "[$s/]"; fi
+ cd $s
+ else
+ mkdir $s
+ if [ $? -ne 0 ]; then exit $? ; fi
+ if [ -n "$VERBOSE" ]; then echo -n "$s/"; fi
+ cd $s
+ fi
+ done
+ if [ -n "$VERBOSE" ]; then echo ; fi
+ cd $Cwd
+done
+
+exit 0
diff --git a/conf/pam.conf b/conf/pam.conf
new file mode 100644
index 0000000..3f10b10
--- /dev/null
+++ b/conf/pam.conf
@@ -0,0 +1,126 @@
+# ---------------------------------------------------------------------------#
+# /etc/pam.conf #
+# #
+# Last modified by Andrew G. Morgan <morgan@parc.power.net> #
+# ---------------------------------------------------------------------------#
+# $Id$
+# ---------------------------------------------------------------------------#
+# serv. module ctrl module [path] ...[args..] #
+# name type flag #
+# ---------------------------------------------------------------------------#
+#
+# The PAM configuration file for the `chfn' service
+#
+chfn auth required pam_pwdb.so
+chfn account required pam_pwdb.so
+chfn password required pam_cracklib.so retry=3
+chfn password required pam_pwdb.so shadow md5 use_authtok
+#
+# The PAM configuration file for the `chsh' service
+#
+chsh auth required pam_pwdb.so
+chsh account required pam_pwdb.so
+chsh password required pam_cracklib.so retry=3
+chsh password required pam_pwdb.so shadow md5 use_authtok
+#
+# The PAM configuration file for the `ftp' service
+#
+ftp auth requisite pam_listfile.so \
+ item=user sense=deny file=/etc/ftpusers onerr=succeed
+ftp auth requisite pam_shells.so
+ftp auth required pam_pwdb.so
+ftp account required pam_pwdb.so
+#
+# The PAM configuration file for the `imap' service
+#
+imap auth required pam_pwdb.so
+imap account required pam_pwdb.so
+#
+# The PAM configuration file for the `login' service
+#
+login auth requisite pam_securetty.so
+login auth required pam_pwdb.so
+login auth optional pam_group.so
+login account requisite pam_time.so
+login account required pam_pwdb.so
+login password required pam_cracklib.so retry=3
+login password required pam_pwdb.so shadow md5 use_authtok
+login session required pam_pwdb.so
+#
+# The PAM configuration file for the `netatalk' service
+#
+netatalk auth required pam_pwdb.so
+netatalk account required pam_pwdb.so
+#
+# The PAM configuration file for the `other' service
+#
+other auth required pam_deny.so
+other auth required pam_warn.so
+other account required pam_deny.so
+other password required pam_deny.so
+other password required pam_warn.so
+other session required pam_deny.so
+#
+# The PAM configuration file for the `passwd' service
+#
+passwd password requisite pam_cracklib.so retry=3
+passwd password required pam_pwdb.so shadow md5 use_authtok
+#
+# The PAM configuration file for the `rexec' service
+#
+rexec auth requisite pam_securetty.so
+rexec auth requisite pam_nologin.so
+rexec auth sufficient pam_rhosts_auth.so
+rexec auth required pam_pwdb.so
+rexec account required pam_pwdb.so
+rexec session required pam_pwdb.so
+rexec session required pam_limits.so
+#
+# The PAM configuration file for the `rlogin' service
+# this application passes control to `login' if it fails
+#
+rlogin auth requisite pam_securetty.so
+rlogin auth requisite pam_nologin.so
+rlogin auth required pam_rhosts_auth.so
+rlogin account required pam_pwdb.so
+rlogin password required pam_cracklib.so retry=3
+rlogin password required pam_pwdb.so shadow md5 use_authtok
+rlogin session required pam_pwdb.so
+rlogin session required pam_limits.so
+#
+# The PAM configuration file for the `rsh' service
+#
+rsh auth requisite pam_securetty.so
+rsh auth requisite pam_nologin.so
+rsh auth sufficient pam_rhosts_auth.so
+rsh auth required pam_pwdb.so
+rsh account required pam_pwdb.so
+rsh session required pam_pwdb.so
+rsh session required pam_limits.so
+#
+# The PAM configuration file for the `samba' service
+#
+samba auth required pam_pwdb.so
+samba account required pam_pwdb.so
+#
+# The PAM configuration file for the `su' service
+#
+su auth required pam_wheel.so
+su auth sufficient pam_rootok.so
+su auth required pam_pwdb.so
+su account required pam_pwdb.so
+su session required pam_pwdb.so
+#
+# The PAM configuration file for the `vlock' service
+#
+vlock auth required pam_pwdb.so
+#
+# The PAM configuration file for the `xdm' service
+#
+xdm auth required pam_pwdb.so
+xdm account required pam_pwdb.so
+#
+# The PAM configuration file for the `xlock' service
+#
+xlock auth required pam_pwdb.so
+
diff --git a/conf/pam_conv1/.cvsignore b/conf/pam_conv1/.cvsignore
new file mode 100644
index 0000000..200a991
--- /dev/null
+++ b/conf/pam_conv1/.cvsignore
@@ -0,0 +1,3 @@
+lex.yy.c
+pam_conv.tab.c
+pam_conv1
diff --git a/conf/pam_conv1/Makefile b/conf/pam_conv1/Makefile
new file mode 100644
index 0000000..7691dc3
--- /dev/null
+++ b/conf/pam_conv1/Makefile
@@ -0,0 +1,41 @@
+#
+#
+ifeq ($(OS),solaris)
+
+clean:
+ @echo not available in Solaris
+
+all:
+ @echo not available in Solaris
+
+install:
+ @echo not available in Solaris
+
+else
+
+all: pam_conv1
+
+pam_conv1: pam_conv.tab.c lex.yy.c
+ $(CC) -o pam_conv1 pam_conv.tab.c -lfl
+
+pam_conv.tab.c: pam_conv.y lex.yy.c
+ bison pam_conv.y
+
+lex.yy.c: pam_conv.lex
+ flex pam_conv.lex
+
+lclean:
+ rm -f core pam_conv1 lex.yy.c pam_conv.tab.c *.o *~
+ rm -rf ./pam.d pam_conv.output
+
+clean: lclean
+
+install: pam_conv1
+ cp -f ./pam_conv1 ../../bin
+
+endif
+
+remove:
+ rm -f ../../bin/pam_conv1
+
+extraclean: remove clean
diff --git a/conf/pam_conv1/README b/conf/pam_conv1/README
new file mode 100644
index 0000000..8d420ce
--- /dev/null
+++ b/conf/pam_conv1/README
@@ -0,0 +1,10 @@
+$Id$
+
+This directory contains a untility to convert pam.conf files to a pam.d/
+tree. The conversion program takes pam.conf from the standard input and
+creates the pam.d/ directory in the current directory.
+
+The program will fail if ./pam.d/ already exists.
+
+Andrew Morgan, February 1997
+
diff --git a/conf/pam_conv1/pam_conv.lex b/conf/pam_conv1/pam_conv.lex
new file mode 100644
index 0000000..a7df2b0
--- /dev/null
+++ b/conf/pam_conv1/pam_conv.lex
@@ -0,0 +1,42 @@
+
+%{
+/*
+ * $Id$
+ *
+ * Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+ *
+ * This file is covered by the Linux-PAM License (which should be
+ * distributed with this file.)
+ */
+
+ const static char lexid[]=
+ "$Id$\n"
+ "Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>\n";
+
+ extern int current_line;
+%}
+
+%%
+
+"#"[^\n]* ; /* skip comments (sorry) */
+
+"\\\n" {
+ ++current_line;
+}
+
+([^\n\t ]|[\\][^\n])+ {
+ return TOK;
+}
+
+[ \t]+ ; /* Ignore */
+
+<<EOF>> {
+ return EOFILE;
+}
+
+[\n] {
+ ++current_line;
+ return NL;
+}
+
+%%
diff --git a/conf/pam_conv1/pam_conv.y b/conf/pam_conv1/pam_conv.y
new file mode 100644
index 0000000..18bedcc
--- /dev/null
+++ b/conf/pam_conv1/pam_conv.y
@@ -0,0 +1,203 @@
+%{
+
+/*
+ * $Id$
+ *
+ * Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+ *
+ * This file is covered by the Linux-PAM License (which should be
+ * distributed with this file.)
+ */
+
+ const static char bisonid[]=
+ "$Id$\n"
+ "Copyright (c) Andrew G. Morgan 1997-8 <morgan@linux.kernel.org>\n";
+
+#include <string.h>
+#include <stdio.h>
+#include <stdarg.h>
+#include <stdlib.h>
+
+ int current_line=1;
+ extern char *yytext;
+
+/* XXX - later we'll change this to be the specific conf file(s) */
+#define newpamf stderr
+
+#define PAM_D "./pam.d"
+#define PAM_D_MODE 0755
+#define PAM_D_MAGIC_HEADER \
+ "#%PAM-1.0\n" \
+ "#[For version 1.0 syntax, the above header is optional]\n"
+
+#define PAM_D_FILE_FMT PAM_D "/%s"
+
+ const char *old_to_new_ctrl_flag(const char *old);
+ void yyerror(const char *format, ...);
+%}
+
+%union {
+ int def;
+ char *string;
+}
+
+%token NL EOFILE TOK
+
+%type <string> tok path tokenls
+
+%start complete
+
+%%
+
+complete
+:
+| complete NL
+| complete line
+| complete EOFILE {
+ return 0;
+}
+;
+
+line
+: tok tok tok path tokenls NL {
+ char *filename;
+ FILE *conf;
+ int i;
+
+ /* make sure we have lower case */
+ for (i=0; $1[i]; ++i) {
+ $1[i] = tolower($1[i]);
+ }
+
+ /* $1 = service-name */
+ yyerror("Appending to " PAM_D "/%s", $1);
+
+ filename = malloc(strlen($1) + sizeof(PAM_D) + 6);
+ sprintf(filename, PAM_D_FILE_FMT, $1);
+ conf = fopen(filename, "r");
+ if (conf == NULL) {
+ /* new file */
+ conf = fopen(filename, "w");
+ if (conf != NULL) {
+ fprintf(conf, PAM_D_MAGIC_HEADER);
+ fprintf(conf,
+ "#\n"
+ "# The PAM configuration file for the `%s' service\n"
+ "#\n", $1);
+ }
+ } else {
+ fclose(conf);
+ conf = fopen(filename, "a");
+ }
+ if (conf == NULL) {
+ yyerror("trouble opening %s - aborting", filename);
+ exit(1);
+ }
+ free(filename);
+
+ /* $2 = module-type */
+ fprintf(conf, "%-10s", $2);
+ free($2);
+
+ /* $3 = required etc. */
+ {
+ const char *trans;
+
+ trans = old_to_new_ctrl_flag($3);
+ free($3);
+ fprintf(conf, " %-10s", trans);
+ }
+
+ /* $4 = module-path */
+ fprintf(conf, " %s", $4);
+ free($4);
+
+ /* $5 = arguments */
+ if ($5 != NULL) {
+ fprintf(conf, " \\\n\t\t%s", $5);
+ free($5);
+ }
+
+ /* end line */
+ fprintf(conf, "\n");
+
+ fclose(conf);
+}
+| error NL {
+ yyerror("malformed line");
+}
+;
+
+tokenls
+: {
+ $$=NULL;
+}
+| tokenls tok {
+ int len;
+
+ if ($1) {
+ len = strlen($1) + strlen($2) + 2;
+ $$ = malloc(len);
+ sprintf($$,"%s %s",$1,$2);
+ free($1);
+ free($2);
+ } else {
+ $$ = $2;
+ }
+}
+;
+
+path
+: TOK {
+ /* XXX - this could be used to check if file present */
+ $$ = strdup(yytext);
+}
+
+tok
+: TOK {
+ $$ = strdup(yytext);
+}
+
+%%
+
+#include "lex.yy.c"
+
+const char *old_to_new_ctrl_flag(const char *old)
+{
+ static const char *clist[] = {
+ "requisite",
+ "required",
+ "sufficient",
+ "optional",
+ NULL,
+ };
+ int i;
+
+ for (i=0; clist[i]; ++i) {
+ if (strcasecmp(clist[i], old) == 0) {
+ break;
+ }
+ }
+
+ return clist[i];
+}
+
+void yyerror(const char *format, ...)
+{
+ va_list args;
+
+ fprintf(stderr, "line %d: ", current_line);
+ va_start(args, format);
+ vfprintf(stderr, format, args);
+ va_end(args);
+ fprintf(stderr, "\n");
+}
+
+void main()
+{
+ if (mkdir(PAM_D, PAM_D_MODE) != 0) {
+ yyerror(PAM_D " already exists.. aborting");
+ exit(1);
+ }
+ yyparse();
+}
diff --git a/defs/debian.defs b/defs/debian.defs
new file mode 100644
index 0000000..19ba466
--- /dev/null
+++ b/defs/debian.defs
@@ -0,0 +1,40 @@
+##
+# 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/defs/hpux.defs b/defs/hpux.defs
new file mode 100644
index 0000000..d834198
--- /dev/null
+++ b/defs/hpux.defs
@@ -0,0 +1,36 @@
+##
+# HPUX defs contributed by Derrick J Brashear <shadow@dementia.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.
+#
+# This file is the default version. Please look in .../defs/ for your
+# preferred OS/vendor.
+
+OS=hpux9
+ARCH=hpux
+CC=gcc
+INSTALL=install
+MKDIR=mkdir -p
+CFLAGS=-g -DPAM_SHL -DHAVE_UTMP_H
+ULIBS=
+LD=ld
+LD_D=$(LD) -b
+LD_L=$(LD) -b
+USESONAME=no
+NEEDSONAME=no
+LDCONFIG=:
+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
+DYNLOAD="dld"
+DYNTYPE="sl"
+SHLIBMODE=755
diff --git a/defs/linux.defs b/defs/linux.defs
new file mode 100644
index 0000000..0e27432
--- /dev/null
+++ b/defs/linux.defs
@@ -0,0 +1,32 @@
+# 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.
+
+OS=linux
+ARCH=i386 # should be changed for alpha
+CC=gcc
+INSTALL=install
+MKDIR=mkdir -p
+CFLAGS=-O7 -pipe -g
+ULIBS=#-lefence
+LD=ld
+LD_D=gcc -shared -Xlinker -x
+LD_L=$(LD) -x -shared
+USESONAME=yes
+LINKLIBS=-lc
+SOSWITCH=-soname
+NEEDSONAME=no
+LDCONFIG=/sbin/ldconfig
+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/defs/morgan.defs b/defs/morgan.defs
new file mode 100644
index 0000000..2b0cf28
--- /dev/null
+++ b/defs/morgan.defs
@@ -0,0 +1,36 @@
+##
+# defs for Andrew's debugging version (which is a modified Red Hat
+# box)
+##
+# 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=i386
+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.d
+INCLUDED=/usr/include/security
+CONFIGED=/etc
+SCONFIGED=/etc/security
diff --git a/defs/redhat.defs b/defs/redhat.defs
new file mode 100644
index 0000000..a6ed36d
--- /dev/null
+++ b/defs/redhat.defs
@@ -0,0 +1,36 @@
+##
+# 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
+EXTRALS=-lcrypt
diff --git a/defs/redhat4.defs b/defs/redhat4.defs
new file mode 100644
index 0000000..219abeb
--- /dev/null
+++ b/defs/redhat4.defs
@@ -0,0 +1,35 @@
+##
+# 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/defs/solaris-2.1.5.defs b/defs/solaris-2.1.5.defs
new file mode 100644
index 0000000..4624b60
--- /dev/null
+++ b/defs/solaris-2.1.5.defs
@@ -0,0 +1,45 @@
+##
+# 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/defs/solaris.defs b/defs/solaris.defs
new file mode 100644
index 0000000..f9f2652
--- /dev/null
+++ b/defs/solaris.defs
@@ -0,0 +1,48 @@
+##
+# 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=cc
+INSTALL=install
+MKDIR=mkdir -p
+WARNINGS = -D_POSIX_SOURCE
+PIC=-KPIC
+CFLAGS=-g -D__EXTENSIONS__ -Dsolaris
+ULIBS=
+LD=ld
+LD_L=$(LD) -G
+LD_D=$(LD_L)
+RDYNAMIC=
+USESONAME=yes
+SOSWITCH=-h
+NEEDSONAME=no
+LDCONFIG=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/defs/sunos.defs b/defs/sunos.defs
new file mode 100644
index 0000000..158accc
--- /dev/null
+++ b/defs/sunos.defs
@@ -0,0 +1,37 @@
+##
+# SunOS defs contributed by Derrick J Brashear <shadow@dementia.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.
+#
+# This file is the SunOS version. Please look in .../defs/ for your
+# preferred OS/vendor.
+
+OS=sunos
+ARCH=sun
+CC=gcc
+INSTALL=install
+MKDIR=mkdir -p
+CFLAGS=-O2 -pipe -g -D__EXTENSIONS__
+ULIBS=
+LD_D=gcc -shared -Xlinker -x
+LD=ld
+LD_L=$(LD)
+USESONAME=no
+NEEDSONAME=yes
+LDCONFIG=/usr/etc/ldconfig
+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
+WARNINGS= -ansi -Wall -Wwrite-strings \
+ -Wpointer-arith -Wcast-qual -Wcast-align \
+ -Wtraditional -Wstrict-prototypes -Wmissing-prototypes \
+ -Wnested-externs -Winline -Wshadow
diff --git a/defs/suse.defs b/defs/suse.defs
new file mode 100644
index 0000000..1fc6b74
--- /dev/null
+++ b/defs/suse.defs
@@ -0,0 +1,36 @@
+##
+# 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/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 0000000..7ac74f9
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,2 @@
+pam.sgml
+MODULES-SGML
diff --git a/doc/CREDITS b/doc/CREDITS
new file mode 100644
index 0000000..059bb5f
--- /dev/null
+++ b/doc/CREDITS
@@ -0,0 +1,48 @@
+<!--
+ an sgml list of people to credit for their contributions to Linux-PAM
+ $Id$
+ -->
+Chris Adams,
+Peter Allgeyer,
+Tim Baverstock,
+Tim Berger,
+Craig S. Bell,
+Derrick J. Brashear,
+Ben Buxton,
+Seth Chaiklin,
+Oliver Crow,
+Chris Dent,
+Marc Ewing,
+Cristian Gafton,
+Emmanuel Galanos,
+Brad M. Garcia,
+Eric Hester,
+Roger Hu,
+Eric Jacksch,
+Michael K. Johnson,
+David Kinchlea,
+Olaf Kirch,
+Marcin Korzonek,
+Stephen Langasek,
+Nicolai Langfeldt,
+Elliot Lee,
+Luke Kenneth Casson Leighton,
+Al Longyear,
+Ingo Luetkebohle,
+Marek Michalkiewicz,
+Robert Milkowski,
+Aleph One,
+Martin Pool,
+Sean Reifschneider,
+Jan Rekorajski,
+Erik Troan,
+Theodore Ts'o,
+Jeff Uphoff,
+Myles Uyema,
+Savochkin Andrey Vladimirovich,
+Ronald Wahl,
+David Wood,
+John Wilmes,
+Joseph S. D. Yao
+and
+Alex O. Yuriev.
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..965f24b
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,101 @@
+
+### $Id$
+
+TXTER=sgml2txt
+HTMLER=sgml2html
+# older distributions use, sgml2ps
+# newer distributions than the one I use (AGM :^) need the following line:
+#PSER=sgml2latex -o ps
+# until I upgrade this is the default
+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
+
+DOCDIR=/usr/doc/Linux-PAM
+MANDIR=/usr/man
+install: all
+ mkdir -p $(FAKEROOT)$(DOCDIR)/{html,ps,text}
+ for file in txts/*.txt; do \
+ install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/text ; \
+ done
+ for file in ps/*.ps; do \
+ install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/ps ; \
+ done
+ for file in html/*.html; do \
+ install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/html ; \
+ done
+ mkdir -p $(FAKEROOT)$(MANDIR)/man{3,8}
+ for file in man/*.3 ; do \
+ install -o root -g root -m 644 $$file $(FAKEROOT)$(MANDIR)/man3 ; \
+ done
+ for file in man/*.8 ; do \
+ install -o root -g root -m 644 $$file $(FAKEROOT)$(MANDIR)/man8 ; \
+ done
+
+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/doc/NOTES b/doc/NOTES
new file mode 100644
index 0000000..b0f40d4
--- /dev/null
+++ b/doc/NOTES
@@ -0,0 +1,16 @@
+Things to be added:
+
+@ modules:
+@ application:
+
+ use of
+ 'user' = user to become,
+ 'uid' = user requesting service
+ 'euid' = privilege of current process.
+
+@ sysadmin:
+
+ included modules:
+ behavior
+ non-included modules:
+ behavior/pointers.
diff --git a/doc/figs/pam_orient.txt b/doc/figs/pam_orient.txt
new file mode 100644
index 0000000..a8b745a
--- /dev/null
+++ b/doc/figs/pam_orient.txt
@@ -0,0 +1,23 @@
+
+
+
+ +----------------+
+ | application: X |
+ +----------------+ / +----------+ +================+
+ | authentication-[---->--\--] Linux- |--<--| /etc/pam.conf |
+ | + [----<--/--] PAM | |================|
+ |[conversation()][--+ \ | | | X auth .. a.so |
+ +----------------+ | / +-n--n-----+ | X auth .. b.so |
+ | | | __| | | _____/
+ | service user | A | | |____,-----'
+ | | | V A
+ +----------------+ +------|-----|---------+ -----+------+
+ +---u-----u----+ | | |
+ | auth.... |--[ a ]--[ b ]--[ c ]
+ +--------------+
+ | acct.... |--[ b ]--[ d ]
+ +--------------+
+ | password |--[ b ]--[ c ]
+ +--------------+
+ | session |--[ e ]--[ c ]
+ +--------------+ \ No newline at end of file
diff --git a/doc/html/.cvsignore b/doc/html/.cvsignore
new file mode 100644
index 0000000..3b358a3
--- /dev/null
+++ b/doc/html/.cvsignore
@@ -0,0 +1 @@
+pam*.html \ No newline at end of file
diff --git a/doc/html/index.html b/doc/html/index.html
new file mode 100644
index 0000000..1ffd7e3
--- /dev/null
+++ b/doc/html/index.html
@@ -0,0 +1,21 @@
+
+<HTML>
+<HEAD>
+<TITLE>Linux-PAM - Pluggable Authentication Modules for Linux</TITLE>
+</HEAD>
+<BODY>
+
+<p>
+Here is the documentation for Linux-PAM. As you will see it is
+currently not complete. However, in order of decreasing length:
+
+<ul>
+<li> <a href="pam.html">The System Administrators' Guide</a>
+<li> <a href="pam_modules.html">The Module Writers' Manual</a>
+<li> <a href="pam_appl.html">The Application developers' Manual</a>
+</ul>
+
+<hr>
+<p>
+REVISION: <tt>$Id$</tt>
+</BODY>
diff --git a/doc/man/pam.8 b/doc/man/pam.8
new file mode 100644
index 0000000..6828073
--- /dev/null
+++ b/doc/man/pam.8
@@ -0,0 +1,279 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
+.TH PAM 8 "1997 Feb 9" "Linux-PAM 0.56" "Linux-PAM Manual"
+.SH NAME
+
+Linux-PAM \- Pluggable Authentication Modules for Linux
+
+.SH SYNOPSIS
+.B /etc/pam.conf
+.sp 2
+.SH DESCRIPTION
+
+This manual is intended to offer a quick introduction to
+.BR Linux-PAM ". "
+For more information the reader is directed to the
+.BR "Linux-PAM system administrators' guide".
+
+.sp
+.BR Linux-PAM
+Is a system of libraries that handle the authentication tasks of
+applications (services) on the system. The library provides a stable
+general interface (Application Programming Interface - API) that
+privilege granting programs (such as
+.BR login "(1) "
+and
+.BR su "(1)) "
+defer to to perform standard authentication tasks.
+
+.sp
+The principal feature of the PAM approach is that the nature of the
+authentication is dynamically configurable. In other words, the
+system administrator is free to choose how individual
+service-providing applications will authenticate users. This dynamic
+configuration is set by the contents of the single
+.BR Linux-PAM
+configuration file
+.BR /etc/pam.conf "."
+Alternatively, the configuration can be set by individual
+configuration files located in the
+.B /etc/pam.d/
+directory.
+.IB "The presence of this directory will cause " Linux-PAM " to ignore"
+.BI /etc/pam.conf "."
+
+.sp
+From the point of view of the system administrator, for whom this
+manual is provided, it is not of primary importance to understand the
+internal behavior of the
+.BR Linux-PAM
+library. The important point to recognize is that the configuration
+file(s)
+.I define
+the connection between applications
+.BR "" "(" services ")"
+and the pluggable authentication modules
+.BR "" "(" PAM "s)"
+that perform the actual authentication tasks.
+
+.sp
+.BR Linux-PAM
+separates the tasks of
+.I authentication
+into four independent management groups:
+.BR "account" " management; "
+.BR "auth" "entication management; "
+.BR "password" " management; "
+and
+.BR "session" " management."
+(We highlight the abbreviations used for these groups in the
+configuration file.)
+
+.sp
+Simply put, these groups take care of different aspects of a typical
+user's request for a restricted service:
+
+.sp
+.BR account " - "
+provide account verification types of service: has the user's password
+expired?; is this user permitted access to the requested service?
+
+.br
+.BR auth "entication - "
+establish the user is who they claim to be. Typically this is via some
+challenge-response request that the user must satisfy: if you are who
+you claim to be please enter your password. Not all authentications
+are of this type, there exist hardware based authentication schemes
+(such as the use of smart-cards and biometric devices), with suitable
+modules, these may be substituted seamlessly for more standard
+approaches to authentication - such is the flexibility of
+.BR Linux-PAM "."
+
+.br
+.BR password " - "
+this group's responsibility is the task of updating authentication
+mechanisms. Typically, such services are strongly coupled to those of
+the
+.BR auth
+group. Some authentication mechanisms lend themselves well to being
+updated with such a function. Standard UN*X password-based access is
+the obvious example: please enter a replacement password.
+
+.br
+.BR session " - "
+this group of tasks cover things that should be done prior to a
+service being given and after it is withdrawn. Such tasks include the
+maintenance of audit trails and the mounting of the user's home
+directory. The
+.BR session
+management group is important as it provides both an opening and
+closing hook for modules to affect the services available to a user.
+
+.SH The configuration file(s)
+
+When a
+.BR Linux-PAM
+aware privilege granting application is started, it activates its
+attachment to the PAM-API. This activation performs a number of
+tasks, the most important being the reading of the configuration file(s):
+.BR /etc/pam.conf "."
+Alternatively, this may be the contents of the
+.BR /etc/pam.d/
+directory.
+
+These files list the
+.BR PAM "s"
+that will do the authentication tasks required by this service, and
+the appropriate behavior of the PAM-API in the event that individual
+.BR PAM "s "
+fail.
+
+.sp
+The syntax of the
+.B /etc/pam.conf
+configuration file is as follows. The file is made
+up of a list of rules, each rule is typically placed on a single line,
+but may be extended with an escaped end of line: `\\<LF>'. Comments
+are preceded with `#' marks and extend to the next end of line.
+
+.sp
+The format of each rule is a space separated collection of tokens, the
+first three being case-insensitive:
+
+.sp
+.br
+.BR " service type control module-path module-arguments"
+
+.sp
+The syntax of files contained in the
+.B /etc/pam.d/
+directory, are identical except for the absence of any
+.I service
+field. In this case, the
+.I service
+is the name of the file in the
+.B /etc/pam.d/
+directory. This filename must be in lower case.
+
+.sp
+An important feature of
+.BR Linux-PAM ", "
+is that a number of rules may be
+.I stacked
+to combine the services of a number of PAMs for a given authentication
+task.
+
+.sp
+The
+.BR service
+is typically the familiar name of the corresponding application:
+.BR login
+and
+.BR su
+are good examples. The
+.BR service "-name, " other ", "
+is reserved for giving
+.I default
+rules. Only lines that mention the current service (or in the absence
+of such, the
+.BR other
+entries) will be associated with the given service-application.
+
+.sp
+The
+.BR type
+is the management group that the rule corresponds to. It is used to
+specify which of the management groups the subsequent module is to
+be associated with. Valid entries are:
+.BR account "; "
+.BR auth "; "
+.BR password "; "
+and
+.BR session "."
+The meaning of each of these tokens was explained above.
+
+.sp
+The third field,
+.BR control ", "
+indicates the behavior of the PAM-API should the module fail to
+succeed in its authentication task. 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 Linux-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/security/*.so " - the PAMs
+
+.sp
+Note, to conform to the Linux File-system standard, the libraries and
+modules in your system may be located in
+.BR /lib " and " /lib/security
+respectively.
+
+.SH ERRORS
+Typically errors generated by the
+.BR Linux-PAM
+system of libraries, will be written to
+.BR syslog "(3)."
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+.br
+Contains additional features, 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/doc/man/pam.conf.8 b/doc/man/pam.conf.8
new file mode 100644
index 0000000..ea2dd98
--- /dev/null
+++ b/doc/man/pam.conf.8
@@ -0,0 +1 @@
+.so man8/pam.8
diff --git a/doc/man/pam.d.8 b/doc/man/pam.d.8
new file mode 100644
index 0000000..ea2dd98
--- /dev/null
+++ b/doc/man/pam.d.8
@@ -0,0 +1 @@
+.so man8/pam.8
diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3
new file mode 100644
index 0000000..ba1bc52
--- /dev/null
+++ b/doc/man/pam_authenticate.3
@@ -0,0 +1,91 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
+.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual"
+.SH NAME
+
+pam_authenticate \- authenticate a user
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.sp
+.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");"
+.sp 2
+.SH DESCRIPTION
+.B pam_authenticate
+
+.br
+Use this function to authenticate an applicant user. It is linked
+.I dynamically
+to the authentication modules by
+.BR Linux-PAM ". "
+It is the task of these module to perform such an authentication. The
+specific nature of the authentication is not the concern of the
+application.
+
+.br
+Following successful completion, the
+.BR name
+of the authenticated user will be present in the
+.BR Linux-PAM
+item
+.BR PAM_USER ". "
+This item may be recovered with a call to
+.BR pam_get_item "(3)."
+
+.br
+The application developer should note that the modules may request
+that the user enter their username via the conversation mechanism (see
+.BR pam_start "(3))."
+Should this be the case, the user-prompt string can be set via
+the
+.BR PAM_USER_PROMPT
+item (see
+.BR pam_set_item "(3))."
+
+.SH "RETURN VALUE"
+On success
+.BR PAM_SUCCESS
+is returned. All other returns should be considered
+authentication failures and will be
+.I delayed
+by an amount specified with prior calls to
+.BR pam_fail_delay "(3). "
+Specific failures that demand special attention are the following:
+.TP
+.B PAM_ABORT
+the application should exit immediately. Of course,
+.BR pam_end "(3)"
+should be called first.
+
+.TP
+.B PAM_MAXTRIES
+the application has tried too many times to authenticate the
+user, authentication should not be attempted again.
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_start "(3), "
+.BR pam_get_item "(3) "
+.BR pam_fail_delay "(3) "
+and
+.BR pam_strerror "(3). "
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3
new file mode 100644
index 0000000..63904da
--- /dev/null
+++ b/doc/man/pam_chauthtok.3
@@ -0,0 +1,101 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
+.SH NAME
+
+pam_chauthtok \- updating authentication tokens
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.sp
+.BI "int pam_chauthtok(pam_handle_t " *pamh ", int " flags ");"
+.sp 2
+.SH DESCRIPTION
+.B pam_chauthtok
+
+.br
+Use this function to rejuvenate the authentication tokens (passwords
+etc.) of an applicant user.
+
+.br
+Note, the application should not pre-authenticate the user, as this is
+performed (if required) by the
+.BR Linux-PAM
+framework.
+
+.br
+The
+.I flags
+argument can
+.I optionally
+take the value,
+.BR PAM_CHANGE_EXPIRED_AUTHTOK "."
+In such cases the framework is only required to update those
+authentication tokens that have expired. Without this argument, the
+framework will attempt to obtain new tokens for all configured
+authentication mechanisms. The details of the types and number of such
+schemes should not concern the calling application.
+
+.SH RETURN VALUE
+A successful return from this function will be indicated with
+.BR PAM_SUCCESS "."
+
+.br
+Specific errors of special interest when calling this function are
+
+.br
+.BR PAM_AUTHTOK_ERROR
+- a valid new token was not obtained
+
+.br
+.BR PAM_AUTHTOK_RECOVERY_ERR
+- old authentication token was not available
+
+.br
+.BR PAM_AUTHTOK_LOCK_BUSY
+- a resource needed to update the token was locked (try again later)
+
+.br
+.BR PAM_AUTHTOK_DISABLE_AGING
+- one or more of the authentication modules does not honor
+authentication token aging
+
+.br
+.BR PAM_TRY_AGAIN
+- one or more authentication mechanism is not prepared to update a
+token at this time
+
+.br
+In general other return values may be returned. They should be treated
+as indicating failure.
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_start "(3), "
+.BR pam_authenticate "(3), "
+.BR pam_setcred "(3), "
+.BR pam_get_item "(3), "
+.BR pam_strerror "(3) "
+and
+.BR pam "(8)."
+
+.br
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3
new file mode 100644
index 0000000..c809a0e
--- /dev/null
+++ b/doc/man/pam_close_session.3
@@ -0,0 +1 @@
+.so man3/pam_open_session.3
diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3
new file mode 100644
index 0000000..06fdabb
--- /dev/null
+++ b/doc/man/pam_end.3
@@ -0,0 +1 @@
+.so man3/pam_start.3
diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3
new file mode 100644
index 0000000..f6cd238
--- /dev/null
+++ b/doc/man/pam_fail_delay.3
@@ -0,0 +1,130 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual"
+.SH NAME
+
+pam_fail_delay \- request a delay on failure
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.br
+or,
+.br
+.B #include <security/pam_modules.h>
+.sp
+.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");"
+.sp 2
+.SH DESCRIPTION
+.br
+It is often possible to attack an authentication scheme by exploiting
+the time it takes the scheme to deny access to an applicant user. In
+cases of
+.I short
+timeouts, it may prove possible to attempt a
+.I brute force
+dictionary attack -- with an automated process, the attacker tries all
+possible passwords to gain access to the system. In other cases,
+where individual failures can take measurable amounts of time
+(indicating the nature of the failure), an attacker can obtain useful
+information about the authentication process. These latter attacks
+make use of procedural delays that constitute a
+.I covert channel
+of useful information.
+
+.br
+To minimize the effectiveness of such attacks, it is desirable to
+introduce a random delay in a failed authentication process.
+.B Linux-PAM
+provides such a facility. The delay occurs upon failure of the
+.BR pam_authenticate "(3) "
+and
+.BR pam_chauthtok "(3) "
+functions. It occurs
+.I after
+all authentication modules have been called, but
+.I before
+control is returned to the service application.
+
+.br
+The function,
+.BR pam_fail_delay "(3),"
+is used to specify a required minimum for the length of the
+failure-delay; the
+.I usec
+argument. This function can be called by the service application
+and/or the authentication modules, both may have an interest in
+delaying a reapplication for service by the user. The length of the
+delay is computed at the time it is required. Its length is
+pseudo-gausianly distributed about the
+.I maximum
+requested value; the resultant delay will differ by as much as 25% of
+this maximum requested value (both up and down).
+
+.br
+On return from
+.BR pam_authenticate "(3) or " pam_chauthtok "(3),"
+independent of success or failure, the new requested delay is reset to
+its default value: zero.
+
+.SH EXAMPLE
+.br
+For example, a
+.B login
+application may require a failure delay of roughly 3 seconds. It will
+contain the following code:
+.sp
+.br
+.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );"
+.br
+.B " pam_authenticate(pamh, 0);"
+.sp
+.br
+if the modules do not request a delay, the failure delay will be
+between 2.25 and 3.75 seconds.
+
+.br
+However, the modules, invoked in the authentication process, may
+also request delays:
+.sp
+.br
+.RB " (module #1) " "pam_fail_delay(pamh, 2000000);"
+.sp
+.br
+.RB " (module #2) " "pam_fail_delay(pamh, 4000000);"
+.sp
+.br
+in this case, it is the largest requested value that is used to
+compute the actual failed delay: here between 3 and 5 seconds.
+
+.SH "RETURN VALUE"
+Following a successful call to
+.BR pam_fail_delay "(3), " PAM_SUCCESS
+is returned. All other returns should be considered serious failures.
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+Under consideration by the X/Open group for future inclusion in the
+PAM RFC. 1996/1/10
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_start "(3), "
+.BR pam_get_item "(3) "
+and
+.BR pam_strerror "(3). "
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_open_session.3 b/doc/man/pam_open_session.3
new file mode 100644
index 0000000..4e63b5c
--- /dev/null
+++ b/doc/man/pam_open_session.3
@@ -0,0 +1,99 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
+.SH NAME
+
+pam_open/close_session \- PAM session management
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.sp
+.BI "int pam_open_session(pam_handle_t " *pamh ", int " flags ");"
+.sp
+.BI "int pam_close_session(pam_handle_t " *pamh ", int " flags ");"
+.sp 2
+.SH DESCRIPTION
+
+PAM provides management-hooks for the initialization and termination
+of a session.
+
+.TP
+.B pam_open_session
+.br
+Use this function to signal that an authenticated user session has
+begun. It should be called only after the user is properly identified
+and (where necessary) has been granted their credentials with
+.BR pam_authenticate "(3)"
+and
+.BR pam_setcred "(3)"
+respectively.
+
+.br
+Some types of functions associated with session
+initialization are logging for the purposes of system-audit and
+mounting directories (the user's home directory for example). These
+should not concern the application. It should be noted that the
+.I effective
+uid,
+.BR geteuid "(2),"
+of the application should be of sufficient privilege to perform such
+tasks.
+
+.TP
+.B pam_close_session
+.br
+Use this function to signal that a user session has
+terminated. In general this function may not need to be located in the
+same application as the initialization function,
+.BR pam_open_session "."
+
+.br
+Typically, this function will undo the actions of
+.BR pam_open_session "."
+That is, log audit information concerning the end of the user session
+or unmount the user's home directory. Apart from having sufficient
+privilege the details of the session termination should not concern
+the calling application. It is good programming practice, however, to
+cease acting on behalf of the user on returning from this call.
+
+.SH RETURN VALUE
+A successful return from the session management functions will be
+indicated with
+.BR PAM_SUCCESS "."
+
+.br
+The specific error indicating a failure to open or close a session is
+.BR PAM_SESSION_ERR "."
+In general other return values may be returned. They should be treated
+as indicating failure.
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+OSF-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_start "(3), "
+.BR pam_authenticate "(3), "
+.BR pam_setcred "(3), "
+.BR pam_get_item "(3), "
+.BR pam_strerror "(3) "
+and
+.BR pam "(3)."
+
+.br
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3
new file mode 100644
index 0000000..8c00fe7
--- /dev/null
+++ b/doc/man/pam_setcred.3
@@ -0,0 +1,79 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
+.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual"
+.SH NAME
+
+pam_setcred \- set the credentials for the user
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.sp
+.BI "int pam_setcred(pam_handle_t " *pamh ", int " flags ");"
+.sp 2
+.SH DESCRIPTION
+.B pam_setcred
+
+This function is used to establish, maintain and delete the
+credentials of a user. It should be called after a user has been
+authenticated and before a session is opened for the user (with
+.BR pam_open_session "(3))."
+
+It should be noted that credentials come in many forms. Examples
+include: group memberships; ticket-files; and Linux-PAM environment
+variables. For this reason, it is important that the basic identity
+of the user is established, by the application, prior to a call to
+this function. For example, the default
+.BR Linux-PAM
+environment variables should be set and also
+.BR initgroups "(2) "
+(or equivalent) should have been performed.
+
+.SH "VALID FLAGS"
+.TP
+.BR PAM_ESTABLISH_CRED
+initialize the credentials for the user.
+
+.TP
+.BR PAM_DELETE_CRED
+delete the user's credentials.
+
+.TP
+.BR PAM_REINITIALIZE_CRED
+delete and then initialize the user's credentials.
+
+.TP
+.BR PAM_REFRESH_CRED
+extend the lifetime of the existing credentials.
+
+.SH "RETURN VALUE"
+
+On success
+.BR PAM_SUCCESS
+is returned, all other return values should be treated as errors.
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_authenticate "(3), "
+.BR pam_strerror "(3)"
+and
+.BR pam_open_session "(3). "
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3
new file mode 100644
index 0000000..9c11fd7
--- /dev/null
+++ b/doc/man/pam_start.3
@@ -0,0 +1,98 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
+.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
+.SH NAME
+
+pam_start, pam_end \- activating Linux-PAM
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.sp
+.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
+.sp
+.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
+.sp 2
+.SH DESCRIPTION
+.TP
+.B pam_start
+Initialize the
+.I Linux-PAM
+library. Identifying the application with a particular
+.IR service
+name. The
+.IR user "name"
+can take the value
+.IR NULL ", "
+if not known at the time the interface is initialized. The
+conversation structure is passed to the library via the
+.IR conv
+argument. (For a complete description of this and other structures
+the reader is directed to the more verbose
+.IR Linux-PAM
+application developers' guide). Upon successful initialization, an
+opaque pointer-handle for future access to the library is returned
+through the contents of the
+.IR pamh_p
+pointer.
+
+.TP
+.B pam_end
+Terminate the
+.B Linux-PAM
+library. The service application associated with the
+.IR pamh
+handle, is terminated. The argument,
+.IR pam_status ", "
+passes the value most recently returned to the application from the
+library; it indicates the manner in which the library should be
+shutdown. Besides carrying a return value, this argument may be
+logically OR'd with
+.IR PAM_DATA_SILENT
+to indicate that the module should not treat the call too
+seriously. It is generally used to indicate that the current closing
+of the library is in a
+.IR fork "(2)ed"
+process, and that the parent will take care of cleaning up things that
+exist outside of the current process space (files etc.).
+
+.SH "RETURN VALUE"
+.TP
+.B pam_start
+.TP
+.B pam_end
+On success,
+.BR PAM_SUCCESS
+is returned
+
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(3). "
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+.sp
+Note, the
+.BR PAM_DATA_SILENT
+flag is pending acceptance with the DCE (as of 1996/12/4).
+
+.SH BUGS
+.sp 2
+None known.
+
+.SH "SEE ALSO"
+
+.BR fork "(2), "
+.BR pam_authenticate "(3), "
+.BR pam_acct_mgmt "(3), "
+.BR pam_open_session "(3), "
+and
+.BR pam_chauthtok "(3)."
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3
new file mode 100644
index 0000000..01ee063
--- /dev/null
+++ b/doc/man/pam_strerror.3
@@ -0,0 +1,51 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" ripped off from Rick Faith's getgroups man page
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
+.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual"
+.SH NAME
+
+pam_strerror \- return a textual description of a Linux-PAM error
+
+.SH SYNOPSIS
+.B #include <security/pam_appl.h>
+.br
+or,
+.br
+.B #include <security/pam_modules.h>
+.sp
+.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");"
+.sp 2
+.SH DESCRIPTION
+.B pam_strerror
+
+This function returns some text describing the
+.BR Linux-PAM
+error associated with the
+.B pam_error
+argument.
+
+.SH "RETURN VALUE"
+
+On success this function returns a description of the indicated
+error. Should the function not recognize the error, ``Unknown
+Linux-PAM error'' is returned.
+
+.SH "CONFORMING TO"
+DCE-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+This function should be internationalized.
+
+.SH "SEE ALSO"
+
+.BR pam "(8). "
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/man/template-man b/doc/man/template-man
new file mode 100644
index 0000000..b8159eb
--- /dev/null
+++ b/doc/man/template-man
@@ -0,0 +1,52 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
+.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual"
+.SH NAME
+
+function names \- brief summary of function
+
+.SH SYNOPSIS
+.B #include <security/pam_????.h>
+.sp
+.BI "int pam_???(pam_handle_t " pamh ", int " flags);
+.sp 2
+.SH DESCRIPTION
+.TP
+.B pam_???
+Here goes the
+.I explanation
+it may be quite
+.IR long .
+.TP
+.SH "RETURN VALUE"
+.B pam_???
+On success...
+.BR PAM_SUCCESS
+is returned
+.TP
+.SH ERRORS
+May be translated to text with
+.BR pam_strerror "(2). "
+
+.SH "CONFORMING TO"
+.B pam_???
+DCE-RFC 86.0, October 1995.
+
+.SH BUGS
+.sp 2
+none known.
+
+.SH "SEE ALSO"
+
+.BR pam_??? "(2), "
+and
+.BR pam_??? "(2). "
+
+Also, see the three
+.BR Linux-PAM
+Guides, for
+.BR "System administrators" ", "
+.BR "module developers" ", "
+and
+.BR "application developers" ". "
diff --git a/doc/modules/README b/doc/modules/README
new file mode 100644
index 0000000..df09193
--- /dev/null
+++ b/doc/modules/README
@@ -0,0 +1,13 @@
+$Id$
+
+This directory contains a number of sgml sub-files. One for each
+documented module. They contain a description of each module and give
+some indication of its reliability.
+
+Additionally, there is a 'module.sgml-template' file which should be
+used as a blank form for new module descriptions.
+
+Please feel free to submit amendments/comments etc. regarding these
+files to:
+
+ Andrew G. Morgan <morgan@parc.power.net>
diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template
new file mode 100644
index 0000000..d0b0e3c
--- /dev/null
+++ b/doc/modules/module.sgml-template
@@ -0,0 +1,170 @@
+<!--
+
+ $Id$
+
+ This template file was written by Andrew G. Morgan
+ <morgan@parc.power.net>
+
+[
+ Text that should be deleted/replaced, is enclosed within
+ '[' .. ']'
+ marks. For example, this text should be deleted!
+]
+
+-->
+
+<sect1> [*Familiar full name of module*, eg. The "allow all" module.]
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+[
+ insert the name of the module
+
+ Blank is not permitted.
+]
+
+<tag><bf>Author[s]:</bf></tag>
+
+[
+ Insert author names here
+
+ Blank is not permitted. If in doubt, put "unknown" if the
+ author wishes to remain anonymous, put "anonymous".
+]
+
+<tag><bf>Maintainer:</bf></tag>
+
+[
+ Insert names and date-begun of most recent maintainer.
+]
+
+<tag><bf>Management groups provided:</bf></tag>
+
+[
+ list the subset of four management groups supported by the
+ module. Choose from: account; authentication; password;
+ session.
+
+ Blank entries are not permitted. Explicitly list all of the
+ management groups. In the future more may be added to libpam!
+]
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+[
+ Indicate whether this module contains code that can perform
+ reversible (strong) encryption. This field is primarily to
+ ensure that people redistributing it are not unwittingly
+ breaking laws...
+
+ Modules may also require the presence of some local library
+ that performs the necessary encryption via some standard API.
+ In this case "uses API" can be included in this field. The
+ library in question should be added to the system requirements
+ below.
+
+ Blank = no cryptography is used by module.
+]
+
+<tag><bf>Security rating:</bf></tag>
+
+[
+ Initially, this field should be left blank. If someone takes
+ it upon themselves to test the strength of the module, it can
+ later be filled.
+
+ Blank = unknown.
+]
+
+<tag><bf>Clean code base:</bf></tag>
+
+[
+ This will probably be filled by the libpam maintainer.
+ It can be considered to be a public humiliation list. :*)
+
+ I am of the opinion that "gcc -with_all_those_flags" is
+ trying to tell us something about whether the program
+ works as intended. Since there is currently no Security
+ evaluation procedure for modules IMHO this is not a
+ completely unreasonable indication (a lower bound anyway)
+ of the reliability of a module.
+
+ This field would indicate the number and flavor of
+ warnings that gcc barfs up when trying to compile the
+ module as part of the tree. Is this too tyrannical?
+
+ Blank = Linux-PAM maintainer has not tested it :)
+]
+
+<tag><bf>System dependencies:</bf></tag>
+
+[
+ here we list config files, dynamic libraries needed, system
+ resources, kernel options.. etc.
+
+ Blank = nothing more than libc required.
+]
+
+<tag><bf>Network aware:</bf></tag>
+
+[
+ Does the module base its behavior on probing a network
+ connection? Does it expect to be protected by the
+ application?
+
+ Blank = Ignorance of network.
+]
+
+</descrip>
+
+<sect2>Overview of module
+
+[
+ some text describing the intended actions of the module
+ general comments mainly (specifics in sections
+ below).
+]
+
+[
+
+ [ now we have a <sect2> level subsection for each of the
+ management groups. Include as many as there are groups
+ listed above in the synopsis ]
+
+<sect2>[ Account | Authentication | Password | Session ] component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+[
+ List the supported arguments (leave their description for the
+ description below.
+
+ Blank = no arguments are read and nothing is logged to syslog
+ about any arguments that are passed. Note, this
+ behavior is contrary to the RFC!
+]
+
+<tag><bf>Description:</bf></tag>
+
+[
+ This component of the module performs the task of ...
+]
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+[
+ Here we list some doos and don'ts for this module.
+]
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_access.sgml b/doc/modules/pam_access.sgml
new file mode 100644
index 0000000..e192d12
--- /dev/null
+++ b/doc/modules/pam_access.sgml
@@ -0,0 +1,93 @@
+<!--
+
+ 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 <tt>/etc/security/access.conf</tt>
+<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>
+
+<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.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Use of module is recommended, for example, on administrative machines
+such as <bf/NIS/ servers and mail servers where you need several accounts
+active but don't want them all to have login capability.
+
+For <tt>/etc/pam.d</tt> style configurations where your modules live
+in <tt>/lib/security</tt>, start by adding the following line to
+<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>,
+<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>:
+
+<tscreen>
+<verb>
+account required /lib/security/pam_access.so
+</verb>
+</tscreen>
+
+Note that use of this module is not effective unless your system ignores
+<tt>.rhosts</tt> files. See the the pam_rhosts_auth documentation.
+
+A sample <tt>access.conf</tt> configuration file is included with the
+distribution.
+
+</descrip>
+
diff --git a/doc/modules/pam_chroot.sgml b/doc/modules/pam_chroot.sgml
new file mode 100644
index 0000000..ec739c1
--- /dev/null
+++ b/doc/modules/pam_chroot.sgml
@@ -0,0 +1,86 @@
+<!--
+ $Id$
+
+ This file was written by Bruce Campbell <brucec@humbug.org.au>
+-->
+
+<sect1>Chroot
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_chroot/
+
+<tag><bf>Author:</bf></tag>
+Bruce Campbell &lt;brucec@humbug.org.au&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author; proposed on 20/11/96 - email for status
+
+<tag><bf>Management groups provided:</bf></tag>
+account; session; authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+Unwritten.
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+Expects localhost.
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is intended to provide a transparent wrapper around the
+average user, one that puts them in a fake file-system (eg, their
+'<tt>/</tt>' is really <tt>/some/where/else</tt>).
+
+<p>
+Useful if you have several classes of users, and are slightly paranoid
+about security. Can be used to limit who else users can see on the
+system, and to limit the selection of programs they can run.
+
+<sect2>Account component:
+
+<p>
+<em/Need more info here./
+
+<sect2>Authentication component:
+
+<p>
+<em/Need more info here./
+
+<sect2>Session component:
+
+<p>
+<em/Need more info here./
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+Arguments and logging levels for the PAM version are being worked on.
+
+<tag><bf>Description:</bf></tag>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm',
+'cp' and 'ed' in there is a bit...
+<p>
+Don't take it to extremes (eg, you can set up a separate environment for
+each user, but its a big waste of your disk space.)
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml
new file mode 100644
index 0000000..f5b2359
--- /dev/null
+++ b/doc/modules/pam_cracklib.sgml
@@ -0,0 +1,259 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com>
+-->
+
+<sect1>Cracklib pluggable password strength-checker
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+
+pam_cracklib
+
+<tag><bf>Author:</bf></tag>
+
+Cristian Gafton &lt;gafton@redhat.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+
+password
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+Requires the system library <tt/libcrack/ and a system dictionary:
+<tt>/usr/lib/cracklib_dict</tt>.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module can be plugged into the <tt/password/ stack of a given
+application to provide some plug-in strength-checking for passwords.
+(XXX - note this does not necessarily work with the pam_unix module,
+although it is known to work with the pam_pwdb replacement for the
+unix module -- see example and pam_pwdb write up for more
+information).
+
+<p>
+This module works in the following manner: it first calls the
+<em>Cracklib</em> routine to check the strength of the password; if
+crack likes the password, the module does an additional set of
+strength checks. These checks are:
+<itemize>
+
+<item> <bf/Palindrome/ -
+
+Is the new password a palindrome of the old one?
+
+<item> <bf/Case Change Only/ -
+
+Is the new password the the old one with only a change of case?
+
+<item> <bf/Similar/ -
+
+Is the new password too much like the old one? This is controlled
+by one argument, <tt/difok/ which is a number of characters that if
+different between the old and new are enough to accept the new
+password, this defaults to 10 or 1/2 the size of the new password
+whichever is smaller.
+
+<item> <bf/Simple/ -
+
+Is the new password too small? This is controlled by 5 arguments
+<tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and
+<tt/ocredit/. See the section on the arguments for the details of how
+these work and there defaults.
+
+<item> <bf/Rotated/ -
+
+Is the new password a rotated version of the old password?
+
+<item> <bf/Already used/ -
+
+Was the password used in the past? Previously used passwords are to
+be found in /etc/security/opasswd.
+
+</itemize>
+
+<p>
+This module with no arguments will work well for standard unix
+password encryption. With md5 encryption, passwords can be longer
+than 8 characters and the default settings for this module can make it
+hard for the user to choose a satisfactory new password. Notably, the
+requirement that the new password contain no more than 1/2 of the
+characters in the old password becomes a non-trivial constraint. For
+example, an old password of the form "the quick brown fox jumped over
+the lazy dogs" would be difficult to change... In addition, the
+default action is to allow passwords as small as 5 characters in
+length. For a md5 systems it can be a good idea to increase the
+required minimum size of a password. One can then allow more credit
+for different kinds of characters but accept that the new password may
+share most of these characters with the old password.
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/;
+<tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/;
+
+<tag><bf>Description:</bf></tag>
+
+The action of this module is to prompt the user for a password and
+check its strength against a system dictionary and a set of rules for
+identifying poor choices.
+
+<p>
+The default action is to prompt for a single password, check its
+strength and then, if it is considered strong, prompt for the password
+a second time (to verify that it was typed correctly on the first
+occasion). All being well, the password is passed on to subsequent
+modules to be installed as the new authentication token.
+
+<p>
+The default action may be modified in a number of ways using the
+arguments recognized by the module:
+<itemize>
+
+<item> <tt/debug/ -
+
+this option makes the module write information to syslog(3) indicating
+the behavior of the module (this option does <bf/not/ write password
+information to the log file).
+
+<item> <tt/type=XXX/ -
+
+the default action is for the module to use the following prompts when
+requesting passwords: ``New UNIX password: '' and ``Retype UNIX
+password: ''. Using this option you can replace the word UNIX with
+<tt/XXX/.
+
+<item> <tt/retry=N/ -
+
+the default number of times this module will request a new password
+(for strength-checking) from the user is 1. Using this argument this
+can be increased to <tt/N/.
+
+<item> <tt/difok=N/ -
+
+This argument will change the default of 10 for the number of
+characters in the new password that must not be present in the old
+password. In addition, if 1/2 of the characters in the new password
+are different then the new password will be accepted anyway.
+
+<item> <tt/minlen=N/ -
+
+The minimum acceptable size for the new password plus one. In
+addition to the number of characters in the new password, credit (of
++1 in length) is given for each different kind of character (<em>other,
+upper, lower</em> and <em/digit/). The default for this parameter is
+9 which is good for a old style UNIX password all of the same type of
+character but may be too low to exploit the added security of a md5
+system. Note that there is a pair of length limits in
+<em>Cracklib</em> itself, a "way too short" limit of 4 which is hard
+coded in and a defined limit (6) that will be checked without
+reference to <tt>minlen</tt>. If you want to allow passwords as short
+as 5 characters you should either not use this module or recompile
+the crack library and then recompile this module.
+
+<item> <tt/dcredit=N/ -
+
+This is the maximum credit for having digits in the new password. If
+you have less than or <tt/N/ digits, each digit will count +1 towards
+meeting the current <tt/minlen/ value. The default for <tt/dcredit/
+is 1 which is the recommended value for <tt/minlen/ less than 10.
+
+<item> <tt/ucredit=N/ -
+
+This is the maximum credit for having upper case letters in the new
+password. If you have less than or <tt/N/ upper case letters each
+letter will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/ucredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10.
+
+<item> <tt/lcredit=N/ -
+
+This is the maximum credit for having lower case letters in the new
+password. If you have less than or <tt/N/ lower case letters, each
+letter will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/lcredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10.
+
+<item> <tt/ocredit=N/ -
+
+This is the maximum credit for having other characters in the new
+password. If you have less than or <tt/N/ other characters, each
+character will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/ocredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+(At the time of writing, this module can only be stacked before the
+<tt/pam_pwdb/ module. Cracklib strength checking may be compiled by
+default into the <tt/pam_unix/ module.)
+
+<p>
+For an example of the use of this module, we show how it may be
+stacked with the password component of <tt/pam_pwdb/:
+<tscreen>
+<verb>
+#
+# These lines stack two password type modules. In this example the
+# user is given 3 opportunities to enter a strong password. The
+# "use_authtok" argument ensures that the pam_pwdb module does not
+# prompt for a password, but instead uses the one provided by
+# pam_cracklib.
+#
+passwd password required pam_cracklib.so retry=3
+passwd password required pam_pwdb.so use_authtok
+</verb>
+</tscreen>
+
+<p>
+Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the
+case that you want to use md5 password encryption:
+<tscreen>
+<verb>
+#%PAM-1.0
+#
+# These lines allow a md5 systems to support passwords of at least 14
+# bytes with extra credit of 2 for digits and 2 for others the new
+# password must have at least three bytes that are not present in the
+# old password
+#
+password required pam_cracklib.so \
+ difok=3 minlen=15 dcredit= 2 ocredit=2
+password required pam_pwdb.so use_authtok nullok md5
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml
new file mode 100644
index 0000000..6e1f299
--- /dev/null
+++ b/doc/modules/pam_deny.sgml
@@ -0,0 +1,179 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The locking-out module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_deny
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+current <bf/Linux-PAM/ maintainer
+
+<tag><bf>Management groups provided:</bf></tag>
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+clean.
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module can be used to deny access. It always indicates a failure
+to the application through the PAM framework. As is commented in the
+overview section <ref id="overview-section" name="above">, this module
+might be suitable for using for default (the <tt/OTHER/) entries.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This component does nothing other than return a failure. The
+failure type is <tt/PAM_ACCT_EXPIRED/.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Stacking this module with type <tt/account/ will prevent the user from
+gaining access to the system via applications that refer to
+<bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/.
+
+<p>
+The following example would make it impossible to login:
+<tscreen>
+<verb>
+#
+# add this line to your other login entries to disable all accounts
+#
+login account required pam_deny.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This component does nothing other than return a failure. The failure
+type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is
+called (when the application tries to authenticate the user), and is
+<tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/
+(to establish and set the credentials of the user -- it is unlikely
+that this function will ever be called in practice).
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+To deny access to default applications with this component of the
+<tt/pam_deny/ module, you might include the following line in your
+<bf/Linux-PAM/ configuration file:
+<tscreen>
+<verb>
+#
+# add this line to your existing OTHER entries to prevent
+# authentication succeeding with default applications.
+#
+OTHER auth required pam_deny.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This component of the module denies the user the opportunity to change
+their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when
+invoked.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This module should be used to prevent an application from updating the
+applicant user's password. For example, to prevent <tt/login/ from
+automatically prompting for a new password when the old one has
+expired you should include the following line in your configuration
+file:
+<tscreen>
+<verb>
+#
+# add this line to your other login entries to prevent the login
+# application from being able to change the user's password.
+#
+login password required pam_deny.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This aspect of the module prevents an application from starting a
+session on the host computer.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Together with another session module, that displays a message of the
+day perhaps (XXX - such a module needs to be written),
+this module can be used to block a user from starting a shell. Given
+the presence of a <tt/pam_motd/ module, we might use the following
+entries in the configuration file to inform the user it is system
+time:
+<tscreen>
+<verb>
+#
+# An example to see how to configure login to refuse the user a
+# session (politely)
+#
+login session required pam_motd.so \
+ file=/etc/system_time
+login session required pam_deny.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml
new file mode 100644
index 0000000..8057b38
--- /dev/null
+++ b/doc/modules/pam_env.sgml
@@ -0,0 +1,141 @@
+<!--
+ $Id$
+
+ This file was written by Dave Kinchlea <kinch@kinch.ark.com>
+ Ed. AGM
+-->
+
+<sect1>Set/unset environment variables
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_env/
+
+<tag><bf>Author:</bf></tag>
+Dave Kinchlea &lt;kinch@kinch.ark.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+Authentication (setcred)
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+<tt>/etc/security/pam_env.conf</tt>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module allows the (un)setting of environment variables. Supported
+is the use of previously set environment variables as well as
+<em>PAM_ITEM</em>s such as <tt>PAM_RHOST</tt>.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/conffile=/<em/configuration-file-name/;
+<tt/envfile/=/<em/env-file-name/; <tt/readenv/=/<em/0|1/
+
+<tag><bf>Description:</bf></tag>
+This module allows you to (un)set arbitrary environment variables
+using fixed strings, the value of previously set environment variables
+and/or <em/PAM_ITEM/s.
+
+<p>
+All is controlled via a configuration file (by default,
+<tt>/etc/security/pam_env.conf</tt> but can be overriden with
+<tt>connfile</tt> argument). Each line starts with the variable name,
+there are then two possible options for each variable <bf>DEFAULT</bf>
+and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows and administrator to
+set the value of the variable to some default value, if none is
+supplied then the empty string is assumed. The <bf>OVERRIDE</bf>
+option tells pam_env that it should enter in its value (overriding the
+default value) if there is one to use. <bf>OVERRIDE</bf> is not used,
+<tt>""</tt> is assumed and no override will be done.
+
+<p>
+<tscreen>
+<verb>
+VARIABLE [DEFAULT=[value]] [OVERRIDE=[value]]
+</verb>
+</tscreen>
+
+<p>
+(Possibly non-existent) environment variables may be used in values
+using the <tt>&dollar;&lcub;string&rcub;</tt> syntax and (possibly
+non-existent) <em/PAM_ITEM/s may be used in values using the
+<tt>&commat;&lcub;string&rcub;</tt> syntax. Both the <tt>&dollar;</tt>
+and <tt>&commat;</tt> characters can be backslash-escaped to be used
+as literal values (as in <tt>&bsol;&dollar;</tt>. Double quotes may
+be used in values (but not environment variable names) when white
+space is needed <bf>the full value must be delimited by the quotes and
+embedded or escaped quotes are not supported</bf>.
+
+<p>
+This module can also parse a file with simple KEY=VAL pairs on seperate
+lines (/etc/environment by default). You can change the default file to
+parse, with the <em/envfile/ flag and turn it on or off by setting the
+<em/readenv/ flag to 1 or 0 respectively.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+
+<item><tt/debug/
+- write more information to <tt/syslog(3)/.
+
+<item><tt/conffile=/<em/filename/
+- by default the file <tt>/etc/security/pam_env.conf</tt> is used as
+the configuration file. This option overrides the default. You must
+supply a complete path + file name.
+
+<item><tt/envfile=/<em/filename/
+- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL
+pairs directly into the env. This option overrides the default. You must
+supply a complete path + file name.
+
+<item><tt/readenv=/<em/0|1/
+- turns on or off the reading of the file specified by envfile (0 is off,
+1 is on). By default this option is on.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+See sample <tt>pam_env.conf</tt> for more information and examples.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml
new file mode 100644
index 0000000..598279b
--- /dev/null
+++ b/doc/modules/pam_filter.sgml
@@ -0,0 +1,150 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The filter module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+
+pam_filter
+
+<tag><bf>Author:</bf></tag>
+
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+Not yet.
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+This module compiles cleanly on Linux based systems.
+
+<tag><bf>System dependencies:</bf></tag>
+
+To function it requires <em/filters/ to be installed on the system.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module was written to offer a plug-in alternative to programs
+like ttysnoop (XXX - need a reference). Since writing a filter that
+performs this function has not occurred, it is currently only a toy.
+The single filter provided with the module simply transposes upper and
+lower case letters in the input and output streams. (This can be very
+annoying and is not kind to termcap based editors).
+
+<sect2>Account+Authentication+Password+Session components
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/
+
+<tag><bf>Description:</bf></tag>
+
+Each component of the module has the potential to invoke the desired
+filter. The filter is always <tt/execv(2)/d with the privilege of the
+calling application and <bf/not/ that of the user. For this reason it
+cannot usually be killed by the user without closing their session.
+
+<p>
+The behavior of the module can be significantly altered by the
+arguments passed to it in the <bf/Linux-PAM/ configuration file:
+<itemize>
+<item><tt/debug/ -
+
+this option increases the amount of information logged to
+<tt/syslog(3)/ as the module is executed.
+
+<item><tt/new_term/ -
+
+the default action of the filter is to set the <tt/PAM_TTY/ item to
+indicate the terminal that the user is using to connect to the
+application. This argument indicates that the filter should set
+<tt/PAM_TTY/ to the filtered pseudo-terminal.
+
+<item><tt/non_term/ -
+don't try to set the <tt/PAM_TTY/ item.
+
+<item><tt/runX/ -
+
+in order that the module can invoke a filter it should know when to
+invoke it. This argument is required to tell the filter when to do
+this. The arguments that follow this one are respectively the full
+pathname of the filter to be run and any command line arguments that
+the filter might expect.
+
+<p>
+Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the
+precise time the that filter is to be run. To explain this concept it
+will be useful to have read the Linux-PAM Module developer's
+guide. Basically, for each management group there are up to two ways
+of calling the module's functions.
+
+In the case of the <em/authentication/ and <em/session/ components
+there are actually two separate functions. For the case of
+authentication, these functions are <tt/_authenticate/ and
+<tt/_setcred/ -- here <tt/run1/ means run the filter from the
+<tt/_authenticate/ function and <tt/run2/ means run the filter from
+<tt/_setcred/. In the case of the session modules, <tt/run1/ implies
+that the filter is invoked at the <tt/_open_session/ stage, and
+<tt/run2/ for <tt/_close_session/.
+
+<p>
+For the case of the account component. Either <tt/run1/ or <tt/run2/
+may be used.
+
+<p>
+For the case of the password component, <tt/run1/ is used to indicate
+that the filter is run on the first occasion <tt/_chauthtok/ is run
+(the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate
+that the filter is run on the second occasion (the
+<tt/PAM_UPDATE_AUTHTOK/ phase).
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+At the time of writing there is little real use to be made of this
+module. For fun you might try adding the following line to your
+login's configuration entries
+<tscreen>
+<verb>
+#
+# An example to see how to configure login to transpose upper and
+# lower case letters once the user has logged in(!)
+#
+login session required pam_filter.so \
+ run1 /usr/sbin/pam_filter/upperLOWER
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml
new file mode 100644
index 0000000..3c26a5f
--- /dev/null
+++ b/doc/modules/pam_ftp.sgml
@@ -0,0 +1,93 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+-->
+
+<sect1>Anonymous access module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_ftp.so/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+prompts for email address of user; easily spoofed (XXX - needs work)
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+The purpose of this module is to provide a pluggable anonymous ftp
+mode of access.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/users=XXX,YYY,.../;
+<tt/ignore/
+
+<tag><bf>Description:</bf></tag>
+
+This module intercepts the user's name and password. If the name is
+``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up
+at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/
+part; these pam-items being set accordingly. The username is set to
+``<tt/ftp/''. In this case the module succeeds. Alternatively, the
+module sets the <tt/PAM_AUTHTOK/ item with the entered password and
+fails.
+
+<p>
+The behavior of the module can be modified with the following flags:
+<itemize>
+<item><tt/debug/ -
+log more information to with <tt/syslog(3)/.
+
+<item><tt/users=XXX,YYY,.../ -
+instead of ``<tt/ftp/'' or ``<tt/anonymous/'', provide anonymous login
+to the comma separated list of users; ``<tt/XXX,YYY,.../''. Should the
+applicant enter one of these usernames the returned username is set to
+the first in the list; ``<tt/XXX/''.
+
+<item><tt/ignore/ -
+pay no attention to the email address of the user (if supplied).
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+An example of the use of this module is provided in the configuration
+file section <ref id="configuration" name="above">. With care, this
+module could be used to provide new/temporary account anonymous
+login.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml
new file mode 100644
index 0000000..8251e3d
--- /dev/null
+++ b/doc/modules/pam_group.sgml
@@ -0,0 +1,108 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The group access module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_group/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+Sensitive to <em/setgid/ status of file-systems accessible to users.
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled
+with or without <tt/libpwdb/.
+
+<tag><bf>Network aware:</bf></tag>
+Only through correctly set <tt/PAM_TTY/ item.
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module provides group-settings based on the user's name and the
+terminal they are requesting a given service from. It takes note of
+the time of day.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This module does not authenticate the user, but instead it grants
+group memberships (in the credential setting phase of the
+authentication module) to the user. Such memberships are based on the
+service they are applying for. The group memberships are listed in
+text form in the <tt>/etc/security/group.conf</tt> file.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+For this module to function correctly there must be a correctly
+formatted <tt>/etc/security/groups.conf</tt> file present. The format
+of this file is as follows. Group memberships are given based on the
+service application satisfying any combination of lines in the
+configuration file. Each line (barring comments which are preceded by
+`<tt/#/' marks) has the following
+syntax:
+<tscreen>
+<verb>
+services ; ttys ; users ; times ; groups
+</verb>
+</tscreen>
+Here the first four fields share the syntax of the <tt>pam_time</tt>
+configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last
+field, the <tt/groups/ field, is a comma (or space) separated list of
+the text-names of a selection of groups. If the users application for
+service satisfies the first four fields, the user is granted membership
+of the listed groups.
+
+<p>
+As stated in above this module's usefulness relies on the file-systems
+accessible to the user. The point being that once granted the
+membership of a group, the user may attempt to create a <em/setgid/
+binary with a restricted group ownership. Later, when the user is not
+given membership to this group, they can recover group membership with
+the precompiled binary. The reason that the file-systems that the user
+has access to are so significant, is the fact that when a system is
+mounted <em/nosuid/ the user is unable to create or execute such a
+binary file. For this module to provide any level of security, all
+file-systems that the user has write access to should be mounted
+<em/nosuid/.
+
+<p>
+The <tt>pam_group</tt> module fuctions in parallel with the
+<tt>/etc/group</tt> file. If the user is granted any groups based on
+the behavior of this module, they are granted <em>in addition</em> to
+those entries <tt>/etc/group</tt> (or equivalent).
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_issue.sgml b/doc/modules/pam_issue.sgml
new file mode 100644
index 0000000..1f617e3
--- /dev/null
+++ b/doc/modules/pam_issue.sgml
@@ -0,0 +1,120 @@
+<!--
+
+Ben Collins <bcollins@debian.org>
+
+-->
+
+<sect1>Add issue file to user prompt
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_issue/
+
+<tag><bf>Author:</bf></tag>
+Ben Collins &lt;bcollins@debian.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+Authentication (pam_sm_authenticate)
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module prepends the issue file (<em>/etc/issue</em> by default) when
+prompting for a username.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/issue=issue-file-name/; <tt/noesc/;
+
+<tag><bf>Description:</bf></tag>
+This module allows you to prepend an issue file to the username prompt. It
+also by default parses escape codes in the issue file similar to some
+common getty's (using &bsol;x format).
+<p>
+Recognized escapes:
+<itemize>
+
+<item><tt/d/
+- current date
+
+<item><tt/s/
+- operating system name
+
+<item><tt/l/
+- name of this tty
+
+<item><tt/m/
+- architecture of this system (i686, sparc, powerpc, ...)
+
+<item><tt/n/
+- hostname of this system
+
+<item><tt/o/
+- domainname of this system
+
+<item><tt/r/
+- release number of the operation system (eg. 2.2.12)
+
+<item><tt/t/
+- current time
+
+<item><tt/u/
+- number of users currently logged in
+
+<item><tt/U/
+- same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1
+user" or "10 users"
+
+<item><tt/v/
+- version/build-date of the operating system (eg. "&num;3 Mon Aug 23 14:38:16
+EDT 1999" on Linux).
+
+</itemize>
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+
+<item><tt/issue/
+- the file to output if not using the default
+
+<item><tt/noesc/
+- turns off escape code parsing
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+login auth pam_issue.so issue=/etc/issue
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_krb4.sgml b/doc/modules/pam_krb4.sgml
new file mode 100644
index 0000000..16ce818
--- /dev/null
+++ b/doc/modules/pam_krb4.sgml
@@ -0,0 +1,126 @@
+<!--
+ $Id$
+
+ This file was written by Derrick J. Brashear <shadow@DEMENTIA.ORG>
+-->
+
+<sect1>The Kerberos 4 module.
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_krb4/
+
+<tag><bf>Author:</bf></tag>
+Derrick J. Brashear &lt;shadow@dementia.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+uses API
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+libraries - <tt/libkrb/, <tt/libdes/, <tt/libcom_err/, <tt/libkadm/;
+and a set of Kerberos include files.
+
+<tag><bf>Network aware:</bf></tag>
+Gets Kerberos ticket granting ticket via a Kerberos key distribution
+center reached via the network.
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module provides an interface for doing Kerberos verification of a
+user's password, getting the user a Kerberos ticket granting ticket
+for use with the Kerberos ticket granting service, destroying the
+user's tickets at logout time, and changing a Kerberos password.
+
+<sect2> Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This component of the module currently sets the user's <tt/KRBTKFILE/
+environment variable (although there is currently no way to export
+this), as well as deleting the user's ticket file upon logout (until
+<tt/PAM_CRED_DELETE/ is supported by <em/login/).
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This part of the module won't be terribly useful until we can change
+the environment from within a <tt/Linux-PAM/ module.
+
+</descrip>
+
+<sect2> Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/use_first_pass/; <tt/try_first_pass/
+
+<tag><bf>Description:</bf></tag>
+
+This component of the module changes a user's Kerberos password
+by first getting and using the user's old password to get
+a session key for the password changing service, then sending
+a new password to that service.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This should only be used with a real Kerberos v4 <tt/kadmind/. It
+cannot be used with an AFS kaserver unless special provisions are
+made. Contact the module author for more information.
+
+</descrip>
+
+<sect2> Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/use_first_pass/; <tt/try_first_pass/
+
+<tag><bf>Description:</bf></tag>
+
+This component of the module verifies a user's Kerberos password
+by requesting a ticket granting ticket from the Kerberos server
+and optionally using it to attempt to retrieve the local computer's
+host key and verifying using the key file on the local machine if
+one exists.
+
+It also writes out a ticket file for the user to use later, and
+deletes the ticket file upon logout (not until <tt/PAM_CRED_DELETE/
+is called from <em/login/).
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This module can be used with a real Kerberos server using MIT
+v4 Kerberos keys. The module or the system Kerberos libraries
+may be modified to support AFS style Kerberos keys. Currently
+this is not supported to avoid cryptography constraints.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_lastlog.sgml b/doc/modules/pam_lastlog.sgml
new file mode 100644
index 0000000..2ade5ba
--- /dev/null
+++ b/doc/modules/pam_lastlog.sgml
@@ -0,0 +1,119 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The last login module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_lastlog/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+auth
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+uses information contained in the <tt>/var/log/lastlog</tt> file.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This session module maintains the <tt>/var/log/lastlog</tt> file. Adding
+an open entry when called via the <tt>pam_open_seesion()</tt> function
+and completing it when <tt>pam_close_session()</tt> is called. This
+module can also display a line of information about the last login of
+the user. If an application already performs these tasks, it is not
+necessary to use this module.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/nodate/; <tt/noterm/; <tt/nohost/; <tt/silent/;
+<tt/never/
+
+<tag><bf>Description:</bf></tag>
+
+<p>
+This module can be used to provide a ``Last login on ...''
+message. when the user logs into the system from what ever application
+uses the PAM libraries. In addition, the module maintains the
+<tt>/var/log/lastlog</tt> file.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+<item><tt/debug/
+- write more information to <tt/syslog(3)/.
+
+<item><tt/nodate/
+- neglect to give the date of the last login when displaying
+information about the last login on the system.
+
+<item><tt/noterm/
+- neglect to diplay the terminal name on which the last login was
+attempt.
+
+<item><tt/nohost/
+- neglect to indicate from which host the last login was attempted.
+
+<item><tt/silent/
+- neglect to inform the user about any previous login: just update
+the <tt>/var/log/lastlog</tt> file.
+
+<item><tt/never/
+- if the <tt>/var/log/lastlog</tt> file does not contain any old entries
+for the user, indicate that the user has never previously logged in
+with a ``welcome..." message.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This module can be used to indicate that the user has new mail when
+they <em/login/ to the system. Here is a sample entry for your
+<tt>/etc/pam.conf</tt> file:
+<tscreen>
+<verb>
+#
+# do we have any mail?
+#
+login session optional pam_lastlog.so
+</verb>
+</tscreen>
+
+<p>
+Note, some applications may perform this function themselves. In such
+cases, this module is not necessary.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_limits.sgml b/doc/modules/pam_limits.sgml
new file mode 100644
index 0000000..f7a2245
--- /dev/null
+++ b/doc/modules/pam_limits.sgml
@@ -0,0 +1,197 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ from information compiled by Cristian Gafton (author of module)
+-->
+
+<sect1>The resource limits module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_limits/
+
+<tag><bf>Authors:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt; <newline>
+Thanks are also due to Elliot Lee &lt;sopwith@redhat.com&gt;
+for his comments on improving this module.
+
+<tag><bf>Maintainer:</bf></tag>
+Cristian Gafton - 1996/11/20
+
+<tag><bf>Management groups provided:</bf></tag>
+session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+requires an <tt>/etc/security/limits.conf</tt> file and kernel support
+for resource limits. Also uses the library, <tt/libpwdb/.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets
+limits on the system resources that can be obtained in a
+user-session. Its actions are dictated more explicitly through the
+configuration file discussed below.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt>conf=/path/to/file.conf</tt>
+
+<tag><bf>Description:</bf></tag>
+
+Through the contents of the configuration file,
+<tt>/etc/security/limits.conf</tt>, resource limits are placed on
+users' sessions. Users of <tt/uid=0/ are not affected by this
+restriction.
+
+<p>
+The behavior of this module can be modified with the following
+arguments:
+<itemize>
+
+<item><tt/debug/ -
+verbose logging to <tt/syslog(3)/.
+
+<item><tt>conf=/path/to/file.conf</tt> -
+indicate an alternative <em/limits/ configuration file to the default.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In order to use this module the system administrator must first create
+a <em/root-only-readable/ file (default is
+<tt>/etc/security/limits.conf</tt>). This file describes the resource
+limits the superuser wishes to impose on users and groups. No limits
+are imposed on <tt/uid=0/ accounts.
+
+<p>
+Each line of the configuration file describes a limit for a user in
+the form:
+<tscreen>
+<verb>
+<domain> <type> <item> <value>
+</verb>
+</tscreen>
+
+<p>
+The fields listed above should be filled as follows...<newline>
+<tt>&lt;domain&gt;</tt> can be:
+<itemize>
+<item> a username
+<item> a groupname, with <tt>@group</tt> syntax
+<item> the wild-card <tt/*/, for default entry
+</itemize>
+
+<p>
+<tt>&lt;type&gt;</tt> can have the two values:
+<itemize>
+
+<item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits
+are set by the superuser and enforced by the Linux Kernel. The user
+cannot raise his requirement of system resources above such values.
+
+<item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits
+are ones that the user can move up or down within the permitted range
+by any pre-exisiting <em/hard/ limits. The values specified with this
+token can be thought of as <em/default/ values, for normal system
+usage.
+
+</itemize>
+
+<p>
+<tt>&lt;item&gt;</tt> can be one of the following:
+<itemize>
+<item><tt/core/ - limits the core file size (KB)
+<item><tt/data/ - max data size (KB)
+<item><tt/fsize/ - maximum filesize (KB)
+<item><tt/memlock/ - max locked-in-memory address space (KB)
+<item><tt/nofile/ - max number of open files
+<item><tt/rss/ - max resident set size (KB)
+<item><tt/stack/ - max stack size (KB)
+<item><tt/cpu/ - max CPU time (MIN)
+<item><tt/nproc/ - max number of processes
+<item><tt/as/ - address space limit
+<item><tt/maxlogins/ - max number of logins for this user.
+<item><tt/priority/ - the priority to run user process with
+</itemize>
+
+<p>
+To completely disable limits for a user (or a group), a single dash
+(-) will do (Example: ``<tt/bin -/'', ``<tt/@admin -/''). Please
+remember that individual limits have priority over group limits, so if
+you impose no limits for <tt/admin/ group, but one of the members in this
+group have a limits line, the user will have its limits set according
+to this line.
+
+<p>
+Also, please note that all limit settings are set <em/per login/.
+They are not global, nor are they permanent; existing only for the
+duration of the session.
+
+<p>
+In the <em/limits/ configuration file, the ``<tt/#/'' character
+introduces a comment - after which the rest of the line is ignored.
+
+<p>
+The <tt/pam_limits/ module does its best to report configuration
+problems found in its configuration file via <tt/syslog(3)/.
+
+<p>
+The following is an example configuration file:
+<tscreen>
+<verb>
+# EXAMPLE /etc/security/limits.conf file:
+# =======================================
+# <domain> <type> <item> <value>
+* soft core 0
+* hard rss 10000
+@student hard nproc 20
+@faculty soft nproc 20
+@faculty hard nproc 50
+ftp hard nproc 0
+@student - maxlogins 4
+</verb>
+</tscreen>
+Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource
+(see <tt/@faculty/) -- this establishes the <em/default/ and permitted
+<em/extreme/ level of resources that the user can can obtain in a
+given service-session.
+
+<p>
+For the services that need resources limits (login for example) put a
+the following line in <tt>/etc/pam.conf</tt> as the last line for that
+service (usually after the pam_unix session line:
+<tscreen>
+<verb>
+#
+# Resource limits imposed on login sessions via pam_limits
+#
+login session required pam_limits.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml
new file mode 100644
index 0000000..98589a3
--- /dev/null
+++ b/doc/modules/pam_listfile.sgml
@@ -0,0 +1,138 @@
+<!--
+ $Id$
+
+ This file was written by Michael K. Johnson <johnsonm@redhat.com>
+-->
+
+<sect1>The list-file module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_listfile/
+
+<tag><bf>Author:</bf></tag>
+Elliot Lee <tt>&lt;sopwith@cuc.edu&gt;</tt>
+
+<tag><bf>Maintainer:</bf></tag>
+Red Hat Software:<newline>
+Michael K. Johnson &lt;johnsonm@redhat.com&gt; 1996/11/18<newline>
+(if unavailable, contact Elliot Lee &lt;sopwith@cuc.edu&gt;).
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+clean
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+The list-file module provides a way to deny or allow services based on
+an arbitrary file.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tt>onerr=succeed|fail</tt>;
+<tt>sense=allow|deny</tt>;
+<tt>file=</tt><it>filename</it>;
+<tt>item=user|tty|rhost|ruser|group|shell</tt>
+<tt>apply=user|@group</tt>
+
+<tag><bf>Description:</bf></tag>
+
+The module gets the item of the type specified -- <tt>user</tt> specifies
+the username, <tt>PAM_USER</tt>; tty specifies the name of the terminal
+over which the request has been made, <tt>PAM_TTY</tt>; rhost specifies
+the name of the remote host (if any) from which the request was made,
+<tt>PAM_RHOST</tt>; and ruser specifies the name of the remote user
+(if available) who made the request, <tt>PAM_RUSER</tt> -- and looks for
+an instance of that item in the file <it>filename</it>. <it>filename</it>
+contains one line per item listed. If the item is found, then if
+<tt>sense=allow</tt>, <tt>PAM_SUCCESS</tt> is returned, causing the
+authorization request to succeed; else if <tt>sense=deny</tt>,
+<tt>PAM_AUTH_ERR</tt> is returned, causing the authorization
+request to fail.
+
+<p>
+If an error is encountered (for instance, if <it>filename</it>
+does not exist, or a poorly-constructed argument is encountered),
+then if <tt>onerr=succeed</tt>, <tt>PAM_SUCCESS</tt> is returned,
+otherwise if <tt>onerr=fail</tt>, <tt>PAM_AUTH_ERR</tt> or
+<tt>PAM_SERVICE_ERR</tt> (as appropriate) will be returned.
+
+<p>
+An additional argument, <tt>apply=</tt>, can be used to restrict the
+application of the above to a specific user
+(<tt>apply=</tt><em>username</em>) or a given group
+(<tt>apply=@</tt><em>groupname</em>). This added restriction is only
+meaningful when used with the <tt/tty/, <tt/rhost/ and <tt/shell/
+<em/items/.
+
+<p>
+Besides this last one, all arguments should be specified; do not count
+on any default behavior, as it is subject to change.
+
+<p>
+No credentials are awarded by this module.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Classic ``ftpusers'' authentication can be implemented with this entry
+in <tt>/etc/pam.conf</tt>:
+<tscreen>
+<verb>
+#
+# deny ftp-access to users listed in the /etc/ftpusers file
+#
+ftp auth required pam_listfile.so \
+ onerr=succeed item=user sense=deny file=/etc/ftpusers
+</verb>
+</tscreen>
+Note, users listed in <tt>/etc/ftpusers</tt> file are
+(counterintuitively) <bf/not/ allowed access to the ftp service.
+
+<p>
+To allow login access only for certain users, you can use an
+pam.conf entry like this:
+<tscreen>
+<verb>
+#
+# permit login to users listed in /etc/loginusers
+#
+login auth required pam_listfile.so \
+ onerr=fail item=user sense=allow file=/etc/loginusers
+</verb>
+</tscreen>
+
+<p>
+For this example to work, all users who are allowed to use the login
+service should be listed in the file <tt>/etc/loginusers</tt>. Unless
+you are explicitly trying to lock out root, make sure that when you do
+this, you leave a way for root to log in, either by listing root in
+<tt>/etc/loginusers</tt>, or by listing a user who is able to <em/su/
+to the root account.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml
new file mode 100644
index 0000000..064b9ff
--- /dev/null
+++ b/doc/modules/pam_mail.sgml
@@ -0,0 +1,137 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+-->
+
+<sect1>The mail module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_mail/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+Authentication (credential)
+Session (open)
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Default mail directory <tt>/var/spool/mail/</tt>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module looks at the user's mail directory and indicates
+whether the user has any mail in it.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/dir=/<em/direcory-name/; <tt/nopen/; <tt/close/;
+<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/;
+<tt/quiet/;
+
+<tag><bf>Description:</bf></tag>
+
+This module provides the ``you have new mail'' service to the user. It
+can be plugged into any application that has credential hooks. It gives a
+single message indicating the <em/newness/ of any mail it finds in the
+user's mail folder. This module also sets the <bf/Linux-PAM/
+environment variable, <tt/MAIL/, to the user's mail directory.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+<item><tt/debug/
+- write more information to <tt/syslog(3)/.
+
+<item><tt/dir=/<em/pathname/
+- look for the users' mail in an alternative directory given by
+<em/pathname/. The default location for mail is
+<tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is
+prefixed by a `<tt/&tilde;/', the directory is interpreted as
+indicating a file in the user's home directory.
+
+<item><tt/nopen/
+- instruct the module to <em/not/ print any mail information when the
+user's credentials are acquired. This flag is useful to get the <tt/MAIL/
+environment variable set, but to not display any information about it.
+
+<item><tt/close/
+- instruct the module to indicate if the user has any mail at the as
+the user's credentials are revoked.
+
+<item><tt/noenv/
+- do not set the <tt/MAIL/ environment variable.
+
+<item><tt/empty/
+- indicate that the user's mail directory is empty if this is found to
+be the case.
+
+<item><tt/hash=/<em/hashcount/
+- mail directory hash depth. For example, a <em/hashcount/ of 2 would
+make the mailfile be <tt>/var/spool/mail/u/s/user</tt>.
+
+<item><tt/standard/
+- old style "You have..." format which doesn't show the mail spool being used.
+ this also implies "empty"
+
+<item><tt/quiet/
+- only report when there is new mail.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This module can be used to indicate that the user has new mail when
+they <em/login/ to the system. Here is a sample entry for your
+<tt>/etc/pam.conf</tt> file:
+<tscreen>
+<verb>
+#
+# do we have any mail?
+#
+login session optional pam_mail.so
+</verb>
+</tscreen>
+
+<p>
+Note, some applications may perform this function themselves. In such
+cases, this module is not necessary.
+
+</descrip>
+
+<sect2>Authentication compent
+
+<p>
+Then authentication companent works the same as the session component,
+expect that everything is done during the pam_setcred() phase.
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_mkhomedir.sgml b/doc/modules/pam_mkhomedir.sgml
new file mode 100644
index 0000000..075e16f
--- /dev/null
+++ b/doc/modules/pam_mkhomedir.sgml
@@ -0,0 +1,83 @@
+<!--
+
+Ben Collins <bcollins@debian.org>
+
+-->
+
+<sect1>Create home directories on initial login
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_mkhomedir/
+
+<tag><bf>Author:</bf></tag>
+Jason Gunthorpe &lt;jgg@ualberta.ca&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Ben Collins &lt;bcollins@debian.org&gt;
+
+<tag><bf>Management groups provided:</bf></tag>
+Session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Creates home directories on the fly for authenticated users.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/;
+
+<tag><bf>Description:</bf></tag>
+This module is useful for distributed systems where the user account is
+managed in a central database (such as NIS, NIS+, or LDAP) and accessed
+through miltiple systems. It frees the administrator from having to create
+a default home directory on each of the systems by creating it upon the
+first succesfully authenticated login of that user. The skeleton directory
+(usually /etc/skel/) is used to copy default files and also set's a umask
+for the creation.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+
+<item><tt/skel/
+- The skeleton directory for default files to copy to the new home directory.
+
+<item><tt/umask/
+- An octal for of the same format as you would pass to the shells umask command.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+session required pam_mkhomedir.so skel=/etc/skel/ umask=0022
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml
new file mode 100644
index 0000000..1f8fc39
--- /dev/null
+++ b/doc/modules/pam_motd.sgml
@@ -0,0 +1,77 @@
+<!--
+
+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 succesful
+login.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/motd=motd-file-name/;
+
+<tag><bf>Description:</bf></tag>
+This module allows you to have arbitrary motd's (message of the day)
+output after a succesful login. By default this file is <em>/etc/motd</em>,
+but is configurable to any file.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+
+<item><tt/motd/
+- the file to output if not using the default.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+login session pam_motd.so motd=/etc/motd
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml
new file mode 100644
index 0000000..90564d8
--- /dev/null
+++ b/doc/modules/pam_nologin.sgml
@@ -0,0 +1,75 @@
+<!--
+ $Id$
+
+ This file was written by Michael K. Johnson <johnsonm@redhat.com>
+-->
+
+<sect1>The no-login module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_nologin/
+
+<tag><bf>Author:</bf></tag>
+Written by Michael K. Johnson &lt;johnsonm@redhat.com&gt;<newline>
+(based on code taken from a module written by Andrew G. Morgan
+&lt;morgan@parc.power.net&gt;).
+
+<tag><bf>Maintainer:</bf></tag>
+Michael K. Johnson &lt;johnsonm@redhat.com&gt;
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+1 warning about dropping const
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Provides standard Unix <em/nologin/ authentication.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+Provides standard Unix <em/nologin/ authentication. If the file
+<tt>/etc/nologin</tt> exists, only root is allowed to log in; other
+users are turned away with an error message. All users (root or
+otherwise) are shown the contents of <tt>/etc/nologin</tt>.
+
+<p>
+If the file <tt>/etc/nologin</tt> does not exist, this module succeeds
+silently.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In order to make this module effective, all login methods should
+be secured by it. It should be used as a <tt>required</tt>
+method listed before any <tt>sufficient</tt> methods in order to
+get standard Unix nologin semantics.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml
new file mode 100644
index 0000000..8b201b7
--- /dev/null
+++ b/doc/modules/pam_permit.sgml
@@ -0,0 +1,83 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The promiscuous module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_permit
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan, &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Linux-PAM maintainer.
+
+<tag><bf>Management groups provided:</bf></tag>
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+VERY LOW. Use with extreme caution.
+
+<tag><bf>Clean code base:</bf></tag>
+Clean.
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is very dangerous. It should be used with extreme
+caution. Its action is always to permit access. It does nothing else.
+
+<sect2>Account+Authentication+Password+Session components
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+No matter what management group, the action of this module is to
+simply return <tt/PAM_SUCCESS/ -- operation successful.
+
+<p>
+In the case of authentication, the user's name will be acquired. Many
+applications become confused if this name is unknown.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+It is seldom a good idea to use this module. However, it does have
+some legitimate uses. For example, if the system-administrator wishes
+to turn off the account management on a workstation, and at the same
+time continue to allow logins, then she might use the following
+configuration file entry for login:
+<tscreen>
+<verb>
+#
+# add this line to your other login entries to disable account
+# management, but continue to permit users to log in...
+#
+login account required pam_permit.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml
new file mode 100644
index 0000000..022cfe5
--- /dev/null
+++ b/doc/modules/pam_pwdb.sgml
@@ -0,0 +1,252 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+-->
+
+<sect1>The Password-Database module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_pwdb
+
+<tag><bf>Author:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt; <newline>
+and Andrew G. Morgan &lt;morgan@linux.kernel.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Authors.
+
+<tag><bf>Management groups provided:</bf></tag>
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires properly configured <tt/libpwdb/
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is a pluggable replacement for the <tt/pam_unix_../
+modules. It uses the generic interface of the <em/Password Database/
+library
+<tt><htmlurl
+url="http://linux.kernel.org/morgan/libpwdb/index.html"
+name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the accounting functions of this module
+<tt/syslog(3)/ more information on its actions. (Remaining arguments
+supported by the other functions of this module are silently ignored,
+but others are logged as errors through <tt/syslog(3)/).
+
+Based on the following <tt/pwdb_element/s:
+<tt/expire/;
+<tt/last_change/;
+<tt/max_change/;
+<tt/defer_change/;
+<tt/warn_change/,
+this module performs the task of establishing the status of the user's
+account and password. In the case of the latter, it may offer advice
+to the user on changing their password or, through the
+<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
+they have established a new password. The entries listed above are
+documented in the <em/Password Database Library Guide/ (see pointer
+above). Should the user's record not contain one or more of these
+entries, the corresponding <em/shadow/ check is not performed.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In its accounting mode, this module can be inserted as follows:
+<tscreen>
+<verb>
+#
+# Ensure users account and password are still active
+#
+login account required pam_pwdb.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/use_first_pass/;
+<tt/try_first_pass/;
+<tt/nullok/;
+<tt/nodelay/;
+<tt/likeauth/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the authentication functions of this
+module <tt/syslog(3)/ more information on its actions.
+
+<p>
+The default action of this module is to not permit the user access to
+a service if their <em/official/ password is blank. The <tt/nullok/
+argument overrides this default.
+
+<p>
+When given the argument <tt/try_first_pass/, before prompting the user
+for their password, the module first tries the previous stacked
+<tt/auth/-module's password in case that satisfies this module as
+well. The argument <tt/use_first_pass/ forces the module to use such a
+recalled password and will never prompt the user - if no password is
+available or the password is not appropriate, the user will be denied
+access.
+
+<p>
+The argument, <tt>nodelay</tt>, can be used to discourage the
+authentication component from requesting a delay should the
+authentication as a whole fail. The default action is for the module
+to request a delay-on-failure of the order of one second.
+
+<p>
+Remaining arguments, supported by the other functions of this module,
+are silently ignored. Other arguments are logged as errors through
+<tt/syslog(3)/.
+
+<p>
+A helper binary, <tt>pwdb_chkpwd</tt>, is provided to check the user's
+password when it is stored in a read protected database. This binary
+is very simple and will only check the password of the user invoking
+it. It is called transparently on behalf of the user by the
+authenticating component of this module. In this way it is possible
+for applications like <em>xlock</em> to work without being setuid-root.
+
+<p>
+The <tt>likeauth</tt> argument makes the module return the same value
+when called as a credential setting module and an authentication
+module. This will help libpam take a sane path through the auth
+component of your configuration file.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The correct functionality of this module is dictated by having an
+appropriate <tt>/etc/pwdb.conf</tt> file, the user
+databases specified there dictate the source of the authenticated
+user's record.
+
+</descrip>
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/;
+<tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/;
+<tt/shadow/; <tt/radius/; <tt/unix/
+
+<tag><bf>Description:</bf></tag>
+
+This part of the <tt/pam_pwdb/ module performs the task of updating
+the user's password. Thanks to the flexibility of <tt/libpwdb/ this
+module is able to move the user's password from one database to
+another, perhaps securing the user's database entry in a dynamic
+manner (<em/this is very ALPHA code at the moment!/) - this is the
+purpose of the <tt/shadow/, <tt/radius/ and <tt/unix/ arguments.
+
+<p>
+In the case of conventional unix databases (which store the password
+encrypted) the <tt/md5/ argument is used to do the encryption with the
+MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
+As an alternative to this, the <tt/bigcrypt/ argument can be used to
+encrypt more than the first 8 characters of a password with DEC's
+(Digital Equipment Cooperation) `C2' extension to the standard UNIX
+<tt/crypt()/ algorithm.
+
+<p>
+The <tt/nullok/ module is used to permit the changing of a password
+<em/from/ an empty one. Without this argument, empty passwords are
+treated as account-locking ones.
+
+<p>
+The argument <tt/use_first_pass/ is used to lock the choice of old and
+new passwords to that dictated by the previously stacked <tt/password/
+module. The <tt/try_first_pass/ argument is used to avoid the user
+having to re-enter an old password when <tt/pam_pwdb/ follows a module
+that possibly shared the user's old password - if this old password is
+not correct the user will be prompted for the correct one. The
+argument <tt/use_authtok/ is used to <em/force/ this module to set the
+new password to the one provided by the previously stacked
+<tt/password/ module (this is used in an example of the stacking of
+the <em/Cracklib/ module documented above).
+
+<p>
+The <tt/not_set_pass/ argument is used to inform the module that it is
+not to pay attention to/make available the old or new passwords from/to
+other (stacked) password modules.
+
+<p>
+The <tt/debug/ argument makes the password functions of this module
+<tt/syslog(3)/ more information on its actions. Other arguments may be
+logged as erroneous to <tt/syslog(3)/.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+An example of the stacking of this module with respect to the
+pluggable password checking module, <tt/pam_cracklib/, is given in
+that modules section above.
+</descrip>
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+No arguments are recognized by this module component. Its action is
+simply to log the username and the service-type to
+<tt/syslog(3)/. Messages are logged at the beginning and end of the
+user's session.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The use of the session modules is straightforward:
+<tscreen>
+<verb>
+#
+# pwdb - unix like session opening and closing
+#
+login session required pam_pwdb.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml
new file mode 100644
index 0000000..fb442ee
--- /dev/null
+++ b/doc/modules/pam_radius.sgml
@@ -0,0 +1,117 @@
+<!--
+ $Id$
+
+ This file was written by Cristian Gafton <gafton@redhat.com>
+-->
+
+<sect1>The RADIUS session module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_radius/
+
+<tag><bf>Author:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+This module does not deal with passwords
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+gcc reports 1 warning when compiling <tt>/usr/include/rpc/clnt.h</tt>.
+Hey, is not my fault !
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+yes; this is a network module (independent of application).
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is intended to provide the session service for users
+autheticated with a RADIUS server. At the present stage, the only
+option supported is the use of the RADIUS server as an accounting
+server.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tt/debug/ - verbose logging to <tt/syslog(3)/.
+
+<tag><bf>Description:</bf></tag>
+
+This module is intended to provide the session service for users
+autheticated with a RADIUS server. At the present stage, the only
+option supported is the use of the RADIUS server as an <em/accounting/
+server.
+
+<p>
+(There are few things which needs to be cleared out first in
+the PAM project until one will be able to use this module and expect
+it to magically start pppd in response to a RADIUS server command to
+use PPP for this user, or to initiate a telnet connection to another
+host, or to hang and call back the user using parameters provided in
+the RADIUS server response. Most of these things are better suited for
+the radius login application. I hope to make available Real Soon (tm)
+patches for the login apps to make it work this way.)
+
+<p>
+When opening a session, this module sends an ``Accounting-Start''
+message to the RADIUS server, which will log/update/whatever a
+database for this user. On close, an ``Accounting-Stop'' message is
+sent to the RADIUS server.
+
+<p>
+This module has no other prerequisites for making it work. One can
+install a RADIUS server just for fun and use it as a centralized
+accounting server and forget about wtmp/last/sac etc. .
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+For the services that need this module (<em/login/ for example) put
+the following line in <tt>/etc/pam.conf</tt> as the last line for that
+service (usually after the pam_unix session line):
+<tscreen>
+<verb>
+login session required pam_radius.so
+</verb>
+</tscreen>
+Replace <tt/login/ for each service you are using this module.
+
+<p>
+This module make extensive use of the API provided in libpwdb
+0.54preB or later. By default, it will read the radius server
+configuration (hostname and secret) from <tt>/etc/raddb/server</tt>.
+This is a default compiled into libpwdb, and curently there is no way to
+modify this default without recompiling libpwdb. I am working on
+extending the radius support from libpwdb to provide a possibility
+to make this runtime-configurable.
+
+Also please note that libpwdb will require also the RADIUS
+dictionary to be present (<tt>/etc/raddb/dictionary</tt>).
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
+
diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml
new file mode 100644
index 0000000..00e55a9
--- /dev/null
+++ b/doc/modules/pam_rhosts.sgml
@@ -0,0 +1,164 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The rhosts module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_rhosts_auth/
+
+<tag><bf>Author:</bf></tag>
+Al Longyear &lt;longyear@netcom.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+Clean.
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls.
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module performs the standard network authentication for services,
+as used by traditional implementations of <em/rlogin/ and <em/rsh/
+etc.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/;
+<tt/privategroup/; <tt/promiscuous/; <tt/suppress/
+
+<tag><bf>Description:</bf></tag>
+
+The authentication mechanism of this module is based on the contents
+of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in
+<tt>#include &lt;netdb.h&gt;</tt>) and <tt>~/.rhosts</tt>. Firstly,
+hosts listed in the former file are treated as equivalent to the
+localhost. Secondly, entries in the user's own copy of the latter file
+is used to map "<tt/remote-host remote-user/" pairs to that user's
+account on the current host. Access is granted to the user if their
+host is present in <tt>/etc/hosts.equiv</tt> and their remote account
+is identical to their local one, or if their remote account has an
+entry in their personal configuration file.
+
+<p>
+Some restrictions are applied to the attributes of the user's personal
+configuration file: it must be a regular file (as defined by
+<tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or
+the user; it must not be writable by any user besides its owner.
+
+<p>
+The module authenticates a remote user (internally specified by the
+item <tt/PAM_RUSER/) connecting from the remote host (internally
+specified by the item <tt/PAM_RHOST/). Accordingly, for applications
+to be compatible this authentication module they must set these items
+prior to calling <tt/pam_authenticate()/. The module is not capable
+of independently probing the network connection for such information.
+
+<p>
+In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is
+<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option
+should be used. Instead, the superuser must have a correctly configured
+personal configuration file.
+
+<p>
+The behavior of the module is modified by flags:
+<itemize>
+<item>
+<tt/debug/ -
+log more information to <tt/syslog(3)/. (XXX - actually, this module
+does not do any logging currently, please volunteer to fix this!)
+
+<item>
+<tt/no_warn/ -
+do not give verbal warnings to the user about failures etc. (XXX -
+this module currently does not issue any warnings, please volunteer to
+fix this!)
+
+<item>
+<tt/no_hosts_equiv/ -
+ignore the contents of the <tt>/etc/hosts.equiv</tt> file.
+
+<item>
+<tt/hosts_equiv_rootok/ -
+allow the use of <tt>/etc/hosts.equiv</tt> for superuser. Without this
+option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account.
+This option has no effect if the <tt>no_hosts_equiv</tt> option is used.
+
+<item>
+<tt/no_rhosts/ -
+ignore the contents of all user's personal configuration file
+<tt>~/.rhosts</tt>.
+
+<item>
+<tt/privategroup/ -
+normally, the <tt>~/.rhosts</tt> file must not be writable by anyone
+other than its owner. This option overlooks group write access in the
+case that the group owner of this file has the same name as the
+user being authenticated. To lessen the security problems associated
+with this option, the module also checks that the user is the only
+member of their private group.
+
+<item>
+<tt/promiscuous/ -
+A host entry of `+' will lead to all hosts being granted
+access. Without this option, '+' entries will be ignored. Note, that
+the <tt/debug/ option will syslog a warning in this latter case.
+
+<item>
+<tt/suppress/ -
+This will prevent the module from <tt/syslog(3)/ing a warning message
+when this authentication fails. This option is mostly for keeping
+logs free of meaningless errors, in particular when the module is used
+with the <tt/sufficient/ control flag.
+
+</itemize>
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+To allow users to login from trusted remote machines, you should try
+adding the following line to your <tt>/etc/pam.conf</tt> file
+<em/before/ the line that would otherwise prompt the user for a
+password:
+<tscreen>
+<verb>
+#
+# No passwords required for users from hosts listed above.
+#
+login auth sufficient pam_rhosts_auth.so no_rhosts
+</verb>
+</tscreen>
+Note, in this example, the system administrator has turned off all
+<em/personal/ <em/rhosts/ configuration files. Also note, that this module
+can be used to <em/only/ allow remote login from hosts specified in
+the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the
+above example with <tt/required/.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml
new file mode 100644
index 0000000..e362a2a
--- /dev/null
+++ b/doc/modules/pam_rootok.sgml
@@ -0,0 +1,85 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>The root access module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_rootok
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+<bf>Linux-PAM</bf> maintainer
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+Clean.
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is for use in situations where the superuser wishes
+to gain access to a service without having to enter a password.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/
+
+<tag><bf>Description:</bf></tag>
+
+This module authenticates the user if their <tt/uid/ is <tt/0/.
+Applications that are created <em/setuid/-root generally retain the
+<tt/uid/ of the user but run with the authority of an enhanced
+<em/effective-/<tt/uid/. It is the real <tt/uid/ that is checked.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In the case of the <tt/su/ application the historical usage is to
+permit the superuser to adopt the identity of a lesser user without
+the use of a password. To obtain this behavior under <tt/Linux-PAM/
+the following pair of lines are needed for the corresponding entry in
+the configuration file:
+<tscreen>
+<verb>
+#
+# su authentication. Root is granted access by default.
+#
+su auth sufficient pam_rootok.so
+su auth required pam_unix_auth.so
+</verb>
+</tscreen>
+
+<p>
+Note. For programs that are run by the superuser (or started when the
+system boots) this module should not be used to authenticate users.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_securetty.sgml b/doc/modules/pam_securetty.sgml
new file mode 100644
index 0000000..ceb1358
--- /dev/null
+++ b/doc/modules/pam_securetty.sgml
@@ -0,0 +1,72 @@
+<!--
+ $Id$
+
+ This file was written by Michael K. Johnson <johnsonm@redhat.com>
+-->
+
+<sect1>The securetty module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_securetty/
+
+<tag><bf>Author[s]:</bf></tag>
+Elliot Lee &lt;sopwith@cuc.edu&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Red Hat Software:<newline>
+<em/currently/ Michael K. Johnson &lt;johnsonm@redhat.com&gt;<newline>
+(if unavailable, contact Elliot Lee &lt;sopwith@cuc.edu&gt;).
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+<tt>/etc/securetty</tt> file
+
+<tag><bf>Network aware:</bf></tag>
+
+Requires the application to fill in the <tt>PAM_TTY</tt> item
+correctly in order to act meaningfully.
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Provides standard Unix securetty checking.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+Provides standard Unix securetty checking, which causes authentication
+for root to fail unless <tt>PAM_TTY</tt> is set to a string listed in
+the <tt>/etc/securetty</tt> file. For all other users, it succeeds.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+For canonical usage, should be listed as a <tt>required</tt>
+authentication method before any <tt>sufficient</tt> authentication
+methods.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml
new file mode 100644
index 0000000..4104aad
--- /dev/null
+++ b/doc/modules/pam_time.sgml
@@ -0,0 +1,166 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>Time control
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_time/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan <tt>&lt;morgan@parc.power.net&gt;</tt>
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+account
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires a configuration file <tt>/etc/security/time.conf</tt>
+
+<tag><bf>Network aware:</bf></tag>
+Through the <tt/PAM_TTY/ item only
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Running a well regulated system occasionally involves restricting
+access to certain services in a selective manner. This module offers
+some time control for access to services offered by a system. Its
+actions are determined with a configuration file. This module can be
+configured to deny access to (individual) users based on their name,
+the time of day, the day of week, the service they are applying for
+and their terminal from which they are making their request.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+This module bases its actions on the rules listed in its configuration
+file: <tt>/etc/security/pam.conf</tt>. Each rule has the following
+form,
+<tscreen>
+<em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/
+</tscreen>
+In words, each rule occupies a line, terminated with a newline or the
+beginning of a comment; a `<tt/#/'. It contains four fields separated
+with semicolons, `<tt/;/'. The fields are as follows:
+
+<p>
+<itemize>
+<item><em/services/ -
+a logic list of service names that are affected by this rule.
+
+<item><em/ttys/ -
+a logic list of terminal names indicating those terminals covered by
+the rule.
+
+<item><em/user/ -
+a logic list of usernames to which this rule applies
+
+<p>
+By a logic list we mean a sequence of tokens (associated with the
+appropriate <tt/PAM_/ item), containing no more than one wildcard
+character; `<tt/*/', and optionally prefixed with a negation operator;
+`<tt/!/'. Such a sequence is concatenated with one of two logical
+operators: <tt/&amp;/ (logical AND) and <tt/|/ (logical OR). Two
+examples are: <tt>!morgan&amp;!root</tt>, indicating that this rule
+does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and
+<tt>tty*&amp;!ttyp*</tt>, which indicates that the rule applies only
+to console terminals but not pseudoterminals.
+
+<item><em/times/ - a logic list of times at which this rule
+applies. The format of each element is a day/time-range. The days are
+specified by a sequence of two character entries. For example,
+<tt/MoTuSa/, indicates Monday Tuesday and Saturday. Note that
+repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and
+<tt/MoWk/ means all weekdays bar Monday. The two character
+combinations accepted are,
+<tscreen>
+<verb>
+Mo Tu We Th Fr Sa Su Wk Wd Al
+</verb>
+</tscreen>
+The last two of these being <em/weekend/ days and <em/all 7 days/ of
+the week respectively.
+
+<p>
+The time range part is a pair of 24-hour times, <em/HHMM/, separated
+by a hyphen -- indicating the start and finish time for the rule. If
+the finsish time is smaller than the start time, it is assumed to
+apply on the following day. For an example, <tt/Mo1800-0300/ indicates
+that the permitted times are Monday night from 6pm to 3am the
+following morning.
+
+</itemize>
+
+<p>
+Note, that the given time restriction is only applied when the first
+three fields are satisfied by a user's application for service.
+
+<p>
+For convenience and readability a rule can be extended beyond a single
+line with a `<tt>&bsol;</tt><em/newline/'.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The use of this module is initiated with an entry in the
+<bf/Linux-PAM/ configuration file of the following type:
+<tscreen>
+<verb>
+#
+# apply pam_time accounting to login requests
+#
+login account required pam_time.so
+</verb>
+</tscreen>
+where, here we are applying the module to the <em/login/ application.
+
+<p>
+Some examples of rules that can be placed in the
+<tt>/etc/security/time.conf</tt> configuration file are the following:
+<descrip>
+
+<tag><tt>login ; tty* &amp ; !ttyp* ; !root ; !Al0000-2400</tt></tag>
+all users except for <tt/root/ are denied access to console-login at
+all times.
+
+<tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag>
+games (configured to use Linux-PAM) are only to be accessed out of
+working hours. This rule does not apply to the user <tt/waster/.
+
+</descrip>
+
+<p>
+Note, currently there is no daemon enforcing the end of a session.
+This needs to be remedied.
+
+<p>
+Poorly formatted rules are logged as errors using <tt/syslog(3)/.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml
new file mode 100644
index 0000000..792362e
--- /dev/null
+++ b/doc/modules/pam_unix.sgml
@@ -0,0 +1,289 @@
+<!--
+ This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+
+ Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
+-->
+
+<sect1>The Unix Password module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+pam_unix
+
+<tag><bf>Author:</bf></tag>
+
+<tag><bf>Maintainer:</bf></tag>
+Authors.
+
+<tag><bf>Management groups provided:</bf></tag>
+account; authentication; password; session
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This is the standard Unix authentication module. It uses standard calls
+from the system's libraries to retrieve and set account information as
+well as authentication. Usually this is obtained from the /etc/passwd
+and the /etc/shadow file aswell if shadow is enabled.
+
+<sect2>Account component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/audit/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the accounting functions of this module
+<tt/syslog(3)/ more information on its actions. (Remaining arguments
+supported by the other functions of this module are silently ignored,
+but others are logged as errors through <tt/syslog(3)/). The <tt/audit/
+argument causes even more logging.
+
+Based on the following <tt/shadow/ elements:
+<tt/expire/;
+<tt/last_change/;
+<tt/max_change/;
+<tt/min_change/;
+<tt/warn_change/,
+this module performs the task of establishing the status of the user's
+account and password. In the case of the latter, it may offer advice
+to the user on changing their password or, through the
+<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
+they have established a new password. The entries listed above are
+documented in the <em/GNU Libc/ info documents. Should the user's record
+not contain one or more of these entries, the corresponding <em/shadow/
+check is not performed.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+In its accounting mode, this module can be inserted as follows:
+<tscreen>
+<verb>
+#
+# Ensure users account and password are still active
+#
+login account required pam_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/audit/;
+<tt/use_first_pass/;
+<tt/try_first_pass/;
+<tt/nullok/;
+<tt/nodelay/
+
+<tag><bf>Description:</bf></tag>
+
+The <tt/debug/ argument makes the authentication functions of this
+module <tt/syslog(3)/ more information on its actions. The <tt/audit/
+causes even more information to be logged.
+
+<p>
+The default action of this module is to not permit the user access to
+a service if their <em/official/ password is blank. The <tt/nullok/
+argument overrides this default.
+
+<p>
+When given the argument <tt/try_first_pass/, before prompting the user
+for their password, the module first tries the previous stacked
+<tt/auth/-module's password in case that satisfies this module as
+well. The argument <tt/use_first_pass/ forces the module to use such a
+recalled password and will never prompt the user - if no password is
+available or the password is not appropriate, the user will be denied
+access.
+
+<p>
+The argument, <tt>nodelay</tt>, can be used to discourage the
+authentication component from requesting a delay should the
+authentication as a whole fail. The default action is for the module
+to request a delay-on-failure of the order of one second.
+
+<p>
+Remaining arguments, supported by the other functions of this module,
+are silently ignored. Other arguments are logged as errors through
+<tt/syslog(3)/.
+
+<p>
+A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's
+password when it is stored in a read protected database. This binary
+is very simple and will only check the password of the user invoking
+it. It is called transparently on behalf of the user by the
+authenticating component of this module. In this way it is possible
+for applications like <em>xlock</em> to work without being setuid-root.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The correct functionality of this module is dictated by having an
+appropriate <tt>/etc/nsswitch.conf</tt> file, the user
+databases specified there dictate the source of the authenticated
+user's record.
+<p>
+In its authentication mode, this module can be inserted as follows:
+<tscreen>
+<verb>
+#
+# Authenticate the user
+#
+login auth required pam_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/audit/;
+<tt/nullok/;
+<tt/not_set_pass/;
+<tt/use_authtok/;
+<tt/try_first_pass/;
+<tt/use_first_pass/;
+<tt/md5/;
+<tt/bigcrypt/;
+<tt/shadow/;
+<tt/nis/;
+<tt/remember/
+
+<tag><bf>Description:</bf></tag>
+
+This part of the <tt/pam_unix/ module performs the task of updating
+the user's password.
+
+<p>
+In the case of conventional unix databases (which store the password
+encrypted) the <tt/md5/ argument is used to do the encryption with the
+MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
+As an alternative to this, the <tt/bigcrypt/ argument can be used to
+encrypt more than the first 8 characters of a password with DEC's
+(Digital Equipment Cooperation) `C2' extension to the standard UNIX
+<tt/crypt()/ algorithm.
+
+<p>
+The <tt/nullok/ argument is used to permit the changing of a password
+<em/from/ an empty one. Without this argument, empty passwords are
+treated as account-locking ones.
+
+<p>
+The argument <tt/use_first_pass/ is used to lock the choice of old and
+new passwords to that dictated by the previously stacked <tt/password/
+module. The <tt/try_first_pass/ argument is used to avoid the user
+having to re-enter an old password when <tt/pam_unix/ follows a module
+that possibly shared the user's old password - if this old password is
+not correct the user will be prompted for the correct one. The
+argument <tt/use_authtok/ is used to <em/force/ this module to set the
+new password to the one provided by the previously stacked
+<tt/password/ module (this is used in an example of the stacking of
+the <em/Cracklib/ module documented above).
+
+<p>
+The <tt/not_set_pass/ argument is used to inform the module that it is
+not to pay attention to/make available the old or new passwords from/to
+other (stacked) password modules.
+
+<p>
+The <tt/debug/ argument makes the password functions of this module
+<tt/syslog(3)/ more information on its actions. Other arguments may be
+logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes
+even more information to be logged.
+
+<p>
+With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC
+for setting new passwords.
+
+<p>
+The <tt/remember/ argument takes one value. This is the number of most
+recent passwords to save for each user. These are saved in
+<tt>/etc/security/opasswd</tt> in order to force password change history
+and keep the user from alternating between the same password too frequently.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+Standard usage:
+<tscreen>
+<verb>
+#
+# Change the users password
+#
+passwd password required pam_unix.so
+</verb>
+</tscreen>
+
+<p>
+An example of the stacking of this module with respect to the
+pluggable password checking module, <tt/pam_cracklib/:
+<tscreen>
+<verb>
+#
+# Change the users password
+#
+passwd password required pam_cracklib.so retry=3 minlen=6 difok=3
+passwd password required pam_unix.so use_authtok nullok md5
+</verb>
+</tscreen>
+
+</descrip>
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+No arguments are recognized by this module component. Its action is
+simply to log the username and the service-type to
+<tt/syslog(3)/. Messages are logged at the beginning and end of the
+user's session.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+The use of the session modules is straightforward:
+<tscreen>
+<verb>
+#
+# session opening and closing
+#
+login session required pam_unix.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_userdb.sgml b/doc/modules/pam_userdb.sgml
new file mode 100644
index 0000000..bdbf80b
--- /dev/null
+++ b/doc/modules/pam_userdb.sgml
@@ -0,0 +1,112 @@
+<!--
+ This file was written by Cristian Gafton <gafton@redhat.com>
+-->
+
+<sect1>The userdb module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_userdb/
+
+<tag><bf>Author:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires Berkeley DB.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Look up users in a .db database and verify their password against
+what is contained in that database.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/icase/;
+<tt/dump/;
+<tt/db=XXXX/;
+
+<tag><bf>Description:</bf></tag>
+
+This module is used to verify a username/password pair against values stored in
+a Berkeley DB database. The database is indexed by the username, and the data
+fields corresponding to the username keys are the passwords, in unencrypted form,
+so caution must be exercised over the access rights to the DB database itself..
+
+The module will read the password from the user using the conversation mechanism. If
+you are using this module on top of another authetication module (like <tt/pam_pwdb/;)
+then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module.
+
+<p>
+The action of the module may be modified from this default by one or
+more of the following flags in the <tt>/etc/pam.d/&lt;service&gt;</tt> file.
+<itemize>
+<item>
+<tt/debug/ -
+Supply more debugging information to <tt/syslog(3)/.
+
+<item>
+<tt/icase/ -
+Perform the password comparisons case insensitive.
+
+<item>
+<tt/dump/ -
+dump all the entries in the database to the log (eek,
+don't do this by default!)
+
+<item>
+<tt/db=XXXX/ -
+use the database found on pathname XXXX. Note that Berkeley DB usually adds the
+needed filename extension for you, so you should use something like <tt>/etc/foodata</tt>
+instead of <tt>/etc/foodata.db</tt>.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt>
+on most systems) that will accept for login users whose username/password pairs are
+provided in the <tt>/tmp/dbtest.db</tt> file:
+
+<tscreen>
+<verb>
+#%PAM-1.0
+auth required pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed
+auth sufficient pam_userdb.so icase db=/tmp/dbtest
+auth required pam_pwdb.so shadow nullok try_first_pass
+auth required pam_shells.so
+account required pam_pwdb.so
+session required pam_pwdb.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml
new file mode 100644
index 0000000..2ca4cc8
--- /dev/null
+++ b/doc/modules/pam_warn.sgml
@@ -0,0 +1,67 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+-->
+
+<sect1>Warning logger module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_warn/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@parc.power.net&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication; password
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+<tag><bf>Network aware:</bf></tag>
+logs information about the remote user and host (if pam-items are known)
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module is principally for logging information about a
+proposed authentication or application to update a password.
+
+<sect2>Authentication+Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tag><bf>Description:</bf></tag>
+
+Log the service, terminal, user, remote user and remote host to
+<tt/syslog(3)/. The items are not probed for, but instead obtained
+from the standard pam-items.
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+an example is provided in the configuration file section <ref
+id="configuration" name="above">.
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml
new file mode 100644
index 0000000..1eb6274
--- /dev/null
+++ b/doc/modules/pam_wheel.sgml
@@ -0,0 +1,125 @@
+<!--
+ $Id$
+
+ This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ from notes provided by Cristian Gafton.
+-->
+
+<sect1>The wheel module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_wheel/
+
+<tag><bf>Author:</bf></tag>
+Cristian Gafton &lt;gafton@redhat.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+authentication
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Requires libpwdb.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+Only permit root access to members of the wheel (<tt/gid=0/) group.
+
+<sect2>Authentication component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/;
+<tt/use_uid/;
+<tt/trust/;
+<tt/deny/;
+<tt/group=XXXX/
+
+<tag><bf>Description:</bf></tag>
+
+This module is used to enforce the so-called <em/wheel/ group. By
+default, it permits root access to the system if the applicant user is
+a member of the <tt/wheel/ group (first, the module checks for the
+existence of a '<tt/wheel/' group. Otherwise the module defines the
+group with group-id <tt/0/ to be the <em/wheel/ group).
+
+<p>
+The action of the module may be modified from this default by one or
+more of the following flags in the <tt>/etc/pam.conf</tt> file.
+<itemize>
+<item>
+<tt/debug/ -
+Supply more debugging information to <tt/syslog(3)/.
+
+<item>
+<tt/use_uid/ -
+This option modifies the behavior of the module by using the current
+<tt/uid/ of the process and not the <tt/getlogin(3)/ name of the user.
+This option is useful for being able to jump from one account to
+another, for example with 'su'.
+
+<item>
+<tt/trust/ -
+This option instructs the module to return <tt/PAM_SUCCESS/ should it
+find the user applying for root privilege is a member of the wheel
+group. The default action is to return <tt/PAM_IGNORE/ in this
+situation. By using the <tt/trust/ option it is possible to arrange
+for <tt/wheel/-group members to become root without typing a
+password. <bf/USE WITH CARE/.
+
+<item>
+<tt/deny/ -
+This is used to reverse the logic of the module's behavior.
+If the user is trying to get <tt/uid=0/ access and is a member of the wheel
+group, deny access (for the wheel group, this is perhaps nonsense!):
+it is intended for use in conjunction with the <tt/group=/ argument...
+
+<item>
+<tt/group=XXXX/ -
+Instead of checking the <tt/gid=0/ group, use the user's <tt/XXXX/
+group membership for the authentication. Here, <tt/XXXX/ is the name
+of the group and <bf/not/ its numeric identifier.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+To restrict access to superuser status to the members of the
+<tt/wheel/ group, use the following entries in your configuration
+file:
+<tscreen>
+<verb>
+#
+# root gains access by default (rootok), only wheel members can
+# become root (wheel) but Unix authenticate non-root applicants.
+#
+su auth sufficient pam_rootok.so
+su auth required pam_wheel.so
+su auth required pam_unix_auth.so
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->
diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
new file mode 100644
index 0000000..d1be8c1
--- /dev/null
+++ b/doc/pam_appl.sgml
@@ -0,0 +1,1643 @@
+<!doctype linuxdoc system>
+
+<!--
+
+ $Id$
+
+ Copyright (C) Andrew G. Morgan 1996-9. 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.71 1999/11/8
+<abstract>
+This manual documents what an application developer needs to know
+about the <bf>Linux-PAM</bf> library. It describes how an application
+might use the <bf>Linux-PAM</bf> library to authenticate users. In
+addition it contains a description of the funtions to be found in
+<tt/libpam_misc/ library, that can be used in general applications.
+Finally, it contains some comments on PAM related security issues for
+the application developer.
+</abstract>
+
+<toc>
+
+<sect>Introduction
+
+<sect1>Synopsis
+
+<p>
+For general applications that wish to use the services provided by
+<bf/Linux-PAM/ the following is a summary of the relevant linking
+information:
+<tscreen>
+<verb>
+#include <security/pam_appl.h>
+
+cc -o application .... -lpam -ldl
+</verb>
+</tscreen>
+
+<p>
+In addition to <tt/libpam/, there is a library of miscellaneous
+functions that make the job of writing <em/PAM-aware/ applications
+easier (this library is not covered in the DCE-RFC for PAM and is
+specific to the Linux-PAM distribution):
+<tscreen>
+<verb>
+...
+#include <security/pam_misc.h>
+
+cc -o application .... -lpam -lpam_misc -ldl
+</verb>
+</tscreen>
+
+<sect1> Description
+
+<p>
+<bf>Linux-PAM</bf> (Pluggable Authentication Modules for Linux) is a
+library that enables the local system administrator to choose how
+individual applications authenticate users. For an overview of the
+<bf>Linux-PAM</bf> library see the <bf/Linux-PAM/ System
+Administrators' Guide.
+
+<p>
+It is the purpose of the <bf>Linux-PAM</bf> project to liberate the
+development of privilege granting software from the development of
+secure and appropriate authentication schemes. This is accomplished
+by providing a documented library of functions that an application may
+use for all forms of user authentication management. This library
+dynamically loads locally configured authentication modules that
+actually perform the authentication tasks.
+
+<p>
+From the perspective of an application developer the information
+contained in the local configuration of the PAM library should not be
+important. Indeed it is intended that an application treat the
+functions documented here as a ``black box'' that will deal with all
+aspects of user authentication. ``All aspects'' includes user
+verification, account management, session initialization/termination
+and also the resetting of passwords (<em/authentication tokens/).
+
+<sect>Overview
+
+<p>
+Most service-giving applications are restricted. In other words,
+their service is not available to all and every prospective client.
+Instead, the applying client must jump through a number of hoops to
+convince the serving application that they are authorized to obtain
+service.
+
+The process of <em/authenticating/ a client is what PAM is designed to
+manage. In addition to authentication, PAM provides account
+management, credential management, session management and
+authentication-token (password changing) management services. It is
+important to realize when writing a PAM based application that these
+services are provided in a manner that is <bf>transparent</bf> to the
+the application. That is to say, when the application is written, no
+assumptions can be made about <em>how</em> the client will be
+authenticated.
+
+<p>
+The process of authentication is performed by the PAM library via a
+call to <tt>pam_authenticate()</tt>. The return value of this
+function will indicate whether a named client (the <em>user</em>) has
+been authenticated. If the PAM library needs to prompt the user for
+any information, such as their <em>name</em> or a <em>password</em>
+then it will do so. If the PAM library is configured to authenticate
+the user using some silent protocol, it will do this too. (This
+latter case might be via some hardware interface for example.)
+
+<p>
+It is important to note that the application must leave all decisions
+about when to prompt the user at the discretion of the PAM library.
+
+<p>
+The PAM library, however, must work equally well for different styles
+of application. Some applications, like the familiar <tt>login</tt>
+and <tt>passwd</tt> are terminal based applications, exchanges of
+information with the client in these cases is as plain text messages.
+Graphically based applications, however, have a more sophisticated
+interface. They generally interact with the user via specially
+constructed dialogue boxes. Additionally, network based services
+require that text messages exchanged with the client are specially
+formatted for automated processing: one such example is <tt>ftpd</tt>
+which prefixes each exchanged message with a numeric identifier.
+
+<p>
+The presentation of simple requests to a client is thus something very
+dependent on the protocol that the serving application will use. In
+spite of the fact that PAM demands that it drives the whole
+authentication process, it is not possible to leave such protocol
+subtleties up to the PAM library. To overcome this potential problem,
+the application provides the PAM library with a <em>conversation</em>
+function. This function is called from <bf>within</bf> the PAM
+library and enables the PAM to directly interact with the client. The
+sorts of things that this conversation function must be able to do are
+prompt the user with text and/or obtain textual input from the user
+for processing by the PAM library. The details of this function are
+provided in a later section.
+
+<p>
+For example, the conversation function may be called by the PAM library
+with a request to prompt the user for a password. Its job is to
+reformat the prompt request into a form that the client will
+understand. In the case of <tt>ftpd</tt>, this might involve prefixing
+the string with the number <tt>331</tt> and sending the request over
+the network to a connected client. The conversation function will
+then obtain any reply and, after extracting the typed password, will
+return this string of text to the PAM library. Similar concerns need
+to be addressed in the case of an X-based graphical server.
+
+<p>
+There are a number of issues that need to be addressed when one is
+porting an existing application to become PAM compliant. A section
+below has been devoted to this: Porting legacy applications.
+
+<p>
+Besides authentication, PAM provides other forms of management.
+Session management is provided with calls to
+<tt>pam_open_session()</tt> and <tt>pam_close_session()</tt>. What
+these functions actually do is up to the local administrator. But
+typically, they could be used to log entry and exit from the system or
+for mounting and unmounting the user's home directory. If an
+application provides continuous service for a period of time, it
+should probably call these functions, first open after the user is
+authenticated and then close when the service is terminated.
+
+<p>
+Account management is another area that an application developer
+should include with a call to <tt/pam_acct_mgmt()/. This call will
+perform checks on the good health of the user's account (has it
+expired etc.). One of the things this function may check is whether
+the user's authentication token has expired - in such a case the
+application may choose to attempt to update it with a call to
+<tt/pam_chauthtok()/, although some applications are not suited to
+this task (<em>ftp</em> for example) and in this case the application
+should deny access to the user.
+
+<p>
+PAM is also capable of setting and deleting the users credentials with
+the call <tt>pam_setcred()</tt>. This function should always be
+called after the user is authenticated and before service is offered
+to the user. By convention, this should be the last call to the PAM
+library before 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>
+Below we document those functions in the <bf/Linux-PAM/ library that
+may be called from an application.
+
+<sect2>Initialization of Linux-PAM
+<label id="pam-start-section">
+
+<p>
+<tscreen>
+<verb>
+extern int pam_start(const char *service_name, const char *user,
+ const struct pam_conv *pam_conversation,
+ pam_handle_t **pamh);
+</verb>
+</tscreen>
+
+<p>
+This is the first of the <bf>Linux-PAM</bf> functions that must be
+called by an application. It initializes the interface and reads the
+system configuration file, <tt>/etc/pam.conf</tt> (see the
+<bf/Linux-PAM/ System Administrators' Guide). Following a successful
+return (<tt/PAM_SUCCESS/) the contents of <tt/*pamh/ is a handle that
+provides continuity for successive calls to the <bf/Linux-PAM/
+library. The arguments expected by <tt/pam_start/ are as follows: the
+<tt/service_name/ of the program, the <tt/user/name of the individual
+to be authenticated, a pointer to an application-supplied
+<tt/pam_conv/ structure and a pointer to a <tt/pam_handle_t/
+<em/pointer/.
+
+<p>
+The <tt>pam_conv</tt> structure is discussed more fully in the section
+<ref id="the-conversation-function" name="below">. The
+<tt>pam_handle_t</tt> is a <em>blind</em> structure and the
+application should not attempt to probe it directly for information.
+Instead the <bf>Linux-PAM</bf> library provides the functions
+<tt>pam_set_item</tt> and <tt>pam_get_item</tt>. These functions are
+documented below.
+
+<sect2>Termination of the library
+<label id="pam-end-section">
+
+<p>
+<tscreen>
+<verb>
+extern int pam_end(pam_handle_t *pamh, int pam_status);
+</verb>
+</tscreen>
+
+<p>
+This function is the last function an application should call in the
+<bf>Linux-PAM</bf> library. Upon return the handle <tt/pamh/ is no
+longer valid and all memory associated with it will be invalid (likely
+to cause a segmentation fault if accessed).
+
+<p>
+Under normal conditions the argument <tt/pam_status/ has the value
+PAM_SUCCESS, but in the event of an unsuccessful 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 call each of the <em/stacked/
+authentication modules listed in the relevant <bf/Linux-PAM/
+configuration file. As directed by this file, one of more of the
+modules may fail causing the <tt/pam_...()/ call to return an error.
+It is desirable for there to also be a pause before the application
+continues. The principal reason for such a delay is security: a delay
+acts to discourage <em/brute force/ dictionary attacks primarily, but
+also helps hinder <em/timed/ (covert channel) attacks.
+
+<p>
+The <tt/pam_fail_delay()/ function provides the mechanism by which an
+application or module can suggest a minimum delay (of <tt/micro_sec/
+<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time
+requested with this function. Should <tt/pam_authenticate()/ fail,
+the failing return to the application is delayed by an amount of time
+randomly distributed (by up to 25%) about this longest value.
+
+<p>
+Independent of success, the delay time is reset to its zero default
+value when <bf/Linux-PAM/ returns control to the application.
+
+<p>
+For applications written with a single thread that are event driven in
+nature, <tt/libpam/ generating this dalay may be undesirable. Instead,
+the application may want to register the delay in some other way. For
+example, in a single threaded server that serves multiple
+authentication requests from a single event loop, the application
+might want to simply mark a given connection as blocked until an
+application timer expires. For this reason, <bf/Linux-PAM/ supplies
+the <tt/PAM_FAIL_DELAY/ item. It can be queried and set with
+<tt/pam_get_item()/ and <tt/pam_set_item()/ respectively. The value
+used to set it should be a function pointer of the following
+prototype:
+
+<tscreen>
+<verb>
+void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
+</verb>
+</tscreen>
+
+The arguments being the <tt/retval/ return code of the module stack,
+the <tt/usec_delay/ micro-second delay that libpam is requesting and
+the <tt/appdata_ptr/ that the application has associated with the
+current <tt/pamh/ (/tt/pam_handle_t/). This last value was set by the
+application when it called <tt/pam_start/ or explicitly with
+<tt/pam_set_item(... , PAM_CONV, ...)/. Note, if <tt/PAM_FAIL_DELAY/
+is unset (or set to <tt/NULL/), then <tt/libpam/ will perform any
+delay.
+
+<sect2>Authenticating the user
+
+<p>
+<tscreen>
+<verb>
+extern int pam_authenticate(pam_handle_t *pamh, int flags);
+</verb>
+</tscreen>
+
+<p>
+This function serves as an interface to the authentication mechanisms
+of the loaded modules. The single <em/optional/ flag, which may be
+logically OR'd with <tt/PAM_SILENT/, takes the following value,
+
+<p><descrip>
+
+<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag>
+ Instruct the authentication modules to return
+<tt/PAM_AUTH_ERR/ if the user does not have a registered
+authorization token---it is set to <tt/NULL/ in the system database.
+</descrip>
+
+<p>
+The value returned by this function is one of the following:
+
+<p><descrip>
+
+<tag><tt/PAM_AUTH_ERR/</tag>
+ The user was not authenticated
+<tag><tt/PAM_CRED_INSUFFICIENT/</tag>
+ For some reason the application does not have sufficient
+credentials to authenticate the user.
+<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag>
+ The modules were not able to access the authentication
+information. This might be due to a network or hardware failure etc.
+<tag><tt/PAM_USER_UNKNOWN/</tag>
+ The supplied username is not known to the authentication
+service
+<tag><tt/PAM_MAXTRIES/</tag>
+ One or more of the authentication modules has reached its
+limit of tries authenticating the user. Do not try again.
+
+</descrip>
+
+<p>
+If one or more of the authentication modules fails to load, for
+whatever reason, this function will return <tt/PAM_ABORT/.
+
+<sect2>Setting user credentials
+<label id="pam-setcred-section">
+
+<p>
+<tscreen>
+<verb>
+extern int pam_setcred(pam_handle_t *pamh, int flags);
+</verb>
+</tscreen>
+
+<p>
+This function is used to set the module-specific credentials of the
+user. It is usually called after the user has been authenticated,
+after the account management function has been called 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>
+PAM, from the perspective of an application, is a convenient API for
+authenticating users. PAM modules generally have no increased
+privilege over that posessed by the application that is making use of
+it. For this reason, the application must take ultimate responsibility
+for protecting the environment in which PAM operates.
+
+<p>
+A poorly (or maliciously) written application can defeat any
+<bf/Linux-PAM/ module's authentication mechanisms by simply ignoring
+it's return values. It is the applications task and responsibility to
+grant privileges and access to services. The <bf/Linux-PAM/ library
+simply assumes the responsibility of <em/authenticating/ the user;
+ascertaining that the user <em/is/ who they say they are. Care should
+be taken to anticipate all of the documented behavior of the
+<bf/Linux-PAM/ library functions. A failure to do this will most
+certainly lead to a future security breach.
+
+<sect1>Care about standard library calls
+
+<p>
+In general, writers of authorization-granting applications should
+assume that each module is likely to call any or <em/all/ `libc'
+functions. For `libc' functions that return pointers to
+static/dynamically allocated structures (ie. the library allocates the
+memory and the user is not expected to `<tt/free()/' it) any module
+call to this function is likely to corrupt a pointer previously
+obtained by the application. The application programmer should either
+re-call such a `libc' function after a call to the <bf/Linux-PAM/
+library, or copy the structure contents to some safe area of memory
+before passing control to the <bf/Linux-PAM/ library.
+
+<p>
+Two important function classes that fall into this category are
+<tt>getpwnam(3)</tt> and <tt>syslog(3)</tt>.
+
+<sect1>Choice of a service name
+
+<p>
+When picking the <em/service-name/ that corresponds to the first entry
+in the <bf/Linux-PAM/ configuration file, the application programmer
+should <bf/avoid/ the temptation of choosing something related to
+<tt/argv[0]/. It is a trivial matter for any user to invoke any
+application on a system under a different name and this should not be
+permitted to cause a security breach.
+
+<p>
+To invoke some <tt/target/ application by another name, the user may
+symbolically link the target application with the desired name. To be
+precise all the user need do is,
+<tscreen>
+<verb>
+ln -s /target/application ./preferred_name
+</verb>
+</tscreen>
+and then <em/run/ <tt>./preferred_name</tt>
+
+<p>
+By studying the <bf/Linux-PAM/ configuration file(s), an attacker can
+choose the <tt/preferred_name/ to be that of a service enjoying
+minimal protection; for example a game which uses <bf/Linux-PAM/ to
+restrict access to certain hours of the day. If the service-name were
+to be linked to the filename under which the service was invoked, it
+is clear that the user is effectively in the position of dictating
+which authentication scheme the service uses. Needless to say, this
+is not a secure situation.
+
+<p>
+The conclusion is that the application developer should carefully
+define the service-name of an application. The safest thing is to make
+it a single hard-wired name.
+
+<sect1>The conversation function
+
+<p>
+Care should be taken to ensure that the <tt/conv()/ function is
+robust. Such a function is provided in the library <tt/libpam_misc/
+(see <ref id="libpam-misc-section" name="below">).
+
+<sect1>The identity of the user
+
+<p>
+The <bf/Linux-PAM/ modules will need to determine the identity of the
+user who requests a service, and the identity of the user who grants
+the service. These two users will seldom be the same. Indeed there
+is generally a third user identity to be considered, the new (assumed)
+identity of the user once the service is granted.
+
+<p>
+The need for keeping tabs on these identities is clearly an issue of
+security. One convention that is actively used by some modules is
+that the identity of the user requesting a service should be the
+current <tt/uid/ (userid) of the running process; the identity of the
+privilege granting user is the <tt/euid/ (effective userid) of the
+running process; the identity of the user, under whose name the
+service will be executed, is given by the contents of the
+<tt/PAM_USER/ <tt/pam_get_item(3)/.
+
+<p>
+For network-serving databases and other applications that provide
+their own security model (independent of the OS kernel) the above
+scheme is insufficient to identify the requesting user.
+
+<p>
+A more portable solution to storing the identity of the requesting
+user is to use the <tt/PAM_RUSER/ <tt/pam_get_item(3)/. The
+application should supply this value before attempting to authenticate
+the user with <tt/pam_authenticate()/. How well this name can be
+trusted will ultimately be at the discretion of the local
+administrator (who configures PAM for your application) and a selected
+module may attempt to override the value where it can obtain more
+reliable data. If an application is unable to determine the identity
+of the requesting entity/user, it should not call <tt/pam_set_item(3)/
+to set <tt/PAM_RUSER/.
+
+<p>
+In addition to the <tt/PAM_RUSER/ item, the application should supply
+the <tt/PAM_RHOST/ (<em/requesting host/) item. As a general rule, the
+following convention for its value can be assumed: <tt/&lt;unset&gt;/
+= unknown; <tt/localhost/ = invoked directly from the local system;
+<em/other.place.xyz/ = some component of the user's connection
+originates from this remote/requesting host. At present, PAM has no
+established convention for indicating whether the application supports
+a trusted path to communication from this host.
+
+<sect1>Sufficient resources
+
+<p>
+Care should be taken to ensure that the proper execution of an
+application is not compromised by a lack of system resources. If an
+application is unable to open sufficient files to perform its service,
+it should fail gracefully, or request additional resources.
+Specifically, the quantities manipulated by the <tt/setrlimit(2)/
+family of commands should be taken into consideration.
+
+<p>
+This is also true of conversation prompts. The application should not
+accept prompts of arbitrary length with out checking for resource
+allocation failure and dealing with such extreme conditions gracefully
+and in a mannor that preserves the PAM API. Such tolerance may be
+especially important when attempting to track a malicious adversary.
+
+<sect>A library of miscellaneous helper functions
+<label id="libpam-misc-section">
+
+<p>
+To aid the work of the application developer a library of
+miscellaneous functions is provided. It is called <tt/libpam_misc/,
+and contains functions for allocating memory (securely), a text based
+conversation function, and routines for enhancing the standard
+PAM-environment variable support.
+
+<sect1>Requirements
+
+<p>
+The functions, structures and macros, made available by this library
+can be defined by including <tt>&lt;security/pam_misc.h&gt;</tt>. It
+should be noted that this library is specific to <bf/Linux-PAM/ and is
+not referred to in the defining DCE-RFC (see <ref id="bibliography"
+name="the bibliography">) below.
+
+<sect1>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$
+ -->
+Chris Adams,
+Peter Allgeyer,
+Tim Baverstock,
+Tim Berger,
+Craig S. Bell,
+Derrick J. Brashear,
+Ben Buxton,
+Seth Chaiklin,
+Oliver Crow,
+Chris Dent,
+Marc Ewing,
+Cristian Gafton,
+Emmanuel Galanos,
+Brad M. Garcia,
+Eric Hester,
+Roger Hu,
+Eric Jacksch,
+Michael K. Johnson,
+David Kinchlea,
+Olaf Kirch,
+Marcin Korzonek,
+Stephen Langasek,
+Nicolai Langfeldt,
+Elliot Lee,
+Luke Kenneth Casson Leighton,
+Al Longyear,
+Ingo Luetkebohle,
+Marek Michalkiewicz,
+Robert Milkowski,
+Aleph One,
+Martin Pool,
+Sean Reifschneider,
+Jan Rekorajski,
+Erik Troan,
+Theodore Ts'o,
+Jeff Uphoff,
+Myles Uyema,
+Savochkin Andrey Vladimirovich,
+Ronald Wahl,
+David Wood,
+John Wilmes,
+Joseph S. D. Yao
+and
+Alex O. Yuriev.
+
+<p>
+Thanks are also due to Sun Microsystems, especially to Vipin Samar and
+Charlie Lai for their advice. At an early stage in the development of
+<bf/Linux-PAM/, Sun graciously made the documentation for their
+implementation of PAM available. This act greatly accelerated the
+development of <bf/Linux-PAM/.
+
+<sect>Bugs/omissions
+
+<p>
+This manual is hopelessly unfinished. Only a partial list of people is
+credited for all the good work they have done.
+
+<sect>Copyright information for this document
+
+<p>
+Copyright (c) Andrew G. Morgan 1996-9. 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$</tt>
+
+</article>
diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml
new file mode 100644
index 0000000..e76e3d7
--- /dev/null
+++ b/doc/pam_modules.sgml
@@ -0,0 +1,1476 @@
+<!doctype linuxdoc system>
+
+<!--
+
+ $Id$
+
+ Copyright (c) Andrew G. Morgan 1996-9. 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@linux.kernel.org</tt>
+<date>DRAFT v0.71 1999/11/8
+<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>
+The <tt/error_status/ may have been logically OR'd with either of the
+following two values:
+
+<p>
+<descrip>
+<tag><tt/PAM_DATA_REPLACE/</tag>
+ When a data item is being replaced (through a second call to
+<tt/pam_set_data()/) this mask is used. Otherwise, the call is assumed
+to be from <tt/pam_end()/.
+
+<tag><tt/PAM_DATA_SILENT/</tag>
+ Which indicates that the process would prefer to perform the
+<tt/cleanup()/ quietly. That is, discourages logging/messages to the
+user.
+
+</descrip>
+
+
+<sect2>
+Getting data
+
+<p>
+Synopsis:
+<tscreen>
+<verb>
+extern int pam_get_data(const pam_handle_t *pamh,
+ const char *module_data_name,
+ const void **data);
+</verb>
+</tscreen>
+
+<p>
+This function together with the previous one provides a method of
+associating module-specific data with the handle <tt/pamh/. A
+successful call to <tt/pam_get_data/ will result in <tt/*data/
+pointing to the data associated with the <tt/module_data_name/. Note,
+this data is <em/not/ a copy and should be treated as <em/constant/
+by the module.
+
+<p>
+Note, if there is an entry but it has the value <tt/NULL/, then this
+call returns <tt/PAM_NO_MODULE_DATA/.
+
+<sect2>
+Setting items
+
+<p>
+Synopsis:
+<tscreen>
+<verb>
+extern int pam_set_item(pam_handle_t *pamh
+ , int item_type
+ , const void *item
+ );
+</verb>
+</tscreen>
+
+<p>
+This function is used to (re)set the value of one of the
+<tt/item_type/s. The reader is urged to read the entry for this
+function in the <bf/Linux-PAM/ application developers' manual.
+
+<p>
+In addition to the <tt/item/s listed there, the module can set the
+following two <tt/item_type/s:
+
+<p>
+<descrip>
+<tag><tt/PAM_AUTHTOK/</tag>
+
+The authentication token (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.
+
+<p>
+The return value of this function is one of the following:
+<itemize>
+
+<item> <tt/PAM_SUCCESS/ - username obtained.
+
+<item> <tt/PAM_CONV_AGAIN/ - converstation did not complete and the
+caller is required to return control to the application, until such
+time as the application has completed the conversation process. A
+module calling <tt/pam_get_user()/ that obtains this return code,
+should return <tt/PAM_INCOMPLETE/ and be prepared (when invoked the
+next time) to recall <tt/pam_get_user()/ to fill in the user's name,
+and then pick up where it left off as if nothing had happened. This
+procedure is needed to support an event-driven application programming
+model.
+
+<item> <tt/PAM_CONV_ERR/ - the conversation method supplied by the
+application failed to obtain the username.
+
+</itemize>
+
+<sect2>Setting a Linux-PAM environment variable
+
+<p>
+Synopsis:
+<tscreen>
+<verb>
+extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
+</verb>
+</tscreen>
+
+<p>
+<bf/Linux-PAM/ (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 call each of the <em/stacked/
+authentication modules listed in the <bf/Linux-PAM/ configuration
+file. As directed by this file, one of more of the modules may fail
+causing the <tt/pam_...()/ call to return an error. It is desirable
+for there to also be a pause before the application continues. The
+principal reason for such a delay is security: a delay acts to
+discourage <em/brute force/ dictionary attacks primarily, but also
+helps hinder <em/timed/ (cf. covert channel) attacks.
+
+<p>
+The <tt/pam_fail_delay()/ function provides the mechanism by which an
+application or module can suggest a minimum delay (of <tt/micro_sec/
+<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time
+requested with this function. Should <tt/pam_authenticate()/ fail,
+the failing return to the application is delayed by an amount of time
+randomly distributed (by up to 25%) about this longest value.
+
+<p>
+Independent of success, the delay time is reset to its zero default
+value when <bf/Linux-PAM/ returns control to the application.
+
+</itemize>
+
+<sect>What is expected of a module
+
+<p>
+The module must supply a sub-set of the six functions listed
+below. Together they define the function of a <bf/Linux-PAM
+module/. Module developers are strongly urged to read the comments on
+security that follow this list.
+
+<sect1> Overview
+
+<p>
+The six module functions are grouped into four independent management
+groups. These groups are as follows: <em/authentication/,
+<em/account/, <em/session/ and <em/password/. To be properly defined,
+a module must define all functions within at least one of these
+groups. A single module may contain the necessary functions for
+<em/all/ four groups.
+
+<sect2> Functional independence
+
+<p>
+The independence of the four groups of service a module can offer
+means that the module should allow for the possibility that any one of
+these four services may legitimately be called in any order. Thus, the
+module writer should consider the appropriateness of performing a
+service without the prior success of some other part of the module.
+
+<p>
+As an informative example, consider the possibility that an
+application applies to change a user's authentication token, without
+having first requested that <bf/Linux-PAM/ authenticate the user. In
+some cases this may be deemed appropriate: when <tt/root/ wants to
+change the authentication token of some lesser user. In other cases it
+may not be appropriate: when <tt/joe/ maliciously wants to reset
+<tt/alice/'s password; or when anyone other than the user themself
+wishes to reset their <em/KERBEROS/ authentication token. A policy for
+this action should be defined by any reasonable authentication scheme,
+the module writer should consider this when implementing a given
+module.
+
+<sect2> Minimizing administration problems
+
+<p>
+To avoid system administration problems and the poor construction of a
+<tt>/etc/pam.conf</tt> file, the module developer may define all
+six of the following functions. For those functions that would not be
+called, the module should return <tt/PAM_SERVICE_ERR/ and write an
+appropriate message to the system log. When this action is deemed
+inappropriate, the function would simply return <tt/PAM_IGNORE/.
+
+<sect2> Arguments supplied to the module
+
+<p>
+The <tt/flags/ argument of each of the following functions can be
+logically OR'd with <tt/PAM_SILENT/, which is used to inform the
+module to not pass any <em/text/ (errors or warnings) to the
+application.
+
+<p>
+The <tt/argc/ and <tt/argv/ arguments are taken from the line
+appropriate to this module---that is, with the <em/service_name/
+matching that of the application---in the configuration file (see the
+<bf/Linux-PAM/ System Administrators' Guide). Together these two
+parameters provide the number of arguments and an array of pointers to
+the individual argument tokens. This will be familiar to C programmers
+as the ubiquitous method of passing command arguments to the function
+<tt/main()/. Note, however, that the first argument (<tt/argv[0]/) is
+a true argument and <bf/not/ the name of the module.
+
+<sect1> Authentication management
+
+<p>
+To be correctly initialized, <tt/PAM_SM_AUTH/ must be <tt/#define/'d
+prior to including <tt>&lt;security/pam_modules.h&gt;</tt>. This will
+ensure that the prototypes for static modules are properly declared.
+
+<p>
+<itemize>
+
+<item>
+<tt>PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
+int argc, const char **argv);</tt>
+
+<p>
+This function performs the task of authenticating the user.
+
+<p>
+The <tt/flags/ argument can be a logically OR'd with <tt/PAM_SILENT/
+and optionally take the following value:
+
+<p><descrip>
+<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag>
+ return <tt/PAM_AUTH_ERR/ if the database of authentication
+tokens for this authentication mechanism has a <tt/NULL/ entry for the
+user. Without this flag, such a <tt/NULL/ token will lead to a success
+without the user being prompted.
+</descrip>
+
+<p>
+Besides <tt/PAM_SUCCESS/ return values that can be sent by this
+function are one of the following:
+
+<descrip>
+
+<tag><tt/PAM_AUTH_ERR/</tag>
+ The user was not authenticated
+<tag><tt/PAM_CRED_INSUFFICIENT/</tag>
+ For some reason the application does not have sufficient
+credentials to authenticate the user.
+<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag>
+ The modules were not able to access the authentication
+information. This might be due to a network or hardware failure etc.
+<tag><tt/PAM_USER_UNKNOWN/</tag>
+ The supplied username is not known to the authentication
+service
+<tag><tt/PAM_MAXTRIES/</tag>
+ One or more of the authentication modules has reached its
+limit of tries authenticating the user. Do not try again.
+
+</descrip>
+
+<item>
+<tt>PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int
+argc, const char **argv);</tt>
+
+<p>
+This function performs the task of altering the credentials of the
+user with respect to the corresponding authorization
+scheme. Generally, an authentication module may have access to more
+information about a user than their authentication token. This
+function is used to make such information available to the
+application. It should only be called <em/after/ the user has been
+authenticated and after a session has been established.
+
+<p>
+Permitted flags, one of which, may be logically OR'd with
+<tt/PAM_SILENT/ are,
+
+<p><descrip>
+<tag><tt/PAM_ESTABLISH_CRED/</tag>
+ Set the credentials for the authentication service,
+<tag><tt/PAM_DELETE_CRED/</tag>
+ Delete the credentials associated with the authentication service,
+<tag><tt/PAM_REINITIALIZE_CRED/</tag>
+ Reinitialize the user credentials, and
+<tag><tt/PAM_REFRESH_CRED/</tag>
+ Extend the lifetime of the user credentials.
+</descrip>
+
+<p>
+Generally, the module should attempt to return the same error code as
+<tt/pam_sm_authenticate/ did. This will preserve the logic followed
+by libpam as it executes the stack of <em/authentication/ modules,
+when the application calls <tt/pam_authenticate()/ and
+<tt/pam_setcred()/. Failing to do this, will lead to much confudion
+on the part of the System administrator.
+
+<p>
+<bf>The following text is depreciated. Some thought needs to be given to
+how the credential setting modules are supposed to be stacked...</bf>
+
+<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/. .
+
+<tag><tt/expose_account/</tag>
+
+<p>
+In general the leakage of some information about user accounts is not
+a secure policy for modules to adopt. Sometimes information such as
+users names or home directories, or preferred shell, can be used to
+attack a user's account. In some circumstances, however, this sort of
+information is not deemed a threat: displaying a user's full name when
+asking them for a password in a secured environment could also be
+called being 'friendly'. The <tt/expose_account/ argument is a
+standard module argument to encourage a module to be less discrete
+about account information as it is deemed appropriate by the local
+administrator.
+
+</descrip>
+
+<sect>Programming notes
+
+<p>
+Here we collect some pointers for the module writer to bear in mind
+when writing/developing a <bf/Linux-PAM/ compatible module.
+
+<sect1>Security issues for module creation
+
+<sect2>Sufficient resources
+
+<p>
+Care should be taken to ensure that the proper execution of a module
+is not compromised by a lack of system resources. If a module is
+unable to open sufficient files to perform its task, it should fail
+gracefully, or request additional resources. Specifically, the
+quantities manipulated by the <tt/setrlimit(2)/ family of commands
+should be taken into consideration.
+
+<sect2>Who's who?
+
+<p>
+Generally, the module may wish to establish the identity of the user
+requesting a service. This may not be the same as the username
+returned by <tt/pam_get_user()/. Indeed, that is only going to be the
+name of the user under whose identity the service will be given. This
+is not necessarily the user that requests the service.
+
+<p>
+In other words, user X runs a program that is setuid-Y, it grants the
+user to have the permissions of Z. A specific example of this sort of
+service request is the <em/su/ program: user <tt/joe/ executes
+<em/su/ to become the user <em/jane/. In this situation X=<tt/joe/,
+Y=<tt/root/ and Z=<tt/jane/. Clearly, it is important that the module
+does not confuse these different users and grant an inappropriate
+level of privilege.
+
+<p>
+The following is the convention to be adhered to when juggling
+user-identities.
+
+<p>
+<itemize>
+<item>X, the identity of the user invoking the service request.
+This is the user identifier; returned by the function <tt/getuid(2)/.
+
+<item>Y, the privileged identity of the application used to grant the
+requested service. This is the <em/effective/ user identifier;
+returned by the function <tt/geteuid(2)/.
+
+<item>Z, the user under whose identity the service will be granted.
+This is the username returned by <tt/pam_get_user(2)/ and also stored
+in the <bf/Linux-PAM/ item, <tt/PAM_USER/.
+
+<item><bf/Linux-PAM/ has a place for an additional user identity that
+a module may care to make use of. This is the <tt/PAM_RUSER/ item.
+Generally, network sensitive modules/applications may wish to set/read
+this item to establish the identity of the user requesting a service
+from a remote location.
+
+</itemize>
+
+<p>
+Note, if a module wishes to modify the identity of either the <tt/uid/
+or <tt/euid/ of the running process, it should take care to restore
+the original values prior to returning control to the <bf/Linux-PAM/
+library.
+
+<sect2>Using the conversation function
+<p>
+Prior to calling the conversation function, the module should reset
+the contents of the pointer that will return the applications
+response. This is a good idea since the application may fail to fill
+the pointer and the module should be in a position to notice!
+
+<p>
+The module should be prepared for a failure from the conversation. The
+generic error would be <tt/PAM_CONV_ERR/, but anything other than
+<tt/PAM_SUCCESS/ should be treated as indicating failure.
+
+<sect2>Authentication tokens
+
+<p>
+To ensure that the authentication tokens are not left lying around the
+items, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/, are not available to
+the application: they are defined in
+<tt>&lt;security/pam_modules.h&gt;</tt>. This is ostensibly for
+security reasons, but a maliciously programmed application will always
+have access to all memory of the process, so it is only superficially
+enforced. As a general rule the module should overwrite
+authentication tokens as soon as they are no longer needed.
+Especially before <tt/free()/'ing them. The <bf/Linux-PAM/ library is
+required to do this when either of these authentication token items
+are (re)set.
+
+<p>
+Not to dwell too little on this concern; should the module store the
+authentication tokens either as (automatic) function variables or
+using <tt/pam_[gs]et_data()/ the associated memory should be
+over-written explicitly before it is released. In the case of the
+latter storage mechanism, the associated <tt/cleanup()/ function
+should explicitly overwrite the <tt/*data/ before <tt/free()/'ing it:
+for example,
+
+<tscreen>
+<verb>
+/*
+ * An example cleanup() function for releasing memory that was used to
+ * store a password.
+ */
+
+int cleanup(pam_handle_t *pamh, void *data, int error_status)
+{
+ char *xx;
+
+ if ((xx = data)) {
+ while (*xx)
+ *xx++ = '\0';
+ free(data);
+ }
+ return PAM_SUCCESS;
+}
+</verb>
+</tscreen>
+
+<sect1>Use of <tt/syslog(3)/
+
+<p>
+Only rarely should error information be directed to the user. Usually,
+this is to be limited to ``<em/sorry you cannot login now/'' type
+messages. Information concerning errors in the configuration file,
+<tt>/etc/pam.conf</tt>, or due to some system failure encountered by
+the module, should be written to <tt/syslog(3)/ with
+<em/facility-type/ <tt/LOG_AUTHPRIV/.
+
+<p>
+With a few exceptions, the level of logging is, at the discretion of
+the module developer. Here is the recommended usage of different
+logging levels:
+
+<p>
+<itemize>
+
+<item>
+As a general rule, errors encountered by a module should be logged at
+the <tt/LOG_ERR/ level. However, information regarding an unrecognized
+argument, passed to a module from an entry in the
+<tt>/etc/pam.conf</tt> file, is <bf/required/ to be logged at the
+<tt/LOG_ERR/ level.
+
+<item>
+Debugging information, as activated by the <tt/debug/ argument to the
+module in <tt>/etc/pam.conf</tt>, should be logged at the
+<tt/LOG_DEBUG/ level.
+
+<item>
+If a module discovers that its personal configuration file or some
+system file it uses for information is corrupted or somehow unusable,
+it should indicate this by logging messages at level, <tt/LOG_ALERT/.
+
+<item>
+Shortages of system resources, such as a failure to manipulate a file
+or <tt/malloc()/ failures should be logged at level <tt/LOG_CRIT/.
+
+<item>
+Authentication failures, associated with an incorrectly typed password
+should be logged at level, <tt/LOG_NOTICE/.
+
+</itemize>
+
+<sect1> Modules that require system libraries
+
+<p>
+Writing a module is much like writing an application. You have to
+provide the "conventional hooks" for it to work correctly, like
+<tt>pam_sm_authenticate()</tt> etc., which would correspond to the
+<tt/main()/ function in a normal function.
+
+<p>
+Typically, the author may want to link against some standard system
+libraries. As when one compiles a normal program, this can be done for
+modules too: you simply append the <tt>-l</tt><em>XXX</em> arguments
+for the desired libraries when you create the shared module object. To
+make sure a module is linked to the <tt>lib<em>whatever</em>.so</tt>
+library when it is <tt>dlopen()</tt>ed, try:
+<tscreen>
+<verb>
+% gcc -shared -Xlinker -x -o pam_module.so pam_module.o -lwhatever
+</verb>
+</tscreen>
+
+<sect1> Added requirements for <em/statically/ loaded modules.
+
+<!--
+ Copyright (C) Michael K. Johnson 1996.
+ Last modified: AGM 1996/5/31.
+ -->
+
+<p>
+Modules may be statically linked into libpam. This should be true of
+all the modules distributed with the basic <bf/Linux-PAM/
+distribution. To be statically linked, a module needs to export
+information about the functions it contains in a manner that does not
+clash with other modules.
+
+The extra code necessary to build a static module should be delimited
+with <tt/#ifdef PAM_STATIC/ and <tt/#endif/. The static code should do
+the following:
+<itemize>
+<item> Define a single structure, <tt/struct pam_module/, called
+<tt>_pam_<it>modname</it>_modstruct</tt>, where
+<tt><it>modname</it></tt> is the name of the module <bf/as used in the
+filesystem/ but without the leading directory name (generally
+<tt>/usr/lib/security/</tt> or the suffix (generally <tt/.so/).
+
+</itemize>
+
+<p>
+As a simple example, consider the following module code which defines
+a module that can be compiled to be <em/static/ or <em/dynamic/:
+
+<p>
+<tscreen>
+<verb>
+#include <stdio.h> /* for NULL define */
+
+#define PAM_SM_PASSWORD /* the only pam_sm_... function declared */
+#include <security/pam_modules.h>
+
+PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags,
+ int argc, const char **argv)
+{
+ return PAM_SUCCESS;
+}
+
+#ifdef PAM_STATIC /* for the case that this module is static */
+
+struct pam_module _pam_modname_modstruct = { /* static module data */
+ "pam_modname",
+ NULL,
+ NULL,
+ NULL,
+ NULL,
+ NULL,
+ pam_sm_chauthtok,
+};
+
+#endif /* end PAM_STATIC */
+</verb>
+</tscreen>
+
+<p>
+To be linked with <em/libpam/, staticly-linked modules must be built
+from within the <tt>Linux-PAM-X.YY/modules/</tt> subdirectory of the
+<bf/Linux-PAM/ source directory as part of a normal build of the
+<bf/Linux-PAM/ system.
+
+The <em/Makefile/, for the module in question, must execute the
+<tt/register_static/ shell script that is located in the
+<tt>Linux-PAM-X.YY/modules/</tt> subdirectory. This is to ensure that
+the module is properly registered with <em/libpam/.
+
+The <bf/two/ manditory arguments to <tt/register_static/ are the
+title, and the pathname of the object file containing the module's
+code. The pathname is specified relative to the
+<tt>Linux-PAM-X.YY/modules</tt> directory. The pathname may be an
+empty string---this is for the case that a single object file needs to
+register more than one <tt/struct pam_module/. In such a case, exactly
+one call to <tt/register_static/ must indicate the object file.
+
+<p>
+Here is an example; a line in the <em/Makefile/ might look like this:
+<tscreen>
+<verb>
+register:
+ifdef STATIC
+ (cd ..; ./register_static pam_modname pam_modname/pam_modname.o)
+endif
+</verb>
+</tscreen>
+
+For some further examples, see the <tt>modules</tt> subdirectory of
+the current <bf/Linux-PAM/ distribution.
+
+<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
+ $Id$
+ -->
+Chris Adams,
+Peter Allgeyer,
+Tim Baverstock,
+Tim Berger,
+Craig S. Bell,
+Derrick J. Brashear,
+Ben Buxton,
+Seth Chaiklin,
+Oliver Crow,
+Chris Dent,
+Marc Ewing,
+Cristian Gafton,
+Emmanuel Galanos,
+Brad M. Garcia,
+Eric Hester,
+Roger Hu,
+Eric Jacksch,
+Michael K. Johnson,
+David Kinchlea,
+Olaf Kirch,
+Marcin Korzonek,
+Stephen Langasek,
+Nicolai Langfeldt,
+Elliot Lee,
+Luke Kenneth Casson Leighton,
+Al Longyear,
+Ingo Luetkebohle,
+Marek Michalkiewicz,
+Robert Milkowski,
+Aleph One,
+Martin Pool,
+Sean Reifschneider,
+Jan Rekorajski,
+Erik Troan,
+Theodore Ts'o,
+Jeff Uphoff,
+Myles Uyema,
+Savochkin Andrey Vladimirovich,
+Ronald Wahl,
+David Wood,
+John Wilmes,
+Joseph S. D. Yao
+and
+Alex O. Yuriev.
+
+<p>
+Thanks are also due to Sun Microsystems, especially to Vipin Samar and
+Charlie Lai for their advice. At an early stage in the development of
+<bf/Linux-PAM/, Sun graciously made the documentation for their
+implementation of PAM available. This act greatly accelerated the
+development of <bf/Linux-PAM/.
+
+<sect>Bugs/omissions
+
+<p>
+Few PAM modules currently exist. Few PAM-aware applications exist.
+This document is hopelessly unfinished. Only a partial list of people is
+credited for all the good work they have done.
+
+<sect>Copyright information for this document
+
+<p>
+Copyright (c) Andrew G. Morgan 1996, 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$</tt>
+
+</article>
diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml
new file mode 100644
index 0000000..1c36940
--- /dev/null
+++ b/doc/pam_source.sgml
@@ -0,0 +1,1173 @@
+<!doctype linuxdoc system>
+
+<!--
+
+ $Id$
+
+ Copyright (c) Andrew G. Morgan 1996-9. 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.71 1999/11/8
+<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.
+
+<sect1>Getting started
+
+<p>
+The following text was contributed by Seth Chaiklin:
+<tscreen>
+<verb>
+To this point, we have described how PAM should work in an
+ideal world, in which all applications are coded properly.
+However, at the present time (October 1998), this is far
+from the case. Therefore, here are some practical considerations
+in trying to use PAM in your system.
+
+Why bother, is it really worth all the trouble?
+
+If you running Linux as a single user system, or in an
+environment where all the users are trusted, then there
+is no real advantage for using PAM.
+</verb>
+</tscreen>
+
+<p>
+<BF>Ed:</BF> there is actually an advantage since you can <em/dummy
+down/ the authentication to the point where you don't have
+any... Almost like Win95.
+<p>
+In a networked environment, it is clear that you need to think a
+little more about how users etc., are authenticated:]
+
+<p>
+<tscreen>
+<verb>
+If you are running Linux as a server, where several different
+services are being provided (e.g., WWW with areas restricted by
+password control, PPP), then there can be some real and interesting
+value for PAM. In particular, through the use of modules, PAM can
+enable a program to search through several different password
+databases, even if that program is not explicitly coded for
+that particular database. Here are some examples of the possibilities
+that this enables.
+
+ o Apache has a module that provides PAM services. Now
+ authentication
+ to use particular directories can be conducted by PAM, which
+ means that the range of modules that are available to PAM can
+ be used, including RADIUS, NIS, NCP (which means that Novell
+ password databases can be used).
+
+ o pppd has a PAMified version (available from RedHat) Now it is
+ possible to use a series of databases to authenticate ppp users.
+ In addition to the normal Linux-based password databases (such
+ as /etc/passwd and /etc/shadow), you can use PAM modules to
+ authenticate against Novell password databases or NT-based
+ password databases.
+
+ o The preceding two examples can be combined. Imagaine that the
+ persons in your office/department are already registered with a
+ username and password in a Novell or NT LAN. If you wanted to
+ use this database on your Linux server (for PPP access, for
+ web access, or even for normal shell access), you can use PAM
+ to authenticate against this existing database, rather than
+ maintain a separate database on both Linux and the LAN server.
+
+
+Can I use PAM for any program that requires authentication?
+
+Yes and no. Yes, if you have access to the source code, and can
+add the appropriate PAM functions. No, if you do not have access
+to the source code, and the binary does not have the PAM functions
+included.
+
+In other words, if a program is going to use PAM, then it has to
+have PAM functions explicitly coded into the program. If they
+are not, then it is not possible to use PAM.
+
+How can I tell whether a program has PAM coded into it or not?
+
+A quick-and-dirty (but not always reliable) method is to ldd
+<programname>
+If libpam and libpam_misc are not among the libraries that the program
+uses, then it is not going to work with PAM. However, it is possible
+that the libraries are included, but there are still problems, because
+the PAM coding in the program does not work as it should. So a
+more reliable method is to make the follow tests.
+
+In the /etc/pam.d directory, one needs to make a configuration file
+for the program that one wants to run. The exact name of the
+configuration
+file is hard-coded into the program. Usually, it is the same name as
+the
+program, but not always. For sake of illustration, let's assume that
+the program is named "pamprog" and the name of the configuration file
+is /etc/pam.d/pamprog.
+
+In the /etc/pam.d/pamprog but the following two lines:
+
+auth required pam_permit.so
+auth required pam_warn.so
+
+
+Now try to use pamprog. The first line in the configuration file
+says that all users are permitted. The second line will write a
+warning to your syslog file (or whether you syslog is writing
+
+messages). If this test succeeds, then you know that you have
+a program that can understand pam, and you can start the more
+interesting work of deciding how to stack modules in your
+/etc/pam.d/pamprog file.
+</verb>
+</tscreen>
+
+<sect>The Linux-PAM configuration file
+<label id="configuration">
+
+<p>
+<bf/Linux-PAM/ is designed to provide the system administrator with a
+great deal of flexibility in configuring the privilege granting
+applications of their system. The local configuration of those aspects
+of system security controlled by <tt/Linux-PAM/ is contained in one of
+two places: either the single system file, <tt>/etc/pam.conf</tt>; or
+the <tt>/etc/pam.d/</tt> directory. In this section we discuss the
+correct syntax of and generic options respected by entries to these
+files.
+
+<sect1>Configuration file syntax
+
+<p>
+The reader should note that the <bf/Linux-PAM/ specific tokens in this
+file are case <em/insensitive/. The module paths, however, are case
+sensitive since they indicate a file's <em/name/ and reflect the case
+dependence of typical Linux file-systems. The case-sensitivity of the
+arguments to any given module is defined for each module in turn.
+
+<p>
+In addition to the lines described below, there are two <em/special/
+characters provided for the convenience of the system administrator:
+comments are preceded by a `<tt/&num;/' and extend to the
+next end-of-line; also, module specification lines may be extended
+with a `<tt/&bsol;/' escaped newline.
+
+<p>
+A general configuration line of the <tt>/etc/pam.conf</tt> file has
+the following form:
+<tscreen>
+<verb>
+service-name module-type control-flag module-path 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. In general, <bf/Linux-PAM/
+ignores such a module when determining if the module stack will
+succeed or fail. However, in the absence of any definite successes or
+failures of previous or subsequent stacked modules this module will
+determine the nature of the response to the application. One example
+of this latter case, is when the other modules return something like
+<tt/PAM_IGNORE/.
+
+</itemize>
+
+<p>
+The more elaborate (newer) syntax is much more specific and gives the
+administrator a great deal of control over how the user is
+authenticated. This form of the control flag is delimeted with square
+brackets and consists of a series of <tt/value=action/ tokens:
+<tscreen>
+<verb>
+ [value1=action1 value2=action2 ...]
+</verb>
+</tscreen>
+
+<p>
+Here, <tt/valueI/ is one of the following <em/return values/:
+<tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/;
+<tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/;
+<tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/;
+<tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/;
+<tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/;
+<tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/;
+<tt/authtok_recover_err/; <tt/authtok_lock_busy/;
+<tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/;
+<tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and
+<tt/default/. The last of these (<tt/default/) can be used to set the
+action for those return values that are not explicitly defined.
+
+<p>
+The <tt/actionI/ can be a positive integer or one of the following
+tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and
+<tt/reset/. A positive integer, <tt/J/, when specified as the action,
+can be used to indicate that the next <em/J/ modules of the current
+type will be skipped. In this way, the administrator can develop a
+moderately sophisticated stack of modules with a number of different
+paths of execution. Which path is taken can be determined by the
+reactions of individual modules.
+
+<p>
+<itemize>
+<item><tt/ignore/ - when used with a stack of modules, the module's
+ return status will not contribute to the return code the application
+ obtains.
+<item><tt/bad/ - this action indicates that the return code should be
+ thought of as indicative of the module failing. If this module is
+ the first in the stack to fail, its status value will be used for
+ that of the whole stack.
+<item><tt/die/ - equivalent to <tt/bad/ with the side effect of
+ terminating the module stack and PAM immediately returning to the
+ application.
+<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this
+ return code should contribute directly to the return code of the full
+ stack of modules. In other words, if the former state of the stack
+ would lead to a return of <tt/PAM_SUCCESS/, the module's return code
+ will override this value. Note, if the former state of the stack
+ holds some value that is indicative of a modules failure, this 'ok'
+ value will not be used to override that value.
+<item><tt/done/ - equivalent to <tt/ok/ with the side effect of
+ terminating the module stack and PAM immediately returning to the
+ application.
+<item><tt/reset/ - clear all memory of the state of the module stack and
+ start again with the next stacked module.
+</itemize>
+
+<p>
+Just to get a feel for the power of this new syntax, here is a taste
+of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of
+client plug-in agents was introduced. This is something that makes it
+possible for PAM to support machine-machine authentication using the
+transport protocol inherent to the client/server application. With
+the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible
+for an application to be configured to support binary prompts with
+compliant clients, but to gracefully fall over into an alternative
+authentication mode for older, legacy, applications. Flexible eh?
+
+<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
+and higher) is to use both <tt>/etc/pam.d/</tt> and
+<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in
+<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>.
+
+The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of
+the <tt>/etc/pam.conf</tt> file and is made up of lines of the
+following form:
+<tscreen>
+<verb>
+module-type control-flag module-path arguments
+</verb>
+</tscreen>
+The only difference being that the <tt>service-name</tt> is not
+present. The service-name is of course the name of the given
+configuration file. For example, <tt>/etc/pam.d/login</tt> contains
+the configuration for the <em>login</em> service.
+
+<p>
+This method of configuration has a number of advantages over the
+single file approach. We list them here to assist the reader in
+deciding which scheme to adopt:
+
+<p>
+<itemize>
+
+<item>A lower chance of misconfiguring an application. There is one
+less field to mis-type when editing the configuration files by hand.
+
+<item>Easier to maintain. One application may be reconfigured without
+risk of interfering with other applications on the system.
+
+<item>It is possible to symbolically link different services
+configuration files to a single file. This makes it easier to keep the
+system policy for access consistent across different applications.
+(It should be noted, to conserve space, it is equally possible to
+<em>hard</em> link a number of configuration files. However, care
+should be taken when administering this arrangement as editing a hard
+linked file is likely to break the link.)
+
+<item>A potential for quicker configuration file parsing. Only the
+relevant entries are parsed when a service gets bound to its modules.
+
+<item>It is possible to limit read access to individual <bf/Linux-PAM/
+configuration files using the file protections of the filesystem.
+
+<item>Package management becomes simpler. Every time a new
+application is installed, it can be accompanied by an
+<tt>/etc/pam.d/</tt><em>xxxxxx</em> file.
+
+</itemize>
+
+<sect1>Generic optional arguments
+
+<p>
+The following are optional arguments which are likely to be understood
+by any module. Arguments (including these) are in general
+<em/optional/.
+
+<p>
+<descrip>
+<tag><tt/debug/</tag>
+
+Use the <tt/syslog(3)/ call to log debugging information to the system
+log files.
+
+<tag> <tt/no_warn/</tag>
+
+Instruct module to not give warning messages to the application.
+
+<tag> <tt/use_first_pass/</tag>
+
+The module should not prompt the user for a password. Instead, it
+should obtain the previously typed password (from the preceding
+<tt/auth/ module), and use that. If that doesn't work, then the user
+will not be authenticated. (This option is intended for <tt/auth/
+and <tt/password/ modules only).
+
+<tag> <tt/try_first_pass/</tag>
+
+The module should attempt authentication with the previously typed
+password (from the preceding <tt/auth/ module). If that doesn't work,
+then the user is prompted for a password. (This option is intended for
+<tt/auth/ modules only).
+
+<tag> <tt/use_mapped_pass/</tag>
+
+This argument is not currently supported by any of the modules in the
+<bf/Linux-PAM/ distribution because of possible consequences
+associated with U.S. encryption exporting restrictions. Within the
+U.S., module developers are, of course, free to implement it (as are
+developers in other countries). For compatibility reasons we describe
+its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref
+id="see-also-sec" name="bibliography"> for a pointer to this document.
+
+<p>
+The <tt/use_mapped_pass/ argument instructs the module to take the
+clear text authentication token entered by a previous module (that
+requests such a token) and use it to generate an encryption/decryption
+key with which to safely store/retrieve the authentication token
+required for this module. In this way the user can enter a single
+authentication token and be quietly authenticated by a number of
+stacked modules. Obviously a convenient feature that necessarily
+requires some reliably strong encryption to make it secure.
+This argument is intended for the <tt/auth/ and <tt/password/ module
+types only.
+
+<tag><tt/expose_account/</tag>
+
+<p>
+In general the leakage of some information about user accounts is not
+a secure policy for modules to adopt. Sometimes information such as
+users names or home directories, or preferred shell, can be used to
+attack a user's account. In some circumstances, however, this sort of
+information is not deemed a threat: displaying a user's full name when
+asking them for a password in a secured environment could also be
+called being 'friendly'. The <tt/expose_account/ argument is a
+standard module argument to encourage a module to be less discrete
+about account information as it is deemed appropriate by the local
+administrator.
+
+</descrip>
+
+<sect1>Example configuration file entries
+
+<p>
+In this section, we give some examples of entries that can be present
+in the <bf/Linux-PAM/ configuration file. As a first attempt at
+configuring your system you could do worse than to implement these.
+
+<sect2>Default policy
+
+<p>
+If a system is to be considered secure, it had better have a
+reasonably secure `<tt/OTHER/' entry. The following is a paranoid
+setting (which is not a bad place to start!):
+<tscreen>
+<verb>
+#
+# default; deny access
+#
+OTHER auth required /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.
+
+<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.
+
+<p>
+Here is a sample "other" configuration file. The <em/pam_deny/ module will
+deny access and the <em/pam_warn/ module will send a syslog message to
+<tt/auth.notice/:
+
+<p>
+<tscreen>
+<verb>
+#
+# The PAM configuration file for the `other' service
+#
+auth required pam_deny.so
+auth required pam_warn.so
+account required pam_deny.so
+account required pam_warn.so
+password required pam_deny.so
+password required pam_warn.so
+session required pam_deny.so
+session required pam_warn.so
+</verb>
+</tscreen>
+
+<sect>A reference guide for available modules
+
+<p>
+Here, we collect together some descriptions of the various modules
+available for <bf/Linux-PAM/. In general these modules should be
+freely available. Where this is not the case, it will be indicated.
+
+<p>
+Also please note the comments contained in the section <ref
+id="text-conventions" name="on text conventions above"> when copying
+the examples listed below.
+
+<!-- insert-file MODULES-SGML -->
+
+<sect>Files
+
+<p><descrip>
+
+<tag><tt>/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@linux.kernel.org)
+with many contributions from
+<!-- insert credits here -->
+<!--
+ an sgml list of people to credit for their contributions to Linux-PAM
+ $Id$
+ -->
+Chris Adams,
+Peter Allgeyer,
+Tim Baverstock,
+Tim Berger,
+Craig S. Bell,
+Derrick J. Brashear,
+Ben Buxton,
+Seth Chaiklin,
+Oliver Crow,
+Chris Dent,
+Marc Ewing,
+Cristian Gafton,
+Emmanuel Galanos,
+Brad M. Garcia,
+Eric Hester,
+Roger Hu,
+Eric Jacksch,
+Michael K. Johnson,
+David Kinchlea,
+Olaf Kirch,
+Marcin Korzonek,
+Stephen Langasek,
+Nicolai Langfeldt,
+Elliot Lee,
+Luke Kenneth Casson Leighton,
+Al Longyear,
+Ingo Luetkebohle,
+Marek Michalkiewicz,
+Robert Milkowski,
+Aleph One,
+Martin Pool,
+Sean Reifschneider,
+Jan Rekorajski,
+Erik Troan,
+Theodore Ts'o,
+Jeff Uphoff,
+Myles Uyema,
+Savochkin Andrey Vladimirovich,
+Ronald Wahl,
+David Wood,
+John Wilmes,
+Joseph S. D. Yao
+and
+Alex O. Yuriev.
+
+<p>
+Thanks are also due to Sun Microsystems, especially to Vipin Samar and
+Charlie Lai for their advice. At an early stage in the development of
+<bf/Linux-PAM/, Sun graciously made the documentation for their
+implementation of PAM available. This act greatly accelerated the
+development of <bf/Linux-PAM/.
+
+<sect>Bugs/omissions
+
+<p>
+More PAM modules are being developed all the time. It is unlikely that
+this document will ever be truely up to date!
+
+<p>
+This manual is unfinished. Only a partial list of people is credited
+for all the good work they have done.
+
+<sect>Copyright information for this document
+
+<p>
+Copyright (c) Andrew G. Morgan 1996-9. All rights reserved.
+<newline>
+Email: <tt>&lt;morgan@linux.kernel.org&gt;</tt>
+
+<p>
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+<p>
+<itemize>
+
+<item>
+1. Redistributions of source code must retain the above copyright
+ notice, and the entire permission notice in its entirety,
+ including the disclaimer of warranties.
+
+<item>
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+<item>
+3. The name of the author may not be used to endorse or promote
+ products derived from this software without specific prior
+ written permission.
+
+</itemize>
+
+<p>
+<bf/Alternatively/, this product may be distributed under the terms of
+the GNU General Public License (GPL), in which case the provisions of
+the GNU GPL are required <bf/instead of/ the above restrictions.
+(This clause is necessary due to a potential bad interaction between
+the GNU GPL and the restrictions contained in a BSD-style copyright.)
+
+<p>
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
+
+<p>
+<tt>$Id$</tt>
+
+</article>
diff --git a/doc/ps/.cvsignore b/doc/ps/.cvsignore
new file mode 100644
index 0000000..8d83f2d
--- /dev/null
+++ b/doc/ps/.cvsignore
@@ -0,0 +1 @@
+pam*.ps \ No newline at end of file
diff --git a/doc/ps/README b/doc/ps/README
new file mode 100644
index 0000000..3122478
--- /dev/null
+++ b/doc/ps/README
@@ -0,0 +1,3 @@
+$Id$
+
+this is the directory for the postscipt documentation
diff --git a/doc/ps/missfont.log b/doc/ps/missfont.log
new file mode 100644
index 0000000..162c37a
--- /dev/null
+++ b/doc/ps/missfont.log
@@ -0,0 +1,36 @@
+MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmr10 600 600 1+0/600 ljfour
+MakeTeXPK cmtt10 600 600 1+0/600 ljfour
+MakeTeXPK cmss10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmti10 600 600 1+0/600 ljfour
+MakeTeXPK cmtt9 600 600 1+0/600 ljfour
+MakeTeXPK cmbx12 600 600 1+0/600 ljfour
+MakeTeXPK cmsy10 600 600 1+0/600 ljfour
+MakeTeXPK cmmi10 600 600 1+0/600 ljfour
+MakeTeXPK cmti9 600 600 1+0/600 ljfour
+MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmr10 600 600 1+0/600 ljfour
+MakeTeXPK cmtt10 600 600 1+0/600 ljfour
+MakeTeXPK cmss10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmbx12 600 600 1+0/600 ljfour
+MakeTeXPK cmtt9 600 600 1+0/600 ljfour
+MakeTeXPK cmti10 600 600 1+0/600 ljfour
+MakeTeXPK cmmi10 600 600 1+0/600 ljfour
+MakeTeXPK cmsy10 600 600 1+0/600 ljfour
+MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmr10 600 600 1+0/600 ljfour
+MakeTeXPK cmtt10 600 600 1+0/600 ljfour
+MakeTeXPK cmss10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour
+MakeTeXPK cmti10 600 600 1+0/600 ljfour
+MakeTeXPK cmbx12 600 600 1+0/600 ljfour
+MakeTeXPK cmtt9 600 600 1+0/600 ljfour
+MakeTeXPK cmtt12 600 600 1+0/600 ljfour
+MakeTeXPK cmti12 600 600 1+0/600 ljfour
+MakeTeXPK cmsy10 600 600 1+0/600 ljfour
+MakeTeXPK cmmi10 600 600 1+0/600 ljfour
diff --git a/doc/specs/.cvsignore b/doc/specs/.cvsignore
new file mode 100644
index 0000000..d564ba7
--- /dev/null
+++ b/doc/specs/.cvsignore
@@ -0,0 +1 @@
+draft-morgan-pam-*.txt
diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw
new file mode 100644
index 0000000..46db001
--- /dev/null
+++ b/doc/specs/draft-morgan-pam.raw
@@ -0,0 +1,702 @@
+PAM working group ## A.G. Morgan
+Internet Draft: ## October 6, 1999
+Document: draft-morgan-pam-07.txt ##
+Expires: June 13, 2000 ##
+Obsoletes: draft-morgan-pam-06.txt##
+
+## Pluggable Authentication Modules ##
+
+#$ Status of this memo
+
+This document is an draft specification. The latest version of this
+draft may be obtained from here:
+
+ http://linux.kernel.org/pub/linux/libs/pam/pre/doc/
+
+As
+
+ Linux-PAM-'version'-docs.tar.gz
+
+It is also contained in the Linux-PAM tar ball.
+
+#$ Abstract
+
+This document is concerned with the definition of a general
+infrastructure for module based authentication. The infrastructure is
+named Pluggable Authentication Modules (PAM for short).
+
+#$ Introduction
+
+Computers are tools. They provide services to people and other
+computers (collectively we shall call these _users_ entities). In
+order to provide convenient, reliable and individual service to
+different entities, it is common for entities to be labelled. Having
+defined a label as referring to a some specific entity, the label is
+used for the purpose of protecting and allocating data resources.
+
+All modern operating systems have a notion of labelled entities and
+all modern operating systems face a common problem: how to
+authenticate the association of a predefined label with applicant
+entities.
+
+There are as many authentication methods as one might care to count.
+None of them are perfect and none of them are invulnerable. In
+general, any given authentication method becomes weaker over time. It
+is common then for new authentication methods to be developed in
+response to newly discovered weaknesses in the old authentication
+methods.
+
+The problem with inventing new authentication methods is the fact that
+old applications do not support them. This contributes to an inertia
+that discourages the overhaul of weakly protected systems. Another
+problem is that individuals (people) are frequently powerless to layer
+the protective authentication around their systems. They are forced
+to rely on single (lowest common denominator) authentication schemes
+even in situations where this is far from appropriate.
+
+PAM, as discussed in this document, is a generalization of the
+approach first introduced in [#$R#{OSF_RFC_PAM}]. In short, it is a
+general framework of interfaces that abstract the process of
+authentication. With PAM, a service provider can custom protect
+individual services to the level that they deem is appropriate.
+
+PAM has nothing explicit to say about transport layer encryption.
+Within the context of this document encryption and/or compression of
+data exchanges are application specific (strictly between client and
+server) and orthogonal to the process of authentication.
+
+#$ Definitions
+
+Here we pose the authentication problem as one of configuring defined
+interfaces between two entities.
+
+#$$#{players} Players in the authentication process
+
+PAM reserves the following words to specify unique entities in the
+authentication process:
+
+ applicant
+ the entity (user) initiating an application for service
+ [PAM associates the PAM_RUSER _item_ with this requesting user].
+
+ arbitrator
+ the entity (user) under whose identity the service application
+ is negotiated and with whose authority service is granted.
+
+ user
+ the entity (user) whose identity is being authenticated
+ [PAM associates the PAM_USER _item_ with this identity].
+
+ server
+ the application that provides service, or acts as an
+ authenticated gateway to the requested service. This
+ application is completely responsible for the server end of
+ the transport layer connecting the server to the client.
+ PAM makes no assumptions about how data is encapsulated for
+ exchanges between the server and the client, only that full
+ octet sequences can be freely exchanged without corruption.
+
+ client
+ application providing the direct/primary interface to
+ applicant. This application is completely responsible
+ for the client end of the transport layer connecting the
+ server to the client. PAM makes no assumptions about how data
+ is encapsulated for exchanges between the server and the
+ client, only that full octet sequences can be freely
+ exchanged without corruption.
+
+ module
+ authentication binary that provides server-side support for
+ some (arbitrary) authentication method.
+
+ agent
+ authentication binary that provides client-side support for
+ some (arbitrary) authentication method.
+
+Here is a diagram to help orient the reader:
+
+## +-------+ +--------+ ##
+## . . . . .| agent | .| module | ##
+## . +-------+ .+--------+ ##
+## V | . | ##
+## . | V | ##
+## +---------+ +-------+ . +------+ ##
+## | | |libpamc| . |libpam| ##
+## | | +-------+ . +------+ ##
+## |applicant| | . | ##
+## | | +--------+ +----------+ ##
+## | |---| client |-----------| server | ##
+## +---------+ +--------+ +----------+ ##
+
+Solid lines connecting the boxes represent two-way interaction. The
+dotted-directed lines indicate an optional connection beteween the
+plugin module (agent) and the server (applicant). In the case of the
+module, this represents the module invoking the 'conversation'
+callback function provided to libpam by the server application when it
+inititializes the libpam library. In the case of the agent, this may
+be some out-of-PAM API interaction (for example directly displaying a
+dialog box under X).
+
+#$$ Defined Data Types
+
+In this draft, we define two composite data types, the text string and
+the binary prompt. They are the data types used to communicate
+authentication requests and responses.
+
+#$$$#{text_string} text string
+
+The text string is a simple sequence of non-NUL (NUL = 0x00)
+octets. Terminated with a single NUL (0x00) octet. The character set
+employed in the octet sequence may be negotiated out of band, but
+defaults to utf-8.
+
+## --------------------------- ##
+## [ character data | NUL ] ##
+## [ octet sequence | 0x00 ] ##
+## --------------------------- ##
+
+Within the rest of this text, PAM text strings are delimited with a
+pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}.
+
+#$$$#{binary_prompt} binary prompt
+
+A binary prompt consists of a stream of octets arranged as follows:
+
+## ---------------------------------------- ##
+## [ u32 | u8 | (length-5 octets) ] ##
+## [ length | control | data ] ##
+## ---------------------------------------- ##
+
+That is, a 32-bit unsigned integer in network byte order, a single
+unsigned byte of control information and a sequence of octets of
+length (length-5). The composition of the _data_ is context dependent
+but is generally not a concern for either the server or the client. It
+is very much the concern of modules and agents.
+
+For purposes of interoperability, we define the following control
+characters as legal.
+
+## value symbol description ##
+## ------------------------------------------------- ##
+## 0x01 PAM_BPC_OK - continuation packet ##
+## 0x02 PAM_BPC_SELECT - initialization packet ##
+## 0x03 PAM_BPC_DONE - termination packet ##
+## 0x04 PAM_BPC_FAIL - unable to execute ##
+
+The following control characters are only legal for exchanges between
+an agent and a client (it is the responsibility of the client to
+enforce this rule in the face of a rogue server):
+
+## 0x41 PAM_BPC_GETENV - obtain client env.var ##
+## 0x42 PAM_BPC_PUTENV - set client env.var ##
+## 0x43 PAM_BPC_TEXT - display message ##
+## 0x44 PAM_BPC_ERROR - display error message ##
+## 0x45 PAM_BPC_PROMPT - echo'd text prompt ##
+## 0x46 PAM_BPC_PASS - non-echo'd text prompt##
+
+Note, length is always equal to the total length of the binary
+prompt and represented by a network ordered unsigned 32 bit integer.
+
+#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts
+
+Binary prompts of control type PAM_BPC_SELECT have a defined
+data part. It is composed of three elements:
+
+ {agent_id;'/';data}
+
+The agent_id is a sequence of characters satisfying the following
+regexp:
+
+ /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/
+
+and has a specific form for each independent agent.
+
+o Agent_ids that do not contain an at-sign (@) are reserved to be
+ assigned by IANA (Internet Assigned Numbers Authority). Names of
+ this format MUST NOT be used without first registering with IANA.
+ Registered names MUST NOT contain an at-sign (@).
+
+o Anyone can define additional agents by using names in the format
+ name@domainname, e.g. "ouragent@example.com". The part following
+ the at-sign MUST be a valid fully qualified internet domain name
+ [RFC-1034] controlled by the person or organization defining the
+ name. (Said another way, if you control the email address that
+ your agent has as an identifier, they you are entitled to use
+ this identifier.) It is up to each domain how it manages its local
+ namespace.
+
+The '/' character is a mandatory delimiter, indicating the end of the
+agent_id. The trailing data is of a format specific to the agent with
+the given agent_id.
+
+
+#$$ Special cases
+
+In a previous section (#{players}) we identified the most general
+selection of authentication participants. In the case of network
+authentication, it is straightforward to ascribe identities to the
+defined participants. However, there are also special (less general)
+cases that we recognize here.
+
+The primary authentication step, when a user is directly introduced
+into a computer system (log's on to a workstation) is a special case.
+In this situation, the client and the server are generally one
+application. Before authenticating such a user, the applicant is
+formally unknown: PAM_RUSER is NULL.
+
+Some client-server implementations (telnet for example) provide
+effective full tty connections. In these cases, the four simple text
+string prompting cases (see below) can be handled as in the primary
+login step. In other words, the server absorbs most of the overhead of
+propagating authentication messages. In these cases, there is special
+client/server support for handling binary prompts.
+
+#$ Defined interfaces for information flow
+
+Here, we discuss the information exchange interfaces between the
+players in the authentication process. It should be understood that
+the server side is responsible for driving the authentication of the
+applicant. Notably, every request received by the client from the
+server must be matched with a single response from the client to the
+server.
+
+#$$#{applicant_client} Applicant <-> client
+
+Once the client is invoked, requests to the applicant entity are
+initiated by the client application. General clients are able to make
+the following requests directly to an applicant:
+
+ echo text string
+ echo error text string
+ prompt with text string for echo'd text string input
+ prompt with text string for concealed text string input
+
+the nature of the interface provided by the client for the benefit of
+the applicant entity is client specific and not defined by PAM.
+
+#$$#{client_agent} Client <-> agent
+
+In general, authentication schemes require more modes of exchange than
+the four defined in the previous section (#{applicant_client}). This
+provides a role for client-loadable agents. The client and agent
+exchange binary-messages that can have one of the following forms:
+
+ client -> agent
+ binary prompt agent expecting binary prompt reply to client
+
+ agent -> client
+ binary prompt reply from agent to clients binary prompt
+
+Following the acceptance of a binary prompt by the agent, the agent
+may attempt to exchange information with the client before returning
+its binary prompt reply. Permitted exchanges are binary prompts of the
+following types:
+
+ agent -> client
+ set environment variable (A)
+ get environment variable (B)
+ echo text string (C)
+ echo error text string (D)
+ prompt for echo'd text string input (E)
+ prompt for concealed text string input (F)
+
+In response to these prompts, the client must legitimately respond
+with a corresponding binary prompt reply. We list a complete set of
+example exchanges, including each type of legitimate response (passes
+and a single fail):
+
+## Type | Agent request | Client response ##
+## --------------------------------------------------------------- ##
+## (A) | {13;PAM_BPC_PUTENV;"FOO=BAR"} | {5;PAM_BPC_OK;} ##
+## | {10;PAM_BPC_PUTENV;"FOO="} | {5;PAM_BPC_OK;} ##
+## | {9;PAM_BPC_PUTENV;"FOO"} (*) | {5;PAM_BPC_OK;} ##
+## | {9;PAM_BPC_PUTENV;"BAR"} (*) | {5;PAM_BPC_FAIL;} ##
+## --------------------------------------------------------------- ##
+## (B) | {10;PAM_BPC_GETENV;"TERM"} | {11;PAM_BPC_OK;"vt100"} ##
+## | {9;PAM_BPC_GETENV;"FOO"} | {5;PAM_BPC_FAIL;} ##
+## --------------------------------------------------------------- ##
+## (C) | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_OK;} ##
+## | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_FAIL;} ##
+## --------------------------------------------------------------- ##
+## (D) | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_OK;} ##
+## | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_FAIL;} ##
+## --------------------------------------------------------------- ##
+## (E) | {13;PAM_BPC_PROMPT;"login: "} | {9;PAM_BPC_OK;"joe"} ##
+## | {13;PAM_BPC_PROMPT;"login: "} | {6;PAM_BPC_OK;""} ##
+## | {13;PAM_BPC_PROMPT;"login: "} | {5;PAM_BPC_FAIL;} ##
+## --------------------------------------------------------------- ##
+## (F) | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"} ##
+## | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""} ##
+## | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;} ##
+
+(*) Used to attempt the removal of a pre-existing environment
+variable.
+
+#$$ Client <-> server
+
+Once the client has established a connection with the server (the
+nature of the transport protocol is not specified by PAM), the server
+is responsible for driving the authentication process.
+
+General servers can request the following from the client:
+
+ (to be forwarded by the client to the applicant)
+ echo text string
+ echo error text string
+ prompt for echo'd text string response
+ prompt for concealed text string response
+
+ (to be forwarded by the client to the appropriate agent)
+ binary prompt for a binary prompt response
+
+Client side agents are required to process binary prompts. The
+agents' binary prompt responses are returned to the server.
+
+#$$ Server <-> module
+
+Modules drive the authentication process. The server provides a
+conversation function with which it encapsulates module-generated
+requests and exchanges them with the client. Every message sent by a
+module should be acknowledged.
+
+General conversation functions can support the following five
+conversation requests:
+
+ echo text string
+ echo error string
+ prompt for echo'd text string response
+ prompt for concealed text string response
+ binary prompt for binary prompt response
+
+The server is responsible for redirecting these requests to the
+client.
+
+#$ C API for application interfaces (client and server)
+
+#$$ Applicant <-> client
+
+No API is defined for this interface. The interface is considered to
+be specific to the client application. Example applications include
+terminal login, (X)windows login, machine file transfer applications.
+
+All that is important is that the client application is able to
+present the applicant with textual output and to receive textual
+input from the applicant. The forms of textual exchange are listed
+in an earlier section (#{applicant_client}). Other methods of
+data input/output are better suited to being handled via an
+authentication agent.
+
+#$$ Client <-> agent
+
+The client makes use of a general API for communicating with
+agents. The client is not required to communicate directly with
+available agents, instead a layer of abstraction (in the form of a
+library: libpamc) takes care of loading and maintaining communication
+with all requested agents. This layer of abstraction will choose which
+agents to interact with based on the content of binary prompts it
+receives that have the control type PAM_BPC_SELECT.
+
+#$$$ Client <-> libpamc
+
+#$$$$ Compilation information
+
+The C-header file provided for client-agent abstraction is included
+with the following source line:
+
+ \#include <security/pam_client.h>
+
+The library providing the corresponding client-agent abstraction
+functions is, libpamc.
+
+ cc .... -lpamc
+
+#$$$$ Initializing libpamc
+
+The libpamc library is initialized with a call to the following
+function:
+
+ pamc_handle_t pamc_start(void);
+
+This function is responsible for configuring the library and
+registering the location of available agents. The location of the
+available agents on the system is implementation specific.
+
+pamc_start() function returns NULL on failure. Otherwise, the return
+value is a pointer to an opaque data type which provides a handle to
+the libpamc library. On systems where threading is available, the
+libpamc libraray is thread safe provided a single (pamc_handler_t *)
+is used by each thread.
+
+#$$$$ Client (Applicant) selection of agents
+
+For the purpose of applicant and client review of available agents,
+the following function is provided.
+
+ char **pamc_list_agents(pamc_handle_t pch);
+
+This returns a list of pointers to the agent_id's of the agents which
+are available on the system. The list is terminated by a NULL pointer.
+It is the clients responsibility to free this memory area by calling
+free() on each agent id and the block of agent_id pointers in the
+result.
+
+PAM represents a server-driven authentication model, so by default
+any available agent may be invoked in the authentication process.
+
+#$$$$$ Client demands agent
+
+If the client requires that a specific authentication agent is
+satisfied during the authentication process, then the client should
+call the following function, immediately after obtaining a
+pamc_handle_t from pamc_start().
+
+ int pamc_load(pamc_handle_t pch, const char *agent_id);
+
+agent_id is a PAM text string (see section #{agent_ids}) and is not
+suffixed with a '/' delimiter. The return value for this function is:
+
+ PAM_BPC_TRUE - agent located and loaded.
+ PAM_BPC_FALSE - agent is not available.
+
+Note, although the agent is loaded, no data is fed to it. The agent's
+opportunity to inform the client that it does not trust the server is
+when the agent is shutdown.
+
+#$$$$$ Client marks agent as unusable
+
+The applicant might prefer that a named agent is marked as not
+available. To do this, the client would invoke the following function
+immediately after obtaining a pamc_handle_t from pam_start().
+
+ int pamc_disable(pamc_handle_t pch, const char *agent_id);
+
+here agent_id is a PAM text string containing an agent_id (section
+#{agent_ids}).
+
+The return value for this function is:
+
+ PAM_BPC_TRUE - agent is disabled. This is the response
+ independent of whether the agent is locally
+ available.
+
+ PAM_BPC_FALSE - agent cannot be disabled (this may be because
+ it has already been invoked).
+
+#$$$$ Allocating and manipulating binary prompts
+
+All conversation between an client and an agent takes place with
+respect to binary prompts. A binary prompt (see section #{binary_prompt}), is
+obtained, resized and deleted via the following C-macro:
+
+ CREATION of a binary prompt with control X1 and data length Y1:
+
+ pamc_bp_t prompt = NULL;
+ PAM_BP_RENEW(&prompt, X1, Y1);
+
+ REPLACEMENT of a binary prompt with a control X2 and data length Y2:
+
+ PAM_BP_RENEW(&prompt, X2, Y2);
+
+ DELETION of a binary prompt (the referenced prompt is scrubbed):
+
+ PAM_BP_RENEW(&prompt, 0, 0);
+
+Note, the PAM_BP_RENEW macro always overwrites any prompt that you
+call it with, deleting and liberating the old contents in a secure
+fashion. Also note that PAM_BP_RENEW, when returning a prompt of data
+size Y1>0, will always append a '\0' byte to the end of the prompt (at
+data offset Y1). It is thus, by definition, acceptable to treat the
+data contents of a binary packet as a text string (see #{text_string}).
+
+ FILLING a binary prompt from a memory pointer U1 from offset O1 of
+ length L1:
+
+ PAM_BP_FILL(prompt, O1, L1, U1);
+
+ the CONTROL type for the packet can be obtained as follows:
+
+ control = PAM_PB_CONTROL(prompt);
+
+ the LENGTH of a data within the prompt (_excluding_ its header
+ information) can be obtained as follows:
+
+ length = PAM_BP_LENGTH(prompt);
+
+ the total SIZE of the prompt (_including_ its header information)
+ can be obtained as follows:
+
+ size = PAM_BP_SIZE(prompt);
+
+ EXTRACTING data from a binary prompt from offset O2 of length L2 to
+ a memory pointer U2:
+
+ PAM_BP_EXTRACT(prompt, O2, L2, U2);
+
+ If you require direct access to the raw prompt DATA, you should use
+ the following macro:
+
+ __u8 *raw_data = PAM_BP_DATA(prompt);
+
+#$$$$ Client<->agent conversations
+
+All exchanges of binary prompts with agents are handled with the
+single function:
+
+ int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p);
+
+The return value for pamc_converse(...) is PAM_BPC_TRUE when there is
+a response packet and PAM_BPC_FALSE when the client is unable to
+handle the request represented by the original prompt. In this latter
+case, *prompt_p is set to NULL.
+
+This function takes a binary prompt and returns a replacement binary
+prompt that is either a request from an agent to be acted upon by the
+client or the 'result' which should be forwarded to the server. In the
+former case, the following macro will return 1 (PAM_BPC_TRUE) and in
+all other cases, 0 (PAM_BPC_FALSE):
+
+ PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt)
+
+Note, all non-NULL binary prompts returned by pamc_converse(...), are
+terminated with a '\0', even when the full length of the prompt (as
+returned by the agent) does not contain this delimiter. This is a
+defined property of the PAM_BP_RENEW macro, and can be relied upon.
+
+Important security note: in certain implementations, agents are
+implemented by executable binaries, which are transparently loaded and
+managed by the PAM client library. To ensure there is never a leakage
+of elevated privilege to an unprivileged agent, the client application
+should go to some effort to lower its level of privilege. It remains
+the responsibility of the applicant and the client to ensure that it
+is not compromised by a rogue agent.
+
+#$$$$ Termination of agents
+
+When closing the authentication session and severing the connection
+between a client and a selection of agents, the following function is
+used:
+
+ int pamc_end(pamc_handle_t *pch);
+
+Following a call to pamc_end, the pamc_handle_t will be invalid.
+
+The return value for this function is one of the following:
+
+ PAM_BPC_TRUE - all invoked agents are content with
+ authentication (the server is _not_ judged
+ _un_trustworthy by any agent)
+
+ PAM_BPC_FALSE - one or more agents were unsatisfied at
+ being terminated. In general, the client
+ should terminate its connection to the
+ server and indicate to the applicant that
+ the server is untrusted.
+
+#$$$ libpamc <-> agents
+
+The agents are manipulated from within libpamc. Each agent is an
+executable in its own right. This permits the agent to have access to
+sensitive data not accessible directly from the client. The mode of
+communication between libpamc and an agent is through a pair of
+pipes. The agent reads binary prompts (section #{binary_prompt})
+through its standard input file descriptor and writes response (to the
+server) binary prompts and instruction binary prompts (instructions
+for the client) through its standard output file descriptor.
+
+#$$ Client <-> server
+
+This interface is concerned with the exchange of text and binary
+prompts between the client application and the server application. No
+API is provided for this as it is considered specific to the transport
+protocol shared by the client and the server.
+
+#$$ Server <-> modules
+
+The server makes use of a general API for communicating with
+modules. The client is not required to communicate directly with
+available modules. By abstracting the authentication interface, it
+becomes possible for the local administrator to make a run time
+decision about the authentication method adopted by the server.
+
+#$$$ Functions and definitions available to servers and modules
+
+[This section will document the following functions
+
+ pam_set_item()
+ pam_get_item()
+ pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)
+ pam_get_env(pam_handle_t *pamh, const char *varname)
+ pam_strerror(pam_handle_t *pamh, int pam_errno)
+]
+
+#$$$ Server <-> libpam
+
+[This section will document the following pam_ calls:
+
+ pam_start
+ pam_end
+ pam_authenticate (*)
+ pam_setcred
+ pam_acct_mgmt
+ pam_open_session
+ pam_close_session
+ pam_chauthtok (*)
+
+The asterisked functions may return PAM_INCOMPLETE. In such cases, the
+application should be aware that the conversation function was called
+and that it returned PAM_CONV_AGAIN to a module. The correct action
+for the application to take in response to receiving PAM_INCOMPLETE,
+is to acquire the replies so that the next time the conversation
+function is called it will be able to provide the desired
+responses. And then recall pam_authenticate (pam_chauthtok) with the
+same arguments. Libpam will arrange that the module stack is resumed
+from the module that returned before. This functionality is required
+for programs whose user interface is maintained by an event loop. ]
+
+#$$$ libpam <-> modules
+
+[This section will document the following pam_ and pam_sm_ calls:
+
+functions provided by libpam
+
+ pam_set_data
+ pam_get_data
+
+functions provided to libpam by each module
+
+ groups:
+ AUTHENTICATION
+ pam_sm_authenticate
+ pam_sm_setcred
+ ACCOUNT
+ pam_sm_acct_mgmt
+ SESSION
+ pam_sm_open_session
+ pam_sm_close_session
+ AUTHENTICATION TOKEN MANAGEMENT
+ pam_sm_chauthtok
+]
+
+#$ Security considerations
+
+This document is devoted to standardizing authentication
+infrastructure: everything in this document has implications for
+security.
+
+#$ Contact
+
+The email list for discussing issues related to this document is
+<pam-list@redhat.com>.
+
+#$ References
+
+[#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication
+ Modules (PAM)", October 1995
+
+#$ Author's Address
+
+Andrew G. Morgan
+Email: morgan@ftp.kernel.org
+
+## $Id$ ##
+
diff --git a/doc/specs/formatter/.cvsignore b/doc/specs/formatter/.cvsignore
new file mode 100644
index 0000000..8af8c89
--- /dev/null
+++ b/doc/specs/formatter/.cvsignore
@@ -0,0 +1,3 @@
+lex.yy.c
+parse.tab.c
+padout
diff --git a/doc/specs/formatter/Makefile b/doc/specs/formatter/Makefile
new file mode 100644
index 0000000..d73258d
--- /dev/null
+++ b/doc/specs/formatter/Makefile
@@ -0,0 +1,16 @@
+LIBS=-lfl
+
+padout: parse.tab.o
+ $(CC) -o padout parse.tab.o $(LIBS)
+
+parse.tab.o: parse.tab.c lex.yy.c
+ $(CC) -c parse.tab.c
+
+parse.tab.c: parse.y
+ bison parse.y
+
+lex.yy.c: parse.lex
+ flex parse.lex
+
+clean:
+ rm -f parse.tab.o parse.tab.c lex.yy.c padout *~ core
diff --git a/doc/specs/formatter/parse.lex b/doc/specs/formatter/parse.lex
new file mode 100644
index 0000000..1d5c898
--- /dev/null
+++ b/doc/specs/formatter/parse.lex
@@ -0,0 +1,11 @@
+%%
+
+\#[\$]+[a-zA-Z]*(\=[0-9]+)? return NEW_COUNTER;
+\#\{[a-zA-Z][a-zA-Z0-9\_]*\} return LABEL;
+\# return NO_INDENT;
+\#\# return RIGHT;
+\\\# return HASH;
+[^\n] return CHAR;
+[\n] return NEWLINE;
+
+%%
diff --git a/doc/specs/formatter/parse.y b/doc/specs/formatter/parse.y
new file mode 100644
index 0000000..6da47d1
--- /dev/null
+++ b/doc/specs/formatter/parse.y
@@ -0,0 +1,293 @@
+
+%{
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define MAXLINE 1000
+#define INDENT_STRING " "
+#define PAPER_WIDTH 74
+
+ int indent=0;
+ int line=1;
+ char *last_label=NULL;
+
+ extern void yyerror(const char *x);
+ extern char *get_label(const char *label);
+ extern void set_label(const char *label, const char *target);
+ char *new_counter(const char *key);
+
+#include "lex.yy.c"
+
+%}
+
+%union {
+ int def;
+ char *string;
+}
+
+%token NEW_COUNTER LABEL HASH CHAR NEWLINE NO_INDENT RIGHT
+%type <string> stuff text
+
+%start doc
+
+%%
+
+doc:
+| doc NEWLINE {
+ printf("\n");
+ ++line;
+}
+| doc stuff NEWLINE {
+ if (strlen($2) > (PAPER_WIDTH-(indent ? strlen(INDENT_STRING):0))) {
+ yyerror("line too long");
+ }
+ printf("%s%s\n", indent ? INDENT_STRING:"", $2);
+ free($2);
+ indent = 1;
+ ++line;
+}
+| doc stuff RIGHT stuff NEWLINE {
+ char fixed[PAPER_WIDTH+1];
+ int len;
+
+ len = PAPER_WIDTH-(strlen($2)+strlen($4));
+
+ if (len >= 0) {
+ memset(fixed, ' ', len);
+ fixed[len] = '\0';
+ } else {
+ yyerror("line too wide");
+ fixed[0] = '\0';
+ }
+ printf("%s%s%s\n", $2, fixed, $4);
+ free($2);
+ free($4);
+ indent = 1;
+ ++line;
+}
+| doc stuff RIGHT stuff RIGHT stuff NEWLINE {
+ char fixed[PAPER_WIDTH+1];
+ int len, l;
+
+ len = PAPER_WIDTH-(strlen($2)+strlen($4));
+
+ if (len < 0) {
+ len = 0;
+ yyerror("line too wide");
+ }
+
+ l = len/2;
+ memset(fixed, ' ', l);
+ fixed[l] = '\0';
+ printf("%s%s%s", $2, fixed, $4);
+ free($2);
+ free($4);
+
+ l = (len+1)/2;
+ memset(fixed, ' ', l);
+ fixed[l] = '\0';
+ printf("%s%s\n", fixed, $6);
+ free($6);
+
+ indent = 1;
+ ++line;
+}
+| doc stuff RIGHT stuff RIGHT stuff NEWLINE {
+ char fixed[PAPER_WIDTH+1];
+ int len, l;
+
+ len = PAPER_WIDTH-(strlen($2)+strlen($4));
+
+ if (len < 0) {
+ len = 0;
+ yyerror("line too wide");
+ }
+
+ l = len/2;
+ memset(fixed, ' ', l);
+ fixed[l] = '\0';
+ printf("%s%s%s", $2, fixed, $4);
+ free($2);
+ free($4);
+
+ l = (len+1)/2;
+ memset(fixed, ' ', l);
+ fixed[l] = '\0';
+ printf("%s%s\n", fixed, $6);
+ free($6);
+
+ indent = 1;
+ ++line;
+}
+;
+
+stuff: {
+ $$ = strdup("");
+}
+| stuff text {
+ $$ = malloc(strlen($1)+strlen($2)+1);
+ sprintf($$,"%s%s", $1, $2);
+ free($1);
+ free($2);
+}
+;
+
+text: CHAR {
+ $$ = strdup(yytext);
+}
+| text CHAR {
+ $$ = malloc(strlen($1)+2);
+ sprintf($$,"%s%s", $1, yytext);
+ free($1);
+}
+| NO_INDENT {
+ $$ = strdup("");
+ indent = 0;
+}
+| HASH {
+ $$ = strdup("#");
+}
+| LABEL {
+ if (($$ = get_label(yytext)) == NULL) {
+ set_label(yytext, last_label);
+ $$ = strdup("");
+ }
+}
+| NEW_COUNTER {
+ $$ = new_counter(yytext);
+}
+;
+
+%%
+
+typedef struct node_s {
+ struct node_s *left, *right;
+ const char *key;
+ char *value;
+} *node_t;
+
+node_t label_root = NULL;
+node_t counter_root = NULL;
+
+const char *find_key(node_t root, const char *key)
+{
+ while (root) {
+ int cmp = strcmp(key, root->key);
+
+ if (cmp > 0) {
+ root = root->right;
+ } else if (cmp) {
+ root = root->left;
+ } else {
+ return root->value;
+ }
+ }
+ return NULL;
+}
+
+node_t set_key(node_t root, const char *key, const char *value)
+{
+ if (root) {
+ int cmp = strcmp(key, root->key);
+ if (cmp > 0) {
+ root->right = set_key(root->right, key, value);
+ } else if (cmp) {
+ root->left = set_key(root->left, key, value);
+ } else {
+ free(root->value);
+ root->value = strdup(value);
+ }
+ } else {
+ root = malloc(sizeof(struct node_s));
+ root->right = root->left = NULL;
+ root->key = strdup(key);
+ root->value = strdup(value);
+ }
+ return root;
+}
+
+void yyerror(const char *x)
+{
+ fprintf(stderr, "line %d: %s\n", line, x);
+}
+
+char *get_label(const char *label)
+{
+ const char *found = find_key(label_root, label);
+
+ if (found) {
+ return strdup(found);
+ }
+ return NULL;
+}
+
+void set_label(const char *label, const char *target)
+{
+ if (target == NULL) {
+ yyerror("no hanging value for label");
+ target = "<??>";
+ }
+ label_root = set_key(label_root, label, target);
+}
+
+char *new_counter(const char *key)
+{
+ int i=0, j, ndollars = 0;
+ const char *old;
+ char *new;
+
+ if (key[i++] != '#') {
+ yyerror("bad index");
+ return strdup("<???>");
+ }
+
+ while (key[i] == '$') {
+ ++ndollars;
+ ++i;
+ }
+
+ key += i;
+ old = find_key(counter_root, key);
+ new = malloc(20*ndollars);
+
+ if (old) {
+ for (j=0; ndollars > 1 && old[j]; ) {
+ if (old[j++] == '.' && --ndollars <= 0) {
+ break;
+ }
+ }
+ if (j) {
+ strncpy(new, old, j);
+ }
+ if (old[j]) {
+ i = atoi(old+j);
+ } else {
+ new[j++] = '.';
+ i = 0;
+ }
+ } else {
+ j=0;
+ while (--ndollars > 0) {
+ new[j++] = '0';
+ new[j++] = '.';
+ }
+ i = 0;
+ }
+ new[j] = '\0';
+ sprintf(new+j, "%d", ++i);
+
+ counter_root = set_key(counter_root, key, new);
+
+ if (last_label) {
+ free(last_label);
+ }
+ last_label = strdup(new);
+
+ return new;
+}
+
+main()
+{
+ yyparse();
+}
diff --git a/doc/specs/rfc86.0.txt b/doc/specs/rfc86.0.txt
new file mode 100644
index 0000000..6dd5e6e
--- /dev/null
+++ b/doc/specs/rfc86.0.txt
@@ -0,0 +1,1851 @@
+
+
+
+
+
+
+
+
+ Open Software Foundation V. Samar (SunSoft)
+ Request For Comments: 86.0 R. Schemers (SunSoft)
+ October 1995
+
+
+
+ UNIFIED LOGIN WITH
+ PLUGGABLE AUTHENTICATION MODULES (PAM)
+
+
+ 1. INTRODUCTION
+
+ Since low-level authentication mechanisms constantly evolve, it is
+ important to shield the high-level consumers of these mechanisms
+ (system-entry services and users) from such low-level changes. With
+ the Pluggable Authentication Module (PAM) framework, we can provide
+ pluggability for a variety of system-entry services -- not just
+ system authentication _per se_, but also for account, session and
+ password management. PAM's ability to _stack_ authentication modules
+ can be used to integrate `login' with different authentication
+ mechanisms such as RSA, DCE, and Kerberos, and thus unify login
+ mechanisms. The PAM framework can also provide easy integration of
+ smart cards into the system.
+
+ Modular design and pluggability have become important for users who
+ want ease of use. In the PC hardware arena, no one wants to set the
+ interrupt vector numbers or resolve the addressing conflict between
+ various devices. In the software arena, people also want to be able
+ to replace components easily for easy customization, maintenance, and
+ upgrades.
+
+ Authentication software deserves special attention because
+ authentication forms a very critical component of any secure computer
+ system. The authentication infrastructure and its components may
+ have to be modified or replaced either because some deficiencies have
+ been found in the current algorithms, or because sites want to
+ enforce a different security policy than what was provided by the
+ system vendor. The replacement and modification should be done in
+ such a way that the user is not affected by these changes.
+
+ The solution has to address not just how the applications use the new
+ authentication mechanisms in a generic fashion, but also how the user
+ will be authenticated to these mechanisms in a generic way. The
+ former is addressed by GSS-API [Linn 93], while this RFC addresses
+ the later; these two efforts are complementary to each other.
+
+ Since most system-entry services (for example, `login', `dtlogin',
+ `rlogin', `ftp', `rsh') may want to be independent of the specific
+ authentication mechanisms used by the machine, it is important that
+ there be a framework for _plugging_ in various mechanisms. This
+ requires that the system applications use a standard API to interact
+
+
+
+ Samar, Schemers Page 1
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ with the authentication services. If these system-entry services
+ remain independent of the actual mechanism used on that machine, the
+ system administrator can install suitable authentication modules
+ without requiring changes to these applications.
+
+ For any security system to be successful, it has to be easy to use.
+ In the case of authentication, the single most important ease-of-use
+ characteristic is that the user should not be required to learn about
+ various ways of authentication and remember multiple passwords.
+ Ideally, there should be one all-encompassing authentication system
+ where there is only one password, but for heterogeneous sites,
+ multiple authentication mechanisms have to co-exist. The problem of
+ integrating multiple authentication mechanisms such as Kerberos
+ [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor
+ 88], is also referred to as _integrated login_, or _unified login_
+ problem. Even if the user has to use multiple authentication
+ mechanisms, the user should not be forced to type multiple passwords.
+ Furthermore, the user should be able to use the new network identity
+ without taking any further actions. The key here is in modular
+ integration of the network authentication technologies with `login'
+ and other system-entry services.
+
+ In this RFC we discuss the architecture and design of pluggable
+ authentication modules. This design gives the capability to use
+ field-replaceable authentication modules along with unified login
+ capability. It thus provides for both _pluggability_ and _ease-of-
+ use_.
+
+ The RFC is organized as follows. We first motivate the need for a
+ generic way to authenticate the user by various system-entry services
+ within the operating system. We describe the goals and constraints
+ of the design. This leads to the architecture, description of the
+ interfaces, and _stacking_ of modules to get unified login
+ functionality. We then describe our experience with the design, and
+ end with a description of future work.
+
+
+ 2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS
+
+ An identification and authentication ("I&A") mechanism is used to
+ establish a user's identity the system (i.e., to a local machine's
+ operating system) and to other principals on the network. On a
+ typical UNIX system, there are various ports of entry into the
+ system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and
+ `telnet'. In all cases, the user has to be identified and
+ authenticated before granting appropriate access rights to the user.
+ The user identification and authentication for all these entry points
+ needs to be coordinated to ensure a secure system.
+
+ In most of the current UNIX systems, the login mechanism is based
+ upon verification of the password using the modified DES algorithm.
+
+
+
+ Samar, Schemers Page 2
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ The security of the implementation assumes that the password cannot
+ be guessed, and that the password does not go over the wire in the
+ clear. These assumptions, however, are not universally valid.
+ Various programs are now available freely on the Internet that can
+ run dictionary attack against the encrypted password. Further, some
+ of the network services (for example, `rlogin', `ftp', `telnet') send
+ the password over in clear, and there are "sniffer" programs freely
+ available to steal these passwords. The classical assumptions may be
+ acceptable on a trusted network, but in an open environment there is
+ a need to use more restrictive and stronger authentication
+ mechanisms. Examples of such mechanisms include Kerberos, RSA,
+ Diffie-Hellman, one-time password [Skey 94], and challenge-response
+ based smart card authentication systems. Since this list will
+ continue to evolve, it is important that the system-entry services do
+ not have hard-coded dependencies on any of these authentication
+ mechanisms.
+
+
+ 3. DESIGN GOALS
+
+ The goals of the PAM framework are as follows:
+
+ (a) The system administrator should be able to choose the default
+ authentication mechanism for the machine. This can range from
+ a simple password-based mechanism to a biometric or a smart
+ card based system.
+
+ (b) It should be possible to configure the user authentication
+ mechanism on a per application basis. For example, a site may
+ require S/Key password authentication for `telnet' access,
+ while allowing machine `login' sessions with just UNIX password
+ authentication.
+
+ (c) The framework should support the display requirements of the
+ applications. For example, for a graphical login session such
+ as `dtlogin', the user name and the password may have to be
+ entered in a new window. For networking system-entry
+ applications such as `ftp' and `telnet', the user name and
+ password has to be transmitted over the network to the client
+ machine.
+
+ (d) It should be possible to configure multiple authentication
+ protocols for each of those applications. For example, one may
+ want the users to get authenticated by both Kerberos and RSA
+ authentication systems.
+
+ (e) The system administrator should be able to _stack_ multiple
+ user authentication mechanisms such that the user is
+ authenticated with all authentication protocols without
+ retyping the password.
+
+
+
+
+ Samar, Schemers Page 3
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ (f) The architecture should allow for multiple passwords if
+ necessary to achieve higher security for users with specific
+ security requirements.
+
+ (g) The system-entry services should not be required to change when
+ the underlying mechanism changes. This can be very useful for
+ third-party developers because they often do not have the
+ source code for these services.
+
+ (h) The architecture should provide for a _pluggable_ model for
+ system authentication, as well as for other related tasks such
+ as password, account, and session management.
+
+ (i) For backward-compatibility reasons, the PAM API should support
+ the authentication requirements of the current system-entry
+ services.
+
+ There are certain issues that the PAM framework does not specifically
+ address:
+
+ (a) We focus only on providing a generic scheme through which users
+ use passwords to establish their identities to the machine.
+ Once the identity is established, how the identity is
+ communicated to other interested parties is outside the scope
+ of this design. There are efforts underway at IETF [Linn 93]
+ to develop a Generic Security Services Application Interface
+ (GSSAPI) that can be used by applications for secure and
+ authenticated communication without knowing the underlying
+ mechanism.
+
+ (b) The _single-signon_ problem of securely transferring the
+ identity of the caller to a remote site is not addressed. For
+ example, the problem of delegating credentials from the
+ `rlogin' client to the other machine without typing the
+ password is not addressed by our work. We also do not address
+ the problem of sending the passwords over the network in the
+ clear.
+
+ (c) We do not address the source of information obtained from the
+ "`getXbyY()'" family of calls (e.g., `getpwnam()'). Different
+ operating systems address this problem differently. For
+ example, Solaris uses the name service switch (NSS) to
+ determine the source of information for the "`getXbyY()'"
+ calls. It is expected that data which is stored in multiple
+ sources (such as passwd entries in NIS+ and the DCE registry)
+ is kept in sync using the appropriate commands (such as
+ `passwd_export').
+
+
+
+
+
+
+
+ Samar, Schemers Page 4
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ 4. OVERVIEW OF THE PAM FRAMEWORK
+
+ We propose that the goals listed above can be met through a framework
+ in which authentication modules can be _plugged_ independently of the
+ application. We call this the _Pluggable Authentication Modules_
+ (PAM) framework.
+
+ The core components of the PAM framework are the authentication
+ library API (the front end) and the authentication mechanism-specific
+ modules (the back end), connected through the Service Provider
+ Interface (SPI). Applications write to the PAM API, while the
+ authentication-system providers write to the PAM SPI and supply the
+ back end modules that are independent of the application.
+
+ ftp telnet login (Applications)
+ | | |
+ | | |
+ +--------+--------+
+ |
+ +-----+-----+
+ | PAM API | <-- pam.conf file
+ +-----+-----+
+ |
+ +--------+--------+
+ UNIX Kerberos Smart Cards (Mechanisms)
+
+ Figure 1: The Basic PAM Architecture
+
+ Figure 1 illustrates the relationship between the application, the
+ PAM library, and the authentication modules. Three applications
+ (`login', `telnet' and `ftp') are shown which use the PAM
+ authentication interfaces. When an application makes a call to the
+ PAM API, it loads the appropriate authentication module as determined
+ by the configuration file, `pam.conf'. The request is forwarded to
+ the underlying authentication module (for example, UNIX password,
+ Kerberos, smart cards) to perform the specified operation. The PAM
+ layer then returns the response from the authentication module to the
+ application.
+
+ PAM unifies system authentication and access control for the system,
+ and allows plugging of associated authentication modules through well
+ defined interfaces. The plugging can be defined through various
+ means, one of which uses a configuration file, such as the one in
+ Table 1. For each of the system applications, the file specifies the
+ authentication module that should be loaded. In the example below,
+ `login' uses the UNIX password module, while `ftp' and `telnet' use
+ the S/Key module.
+
+
+
+
+
+
+
+ Samar, Schemers Page 5
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ Table 1: A Simplified View of a Sample PAM Configuration File.
+
+ service module_path
+ ------- -----------
+ login pam_unix.so
+ ftp pam_skey.so
+ telnet pam_skey.so
+
+ Authentication configuration is only one aspect of this interface.
+ Other critical components include account management, session
+ management, and password management. For example, the `login'
+ program may want to verify not only the password but also whether the
+ account has aged or expired. Generic interfaces also need to be
+ provided so that the password can be changed according to the
+ requirements of the module. Furthermore, the application may want to
+ log information about the current session as determined by the
+ module.
+
+ Not all applications or services may need all of the above
+ components, and not each authentication module may need to provide
+ support for all of the interfaces. For example, while `login' may
+ need access to all four components, `su' may need access to just the
+ authentication component. Some applications may use some specific
+ authentication and password management modules but share the account
+ and session management modules with others.
+
+ This reasoning leads to a partitioning of the entire set of
+ interfaces into four areas of functionality: (1) authentication, (2)
+ account, (3) session, and (4) password. The concept of PAM was
+ extended to these functional areas by implementing each of them as a
+ separate pluggable module.
+
+ Breaking the functionality into four modules helps the module
+ providers because they can use the system-provided libraries for the
+ modules that they are not changing. For example, if a supplier wants
+ to provide a better version of Kerberos, they can just provide that
+ new authentication and password module, and reuse the existing ones
+ for account and session.
+
+ 4.1. Module Description
+
+ More details on specific API's are described in Appendix A. A brief
+ description of four modules follows:
+
+ (a) Authentication management: This set includes the
+ `pam_authenticate()' function to authenticate the user, and the
+ `pam_setcred()' interface to set, refresh or destroy the user
+ credentials.
+
+ (b) Account management: This set includes the `pam_acct_mgmt()'
+ function to check whether the authenticated user should be
+
+
+
+ Samar, Schemers Page 6
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ given access to his/her account. This function can implement
+ account expiration and access hour restrictions.
+
+ (c) Session management: This set includes the `pam_open_session()'
+ and `pam_close_session()' functions for session management and
+ accounting. For example, the system may want to store the
+ total time for the session.
+
+ (d) Password management: This set includes a function,
+ `pam_chauthtok()', to change the password.
+
+
+ 5. FRAMEWORK INTERFACES
+
+ The PAM framework further provides a set of administrative interfaces
+ to support the above modules and to provide for application-module
+ communication. There is no corresponding service provider interface
+ (SPI) for such functions.
+
+ 5.1. Administrative Interfaces
+
+ Each set of PAM transactions starts with `pam_start()' and ends with
+ the `pam_end()' function. The interfaces `pam_get_item()' and
+ `pam_set_item()' are used to read and write the state information
+ associated with the PAM transaction.
+
+ If there is any error with any of the PAM interfaces, the error
+ message can be printed with `pam_strerror()'.
+
+ 5.2. Application-Module Communication
+
+ During application initialization, certain data such as the user name
+ is saved in the PAM framework layer through `pam_start()' so that it
+ can be used by the underlying modules. The application can also pass
+ opaque data to the module which the modules will pass back while
+ communicating with the user.
+
+ 5.3. User-Module Communication
+
+ The `pam_start()' function also passes conversation function that has
+ to be used by the underlying modules to read and write module
+ specific authentication information. For example, these functions
+ can be used to prompt the user for the password in a way determined
+ by the application. PAM can thus be used by graphical, non-
+ graphical, or networked applications.
+
+
+
+
+
+
+
+
+
+ Samar, Schemers Page 7
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ 5.4. Inter-Module Communication
+
+ Though the modules are independent, they can share certain common
+ information about the authentication session such as user name,
+ service name, password, and conversation function through the
+ `pam_get_item()' and `pam_set_item()' interfaces. These API's can
+ also be used by the application to change the state information after
+ having called `pam_start()' once.
+
+ 5.5. Module State Information
+
+ The PAM service modules may want to keep certain module-specific
+ state information about the session. The interfaces `pam_get_data()'
+ and `pam_set_data()' can be used by the service modules to access and
+ update module-specific information as needed from the PAM handle.
+ The modules can also attach a cleanup function with the data. The
+ cleanup function is executed when `pam_end()' is called to indicate
+ the end of the current authentication activity.
+
+ Since the PAM modules are loaded upon demand, there is no direct
+ module initialization support in the PAM framework. If there are
+ certain initialization tasks that the PAM service modules have to do,
+ they should be done upon the first invocation. However, if there are
+ certain clean-up tasks to be done when the authentication session
+ ends, the modules should use `pam_set_data()' to specify the clean-up
+ functions, which would be called when `pam_end()' is called by the
+ application.
+
+
+ 6. MODULE CONFIGURATION MANAGEMENT
+
+ Table 2 shows an example of a configuration file `pam.conf' with
+ support for authentication, session, account, and password management
+ modules. `login' has three entries: one each for authentication
+ processing, session management and account management. Each entry
+ specifies the module name that should be loaded for the given module
+ type. In this example, the `ftp' service uses the authentication and
+ session modules. Note that all services here share the same session
+ management module, while having different authentication modules.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Samar, Schemers Page 8
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ Table 2: Configuration File (pam.conf) with Different Modules
+ and Control Flow
+
+ service module_type control_flag module_path options
+ ------- ----------- ------------ ----------- -------
+ login auth required pam_unix_auth.so nowarn
+ login session required pam_unix_session.so
+ login account required pam_unix_account.so
+ ftp auth required pam_skey_auth.so debug
+ ftp session required pam_unix_session.so
+ telnet session required pam_unix_session.so
+ login password required pam_unix_passwd.so
+ passwd password required pam_unix_passwd.so
+ OTHER auth required pam_unix_auth.so
+ OTHER session required pam_unix_session.so
+ OTHER account required pam_unix_account.so
+
+ The first field, _service_, denotes the service (for example,
+ `login', `passwd', `rlogin'). The name `OTHER' indicates the module
+ used by all other applications that have not been specified in this
+ file. This name can also be used if all services have the same
+ requirements. In the example, since all the services use the same
+ session module, we could have replaced those lines with a single
+ `OTHER' line.
+
+ The second field, _module_type_, indicates the type of the PAM
+ functional module. It can be one of `auth', `account', `session', or
+ `password' modules.
+
+ The third field, _control_flag_ determines the behavior of stacking
+ multiple modules by specifying whether any particular module is
+ _required_, _sufficient_, or _optional_. The next section describes
+ stacking in more detail.
+
+ The fourth field, _module_path_, specifies the location of the
+ module. The PAM framework loads this module upon demand to invoke
+ the required function.
+
+ The fifth field, _options_, is used by the PAM framework layer to
+ pass module specific options to the modules. It is up to the module
+ to parse and interpret the options. This field can be used by the
+ modules to turn on debugging or to pass any module specific
+ parameters such as a timeout value. It is also used to support
+ unified login as described below. The options field can be used by
+ the system administrator to fine-tune the PAM modules.
+
+ If any of the fields are invalid, or if a module is not found, that
+ line is ignored and the error is logged as a critical error via
+ `syslog(3)'. If no entries are found for the given module type, then
+ the PAM framework returns an error to the application.
+
+
+
+
+ Samar, Schemers Page 9
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ 7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING
+
+ In the world of heterogeneous systems, the system administrator often
+ has to deal with the problem of integrating multiple authentication
+ mechanisms. The user is often required to know about the
+ authentication command of the new authentication module (for example,
+ `kinit', `dce_login') after logging into the system. This is not
+ user-friendly because it forces people to remember to type the new
+ command and enter the new password. This functionality should be
+ invisible instead of burdening the user with it.
+
+ There are two problems to be addressed here:
+
+ (a) Supporting multiple authentication mechanisms.
+
+ (b) Providing unified login in the presence of multiple mechanisms.
+
+ In the previous section, we described how one could replace the
+ default authentication module with any other module of choice. Now
+ we demonstrate how the same model can be extended to provide support
+ for multiple modules.
+
+ 7.1. Design for Stacked Modules
+
+ One possibility was to provide hard-coded rules in `login' or other
+ applications requiring authentication services [Adamson 95]. But
+ this becomes very specific to the particular combination of
+ authentication protocols, and also requires the source code of the
+ application. Digital's Security Integration Architecture [SIA 95]
+ addresses this problem by specifying the same list of authentication
+ modules for all applications. Since requirements for various
+ applications can vary, it is essential that the configuration be on a
+ per-application basis.
+
+ To support multiple authentication mechanisms, the PAM framework was
+ extended to support _stacking_. When any API is called, the back
+ ends for the stacked modules are invoked in the order listed, and the
+ result returned to the caller. In Figure 2, the authentication
+ service of `login' is stacked and the user is authenticated by UNIX,
+ Kerberos, and RSA authentication mechanisms. Note that in this
+ example, there is no stacking for session or account management
+ modules.
+
+
+
+
+
+
+
+
+
+
+
+
+ Samar, Schemers Page 10
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ login
+ |
+ +--------+--------+
+ | | |
+ session auth account
+ | | |
+ +--+--+ +--+--+ +--+--+
+ | PAM | | PAM | | PAM |
+ +--+--+ +--+--+ +--+--+
+ | | |
+ UNIX UNIX UNIX
+ session auth account
+ |
+ Kerberos
+ auth
+ |
+ RSA
+ auth
+
+ Figure 2: Stacking With the PAM Architecture
+
+ Stacking is specified through additional entries in the configuration
+ file shown earlier. As shown in Table 2, for each application (such
+ as `login') the configuration file can specify multiple mechanisms
+ that have to be invoked in the specified order. When mechanisms
+ fail, the _control_flag_ decides which error should be returned to
+ the application. Since the user should not know which authentication
+ module failed when a bad password was typed, the PAM framework
+ continues to call other authentication modules on the stack even on
+ failure. The semantics of the control flag are as follows:
+
+ (a) `required': With this flag, the module failure results in the
+ PAM framework returning the error to the caller _after_
+ executing all other modules on the stack. For the function to
+ be able to return success to the application all `required'
+ modules have to report success. This flag is normally set when
+ authentication by this module is a _must_.
+
+ (b) `optional': With this flag, the PAM framework ignores the
+ module failure and continues with the processing of the next
+ module in sequence. This flag is used when the user is allowed
+ to login even if that particular module has failed.
+
+ (c) `sufficient': With this flag, if the module succeeds the PAM
+ framework returns success to the application immediately
+ without trying any other modules. For failure cases, the
+ _sufficient_ modules are treated as `optional'.
+
+ Table 3 shows a sample configuration file that stacks the `login'
+ command. Here the user is authenticated by UNIX, Kerberos, and RSA
+ authentication services. The `required' key word for _control_flag_
+
+
+
+ Samar, Schemers Page 11
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ enforces that the user is allowed to login only if he/she is
+ authenticated by _both_ UNIX and Kerberos services. RSA
+ authentication is optional by virtue of the `optional' key word in
+ the _control_flag_ field. The user can still log in even if RSA
+ authentication fails.
+
+ Table 3: PAM Configuration File with Support for Stacking
+
+ service module_type control_flag module_path options
+ ------- ----------- ------------ ----------- -------
+ login auth required pam_unix.so debug
+ login auth required pam_kerb.so use_mapped_pass
+ login auth optional pam_rsa.so use_first_pass
+
+ Table 4 illustrates the use of the sufficient flag for the `rlogin'
+ service. The Berkeley `rlogin' protocol specifies that if the remote
+ host is trusted (as specified in the `/etc/hosts.equiv' file or in
+ the `.rhosts' file in the home directory of the user), then the
+ `rlogin' daemon should not require the user to type the password. If
+ this is not the case, then the user is required to type the password.
+ Instead of hard coding this policy in the `rlogin' daemon, this can
+ be expressed with the `pam.conf' file in Table 4. The PAM module
+ `pam_rhosts_auth.so.1' implements the `.rhosts' policy described
+ above. If a site administrator wants to enable remote login with
+ only passwords, then the first line should be deleted.
+
+ Table 4: PAM Configuration File for the rlogin service
+
+ service module_type control_flag module_path options
+ ------- ----------- ------------ ----------- -------
+ rlogin auth sufficient pam_rhosts_auth.so
+ rlogin auth required pam_unix.so
+
+ 7.2. Password-Mapping
+
+ Multiple authentication mechanisms on a machine can lead to multiple
+ passwords that users have to remember. One attractive solution from
+ the ease-of-use viewpoint is to use the same password for all
+ mechanisms. This, however, can also weaken the security because if
+ that password were to be compromised in any of the multiple
+ mechanisms, all mechanisms would be compromised at the same time.
+ Furthermore, different authentication mechanisms may have their own
+ distinctive password requirements in regards to its length, allowed
+ characters, time interval between updates, aging, locking, and so
+ forth. These requirements make it problematic to use the same
+ password for multiple authentication mechanisms.
+
+ The solution we propose, while not precluding use of the same
+ password for every mechanism, allows for a different password for
+ each mechanism through what we call _password-mapping_. This
+ basically means using the user's _primary_ password to encrypt the
+
+
+
+ Samar, Schemers Page 12
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ user's other (_secondary_) passwords, and storing these encrypted
+ passwords in a place where they are available to the user. Once the
+ primary password is verified, the authentication modules would obtain
+ the other passwords for their own mechanisms by decrypting the
+ mechanism-specific encrypted password with the primary password, and
+ passing it to the authentication service. The security of this
+ design for password-mapping assumes that the primary password is the
+ user's strongest password, in terms of its unguessability (length,
+ type and mix of characters used, etc.).
+
+ If there is any error in password-mapping, or if the mapping does not
+ exist, the user will be prompted for the password by each
+ authentication module.
+
+ To support password-mapping, the PAM framework saves the primary
+ password and provides it to stacked authentication modules. The
+ password is cleared out before the `pam_authenticate' function
+ returns.
+
+ How the password is encrypted depends completely on the module
+ implementation. The encrypted secondary password (also called a
+ "mapped password") can be stored in a trusted or untrusted place,
+ such as a smart card, a local file, or a directory service. If the
+ encrypted passwords are stored in an untrusted publicly accessible
+ place, this does provide an intruder with opportunities for potential
+ dictionary attack.
+
+ Though password-mapping is voluntary, it is recommended that all
+ module providers add support for the following four mapping options:
+
+ (a) `use_first_pass': Use the same password used by the first
+ mechanism that asked for a password. The module should not ask
+ for the password if the user cannot be authenticated by the
+ first password. This option is normally used when the system
+ administrator wants to enforce the same password across
+ multiple modules.
+
+ (b) `try_first_pass': This is the same as `use_first_pass', except
+ that if the primary password is not valid, it should prompt the
+ user for the password.
+
+ (c) `use_mapped_pass': Use the password-mapping scheme to get the
+ actual password for this module. One possible implementation
+ is to get the mapped-password using the XFN API [XFN 94], and
+ decrypt it with the primary password to get the module-specific
+ password. The module should not ask for the password if the
+ user cannot be authenticated by the first password. The XFN
+ API allows user-defined attributes (such as _mapped-password_)
+ to be stored in the _user-context_. Using the XFN API is
+ particularly attractive because support for the XFN may be
+ found on many systems in the future.
+
+
+
+ Samar, Schemers Page 13
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ (d) `try_mapped_pass': This is the same as `use_mapped_pass',
+ except that if the primary password is not valid, it should
+ prompt the user for the password.
+
+ When passwords get updated, the PAM framework stores both the old as
+ well as the new password to be able to inform other dependent
+ authentication modules about the change. Other modules can use this
+ information to update the encrypted password without forcing the user
+ to type the sequence of passwords again. The PAM framework clears
+ out the passwords before returning to the application.
+
+ Table 3 illustrates how the same password can be used by `login' for
+ authenticating to the standard UNIX login, Kerberos and RSA services.
+ Once the user has been authenticated to the primary authentication
+ service (UNIX `login' in this example) with the primary password, the
+ option `use_mapped_pass' indicates to the Kerberos module that it
+ should use the primary password to decrypt the stored Kerberos
+ password and then use the Kerberos password to get the ticket for the
+ ticket-granting-service. After that succeeds, the option
+ `use_first_pass' indicates to the RSA module that instead of
+ prompting the user for a password, it should use the primary password
+ typed earlier for authenticating the user. Note that in this
+ scenario, the user has to enter the password just once.
+
+ Note that if a one-time password scheme (e.g., S/Key) is used,
+ password mapping cannot apply.
+
+ 7.3. Implications of Stacking on the PAM Design
+
+ Because of the stacking capability of PAM, we have designed the PAM
+ API's to not return any data to the application, except status. If
+ this were not the case, it would be difficult for the PAM framework
+ to decide which module should return data to the application. When
+ there is any error, the application does not know which of the
+ modules failed. This behavior enables (even requires) the
+ application to be completely independent from the modules.
+
+ Another design decision we have made is that PAM gives only the user
+ name to all the underlying PAM modules, hence it is the
+ responsibility of the PAM modules to convert the name to their own
+ internal format. For example, the Kerberos module may have to
+ convert the UNIX user name to a Kerberos principal name.
+
+ Stacking also forces the modules to be designed such that they can
+ occur anywhere in the stack without any side-effects.
+
+ Since modules such as the authentication and the password module are
+ very closely related, it is important they be configured in the same
+ order and with compatible options.
+
+
+
+
+
+ Samar, Schemers Page 14
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ 8. INTEGRATION WITH SMART CARDS
+
+ Many networking authentication protocols require possession of a long
+ key to establish the user identity. For ease-of-use reasons, that
+ long key is normally encrypted with the user's password so that the
+ user is not required to memorize it. However, weak passwords can be
+ compromised through a dictionary attack and thus undermine the
+ stronger network authentication mechanism. Furthermore, the
+ encrypted data is normally stored in a centrally accessible service
+ whose availability depends upon the reliability of the associated
+ service. Solutions have been proposed to use a pass-phrase or one-
+ time-password, but those are much longer than the regular eight
+ character passwords traditionally used with UNIX `login'. This makes
+ the solution user-unfriendly because it requires longer strings to be
+ remembered and typed.
+
+ For most authentication protocol implementations, the trust boundary
+ is the local machine. This assumption may not be valid in cases
+ where the user is mobile and has to use publicly available networked
+ computers. In such cases, it is required that the clear text of the
+ key or the password never be made available to the machine.
+
+ Smart cards solve the above problems by reducing password exposure by
+ supporting a _two factor_ authentication mechanism: the first with
+ the possession of the card, and the second with the knowledge of the
+ PIN associated with the card. Not only can the smart cards be a
+ secure repository of multiple passwords, they can also provide the
+ encryption and authentication functions such that the long (private)
+ key is never exposed outside the card.
+
+ The PAM framework allows for integrating smart cards to the system by
+ providing a smart card specific module for authentication.
+ Furthermore, the unified login problem is simplified because the
+ multiple passwords for various authentication mechanisms can be
+ stored on the smart card itself. This can be enabled by adding a
+ suitable key-word such as `use_smart_card' in the _options_ field.
+
+
+ 9. SECURITY ISSUES
+
+ It is important to understand the impact of PAM on the security of
+ any system so that the site-administrator can make an informed
+ decision.
+
+ (a) Sharing of passwords with multiple authentication mechanisms.
+
+ If there are multiple authentication modules, one possibility
+ is to use the same password for all of them. If the password
+ for any of the multiple authentication system is compromised,
+ the user's password in all systems would be compromised. If
+ this is a concern, then multiple passwords might be considered
+
+
+
+ Samar, Schemers Page 15
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ at the cost of ease-of-use.
+
+ (b) Password-mapping.
+
+ This technique of encrypting all other passwords with the
+ primary password assumes that it is lot more difficult to crack
+ the primary password and that reasonable steps have been taken
+ to ensure limited availability of the encrypted primary
+ password. If this is not done, an intruder could target the
+ primary password as the first point of dictionary attack. If
+ one of the other modules provide stronger security than the
+ password based security, the site would be negating the strong
+ security by using password-mapping. If this is a concern, then
+ multiple passwords might be considered at the cost of ease-of-
+ use. If smart cards are used, they obviate the need for
+ password-mapping completely.
+
+ (c) Security of the configuration file.
+
+ Since the policy file dictates how the user is authenticated,
+ this file should be protected from unauthorized modifications.
+
+ (d) Stacking various PAM modules.
+
+ The system administrator should fully understand the
+ implications of stacking various modules that will be installed
+ on the system and their respective orders and interactions.
+ The composition of various authentication modules should be
+ carefully examined. The trusted computing base of the machine
+ now includes the PAM modules.
+
+
+ 10. EXPERIENCE WITH PAM
+
+ The PAM framework was first added in Solaris 2.3 release as a private
+ internal interface. PAM is currently being used by several system
+ entry applications such as `login', `passwd', `su', `dtlogin',
+ `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init',
+ `sac', and `ttymon'. We have found that PAM provides an excellent
+ framework to encapsulate the authentication-related tasks for the
+ entire system. The Solaris 2.3 PAM API's were hence enhanced and
+ simplified to support stacking.
+
+ PAM modules have been developed for UNIX, DCE, Kerberos, S/Key,
+ remote user authentication, and dialpass authentication. Other PAM
+ modules are under development, and integration with smart cards is
+ being planned.
+
+ Some third parties have used the PAM interface to extend the security
+ mechanisms offered by the Solaris environment.
+
+
+
+
+ Samar, Schemers Page 16
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ The PAM API has been accepted by Common Desktop Environment (CDE)
+ vendors as the API to be used for integrating the graphical interface
+ for login, `dtlogin' with multiple authentication mechanisms.
+
+
+ 11. FUTURE WORK
+
+ Amongst the various components of PAM, the password component needs
+ to be carefully examined to see whether the stacking semantics are
+ particularly applicable, and how PAM should deal with partial
+ failures when changing passwords.
+
+ The _control_flag_ of the configuration file can be extended to
+ include other semantics. For example, if the error is "name service
+ not available", one may want to retry. It is also possible to offer
+ semantics of "return success if any of the modules return success".
+
+ In an earlier section, we had mentioned integration of smart cards
+ with PAM. Though we feel that integration should be straight forward
+ from the PAM architecture point of view, there may be some issues
+ with implementation because the interfaces to the smart cards have
+ not yet been standardized.
+
+ One possible extension to PAM is to allow the passing of module-
+ specific data between applications and PAM modules. For example, the
+ `login' program likes to build its new environment from a select list
+ of variables, yet the DCE module needs the `KRB5CCNAME' variable to
+ be exported to the child process. For now we have modified the
+ `login' program to explicitly export the `KRB5CCNAME' variable.
+
+ Administrative tools are needed to help system administrators modify
+ `pam.conf', and perform sanity checks on it (i.e., a `pam_check'
+ utility).
+
+
+ 12. CONCLUSION
+
+ The PAM framework and the module interfaces provide pluggability for
+ user authentication, as well as for account, session and password
+ management. The PAM architecture can be used by `login' and by all
+ other system-entry services, and thus ensure that all entry points
+ for the system have been secured. This architecture enables
+ replacement and modification of authentication modules in the field
+ to secure the system against the newly found weaknesses without
+ changing any of the system services.
+
+ The PAM framework can be used to integrate `login' and `dtlogin' with
+ different authentication mechanisms such as RSA and Kerberos.
+ Multiple authentication systems can be accessed with the same
+ password. The PAM framework also provides easy integration of smart
+ cards into the system.
+
+
+
+ Samar, Schemers Page 17
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ PAM provides complementary functionality to GSS-API, in that it
+ provides mechanisms through which the user gets authenticated to any
+ new system-level authentication service on the machine. GSS-API then
+ uses the credentials for authenticated and secure communications with
+ other application-level service entities on the network.
+
+
+ 13. ACKNOWLEDGEMENTS
+
+ PAM development has spanned several release cycles at SunSoft.
+ Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and
+ implementation. Bill Shannon and Don Stephenson helped with the PAM
+ architecture. Rocky Wu prototyped stacking of multiple modules.
+ Paul Fronberg, Charlie Lai, and Roland Schemers made very significant
+ enhancements to the PAM interfaces and took the project to completion
+ within a very short time. Kathy Slattery wrote the PAM
+ documentation. John Perry integrated PAM within the CDE framework.
+
+
+ APPENDIX A. PAM API'S
+
+ This appendix gives an informal description of the various interfaces
+ of PAM. Since the goal here is just for the reader to get a working
+ knowledge about the PAM interfaces, not all flags and options have
+ been fully defined and explained. The API's described here are
+ subject to change.
+
+ The PAM Service Provider Interface is very similar to the PAM API,
+ except for one extra parameter to pass module-specific options to the
+ underlying modules.
+
+ A.1. Framework Layer API's
+
+ int
+ pam_start(
+ char *service_name,
+ char *user,
+ struct pam_conv *pam_conversation,
+ pam_handle_t **pamh
+ );
+
+ `pam_start()' is called to initiate an authentication transaction.
+ `pam_start()' takes as arguments the name of the service, the name of
+ the user to be authenticated, the address of the conversation
+ structure. `pamh' is later used as a handle for subsequent calls to
+ the PAM library.
+
+ The PAM modules do not communicate directly with the user; instead
+ they rely on the application to perform all such interaction. The
+ application needs to provide the conversation functions, `conv()',
+ and associated application data pointers through a `pam_conv'
+
+
+
+ Samar, Schemers Page 18
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ structure when it initiates an authentication transaction. The
+ module uses the `conv()' function to prompt the user for data,
+ display error messages, or text information.
+
+ int
+ pam_end(
+ pam_handle_t *pamh,
+ int pam_status
+ );
+
+ `pam_end()' is called to terminate the PAM transaction as specified
+ by `pamh', and to free any storage area allocated by the PAM modules
+ with `pam_set_item()'.
+
+ int
+ pam_set_item(
+ pam_handle_t *pamh,
+ int item_type,
+ void *item
+ );
+
+ int
+ pam_get_item(
+ pam_handle_t *pamh,
+ int item_type,
+ void **item);
+
+ `pam_get_item()' and `pam_set_item()' allow the parameters specified
+ in the initial call to `pam_start()' to be read and updated. This is
+ useful when a particular parameter is not available when
+ `pam_start()' is called or must be modified after the initial call to
+ `pam_start()'. `pam_set_item()' is passed a pointer to the object,
+ `item', and its type, `item_type'. `pam_get_item()' is passed the
+ address of the pointer, `item', which is assigned the address of the
+ requested object.
+
+ The `item_type' is one of the following:
+
+ Table 5: Possible Values for Item_type
+
+ Item Name Description
+ --------- -----------
+ PAM_SERVICE The service name
+ PAM_USER The user name
+ PAM_TTY The tty name
+ PAM_RHOST The remote host name
+ PAM_CONV The pam_conv structure
+ PAM_AUTHTOK The authentication token (password)
+ PAM_OLDAUTHTOK The old authentication token
+ PAM_RUSER The remote user name
+
+
+
+
+ Samar, Schemers Page 19
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only
+ available to PAM modules and not to the applications. They are
+ explicitly cleared out by the framework before returning to the
+ application.
+
+ char *
+ pam_strerror(
+ int errnum
+ );
+
+ `pam_strerror()' maps the error number to a PAM error message string,
+ and returns a pointer to that string.
+
+ int
+ pam_set_data(
+ pam_handle_t *pamh,
+ char *module_data_name,
+ char *data,
+ (*cleanup)(pam_handle_t *pamh, char *data,
+ int error_status)
+ );
+
+ The `pam_set_data()' function stores module specific data within the
+ PAM handle. The `module_data_name' uniquely specifies the name to
+ which some data and cleanup callback function can be attached. The
+ cleanup function is called when `pam_end()' is invoked.
+
+ int
+ pam_get_data(
+ pam_handle_t *pamh,
+ char *module_data_name,
+ void **datap
+ );
+
+ The `pam_get_data()' function obtains module-specific data from the
+ PAM handle stored previously by the `pam_get_data()' function. The
+ `module_data_name' uniquely specifies the name for which data has to
+ be obtained. This function is normally used to retrieve module
+ specific state information.
+
+ A.2. Authentication API's
+
+ int
+ pam_authenticate(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ The `pam_authenticate()' function is called to verify the identity of
+ the current user. The user is usually required to enter a password
+ or similar authentication token, depending upon the authentication
+
+
+
+ Samar, Schemers Page 20
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ module configured with the system. The user in question is specified
+ by a prior call to `pam_start()', and is referenced by the
+ authentication handle, `pamh'.
+
+ int
+ pam_setcred(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ The `pam_setcred()' function is called to set the credentials of the
+ current process associated with the authentication handle, `pamh'.
+ The actions that can be denoted through `flags' include credential
+ initialization, refresh, reinitialization and deletion.
+
+ A.3. Account Management API
+
+ int
+ pam_acct_mgmt(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ The function `pam_acct_mgmt()' is called to determine whether the
+ current user's account and password are valid. This typically
+ includes checking for password and account expiration, valid login
+ times, etc. The user in question is specified by a prior call to
+ `pam_start()', and is referenced by the authentication handle,
+ `pamh'.
+
+ A.4. Session Management API's
+
+ int
+ pam_open_session(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ `pam_open_session()' is called to inform the session modules that a
+ new session has been initialized. All programs which use PAM should
+ invoke `pam_open_session()' when beginning a new session.
+
+ int
+ pam_close_session(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ Upon termination of this session, the `pam_close_session()' function
+ should be invoked to inform the underlying modules that the session
+ has terminated.
+
+
+
+ Samar, Schemers Page 21
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ A.5. Password Management API's
+
+ int
+ pam_chauthtok(
+ pam_handle_t *pamh,
+ int flags
+ );
+
+ `pam_chauthtok()' is called to change the authentication token
+ associated with the user referenced by the authentication handle
+ `pamh'. After the call, the authentication token of the user will be
+ changed in accordance with the authentication module configured on
+ the system.
+
+
+ APPENDIX B. SAMPLE PAM APPLICATION
+
+ This appendix shows a sample `login' application which uses the PAM
+ API's. It is not meant to be a fully functional login program, as
+ some functionality has been left out in order to emphasize the use of
+ PAM API's.
+
+ #include <security/pam_appl.h>
+
+ static int login_conv(int num_msg, struct pam_message **msg,
+ struct pam_response **response, void *appdata_ptr);
+
+ static struct pam_conv pam_conv = {login_conv, NULL};
+
+ static pam_handle_t *pamh; /* Authentication handle */
+
+ void
+ main(int argc, char *argv[], char **renvp)
+ {
+
+ /*
+ * Call pam_start to initiate a PAM authentication operation
+ */
+
+ if ((pam_start("login", user_name, &pam_conv, &pamh))
+ != PAM_SUCCESS)
+ login_exit(1);
+
+ pam_set_item(pamh, PAM_TTY, ttyn);
+ pam_set_item(pamh, PAM_RHOST, remote_host);
+
+ while (!authenticated && retry < MAX_RETRIES) {
+ status = pam_authenticate(pamh, 0);
+ authenticated = (status == PAM_SUCCESS);
+ }
+
+
+
+
+ Samar, Schemers Page 22
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ if (status != PAM_SUCCESS) {
+ fprintf(stderr,"error: %s\n", pam_strerror(status));
+ login_exit(1);
+ }
+
+ /* now check if the authenticated user is allowed to login. */
+
+ if ((status = pam_acct_mgmt(pamh, 0)) != PAM_SUCCESS) {
+ if (status == PAM_AUTHTOK_EXPIRED) {
+ status = pam_chauthtok(pamh, 0);
+ if (status != PAM_SUCCESS)
+ login_exit(1);
+ } else {
+ login_exit(1);
+ }
+ }
+
+ /*
+ * call pam_open_session to open the authenticated session
+ * pam_close_session gets called by the process that
+ * cleans up the utmp entry (i.e., init)
+ */
+ if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) {
+ login_exit(status);
+ }
+
+ /* set up the process credentials */
+ setgid(pwd->pw_gid);
+
+ /*
+ * Initialize the supplementary group access list.
+ * This should be done before pam_setcred because
+ * the PAM modules might add groups during the pam_setcred call
+ */
+ initgroups(user_name, pwd->pw_gid);
+
+ status = pam_setcred(pamh, PAM_ESTABLISH_CRED);
+ if (status != PAM_SUCCESS) {
+ login_exit(status);
+ }
+
+ /* set the real (and effective) UID */
+ setuid(pwd->pw_uid);
+
+ pam_end(pamh, PAM_SUCCESS); /* Done using PAM */
+
+ /*
+ * Add DCE/Kerberos cred name, if any.
+ * XXX - The module specific stuff should be removed from login
+ * program eventually. This is better placed in DCE module and
+ * will be once PAM has routines for "exporting" environment
+
+
+
+ Samar, Schemers Page 23
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ * variables.
+ */
+ krb5p = getenv("KRB5CCNAME");
+ if (krb5p != NULL) {
+ ENVSTRNCAT(krb5ccname, krb5p);
+ envinit[basicenv++] = krb5ccname;
+ }
+ environ = envinit; /* Switch to the new environment. */
+ exec_the_shell();
+
+ /* All done */
+ }
+
+ /*
+ * login_exit - Call exit() and terminate.
+ * This function is here for PAM so cleanup can
+ * be done before the process exits.
+ */
+ static void
+ login_exit(int exit_code)
+ {
+ if (pamh)
+ pam_end(pamh, PAM_ABORT);
+ exit(exit_code);
+ /*NOTREACHED*/
+ }
+
+ /*
+ * login_conv():
+ * This is the conv (conversation) function called from
+ * a PAM authentication module to print error messages
+ * or garner information from the user.
+ */
+
+ static int
+ login_conv(int num_msg, struct pam_message **msg,
+ struct pam_response **response, void *appdata_ptr)
+ {
+
+ while (num_msg--) {
+ switch (m->msg_style) {
+
+ case PAM_PROMPT_ECHO_OFF:
+ r->resp = strdup(getpass(m->msg));
+ break;
+
+ case PAM_PROMPT_ECHO_ON:
+ (void) fputs(m->msg, stdout);
+ r->resp = malloc(PAM_MAX_RESP_SIZE);
+ fgets(r->resp, PAM_MAX_RESP_SIZE, stdin);
+ /* add code here to remove \n from fputs */
+
+
+
+ Samar, Schemers Page 24
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ break;
+
+ case PAM_ERROR_MSG:
+ (void) fputs(m->msg, stderr);
+ break;
+
+ case PAM_TEXT_INFO:
+ (void) fputs(m->msg, stdout);
+ break;
+
+ default:
+ /* add code here to log error message, etc */
+ break;
+ }
+ }
+ return (PAM_SUCCESS);
+ }
+
+
+ APPENDIX C. DCE MODULE
+
+ This appendix describes a sample implementation of a DCE PAM module.
+ In order to simplify the description, we do not address the issues
+ raised by password-mapping or stacking. The intent is to show which
+ DCE calls are being made by the DCE module.
+
+ The `pam_sm_*()' functions implement the PAM SPI functions which are
+ called from the PAM API functions.
+
+ C.1. DCE Authentication Management
+
+ The algorithm for authenticating with DCE (not including error
+ checking, prompting for passwords, etc.) is as follows:
+
+ pam_sm_authenticate()
+ {
+ sec_login_setup_identity(...);
+ pam_set_data(...);
+ sec_login_valid_and_cert_ident(...);
+ }
+
+ pam_sm_setcred()
+ {
+ pam_get_data(...);
+ sec_login_set_context(...);
+ }
+
+ The `pam_sm_authenticate()' function for DCE uses the
+ `pam_set_data()' and `pam_get_data()' functions to keep state (like
+ the `sec_login_handle_t' context) between calls. The following
+ cleanup function is also registered and gets called when `pam_end()'
+
+
+
+ Samar, Schemers Page 25
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ is called:
+
+ dce_cleanup()
+ {
+ if (/* PAM_SUCCESS and
+ sec_login_valid_and_cert_ident success */) {
+ sec_login_release_context(...);
+ } else {
+ sec_login_purge_context(...);
+ }
+ }
+
+ If everything was successful we release the login context, but leave
+ the credentials file intact. If the status passed to `pam_end()' was
+ not `PAM_SUCCESS' (i.e., a required module failed) we purge the login
+ context which also removes the credentials file.
+
+ C.2. DCE Account Management
+
+ The algorithm for DCE account management is as follows:
+
+ pam_sm_acct_mgmt()
+ {
+ pam_get_data(...);
+ sec_login_inquire_net_info(...);
+ /* check for expired password and account */
+ sec_login_free_net_info(...);
+ }
+
+ The `sec_login_inquire_net_info()' function is called to obtain
+ information about when the user's account and/or password are going
+ to expire. A warning message is displayed (using the conversation
+ function) if the user's account or password is going to expire in the
+ near future, or has expired. These warning messages can be disabled
+ using the `nowarn' option in the `pam.conf' file.
+
+ C.3. DCE Session Management
+
+ The DCE session management functions are currently empty. They could
+ be modified to optionally remove the DCE credentials file upon
+ logout, etc.
+
+ C.4. DCE Password Management
+
+ The algorithm for DCE password management is as follows:
+
+
+
+
+
+
+
+
+
+ Samar, Schemers Page 26
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ pam_sm_chauthtok
+ {
+ sec_rgy_site_open(...);
+ sec_rgy_acct_lookup(...);
+ sec_rgy_acct_passwd(...);
+ sec_rgy_site_close(...);
+ }
+
+ The `sec_rgy_acct_passwd()' function is called to change the user's
+ password in the DCE registry.
+
+
+ REFERENCES
+
+ [Adamson 95] W. A. Adamson, J. Rees, and P. Honeyman, "Joining
+ Security Realms: A Single Login for Netware and
+ Kerberos", CITI Technical Report 95-1, Center for
+ Information Technology Integration, University of
+ Michigan, Ann Arbor, MI, February 1995.
+
+ [Diffie 76] W. Diffie and M. E. Hellman, "New Directions in
+ Cryptography", IEEE Transactions on Information
+ Theory, November 1976.
+
+ [Linn 93] J. Linn, "Generic Security Service Application
+ Programming Interface", Internet RFC 1508, 1509, 1993.
+
+ [Rivest 78] R. L. Rivest, A. Shamir, and L. Adleman., "A Method
+ for Obtaining Digital Signatures and Pubic-key
+ Cryptosystems", Communications of the ACM, 21(2),
+ 1978.
+
+ [SIA 95] "Digital UNIX Security", Digital Equipment
+ Corporation, Order Number AA-Q0R2C-TE, July 1995.
+
+ [Skey 94] N. M. Haller, "The S/Key One-Time Password System",
+ ISOC Symposium on Network and Distributed Security,
+ 1994.
+
+ [Steiner 88] J.G. Steiner, B. C. Neuman, and J. I. Schiller,
+ "Kerberos, An Authentication Service for Open Network
+ Systems", in Proceedings of the Winter USENIX
+ Conference, Dallas, Jan 1988.
+
+ [Taylor 88] B. Taylor and D. Goldberg, "Secure Networking in the
+ Sun Environment", Sun Microsystems Technical Paper,
+ 1988.
+
+ [XFN 94] "Federated Naming: the XFN Specifications", X/Open
+ Preliminary Specification, X/Open Document #P403,
+ ISBN:1-85912-045-8, X/Open Co. Ltd., July 1994.
+
+
+
+ Samar, Schemers Page 27
+
+
+
+
+
+
+
+ OSF-RFC 86.0 PAM October 1995
+
+
+
+ AUTHOR'S ADDRESS
+
+ Vipin Samar Internet email: vipin@eng.sun.com
+ SunSoft, Inc. Telephone: +1-415-336-1002
+ 2550 Garcia Avenue
+ Mountain View, CA 94043
+ USA
+
+ Roland J. Schemers III Internet email: schemers@eng.sun.com
+ SunSoft, Inc. Telephone: +1-415-336-1035
+ 2550 Garcia Avenue
+ Mountain View, CA 94043
+ USA
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Samar, Schemers Page 28
+
+
+
+
+
+
diff --git a/doc/txts/.cvsignore b/doc/txts/.cvsignore
new file mode 100644
index 0000000..f35c392
--- /dev/null
+++ b/doc/txts/.cvsignore
@@ -0,0 +1 @@
+pam*.txt
diff --git a/doc/txts/README b/doc/txts/README
new file mode 100644
index 0000000..540b09b
--- /dev/null
+++ b/doc/txts/README
@@ -0,0 +1,3 @@
+$Id$
+
+This is a directory for text versions of the pam documentation
diff --git a/examples/.cvsignore b/examples/.cvsignore
new file mode 100644
index 0000000..2769a41
--- /dev/null
+++ b/examples/.cvsignore
@@ -0,0 +1,3 @@
+blank
+xsh
+check_user
diff --git a/examples/Makefile b/examples/Makefile
new file mode 100644
index 0000000..c688247
--- /dev/null
+++ b/examples/Makefile
@@ -0,0 +1,42 @@
+#
+# $Id$
+#
+
+dummy:
+
+ @echo "*** This is not a top level Makefile!"
+
+PROGS = blank xsh check_user
+SRCS = blank.c xsh.c check_user.c
+
+# have removed the following pair since they no longer conform to
+# any recognized conventions: vpass test
+# ditto: vpass.c test.c
+
+PROGSUID =
+
+all: $(PROGS)
+
+check_user: check_user.o
+ $(CC) $(CFLAGS) -o $@ $< $(LOADLIBES)
+
+blank: blank.o
+ $(CC) $(CFLAGS) -o $@ $< $(LOADLIBES)
+
+xsh: xsh.o
+ $(CC) $(CFLAGS) -o $@ $< $(LOADLIBES)
+
+install: all
+ if [ -n "$(PROGS)" ]; then cp $(PROGS) ../bin ; fi
+ if [ -n "$(PROGSUID)" ]; then \
+ $(INSTALL) -m 4555 -o root -g bin $(PROGSUID) ../bin ; fi
+
+clean:
+ rm -f *.a *.so *.o *~ $(PROGS) $(PROGSUID)
+
+remove:
+ cd ../bin ; rm -f $(PROGS) $(PROGSUID)
+
+extraclean: clean
+ rm -f *.a *.out *.o *.so
+ for x in $(PROGS) $(PROGSUID) ; do rm -f ../bin/$$x ; done
diff --git a/examples/blank.c b/examples/blank.c
new file mode 100644
index 0000000..33b5056
--- /dev/null
+++ b/examples/blank.c
@@ -0,0 +1,182 @@
+/*
+ * $Id$
+ *
+ * $Log$
+ * Revision 1.1 2000/06/20 22:11:13 agmorgan
+ * Initial revision
+ *
+ * Revision 1.2 1999/11/08 05:39:53 morgan
+ * removed void main def which was making gcc complain
+ *
+ * Revision 1.1.1.1 1998/07/12 05:17:14 morgan
+ * Linux PAM sources pre-0.66
+ *
+ * Revision 1.7 1996/12/01 03:16:53 morgan
+ * added setcred closing function
+ *
+ * Revision 1.6 1996/11/10 19:51:40 morgan
+ * minor change to avoid gcc warning
+ *
+ * Revision 1.5 1996/07/07 23:53:05 morgan
+ * added optional fail delay (non-standard Linux-PAM)
+ *
+ * Revision 1.4 1996/05/02 04:44:18 morgan
+ * moved conversation to a libmisc library routine.
+ *
+ *
+ */
+
+/* Andrew Morgan (morgan@parc.power.net) -- a self contained `blank'
+ * application
+ *
+ * I am not very proud of this code. It makes use of a possibly ill-
+ * defined pamh pointer to call pam_strerror() with. The reason that
+ * I was sloppy with this is historical (pam_strerror, prior to 0.59,
+ * did not require a pamh argument) and if this program is used as a
+ * model for anything, I should wish that you will take this error into
+ * account.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <security/pam_appl.h>
+#include <security/pam_misc.h>
+
+/* ------ some local (static) functions ------- */
+
+static void bail_out(pam_handle_t *pamh, int really, int code, const char *fn)
+{
+ fprintf(stderr,"==> called %s()\n got: `%s'\n", fn,
+ pam_strerror(pamh, code));
+ if (really && code)
+ exit (1);
+}
+
+/* ------ some static data objects ------- */
+
+static struct pam_conv conv = {
+ misc_conv,
+ NULL
+};
+
+/* ------- the application itself -------- */
+
+int main(int argc, char **argv)
+{
+ pam_handle_t *pamh=NULL;
+ char *username=NULL;
+ int retcode;
+
+ /* did the user call with a username as an argument ? */
+
+ if (argc > 2) {
+ fprintf(stderr,"usage: %s [username]\n",argv[0]);
+ } else if (argc == 2) {
+ username = argv[1];
+ }
+
+ /* initialize the Linux-PAM library */
+ retcode = pam_start("blank", username, &conv, &pamh);
+ bail_out(pamh,1,retcode,"pam_start");
+
+ /* test the environment stuff */
+ {
+#define MAXENV 15
+ const char *greek[MAXENV] = {
+ "a=alpha", "b=beta", "c=gamma", "d=delta", "e=epsilon",
+ "f=phi", "g=psi", "h=eta", "i=iota", "j=mu", "k=nu",
+ "l=zeta", "h=", "d", "k=xi"
+ };
+ char **env;
+ int i;
+
+ for (i=0; i<MAXENV; ++i) {
+ retcode = pam_putenv(pamh,greek[i]);
+ bail_out(pamh,0,retcode,"pam_putenv");
+ }
+ env = pam_getenvlist(pamh);
+ if (env)
+ env = pam_misc_drop_env(env);
+ else
+ fprintf(stderr,"???\n");
+ fprintf(stderr,"a test: c=[%s], j=[%s]\n"
+ , pam_getenv(pamh, "c"), pam_getenv(pamh, "j"));
+ }
+
+ /* to avoid using goto we abuse a loop here */
+ for (;;) {
+ /* authenticate the user --- `0' here, could have been PAM_SILENT
+ * | PAM_DISALLOW_NULL_AUTHTOK */
+
+ retcode = pam_authenticate(pamh, 0);
+ bail_out(pamh,0,retcode,"pam_authenticate");
+
+ /* has the user proved themself valid? */
+ if (retcode != PAM_SUCCESS) {
+ fprintf(stderr,"%s: invalid request\n",argv[0]);
+ break;
+ }
+
+ /* the user is valid, but should they have access at this
+ time? */
+
+ retcode = pam_acct_mgmt(pamh, 0); /* `0' could be as above */
+ bail_out(pamh,0,retcode,"pam_acct_mgmt");
+
+ if (retcode == PAM_NEW_AUTHTOK_REQD) {
+ fprintf(stderr,"Application must request new password...\n");
+ retcode = pam_chauthtok(pamh,PAM_CHANGE_EXPIRED_AUTHTOK);
+ bail_out(pamh,0,retcode,"pam_chauthtok");
+ }
+
+ if (retcode != PAM_SUCCESS) {
+ fprintf(stderr,"%s: invalid request\n",argv[0]);
+ break;
+ }
+
+ /* `0' could be as above */
+ retcode = pam_setcred(pamh, PAM_ESTABLISH_CRED);
+ bail_out(pamh,0,retcode,"pam_setcred1");
+
+ if (retcode != PAM_SUCCESS) {
+ fprintf(stderr,"%s: problem setting user credentials\n"
+ ,argv[0]);
+ break;
+ }
+
+ /* open a session for the user --- `0' could be PAM_SILENT */
+ retcode = pam_open_session(pamh,0);
+ bail_out(pamh,0,retcode,"pam_open_session");
+ if (retcode != PAM_SUCCESS) {
+ fprintf(stderr,"%s: problem opening a session\n",argv[0]);
+ break;
+ }
+
+ fprintf(stderr,"The user has been authenticated and `logged in'\n");
+
+ /* close a session for the user --- `0' could be PAM_SILENT
+ * it is possible that this pam_close_call is in another program..
+ */
+
+ retcode = pam_close_session(pamh,0);
+ bail_out(pamh,0,retcode,"pam_close_session");
+ if (retcode != PAM_SUCCESS) {
+ fprintf(stderr,"%s: problem closing a session\n",argv[0]);
+ break;
+ }
+
+ retcode = pam_setcred(pamh, PAM_DELETE_CRED);
+ bail_out(pamh,0,retcode,"pam_setcred2");
+
+ break; /* don't go on for ever! */
+ }
+
+ /* close the Linux-PAM library */
+ retcode = pam_end(pamh, PAM_SUCCESS);
+ pamh = NULL;
+
+ bail_out(pamh,1,retcode,"pam_end");
+
+ exit(0);
+}
diff --git a/examples/check_user.c b/examples/check_user.c
new file mode 100644
index 0000000..6d52cca
--- /dev/null
+++ b/examples/check_user.c
@@ -0,0 +1,71 @@
+/*
+ $Id$
+
+ This program was contributed by Shane Watts <shane@icarus.bofh.asn.au>
+ slight modifications by AGM.
+
+ You need to add the following (or equivalent) to the /etc/pam.conf file.
+ # check authorization
+ check auth required pam_unix_auth.so
+ check account required pam_unix_acct.so
+
+ $Log$
+ Revision 1.1 2000/06/20 22:11:13 agmorgan
+ Initial revision
+
+ Revision 1.1.1.1 1998/07/12 05:17:14 morgan
+ Linux PAM sources pre-0.66
+
+ Revision 1.1 1996/11/10 21:19:30 morgan
+ Initial revision
+
+ */
+
+#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, &conv, &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 */
+}
diff --git a/examples/test.c b/examples/test.c
new file mode 100644
index 0000000..8fc5e6c
--- /dev/null
+++ b/examples/test.c
@@ -0,0 +1,105 @@
+/*
+ * $Log$
+ * Revision 1.1 2000/06/20 22:11:13 agmorgan
+ * Initial revision
+ *
+ * Revision 1.1.1.1 1998/07/12 05:17:14 morgan
+ * Linux PAM sources pre-0.66
+ *
+ * Revision 1.3 1996/03/10 00:14:20 morgan
+ * made lines less than 80 chars long.
+ *
+ * Revision 1.2 1996/03/09 09:16:26 morgan
+ * changed the header file that it includes.
+ *
+ * Revision 1.1 1996/03/09 09:13:34 morgan
+ * Initial revision
+ */
+
+/* Marc Ewing (marc@redhat.com) - original test code
+ * Alexander O. Yuriev (alex@bach.cis.temple.edu)
+ * Andrew Morgan (morgan@physics.ucla.edu)
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <pwd.h>
+
+#include <security/pam_appl.h>
+
+/* this program is not written to the PAM spec: it tests the
+ * pam_[sg]et_data() functions. Which is usually reserved for modules */
+
+#include <security/pam_modules.h>
+#include <security/pam_misc.h>
+
+#define USERNAMESIZE 1024
+
+static int test_conv( int num_msg,
+ const struct pam_message **msgm,
+ struct pam_response **response,
+ void *appdata_ptr )
+{
+ return 0;
+}
+
+static struct pam_conv conv = {
+ test_conv,
+ NULL
+};
+
+static int cleanup_func(pam_handle_t *pamh, void *data, int error_status)
+{
+ printf("Cleaning up!\n");
+ return PAM_SUCCESS;
+}
+
+void main( void )
+{
+ pam_handle_t *pamh;
+ char *name = ( char *) malloc( USERNAMESIZE + 1 );
+ char *p = NULL;
+ char *s = NULL;
+
+ if (! name )
+ {
+ perror( "Ouch, don't have enough memory");
+ exit( -1 );
+ }
+
+
+
+
+ fprintf( stdout, "Enter a name of a user to authenticate : ");