From efd31890b5ed496a5a00c08a262da240e66a4ddc Mon Sep 17 00:00:00 2001 From: Steve Langasek Date: Thu, 3 Jan 2019 12:44:11 -0800 Subject: New upstream version 0.76 --- doc/.cvsignore | 2 - doc/CREDITS | 49 - doc/Makefile | 167 ---- doc/NOTES | 16 - doc/figs/pam_orient.txt | 23 - doc/html/.cvsignore | 1 - doc/html/index.html | 21 - doc/man/pam.8 | 369 -------- doc/man/pam.conf.8 | 1 - doc/man/pam.d.8 | 1 - doc/man/pam_authenticate.3 | 91 -- doc/man/pam_chauthtok.3 | 101 --- doc/man/pam_close_session.3 | 1 - doc/man/pam_end.3 | 1 - doc/man/pam_fail_delay.3 | 130 --- doc/man/pam_get_item.3 | 1 - doc/man/pam_open_session.3 | 99 -- doc/man/pam_set_item.3 | 55 -- doc/man/pam_setcred.3 | 79 -- doc/man/pam_start.3 | 98 -- doc/man/pam_strerror.3 | 51 -- doc/man/template-man | 52 -- doc/modules/README | 13 - doc/modules/module.sgml-template | 170 ---- doc/modules/pam_access.sgml | 117 --- doc/modules/pam_chroot.sgml | 86 -- doc/modules/pam_cracklib.sgml | 304 ------- doc/modules/pam_deny.sgml | 177 ---- doc/modules/pam_env.sgml | 141 --- doc/modules/pam_filter.sgml | 150 --- doc/modules/pam_ftp.sgml | 93 -- doc/modules/pam_group.sgml | 108 --- doc/modules/pam_issue.sgml | 120 --- doc/modules/pam_krb4.sgml | 126 --- doc/modules/pam_lastlog.sgml | 119 --- doc/modules/pam_limits.sgml | 247 ----- doc/modules/pam_listfile.sgml | 138 --- doc/modules/pam_mail.sgml | 142 --- doc/modules/pam_mkhomedir.sgml | 83 -- doc/modules/pam_motd.sgml | 77 -- doc/modules/pam_nologin.sgml | 81 -- doc/modules/pam_permit.sgml | 83 -- doc/modules/pam_pwdb.sgml | 249 ----- doc/modules/pam_radius.sgml | 117 --- doc/modules/pam_rhosts.sgml | 164 ---- doc/modules/pam_rootok.sgml | 85 -- doc/modules/pam_securetty.sgml | 72 -- doc/modules/pam_tally.sgml | 191 ---- doc/modules/pam_time.sgml | 166 ---- doc/modules/pam_unix.sgml | 288 ------ doc/modules/pam_userdb.sgml | 112 --- doc/modules/pam_warn.sgml | 67 -- doc/modules/pam_wheel.sgml | 125 --- doc/pam_appl.sgml | 1782 ------------------------------------ doc/pam_modules.sgml | 1505 ------------------------------- doc/pam_source.sgml | 1160 ------------------------ doc/pdf/.cvsignore | 1 - doc/pdf/README | 3 - doc/ps/.cvsignore | 1 - doc/ps/README | 3 - doc/specs/.cvsignore | 1 - doc/specs/draft-morgan-pam.raw | 764 ---------------- doc/specs/formatter/.cvsignore | 3 - doc/specs/formatter/Makefile | 16 - doc/specs/formatter/parse.lex | 11 - doc/specs/formatter/parse.y | 293 ------ doc/specs/rfc86.0.txt | 1851 -------------------------------------- doc/specs/std-agent-id.raw | 95 -- doc/txts/.cvsignore | 1 - doc/txts/README | 3 - 70 files changed, 13113 deletions(-) delete mode 100644 doc/.cvsignore delete mode 100644 doc/CREDITS delete mode 100644 doc/Makefile delete mode 100644 doc/NOTES delete mode 100644 doc/figs/pam_orient.txt delete mode 100644 doc/html/.cvsignore delete mode 100644 doc/html/index.html delete mode 100644 doc/man/pam.8 delete mode 100644 doc/man/pam.conf.8 delete mode 100644 doc/man/pam.d.8 delete mode 100644 doc/man/pam_authenticate.3 delete mode 100644 doc/man/pam_chauthtok.3 delete mode 100644 doc/man/pam_close_session.3 delete mode 100644 doc/man/pam_end.3 delete mode 100644 doc/man/pam_fail_delay.3 delete mode 100644 doc/man/pam_get_item.3 delete mode 100644 doc/man/pam_open_session.3 delete mode 100644 doc/man/pam_set_item.3 delete mode 100644 doc/man/pam_setcred.3 delete mode 100644 doc/man/pam_start.3 delete mode 100644 doc/man/pam_strerror.3 delete mode 100644 doc/man/template-man delete mode 100644 doc/modules/README delete mode 100644 doc/modules/module.sgml-template delete mode 100644 doc/modules/pam_access.sgml delete mode 100644 doc/modules/pam_chroot.sgml delete mode 100644 doc/modules/pam_cracklib.sgml delete mode 100644 doc/modules/pam_deny.sgml delete mode 100644 doc/modules/pam_env.sgml delete mode 100644 doc/modules/pam_filter.sgml delete mode 100644 doc/modules/pam_ftp.sgml delete mode 100644 doc/modules/pam_group.sgml delete mode 100644 doc/modules/pam_issue.sgml delete mode 100644 doc/modules/pam_krb4.sgml delete mode 100644 doc/modules/pam_lastlog.sgml delete mode 100644 doc/modules/pam_limits.sgml delete mode 100644 doc/modules/pam_listfile.sgml delete mode 100644 doc/modules/pam_mail.sgml delete mode 100644 doc/modules/pam_mkhomedir.sgml delete mode 100644 doc/modules/pam_motd.sgml delete mode 100644 doc/modules/pam_nologin.sgml delete mode 100644 doc/modules/pam_permit.sgml delete mode 100644 doc/modules/pam_pwdb.sgml delete mode 100644 doc/modules/pam_radius.sgml delete mode 100644 doc/modules/pam_rhosts.sgml delete mode 100644 doc/modules/pam_rootok.sgml delete mode 100644 doc/modules/pam_securetty.sgml delete mode 100644 doc/modules/pam_tally.sgml delete mode 100644 doc/modules/pam_time.sgml delete mode 100644 doc/modules/pam_unix.sgml delete mode 100644 doc/modules/pam_userdb.sgml delete mode 100644 doc/modules/pam_warn.sgml delete mode 100644 doc/modules/pam_wheel.sgml delete mode 100644 doc/pam_appl.sgml delete mode 100644 doc/pam_modules.sgml delete mode 100644 doc/pam_source.sgml delete mode 100644 doc/pdf/.cvsignore delete mode 100644 doc/pdf/README delete mode 100644 doc/ps/.cvsignore delete mode 100644 doc/ps/README delete mode 100644 doc/specs/.cvsignore delete mode 100644 doc/specs/draft-morgan-pam.raw delete mode 100644 doc/specs/formatter/.cvsignore delete mode 100644 doc/specs/formatter/Makefile delete mode 100644 doc/specs/formatter/parse.lex delete mode 100644 doc/specs/formatter/parse.y delete mode 100644 doc/specs/rfc86.0.txt delete mode 100644 doc/specs/std-agent-id.raw delete mode 100644 doc/txts/.cvsignore delete mode 100644 doc/txts/README (limited to 'doc') diff --git a/doc/.cvsignore b/doc/.cvsignore deleted file mode 100644 index 7ac74f9d..00000000 --- a/doc/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -pam.sgml -MODULES-SGML diff --git a/doc/CREDITS b/doc/CREDITS deleted file mode 100644 index df0eb599..00000000 --- a/doc/CREDITS +++ /dev/null @@ -1,49 +0,0 @@ - -Chris Adams, -Peter Allgeyer, -Tim Baverstock, -Tim Berger, -Craig S. Bell, -Derrick J. Brashear, -Ben Buxton, -Seth Chaiklin, -Oliver Crow, -Chris Dent, -Marc Ewing, -Cristian Gafton, -Emmanuel Galanos, -Brad M. Garcia, -Eric Hester, -Michel D'Hooge, -Roger Hu, -Eric Jacksch, -Michael K. Johnson, -David Kinchlea, -Olaf Kirch, -Marcin Korzonek, -Stephen Langasek, -Nicolai Langfeldt, -Elliot Lee, -Luke Kenneth Casson Leighton, -Al Longyear, -Ingo Luetkebohle, -Marek Michalkiewicz, -Robert Milkowski, -Aleph One, -Martin Pool, -Sean Reifschneider, -Jan Rekorajski, -Erik Troan, -Theodore Ts'o, -Jeff Uphoff, -Myles Uyema, -Savochkin Andrey Vladimirovich, -Ronald Wahl, -David Wood, -John Wilmes, -Joseph S. D. Yao -and -Alex O. Yuriev. diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 63c11fbf..00000000 --- a/doc/Makefile +++ /dev/null @@ -1,167 +0,0 @@ - -### $Id$ - -include ../Make.Rules - -####################################################### - -FILES=pam pam_appl pam_modules -FSRCS=pam.sgml pam_appl.sgml pam_modules.sgml - -TEXTS=txts/pam.txt txts/pam_appl.txt txts/pam_modules.txt -HTMLS=html/pam.html html/pam_appl.html html/pam_modules.html -PSFILES=ps/pam.ps ps/pam_appl.ps ps/pam_modules.ps -PDFFILES=pdf/pam.pdf ps/pam_appl.pdf ps/pam_modules.pdf - -MODULES=$(shell ls modules/*.sgml) - -####################################################### - -dummy: - @echo "Making the documentation..." - @$(MAKE) all - -# note, at this time we don't include pdf files by default, but you -# can type make pdf in this directory and see what happens in the pdf -# subdirectory. - -all: htmls texts postscript - -htmls: $(HTMLS) - -$(HTMLS) : $(FSRCS) -ifeq ($(HAVE_SGML2HTML),yes) - @for i in $(FILES) ; do \ - if [ ! -f "html/$$i.html" ] || [ "$$i.sgml" -nt "html/$$i.html" ]; \ - then \ - cd html ; sgml2html ../$$i ; \ - if [ $$? -ne 0 ]; then exit 1 ; fi ; \ - cd .. ; \ - fi ; \ - done -else - @echo XXX - you do not have the sgml2html binary installed -endif - -texts: $(TEXTS) - -$(TEXTS) : $(FSRCS) -ifeq ($(HAVE_SGML2TXT),yes) - @for i in $(FILES) ; do \ - if [ ! -f "txts/$$i.txt" ] \ - || [ "$$i.sgml" -nt "txts/$$i.txt" ]; then \ - cd txts ; sgml2txt ../$$i ; cd .. ; \ - fi ; \ - done -else - @echo XXX - you do not have the sgml2txt binary installed -endif - -postscript: $(PSFILES) - -$(PSFILES): $(FSRCS) -ifneq ($(PSER),) - @for i in $(FILES) ; do \ - if [ ! -f "ps/$$i.ps" ] || [ "$$i.sgml" -nt "ps/$$i.ps" ]; then \ - cd ps ; $(PSER) ../$$i ; cd .. ; \ - fi ; \ - done -else - @echo XXX - neither sgml2ps nor sgml2latex binaries are installed -endif - -pdf: $(PDFFILES) - -$(PDFFILES) : $(PSFILES) -ifeq ($(HAVE_PS2PDF),yes) - @for i in $(FILES) ; do \ - if [ ! -f "pdf/$$i.pdf" ] || [ "ps/$$i.ps" -nt "ps/$$i.pdf" ]; then \ - ps2pdf ps/$$i.ps pdf/$$i.pdf ; \ - fi ; \ - done -else - @echo XXX - ps2pdf is not installed -endif - -pam.sgml: pam_source.sgml MODULES-SGML CREDITS - @sed -e '/^/r MODULES-SGML' pam_source.sgml | sed -e '/^/r CREDITS' > pam.sgml - -MODULES-SGML: $(MODULES) - @echo 'Building module text from files in modules/*.sgml' - @rm -f MODULES-SGML - @echo '' >> MODULES-SGML - @cat modules/*.sgml >> MODULES-SGML - -extraclean: clean - -remove: - cd man && for file in *.3 ; do \ - rm -f $(FAKEROOT)$(MANDIR)/man3/$$file ; \ - done - cd man && for file in *.8 ; do \ - rm -f $(FAKEROOT)$(MANDIR)/man8/$$file ; \ - done - cd txts && for file in *.txt; do \ - rm -f $(FAKEROOT)$(DOCDIR)/text/$$file ; \ - done - cd ps && for file in *.ps; do \ - rm -f $(FAKEROOT)$(DOCDIR)/ps/$$file ; \ - done - cd html && for file in *.html; do \ - rm -f $(FAKEROOT)$(DOCDIR)/html/$$file ; \ - done - -install: all -ifeq ($(HAVE_SGML2TXT),yes) - mkdir -p $(FAKEROOT)$(DOCDIR)/text - for file in txts/*.txt; do \ - install -m 644 $$file $(FAKEROOT)$(DOCDIR)/text ; \ - done -endif -ifneq ($(PSER),) - mkdir -p $(FAKEROOT)$(DOCDIR)/ps - for file in ps/*.ps; do \ - install -m 644 $$file $(FAKEROOT)$(DOCDIR)/ps ; \ - done - ifeq ($(HAVE_PS2PDF),yes) - mkdir -p $(FAKEROOT)$(DOCDIR)/pdf - for file in pdf/*.pdf; do \ - install -m 644 $$file $(FAKEROOT)$(DOCDIR)/pdf ; \ - done - endif -endif -ifeq ($(HAVE_SGML2HTML),yes) - mkdir -p $(FAKEROOT)$(DOCDIR)/html - for file in html/*.html; do \ - install -m 644 $$file $(FAKEROOT)$(DOCDIR)/html ; \ - done -endif - mkdir -p $(FAKEROOT)$(MANDIR)/man3 - mkdir -p $(FAKEROOT)$(MANDIR)/man8 - for file in man/*.3 ; do \ - install -m 644 $$file $(FAKEROOT)$(MANDIR)/man3 ; \ - done - for file in man/*.8 ; do \ - install -m 644 $$file $(FAKEROOT)$(MANDIR)/man8 ; \ - done - -spec: specs/draft-morgan-pam.raw - cd specs/formatter && $(MAKE) - specs/formatter/padout < specs/draft-morgan-pam.raw > specs/draft-morgan-pam-current.txt - -releasedocs: all spec - tar zvfc Linux-PAM-$(MAJOR_REL).$(MINOR_REL)-docs.tar.gz --exclude CVS html ps txts specs/draft-morgan-pam-current.txt - -clean: - rm -f *~ *.bak - rm -f html/pam*.html - rm -f man/*~ - rm -f $(TEXTS) - rm -f $(PSFILES) ps/missfont.log - rm -f pdf/*.pdf - rm -f MODULES-SGML pam.sgml - rm -f specs/draft-morgan-pam-current.txt - $(MAKE) -C specs/formatter clean - diff --git a/doc/NOTES b/doc/NOTES deleted file mode 100644 index b0f40d47..00000000 --- a/doc/NOTES +++ /dev/null @@ -1,16 +0,0 @@ -Things to be added: - -@ modules: -@ application: - - use of - 'user' = user to become, - 'uid' = user requesting service - 'euid' = privilege of current process. - -@ sysadmin: - - included modules: - behavior - non-included modules: - behavior/pointers. diff --git a/doc/figs/pam_orient.txt b/doc/figs/pam_orient.txt deleted file mode 100644 index a8b745a1..00000000 --- a/doc/figs/pam_orient.txt +++ /dev/null @@ -1,23 +0,0 @@ - - - - +----------------+ - | application: X | - +----------------+ / +----------+ +================+ - | authentication-[---->--\--] Linux- |--<--| /etc/pam.conf | - | + [----<--/--] PAM | |================| - |[conversation()][--+ \ | | | X auth .. a.so | - +----------------+ | / +-n--n-----+ | X auth .. b.so | - | | | __| | | _____/ - | service user | A | | |____,-----' - | | | V A - +----------------+ +------|-----|---------+ -----+------+ - +---u-----u----+ | | | - | auth.... |--[ a ]--[ b ]--[ c ] - +--------------+ - | acct.... |--[ b ]--[ d ] - +--------------+ - | password |--[ b ]--[ c ] - +--------------+ - | session |--[ e ]--[ c ] - +--------------+ \ No newline at end of file diff --git a/doc/html/.cvsignore b/doc/html/.cvsignore deleted file mode 100644 index 3b358a3a..00000000 --- a/doc/html/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -pam*.html \ No newline at end of file diff --git a/doc/html/index.html b/doc/html/index.html deleted file mode 100644 index 1ffd7e38..00000000 --- a/doc/html/index.html +++ /dev/null @@ -1,21 +0,0 @@ - - - -Linux-PAM - Pluggable Authentication Modules for Linux - - - -

-Here is the documentation for Linux-PAM. As you will see it is -currently not complete. However, in order of decreasing length: - -

- -
-

-REVISION: $Id$ - diff --git a/doc/man/pam.8 b/doc/man/pam.8 deleted file mode 100644 index 939a0fe9..00000000 --- a/doc/man/pam.8 +++ /dev/null @@ -1,369 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7,2001 -.TH PAM 8 "2001 Jan 20" "Linux-PAM 0.74" "Linux-PAM Manual" -.SH NAME - -Linux-PAM \- Pluggable Authentication Modules for Linux - -.SH SYNOPSIS -.B /etc/pam.conf -.sp 2 -.SH DESCRIPTION - -This manual is intended to offer a quick introduction to -.BR Linux-PAM ". " -For more information the reader is directed to the -.BR "Linux-PAM system administrators' guide". - -.sp -.BR Linux-PAM -Is a system of libraries that handle the authentication tasks of -applications (services) on the system. The library provides a stable -general interface (Application Programming Interface - API) that -privilege granting programs (such as -.BR login "(1) " -and -.BR su "(1)) " -defer to to perform standard authentication tasks. - -.sp -The principal feature of the PAM approach is that the nature of the -authentication is dynamically configurable. In other words, the -system administrator is free to choose how individual -service-providing applications will authenticate users. This dynamic -configuration is set by the contents of the single -.BR Linux-PAM -configuration file -.BR /etc/pam.conf "." -Alternatively, the configuration can be set by individual -configuration files located in the -.B /etc/pam.d/ -directory. -.IB "The presence of this directory will cause " Linux-PAM " to ignore" -.BI /etc/pam.conf "." - -.sp -From the point of view of the system administrator, for whom this -manual is provided, it is not of primary importance to understand the -internal behavior of the -.BR Linux-PAM -library. The important point to recognize is that the configuration -file(s) -.I define -the connection between applications -.BR "" "(" services ")" -and the pluggable authentication modules -.BR "" "(" PAM "s)" -that perform the actual authentication tasks. - -.sp -.BR Linux-PAM -separates the tasks of -.I authentication -into four independent management groups: -.BR "account" " management; " -.BR "auth" "entication management; " -.BR "password" " management; " -and -.BR "session" " management." -(We highlight the abbreviations used for these groups in the -configuration file.) - -.sp -Simply put, these groups take care of different aspects of a typical -user's request for a restricted service: - -.sp -.BR account " - " -provide account verification types of service: has the user's password -expired?; is this user permitted access to the requested service? - -.br -.BR auth "entication - " -establish the user is who they claim to be. Typically this is via some -challenge-response request that the user must satisfy: if you are who -you claim to be please enter your password. Not all authentications -are of this type, there exist hardware based authentication schemes -(such as the use of smart-cards and biometric devices), with suitable -modules, these may be substituted seamlessly for more standard -approaches to authentication - such is the flexibility of -.BR Linux-PAM "." - -.br -.BR password " - " -this group's responsibility is the task of updating authentication -mechanisms. Typically, such services are strongly coupled to those of -the -.BR auth -group. Some authentication mechanisms lend themselves well to being -updated with such a function. Standard UN*X password-based access is -the obvious example: please enter a replacement password. - -.br -.BR session " - " -this group of tasks cover things that should be done prior to a -service being given and after it is withdrawn. Such tasks include the -maintenance of audit trails and the mounting of the user's home -directory. The -.BR session -management group is important as it provides both an opening and -closing hook for modules to affect the services available to a user. - -.SH The configuration file(s) - -When a -.BR Linux-PAM -aware privilege granting application is started, it activates its -attachment to the PAM-API. This activation performs a number of -tasks, the most important being the reading of the configuration file(s): -.BR /etc/pam.conf "." -Alternatively, this may be the contents of the -.BR /etc/pam.d/ -directory. - -These files list the -.BR PAM "s" -that will do the authentication tasks required by this service, and -the appropriate behavior of the PAM-API in the event that individual -.BR PAM "s " -fail. - -.sp -The syntax of the -.B /etc/pam.conf -configuration file is as follows. The file is made -up of a list of rules, each rule is typically placed on a single line, -but may be extended with an escaped end of line: `\\'. Comments -are preceded with `#' marks and extend to the next end of line. - -.sp -The format of each rule is a space separated collection of tokens, the -first three being case-insensitive: - -.sp -.br -.BR " service type control module-path module-arguments" - -.sp -The syntax of files contained in the -.B /etc/pam.d/ -directory, are identical except for the absence of any -.I service -field. In this case, the -.I service -is the name of the file in the -.B /etc/pam.d/ -directory. This filename must be in lower case. - -.sp -An important feature of -.BR Linux-PAM ", " -is that a number of rules may be -.I stacked -to combine the services of a number of PAMs for a given authentication -task. - -.sp -The -.BR service -is typically the familiar name of the corresponding application: -.BR login -and -.BR su -are good examples. The -.BR service "-name, " other ", " -is reserved for giving -.I default -rules. Only lines that mention the current service (or in the absence -of such, the -.BR other -entries) will be associated with the given service-application. - -.sp -The -.BR type -is the management group that the rule corresponds to. It is used to -specify which of the management groups the subsequent module is to -be associated with. Valid entries are: -.BR account "; " -.BR auth "; " -.BR password "; " -and -.BR session "." -The meaning of each of these tokens was explained above. - -.sp -The third field, -.BR control ", " -indicates the behavior of the PAM-API should the module fail to -succeed in its authentication task. There are two types of syntax for -this control field: the simple one has a single simple keyword; the -more complicated one involves a square-bracketed selection of -.B value=action -pairs. - -.sp -For the simple (historical) syntax valid -.BR control -values are: -.BR requisite -- failure of such a PAM results in the immediate termination of the -authentication process; -.BR required -- failure of such a PAM will ultimately lead to the PAM-API returning -failure but only after the remaining -.I stacked -modules (for this -.BR service -and -.BR type ")" -have been invoked; -.BR sufficient -- success of such a module is enough to satisfy the authentication -requirements of the stack of modules (if a prior -.BR required -module has failed the success of this one is -.IR ignored "); " -.BR optional -- the success or failure of this module is only important if it is the -only module in the stack associated with this -.BR service "+" type "." - -.sp -For the more complicated syntax valid -.B control -values have the following form: -.sp -.RB [value1=action1 value2=action2 ...] -.sp -Where -.B valueN -corresponds to the return code from the function invoked in the module -for which the line is defined. It is selected from one of these: -.BR success ; -.BR open_err ; -.BR symbol_err ; -.BR service_err ; -.BR system_err ; -.BR buf_err ; -.BR perm_denied ; -.BR auth_err ; -.BR cred_insufficient ; -.BR authinfo_unavail ; -.BR user_unknown ; -.BR maxtries ; -.BR new_authtok_reqd ; -.BR acct_expired ; -.BR session_err ; -.BR cred_unavail ; -.BR cred_expired ; -.BR cred_err ; -.BR no_module_data ; -.BR conv_err ; -.BR authtok_err ; -.BR authtok_recover_err ; -.BR authtok_lock_busy ; -.BR authtok_disable_aging ; -.BR try_again ; -.BR ignore ; -.BR abort ; -.BR authtok_expired ; -.BR module_unknown ; -.BR bad_item "; and" -.BR default . -The last of these, -.BR default , -implies 'all -.BR valueN 's -not mentioned explicitly. Note, the full list of PAM errors is -available in /usr/include/security/_pam_types.h . The -.B actionN -can be: an unsigned integer, -.BR J , -signifying an action of 'jump over the next J modules in the stack'; -or take one of the following forms: -.br -.B ignore -- when used with a stack of modules, the module's return status will -not contribute to the return code the application obtains; -.br -.B bad -- this action indicates that the return code should be thought of as -indicative of the module failing. If this module is the first in the -stack to fail, its status value will be used for that of the whole -stack. -.br -.B die -- equivalent to bad with the side effect of terminating the module -stack and PAM immediately returning to the application. -.br -.B ok -- this tells PAM that the administrator thinks this return code -should contribute directly to the return code of the full stack of -modules. In other words, if the former state of the stack would lead -to a return of -.BR PAM_SUCCESS , -the module's return code will override this value. Note, if the former -state of the stack holds some value that is indicative of a modules -failure, this 'ok' value will not be used to override that value. -.br -.B done -- equivalent to ok with the side effect of terminating the module -stack and PAM immediately returning to the application. -.br -.B reset -- clear all memory of the state of the module stack and start again -with the next stacked module. - -.sp -.BR module-path -- this is either the full filename of the PAM to be used by the -application (it begins with a '/'), or a relative pathname from the -default module location: -.BR /lib/security/ . - -.sp -.BR module-arguments -- these are a space separated list of tokens that can be used to -modify the specific behavior of the given PAM. Such arguments will be -documented for each individual module. - -.SH "FILES" -.BR /etc/pam.conf " - the configuration file" -.br -.BR /etc/pam.d/ " - the" -.BR Linux-PAM -configuration directory. Generally, if this directory is present, the -.B /etc/pam.conf -file is ignored. -.br -.BR /lib/libpam.so.X " - the dynamic library" -.br -.BR /lib/security/*.so " - the PAMs - -.SH ERRORS -Typically errors generated by the -.BR Linux-PAM -system of libraries, will be written to -.BR syslog "(3)." - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. -.br -Contains additional features, but remains backwardly compatible with -this RFC. - -.SH BUGS -.sp 2 -None known. - -.SH "SEE ALSO" - -The three -.BR Linux-PAM -Guides, for -.BR "system administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam.conf.8 b/doc/man/pam.conf.8 deleted file mode 100644 index d067b559..00000000 --- a/doc/man/pam.conf.8 +++ /dev/null @@ -1 +0,0 @@ -.so pam.8 diff --git a/doc/man/pam.d.8 b/doc/man/pam.d.8 deleted file mode 100644 index d067b559..00000000 --- a/doc/man/pam.d.8 +++ /dev/null @@ -1 +0,0 @@ -.so pam.8 diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3 deleted file mode 100644 index ba1bc52e..00000000 --- a/doc/man/pam_authenticate.3 +++ /dev/null @@ -1,91 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.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 -.sp -.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_authenticate - -.br -Use this function to authenticate an applicant user. It is linked -.I dynamically -to the authentication modules by -.BR Linux-PAM ". " -It is the task of these module to perform such an authentication. The -specific nature of the authentication is not the concern of the -application. - -.br -Following successful completion, the -.BR name -of the authenticated user will be present in the -.BR Linux-PAM -item -.BR PAM_USER ". " -This item may be recovered with a call to -.BR pam_get_item "(3)." - -.br -The application developer should note that the modules may request -that the user enter their username via the conversation mechanism (see -.BR pam_start "(3))." -Should this be the case, the user-prompt string can be set via -the -.BR PAM_USER_PROMPT -item (see -.BR pam_set_item "(3))." - -.SH "RETURN VALUE" -On success -.BR PAM_SUCCESS -is returned. All other returns should be considered -authentication failures and will be -.I delayed -by an amount specified with prior calls to -.BR pam_fail_delay "(3). " -Specific failures that demand special attention are the following: -.TP -.B PAM_ABORT -the application should exit immediately. Of course, -.BR pam_end "(3)" -should be called first. - -.TP -.B PAM_MAXTRIES -the application has tried too many times to authenticate the -user, authentication should not be attempted again. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_get_item "(3) " -.BR pam_fail_delay "(3) " -and -.BR pam_strerror "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3 deleted file mode 100644 index 63904da3..00000000 --- a/doc/man/pam_chauthtok.3 +++ /dev/null @@ -1,101 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.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 -.sp -.BI "int pam_chauthtok(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_chauthtok - -.br -Use this function to rejuvenate the authentication tokens (passwords -etc.) of an applicant user. - -.br -Note, the application should not pre-authenticate the user, as this is -performed (if required) by the -.BR Linux-PAM -framework. - -.br -The -.I flags -argument can -.I optionally -take the value, -.BR PAM_CHANGE_EXPIRED_AUTHTOK "." -In such cases the framework is only required to update those -authentication tokens that have expired. Without this argument, the -framework will attempt to obtain new tokens for all configured -authentication mechanisms. The details of the types and number of such -schemes should not concern the calling application. - -.SH RETURN VALUE -A successful return from this function will be indicated with -.BR PAM_SUCCESS "." - -.br -Specific errors of special interest when calling this function are - -.br -.BR PAM_AUTHTOK_ERROR -- a valid new token was not obtained - -.br -.BR PAM_AUTHTOK_RECOVERY_ERR -- old authentication token was not available - -.br -.BR PAM_AUTHTOK_LOCK_BUSY -- a resource needed to update the token was locked (try again later) - -.br -.BR PAM_AUTHTOK_DISABLE_AGING -- one or more of the authentication modules does not honor -authentication token aging - -.br -.BR PAM_TRY_AGAIN -- one or more authentication mechanism is not prepared to update a -token at this time - -.br -In general other return values may be returned. They should be treated -as indicating failure. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_authenticate "(3), " -.BR pam_setcred "(3), " -.BR pam_get_item "(3), " -.BR pam_strerror "(3) " -and -.BR pam "(8)." - -.br -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3 deleted file mode 100644 index d851700c..00000000 --- a/doc/man/pam_close_session.3 +++ /dev/null @@ -1 +0,0 @@ -.so pam_open_session.3 diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3 deleted file mode 100644 index de999f24..00000000 --- a/doc/man/pam_end.3 +++ /dev/null @@ -1 +0,0 @@ -.so pam_start.3 diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3 deleted file mode 100644 index f6cd238a..00000000 --- a/doc/man/pam_fail_delay.3 +++ /dev/null @@ -1,130 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.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 -.br -or, -.br -.B #include -.sp -.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");" -.sp 2 -.SH DESCRIPTION -.br -It is often possible to attack an authentication scheme by exploiting -the time it takes the scheme to deny access to an applicant user. In -cases of -.I short -timeouts, it may prove possible to attempt a -.I brute force -dictionary attack -- with an automated process, the attacker tries all -possible passwords to gain access to the system. In other cases, -where individual failures can take measurable amounts of time -(indicating the nature of the failure), an attacker can obtain useful -information about the authentication process. These latter attacks -make use of procedural delays that constitute a -.I covert channel -of useful information. - -.br -To minimize the effectiveness of such attacks, it is desirable to -introduce a random delay in a failed authentication process. -.B Linux-PAM -provides such a facility. The delay occurs upon failure of the -.BR pam_authenticate "(3) " -and -.BR pam_chauthtok "(3) " -functions. It occurs -.I after -all authentication modules have been called, but -.I before -control is returned to the service application. - -.br -The function, -.BR pam_fail_delay "(3)," -is used to specify a required minimum for the length of the -failure-delay; the -.I usec -argument. This function can be called by the service application -and/or the authentication modules, both may have an interest in -delaying a reapplication for service by the user. The length of the -delay is computed at the time it is required. Its length is -pseudo-gausianly distributed about the -.I maximum -requested value; the resultant delay will differ by as much as 25% of -this maximum requested value (both up and down). - -.br -On return from -.BR pam_authenticate "(3) or " pam_chauthtok "(3)," -independent of success or failure, the new requested delay is reset to -its default value: zero. - -.SH EXAMPLE -.br -For example, a -.B login -application may require a failure delay of roughly 3 seconds. It will -contain the following code: -.sp -.br -.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );" -.br -.B " pam_authenticate(pamh, 0);" -.sp -.br -if the modules do not request a delay, the failure delay will be -between 2.25 and 3.75 seconds. - -.br -However, the modules, invoked in the authentication process, may -also request delays: -.sp -.br -.RB " (module #1) " "pam_fail_delay(pamh, 2000000);" -.sp -.br -.RB " (module #2) " "pam_fail_delay(pamh, 4000000);" -.sp -.br -in this case, it is the largest requested value that is used to -compute the actual failed delay: here between 3 and 5 seconds. - -.SH "RETURN VALUE" -Following a successful call to -.BR pam_fail_delay "(3), " PAM_SUCCESS -is returned. All other returns should be considered serious failures. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -Under consideration by the X/Open group for future inclusion in the -PAM RFC. 1996/1/10 - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_get_item "(3) " -and -.BR pam_strerror "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_get_item.3 b/doc/man/pam_get_item.3 deleted file mode 100644 index f4f0d462..00000000 --- a/doc/man/pam_get_item.3 +++ /dev/null @@ -1 +0,0 @@ -.so pam_set_item.3 diff --git a/doc/man/pam_open_session.3 b/doc/man/pam_open_session.3 deleted file mode 100644 index 4e63b5c4..00000000 --- a/doc/man/pam_open_session.3 +++ /dev/null @@ -1,99 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.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 -.sp -.BI "int pam_open_session(pam_handle_t " *pamh ", int " flags ");" -.sp -.BI "int pam_close_session(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION - -PAM provides management-hooks for the initialization and termination -of a session. - -.TP -.B pam_open_session -.br -Use this function to signal that an authenticated user session has -begun. It should be called only after the user is properly identified -and (where necessary) has been granted their credentials with -.BR pam_authenticate "(3)" -and -.BR pam_setcred "(3)" -respectively. - -.br -Some types of functions associated with session -initialization are logging for the purposes of system-audit and -mounting directories (the user's home directory for example). These -should not concern the application. It should be noted that the -.I effective -uid, -.BR geteuid "(2)," -of the application should be of sufficient privilege to perform such -tasks. - -.TP -.B pam_close_session -.br -Use this function to signal that a user session has -terminated. In general this function may not need to be located in the -same application as the initialization function, -.BR pam_open_session "." - -.br -Typically, this function will undo the actions of -.BR pam_open_session "." -That is, log audit information concerning the end of the user session -or unmount the user's home directory. Apart from having sufficient -privilege the details of the session termination should not concern -the calling application. It is good programming practice, however, to -cease acting on behalf of the user on returning from this call. - -.SH RETURN VALUE -A successful return from the session management functions will be -indicated with -.BR PAM_SUCCESS "." - -.br -The specific error indicating a failure to open or close a session is -.BR PAM_SESSION_ERR "." -In general other return values may be returned. They should be treated -as indicating failure. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -OSF-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_authenticate "(3), " -.BR pam_setcred "(3), " -.BR pam_get_item "(3), " -.BR pam_strerror "(3) " -and -.BR pam "(3)." - -.br -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_set_item.3 b/doc/man/pam_set_item.3 deleted file mode 100644 index b0582778..00000000 --- a/doc/man/pam_set_item.3 +++ /dev/null @@ -1,55 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996,1997 -.TH PAM_SET_ITEM 3 "2001 Jan 21" "Linux-PAM" "App. Programmers' Manual" -.SH NAME - -pam_set_item, pam_get_item \- item manipulation under PAM - -.SH SYNOPSIS -.B #include -.br -or -.br -.B #include -.sp -.BI "int pam_set_item(pam_handle_t " *pamh ", int " item_type ", void " *item ");" -.sp -.BI "int pam_get_item(const pam_handle_t " *pamh ", int " item_type ", const void " **item_p ");" -.sp 2 -.SH DESCRIPTION -.B pam_set_item -.sp -.B pam_set_item - -These functions are currently undocumented in a man page, but see the -end of this man page for more information (the PAM guides). - -On success -.BR PAM_SUCCESS -is returned, all other return values should be treated as errors. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam (8) -and -.BR pam_strerror "(3)." - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3 deleted file mode 100644 index 8c00fe71..00000000 --- a/doc/man/pam_setcred.3 +++ /dev/null @@ -1,79 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996,1997 -.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 -.sp -.BI "int pam_setcred(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_setcred - -This function is used to establish, maintain and delete the -credentials of a user. It should be called after a user has been -authenticated and before a session is opened for the user (with -.BR pam_open_session "(3))." - -It should be noted that credentials come in many forms. Examples -include: group memberships; ticket-files; and Linux-PAM environment -variables. For this reason, it is important that the basic identity -of the user is established, by the application, prior to a call to -this function. For example, the default -.BR Linux-PAM -environment variables should be set and also -.BR initgroups "(2) " -(or equivalent) should have been performed. - -.SH "VALID FLAGS" -.TP -.BR PAM_ESTABLISH_CRED -initialize the credentials for the user. - -.TP -.BR PAM_DELETE_CRED -delete the user's credentials. - -.TP -.BR PAM_REINITIALIZE_CRED -delete and then initialize the user's credentials. - -.TP -.BR PAM_REFRESH_CRED -extend the lifetime of the existing credentials. - -.SH "RETURN VALUE" - -On success -.BR PAM_SUCCESS -is returned, all other return values should be treated as errors. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_authenticate "(3), " -.BR pam_strerror "(3)" -and -.BR pam_open_session "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3 deleted file mode 100644 index 9c11fd73..00000000 --- a/doc/man/pam_start.3 +++ /dev/null @@ -1,98 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.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 -.sp -.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");" -.sp -.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");" -.sp 2 -.SH DESCRIPTION -.TP -.B pam_start -Initialize the -.I Linux-PAM -library. Identifying the application with a particular -.IR service -name. The -.IR user "name" -can take the value -.IR NULL ", " -if not known at the time the interface is initialized. The -conversation structure is passed to the library via the -.IR conv -argument. (For a complete description of this and other structures -the reader is directed to the more verbose -.IR Linux-PAM -application developers' guide). Upon successful initialization, an -opaque pointer-handle for future access to the library is returned -through the contents of the -.IR pamh_p -pointer. - -.TP -.B pam_end -Terminate the -.B Linux-PAM -library. The service application associated with the -.IR pamh -handle, is terminated. The argument, -.IR pam_status ", " -passes the value most recently returned to the application from the -library; it indicates the manner in which the library should be -shutdown. Besides carrying a return value, this argument may be -logically OR'd with -.IR PAM_DATA_SILENT -to indicate that the module should not treat the call too -seriously. It is generally used to indicate that the current closing -of the library is in a -.IR fork "(2)ed" -process, and that the parent will take care of cleaning up things that -exist outside of the current process space (files etc.). - -.SH "RETURN VALUE" -.TP -.B pam_start -.TP -.B pam_end -On success, -.BR PAM_SUCCESS -is returned - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. -.sp -Note, the -.BR PAM_DATA_SILENT -flag is pending acceptance with the DCE (as of 1996/12/4). - -.SH BUGS -.sp 2 -None known. - -.SH "SEE ALSO" - -.BR fork "(2), " -.BR pam_authenticate "(3), " -.BR pam_acct_mgmt "(3), " -.BR pam_open_session "(3), " -and -.BR pam_chauthtok "(3)." - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3 deleted file mode 100644 index 01ee0635..00000000 --- a/doc/man/pam_strerror.3 +++ /dev/null @@ -1,51 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" ripped off from Rick Faith's getgroups man page -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.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 -.br -or, -.br -.B #include -.sp -.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");" -.sp 2 -.SH DESCRIPTION -.B pam_strerror - -This function returns some text describing the -.BR Linux-PAM -error associated with the -.B pam_error -argument. - -.SH "RETURN VALUE" - -On success this function returns a description of the indicated -error. Should the function not recognize the error, ``Unknown -Linux-PAM error'' is returned. - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -This function should be internationalized. - -.SH "SEE ALSO" - -.BR pam "(8). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/man/template-man b/doc/man/template-man deleted file mode 100644 index b8159eb6..00000000 --- a/doc/man/template-man +++ /dev/null @@ -1,52 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.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 -.sp -.BI "int pam_???(pam_handle_t " pamh ", int " flags); -.sp 2 -.SH DESCRIPTION -.TP -.B pam_??? -Here goes the -.I explanation -it may be quite -.IR long . -.TP -.SH "RETURN VALUE" -.B pam_??? -On success... -.BR PAM_SUCCESS -is returned -.TP -.SH ERRORS -May be translated to text with -.BR pam_strerror "(2). " - -.SH "CONFORMING TO" -.B pam_??? -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_??? "(2), " -and -.BR pam_??? "(2). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " diff --git a/doc/modules/README b/doc/modules/README deleted file mode 100644 index 448aefc7..00000000 --- a/doc/modules/README +++ /dev/null @@ -1,13 +0,0 @@ -$Id$ - -This directory contains a number of sgml sub-files. One for each -documented module. They contain a description of each module and give -some indication of its reliability. - -Additionally, there is a 'module.sgml-template' file which should be -used as a blank form for new module descriptions. - -Please feel free to submit amendments/comments etc. regarding these -files to: - - Andrew G. Morgan diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template deleted file mode 100644 index 16a93c79..00000000 --- a/doc/modules/module.sgml-template +++ /dev/null @@ -1,170 +0,0 @@ - - - [*Familiar full name of module*, eg. The "allow all" module.] - -Synopsis - -

- - -Module Name: -[ - insert the name of the module - - Blank is not permitted. -] - -Author[s]: - -[ - Insert author names here - - Blank is not permitted. If in doubt, put "unknown" if the - author wishes to remain anonymous, put "anonymous". -] - -Maintainer: - -[ - Insert names and date-begun of most recent maintainer. -] - -Management groups provided: - -[ - 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! -] - -Cryptographically sensitive: - -[ - 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. -] - -Security rating: - -[ - 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. -] - -Clean code base: - -[ - 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 :) -] - -System dependencies: - -[ - here we list config files, dynamic libraries needed, system - resources, kernel options.. etc. - - Blank = nothing more than libc required. -] - -Network aware: - -[ - Does the module base its behavior on probing a network - connection? Does it expect to be protected by the - application? - - Blank = Ignorance of network. -] - - - -Overview of module - -[ - some text describing the intended actions of the module - general comments mainly (specifics in sections - below). -] - -[ - - [ now we have a level subsection for each of the - management groups. Include as many as there are groups - listed above in the synopsis ] - -[ Account | Authentication | Password | Session ] component - -

- - -Recognized arguments: - -[ - 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! -] - -Description: - -[ - This component of the module performs the task of ... -] - -Examples/suggested usage: - -[ - Here we list some doos and don'ts for this module. -] - - - - diff --git a/doc/modules/pam_access.sgml b/doc/modules/pam_access.sgml deleted file mode 100644 index 8a910d13..00000000 --- a/doc/modules/pam_access.sgml +++ /dev/null @@ -1,117 +0,0 @@ - - - The access module - -Synopsis - -

- - -Module Name: - -pam_access - - -Author[s]: - -Alexei Nogin <alexei@nogin.dnttm.ru> - -Maintainer: - -Management groups provided: - -account - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Requires a configuration file. By default -/etc/security/access.conf is used but this can be overridden. - -Network aware: - -Through - -Overview of module - -

-Provides logdaemon style login access control. - - Account component - -

- - -Recognized arguments: - -accessfile=/path/to/file.conf; -fieldsep=separators - -Description: - -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 -The behavior of this module can be modified with the following -arguments: - - -accessfile=/path/to/file.conf - -indicate an alternative fieldsep=separators - -this option modifies the field separator character that -fieldsep=| will cause the default `:' -character to be treated as part of a field value and `|' becomes the -field separator. Doing this is useful in conjuction with a system that -wants to use pam_access with X based applications, since the - - -Examples/suggested usage: - -Use of module is recommended, for example, on administrative machines -such as /etc/pam.d style configurations where your modules live -in /lib/security, start by adding the following line to -/etc/pam.d/login, /etc/pam.d/rlogin, -/etc/pam.d/rsh and /etc/pam.d/ftp: - - - -account required /lib/security/pam_access.so - - - -Note that use of this module is not effective unless your system ignores -.rhosts files. See the the pam_rhosts_auth documentation. - -A sample access.conf configuration file is included with the -distribution. - - diff --git a/doc/modules/pam_chroot.sgml b/doc/modules/pam_chroot.sgml deleted file mode 100644 index ec739c18..00000000 --- a/doc/modules/pam_chroot.sgml +++ /dev/null @@ -1,86 +0,0 @@ - - -Chroot - -Synopsis - -

- - -Module Name: -Author: -Bruce Campbell <brucec@humbug.org.au> - -Maintainer: -Author; proposed on 20/11/96 - email for status - -Management groups provided: -account; session; authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: -Unwritten. - -System dependencies: - -Network aware: -Expects localhost. - - - -Overview of module - -

-This module is intended to provide a transparent wrapper around the -average user, one that puts them in a fake file-system (eg, their -'/' is really /some/where/else). - -

-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. - -Account component: - -

-Authentication component: - -

-Session component: - -

- - - -Recognized arguments: -Arguments and logging levels for the PAM version are being worked on. - -Description: - -Examples/suggested usage: -Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm', -'cp' and 'ed' in there is a bit... -

-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.) - - - - diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml deleted file mode 100644 index 008e49f6..00000000 --- a/doc/modules/pam_cracklib.sgml +++ /dev/null @@ -1,304 +0,0 @@ - - -Cracklib pluggable password strength-checker - -Synopsis - -

- - -Module Name: - -pam_cracklib - -Author: - -Cristian Gafton <gafton@redhat.com> - -Maintainer: - -Author. - -Management groups provided: - -password - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Requires the system library /usr/lib/cracklib_dict. - -Network aware: - - - -Overview of module - -

-This module can be plugged into the -This module works in the following manner: it first calls the -Cracklib 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: - - - - -

-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. - -Password component - -

- - -Recognized arguments: - -Description: - -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. - -

-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. - -

-The default action may be modified in a number of ways using the -arguments recognized by the module: - - - other, -upper, lower and Cracklib 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 minlen. 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. - - = 0) This is the maximum credit for having digits in the new password. If -you have less than or = 0) This is the maximum credit for having upper case letters in the new -password. If you have less than or = 0) This is the maximum credit for having lower case letters in the new -password. If you have less than or = 0) This is the maximum credit for having other characters in the new -password. If you have less than or - -Examples/suggested usage: - -

-For an example of the use of this module, we show how it may be -stacked with the password component of - -# -# 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 - - - -

-Another example (in the /etc/pam.d/passwd format) is for the -case that you want to use md5 password encryption: - - -#%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 - - - -

-And here is another example in case you don't want to use credits: - - -#%PAM-1.0 -# -# These lines require the user to select a password with a minimum -# length of 8 and with at least 1 digit number, 1 upper case letter, -# and 1 other character -# -password required pam_cracklib.so \ - dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8 -password required pam_pwdb.so use_authtok nullok md5 - - - -

-In this example we simply say that the password must have a minimum -length of 8: - - -#%PAM-1.0 -# -# These lines require the user to select a password with a mimimum -# length of 8. He gets no credits and he is not forced to use -# digit numbers, upper case letters etc. -# -password required pam_cracklib.so \ - dcredit=0 ucredit=0 ocredit=0 lcredit=0 minlen=8 -password required pam_pwdb.so use_authtok nullok md5 - - - - - - diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml deleted file mode 100644 index 6953231f..00000000 --- a/doc/modules/pam_deny.sgml +++ /dev/null @@ -1,177 +0,0 @@ - - -The locking-out module - -Synopsis - -

- - -Module Name: -pam_deny - -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -current Management groups provided: -account; authentication; password; session - -Cryptographically sensitive: - -Security rating: - -Clean code base: -clean. - -System dependencies: - -Network aware: - - - -Overview of module - -

-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 , this module -might be suitable for using for default (the Account component - -

- - -Recognized arguments: - -Description: - -This component does nothing other than return a failure. The -failure type is Examples/suggested usage: - -Stacking this module with type -The following example would make it impossible to login: - - -# -# add this line to your other login entries to disable all accounts -# -login account required pam_deny.so - - - - - -Authentication component - -

- - -Recognized arguments: - -Description: - -This component does nothing other than return a failure. The failure -type is Examples/suggested usage: - -To deny access to default applications with this component of the - - -# -# add this line to your existing OTHER entries to prevent -# authentication succeeding with default applications. -# -OTHER auth required pam_deny.so - - - - - -Password component - -

- - -Recognized arguments: - -Description: - -This component of the module denies the user the opportunity to change -their password. It always responds with Examples/suggested usage: - -This module should be used to prevent an application from updating the -applicant user's password. For example, to prevent - -# -# 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 - - - - - -Session component - -

- - -Recognized arguments: - -Description: - -This aspect of the module prevents an application from starting a -session on the host computer. - -Examples/suggested usage: - -Together with another session module, that displays a message of the -day perhaps ( - -# -# An example to see how to configure login to refuse the user a -# session (politely) -# -login session required pam_motd.so \ - motd=/etc/system_time -login session required pam_deny.so - - - - - - diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml deleted file mode 100644 index d795d591..00000000 --- a/doc/modules/pam_env.sgml +++ /dev/null @@ -1,141 +0,0 @@ - - -Set/unset environment variables - -Synopsis - -

- - -Module Name: -Author: -Dave Kinchlea <kinch@kinch.ark.com> - -Maintainer: -Author - -Management groups provided: -Authentication (setcred) - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -/etc/security/pam_env.conf - -Network aware: - - - -Overview of module - -

-This module allows the (un)setting of environment variables. Supported -is the use of previously set environment variables as well as -PAM_ITEMs such as PAM_RHOST. - -Authentication component - -

- - -Recognized arguments: -Description: -This module allows you to (un)set arbitrary environment variables -using fixed strings, the value of previously set environment variables -and/or -All is controlled via a configuration file (by default, -/etc/security/pam_env.conf but can be overriden with -conffile argument). Each line starts with the variable name, -there are then two possible options for each variable DEFAULT -and OVERRIDE. DEFAULT allows an administrator to -set the value of the variable to some default value, if none is -supplied then the empty string is assumed. The OVERRIDE -option tells pam_env that it should enter in its value (overriding the -default value) if there is one to use. OVERRIDE is not used, -"" is assumed and no override will be done. - -

- - -VARIABLE [DEFAULT=[value]] [OVERRIDE=[value]] - - - -

-(Possibly non-existent) environment variables may be used in values -using the ${string} syntax and (possibly -non-existent) @{string} syntax. Both the $ -and @ characters can be backslash-escaped to be used -as literal values (as in \$. Double quotes may -be used in values (but not environment variable names) when white -space is needed the full value must be delimited by the quotes and -embedded or escaped quotes are not supported. - -

-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 -The behavior of this module can be modified with one of the following -flags: - -

- - -/etc/security/pam_env.conf is used as -the configuration file. This option overrides the default. You must -supply a complete path + file name. - -/etc/environment is used to load KEY=VAL -pairs directly into the env. This option overrides the default. You must -supply a complete path + file name. - - - -Examples/suggested usage: - -See sample pam_env.conf for more information and examples. - - - - - - - - - - - - - - diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml deleted file mode 100644 index 4d3b4e84..00000000 --- a/doc/modules/pam_filter.sgml +++ /dev/null @@ -1,150 +0,0 @@ - - -The filter module - -Synopsis - -

- - -Module Name: - -pam_filter - -Author: - -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: - -Author. - -Management groups provided: - -account; authentication; password; session - -Cryptographically sensitive: - -Not yet. - -Security rating: - -Clean code base: - -This module compiles cleanly on Linux based systems. - -System dependencies: - -To function it requires Network aware: - - - -Overview of module - -

-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). - -Account+Authentication+Password+Session components - -

- - -Recognized arguments: - -Description: - -Each component of the module has the potential to invoke the desired -filter. The filter is always -The behavior of the module can be significantly altered by the -arguments passed to it in the - -Permitted values for -For the case of the account component. Either -For the case of the password component, - -Examples/suggested usage: - -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 - - -# -# 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 - - - - - - diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml deleted file mode 100644 index a9444733..00000000 --- a/doc/modules/pam_ftp.sgml +++ /dev/null @@ -1,93 +0,0 @@ - - -Anonymous access module - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author. - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: -prompts for email address of user; easily spoofed (XXX - needs work) - - - -Overview of module - -

-The purpose of this module is to provide a pluggable anonymous ftp -mode of access. - -Authentication component - -

- - -Recognized arguments: -Description: - -This module intercepts the user's name and password. If the name is -`` -The behavior of the module can be modified with the following flags: - - - -Examples/suggested usage: - -An example of the use of this module is provided in the configuration -file section . With care, this -module could be used to provide new/temporary account anonymous -login. - - - - diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml deleted file mode 100644 index 0d8550d4..00000000 --- a/doc/modules/pam_group.sgml +++ /dev/null @@ -1,108 +0,0 @@ - - -The group access module - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author. - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: -Sensitive to Clean code base: - -System dependencies: -Requires an /etc/security/group.conf file. Can be compiled -with or without Network aware: -Only through correctly set - -Overview of module - -

-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. - -Authentication component - -

- - -Recognized arguments: - -Description: - -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 /etc/security/group.conf file. - -Examples/suggested usage: - -For this module to function correctly there must be a correctly -formatted /etc/security/groups.conf 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 -` - -services ; ttys ; users ; times ; groups - - -Here the first four fields share the syntax of the pam_time -configuration file; /etc/security/pam_time.conf, and the last -field, the -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 -The pam_group module fuctions in parallel with the -/etc/group file. If the user is granted any groups based on -the behavior of this module, they are granted in addition to -those entries /etc/group (or equivalent). - - - - diff --git a/doc/modules/pam_issue.sgml b/doc/modules/pam_issue.sgml deleted file mode 100644 index 1f617e3b..00000000 --- a/doc/modules/pam_issue.sgml +++ /dev/null @@ -1,120 +0,0 @@ - - -Add issue file to user prompt - -Synopsis - -

- - -Module Name: -Author: -Ben Collins <bcollins@debian.org> - -Maintainer: -Author - -Management groups provided: -Authentication (pam_sm_authenticate) - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: - - - -Overview of module - -

-This module prepends the issue file (/etc/issue by default) when -prompting for a username. - -Authentication component - -

- - -Recognized arguments: -Description: -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 \x format). -

-Recognized escapes: - - - - -

-The behavior of this module can be modified with one of the following -flags: - -

- - - - -Examples/suggested usage: - -login auth pam_issue.so issue=/etc/issue - - - - diff --git a/doc/modules/pam_krb4.sgml b/doc/modules/pam_krb4.sgml deleted file mode 100644 index 16ce8183..00000000 --- a/doc/modules/pam_krb4.sgml +++ /dev/null @@ -1,126 +0,0 @@ - - -The Kerberos 4 module. - -Synopsis - -

- - -Module Name: -Author: -Derrick J. Brashear <shadow@dementia.org> - -Maintainer: -Author. - -Management groups provided: -authentication; password; session - -Cryptographically sensitive: -uses API - -Security rating: - -Clean code base: - -System dependencies: -libraries - Network aware: -Gets Kerberos ticket granting ticket via a Kerberos key distribution -center reached via the network. - - - -Overview of module - -

-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. - - Session component - -

- - -Recognized arguments: - -Description: - -This component of the module currently sets the user's Examples/suggested usage: - -This part of the module won't be terribly useful until we can change -the environment from within a - - Password component - -

- - -Recognized arguments: -Description: - -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. - -Examples/suggested usage: - -This should only be used with a real Kerberos v4 - - Authentication component - -

- - -Recognized arguments: -Description: - -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 Examples/suggested usage: - -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. - - - - diff --git a/doc/modules/pam_lastlog.sgml b/doc/modules/pam_lastlog.sgml deleted file mode 100644 index a00f76b1..00000000 --- a/doc/modules/pam_lastlog.sgml +++ /dev/null @@ -1,119 +0,0 @@ - - -The last login module - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author - -Management groups provided: -auth - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -uses information contained in the /var/log/lastlog file. - -Network aware: - - - -Overview of module - -

-This session module maintains the /var/log/lastlog file. Adding -an open entry when called via the pam_open_seesion() function -and completing it when pam_close_session() 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. - -Session component - -

- - -Recognized arguments: -Description: - -

-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 -/var/log/lastlog file. - -

-The behavior of this module can be modified with one of the following -flags: - -

- -/var/log/lastlog file. - -/var/log/lastlog file does not contain any old entries -for the user, indicate that the user has never previously logged in -with a ``welcome..." message. - - - -Examples/suggested usage: - -This module can be used to indicate that the user has new mail when -they /etc/pam.d/XXX file: - - -# -# When were we last here? -# -session optional pam_lastlog.so - - - -

-Note, some applications may perform this function themselves. In such -cases, this module is not necessary. - - - - diff --git a/doc/modules/pam_limits.sgml b/doc/modules/pam_limits.sgml deleted file mode 100644 index 44f057c4..00000000 --- a/doc/modules/pam_limits.sgml +++ /dev/null @@ -1,247 +0,0 @@ - - -The resource limits module - -Synopsis - -

- - -Module Name: -Authors: -Cristian Gafton <gafton@redhat.com> -Thanks are also due to Elliot Lee <sopwith@redhat.com> -for his comments on improving this module. - -Maintainer: -Cristian Gafton - 1996/11/20 - -Management groups provided: -session - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -requires an /etc/security/limits.conf file and kernel support -for resource limits. Also uses the library, Network aware: - - - -Overview of module - -

-This module, through the Session component - -

- - -Recognized arguments: -conf=/path/to/file.conf; change_uid; -utmp_early - -Description: - -Through the contents of the configuration file, -/etc/security/limits.conf, resource limits are placed on -users' sessions. Users of -The behavior of this module can be modified with the following -arguments: - - -conf=/path/to/file.conf - -indicate an alternative - -Examples/suggested usage: - -In order to use this module the system administrator must first create -a /etc/security/limits.conf). This file describes the resource -limits the superuser wishes to impose on users and groups. No limits -are imposed on -Each line of the configuration file describes a limit for a user in -the form: - - - - - - -

-The fields listed above should be filled as follows... -<domain> can be: - - a username - a groupname, with @group syntax - the wild-card the wild-card %group syntax - - -

-<type> can have the three values: - - - - -

-<item> can be one of the following: - - - -

-Note, if you specify a type of ``-'' but neglect to supply the - -In general, individual limits have priority over group limits, so if -you impose no limits for -Also, please note that all limit settings are set -In the -The -The following is an example configuration file: - - -# EXAMPLE /etc/security/limits.conf file: -# ======================================= -# -* 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 - - -Note, the use of -Note, that wild-cards - %group is specified - -See the following examples: - - -# EXAMPLE /etc/security/limits.conf file: -# -* - maxlogins 2 -@faculty - maxlogins 4 -% - maxlogins 30 -%student - maxlogins 10 - - -Explanation: every user can login 2 times, members of the -For the services that need resources limits (login for example) put -the following line in /etc/pam.conf as the last line for that -service (usually after the pam_unix session line: - - -# -# Resource limits imposed on login sessions via pam_limits -# -login session required pam_limits.so - - - - - - diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml deleted file mode 100644 index 3754f57e..00000000 --- a/doc/modules/pam_listfile.sgml +++ /dev/null @@ -1,138 +0,0 @@ - - -The list-file module - -Synopsis - -

- - -Module Name: -Author: -Elliot Lee <sopwith@cuc.edu> - -Maintainer: -Red Hat Software: -Michael K. Johnson <johnsonm@redhat.com> 1996/11/18 -(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: -clean - -System dependencies: - -Network aware: - - - -Overview of module - -

-The list-file module provides a way to deny or allow services based on -an arbitrary file. - -Authentication component - -

- - -Recognized arguments: - -onerr=succeed|fail; -sense=allow|deny; -file=filename; -item=user|tty|rhost|ruser|group|shell -apply=user|@group - -Description: - -The module gets the item of the type specified -- user specifies -the username, PAM_USER; tty specifies the name of the terminal -over which the request has been made, PAM_TTY; rhost specifies -the name of the remote host (if any) from which the request was made, -PAM_RHOST; and ruser specifies the name of the remote user -(if available) who made the request, PAM_RUSER -- and looks for -an instance of that item in the file filename. filename -contains one line per item listed. If the item is found, then if -sense=allow, PAM_SUCCESS is returned, causing the -authorization request to succeed; else if sense=deny, -PAM_AUTH_ERR is returned, causing the authorization -request to fail. - -

-If an error is encountered (for instance, if filename -does not exist, or a poorly-constructed argument is encountered), -then if onerr=succeed, PAM_SUCCESS is returned, -otherwise if onerr=fail, PAM_AUTH_ERR or -PAM_SERVICE_ERR (as appropriate) will be returned. - -

-An additional argument, apply=, can be used to restrict the -application of the above to a specific user -(apply=username) or a given group -(apply=@groupname). This added restriction is only -meaningful when used with the -Besides this last one, all arguments should be specified; do not count -on any default behavior, as it is subject to change. - -

-No credentials are awarded by this module. - -Examples/suggested usage: - -Classic ``ftpusers'' authentication can be implemented with this entry -in /etc/pam.conf: - - -# -# 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 - - -Note, users listed in /etc/ftpusers file are -(counterintuitively) -To allow login access only for certain users, you can use a - - -# -# permit login to users listed in /etc/loginusers -# -login auth required pam_listfile.so \ - onerr=fail item=user sense=allow file=/etc/loginusers - - - -

-For this example to work, all users who are allowed to use the login -service should be listed in the file /etc/loginusers. 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 -/etc/loginusers, or by listing a user who is able to - - diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml deleted file mode 100644 index 78ae95dc..00000000 --- a/doc/modules/pam_mail.sgml +++ /dev/null @@ -1,142 +0,0 @@ - - -The mail module - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author - -Management groups provided: -Authentication (credential) -Session (open) - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Default mail directory /var/spool/mail/ - -Network aware: - - - -Overview of module - -

-This module looks at the user's mail directory and indicates -whether the user has any mail in it. - -Session component - -

- - -Recognized arguments: -Description: - -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 -The behavior of this module can be modified with one of the following -flags: - -

- -/var/spool/mail. Note, if the supplied /var/spool/mail/u/s/user. - - - -Examples/suggested usage: - -This module can be used to indicate that the user has new mail when -they /etc/pam.conf file: - - -# -# do we have any mail? -# -login session optional pam_mail.so - - - -

-Note, if the mail spool file (be it /var/spool/mail/$USER or -a pathname given with the dir= parameter) is a directory then -pam_mail assumes it is in the Qmail Maildir format. - -

-Note, some applications may perform this function themselves. In such -cases, this module is not necessary. - - - -Authentication component - -

-Then authentication companent works the same as the session component, -except that everything is done during the pam_setcred() phase. - - diff --git a/doc/modules/pam_mkhomedir.sgml b/doc/modules/pam_mkhomedir.sgml deleted file mode 100644 index 075e16f9..00000000 --- a/doc/modules/pam_mkhomedir.sgml +++ /dev/null @@ -1,83 +0,0 @@ - - -Create home directories on initial login - -Synopsis - -

- - -Module Name: -Author: -Jason Gunthorpe <jgg@ualberta.ca> - -Maintainer: -Ben Collins <bcollins@debian.org> - -Management groups provided: -Session - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: - - - -Overview of module - -

-Creates home directories on the fly for authenticated users. - -Session component - -

- - -Recognized arguments: -Description: -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. - -

-The behavior of this module can be modified with one of the following -flags: - -

- - - - -Examples/suggested usage: - -session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 - - - - diff --git a/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml deleted file mode 100644 index 8ddc6392..00000000 --- a/doc/modules/pam_motd.sgml +++ /dev/null @@ -1,77 +0,0 @@ - - -Output the motd file - -Synopsis - -

- - -Module Name: -Author: -Ben Collins <bcollins@debian.org> - -Maintainer: -Author - -Management groups provided: -Session (open) - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: - - - -Overview of module - -

-This module outputs the motd file (/etc/motd by default) upon -successful login. - -Session component - -

- - -Recognized arguments: -Description: -This module allows you to have arbitrary motd's (message of the day) -output after a succesful login. By default this file is /etc/motd, -but is configurable to any file. - -

-The behavior of this module can be modified with one of the following -flags: - -

- - - - -Examples/suggested usage: - -login session pam_motd.so motd=/etc/motd - - - - diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml deleted file mode 100644 index 52cf02a5..00000000 --- a/doc/modules/pam_nologin.sgml +++ /dev/null @@ -1,81 +0,0 @@ - - -The no-login module - -Synopsis - -

- - -Module Name: -Author: -Written by Michael K. Johnson <johnsonm@redhat.com> - -Maintainer: - -Management groups provided: -account; authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: - - - -Overview of module - -

-Provides standard Unix Authentication component - -

- - -Recognized arguments: -successok, file=<Description: - -Provides standard Unix /etc/nologin exists, only root is allowed to log in; other -users are turned away with an error message (and the module returns -/etc/nologin. - -

-If the file /etc/nologin does not exist, this module defaults -to returning -The administrator can override the default nologin file with the -Examples/suggested usage: - -In order to make this module effective, all login methods should be -secured by it. It should be used as a required method listed -before any sufficient methods in order to get standard Unix -nologin semantics. Note, the use of - - diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml deleted file mode 100644 index fe616ac3..00000000 --- a/doc/modules/pam_permit.sgml +++ /dev/null @@ -1,83 +0,0 @@ - - -The promiscuous module - -Synopsis - -

- - -Module Name: -pam_permit - -Author: -Andrew G. Morgan, <morgan@kernel.org> - -Maintainer: -Linux-PAM maintainer. - -Management groups provided: -account; authentication; password; session - -Cryptographically sensitive: - -Security rating: -VERY LOW. Use with extreme caution. - -Clean code base: -Clean. - -System dependencies: - -Network aware: - - - -Overview of module - -

-This module is very dangerous. It should be used with extreme -caution. Its action is always to permit access. It does nothing else. - -Account+Authentication+Password+Session components - -

- - -Recognized arguments: - -Description: - -No matter what management group, the action of this module is to -simply return -In the case of authentication, the user's name will be acquired. Many -applications become confused if this name is unknown. - -Examples/suggested usage: - -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: - - -# -# 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 - - - - - - diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml deleted file mode 100644 index 2ee102e1..00000000 --- a/doc/modules/pam_pwdb.sgml +++ /dev/null @@ -1,249 +0,0 @@ - - -The Password-Database module - -Synopsis - -

- - -Module Name: -pam_pwdb - -Author: -Cristian Gafton <gafton@redhat.com> -and Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Red Hat. - -Management groups provided: -account; authentication; password; session - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Requires properly configured Network aware: - - - -Overview of module - -

-This module is a pluggable replacement for the libpwdb. - -Account component - -

- - -Recognized arguments: -Description: - -The Examples/suggested usage: - -In its accounting mode, this module can be inserted as follows: - - -# -# Ensure users account and password are still active -# -login account required pam_pwdb.so - - - - - -Authentication component - -

- - -Recognized arguments: -Description: - -The -The default action of this module is to not permit the user access to -a service if their -When given the argument -The argument, nodelay, 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. - -

-Remaining arguments, supported by the other functions of this module, -are silently ignored. Other arguments are logged as errors through - -A helper binary, pwdb_chkpwd, 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 xlock to work without being setuid-root. - -

-The likeauth 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. - -Examples/suggested usage: - -The correct functionality of this module is dictated by having an -appropriate /etc/pwdb.conf file, the user -databases specified there dictate the source of the authenticated -user's record. - - - -Password component - -

- - -Recognized arguments: -Description: - -This part of the -In the case of conventional unix databases (which store the password -encrypted) the -The -The argument -The -The Examples/suggested usage: - -An example of the stacking of this module with respect to the -pluggable password checking module, - -Session component - -

- - -Recognized arguments: - -Description: - -No arguments are recognized by this module component. Its action is -simply to log the username and the service-type to -Examples/suggested usage: - -The use of the session modules is straightforward: - - -# -# pwdb - unix like session opening and closing -# -login session required pam_pwdb.so - - - - - - diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml deleted file mode 100644 index 2bc4a9cd..00000000 --- a/doc/modules/pam_radius.sgml +++ /dev/null @@ -1,117 +0,0 @@ - - -The RADIUS session module - -Synopsis - -

- - -Module Name: -Author: -Cristian Gafton <gafton@redhat.com> - -Maintainer: -Author. - -Management groups provided: -session - -Cryptographically sensitive: -This module does not deal with passwords - -Security rating: - -Clean code base: -gcc reports 1 warning when compiling /usr/include/rpc/clnt.h. -Hey, is not my fault ! - -System dependencies: - -Network aware: - -yes; this is a network module (independent of application). - - - -Overview of module - -

-This module is intended to provide the session service for users -authenticated with a RADIUS server. At the present stage, the only -option supported is the use of the RADIUS server as an accounting -server. - -Session component - -

- - -Recognized arguments: - -Description: - -This module is intended to provide the session service for users -authenticated with a RADIUS server. At the present stage, the only -option supported is the use of the RADIUS server as an -(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.) - -

-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. - -

-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. . - -Examples/suggested usage: - -For the services that need this module (/etc/pam.conf as the last line for that -service (usually after the pam_unix session line): - - -login session required pam_radius.so - - -Replace -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 /etc/raddb/server. -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 (/etc/raddb/dictionary). - - - - - diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml deleted file mode 100644 index 69885047..00000000 --- a/doc/modules/pam_rhosts.sgml +++ /dev/null @@ -1,164 +0,0 @@ - - -The rhosts module - -Synopsis - -

- - -Module Name: -Author: -Al Longyear <longyear@netcom.com> - -Maintainer: - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: -Clean. - -System dependencies: - -Network aware: -Standard - -Overview of module - -

-This module performs the standard network authentication for services, -as used by traditional implementations of Authentication component - -

- - -Recognized arguments: -Description: - -The authentication mechanism of this module is based on the contents -of two files; /etc/hosts.equiv (or #include <netdb.h>) and ~/.rhosts. 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 "/etc/hosts.equiv and their remote account -is identical to their local one, or if their remote account has an -entry in their personal configuration file. - -

-Some restrictions are applied to the attributes of the user's personal -configuration file: it must be a regular file (as defined by - -The module authenticates a remote user (internally specified by the -item -In the case of /etc/host.equiv file is -hosts_equiv_rootok option -should be used. Instead, the superuser must have a correctly configured -personal configuration file. - -

-The behavior of the module is modified by flags: - - - - -/etc/hosts.equiv file. - - -/etc/hosts.equiv for superuser. Without this -option /etc/hosts.equiv is not consulted for the superuser account. -This option has no effect if the no_hosts_equiv option is used. - - -~/.rhosts. - - -~/.rhosts 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. - - - - -Examples/suggested usage: - -To allow users to login from trusted remote machines, you should try -adding the following line to your /etc/pam.conf file - - -# -# No passwords required for users from hosts listed above. -# -login auth sufficient pam_rhosts_auth.so no_rhosts - - -Note, in this example, the system administrator has turned off all -/etc/host.equiv file, by replacing - - diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml deleted file mode 100644 index f6aa8a07..00000000 --- a/doc/modules/pam_rootok.sgml +++ /dev/null @@ -1,85 +0,0 @@ - - -The root access module - -Synopsis - -

- - -Module Name: -pam_rootok - -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Linux-PAM maintainer - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: -Clean. - -System dependencies: - -Network aware: - - - -Overview of module - -

-This module is for use in situations where the superuser wishes -to gain access to a service without having to enter a password. - -Authentication component - -

- - -Recognized arguments: -Description: - -This module authenticates the user if their Examples/suggested usage: - -In the case of the - -# -# su authentication. Root is granted access by default. -# -su auth sufficient pam_rootok.so -su auth required pam_unix_auth.so - - - -

-Note. For programs that are run by the superuser (or started when the -system boots) this module should not be used to authenticate users. - - - - diff --git a/doc/modules/pam_securetty.sgml b/doc/modules/pam_securetty.sgml deleted file mode 100644 index ceb1358c..00000000 --- a/doc/modules/pam_securetty.sgml +++ /dev/null @@ -1,72 +0,0 @@ - - -The securetty module - -Synopsis - -

- - -Module Name: -Author[s]: -Elliot Lee <sopwith@cuc.edu> - -Maintainer: -Red Hat Software: - -(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -/etc/securetty file - -Network aware: - -Requires the application to fill in the PAM_TTY item -correctly in order to act meaningfully. - - - -Overview of module - -

-Provides standard Unix securetty checking. - -Authentication component - -

- - -Recognized arguments: - -Description: - -Provides standard Unix securetty checking, which causes authentication -for root to fail unless PAM_TTY is set to a string listed in -the /etc/securetty file. For all other users, it succeeds. - -Examples/suggested usage: - -For canonical usage, should be listed as a required -authentication method before any sufficient authentication -methods. - - - - diff --git a/doc/modules/pam_tally.sgml b/doc/modules/pam_tally.sgml deleted file mode 100644 index eeb05518..00000000 --- a/doc/modules/pam_tally.sgml +++ /dev/null @@ -1,191 +0,0 @@ - - -The login counter (tallying) module - -Synopsis - -

- - -Module Name: -pam_tally - -Author[s]: -Tim Baverstock - -Maintainer: - -Management groups provided: -auth; account - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -A faillog file (default location /var/log/faillog) - -Network aware: - - - -Overview of module - -

-This module maintains a count of attempted accesses, can reset count -on success, can deny access if too many attempts fail. - -

-pam_tally comes in two parts: pam_tally.so and -pam_tally. The former is the PAM module and the latter, a -stand-alone program. pam_tally is an (optional) application -which can be used to interrogate and manipulate the counter file. It -can display users' counts, set individual counts, or clear all -counts. Setting artificially high counts may be useful for blocking -users without changing their passwords. For example, one might find it -useful to clear all counts every midnight from a cron job. - -

-The counts file is organized as a binary-word array, indexed by -uid. You can probably make sense of it with od, if you don't -want to use the supplied appliction. - -

-Note, there are some outstanding issues with this module: -pam_tally is very dependant on getpw*() - a database -of usernames would be much more flexible; the `keep a count of current -logins' bit has been #ifdef'd out and you can only reset the -counter on successful authentication, for now. - -Generic options accepted by both components -

- - onerr=(succeed|fail): - if something weird happens, such as unable to open the file, how - should the module react? - file=/where/to/keep/counts: - specify the file location for the counts. - The default location is /var/log/faillog. - - -Authentication component - -

- - -Recognized arguments: -onerr=(succeed|fail); -file=/where/to/keep/counts; -no_magic_root - -Description: - -

-The authentication component of this module increments the attempted -login counter. - -

-Examples/suggested usage: - -

-The module argument no_magic_root is used to indicate that if -the module is invoked by a user with uid=0, then the counter is -incremented. The sys-admin should use this for daemon-launched -services, like telnet/rsh/login. For user -launched services, like su, this argument should be omitted. - -

-By way of more explanation, when a process already running as root -tries to access some service, the access is magic, and -bypasses pam_tally's checks: this is handy for suing -from root into an account otherwise blocked. However, for services -like telnet or login, which always effectively run -from the root account, root (ie everyone) shouldn't be granted this -magic status, and the flag `no_magic_root' should be set in this -situation, as noted in the summary above. - - - -Account component - -

- - -Recognized arguments: -onerr=(succeed|fail); -file=/where/to/keep/counts; -deny=n; -no_magic_root; -even_deny_root_account; -reset; -no_reset; -per_user; -no_lock_time - -Description: - -

-The account component can deny access and/or reset the attempts -counter. It also checks to make sure that the counts file is a plain -file and not world writable. - -Examples/suggested usage: - -

-The deny=n option is used to deny access if tally -for this user exceeds n. The presence of -deny=n changes the default for -reset/no_reset to reset, unless the user -trying to gain access is root and the no_magic_root option -has NOT been specified. - -

-The no_magic_root option ensures that access attempts by root -DON'T ignore deny. Use this for daemon-based stuff, like -telnet/rsh/login. - -

-The even_deny_root_account option is used to ensure that the -root account can become unavailable. Note that magic root -trying to gain root bypasses this, but normal users can be locked out. - -

-The reset option instructs the module to reset count to 0 on -successful entry, even for magic root. The no_reset option is -used to instruct the module to not reset the count on successful -entry. This is the default unless deny exists and the user -attempting access is NOT magic root. - -

-If /var/log/faillog contains a non-zero .fail_max -field for this user then the per_user module argument will -ensure that the module uses this value and not the global -deny=n parameter. - -

-The no_lock_time option is for ensuring that the module does -not use the .fail_locktime field in /var/log/faillog for this -user. - -

-Normally, failed attempts to access root will NOT cause the -root account to become blocked, to prevent denial-of-service: if your -users aren't given shell accounts and root may only login via -su or at the machine console (not -telnet/rsh, etc), this is safe. If you really want -root to be blocked for some given service, use -even_deny_root_account. - - - - diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml deleted file mode 100644 index 8c5f677f..00000000 --- a/doc/modules/pam_time.sgml +++ /dev/null @@ -1,166 +0,0 @@ - - -Time control - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author - -Management groups provided: -account - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Requires a configuration file /etc/security/time.conf - -Network aware: -Through the - -Overview of module - -

-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. - -Account component - -

- - -Recognized arguments: - -Description: - -This module bases its actions on the rules listed in its configuration -file: /etc/security/time.conf. Each rule has the following -form, - - -In words, each rule occupies a line, terminated with a newline or the -beginning of a comment; a ` - - -By a logic list we mean a sequence of tokens (associated with the -appropriate !morgan&!root, indicating that this rule -does not apply to the user morgan nor to root; and -tty*&!ttyp*, which indicates that the rule applies only -to console terminals but not pseudoterminals. - - - -Mo Tu We Th Fr Sa Su Wk Wd Al - - -The last two of these being -The time range part is a pair of 24-hour times, - -

-Note, that the given time restriction is only applied when the first -three fields are satisfied by a user's application for service. - -

-For convenience and readability a rule can be extended beyond a single -line with a `\Examples/suggested usage: - -The use of this module is initiated with an entry in the - - -# -# apply pam_time accounting to login requests -# -login account required pam_time.so - - -where, here we are applying the module to the -Some examples of rules that can be placed in the -/etc/security/time.conf configuration file are the following: - - -login ; tty* & !ttyp* ; !root ; !Al0000-2400 -all users except for games ; * ; !waster ; Wd0000-2400 | Wk1800-0800 -games (configured to use Linux-PAM) are only to be accessed out of -working hours. This rule does not apply to the user - -

-Note, currently there is no daemon enforcing the end of a session. -This needs to be remedied. - -

-Poorly formatted rules are logged as errors using - - diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml deleted file mode 100644 index 286cd3f8..00000000 --- a/doc/modules/pam_unix.sgml +++ /dev/null @@ -1,288 +0,0 @@ - - -The Unix Password module - -Synopsis - -

- - -Module Name: -pam_unix - -Author: - -Maintainer: - -Management groups provided: -account; authentication; password; session - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: - - - -Overview of module - -

-This is the standard Unix authentication module. It uses standard calls -from the system's libraries to retrieve and set account information as -well as authentication. Usually this is obtained from the /etc/passwd -and the /etc/shadow file as well if shadow is enabled. - -Account component - -

- - -Recognized arguments: -Description: - -The Examples/suggested usage: - -In its accounting mode, this module can be inserted as follows: - - -# -# Ensure users account and password are still active -# -login account required pam_unix.so - - - - - -Authentication component - -

- - -Recognized arguments: -Description: - -The -The default action of this module is to not permit the user access to -a service if their -When given the argument -The argument, nodelay, 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. - -

-Remaining arguments, supported by the other functions of this module, -are silently ignored. Other arguments are logged as errors through - -A helper binary, unix_chkpwd, 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 xlock to work without being setuid-root. - -Examples/suggested usage: - -The correct functionality of this module is dictated by having an -appropriate /etc/nsswitch.conf file, the user -databases specified there dictate the source of the authenticated -user's record. -

-In its authentication mode, this module can be inserted as follows: - - -# -# Authenticate the user -# -login auth required pam_unix.so - - - - - -Password component - -

- - -Recognized arguments: -Description: - -This part of the -In the case of conventional unix databases (which store the password -encrypted) the -The -The argument -The -The -With the -The /etc/security/opasswd in order to force password change history -and keep the user from alternating between the same password too frequently. - -Examples/suggested usage: - -Standard usage: - - -# -# Change the users password -# -passwd password required pam_unix.so - - - -

-An example of the stacking of this module with respect to the -pluggable password checking module, - -# -# 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 - - - - - -Session component - -

- - -Recognized arguments: - -Description: - -No arguments are recognized by this module component. Its action is -simply to log the username and the service-type to -Examples/suggested usage: - -The use of the session modules is straightforward: - - -# -# session opening and closing -# -login session required pam_unix.so - - - - - - diff --git a/doc/modules/pam_userdb.sgml b/doc/modules/pam_userdb.sgml deleted file mode 100644 index bdbf80b8..00000000 --- a/doc/modules/pam_userdb.sgml +++ /dev/null @@ -1,112 +0,0 @@ - - -The userdb module - -Synopsis - -

- - -Module Name: -Author: -Cristian Gafton <gafton@redhat.com> - -Maintainer: -Author. - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Requires Berkeley DB. - -Network aware: - - - -Overview of module - -

-Look up users in a .db database and verify their password against -what is contained in that database. - -Authentication component - -

- - -Recognized arguments: -Description: - -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 -The action of the module may be modified from this default by one or -more of the following flags in the /etc/pam.d/<service> file. - - - - - -/etc/foodata -instead of /etc/foodata.db. - - - -Examples/suggested usage: - -This is a normal ftp configuration file (usually placed as /etc/pam.d/ftp -on most systems) that will accept for login users whose username/password pairs are -provided in the /tmp/dbtest.db file: - - - -#%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 - - - - - - diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml deleted file mode 100644 index 4c2e3e18..00000000 --- a/doc/modules/pam_warn.sgml +++ /dev/null @@ -1,67 +0,0 @@ - - -Warning logger module - -Synopsis - -

- - -Module Name: -Author: -Andrew G. Morgan <morgan@kernel.org> - -Maintainer: -Author. - -Management groups provided: -authentication; password - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: - -Network aware: -logs information about the remote user and host (if pam-items are known) - - - -Overview of module - -

-This module is principally for logging information about a -proposed authentication or application to update a password. - -Authentication+Password component - -

- - -Recognized arguments: - -Description: - -Log the service, terminal, user, remote user and remote host to -Examples/suggested usage: - -an example is provided in the configuration file section . - - - - diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml deleted file mode 100644 index 8c07a8b7..00000000 --- a/doc/modules/pam_wheel.sgml +++ /dev/null @@ -1,125 +0,0 @@ - - -The wheel module - -Synopsis - -

- - -Module Name: -Author: -Cristian Gafton <gafton@redhat.com> - -Maintainer: -Author. - -Management groups provided: -authentication - -Cryptographically sensitive: - -Security rating: - -Clean code base: - -System dependencies: -Requires libpwdb. - -Network aware: - - - -Overview of module - -

-Only permit root access to members of the wheel (Authentication component - -

- - -Recognized arguments: -Description: - -This module is used to enforce the so-called -The action of the module may be modified from this default by one or -more of the following flags in the /etc/pam.conf file. - - - - - - - - -Examples/suggested usage: - -To restrict access to superuser status to the members of the - - -# -# 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 - - - - - - diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml deleted file mode 100644 index 85a878a0..00000000 --- a/doc/pam_appl.sgml +++ /dev/null @@ -1,1782 +0,0 @@ - - - - -

- -The Linux-PAM Application Developers' Guide -<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2001/12/08 -<abstract> -This manual documents what an application developer needs to know -about the <bf>Linux-PAM</bf> library. It describes how an application -might use the <bf>Linux-PAM</bf> library to authenticate users. In -addition it contains a description of the funtions to be found in -<tt/libpam_misc/ library, that can be used in general applications. -Finally, it contains some comments on PAM related security issues for -the application developer. -</abstract> - -<toc> - -<sect>Introduction - -<sect1>Synopsis - -<p> -For general applications that wish to use the services provided by -<bf/Linux-PAM/ the following is a summary of the relevant linking -information: -<tscreen> -<verb> -#include <security/pam_appl.h> - -cc -o application .... -lpam -ldl -</verb> -</tscreen> - -<p> -In addition to <tt/libpam/, there is a library of miscellaneous -functions that make the job of writing <em/PAM-aware/ applications -easier (this library is not covered in the DCE-RFC for PAM and is -specific to the Linux-PAM distribution): -<tscreen> -<verb> -... -#include <security/pam_misc.h> - -cc -o application .... -lpam -lpam_misc -ldl -</verb> -</tscreen> - -<sect1> Description - -<p> -<bf>Linux-PAM</bf> (Pluggable Authentication Modules for Linux) is a -library that enables the local system administrator to choose how -individual applications authenticate users. For an overview of the -<bf>Linux-PAM</bf> library see the <bf/Linux-PAM/ System -Administrators' Guide. - -<p> -It is the purpose of the <bf>Linux-PAM</bf> project to liberate the -development of privilege granting software from the development of -secure and appropriate authentication schemes. This is accomplished -by providing a documented library of functions that an application may -use for all forms of user authentication management. This library -dynamically loads locally configured authentication modules that -actually perform the authentication tasks. - -<p> -From the perspective of an application developer the information -contained in the local configuration of the PAM library should not be -important. Indeed it is intended that an application treat the -functions documented here as a ``black box'' that will deal with all -aspects of user authentication. ``All aspects'' includes user -verification, account management, session initialization/termination -and also the resetting of passwords (<em/authentication tokens/). - -<sect>Overview - -<p> -Most service-giving applications are restricted. In other words, -their service is not available to all and every prospective client. -Instead, the applying client must jump through a number of hoops to -convince the serving application that they are authorized to obtain -service. - -The process of <em/authenticating/ a client is what PAM is designed to -manage. In addition to authentication, PAM provides account -management, credential management, session management and -authentication-token (password changing) management services. It is -important to realize when writing a PAM based application that these -services are provided in a manner that is <bf>transparent</bf> to -the application. That is to say, when the application is written, no -assumptions can be made about <em>how</em> the client will be -authenticated. - -<p> -The process of authentication is performed by the PAM library via a -call to <tt>pam_authenticate()</tt>. The return value of this -function will indicate whether a named client (the <em>user</em>) has -been authenticated. If the PAM library needs to prompt the user for -any information, such as their <em>name</em> or a <em>password</em> -then it will do so. If the PAM library is configured to authenticate -the user using some silent protocol, it will do this too. (This -latter case might be via some hardware interface for example.) - -<p> -It is important to note that the application must leave all decisions -about when to prompt the user at the discretion of the PAM library. - -<p> -The PAM library, however, must work equally well for different styles -of application. Some applications, like the familiar <tt>login</tt> -and <tt>passwd</tt> are terminal based applications, exchanges of -information with the client in these cases is as plain text messages. -Graphically based applications, however, have a more sophisticated -interface. They generally interact with the user via specially -constructed dialogue boxes. Additionally, network based services -require that text messages exchanged with the client are specially -formatted for automated processing: one such example is <tt>ftpd</tt> -which prefixes each exchanged message with a numeric identifier. - -<p> -The presentation of simple requests to a client is thus something very -dependent on the protocol that the serving application will use. In -spite of the fact that PAM demands that it drives the whole -authentication process, it is not possible to leave such protocol -subtleties up to the PAM library. To overcome this potential problem, -the application provides the PAM library with a <em>conversation</em> -function. This function is called from <bf>within</bf> the PAM -library and enables the PAM to directly interact with the client. The -sorts of things that this conversation function must be able to do are -prompt the user with text and/or obtain textual input from the user -for processing by the PAM library. The details of this function are -provided in a later section. - -<p> -For example, the conversation function may be called by the PAM library -with a request to prompt the user for a password. Its job is to -reformat the prompt request into a form that the client will -understand. In the case of <tt>ftpd</tt>, this might involve prefixing -the string with the number <tt>331</tt> and sending the request over -the network to a connected client. The conversation function will -then obtain any reply and, after extracting the typed password, will -return this string of text to the PAM library. Similar concerns need -to be addressed in the case of an X-based graphical server. - -<p> -There are a number of issues that need to be addressed when one is -porting an existing application to become PAM compliant. A section -below has been devoted to this: Porting legacy applications. - -<p> -Besides authentication, PAM provides other forms of management. -Session management is provided with calls to -<tt>pam_open_session()</tt> and <tt>pam_close_session()</tt>. What -these functions actually do is up to the local administrator. But -typically, they could be used to log entry and exit from the system or -for mounting and unmounting the user's home directory. If an -application provides continuous service for a period of time, it -should probably call these functions, first open after the user is -authenticated and then close when the service is terminated. - -<p> -Account management is another area that an application developer -should include with a call to <tt/pam_acct_mgmt()/. This call will -perform checks on the good health of the user's account (has it -expired etc.). One of the things this function may check is whether -the user's authentication token has expired - in such a case the -application may choose to attempt to update it with a call to -<tt/pam_chauthtok()/, although some applications are not suited to -this task (<em>ftp</em> for example) and in this case the application -should deny access to the user. - -<p> -PAM is also capable of setting and deleting the users credentials with -the call <tt>pam_setcred()</tt>. This function should always be -called after the user is authenticated and before service is offered -to the user. By convention, this should be the last call to the PAM -library before the PAM session is opened. What exactly a credential -is, is not well defined. However, some examples are given in the -glossary below. - -<sect>The public interface to <bf>Linux-PAM</bf> - -<p> -Firstly, the relevant include file for the <bf>Linux-PAM</bf> library -is <tt><security/pam_appl.h></tt>. It contains the definitions -for a number of functions. After listing these functions, we collect -some guiding remarks for programmers. - -<sect1>What can be expected by the application - -<p> -Below we document those functions in the <bf/Linux-PAM/ library that -may be called from an application. - -<sect2>Initialization of Linux-PAM -<label id="pam-start-section"> - -<p> -<tscreen> -<verb> -extern int pam_start(const char *service_name, const char *user, - const struct pam_conv *pam_conversation, - pam_handle_t **pamh); -</verb> -</tscreen> - -<p> -This is the first of the <bf>Linux-PAM</bf> functions that must be -called by an application. It initializes the interface and reads the -system configuration file, <tt>/etc/pam.conf</tt> (see the -<bf/Linux-PAM/ System Administrators' Guide). Following a successful -return (<tt/PAM_SUCCESS/) the contents of <tt/*pamh/ is a handle that -provides continuity for successive calls to the <bf/Linux-PAM/ -library. The arguments expected by <tt/pam_start/ are as follows: the -<tt/service_name/ of the program, the <tt/user/name of the individual -to be authenticated, a pointer to an application-supplied -<tt/pam_conv/ structure and a pointer to a <tt/pam_handle_t/ -<em/pointer/. - -<p> -The <tt>pam_conv</tt> structure is discussed more fully in the section -<ref id="the-conversation-function" name="below">. The -<tt>pam_handle_t</tt> is a <em>blind</em> structure and the -application should not attempt to probe it directly for information. -Instead the <bf>Linux-PAM</bf> library provides the functions -<tt>pam_set_item</tt> and <tt>pam_get_item</tt>. These functions are -documented below. - -<sect2>Termination of the library -<label id="pam-end-section"> - -<p> -<tscreen> -<verb> -extern int pam_end(pam_handle_t *pamh, int pam_status); -</verb> -</tscreen> - -<p> -This function is the last function an application should call in the -<bf>Linux-PAM</bf> library. Upon return the handle <tt/pamh/ is no -longer valid and all memory associated with it will be invalid (likely -to cause a segmentation fault if accessed). - -<p> -Under normal conditions the argument <tt/pam_status/ has the value -PAM_SUCCESS, but in the event of an unsuccessful application for -service the appropriate <bf/Linux-PAM/ error-return value should be -used here. Note, <tt/pam_end()/ unconditionally shuts down the -authentication stack associated with the <tt/pamh/ handle. The value -taken by <tt/pam_status/ is used as an argument to the module specific -callback functions, <tt/cleanup()/ (see the <bf/Linux-PAM/ <htmlurl -url="pam_modules.html" name="Module Developers' Guide">). In this way, -the module can be given notification of the pass/fail nature of the -tear-down process, and perform any last minute tasks that are -appropriate to the module before it is unlinked. - -<sect2>Setting PAM items -<label id="pam-set-item-section"> - -<p> -<tscreen> -<verb> -extern int pam_set_item(pam_handle_t *pamh, int item_type, - const void *item); -</verb> -</tscreen> - -<p>This function is used to (re)set the value of one of the following -<bf/item_type/s: - -<p><descrip> -<tag><tt/PAM_SERVICE/</tag> - - The service name (which identifies that PAM stack that - <tt/libpam/ will use to authenticate the program). - -<tag><tt/PAM_USER/</tag> - - The username of the entity under who's identity service will - be given. That is, following authentication, <tt/PAM_USER/ - identifies the local entity that gets to use the - service. Note, this value can be mapped from something (eg., - "<tt/anonymous/") to something else (eg. "<tt/guest119/") by - any module in the PAM stack. As such an application should - consult the value of <tt/PAM_USER/ after each call to a - <tt/pam_*()/ function. - -<tag><tt/PAM_USER_PROMPT/</tag> - - The string used when prompting for a user's name. The default - value for this string is ``Please enter username: ''. - -<tag><tt/PAM_TTY/</tag> - - The terminal name: prefixed by <tt>/dev/</tt> if it is a - device file; for graphical, X-based, applications the value - for this item should be the <tt/$DISPLAY/ variable. - -<tag><tt/PAM_RUSER/</tag> - - The requesting entity: user's username for a locally - requesting user or a remote requesting user - generally an - application or module will attempt to supply the value that is - most strongly authenticated (a local account before a remote - one. The level of trust in this value is embodied in the - actual authentication stack associated with the application, - so it is ultimately at the discretion of the system - administrator. It should generally match the current - <tt/PAM_RHOST/ value. That is, "<tt/PAM_RUSER@PAM_RHOST/" - should always identify the requesting user. In some cases, - <tt/PAM_RUSER/ may be NULL. In such situations, it is unclear - who the requesting entity is. - -<tag><tt/PAM_RHOST/</tag> - - The requesting hostname (the hostname of the machine from - which the <tt/PAM_RUSER/ entity is requesting service). That - is "<tt/PAM_RUSER@PAM_RHOST/" does identify the requesting - user. "<tt/luser@localhost/" or "<tt/evil@evilcom.com/" are - valid "<tt/PAM_RUSER@PAM_RHOST/" examples. In some - applications, <tt/PAM_RHOST/ may be NULL. In such situations, - it is unclear where the authentication request is originating - from. - -<tag><tt/PAM_CONV/</tag> - - The conversation structure (see section <ref - id="the-conversation-function" name="below">). - -<tag><tt/PAM_FAIL_DELAY/</tag> A function pointer to redirect - centrally managed failure delays (see section <ref - id="the-failure-delay-function" name="below">). - -</descrip> - -<p> -For all <tt/item_type/s, other than <tt/PAM_CONV/ and -<tt/PAM_FAIL_DELAY/, <tt/item/ is a pointer to a <tt><NUL></tt> -terminated character string. In the case of <tt/PAM_CONV/, <tt/item/ -points to an initialized <tt/pam_conv/ structure (see section <ref -id="the-conversation-function" name="below">). In the case of -<tt/PAM_FAIL_DELAY/, <tt/item/ is a function pointer: <tt/void -(*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)/ (see -section <ref id="the-failure-delay-function" name="below">). - -<p> -A successful call to this function returns <tt/PAM_SUCCESS/. However, -the application should expect at least one the following errors: - -<p> -<descrip> -<tag><tt/PAM_SYSTEM_ERR/</tag> - The <tt/pam_handle_t/ passed as a first argument to this - function was invalid. -<tag><tt/PAM_PERM_DENIED/</tag> - An attempt was made to replace the conversation structure with - a <tt/NULL/ value. -<tag><tt/PAM_BUF_ERR/</tag> - The function ran out of memory making a copy of the item. -<tag><tt/PAM_BAD_ITEM/</tag> - The application attempted to set an undefined or inaccessible - item. -</descrip> - -<sect2>Getting PAM items -<label id="pam-get-item-section"> - -<p> -<tscreen> -<verb> -extern int pam_get_item(const pam_handle_t *pamh, int item_type, - const void **item); -</verb> -</tscreen> - -<p> -This function is used to obtain the value of the indicated -<tt/item_type/. Upon successful return, <tt/*item/ contains a pointer -to the value of the corresponding item. Note, this is a pointer to -the <em/actual/ data and should <em/not/ be <tt/free()/'ed or -over-written! - -<p> -A successful call is signaled by a return value of <tt/PAM_SUCCESS/. -However, the application should expect one of the following errors: - -<p> -<descrip> -<tag><tt/PAM_SYSTEM_ERR/</tag> - The <tt/pam_handle_t/ passed as a first argument to this - function was invalid. -<tag><tt/PAM_PERM_DENIED/</tag> - The value of <tt/item/ was <tt/NULL/. -<tag><tt/PAM_BAD_ITEM/</tag> - The application attempted to set an undefined or inaccessible - item. -</descrip> - -<p> -Note, in the case of an error, the contents of <tt/item/ is not -modified - that is, it retains its pre-call value. One should take -care to initialize this value prior to calling -<tt/pam_get_item()/. Since, if its value - despite the -<tt/pam_get_item()/ function failing - is to be used the consequences -are undefined. - -<sect2>Understanding errors -<label id="pam-strerror-section"> - -<p> -<tscreen> -<verb> -extern const char *pam_strerror(pam_handle_t *pamh, int errnum); -</verb> -</tscreen> - -<p> -This function returns some text describing the <bf>Linux-PAM</bf> -error associated with the argument <tt/errnum/. If the error is not -recognized ``<tt/Unknown Linux-PAM error/'' is returned. - -<sect2>Planning for delays -<label id="the-failure-delay-function"> - -<p> -<tscreen> -<verb> -extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec); -</verb> -</tscreen> - -<p> -This function is offered by <bf/Linux-PAM/ to facilitate time delays -following a failed call to <tt/pam_authenticate()/ and before control -is returned to the application. When using this function the -application programmer should check if it is available with, -<tscreen> -<verb> -#ifdef PAM_FAIL_DELAY - .... -#endif /* PAM_FAIL_DELAY */ -</verb> -</tscreen> - - -<p> -Generally, an application requests that a user is authenticated by -<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or -<tt/pam_chauthtok()/. These functions call each of the <em/stacked/ -authentication modules listed in the relevant <bf/Linux-PAM/ -configuration file. As directed by this file, one of more of the -modules may fail causing the <tt/pam_...()/ call to return an error. -It is desirable for there to also be a pause before the application -continues. The principal reason for such a delay is security: a delay -acts to discourage <em/brute force/ dictionary attacks primarily, but -also helps hinder <em/timed/ (covert channel) attacks. - -<p> -The <tt/pam_fail_delay()/ function provides the mechanism by which an -application or module can suggest a minimum delay (of <tt/micro_sec/ -<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time -requested with this function. Should <tt/pam_authenticate()/ fail, -the failing return to the application is delayed by an amount of time -randomly distributed (by up to 25%) about this longest value. - -<p> -Independent of success, the delay time is reset to its zero default -value when <bf/Linux-PAM/ returns control to the application. - -<p> -For applications written with a single thread that are event driven in -nature, <tt/libpam/ generating this delay may be undesirable. Instead, -the application may want to register the delay in some other way. For -example, in a single threaded server that serves multiple -authentication requests from a single event loop, the application -might want to simply mark a given connection as blocked until an -application timer expires. For this reason, <bf/Linux-PAM/ supplies -the <tt/PAM_FAIL_DELAY/ item. It can be queried and set with -<tt/pam_get_item()/ and <tt/pam_set_item()/ respectively. The value -used to set it should be a function pointer of the following -prototype: - -<tscreen> -<verb> -void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr); -</verb> -</tscreen> - -The arguments being the <tt/retval/ return code of the module stack, -the <tt/usec_delay/ micro-second delay that libpam is requesting and -the <tt/appdata_ptr/ that the application has associated with the -current <tt/pamh/ (<tt/pam_handle_t/). This last value was set by the -application when it called <tt/pam_start/ or explicitly with -<tt/pam_set_item(... , PAM_CONV, ...)/. Note, if <tt/PAM_FAIL_DELAY/ -is unset (or set to <tt/NULL/), then <tt/libpam/ will perform any -delay. - -<sect2>Authenticating the user - -<p> -<tscreen> -<verb> -extern int pam_authenticate(pam_handle_t *pamh, int flags); -</verb> -</tscreen> - -<p> -This function serves as an interface to the authentication mechanisms -of the loaded modules. The single <em/optional/ flag, which may be -logically OR'd with <tt/PAM_SILENT/, takes the following value, - -<p><descrip> - -<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag> - Instruct the authentication modules to return -<tt/PAM_AUTH_ERR/ if the user does not have a registered -authorization token---it is set to <tt/NULL/ in the system database. -</descrip> - -<p> -The value returned by this function is one of the following: - -<p><descrip> - -<tag><tt/PAM_AUTH_ERR/</tag> - The user was not authenticated -<tag><tt/PAM_CRED_INSUFFICIENT/</tag> - For some reason the application does not have sufficient -credentials to authenticate the user. -<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag> - The modules were not able to access the authentication -information. This might be due to a network or hardware failure etc. -<tag><tt/PAM_USER_UNKNOWN/</tag> - The supplied username is not known to the authentication -service -<tag><tt/PAM_MAXTRIES/</tag> - One or more of the authentication modules has reached its -limit of tries authenticating the user. Do not try again. - -</descrip> - -<p> -If one or more of the authentication modules fails to load, for -whatever reason, this function will return <tt/PAM_ABORT/. - -<sect2>Setting user credentials -<label id="pam-setcred-section"> - -<p> -<tscreen> -<verb> -extern int pam_setcred(pam_handle_t *pamh, int flags); -</verb> -</tscreen> - -<p> -This function is used to set the module-specific credentials of the -user. It is usually called after the user has been authenticated, -after the account management function has been called but before a -session has been opened for the user. - -<p> -A credential is something that the user possesses. It is some -property, such as a <em>Kerberos</em> ticket, or a supplementary group -membership that make up the uniqueness of a given user. On a Linux -(or UN*X system) the user's <tt>UID</tt> and <tt>GID</tt>'s are -credentials too. However, it has been decided that these properties -(along with the default supplementary groups of which the user is a -member) are credentials that should be set directly by the application -and not by PAM. - -<p> -This function simply calls the <tt/pam_sm_setcred/ functions of each -of the loaded modules. Valid <tt/flags/, any one of which, may be -logically OR'd with <tt/PAM_SILENT/, are: - -<p><descrip> -<tag><tt/PAM_ESTABLISH_CRED/</tag> - Set the credentials for the authentication service, -<tag><tt/PAM_DELETE_CRED/</tag> - Delete the credentials associated with the authentication service, -<tag><tt/PAM_REINITIALIZE_CRED/</tag> - Reinitialize the user credentials, and -<tag><tt/PAM_REFRESH_CRED/</tag> - Extend the lifetime of the user credentials. -</descrip> - -<p> -A successful return is signalled with <tt/PAM_SUCCESS/. Errors that -are especially relevant to this function are the following: - -<p><descrip> -<tag><tt/PAM_CRED_UNAVAIL/</tag> - A module cannot retrieve the user's credentials. -<tag><tt/PAM_CRED_EXPIRED/</tag> - The user's credentials have expired. -<tag><tt/PAM_USER_UNKNOWN/</tag> - The user is not known to an authentication module. -<tag><tt/PAM_CRED_ERR/</tag> - A module was unable to set the credentials of the user. -</descrip> - -<sect2>Account management - -<p> -<tscreen> -<verb> -extern int pam_acct_mgmt(pam_handle_t *pamh, int flags); -</verb> -</tscreen> - -<p> -This function is typically called after the user has been -authenticated. It establishes whether the user's account is healthy. -That is to say, whether the user's account is still active and whether -the user is permitted to gain access to the system at this time. -Valid flags, any one of which, may be logically OR'd with -<tt/PAM_SILENT/, and are the same as those applicable to the -<tt/flags/ argument of <tt/pam_authenticate/. - -<p> -This function simply calls the corresponding functions of each of the -loaded modules, as instructed by the configuration file, -<tt>/etc/pam.conf</tt>. - -<p> -The normal response from this function is <tt/PAM_SUCCESS/, however, -specific failures are indicated by the following error returns: - -<descrip> -<tag><tt/PAM_AUTHTOKEN_REQD/</tag> -The user <bf/is/ valid but their authentication token has -<em/expired/. The correct response to this return-value is to require -that the user satisfies the <tt/pam_chauthtok()/ function before -obtaining service. It may not be possible for some applications to do -this. In such cases, the user should be denied access until such time -as they can update their password. - -<tag><tt/PAM_ACCT_EXPIRED/</tag> - The user is no longer permitted to access the system. -<tag><tt/PAM_AUTH_ERR/</tag> - There was an authentication error. - -<tag><tt/PAM_PERM_DENIED/</tag> - The user is not permitted to gain access at this time. -<tag><tt/PAM_USER_UNKNOWN/</tag> - The user is not known to a module's account management -component. - -</descrip> - -<sect2>Updating authentication tokens -<label id="pam-chauthtok-section"> - -<p> -<tscreen> -<verb> -extern int pam_chauthtok(pam_handle_t *pamh, const int flags); -</verb> -</tscreen> - -<p> -This function is used to change the authentication token for a given -user (as indicated by the state associated with the handle, -<tt/pamh/). The following is a valid but optional flag which may be -logically OR'd with <tt/PAM_SILENT/, - -<descrip> -<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag> - This argument indicates to the modules that the users -authentication token (password) should only be changed if it has -expired. -</descrip> - -<p> -Note, if this argument is not passed, the application requires that -<em/all/ authentication tokens are to be changed. - -<p> -<tt/PAM_SUCCESS/ is the only successful return value, valid -error-returns are: - -<descrip> -<tag><tt/PAM_AUTHTOK_ERR/</tag> - A module was unable to obtain the new authentication token. - -<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag> - A module was unable to obtain the old authentication token. - -<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag> - One or more of the modules was unable to change the -authentication token since it is currently locked. - -<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag> - Authentication token aging has been disabled for at least one -of the modules. - -<tag><tt/PAM_PERM_DENIED/</tag> - Permission denied. - -<tag><tt/PAM_TRY_AGAIN/</tag> - Not all of the modules were in a position to update the -authentication token(s). In such a case none of the user's -authentication tokens are updated. - -<tag><tt/PAM_USER_UNKNOWN/</tag> - The user is not known to the authentication token changing -service. - -</descrip> - -<sect2>Session initialization -<label id="pam-open-session-section"> - -<p> -<tscreen> -<verb> -extern int pam_open_session(pam_handle_t *pamh, int flags); -</verb> -</tscreen> - -<p> -This function is used to indicate that an authenticated session has -begun. It is used to inform the modules that the user is currently in -a session. It should be possible for the <bf>Linux-PAM</bf> library -to open a session and close the same session (see section <ref -id="pam-close-session-section" name="below">) from different -applications. - -<p> -Currently, this function simply calls each of the corresponding -functions of the loaded modules. The only valid flag is -<tt/PAM_SILENT/ and this is, of course, <em/optional/. - -<p> -If any of the <em/required/ loaded modules are unable to open a -session for the user, this function will return <tt/PAM_SESSION_ERR/. - -<sect2>Terminating sessions -<label id="pam-close-session-section"> - -<p> -<tscreen> -<verb> -extern int pam_close_session(pam_handle_t *pamh, int flags); -</verb> -</tscreen> - -<p> -This function is used to indicate that an authenticated session has -ended. It is used to inform the modules that the user is exiting a -session. It should be possible for the <bf>Linux-PAM</bf> library to -open a session and close the same session from different applications. - -<p> -This function simply calls each of the corresponding functions of the -loaded modules in the same order that they were invoked with -<tt/pam_open_session()/. The only valid flag is <tt/PAM_SILENT/ and -this is, of course, <em/optional/. - -<p> -If any of the <em/required/ loaded modules are unable to close a -session for the user, this function will return <tt/PAM_SESSION_ERR/. - -<sect2>Setting PAM environment variables -<label id="pam-putenv-section"> - -<p> -The <tt/libpam/ library associates with each PAM-handle (<tt/pamh/), a -set of <it/PAM environment variables/. These variables are intended to -hold the session environment variables that the user will inherit when -the session is granted and the authenticated user obtains access to -the requested service. For example, when <tt/login/ has finally given -the user a shell, the environment (as viewed with the command -<tt/env/) will be what <tt/libpam/ was maintaining as the PAM -environment for that service application. Note, these variables are not -the environment variables of the <tt/login/ application. This is -principally for two reasons: <tt/login/ may want to have an -environment that cannot be seen or manipulated by a user; and -<tt/login/ (or whatever the serving application is) may be maintaining -a number of parallel sessions, via different <tt/pamh/ values, at the -same time and a single environment may not be appropriately shared -between each of these. The PAM environment may contain variables -seeded by the applicant user's client program, for example, and as -such it is not appropriate for one applicant to interfere with the -environment of another applicant. - -<p> -<tscreen> -<verb> -extern int pam_putenv(pam_handle_t *pamh, const char *name_value); -</verb> -</tscreen> - -<p> -This function attempts to (re)set a <bf/Linux-PAM/ environment -variable. The <tt/name_value/ argument is a single <tt/NUL/ terminated -string of one of the following forms: -<descrip> -<tag>``<tt/NAME=value of variable/''</tag> - -In this case the environment variable of the given <tt/NAME/ is set to -the indicated value: ``<tt/value of variable/''. If this variable is -already known, it is overwritten. Otherwise it is added to the -<bf/Linux-PAM/ environment. - -<tag>``<tt/NAME=/''</tag> - -This function sets the variable to an empty value. It is listed -separately to indicate that this is the correct way to achieve such a -setting. - -<tag>``<tt/NAME/''</tag> - -Without an `<tt/=/' the <tt/pam_putenv()/ function will delete the -corresponding variable from the <bf/Linux-PAM/ environment. - -</descrip> - -<p> -Success is indicated with a return value of <tt/PAM_SUCCESS/. Failure -is indicated by one of the following returns: - -<descrip> -<tag><tt/PAM_PERM_DENIED/</tag> - name given is a <tt/NULL/ pointer - -<tag><tt/PAM_BAD_ITEM/</tag> - variable requested (for deletion) is not currently set - -<tag><tt/PAM_ABORT/</tag> - the <bf/Linux-PAM/ handle, <tt/pamh/, is corrupt - -<tag><tt/PAM_BUF_ERR/</tag> - failed to allocate memory when attempting update - -</descrip> - -<sect2>Getting a PAM environment variable -<label id="pam-getenv-section"> - -<p> -<tscreen> -<verb> -extern const char *pam_getenv(pam_handle_t *pamh, const char *name); -</verb> -</tscreen> - -<p> -Obtain the value of the indicated <bf/Linux-PAM/ environment -variable. On error, internal failure or the unavailability of the -given variable (unspecified), this function simply returns <tt/NULL/. - -<sect2>Getting the PAM environment -<label id="pam-getenvlist-section"> - -<p> -<tscreen> -<verb> -extern const char * const *pam_getenvlist(pam_handle_t *pamh); -</verb> -</tscreen> - -<p> -The PAM environment variables (see section <ref -id="pam-putenv-section" name="above">) are a complete set of enviroment -variables that are associated with a PAM-handle (<tt/pamh/). They -represent the contents of the <it/regular/ environment variables of -the authenticated user when service is granted. - -<p> -Th function, <tt>pam_getenvlist()</tt> returns a pointer to a complete, -<tt/malloc()/'d, copy of the PAM environment. It is a pointer to a -duplicated list of environment variables. It should be noted that -this memory will never be <tt/free()'d/ by <tt/libpam/. Once obtained -by a call to <tt/pam_getenvlist()/, <bf>it is the responsibility of -the calling application</bf> to <tt/free()/ this memory. - -<p> -The format of the memory is a <tt/malloc()/'d array of <tt/char */ -pointers, the last element of which is set to <tt/NULL/. Each of the -non-<tt/NULL/ entries in this array point to a <tt/NUL/ terminated and -<tt/malloc()/'d <tt/char/ string of the form: -<tt/"/<it/name/<tt/=/<it/value/<tt/"/. - -<p> -It is by design, and not a coincidence, that the format and contents -of the returned array matches that required for the third argument of -the <tt/execle(3)/ function call. - -<sect1>What is expected of an application - -<sect2>The conversation function -<label id="the-conversation-function"> - -<p> -An application must provide a ``conversation function''. It is used -for direct communication between a loaded module and the application -and will typically provide a means for the module to prompt the user -for a password etc. . The structure, <tt/pam_conv/, is defined by -including <tt><security/pam_appl.h></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><security/pam_appl.h></tt> as: - -<p> -<tscreen> -<verb> -struct pam_message { - int msg_style; - const char *msg; -}; -</verb> -</tscreen> - -<p> -Valid choices for <tt/msg_style/ are: - -<p><descrip> -<tag><tt/PAM_PROMPT_ECHO_OFF/</tag> - Obtain a string without echoing any text -<tag><tt/PAM_PROMPT_ECHO_ON/</tag> - Obtain a string whilst echoing text -<tag><tt/PAM_ERROR_MSG/</tag> - Display an error -<tag><tt/PAM_TEXT_INFO/</tag> - Display some text. -</descrip> - -<p> -The point of having an array of messages is that it becomes possible -to pass a number of things to the application in a single call from -the module. It can also be convenient for the application that related -things come at once: a windows based application can then present a -single form with many messages/prompts on at once. - -<p> -In passing, it is worth noting that there is a descrepency between the -way Linux-PAM handles the <tt/const struct pam_message **msg/ -conversation function argument from the way that Solaris' PAM (and -derivitives, known to include HP/UX, <em/are there others?/) -does. Linux-PAM interprets the <tt/msg/ argument as entirely -equivalent to the following prototype <tt/const struct pam_message -*msg[]/ (which, in spirit, is consistent with the commonly used -prototypes for <tt/argv/ argument to the familiar <tt/main()/ -function: <tt/char **argv/; and <tt/char *argv[]/). Said another way -Linux-PAM interprets the <tt/msg/ argument as a pointer to an array of -<tt/num_meg/ read only 'struct pam_message' <em/pointers/. Solaris' -PAM implementation interprets this argument as a pointer to a pointer -to an array of <tt/num_meg/ <tt/pam_message/ structures. Fortunately, -perhaps, for most module/application developers when <tt/num_msg/ has -a value of one these two definitions are entirely -equivalent. Unfortunately, casually raising this number to two has led -to unanticipated compatibility problems. - -<p> -For what its worth the two known module writer work-arounds for trying -to maintain source level compatibility with both PAM implementations -are: -<itemize> -<item> never call the conversation function with <tt/num_msg/ greater -than one. -<item> set up <tt/msg/ as doubly referenced so both types of -conversation function can find the messages. That is, make -<p><tscreen> -<verb> -msg[n] = & (( *msg )[n]) -</verb> -</tscreen> -</itemize> -<p> -The response (from the application to the module) passing structure is -defined by including <tt><security/pam_appl.h></tt> as: - -<p><tscreen><verb> -struct pam_response { - char *resp; - int resp_retcode; -}; -</verb></tscreen> - -<p> -Currently, there are no definitions for <tt/resp_retcode/ values; the -normal value is <tt/0/. - -<p> -Prior to the 0.59 release of Linux-PAM, the length of the returned -<tt/pam_response/ array was equal to the number of <em/prompts/ (types -<tt/PAM_PROMPT_ECHO_OFF/ and <tt/PAM_PROMPT_ECHO_ON/) in the -<tt/pam_message/ array with which the conversation function was -called. This meant that it was not always necessary for the module to -<tt/free(3)/ the responses if the conversation function was only used -to display some text. - -<p> -Post Linux-PAM-0.59. The number of responses is always equal to the -<tt/num_msg/ conversation function argument. This is slightly easier -to program but does require that the response array is <tt/free(3)/'d -after every call to the conversation function. The index of the -responses corresponds directly to the prompt index in the -<tt/pam_message/ array. - -<p> -The maximum length of the <tt/pam_msg.msg/ and <tt/pam_response.resp/ -character strings is <tt/PAM_MAX_MSG_SIZE/. (This is not enforced by -Linux-PAM.) - -<p> -<tt/PAM_SUCCESS/ is the expected return value of this -function. However, should an error occur the application should not -set <tt/*resp/ but simply return <tt/PAM_CONV_ERR/. - -<p> -Note, if an application wishes to use two conversation functions, it -should activate the second with a call to <tt/pam_set_item()/. - -<p> -<bf>Notes:</bf> New item types are being added to the conversation -protocol. Currently Linux-PAM supports: <tt>PAM_BINARY_PROMPT</tt> -and <tt>PAM_BINARY_MSG</tt>. These two are intended for server-client -hidden information exchange and may be used as an interface for -maching-machine authentication. - -<sect1>Programming notes - -<p> -Note, all of the authentication service function calls accept the -token <tt/PAM_SILENT/, which instructs the modules to not send -messages to the application. This token can be logically OR'd with any -one of the permitted tokens specific to the individual function calls. -<tt/PAM_SILENT/ does not override the prompting of the user for -passwords etc., it only stops informative messages from being -generated. - -<sect>Security issues of <bf>Linux-PAM</bf> - -<p> -PAM, from the perspective of an application, is a convenient API for -authenticating users. PAM modules generally have no increased -privilege over that possessed by the application that is making use of -it. For this reason, the application must take ultimate responsibility -for protecting the environment in which PAM operates. - -<p> -A poorly (or maliciously) written application can defeat any -<bf/Linux-PAM/ module's authentication mechanisms by simply ignoring -it's return values. It is the applications task and responsibility to -grant privileges and access to services. The <bf/Linux-PAM/ library -simply assumes the responsibility of <em/authenticating/ the user; -ascertaining that the user <em/is/ who they say they are. Care should -be taken to anticipate all of the documented behavior of the -<bf/Linux-PAM/ library functions. A failure to do this will most -certainly lead to a future security breach. - -<sect1>Care about standard library calls - -<p> -In general, writers of authorization-granting applications should -assume that each module is likely to call any or <em/all/ `libc' -functions. For `libc' functions that return pointers to -static/dynamically allocated structures (ie. the library allocates the -memory and the user is not expected to `<tt/free()/' it) any module -call to this function is likely to corrupt a pointer previously -obtained by the application. The application programmer should either -re-call such a `libc' function after a call to the <bf/Linux-PAM/ -library, or copy the structure contents to some safe area of memory -before passing control to the <bf/Linux-PAM/ library. - -<p> -Two important function classes that fall into this category are -<tt>getpwnam(3)</tt> and <tt>syslog(3)</tt>. - -<sect1>Choice of a service name - -<p> -When picking the <em/service-name/ that corresponds to the first entry -in the <bf/Linux-PAM/ configuration file, the application programmer -should <bf/avoid/ the temptation of choosing something related to -<tt/argv[0]/. It is a trivial matter for any user to invoke any -application on a system under a different name and this should not be -permitted to cause a security breach. - -<p> -In general, this is always the right advice if the program is setuid, -or otherwise more privileged than the user that invokes it. In some -cases, avoiding this advice is convenient, but as an author of such an -application, you should consider well the ways in which your program -will be installed and used. (Its often the case that programs are not -intended to be setuid, but end up being installed that way for -convenience. If your program falls into this category, don't fall into -the trap of making this mistake.) - -<p> -To invoke some <tt/target/ application by another name, the user may -symbolically link the target application with the desired name. To be -precise all the user need do is, -<tscreen> -<verb> -ln -s /target/application ./preferred_name -</verb> -</tscreen> -and then <em/run/ <tt>./preferred_name</tt> - -<p> -By studying the <bf/Linux-PAM/ configuration file(s), an attacker can -choose the <tt/preferred_name/ to be that of a service enjoying -minimal protection; for example a game which uses <bf/Linux-PAM/ to -restrict access to certain hours of the day. If the service-name were -to be linked to the filename under which the service was invoked, it -is clear that the user is effectively in the position of dictating -which authentication scheme the service uses. Needless to say, this -is not a secure situation. - -<p> -The conclusion is that the application developer should carefully -define the service-name of an application. The safest thing is to make -it a single hard-wired name. - -<sect1>The conversation function - -<p> -Care should be taken to ensure that the <tt/conv()/ function is -robust. Such a function is provided in the library <tt/libpam_misc/ -(see <ref id="libpam-misc-section" name="below">). - -<sect1>The identity of the user - -<p> -The <bf/Linux-PAM/ modules will need to determine the identity of the -user who requests a service, and the identity of the user who grants -the service. These two users will seldom be the same. Indeed there -is generally a third user identity to be considered, the new (assumed) -identity of the user once the service is granted. - -<p> -The need for keeping tabs on these identities is clearly an issue of -security. One convention that is actively used by some modules is -that the identity of the user requesting a service should be the -current <tt/uid/ (userid) of the running process; the identity of the -privilege granting user is the <tt/euid/ (effective userid) of the -running process; the identity of the user, under whose name the -service will be executed, is given by the contents of the -<tt/PAM_USER/ <tt/pam_get_item(3)/. Note, modules can change the -values of <tt/PAM_USER/ and <tt/PAM_RUSER/ during any of the -<tt/pam_*()/ library calls. For this reason, the application should -take care to use the <tt/pam_get_item()/ every time it wishes to -establish who the authenticated user is (or will currently be). - -<p> -For network-serving databases and other applications that provide -their own security model (independent of the OS kernel) the above -scheme is insufficient to identify the requesting user. - -<p> -A more portable solution to storing the identity of the requesting -user is to use the <tt/PAM_RUSER/ <tt/pam_get_item(3)/. The -application should supply this value before attempting to authenticate -the user with <tt/pam_authenticate()/. How well this name can be -trusted will ultimately be at the discretion of the local -administrator (who configures PAM for your application) and a selected -module may attempt to override the value where it can obtain more -reliable data. If an application is unable to determine the identity -of the requesting entity/user, it should not call <tt/pam_set_item(3)/ -to set <tt/PAM_RUSER/. - -<p> -In addition to the <tt/PAM_RUSER/ item, the application should supply -the <tt/PAM_RHOST/ (<em/requesting host/) item. As a general rule, the -following convention for its value can be assumed: <tt/<unset>/ -= 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><security/pam_misc.h></tt>. It -should be noted that this library is specific to <bf/Linux-PAM/ and is -not referred to in the defining DCE-RFC (see <ref id="bibliography" -name="the bibliography">) below. - -<sect1>Macros supplied - -<sect2>Safe duplication of strings - -<p> -<tscreen> -<verb> -x_strdup(const char *s) -</verb> -</tscreen> - -<p> -This macro is a replacement for the <tt/xstrdup()/ function that was -present in earlier versions of the library and which clashed horribly -with a number of applications. It returns a duplicate copy of the -<tt/NUL/ terminated string, <tt/s/. <tt/NULL/ is returned if there is -insufficient memory available for the duplicate or if <tt/s/ is -<tt/NULL/ to begin with. - -<sect1>Functions supplied - -<sect2>A text based conversation function - -<p> -<tscreen> -<verb> -extern int misc_conv(int num_msg, const struct pam_message **msgm, - struct pam_response **response, void *appdata_ptr); -</verb> -</tscreen> - -<p> -This is a function that will prompt the user with the appropriate -comments and obtain the appropriate inputs as directed by -authentication modules. - -<p> -In addition to simply slotting into the appropriate <tt/struct -pam_conv/, this function provides some time-out facilities. The -function exports five variables that can be used by an application -programmer to limit the amount of time this conversation function will -spend waiting for the user to type something. - -<p> -The five variables are as follows: -<descrip> -<tag><tt>extern time_t pam_misc_conv_warn_time;</tt></tag> - -This variable contains the <em/time/ (as returned by <tt/time()/) that -the user should be first warned that the clock is ticking. By default -it has the value <tt/0/, which indicates that no such warning will be -given. The application may set its value to sometime in the future, -but this should be done prior to passing control to the <bf/Linux-PAM/ -library. - -<tag><tt>extern const char *pam_misc_conv_warn_line;</tt></tag> - -Used in conjuction with <tt/pam_misc_conv_warn_time/, this variable is -a pointer to the string that will be displayed when it becomes time to -warn the user that the timeout is approaching. Its default value is -``..\a.Time is running out...\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 ``..\a.Sorry, your time is -up!\n'', but this can be changed by the application prior to -passing control to <bf/Linux-PAM/. - -<tag><tt>extern int pam_misc_conv_died;</tt></tag> - -Following a return from the <bf/Linux-PAM/ libraray, the value of this -variable indicates whether the conversation has timed out. A value of -<tt/1/ indicates the time-out occurred. - -</descrip> - -<p> -The following two function pointers are available for supporting binary -prompts in the conversation function. They are optimized for the -current incarnation of the <tt/libpamc/ library and are subject to -change. -<descrip> -<tag><tt>extern int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t -*prompt_p);</tt></tag> - -This function pointer is initialized to <tt/NULL/ but can be filled -with a function that provides machine-machine (hidden) message -exchange. It is intended for use with hidden authentication protocols -such as RSA or Diffie-Hellman key exchanges. (This is still under -development.) - -<tag><tt>extern int (*pam_binary_handler_free)(void *appdata, -pamc_bp_t *delete_me);</tt></tag> - -This function pointer is initialized to <tt/PAM_BP_RENEW(delete_me, 0, -0)/, but can be redefined as desired by the application. - -</descrip> - -<sect2>Transcribing an environment to that of Linux-PAM -<p> -<tscreen> -<verb> -extern int pam_misc_paste_env(pam_handle_t *pamh, - const char * const * user_env); -</verb> -</tscreen> - -This function takes the supplied list of environment pointers and -<em/uploads/ its contents to the <bf/Linux-PAM/ environment. Success -is indicated by <tt/PAM_SUCCESS/. - -<sect2>Liberating a locally saved environment -<p> -<tscreen> -<verb> -extern char **pam_misc_drop_env(char **env); -</verb> -</tscreen> - -This function is defined to complement the <tt/pam_getenvlist()/ -function. It liberates the memory associated with <tt/env/, -<em/overwriting/ with <tt/0/ all memory before <tt/free()/ing it. - -<sect2>BSD like Linux-PAM environment variable setting -<p> -<tscreen> -<verb> -extern int pam_misc_setenv(pam_handle_t *pamh, const char *name, - const char *value, int readonly); -</verb> -</tscreen> - -This function performs a task equivalent to <tt/pam_putenv()/, its -syntax is, however, more like the BSD style function; <tt/setenv()/. -The <tt/name/ and <tt/value/ are concatenated with an ``<tt/=/'' to -form a <tt/name_value/ and passed to <tt/pam_putenv()/. If, however, -the <bf/Linux-PAM/ variable is already set, the replacement will only -be applied if the last argument, <tt/readonly/, is zero. - -<sect>Porting legacy applications - -<p> -The following is extracted from an email. I'll tidy it up later. - -<p> -The point of PAM is that the application is not supposed to have any -idea how the attached authentication modules will choose to -authenticate the user. So all they can do is provide a conversation -function that will talk directly to the user(client) on the modules' -behalf. - -<p> -Consider the case that you plug a retinal scanner into the login -program. In this situation the user would be prompted: "please look -into the scanner". No username or password would be needed - all this -information could be deduced from the scan and a database lookup. The -point is that the retinal scanner is an ideal task for a "module". - -<p> -While it is true that a pop-daemon program is designed with the POP -protocol in mind and no-one ever considered attaching a retinal -scanner to it, it is also the case that the "clean" PAM'ification of -such a daemon would allow for the possibility of a scanner module -being be attached to it. The point being that the "standard" -pop-authentication protocol(s) [which will be needed to satisfy -inflexible/legacy clients] would be supported by inserting an -appropriate pam_qpopper module(s). However, having rewritten popd -once in this way any new protocols can be implemented in-situ. - -<p> -One simple test of a ported application would be to insert the -<tt/pam_permit/ module and see if the application demands you type a -password... In such a case, <tt/xlock/ would fail to lock the -terminal - or would at best be a screen-saver, ftp would give password -free access to all etc.. Neither of these is a very secure thing to -do, but they do illustrate how much flexibility PAM puts in the hands -of the local admin. - -<p> -The key issue, in doing things correctly, is identifying what is part -of the authentication procedure (how many passwords etc..) the -exchange protocol (prefixes to prompts etc., numbers like 331 in the -case of ftpd) and what is part of the service that the application -delivers. PAM really needs to have total control in the -authentication "procedure", the conversation function should only -deal with reformatting user prompts and extracting responses from raw -input. - -<sect>Glossary of PAM related terms - -<p> -The following are a list of terms used within this document. - -<p> -<descrip> - -<tag>Authentication token</tag> -Generally, this is a password. However, a user can authenticate -him/herself in a variety of ways. Updating the user's authentication -token thus corresponds to <em>refreshing</em> the object they use to -authenticate themself with the system. The word password is avoided -to keep open the possibility that the authentication involves a -retinal scan or other non-textual mode of challenge/response. - -<tag>Credentials</tag> -Having successfully authenticated the user, PAM is able to establish -certain characteristics/attributes of the user. These are termed -<em>credentials</em>. Examples of which are group memberships to -perform privileged tasks with, and <em>tickets</em> in the form of -environment variables etc. . Some user-credentials, such as the -user's UID and GID (plus default group memberships) are not deemed to -be PAM-credentials. It is the responsibility of the application to -grant these directly. - -</descrip> - -<sect>An example application - -<p> -To get a flavor of the way a <tt/Linux-PAM/ application is written we -include the following example. It prompts the user for their password -and indicates whether their account is valid on the standard output, -its return code also indicates the success (<tt/0/ for success; <tt/1/ -for failure). - -<p> -<tscreen> -<verb> -/* - This program was contributed by Shane Watts - [modifications by AGM] - - You need to add the following (or equivalent) to the /etc/pam.conf file. - # check authorization - check_user auth required /usr/lib/security/pam_unix_auth.so - check_user account required /usr/lib/security/pam_unix_acct.so - */ - -#include <security/pam_appl.h> -#include <security/pam_misc.h> -#include <stdio.h> - -static struct pam_conv conv = { - misc_conv, - NULL -}; - -int main(int argc, char *argv[]) -{ - pam_handle_t *pamh=NULL; - int retval; - const char *user="nobody"; - - if(argc == 2) { - user = argv[1]; - } - - if(argc > 2) { - fprintf(stderr, "Usage: check_user [username]\n"); - exit(1); - } - - retval = pam_start("check_user", user, &ero;conv, &ero;pamh); - - if (retval == PAM_SUCCESS) - retval = pam_authenticate(pamh, 0); /* is user really user? */ - - if (retval == PAM_SUCCESS) - retval = pam_acct_mgmt(pamh, 0); /* permitted access? */ - - /* This is where we have been authorized or not. */ - - if (retval == PAM_SUCCESS) { - fprintf(stdout, "Authenticated\n"); - } else { - fprintf(stdout, "Not Authenticated\n"); - } - - if (pam_end(pamh,retval) != PAM_SUCCESS) { /* close Linux-PAM */ - pamh = NULL; - fprintf(stderr, "check_user: failed to release authenticator\n"); - exit(1); - } - - return ( retval == PAM_SUCCESS ? 0:1 ); /* indicate success */ -} -</verb> -</tscreen> - -<sect>Files - -<p><descrip> - -<tag><tt>/usr/include/security/pam_appl.h</tt></tag> - -header file for <bf/Linux-PAM/ applications interface - -<tag><tt>/usr/include/security/pam_misc.h</tt></tag> - -header file for useful library functions for making applications -easier to write - -<tag><tt>/usr/lib/libpam.so.*</tt></tag> - -the shared library providing applications with access to -<bf/Linux-PAM/. - -<tag><tt>/etc/pam.conf</tt></tag> - -the <bf/Linux-PAM/ configuration file. - -<tag><tt>/usr/lib/security/pam_*.so</tt></tag> - -the primary location for <bf/Linux-PAM/ dynamically loadable object -files; the modules. - -</descrip> - -<sect>See also -<label id="bibliography"> - -<p><itemize> - -<item>The <bf/Linux-PAM/ -<htmlurl url="pam.html" name="System Administrators' Guide">. - -<item>The <bf/Linux-PAM/ -<htmlurl url="pam_modules.html" name="Module Writers' Guide">. - -<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH -PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request -For Comments 86.0, October 1995. - -</itemize> - -<sect>Notes - -<p> -I intend to put development comments here... like ``at the moment -this isn't actually supported''. At release time what ever is in -this section will be placed in the Bugs section below! :) - -<p> -<itemize> - -<item> <tt/pam_strerror()/ should be internationalized.... - -<item> -Note, the <tt/resp_retcode/ of struct <tt/pam_message/, has no -purpose at the moment. Ideas/suggestions welcome! - -<item> more security issues are required.... - -</itemize> - -<sect>Author/acknowledgments - -<p> -This document was written by Andrew G. Morgan -(morgan@kernel.org) with many contributions from -<!-- insert credits here --> -<!-- - an sgml list of people to credit for their contributions to Linux-PAM - $Id$ - --> -Chris Adams, -Peter Allgeyer, -Tim Baverstock, -Tim Berger, -Craig S. Bell, -Derrick J. Brashear, -Ben Buxton, -Seth Chaiklin, -Oliver Crow, -Chris Dent, -Marc Ewing, -Cristian Gafton, -Emmanuel Galanos, -Brad M. Garcia, -Eric Hester, -Roger Hu, -Eric Jacksch, -Michael K. Johnson, -David Kinchlea, -Olaf Kirch, -Marcin Korzonek, -Stephen Langasek, -Nicolai Langfeldt, -Elliot Lee, -Luke Kenneth Casson Leighton, -Al Longyear, -Ingo Luetkebohle, -Marek Michalkiewicz, -Robert Milkowski, -Aleph One, -Martin Pool, -Sean Reifschneider, -Jan Rekorajski, -Erik Troan, -Theodore Ts'o, -Jeff Uphoff, -Myles Uyema, -Savochkin Andrey Vladimirovich, -Ronald Wahl, -David Wood, -John Wilmes, -Joseph S. D. Yao -and -Alex O. Yuriev. - -<p> -Thanks are also due to Sun Microsystems, especially to Vipin Samar and -Charlie Lai for their advice. At an early stage in the development of -<bf/Linux-PAM/, Sun graciously made the documentation for their -implementation of PAM available. This act greatly accelerated the -development of <bf/Linux-PAM/. - -<sect>Bugs/omissions - -<p> -This manual is hopelessly unfinished. Only a partial list of people is -credited for all the good work they have done. - -<sect>Copyright information for this document - -<p> -Copyright (c) Andrew G. Morgan 1996-9,2000-1. All rights reserved. -<newline> -Email: <tt><morgan@kernel.org></tt> - -<p> -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -<p> -<itemize> - -<item> -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -<item> -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -<item> -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -</itemize> - -<p> -<bf/Alternatively/, this product may be distributed under the terms of -the GNU General Public License (GPL), in which case the provisions of -the GNU GPL are required <bf/instead of/ the above restrictions. -(This clause is necessary due to a potential bad interaction between -the GNU GPL and the restrictions contained in a BSD-style copyright.) - -<p> -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. - -<p> -<tt>$Id$</tt> - -</article> diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml deleted file mode 100644 index c986e0a9..00000000 --- a/doc/pam_modules.sgml +++ /dev/null @@ -1,1505 +0,0 @@ -<!doctype linuxdoc system> - -<!-- - - $Id$ - - Copyright (c) Andrew G. Morgan 1996-2001. All rights reserved. - - ** some sections, in this document, were contributed by other - ** authors. They carry individual copyrights. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -ALTERNATIVELY, this product may be distributed under the terms of the -GNU General Public License, in which case the provisions of the GNU -GPL are required INSTEAD OF the above restrictions. (This clause is -necessary due to a potential bad interaction between the GNU GPL and -the restrictions contained in a BSD-style copyright.) - -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. - - --> - -<article> - -<title>The Linux-PAM Module Writers' Guide -<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2002/05/09 -<abstract> -This manual documents what a programmer needs to know in order to -write a module that conforms to the <bf/Linux-PAM/ standard. It also -discusses some security issues from the point of view of the module -programmer. -</abstract> - -<toc> - -<sect>Introduction - -<sect1> Synopsis -<p> -<tscreen> -<verb> -#include <security/pam_modules.h> - -gcc -fPIC -c pam_module-name.c -ld -x --shared -o pam_module-name.so pam_module-name.o -</verb> -</tscreen> - -<sect1> Description - -<p> -<bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a -library that enables the local system administrator to choose how -individual applications authenticate users. For an overview of the -<bf/Linux-PAM/ library see the <bf/Linux-PAM/ System Administrators' -Guide. - -<p> -A <bf/Linux-PAM/ module is a single executable binary file that can be -loaded by the <bf/Linux-PAM/ interface library. This PAM library is -configured locally with a system file, <tt>/etc/pam.conf</tt>, to -authenticate a user request via the locally available authentication -modules. The modules themselves will usually be located in the -directory <tt>/usr/lib/security</tt> and take the form of dynamically -loadable object files (see dlopen(3)). Alternatively, the modules can -be statically linked into the <bf/Linux-PAM/ library; this is mostly to -allow <bf/Linux-PAM/ to be used on platforms without dynamic linking -available, but the two forms can be used together. It is the -<bf/Linux-PAM/ interface that is called by an application and it is -the responsibility of the library to locate, load and call the -appropriate functions in a <bf/Linux-PAM/-module. - -<p> -Except for the immediate purpose of interacting with the user -(entering a password etc..) the module should never call the -application directly. This exception requires a "conversation -mechanism" which is documented below. - -<sect>What can be expected by the module - -<p> -Here we list the interface that the conventions that all -<bf/Linux-PAM/ modules must adhere to. - -<sect1>Getting and setting <tt/PAM_ITEM/s and <em/data/ - -<p> -First, we cover what the module should expect from the <bf/Linux-PAM/ -library and a <bf/Linux-PAM/ <em/aware/ application. Essesntially this -is the <tt/libpam.*/ library. - -<sect2> -Setting data - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_set_data(pam_handle_t *pamh, - const char *module_data_name, - void *data, - void (*cleanup)(pam_handle_t *pamh, - void *data, int error_status) ); -</verb> -</tscreen> - -<p> -The modules may be dynamically loadable objects. In general such files -should not contain <tt/static/ variables. This and the subsequent -function provide a mechanism for a module to associate some data with -the handle <tt/pamh/. Typically a module will call the -<tt/pam_set_data()/ function to register some data under a (hopefully) -unique <tt/module_data_name/. The data is available for use by other -modules too but <em/not/ by an application. - -<p> -The function <tt/cleanup()/ is associated with the <tt/data/ and, if -non-<tt/NULL/, it is called when this data is over-written or -following a call to <tt/pam_end()/ (see the Linux-PAM Application -Developers' Guide). - -<p> -The <tt/error_status/ argument is used to indicate to the module the -sort of action it is to take in cleaning this data item. As an -example, Kerberos creates a ticket file during the authentication -phase, this file might be associated with a data item. When -<tt/pam_end()/ is called by the module, the <tt/error_status/ -carries the return value of the <tt/pam_authenticate()/ or other -<tt/libpam/ function as appropriate. Based on this value the Kerberos -module may choose to delete the ticket file (<em/authentication -failure/) or leave it in place. - -<p> -The <tt/error_status/ may have been logically OR'd with either of the -following two values: - -<p> -<descrip> -<tag><tt/PAM_DATA_REPLACE/</tag> - When a data item is being replaced (through a second call to -<tt/pam_set_data()/) this mask is used. Otherwise, the call is assumed -to be from <tt/pam_end()/. - -<tag><tt/PAM_DATA_SILENT/</tag> - Which indicates that the process would prefer to perform the -<tt/cleanup()/ quietly. That is, discourages logging/messages to the -user. - -</descrip> - - -<sect2> -Getting data - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_get_data(const pam_handle_t *pamh, - const char *module_data_name, - const void **data); -</verb> -</tscreen> - -<p> -This function together with the previous one provides a method of -associating module-specific data with the handle <tt/pamh/. A -successful call to <tt/pam_get_data/ will result in <tt/*data/ -pointing to the data associated with the <tt/module_data_name/. Note, -this data is <em/not/ a copy and should be treated as <em/constant/ -by the module. - -<p> -Note, if there is an entry but it has the value <tt/NULL/, then this -call returns <tt/PAM_NO_MODULE_DATA/. - -<sect2> -Setting items - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_set_item(pam_handle_t *pamh, - int item_type, - const void *item); -</verb> -</tscreen> - -<p> -This function is used to (re)set the value of one of the -<tt/item_type/s. The reader is urged to read the entry for this -function in the <bf/Linux-PAM/ application developers' manual. - -<p> -In addition to the <tt/item/s listed there, the module can set the -following two <tt/item_type/s: - -<p> -<descrip> -<tag><tt/PAM_AUTHTOK/</tag> - -The authentication token (often a password). This token should be -ignored by all module functions besides <tt/pam_sm_authenticate()/ and -<tt/pam_sm_chauthtok()/. In the former function it is used to pass the -most recent authentication token from one stacked module to -another. In the latter function the token is used for another -purpose. It contains the currently active authentication token. - -<tag><tt/PAM_OLDAUTHTOK/</tag> - -The old authentication token. This token should be ignored by all -module functions except <tt/pam_sm_chauthtok()/. - -</descrip> - -<p> -Both of these items are reset before returning to the application. -When resetting these items, the <bf/Linux-PAM/ library first writes -<tt/0/'s to the current tokens and then <tt/free()/'s the associated -memory. - -<p> -The return values for this function are listed in the -<bf>Linux-PAM</bf> Application Developers' Guide. - -<sect2> -Getting items - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_get_item(const pam_handle_t *pamh, - int item_type, - const void **item); -</verb> -</tscreen> - -<p> -This function is used to obtain the value of the specified -<tt/item_type/. It is better documented in the <bf/Linux-PAM/ -Application Developers' Guide. However, there are three things worth -stressing here: -<itemize> - -<item> -Generally, if the module wishes to obtain the name of the user, it -should not use this function, but instead perform a call to -<tt/pam_get_user()/ (see section <ref id="pam-get-user" -name="below">). - -<item> -The module is additionally privileged to read the authentication -tokens, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/ (see the section -above on <tt/pam_set_data()/). - -<item> -The module should <em/not/ <tt/free()/ or alter the data pointed to by -<tt/*item/ after a successful return from <tt/pam_get_item()/. This -pointer points directly at the data contained within the <tt/*pamh/ -structure. Should a module require that a change is made to the this -<tt/ITEM/ it should make the appropriate call to <tt/pam_set_item()/. -</itemize> - -<sect2>The <em/conversation/ mechanism - -<p> -Following the call <tt>pam_get_item(pamh,PAM_CONV,&item)</tt>, the -pointer <tt/item/ points to a structure containing an a pointer to a -<em/conversation/-function that provides limited but direct access to -the application. The purpose of this function is to allow the module -to prompt the user for their password and pass other information in a -manner consistent with the application. For example, an X-windows -based program might pop up a dialog box to report a login -failure. Just as the application should not be concerned with the -method of authentication, so the module should not dictate the manner -in which input (output) is obtained from (presented to) to the user. - -<p> -<bf>The reader is strongly urged to read the more complete description of -the <tt/pam_conv/ structure, written from the perspective of the -application developer, in the <bf/Linux-PAM/ Application Developers' -Guide.</bf> - -<p> -The return values for this function are listed in the -<bf>Linux-PAM</bf> Application Developers' Guide. - -<p> -The <tt/pam_response/ structure returned after a call to the -<tt/pam_conv/ function must be <tt/free()/'d by the module. Since the -call to the conversation function originates from the module, it is -clear that this <tt/pam_response/ structure could be either statically -or dynamically (using <tt/malloc()/ etc.) allocated within the -application. Repeated calls to the conversation function would likely -overwrite static memory, so it is required that for a successful -return from the conversation function the memory for the response -structure is dynamically allocated by the application with one of the -<tt/malloc()/ family of commands and <em/must/ be <tt/free()/'d by the -module. - -<p> -If the <tt/pam_conv/ mechanism is used to enter authentication tokens, -the module should either pass the result to the <tt/pam_set_item()/ -library function, or copy it itself. In such a case, once the token -has been stored (by one of these methods or another one), the memory -returned by the application should be overwritten with <tt/0/'s, and -then <tt/free()/'d. - -There is a handy macro <tt/_pam_drop_reply()/ to be found in -<tt><security/_pam_macros.h></tt> that can be used to -conveniently cleanup a <tt/pam_response/ structure. (Note, this -include file is specific to the Linux-PAM sources, and whilst it will -work with Sun derived PAM implementations, it is not generally -distributed by Sun.) - -<sect2>Getting the name of a user<label id="pam-get-user"> - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_get_user(pam_handle_t *pamh, - const char **user, - const char *prompt); -</verb> -</tscreen> - -<p> -This is a <bf/Linux-PAM/ library function that returns the -(prospective) name of the user. To determine the username it does the -following things, in this order: -<itemize> - -<item> checks what <tt/pam_get_item(pamh, PAM_USER, ... );/ would have -returned. If this is not <tt/NULL/ this is what it returns. Otherwise, - -<item> obtains a username from the application via the <tt/pam_conv/ -mechanism, it prompts the user with the first non-<tt/NULL/ string in -the following list: -<itemize> - -<item> The <tt/prompt/ argument passed to the function -<item> What is returned by <tt/pam_get_item(pamh,PAM_USER_PROMPT, ... );/ -<item> The default prompt: ``Please enter username: '' - -</itemize> -</itemize> - -<p> -By whatever means the username is obtained, a pointer to it is -returned as the contents of <tt/*user/. Note, this memory should -<em/not/ be <tt/free()/'d by the module. Instead, it will be liberated -on the next call to <tt/pam_get_user()/, or by <tt/pam_end()/ when the -application ends its interaction with <bf/Linux-PAM/. - -<p> -Also, in addition, it should be noted that this function sets the -<tt/PAM_USER/ item that is associated with the <tt/pam_[gs]et_item()/ -function. - -<p> -The return value of this function is one of the following: -<itemize> - -<item> <tt/PAM_SUCCESS/ - username obtained. - -<item> <tt/PAM_CONV_AGAIN/ - converstation did not complete and the -caller is required to return control to the application, until such -time as the application has completed the conversation process. A -module calling <tt/pam_get_user()/ that obtains this return code, -should return <tt/PAM_INCOMPLETE/ and be prepared (when invoked the -next time) to recall <tt/pam_get_user()/ to fill in the user's name, -and then pick up where it left off as if nothing had happened. This -procedure is needed to support an event-driven application programming -model. - -<item> <tt/PAM_CONV_ERR/ - the conversation method supplied by the -application failed to obtain the username. - -</itemize> - -<sect2>Setting a Linux-PAM environment variable - -<p> -Synopsis: -<tscreen> -<verb> -extern int pam_putenv(pam_handle_t *pamh, const char *name_value); -</verb> -</tscreen> - -<p> -<bf/Linux-PAM/ comes equipped with a series of functions for -maintaining a set of <em/environment/ variables. The environment is -initialized by the call to <tt/pam_start()/ and is <bf/erased/ with a -call to <tt/pam_end()/. This <em/environment/ is associated with the -<tt/pam_handle_t/ pointer returned by the former call. - -<p> -The default environment is all but empty. It contains a single -<tt/NULL/ pointer, which is always required to terminate the -variable-list. The <tt/pam_putenv()/ function can be used to add a -new environment variable, replace an existing one, or delete an old -one. - -<p> -<itemize> -<item>Adding/replacing a variable<newline> - -To add or overwrite a <bf/Linux-PAM/ environment variable the value of -the argument <tt/name_value/, should be of the following form: -<tscreen> -<verb> -name_value="VARIABLE=VALUE OF VARIABLE" -</verb> -</tscreen> -Here, <tt/VARIABLE/ is the environment variable's name and what -follows the `<tt/=/' is its (new) value. (Note, that <tt/"VARIABLE="/ -is a valid value for <tt/name_value/, indicating that the variable is -set to <tt/""/.) - -<item> Deleting a variable<newline> - -To delete a <bf/Linux-PAM/ environment variable the value of -the argument <tt/name_value/, should be of the following form: -<tscreen> -<verb> -name_value="VARIABLE" -</verb> -</tscreen> -Here, <tt/VARIABLE/ is the environment variable's name and the absence -of an `<tt/=/' indicates that the variable should be removed. - -</itemize> - -<p> -In all cases <tt/PAM_SUCCESS/ indicates success. - -<sect2>Getting a Linux-PAM environment variable - -<p> -Synopsis: -<tscreen> -<verb> -extern const char *pam_getenv(pam_handle_t *pamh, const char *name); -</verb> -</tscreen> - -<p> -This function can be used to return the value of the given -variable. If the returned value is <tt/NULL/, the variable is not -known. - -<sect2>Listing the Linux-PAM environment - -<p> -Synopsis: -<tscreen> -<verb> -extern char * const *pam_getenvlist(pam_handle_t *pamh); -</verb> -</tscreen> - -<p> -This function returns a pointer to the entire <bf/Linux-PAM/ -environment array. At first sight the <em/type/ of the returned data -may appear a little confusing. It is basically a <em/read-only/ array -of character pointers, that lists the <tt/NULL/ terminated list of -environment variables set so far. - -<p> -Although, this is not a concern for the module programmer, we mention -here that an application should be careful to copy this entire array -before executing <tt/pam_end()/ otherwise all the variable information -will be lost. (There are functions in <tt/libpam_misc/ for this -purpose: <tt/pam_misc_copy_env()/ and <tt/pam_misc_drop_env()/.) - -<sect1>Other functions provided by <tt/libpam/ - -<sect2>Understanding errors - -<p> -<itemize> - -<item> -<tt>extern const char *pam_strerror(pam_handle_t *pamh, int errnum);</tt> - -<p> -This function returns some text describing the <bf/Linux-PAM/ error -associated with the argument <tt/errnum/. If the error is not -recognized <tt/``Unknown Linux-PAM error''/ is returned. - -</itemize> - -<sect2>Planning for delays - -<p> -<itemize> - -<item> -<tt>extern int pam_fail_delay(pam_handle_t *pamh, unsigned int -micro_sec)</tt> - -<p> -This function is offered by <bf/Linux-PAM/ to facilitate time delays -following a failed call to <tt/pam_authenticate()/ and before control -is returned to the application. When using this function the module -programmer should check if it is available with, -<tscreen> -<verb> -#ifdef PAM_FAIL_DELAY - .... -#endif /* PAM_FAIL_DELAY */ -</verb> -</tscreen> - -<p> -Generally, an application requests that a user is authenticated by -<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or -<tt/pam_chauthtok()/. These functions call each of the <em/stacked/ -authentication modules listed in the <bf/Linux-PAM/ configuration -file. As directed by this file, one of more of the modules may fail -causing the <tt/pam_...()/ call to return an error. It is desirable -for there to also be a pause before the application continues. The -principal reason for such a delay is security: a delay acts to -discourage <em/brute force/ dictionary attacks primarily, but also -helps hinder <em/timed/ (cf. covert channel) attacks. - -<p> -The <tt/pam_fail_delay()/ function provides the mechanism by which an -application or module can suggest a minimum delay (of <tt/micro_sec/ -<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time -requested with this function. Should <tt/pam_authenticate()/ fail, -the failing return to the application is delayed by an amount of time -randomly distributed (by up to 25%) about this longest value. - -<p> -Independent of success, the delay time is reset to its zero default -value when <bf/Linux-PAM/ returns control to the application. - -</itemize> - -<sect>What is expected of a module - -<p> -The module must supply a sub-set of the six functions listed -below. Together they define the function of a <bf/Linux-PAM -module/. Module developers are strongly urged to read the comments on -security that follow this list. - -<sect1> Overview - -<p> -The six module functions are grouped into four independent management -groups. These groups are as follows: <em/authentication/, -<em/account/, <em/session/ and <em/password/. To be properly defined, -a module must define all functions within at least one of these -groups. A single module may contain the necessary functions for -<em/all/ four groups. - -<sect2> Functional independence - -<p> -The independence of the four groups of service a module can offer -means that the module should allow for the possibility that any one of -these four services may legitimately be called in any order. Thus, the -module writer should consider the appropriateness of performing a -service without the prior success of some other part of the module. - -<p> -As an informative example, consider the possibility that an -application applies to change a user's authentication token, without -having first requested that <bf/Linux-PAM/ authenticate the user. In -some cases this may be deemed appropriate: when <tt/root/ wants to -change the authentication token of some lesser user. In other cases it -may not be appropriate: when <tt/joe/ maliciously wants to reset -<tt/alice/'s password; or when anyone other than the user themself -wishes to reset their <em/KERBEROS/ authentication token. A policy for -this action should be defined by any reasonable authentication scheme, -the module writer should consider this when implementing a given -module. - -<sect2> Minimizing administration problems - -<p> -To avoid system administration problems and the poor construction of a -<tt>/etc/pam.conf</tt> file, the module developer may define all -six of the following functions. For those functions that would not be -called, the module should return <tt/PAM_SERVICE_ERR/ and write an -appropriate message to the system log. When this action is deemed -inappropriate, the function would simply return <tt/PAM_IGNORE/. - -<sect2> Arguments supplied to the module - -<p> -The <tt/flags/ argument of each of the following functions can be -logically OR'd with <tt/PAM_SILENT/, which is used to inform the -module to not pass any <em/text/ (errors or warnings) to the -application. - -<p> -The <tt/argc/ and <tt/argv/ arguments are taken from the line -appropriate to this module---that is, with the <em/service_name/ -matching that of the application---in the configuration file (see the -<bf/Linux-PAM/ System Administrators' Guide). Together these two -parameters provide the number of arguments and an array of pointers to -the individual argument tokens. This will be familiar to C programmers -as the ubiquitous method of passing command arguments to the function -<tt/main()/. Note, however, that the first argument (<tt/argv[0]/) is -a true argument and <bf/not/ the name of the module. - -<sect1> Authentication management - -<p> -To be correctly initialized, <tt/PAM_SM_AUTH/ must be <tt/#define/'d -prior to including <tt><security/pam_modules.h></tt>. This will -ensure that the prototypes for static modules are properly declared. - -<p> -<itemize> - -<item> -<tt>PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags, -int argc, const char **argv);</tt> - -<p> -This function performs the task of authenticating the user. - -<p> -The <tt/flags/ argument can be a logically OR'd with <tt/PAM_SILENT/ -and optionally take the following value: - -<p><descrip> -<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag> - return <tt/PAM_AUTH_ERR/ if the database of authentication -tokens for this authentication mechanism has a <tt/NULL/ entry for the -user. Without this flag, such a <tt/NULL/ token will lead to a success -without the user being prompted. -</descrip> - -<p> -Besides <tt/PAM_SUCCESS/ return values that can be sent by this -function are one of the following: - -<descrip> - -<tag><tt/PAM_AUTH_ERR/</tag> - The user was not authenticated -<tag><tt/PAM_CRED_INSUFFICIENT/</tag> - For some reason the application does not have sufficient -credentials to authenticate the user. -<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag> - The modules were not able to access the authentication -information. This might be due to a network or hardware failure etc. -<tag><tt/PAM_USER_UNKNOWN/</tag> - The supplied username is not known to the authentication -service -<tag><tt/PAM_MAXTRIES/</tag> - One or more of the authentication modules has reached its -limit of tries authenticating the user. Do not try again. - -</descrip> - -<item> -<tt>PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int -argc, const char **argv);</tt> - -<p> -This function performs the task of altering the credentials of the -user with respect to the corresponding authorization -scheme. Generally, an authentication module may have access to more -information about a user than their authentication token. This -function is used to make such information available to the -application. It should only be called <em/after/ the user has been -authenticated but before a session has been established. - -<p> -Permitted flags, one of which, may be logically OR'd with -<tt/PAM_SILENT/ are, - -<p><descrip> -<tag><tt/PAM_ESTABLISH_CRED/</tag> - Set the credentials for the authentication service, -<tag><tt/PAM_DELETE_CRED/</tag> - Delete the credentials associated with the authentication service, -<tag><tt/PAM_REINITIALIZE_CRED/</tag> - Reinitialize the user credentials, and -<tag><tt/PAM_REFRESH_CRED/</tag> - Extend the lifetime of the user credentials. -</descrip> - -<p> -Prior to <bf/Linux-PAM-0.75/, and due to a deficiency with the way the -<tt/auth/ stack was handled in the case of the setcred stack being -processed, the module was required to attempt to return the same error -code as <tt/pam_sm_authenticate/ did. This was necessary to preserve -the logic followed by libpam as it executes the stack of -<em/authentication/ modules, when the application called either -<tt/pam_authenticate()/ or <tt/pam_setcred()/. Failing to do this, -led to confusion on the part of the System Administrator. - -<p> -For <bf/Linux-PAM-0.75/ and later, libpam handles the credential stack -much more sanely. The way the <tt/auth/ stack is navigated in order to -evaluate the <tt/pam_setcred()/ function call, independent of the -<tt/pam_sm_setcred()/ return codes, is exactly the same way that it -was navigated when evaluating the <tt/pam_authenticate()/ library -call. Typically, if a stack entry was ignored in evaluating -<tt/pam_authenticate()/, it will be ignored when libpam evaluates the -<tt/pam_setcred()/ function call. Otherwise, the return codes from -each module specific <tt/pam_sm_setcred()/ call are treated as -<tt/required/. - -<p> -Besides <tt/PAM_SUCCESS/, the module may return one of the following -errors: - -<p><descrip> -<tag><tt/PAM_CRED_UNAVAIL/</tag> - This module cannot retrieve the user's credentials. -<tag><tt/PAM_CRED_EXPIRED/</tag> - The user's credentials have expired. -<tag><tt/PAM_USER_UNKNOWN/</tag> - The user is not known to this authentication module. -<tag><tt/PAM_CRED_ERR/</tag> - This module was unable to set the credentials of the user. -</descrip> - -<p> -these, non-<tt/PAM_SUCCESS/, return values will typically lead to the -credential stack <em/failing/. The first such error will dominate in -the return value of <tt/pam_setcred()/. - -</itemize> - -<sect1> Account management - -<p> -To be correctly initialized, <tt/PAM_SM_ACCOUNT/ must be -<tt/#define/'d prior to including <tt><security/pam_modules.h></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><security/pam_modules.h></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><security/pam_modules.h></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><security/pam_modules.h></tt>. This is ostensibly for -security reasons, but a maliciously programmed application will always -have access to all memory of the process, so it is only superficially -enforced. As a general rule the module should overwrite -authentication tokens as soon as they are no longer needed. -Especially before <tt/free()/'ing them. The <bf/Linux-PAM/ library is -required to do this when either of these authentication token items -are (re)set. - -<p> -Not to dwell too little on this concern; should the module store the -authentication tokens either as (automatic) function variables or -using <tt/pam_[gs]et_data()/ the associated memory should be -over-written explicitly before it is released. In the case of the -latter storage mechanism, the associated <tt/cleanup()/ function -should explicitly overwrite the <tt/*data/ before <tt/free()/'ing it: -for example, - -<tscreen> -<verb> -/* - * An example cleanup() function for releasing memory that was used to - * store a password. - */ - -int cleanup(pam_handle_t *pamh, void *data, int error_status) -{ - char *xx; - - if ((xx = data)) { - while (*xx) - *xx++ = '\0'; - free(data); - } - return PAM_SUCCESS; -} -</verb> -</tscreen> - -<sect1>Use of <tt/syslog(3)/ - -<p> -Only rarely should error information be directed to the user. Usually, -this is to be limited to ``<em/sorry you cannot login now/'' type -messages. Information concerning errors in the configuration file, -<tt>/etc/pam.conf</tt>, or due to some system failure encountered by -the module, should be written to <tt/syslog(3)/ with -<em/facility-type/ <tt/LOG_AUTHPRIV/. - -<p> -With a few exceptions, the level of logging is, at the discretion of -the module developer. Here is the recommended usage of different -logging levels: - -<p> -<itemize> - -<item> -As a general rule, errors encountered by a module should be logged at -the <tt/LOG_ERR/ level. However, information regarding an unrecognized -argument, passed to a module from an entry in the -<tt>/etc/pam.conf</tt> file, is <bf/required/ to be logged at the -<tt/LOG_ERR/ level. - -<item> -Debugging information, as activated by the <tt/debug/ argument to the -module in <tt>/etc/pam.conf</tt>, should be logged at the -<tt/LOG_DEBUG/ level. - -<item> -If a module discovers that its personal configuration file or some -system file it uses for information is corrupted or somehow unusable, -it should indicate this by logging messages at level, <tt/LOG_ALERT/. - -<item> -Shortages of system resources, such as a failure to manipulate a file -or <tt/malloc()/ failures should be logged at level <tt/LOG_CRIT/. - -<item> -Authentication failures, associated with an incorrectly typed password -should be logged at level, <tt/LOG_NOTICE/. - -</itemize> - -<sect1> Modules that require system libraries - -<p> -Writing a module is much like writing an application. You have to -provide the "conventional hooks" for it to work correctly, like -<tt>pam_sm_authenticate()</tt> etc., which would correspond to the -<tt/main()/ function in a normal function. - -<p> -Typically, the author may want to link against some standard system -libraries. As when one compiles a normal program, this can be done for -modules too: you simply append the <tt>-l</tt><em>XXX</em> arguments -for the desired libraries when you create the shared module object. To -make sure a module is linked to the <tt>lib<em>whatever</em>.so</tt> -library when it is <tt>dlopen()</tt>ed, try: -<tscreen> -<verb> -% gcc -shared -Xlinker -x -o pam_module.so pam_module.o -lwhatever -</verb> -</tscreen> - -<sect1> Added requirements for <em/statically/ loaded modules. - -<!-- - Copyright (C) Michael K. Johnson 1996. - Last modified: AGM 1996/5/31. - --> - -<p> -Modules may be statically linked into libpam. This should be true of -all the modules distributed with the basic <bf/Linux-PAM/ -distribution. To be statically linked, a module needs to export -information about the functions it contains in a manner that does not -clash with other modules. - -The extra code necessary to build a static module should be delimited -with <tt/#ifdef PAM_STATIC/ and <tt/#endif/. The static code should do -the following: -<itemize> -<item> Define a single structure, <tt/struct pam_module/, called -<tt>_pam_<it>modname</it>_modstruct</tt>, where -<tt><it>modname</it></tt> is the name of the module <bf/as used in the -filesystem/ but without the leading directory name (generally -<tt>/usr/lib/security/</tt> or the suffix (generally <tt/.so/). - -</itemize> - -<p> -As a simple example, consider the following module code which defines -a module that can be compiled to be <em/static/ or <em/dynamic/: - -<p> -<tscreen> -<verb> -#include <stdio.h> /* for NULL define */ - -#define PAM_SM_PASSWORD /* the only pam_sm_... function declared */ -#include <security/pam_modules.h> - -PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, - int argc, const char **argv) -{ - return PAM_SUCCESS; -} - -#ifdef PAM_STATIC /* for the case that this module is static */ - -struct pam_module _pam_modname_modstruct = { /* static module data */ - "pam_modname", - NULL, - NULL, - NULL, - NULL, - NULL, - pam_sm_chauthtok, -}; - -#endif /* end PAM_STATIC */ -</verb> -</tscreen> - -<p> -To be linked with <em/libpam/, staticly-linked modules must be built -from within the <tt>Linux-PAM-X.YY/modules/</tt> subdirectory of the -<bf/Linux-PAM/ source directory as part of a normal build of the -<bf/Linux-PAM/ system. - -The <em/Makefile/, for the module in question, must execute the -<tt/register_static/ shell script that is located in the -<tt>Linux-PAM-X.YY/modules/</tt> subdirectory. This is to ensure that -the module is properly registered with <em/libpam/. - -The <bf/two/ manditory arguments to <tt/register_static/ are the -title, and the pathname of the object file containing the module's -code. The pathname is specified relative to the -<tt>Linux-PAM-X.YY/modules</tt> directory. The pathname may be an -empty string---this is for the case that a single object file needs to -register more than one <tt/struct pam_module/. In such a case, exactly -one call to <tt/register_static/ must indicate the object file. - -<p> -Here is an example; a line in the <em/Makefile/ might look like this: -<tscreen> -<verb> -register: -ifdef STATIC - (cd ..; ./register_static pam_modname pam_modname/pam_modname.o) -endif -</verb> -</tscreen> - -For some further examples, see the <tt>modules</tt> subdirectory of -the current <bf/Linux-PAM/ distribution. - -<sect>An example module file - -<p> -At some point, we may include a fully commented example of a module in -this document. For now, we point the reader to these two locations in -the public CVS repository: -<itemize> -<item> A module that always succeeds: <tt><htmlurl -url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_permit/" -name="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_permit/" -></tt> -<item> A module that always fails: <tt><htmlurl -url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_deny/" -name="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/pam/Linux-PAM/modules/pam_deny/" -></tt> -</itemize> - -<sect>Files - -<p><descrip> - -<tag><tt>/usr/lib/libpam.so.*</tt></tag> - -the shared library providing applications with access to -<bf/Linux-PAM/. - -<tag><tt>/etc/pam.conf</tt></tag> - -the <bf/Linux-PAM/ configuration file. - -<tag><tt>/usr/lib/security/pam_*.so</tt></tag> - -the primary location for <bf/Linux-PAM/ dynamically loadable object -files; the modules. - -</descrip> - -<sect>See also - -<p><itemize> -<item>The <bf/Linux-PAM/ System Administrators' Guide. -<item>The <bf/Linux-PAM/ Application Writers' Guide. -<item> -V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE -AUTHENTICATION MODULES'', Open Software Foundation Request For -Comments 86.0, October 1995. -</itemize> - -<sect>Notes - -<p> -I intend to put development comments here... like ``at the moment -this isn't actually supported''. At release time what ever is in -this section will be placed in the Bugs section below! :) - -<p> -<itemize> -<item> -Perhaps we should keep a registry of data-names as used by -<tt/pam_[gs]et_data()/ so there are no unintentional problems due to -conflicts? - -<item> -<tt/pam_strerror()/ should be internationalized.... - -<item> -There has been some debate about whether <tt/initgroups()/ should be -in an application or in a module. It was settled by Sun who stated -that initgroups is an action of the <em/application/. The modules are -permitted to add additional groups, however. - -<item> -Refinements/futher suggestions to <tt/syslog(3)/ usage by modules are -needed. - -</itemize> - -<sect>Author/acknowledgments - -<p> -This document was written by Andrew G. Morgan -(<tt/morgan@kernel.org/) with many contributions from -<!-- insert credits here --> -<!-- - an sgml list of people to credit for their contributions to Linux-PAM - $Id$ - --> -Chris Adams, -Peter Allgeyer, -Tim Baverstock, -Tim Berger, -Craig S. Bell, -Derrick J. Brashear, -Ben Buxton, -Seth Chaiklin, -Oliver Crow, -Chris Dent, -Marc Ewing, -Cristian Gafton, -Emmanuel Galanos, -Brad M. Garcia, -Eric Hester, -Roger Hu, -Eric Jacksch, -Michael K. Johnson, -David Kinchlea, -Olaf Kirch, -Marcin Korzonek, -Stephen Langasek, -Nicolai Langfeldt, -Elliot Lee, -Luke Kenneth Casson Leighton, -Al Longyear, -Ingo Luetkebohle, -Marek Michalkiewicz, -Robert Milkowski, -Aleph One, -Martin Pool, -Sean Reifschneider, -Jan Rekorajski, -Erik Troan, -Theodore Ts'o, -Jeff Uphoff, -Myles Uyema, -Savochkin Andrey Vladimirovich, -Ronald Wahl, -David Wood, -John Wilmes, -Joseph S. D. Yao -and -Alex O. Yuriev. - -<p> -Thanks are also due to Sun Microsystems, especially to Vipin Samar and -Charlie Lai for their advice. At an early stage in the development of -<bf/Linux-PAM/, Sun graciously made the documentation for their -implementation of PAM available. This act greatly accelerated the -development of <bf/Linux-PAM/. - -<sect>Bugs/omissions - -<p> -Few PAM modules currently exist. Few PAM-aware applications exist. -This document is hopelessly unfinished. Only a partial list of people is -credited for all the good work they have done. - -<sect>Copyright information for this document - -<p> -Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. -<newline> -Email: <tt><morgan@kernel.org></tt> - -<p> -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -<p> -<itemize> - -<item> -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -<item> -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -<item> -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -</itemize> - -<p> -<bf/Alternatively/, this product may be distributed under the terms of -the GNU General Public License (GPL), in which case the provisions of -the GNU GPL are required <bf/instead of/ the above restrictions. -(This clause is necessary due to a potential bad interaction between -the GNU GPL and the restrictions contained in a BSD-style copyright.) - -<p> -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. - -<p> -<tt>$Id$</tt> - -</article> diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml deleted file mode 100644 index 2dd5783e..00000000 --- a/doc/pam_source.sgml +++ /dev/null @@ -1,1160 +0,0 @@ -<!doctype linuxdoc system> - -<!-- - - $Id$ - - Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. - -Redistribution and use in source (sgml) and binary (derived) forms, -with or without modification, are permitted provided that the -following conditions are met: - -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -ALTERNATIVELY, this product may be distributed under the terms of the -GNU General Public License, in which case the provisions of the GNU -GPL are required INSTEAD OF the above restrictions. (This clause is -necessary due to a potential bad interaction between the GNU GPL and -the restrictions contained in a BSD-style copyright.) - -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. - - --> - -<article> - -<title>The Linux-PAM System Administrators' Guide -<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2002/06/26 -<abstract> -This manual documents what a system-administrator needs to know about -the <bf>Linux-PAM</bf> library. It covers the correct syntax of the -PAM configuration file and discusses strategies for maintaining a -secure system. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Introduction - -<p><bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a -suite of shared libraries that enable the local system administrator -to choose how applications authenticate users. - -<p>In other words, without (rewriting and) recompiling a PAM-aware -application, it is possible to switch between the authentication -mechanism(s) it uses. Indeed, one may entirely upgrade the local -authentication system without touching the applications themselves. - -<p>Historically an application that has required a given user to be -authenticated, has had to be compiled to use a specific authentication -mechanism. For example, in the case of traditional UN*X systems, the -identity of the user is verified by the user entering a correct -password. This password, after being prefixed by a two character -``salt'', is encrypted (with crypt(3)). The user is then authenticated -if this encrypted password is identical to the second field of the -user's entry in the system password database (the <tt>/etc/passwd</tt> -file). On such systems, most if not all forms of privileges are -granted based on this single authentication scheme. Privilege comes in -the form of a personal user-identifier (<tt/uid/) and membership of -various groups. Services and applications are available based on the -personal and group identity of the user. Traditionally, group -membership has been assigned based on entries in the -<tt>/etc/group</tt> file. - -<p> -Unfortunately, increases in the speed of computers and the -widespread introduction of network based computing, have made once -secure authentication mechanisms, such as this, vulnerable to -attack. In the light of such realities, new methods of authentication -are continuously being developed. - -<p> -It is the purpose of the <bf/Linux-PAM/ project to separate the -development of privilege granting software from the development of -secure and appropriate authentication schemes. This is accomplished -by providing a library of functions that an application may use to -request that a user be authenticated. This PAM library is configured -locally with a system file, <tt>/etc/pam.conf</tt> (or a series of -configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a -user request via the locally available authentication modules. The -modules themselves will usually be located in the directory -<tt>/lib/security</tt> and take the form of dynamically loadable -object files (see <tt/dlopen(3)/). - -<sect>Some comments on the text<label id="text-conventions"> - -<p> -Before proceeding to read the rest of this document, it should be -noted that the text assumes that certain files are placed in certain -directories. Where they have been specified, the conventions we adopt -here for locating these files are those of the relevant RFC (RFC-86.0, -see <ref id="see-also-sec" name="bibliography">). If you are using a -distribution of Linux (or some other operating system) that supports -PAM but chooses to distribute these files in a diferent way you should -be careful when copying examples directly from the text. - -<p> -As an example of the above, where it is explicit, the text assumes -that PAM loadable object files (the <em/modules/) are to be located in -the following directory: <tt>/lib/security/</tt>. This is generally -the location that seems to be compatible with the Linux File System -Standard (the FSSTND). On Solaris, which has its own licensed version -of PAM, and some other implementations of UN*X, these files can be -found in <tt>/usr/lib/security</tt>. Please be careful to perform the -necessary transcription when using the examples from the text. - -<sect>Overview<label id="overview-section"> - -<p> -For the uninitiated, we begin by considering an example. We take an -application that grants some service to users; <em/login/ is one such -program. <em/Login/ does two things, it first establishes that the -requesting user is whom they claim to be and second provides them with -the requested service: in the case of <em/login/ the service is a -command shell (<em>bash, tcsh, zsh, etc.</em>) running with the -identity of the user. - -<p> -Traditionally, the former step is achieved by the <em/login/ -application prompting the user for a password and then verifying that -it agrees with that located on the system; hence verifying that -as far as the system is concerned the user is who they claim to be. -This is the task that is delegated to <bf/Linux-PAM/. - -<p> -From the perspective of the application programmer (in this case the -person that wrote the <em/login/ application), <bf/Linux-PAM/ takes -care of this authentication task -- verifying the identity of the user. - -<p> -The flexibility of <bf/Linux-PAM/ is that <em/you/, the system -administrator, have the freedom to stipulate which authentication -scheme is to be used. You have the freedom to set the scheme for -any/all PAM-aware applications on your Linux system. That is, you can -authenticate from anything as naive as <em/simple trust/ -(<tt/pam_permit/) to something as paranoid as a combination of a -retinal scan, a voice print and a one-time password! - -<p> -To illustrate the flexibility you face, consider the following -situation: a system administrator (parent) wishes to improve the -mathematical ability of her users (children). She can configure their -favorite ``Shoot 'em up game'' (PAM-aware of course) to authenticate -them with a request for the product of a couple of random numbers less -than 12. It is clear that if the game is any good they will soon learn -their <em/multiplication tables/. As they mature, the authentication -can be upgraded to include (long) division! - -<p> -<bf/Linux-PAM/ deals with four separate types of (management) -task. These are: <em/authentication management/; <em/account -management/; <em/session management/; and <em/password management/. -The association of the preferred management scheme with the behavior -of an application is made with entries in the relevant <bf/Linux-PAM/ -configuration file. The management functions are performed by -<em/modules/ specified in the configuration file. The syntax for this -file is discussed in the section <ref id="configuration" -name="below">. - -<p> -Here is a figure that describes the overall organization of -<bf/Linux-PAM/. -<tscreen> -<verb> - +----------------+ - | application: X | - +----------------+ / +----------+ +================+ - | authentication-[---->--\--] Linux- |--<--| PAM config file| - | + [----<--/--] PAM | |================| - |[conversation()][--+ \ | | | X auth .. a.so | - +----------------+ | / +-n--n-----+ | X auth .. b.so | - | | | __| | | _____/ - | service user | A | | |____,-----' - | | | V A - +----------------+ +------|-----|---------+ -----+------+ - +---u-----u----+ | | | - | auth.... |--[ a ]--[ b ]--[ c ] - +--------------+ - | acct.... |--[ b ]--[ d ] - +--------------+ - | password |--[ b ]--[ c ] - +--------------+ - | session |--[ e ]--[ c ] - +--------------+ -</verb> -</tscreen> -By way of explanation, the left of the figure represents the -application; application X. Such an application interfaces with the -<bf/Linux-PAM/ library and knows none of the specifics of its -configured authentication method. The <bf/Linux-PAM/ library (in the -center) consults the contents of the PAM configuration file and loads -the modules that are appropriate for application-X. These modules fall -into one of four management groups (lower-center) and are stacked in -the order they appear in the configuration file. These modules, when -called by <bf/Linux-PAM/, perform the various authentication tasks for -the application. Textual information, required from/or offered to the -user, can be exchanged through the use of the application-supplied -<em/conversation/ function. - -<sect1>Getting started - -<p> -The following text was contributed by Seth Chaiklin: -<tscreen> -<verb> -To this point, we have described how PAM should work in an -ideal world, in which all applications are coded properly. -However, at the present time (October 1998), this is far -from the case. Therefore, here are some practical considerations -in trying to use PAM in your system. - -Why bother, is it really worth all the trouble? - -If you running Linux as a single user system, or in an -environment where all the users are trusted, then there -is no real advantage for using PAM. -</verb> -</tscreen> - -<p> -<BF>Ed:</BF> there is actually an advantage since you can <em/dummy -down/ the authentication to the point where you don't have -any... Almost like Win95. -<p> -In a networked environment, it is clear that you need to think a -little more about how users etc., are authenticated:] - -<p> -<tscreen> -<verb> -If you are running Linux as a server, where several different -services are being provided (e.g., WWW with areas restricted by -password control, PPP), then there can be some real and interesting -value for PAM. In particular, through the use of modules, PAM can -enable a program to search through several different password -databases, even if that program is not explicitly coded for -that particular database. Here are some examples of the possibilities -that this enables. - - o Apache has a module that provides PAM services. Now - authentication - to use particular directories can be conducted by PAM, which - means that the range of modules that are available to PAM can - be used, including RADIUS, NIS, NCP (which means that Novell - password databases can be used). - - o pppd has a PAMified version (available from RedHat) Now it is - possible to use a series of databases to authenticate ppp users. - In addition to the normal Linux-based password databases (such - as /etc/passwd and /etc/shadow), you can use PAM modules to - authenticate against Novell password databases or NT-based - password databases. - - o The preceding two examples can be combined. Imagaine that the - persons in your office/department are already registered with a - username and password in a Novell or NT LAN. If you wanted to - use this database on your Linux server (for PPP access, for - web access, or even for normal shell access), you can use PAM - to authenticate against this existing database, rather than - maintain a separate database on both Linux and the LAN server. - - -Can I use PAM for any program that requires authentication? - -Yes and no. Yes, if you have access to the source code, and can -add the appropriate PAM functions. No, if you do not have access -to the source code, and the binary does not have the PAM functions -included. - -In other words, if a program is going to use PAM, then it has to -have PAM functions explicitly coded into the program. If they -are not, then it is not possible to use PAM. - -How can I tell whether a program has PAM coded into it or not? - -A quick-and-dirty (but not always reliable) method is to ldd -<programname> -If libpam and libpam_misc are not among the libraries that the program -uses, then it is not going to work with PAM. However, it is possible -that the libraries are included, but there are still problems, because -the PAM coding in the program does not work as it should. So a -more reliable method is to make the follow tests. - -In the /etc/pam.d directory, one needs to make a configuration file -for the program that one wants to run. The exact name of the -configuration -file is hard-coded into the program. Usually, it is the same name as -the -program, but not always. For sake of illustration, let's assume that -the program is named "pamprog" and the name of the configuration file -is /etc/pam.d/pamprog. - -In the /etc/pam.d/pamprog but the following two lines: - -auth required pam_permit.so -auth required pam_warn.so - - -Now try to use pamprog. The first line in the configuration file -says that all users are permitted. The second line will write a -warning to your syslog file (or whether you syslog is writing - -messages). If this test succeeds, then you know that you have -a program that can understand pam, and you can start the more -interesting work of deciding how to stack modules in your -/etc/pam.d/pamprog file. -</verb> -</tscreen> - -<sect>The Linux-PAM configuration file -<label id="configuration"> - -<p> -<bf/Linux-PAM/ is designed to provide the system administrator with a -great deal of flexibility in configuring the privilege granting -applications of their system. The local configuration of those aspects -of system security controlled by <tt/Linux-PAM/ is contained in one of -two places: either the single system file, <tt>/etc/pam.conf</tt>; or -the <tt>/etc/pam.d/</tt> directory. In this section we discuss the -correct syntax of and generic options respected by entries to these -files. - -<sect1>Configuration file syntax - -<p> -The reader should note that the <bf/Linux-PAM/ specific tokens in this -file are case <em/insensitive/. The module paths, however, are case -sensitive since they indicate a file's <em/name/ and reflect the case -dependence of typical Linux file-systems. The case-sensitivity of the -arguments to any given module is defined for each module in turn. - -<p> -In addition to the lines described below, there are two <em/special/ -characters provided for the convenience of the system administrator: -comments are preceded by a `<tt/#/' and extend to the -next end-of-line; also, module specification lines may be extended -with a `<tt/\/' escaped newline. - -<p> -A general configuration line of the <tt>/etc/pam.conf</tt> file has -the following form: -<tscreen> -<verb> -service-name module-type control-flag module-path args -</verb> -</tscreen> -Below, we explain the meaning of each of these tokens. The second (and -more recently adopted) way of configuring <bf/Linux-PAM/ is via the -contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained -the meaning of the above tokens, we will describe this method. - -<p> -<descrip> -<tag><tt/service-name/</tag> -The name of the service associated with this entry. Frequently the -service name is the conventional name of the given application. For -example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ . - -<p> -There is a special <tt/service-name/, reserved for defining a default -authentication mechanism. It has the name `<tt/OTHER/' and may be -specified in either lower or upper case characters. Note, when there -is a module specified for a named service, the `<tt/OTHER/' entries -are ignored. - -<tag><tt/module-type/</tag> -One of (currently) four types of module. The four types are as -follows: -<itemize> -<item> <tt/auth/; this module type provides two aspects of -authenticating the user. Firstly, it establishes that the user is who -they claim to be, by instructing the application to prompt the user -for a password or other means of identification. Secondly, the module -can grant <tt/group/ membership (independently of the -<tt>/etc/groups</tt> file discussed above) or other privileges through -its <em/credential/ granting properties. - -<item> <tt/account/; this module performs non-authentication based -account management. It is typically used to restrict/permit access to -a service based on the time of day, currently available system -resources (maximum number of users) or perhaps the location of the -applicant user---`<tt/root/' login only on the console. - -<item> <tt/session/; primarily, this module is associated with doing -things that need to be done for the user before/after they can be -given service. Such things include the logging of information -concerning the opening/closing of some data exchange with a user, -mounting directories, etc. . - -<item> <tt/password/; this last module type is required for updating the -authentication token associated with the user. Typically, there is one -module for each `challenge/response' based authentication (<tt/auth/) -module-type. - -</itemize> - -<tag><tt/control-flag/</tag> - -The control-flag is used to indicate how the PAM library will react to -the success or failure of the module it is associated with. Since -modules can be <em/stacked/ (modules of the same type execute in -series, one after another), the control-flags determine the relative -importance of each module. The application is not made aware of the -individual success or failure of modules listed in the -`<tt>/etc/pam.conf</tt>' file. Instead, it receives a summary -<em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library. -The order of execution of these modules is that of the entries in the -<tt>/etc/pam.conf</tt> file; earlier entries are executed before later -ones. As of Linux-PAM v0.60, this <em/control-flag/ can be defined -with one of two syntaxes. - -<p> -The simpler (and historical) syntax for the control-flag is a single -keyword defined to indicate the severity of concern associated with -the success or failure of a specific module. There are four such -keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and -<tt/optional/. - -<p> -The Linux-PAM library interprets these keywords in the following -manner: - -<itemize> - -<item> <tt/required/; this indicates that the success of the module is -required for the <tt/module-type/ facility to succeed. Failure of this -module will not be apparent to the user until all of the remaining -modules (of the same <tt/module-type/) have been executed. - -<item> <tt/requisite/; like <tt/required/, however, in the case that -such a module returns a failure, control is directly returned to the -application. The return value is that associated with the <em/first/ -<tt/required/ or <tt/requisite/ module to fail. Note, this flag can be -used to protect against the possibility of a user getting the -opportunity to enter a password over an unsafe medium. It is -conceivable that such behavior might inform an attacker of valid -accounts on a system. This possibility should be weighed against the -not insignificant concerns of exposing a sensitive password in a -hostile environment. - -<item> <tt/sufficient/; the success of this module is deemed -`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this -module-type has succeeded in its purpose. In the event that no -previous <tt/required/ module has failed, no more `<em/stacked/' -modules of this type are invoked. (Note, in this case subsequent -<tt/required/ modules are <bf/not/ invoked.). A failure of this module -is not deemed as fatal to satisfying the application that this -<tt/module-type/ has succeeded. - -<item> <tt/optional/; as its name suggests, this <tt/control-flag/ -marks the module as not being critical to the success or failure of -the user's application for service. In general, <bf/Linux-PAM/ -ignores such a module when determining if the module stack will -succeed or fail. However, in the absence of any definite successes or -failures of previous or subsequent stacked modules this module will -determine the nature of the response to the application. One example -of this latter case, is when the other modules return something like -<tt/PAM_IGNORE/. - -</itemize> - -<p> -The more elaborate (newer) syntax is much more specific and gives the -administrator a great deal of control over how the user is -authenticated. This form of the control flag is delimeted with square -brackets and consists of a series of <tt/value=action/ tokens: -<tscreen> -<verb> - [value1=action1 value2=action2 ...] -</verb> -</tscreen> - -<p> -Here, <tt/valueI/ is one of the following <em/return values/: -<tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/; -<tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/; -<tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/; -<tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/; -<tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/; -<tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/; -<tt/authtok_recover_err/; <tt/authtok_lock_busy/; -<tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/; -<tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and -<tt/default/. The last of these (<tt/default/) can be used to set the -action for those return values that are not explicitly defined. - -<p> -The <tt/actionI/ can be a positive integer or one of the following -tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and -<tt/reset/. A positive integer, <tt/J/, when specified as the action, -can be used to indicate that the next <em/J/ modules of the current -module-type will be skipped. In this way, the administrator can -develop a moderately sophisticated stack of modules with a number of -different paths of execution. Which path is taken can be determined -by the reactions of individual modules. - -<p> -<itemize> -<item><tt/ignore/ - when used with a stack of modules, the module's - return status will not contribute to the return code the application - obtains. -<item><tt/bad/ - this action indicates that the return code should be - thought of as indicative of the module failing. If this module is - the first in the stack to fail, its status value will be used for - that of the whole stack. -<item><tt/die/ - equivalent to <tt/bad/ with the side effect of - terminating the module stack and PAM immediately returning to the - application. -<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this - return code should contribute directly to the return code of the full - stack of modules. In other words, if the former state of the stack - would lead to a return of <tt/PAM_SUCCESS/, the module's return code - will override this value. Note, if the former state of the stack - holds some value that is indicative of a modules failure, this 'ok' - value will not be used to override that value. -<item><tt/done/ - equivalent to <tt/ok/ with the side effect of - terminating the module stack and PAM immediately returning to the - application. -<item><tt/reset/ - clear all memory of the state of the module stack and - start again with the next stacked module. -</itemize> - -<p> -Each of the four keywords: <tt/required/; <tt/requisite/; -<tt/sufficient/; and <tt/optional/, have an equivalent expression in -terms of the <tt/[...]/ syntax. They are as follows: -<itemize> -<item><tt/required/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=bad]/ -<item><tt/requisite/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=die]/ -<item><tt/sufficient/ is equivalent to -<tt/[success=done new_authtok_reqd=done default=ignore]/ -<item><tt/optional/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok default=ignore]/ -</itemize> - -<p> -Just to get a feel for the power of this new syntax, here is a taste -of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of -client plug-in agents was introduced. This is something that makes it -possible for PAM to support machine-machine authentication using the -transport protocol inherent to the client/server application. With -the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible -for an application to be configured to support binary prompts with -compliant clients, but to gracefully fall over into an alternative -authentication mode for older, legacy, applications. - -<tag> <tt/module-path/</tag> - -The path-name of the dynamically loadable object file; <em/the -pluggable module/ itself. If the first character of the module path is -`<tt>/</tt>', it is assumed to be a complete path. If this is not the -case, the given module path is appended to the default module path: -<tt>/lib/security</tt> (but see the notes <ref id="text-conventions" -name="above">). - -<tag> <tt/args/</tag> - -The <tt/args/ are a list of tokens that are passed to the module when -it is invoked. Much like arguments to a typical Linux shell command. -Generally, valid arguments are optional and are specific to any given -module. Invalid arguments are ignored by a module, however, when -encountering an invalid argument, the module is required to write an -error to <tt/syslog(3)/. For a list of <em/generic/ options see the -next section. - -Note, if you wish to include spaces in an argument, you should -surround that argument with square brackets. For example: -<tscreen> -<verb> -squid auth required pam_mysql.so user=passwd_query passwd=mada \ - db=eminence [query=select user_name from internet_service where \ - user_name='%u' and password=PASSWORD('%p') and \ - service='web_proxy'] -</verb> -</tscreen> -Note, when using this convention, you can include `<tt/[/' characters -inside the string, and if you wish to include a `<tt/]/' character -inside the string that will survive the argument parsing, you should -use `<tt/\[/'. In other words: -<tscreen> -<verb> -[..[..\]..] --> ..[..].. -</verb> -</tscreen> - -</descrip> - -<p> -Any line in (one of) the configuration file(s), that is not formatted -correctly, will generally tend (erring on the side of caution) to make -the authentication process fail. A corresponding error is written to -the system log files with a call to <tt/syslog(3)/. - -<sect1>Directory based configuration - -<p> -More flexible than the single configuration file, as of version 0.56, -it is possible to configure <tt>libpam</tt> via the contents of the -<tt>/etc/pam.d/</tt> directory. In this case the directory is filled -with files each of which has a filename equal to a service-name (in -lower-case): it is the personal configuration file for the named -service. - -<p> -<bf/Linux-PAM/ can be compiled in one of two modes. The preferred -mode uses either <tt>/etc/pam.d/</tt> or <tt>/etc/pam.conf</tt> -configuration but not both. That is to say, if there is a -<tt>/etc/pam.d/</tt> directory then libpam only uses the files -contained in this directory. However, in the absence of the -<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is used -(this is likely to be the mode your preferred distribution uses). The -other mode is to use both <tt>/etc/pam.d/</tt> and -<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in -<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>. - -The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of -the <tt>/etc/pam.conf</tt> file and is made up of lines of the -following form: -<tscreen> -<verb> -module-type control-flag module-path arguments -</verb> -</tscreen> -The only difference being that the <tt>service-name</tt> is not -present. The service-name is of course the name of the given -configuration file. For example, <tt>/etc/pam.d/login</tt> contains -the configuration for the <em>login</em> service. - -<p> -This method of configuration has a number of advantages over the -single file approach. We list them here to assist the reader in -deciding which scheme to adopt: - -<p> -<itemize> - -<item>A lower chance of misconfiguring an application. There is one -less field to mis-type when editing the configuration files by hand. - -<item>Easier to maintain. One application may be reconfigured without -risk of interfering with other applications on the system. - -<item>It is possible to symbolically link different services -configuration files to a single file. This makes it easier to keep the -system policy for access consistent across different applications. -(It should be noted, to conserve space, it is equally possible to -<em>hard</em> link a number of configuration files. However, care -should be taken when administering this arrangement as editing a hard -linked file is likely to break the link.) - -<item>A potential for quicker configuration file parsing. Only the -relevant entries are parsed when a service gets bound to its modules. - -<item>It is possible to limit read access to individual <bf/Linux-PAM/ -configuration files using the file protections of the filesystem. - -<item>Package management becomes simpler. Every time a new -application is installed, it can be accompanied by an -<tt>/etc/pam.d/</tt><em>xxxxxx</em> file. - -</itemize> - -<sect1>Generic optional arguments - -<p> -The following are optional arguments which are likely to be understood -by any module. Arguments (including these) are in general -<em/optional/. - -<p> -<descrip> -<tag><tt/debug/</tag> - -Use the <tt/syslog(3)/ call to log debugging information to the system -log files. - -<tag> <tt/no_warn/</tag> - -Instruct module to not give warning messages to the application. - -<tag> <tt/use_first_pass/</tag> - -The module should not prompt the user for a password. Instead, it -should obtain the previously typed password (from the preceding -<tt/auth/ module), and use that. If that doesn't work, then the user -will not be authenticated. (This option is intended for <tt/auth/ -and <tt/password/ modules only). - -<tag> <tt/try_first_pass/</tag> - -The module should attempt authentication with the previously typed -password (from the preceding <tt/auth/ module). If that doesn't work, -then the user is prompted for a password. (This option is intended for -<tt/auth/ modules only). - -<tag> <tt/use_mapped_pass/</tag> - -This argument is not currently supported by any of the modules in the -<bf/Linux-PAM/ distribution because of possible consequences -associated with U.S. encryption exporting restrictions. Within the -U.S., module developers are, of course, free to implement it (as are -developers in other countries). For compatibility reasons we describe -its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref -id="see-also-sec" name="bibliography"> for a pointer to this document. - -<p> -The <tt/use_mapped_pass/ argument instructs the module to take the -clear text authentication token entered by a previous module (that -requests such a token) and use it to generate an encryption/decryption -key with which to safely store/retrieve the authentication token -required for this module. In this way the user can enter a single -authentication token and be quietly authenticated by a number of -stacked modules. Obviously a convenient feature that necessarily -requires some reliably strong encryption to make it secure. -This argument is intended for the <tt/auth/ and <tt/password/ module -types only. - -<tag><tt/expose_account/</tag> - -<p> -In general the leakage of some information about user accounts is not -a secure policy for modules to adopt. Sometimes information such as -users names or home directories, or preferred shell, can be used to -attack a user's account. In some circumstances, however, this sort of -information is not deemed a threat: displaying a user's full name when -asking them for a password in a secured environment could also be -called being 'friendly'. The <tt/expose_account/ argument is a -standard module argument to encourage a module to be less discrete -about account information as it is deemed appropriate by the local -administrator. - -</descrip> - -<sect1>Example configuration file entries - -<p> -In this section, we give some examples of entries that can be present -in the <bf/Linux-PAM/ configuration file. As a first attempt at -configuring your system you could do worse than to implement these. - -<sect2>Default policy - -<p> -If a system is to be considered secure, it had better have a -reasonably secure `<tt/OTHER/' entry. The following is a paranoid -setting (which is not a bad place to start!): -<tscreen> -<verb> -# -# default; deny access -# -OTHER auth required pam_deny.so -OTHER account required pam_deny.so -OTHER password required pam_deny.so -OTHER session required pam_deny.so -</verb> -</tscreen> -Whilst fundamentally a secure default, this is not very sympathetic to -a misconfigured system. For example, such a system is vulnerable to -locking everyone out should the rest of the file become badly written. - -<p> -The module <tt/pam_deny/ (documented in a later section) is not very -sophisticated. For example, it logs no information when it is invoked -so unless the users of a system contact the administrator when failing -to execute a service application, the administrator may go for a long -while in ignorance of the fact that his system is misconfigured. - -<p> -The addition of the following line before those in the above example -would provide a suitable warning to the administrator. -<tscreen> -<verb> -# -# default; wake up! This application is not configured -# -OTHER auth required pam_warn.so -OTHER password required pam_warn.so -</verb> -</tscreen> -Having two ``<tt/OTHER auth/'' lines is an example of stacking. - -<p> -On a system that uses the <tt>/etc/pam.d/</tt> configuration, the -corresponding default setup would be achieved with the following file: -<tscreen> -<verb> -# -# default configuration: /etc/pam.d/other -# -auth required pam_warn.so -auth required pam_deny.so -account required pam_deny.so -password required pam_warn.so -password required pam_deny.so -session required pam_deny.so -</verb> -</tscreen> -This is the only explicit example we give for an <tt>/etc/pam.d/</tt> -file. In general, it should be clear how to transpose the remaining -examples to this configuration scheme. - -<p> -On a less sensitive computer, one on which the system administrator -wishes to remain ignorant of much of the power of <tt/Linux-PAM/, the -following selection of lines (in <tt>/etc/pam.conf</tt>) is likely to -mimic the historically familiar Linux setup. -<tscreen> -<verb> -# -# default; standard UN*X access -# -OTHER auth required pam_unix.so -OTHER account required pam_unix.so -OTHER password required pam_unix.so -OTHER session required pam_unix.so -</verb> -</tscreen> -In general this will provide a starting place for most applications. -Unfortunately, most is not all. One application that might require -additional lines is <em/ftpd/ if you wish to enable -<em/anonymous-ftp/. - -<p> -To enable anonymous-ftp, the following lines might be used to replace -the default (<tt/OTHER/) ones. (<bf/*WARNING*/ as of 1996/12/28 this -does not work correctly with any ftpd. Consequently, this description -may be subject to change or the application will be fixed.) -<tscreen> -<verb> -# -# ftpd; add ftp-specifics. These lines enable anonymous ftp over -# standard UN*X access (the listfile entry blocks access to -# users listed in /etc/ftpusers) -# -ftpd auth sufficient pam_ftp.so -ftpd auth required pam_unix_auth.so use_first_pass -ftpd auth required pam_listfile.so \ - onerr=succeed item=user sense=deny file=/etc/ftpusers -</verb> -</tscreen> -Note, the second line is necessary since the default entries are -ignored by a service application (here <em/ftpd/) if there are -<em/any/ entries in <tt>/etc/pam.conf</tt> for that specified service. -Again, this is an example of authentication module stacking. Note the -use of the <tt/sufficient/ control-flag. It says that ``if this module -authenticates the user, ignore the subsequent <tt/auth/ -modules''. Also note the use of the ``<tt/use_first_pass/'' -module-argument, this instructs the UN*X authentication module that it -is not to prompt for a password but rely on one already having been -obtained by the <tt/pam_ftp/ module. - -<sect>Security issues of Linux-PAM - -<p> -This section will discuss good practices for using PAM in a secure -manner. <em>It is currently sadly lacking...suggestions are -welcome!</em> - -<sect1>If something goes wrong - -<p> -<bf/Linux-PAM/ has the potential to seriously change the security of -your system. You can choose to have no security or absolute security -(no access permitted). In general, <bf/Linux-PAM/ errs towards the -latter. Any number of configuration errors can dissable access to -your system partially, or completely. - -<p> -The most dramatic problem that is likely to be encountered when -configuring <bf/Linux-PAM/ is that of <em>deleting</em> the -configuration file(s): <tt>/etc/pam.d/*</tt> and/or -<tt>/etc/pam.conf</tt>. This will lock you out of your own system! - -<p> -To recover, your best bet is to reboot the system in single user mode -and set about correcting things from there. The following has been -<em>adapted</em> from a life-saving email on the subject from David -Wood: -<verb> -> What the hell do I do now? - -OK, don't panic. The first thing you have to realize is that -this happens to 50% of users who ever do anything with PAM. -It happened here, not once, not twice, but three times, all -different, and in the end, the solution was the same every -time. - -First, I hope you installed LILO with a delay. If you can, -reboot, hit shift or tab or something and type: - - LILO boot: linux single - -(Replace 'linux' with 'name-of-your-normal-linux-image'). -This will let you in without logging in. Ever wondered how -easy it is to break into a linux machine from the console? -Now you know. - -If you can't do that, then get yourself a bootkernel floppy -and a root disk a-la slackware's rescue.gz. (Red Hat's -installation disks can be used in this mode too.) - -In either case, the point is to get back your root prompt. - -Second, I'm going to assume that you haven't completely -nuked your pam installation - just your configuration files. -Here's how you make your configs nice again: - - cd /etc - mv pam.conf pam.conf.orig - mv pam.d pam.d.orig - mkdir pam.d - cd pam.d - -and then use vi to create a file called "other" in this -directory. It should contain the following four lines: - - auth required pam_unix.so - account required pam_unix.so - password required pam_unix.so - session required pam_unix.so - -Now you have the simplest possible PAM configuration that -will work the way you're used to. Everything should -magically start to work again. Try it out by hitting ALT-F2 -and logging in on another virtual console. If it doesn't -work, you have bigger problems, or you've mistyped -something. One of the wonders of this system (seriously, -perhaps) is that if you mistype anything in the conf files, -you usually get no error reporting of any kind on the -console - just some entries in the log file. So look there! -(Try 'tail /var/log/messages'.) - -From here you can go back and get a real configuration -going, hopefully after you've tested it first on a machine -you don't care about screwing up. :/ - -Some pointers (to make everything "right" with Red Hat...): - - Install the newest pam, pamconfig, and pwdb from the - redhat current directory, and do it all on the same - command line with rpm... - - rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-* - - Then make sure you install (or reinstall) the newest - version of libc, util-linux, wuftp, and NetKit. For - kicks you might try installing the newest versions of - the affected x apps, like xlock, but I haven't gotten - those to work at all yet. - -</verb> - -<sect1>Avoid having a weak `other' configuration - -<p> -It is not a good thing to have a weak default (<tt/OTHER/) entry. -This service is the default configuration for all PAM aware -applications and if it is weak, your system is likely to be vulnerable -to attack. - -<p> -Here is a sample "other" configuration file. The <em/pam_deny/ module will -deny access and the <em/pam_warn/ module will send a syslog message to -<tt/auth.notice/: - -<p> -<tscreen> -<verb> -# -# The PAM configuration file for the `other' service -# -auth required pam_deny.so -auth required pam_warn.so -account required pam_deny.so -account required pam_warn.so -password required pam_deny.so -password required pam_warn.so -session required pam_deny.so -session required pam_warn.so -</verb> -</tscreen> - -<sect>A reference guide for available modules - -<p> -Here, we collect together some descriptions of the various modules -available for <bf/Linux-PAM/. In general these modules should be -freely available. Where this is not the case, it will be indicated. - -<p> -Also please note the comments contained in the section <ref -id="text-conventions" name="on text conventions above"> when copying -the examples listed below. - -<!-- insert-file MODULES-SGML --> - -<sect>Files - -<p><descrip> - -<tag><tt>/lib/libpam.so.*</tt></tag> - -the shared library providing applications with access to -<bf/Linux-PAM/. - -<tag><tt>/etc/pam.conf</tt></tag> - -the <bf/Linux-PAM/ configuration file. - -<tag><tt>/lib/security/pam_*.so</tt></tag> - -the primary location for <bf/Linux-PAM/ dynamically loadable object -files; the modules. - -</descrip> - -<sect>See also<label id="see-also-sec"> - -<p><itemize> - -<item>The <bf/Linux-PAM/ Application Writers' Guide. - -<item>The <bf/Linux-PAM/ Module Writers' Guide. - -<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH -PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request -For Comments 86.0, October 1995. See this url: -<tt><htmlurl -url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz" -name="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz"></tt> - -</itemize> - -<sect>Notes - -<p> -I intend to put development comments here... like ``at the moment -this isn't actually supported''. At release time what ever is in -this section will be placed in the Bugs section below! :) - -<p> -Are we going to be able to support the <tt/use_mapped_pass/ module -argument? Anyone know a cheap (free) good lawyer?! - -<p> -<itemize> -<item> -This issue may go away, as Sun have investigated adding a new -management group for mappings. In this way, libpam would have mapping -modules that could securely store passwords using strong cryptography -and in such a way that they need not be distributed with Linux-PAM. -</itemize> - -<sect>Author/acknowledgments - -<p> -This document was written by Andrew G. Morgan (morgan@kernel.org) -with many contributions from -<!-- insert-file CREDITS --> - -<p> -Thanks are also due to Sun Microsystems, especially to Vipin Samar and -Charlie Lai for their advice. At an early stage in the development of -<bf/Linux-PAM/, Sun graciously made the documentation for their -implementation of PAM available. This act greatly accelerated the -development of <bf/Linux-PAM/. - -<sect>Bugs/omissions - -<p> -More PAM modules are being developed all the time. It is unlikely that -this document will ever be truely up to date! - -<p> -This manual is unfinished. Only a partial list of people is credited -for all the good work they have done. - -<sect>Copyright information for this document - -<p> -Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. -<newline> -Email: <tt><morgan@kernel.org></tt> - -<p> -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -<p> -<itemize> - -<item> -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -<item> -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -<item> -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -</itemize> - -<p> -<bf/Alternatively/, this product may be distributed under the terms of -the GNU General Public License (GPL), in which case the provisions of -the GNU GPL are required <bf/instead of/ the above restrictions. -(This clause is necessary due to a potential bad interaction between -the GNU GPL and the restrictions contained in a BSD-style copyright.) - -<p> -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED -WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, -INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH -DAMAGE. - -<p> -<tt>$Id$</tt> - -</article> diff --git a/doc/pdf/.cvsignore b/doc/pdf/.cvsignore deleted file mode 100644 index a1363379..00000000 --- a/doc/pdf/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.pdf diff --git a/doc/pdf/README b/doc/pdf/README deleted file mode 100644 index 82efcd46..00000000 --- a/doc/pdf/README +++ /dev/null @@ -1,3 +0,0 @@ -$Id$ - -a directory for PDF versions of the documentation diff --git a/doc/ps/.cvsignore b/doc/ps/.cvsignore deleted file mode 100644 index fa1d1137..00000000 --- a/doc/ps/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -pam*.ps diff --git a/doc/ps/README b/doc/ps/README deleted file mode 100644 index 32a833f6..00000000 --- a/doc/ps/README +++ /dev/null @@ -1,3 +0,0 @@ -$Id$ - -this is the directory for the PostScript documentation diff --git a/doc/specs/.cvsignore b/doc/specs/.cvsignore deleted file mode 100644 index d564ba7e..00000000 --- a/doc/specs/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -draft-morgan-pam-*.txt diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw deleted file mode 100644 index 45109f45..00000000 --- a/doc/specs/draft-morgan-pam.raw +++ /dev/null @@ -1,764 +0,0 @@ -Open-PAM working group ## A.G. Morgan -Internet Draft: ## Dec 8, 2001 -Document: draft-morgan-pam-08.txt ## -Expires: June 8, 2002 ## -Obsoletes: draft-morgan-pam-07.txt## - -## Pluggable Authentication Modules (PAM) ## - -#$ Status of this memo - -This document is a draft specification. Its contents are subject to -change with revision. The latest version of this draft may be obtained -from here: - - http://www.kernel.org/pub/linux/libs/pam/pre/doc/ - -As - - Linux-PAM-'version'-docs.tar.gz - -It is also contained in the Linux-PAM tar ball. - -#$ Abstract - -This document is concerned with the definition of a general -infrastructure for module based authentication. The infrastructure is -named Pluggable Authentication Modules (PAM for short). - -#$ Introduction - -Computers are tools. They provide services to people and other -computers (collectively we shall call these _users_ entities). In -order to provide convenient, reliable and individual service to -different entities, it is common for entities to be labelled. Having -defined a label as referring to a some specific entity, the label is -used for the purpose of protecting and allocating data resources. - -All modern operating systems have a notion of labelled entities and -all modern operating systems face a common problem: how to -authenticate the association of a predefined label with applicant -entities. - -There are as many authentication methods as one might care to count. -None of them are perfect and none of them are invulnerable. In -general, any given authentication method becomes weaker over time. It -is common then for new authentication methods to be developed in -response to newly discovered weaknesses in the old authentication -methods. - -The problem with inventing new authentication methods is the fact that -old applications do not support them. This contributes to an inertia -that discourages the overhaul of weakly protected systems. Another -problem is that individuals (people) are frequently powerless to layer -the protective authentication around their systems. They are forced -to rely on single (lowest common denominator) authentication schemes -even in situations where this is far from appropriate. - -PAM, as discussed in this document, is a generalization of the -approach first introduced in [#$R#{OSF_RFC_PAM}]. In short, it is a -general framework of interfaces that abstract the process of -authentication. With PAM, a service provider can custom protect -individual services to the level that they deem is appropriate. - -PAM has nothing explicit to say about transport layer encryption. -Within the context of this document encryption and/or compression of -data exchanges are application specific (strictly between client and -server) and orthogonal to the process of authentication. - -#$ Definitions - -Here we pose the authentication problem as one of configuring defined -interfaces between two entities. - -#$$#{players} Players in the authentication process - -PAM reserves the following words to specify unique entities in the -authentication process: - - applicant - the entity (user) initiating an application for service - [PAM associates the PAM_RUSER _item_ with this requesting user]. - - arbitrator - the entity (user) under whose identity the service application - is negotiated and with whose authority service is granted. - - user - the entity (user) whose identity is being authenticated - [PAM associates the PAM_USER _item_ with this identity]. - - server - the application that provides service, or acts as an - authenticated gateway to the requested service. This - application is completely responsible for the server end of - the transport layer connecting the server to the client. - PAM makes no assumptions about how data is encapsulated for - exchanges between the server and the client, only that full - octet sequences can be freely exchanged without corruption. - - client - application providing the direct/primary interface to - applicant. This application is completely responsible - for the client end of the transport layer connecting the - server to the client. PAM makes no assumptions about how data - is encapsulated for exchanges between the server and the - client, only that full octet sequences can be freely - exchanged without corruption. - - module - authentication binary that provides server-side support for - some (arbitrary) authentication method. - - agent - authentication binary that provides client-side support for - some (arbitrary) authentication method. - -Here is a diagram to help orient the reader: - -## +-------+ +--------+ ## -## . . . . .| agent | .| module | ## -## . +-------+ .+--------+ ## -## V | . | ## -## . | V | ## -## +---------+ +-------+ . +------+ ## -## | | |libpamc| . |libpam| ## -## | | +-------+ . +------+ ## -## |applicant| | . | ## -## | | +--------+ +----------+ ## -## | |---| client |-----------| server | ## -## +---------+ +--------+ +----------+ ## - -Solid lines connecting the boxes represent two-way interaction. The -dotted-directed lines indicate an optional connection beteween the -plugin module (agent) and the server (applicant). In the case of the -module, this represents the module invoking the 'conversation' -callback function provided to libpam by the server application when it -inititializes the libpam library. In the case of the agent, this may -be some out-of-PAM API interaction (for example directly displaying a -dialog box under X). - -#$$ Defined Data Types - -In this draft, we define two composite data types, the text string and -the binary prompt. They are the data types used to communicate -authentication requests and responses. - -#$$$#{text_string} text string - -The text string is a simple sequence of non-NUL (NUL = 0x00) -octets. Terminated with a single NUL (0x00) octet. The character set -employed in the octet sequence may be negotiated out of band, but -defaults to utf-8. - -## --------------------------- ## -## [ character data | NUL ] ## -## [ octet sequence | 0x00 ] ## -## --------------------------- ## - -Within the rest of this text, PAM text strings are delimited with a -pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}. - -#$$$#{binary_prompt} binary prompt - -A binary prompt consists of a stream of octets arranged as follows: - -## ---------------------------------------- ## -## [ u32 | u8 | (length-5 octets) ] ## -## [ length | control | data ] ## -## ---------------------------------------- ## - -That is, a 32-bit unsigned integer in network byte order, a single -unsigned byte of control information and a sequence of octets of -length (length-5). The composition of the _data_ is context dependent -but is generally not a concern for either the server or the client. It -is very much the concern of modules and agents. - -For purposes of interoperability, we define the following control -characters as legal. - -## value symbol description ## -## ------------------------------------------------- ## -## 0x01 PAM_BPC_OK - continuation packet ## -## 0x02 PAM_BPC_SELECT - initialization packet ## -## 0x03 PAM_BPC_DONE - termination packet ## -## 0x04 PAM_BPC_FAIL - unable to execute ## - -The following control characters are only legal for exchanges between -an agent and a client (it is the responsibility of the client to -enforce this rule in the face of a rogue server): - -## 0x41 PAM_BPC_GETENV - obtain client env.var ## -## 0x42 PAM_BPC_PUTENV - set client env.var ## -## 0x43 PAM_BPC_TEXT - display message ## -## 0x44 PAM_BPC_ERROR - display error message ## -## 0x45 PAM_BPC_PROMPT - echo'd text prompt ## -## 0x46 PAM_BPC_PASS - non-echo'd text prompt ## -## 0x46 PAM_BPC_STATUS - ping all active clients## -## 0x47 PAM_BPC_ABORT - please abort session ## - -Note, length is always equal to the total length of the binary -prompt and represented by a network ordered unsigned 32 bit integer. - -#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts - -Binary prompts of control type PAM_BPC_SELECT have a defined -data part. It is composed of three elements: - - {agent_id;'/';data} - -The agent_id is a sequence of characters satisfying the following -regexp: - - /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/ - -and has a specific form for each independent agent. - -o Agent_ids that do not contain an at-sign (@) are to be considered as - representing some authentication mode that is a "public - standard" see reference [#$R#{PAM_STD_AGENTIDS}]. Registered names - MUST NOT contain an at-sign (@). - -o Anyone can define additional agents by using names in the format - name@domainname, e.g. "ouragent@example.com". The part following - the at-sign MUST be a valid fully qualified internet domain name - [RFC-1034] controlled by the person or organization defining the - name. (Said another way, if you control the email address that - your agent has as an identifier, they you are entitled to use - this identifier.) It is up to each domain how it manages its local - namespace. - -The '/' character is a mandatory delimiter, indicating the end of the -agent_id. The trailing data is of a format specific to the agent with -the given agent_id. - - -#$$ Special cases - -In a previous section (#{players}) we identified the most general -selection of authentication participants. In the case of network -authentication, it is straightforward to ascribe identities to the -defined participants. However, there are also special (less general) -cases that we recognize here. - -The primary authentication step, when a user is directly introduced -into a computer system (log's on to a workstation) is a special case. -In this situation, the client and the server are generally one -application. Before authenticating such a user, the applicant is -formally unknown: PAM_RUSER is NULL. - -Some client-server implementations (telnet for example) provide -effective full tty connections. In these cases, the four simple text -string prompting cases (see below) can be handled as in the primary -login step. In other words, the server absorbs most of the overhead of -propagating authentication messages. In these cases, there needs to be -special client/server support for handling binary prompts. - -In some circumstances, a legacy network transfer protocol can carry -authentication information. In such cases, a desire to support legacy -clients (with no client-side support for PAM) will neccessitate the -'hardcoding' of an agent protocol into the server application. Whilst -against the spirit of PAM, this special casing can be managed by the -server's 'conversation function' (see below). The guiding principle -when implementing such support is for the application developer to -relegate the authentication process to the PAM module -- simply -performing a transcription of data from binary-prompt to legacy -network 'packet' and visa-versa for propagating replies back to the -driving PAM module. A common case of this is with network protocols -that define an initialization packet of "user+password". In such cases -one should attempt to support the "userpass" agent-id and its defined -protocol. - -#$ Defined interfaces for information flow - -Here, we discuss the information exchange interfaces between the -players in the authentication process. It should be understood that -the server side is responsible for driving the authentication of the -applicant. Notably, every request received by the client from the -server must be matched with a single response from the client to the -server. - -#$$#{applicant_client} Applicant <-> client - -Once the client is invoked, requests to the applicant entity are -initiated by the client application. General clients are able to make -the following requests directly to an applicant: - - echo text string - echo error text string - prompt with text string for echo'd text string input - prompt with text string for concealed text string input - -the nature of the interface provided by the client for the benefit of -the applicant entity is client specific and not defined by PAM. - -#$$#{client_agent} Client <-> agent - -In general, authentication schemes require more modes of exchange than -the four defined in the previous section (#{applicant_client}). This -provides a role for client-loadable agents. The client and agent -exchange binary-messages that can have one of the following forms: - - client -> agent - binary prompt agent expecting binary prompt reply to client - - agent -> client - binary prompt reply from agent to clients binary prompt - -Following the acceptance of a binary prompt by the agent, the agent -may attempt to exchange information with the client before returning -its binary prompt reply. Permitted exchanges are binary prompts of the -following types: - - agent -> client - set environment variable (A) - get environment variable (B) - echo text string (C) - echo error text string (D) - prompt for echo'd text string input (E) - prompt for concealed text string input (F) - -In response to these prompts, the client must legitimately respond -with a corresponding binary prompt reply. We list a complete set of -example exchanges, including each type of legitimate response (passes -and a single fail): - -## Type | Agent request | Client response ## -## --------------------------------------------------------------- ## -## (A) | {13;PAM_BPC_PUTENV;"FOO=BAR"} | {5;PAM_BPC_OK;} ## -## | {10;PAM_BPC_PUTENV;"FOO="} | {5;PAM_BPC_OK;} ## -## | {9;PAM_BPC_PUTENV;"FOO"} (*) | {5;PAM_BPC_OK;} ## -## | {9;PAM_BPC_PUTENV;"BAR"} (*) | {5;PAM_BPC_FAIL;} ## -## --------------------------------------------------------------- ## -## (B) | {10;PAM_BPC_GETENV;"TERM"} | {11;PAM_BPC_OK;"vt100"} ## -## | {9;PAM_BPC_GETENV;"FOO"} | {5;PAM_BPC_FAIL;} ## -## --------------------------------------------------------------- ## -## (C) | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_OK;} ## -## | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_FAIL;} ## -## --------------------------------------------------------------- ## -## (D) | {11;PAM_BPC_ERROR;"ouch!"} | {5;PAM_BPC_OK;} ## -## | {11;PAM_BPC_ERROR;"ouch!"} | {5;PAM_BPC_FAIL;} ## -## --------------------------------------------------------------- ## -## (E) | {13;PAM_BPC_PROMPT;"login: "} | {9;PAM_BPC_OK;"joe"} ## -## | {13;PAM_BPC_PROMPT;"login: "} | {6;PAM_BPC_OK;""} ## -## | {13;PAM_BPC_PROMPT;"login: "} | {5;PAM_BPC_FAIL;} ## -## --------------------------------------------------------------- ## -## (F) | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"} ## -## | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""} ## -## | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;} ## - -(*) Used to attempt the removal of a pre-existing environment -variable. - -#$$ Client <-> server - -Once the client has established a connection with the server (the -nature of the transport protocol is not specified by PAM), the server -is responsible for driving the authentication process. - -General servers can request the following from the client: - - (to be forwarded by the client to the applicant) - echo text string - echo error text string - prompt for echo'd text string response - prompt for concealed text string response - - (to be forwarded by the client to the appropriate agent) - binary prompt for a binary prompt response - -Client side agents are required to process binary prompts. The -agents' binary prompt responses are returned to the server. - -#$$ Server <-> module - -Modules drive the authentication process. The server provides a -conversation function with which it encapsulates module-generated -requests and exchanges them with the client. Every message sent by a -module should be acknowledged. - -General conversation functions can support the following five -conversation requests: - - echo text string - echo error string - prompt for echo'd text string response - prompt for concealed text string response - binary prompt for binary prompt response - -The server is responsible for redirecting these requests to the -client. - -#$ C API for application interfaces (client and server) - -#$$ Applicant <-> client - -No API is defined for this interface. The interface is considered to -be specific to the client application. Example applications include -terminal login, (X)windows login, machine file transfer applications. - -All that is important is that the client application is able to -present the applicant with textual output and to receive textual -input from the applicant. The forms of textual exchange are listed -in an earlier section (#{applicant_client}). Other methods of -data input/output are better suited to being handled via an -authentication agent. - -#$$ Client <-> agent - -The client makes use of a general API for communicating with -agents. The client is not required to communicate directly with -available agents, instead a layer of abstraction (in the form of a -library: libpamc) takes care of loading and maintaining communication -with all requested agents. This layer of abstraction will choose which -agents to interact with based on the content of binary prompts it -receives that have the control type PAM_BPC_SELECT. - -#$$$ Client <-> libpamc - -#$$$$ Compilation information - -The C-header file provided for client-agent abstraction is included -with the following source line: - - \#include <security/pam_client.h> - -The library providing the corresponding client-agent abstraction -functions is, libpamc. - - cc .... -lpamc - -#$$$$ Initializing libpamc - -The libpamc library is initialized with a call to the following -function: - - pamc_handle_t pamc_start(void); - -This function is responsible for configuring the library and -registering the location of available agents. The location of the -available agents on the system is implementation specific. - -pamc_start() function returns NULL on failure. Otherwise, the return -value is a pointer to an opaque data type which provides a handle to -the libpamc library. On systems where threading is available, the -libpamc libraray is thread safe provided a single (pamc_handler_t *) -is used by each thread. - -#$$$$ Client (Applicant) selection of agents - -For the purpose of applicant and client review of available agents, -the following function is provided. - - char **pamc_list_agents(pamc_handle_t pch); - -This returns a list of pointers to the agent_id's of the agents which -are available on the system. The list is terminated by a NULL pointer. -It is the clients responsibility to free this memory area by calling -free() on each agent id and the block of agent_id pointers in the -result. - -PAM represents a server-driven authentication model, so by default -any available agent may be invoked in the authentication process. - -#$$$$$ Client demands agent - -If the client requires that a specific authentication agent is -satisfied during the authentication process, then the client should -call the following function, immediately after obtaining a -pamc_handle_t from pamc_start(). - - int pamc_load(pamc_handle_t pch, const char *agent_id); - -agent_id is a PAM text string (see section #{agent_ids}) and is not -suffixed with a '/' delimiter. The return value for this function is: - - PAM_BPC_TRUE - agent located and loaded. - PAM_BPC_FALSE - agent is not available. - -Note, although the agent is loaded, no data is fed to it. The agent's -opportunity to inform the client that it does not trust the server is -when the agent is shutdown. - -#$$$$$ Client marks agent as unusable - -The applicant might prefer that a named agent is marked as not -available. To do this, the client would invoke the following function -immediately after obtaining a pamc_handle_t from pam_start(). - - int pamc_disable(pamc_handle_t pch, const char *agent_id); - -here agent_id is a PAM text string containing an agent_id (section -#{agent_ids}). - -The return value for this function is: - - PAM_BPC_TRUE - agent is disabled. This is the response - independent of whether the agent is locally - available. - - PAM_BPC_FALSE - agent cannot be disabled (this may be because - it has already been invoked). - -#$$$$ Allocating and manipulating binary prompts - -All conversation between an client and an agent takes place with -respect to binary prompts. A binary prompt (see section #{binary_prompt}), is -obtained, resized and deleted via the following C-macro: - - CREATION of a binary prompt with control X1 and data length Y1: - - pamc_bp_t prompt = NULL; - PAM_BP_RENEW(&prompt, X1, Y1); - - REPLACEMENT of a binary prompt with a control X2 and data length Y2: - - PAM_BP_RENEW(&prompt, X2, Y2); - - DELETION of a binary prompt (the referenced prompt is scrubbed): - - PAM_BP_RENEW(&prompt, 0, 0); - -Note, the PAM_BP_RENEW macro always overwrites any prompt that you -call it with, deleting and liberating the old contents in a secure -fashion. Also note that PAM_BP_RENEW, when returning a prompt of data -size Y1>0, will always append a '\0' byte to the end of the prompt (at -data offset Y1). It is thus, by definition, acceptable to treat the -data contents of a binary packet as a text string (see #{text_string}). - - FILLING a binary prompt from a memory pointer U1 from offset O1 of - length L1: - - PAM_BP_FILL(prompt, O1, L1, U1); - - the CONTROL type for the packet can be obtained as follows: - - control = PAM_PB_CONTROL(prompt); - - the LENGTH of a data within the prompt (_excluding_ its header - information) can be obtained as follows: - - length = PAM_BP_LENGTH(prompt); - - the total SIZE of the prompt (_including_ its header information) - can be obtained as follows: - - size = PAM_BP_SIZE(prompt); - - EXTRACTING data from a binary prompt from offset O2 of length L2 to - a memory pointer U2: - - PAM_BP_EXTRACT(prompt, O2, L2, U2); - - If you require direct access to the raw prompt DATA, you should use - the following macro: - - __u8 *raw_data = PAM_BP_DATA(prompt); - -#$$$$ Client<->agent conversations - -All exchanges of binary prompts with agents are handled with the -single function: - - int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p); - -The return value for pamc_converse(...) is PAM_BPC_TRUE when there is -a response packet and PAM_BPC_FALSE when the client is unable to -handle the request represented by the original prompt. In this latter -case, *prompt_p is set to NULL. - -This function takes a binary prompt and returns a replacement binary -prompt that is either a request from an agent to be acted upon by the -client or the 'result' which should be forwarded to the server. In the -former case, the following macro will return 1 (PAM_BPC_TRUE) and in -all other cases, 0 (PAM_BPC_FALSE): - - PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt) - -Note, all non-NULL binary prompts returned by pamc_converse(...), are -terminated with a '\0', even when the full length of the prompt (as -returned by the agent) does not contain this delimiter. This is a -defined property of the PAM_BP_RENEW macro, and can be relied upon. - -Important security note: in certain implementations, agents are -implemented by executable binaries, which are transparently loaded and -managed by the PAM client library. To ensure there is never a leakage -of elevated privilege to an unprivileged agent, the client application -should go to some effort to lower its level of privilege. It remains -the responsibility of the applicant and the client to ensure that it -is not compromised by a rogue agent. - -#$$$$ Status of agents - - int pamc_status(pamc_handle_t *pch, pamc_bp_t *prompt_p); - -At any time, the client may ping all active agents for their status -(with a PAM_BPC_STATUS binary prompt). If any agent replies with -PAM_BPC_ABORT, the client is responsible for terminating the -connection to the server and then terminating all agents with a call -to pamc_end(). In such cases, the return value of pamc_status() is -PAM_BPC_FALSE. - -If the return status of pamc_status() is PAM_BPC_TRUE and *prompt_p is -non-NULL, then an agent is requesting access to a server module. - -XXX - how this information gets propagated to the server, and - ultimately to the server's module is yet to be determined. - -#$$$$ Termination of agents - -When closing the authentication session and severing the connection -between a client and a selection of agents, the following function is -used: - - int pamc_end(pamc_handle_t *pch); - -Following a call to pamc_end, the pamc_handle_t will be invalid. - -The return value for this function is one of the following: - - PAM_BPC_TRUE - all invoked agents are content with - authentication (the server is _not_ judged - _un_trustworthy by any agent) - - PAM_BPC_FALSE - one or more agents were unsatisfied at - being terminated. In general, the client - should terminate its connection to the - server and indicate to the applicant that - the server is untrusted. - -#$$$ libpamc <-> agents - -The agents are manipulated from within libpamc. Each agent is an -executable in its own right. This permits the agent to have access to -sensitive data not accessible directly from the client. The mode of -communication between libpamc and an agent is through a pair of -pipes. The agent reads binary prompts (section #{binary_prompt}) -through its standard input file descriptor and writes response (to the -server) binary prompts and instruction binary prompts (instructions -for the client) through its standard output file descriptor. - -#$$ Client <-> server - -This interface is concerned with the exchange of text and binary -prompts between the client application and the server application. No -API is provided for this as it is considered specific to the transport -protocol shared by the client and the server. - -#$$ Server <-> modules - -The server makes use of a general API for communicating with -modules. The client is not required to communicate directly with -available modules. By abstracting the authentication interface, it -becomes possible for the local administrator to make a run time -decision about the authentication method adopted by the server. - -#$$$ Functions and definitions available to servers and modules - -[This section will document the following functions - - pam_set_item() - pam_get_item() - pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec) - pam_get_env(pam_handle_t *pamh, const char *varname) - pam_strerror(pam_handle_t *pamh, int pam_errno) - -Event driven support (XXX work in progress) - - pam_register_event() - app or module associates an event poller/handler - pam_select_event() - query for any outstanding event and act on any -] - -#$$$ Server <-> libpam - -[This section will document the following pam_ calls: - - pam_start - pam_end - pam_authenticate (*) - pam_setcred - pam_acct_mgmt - pam_open_session - pam_close_session - pam_chauthtok (*) - -The asterisked functions may return PAM_INCOMPLETE. In such cases, the -application should be aware that the conversation function was called -and that it returned PAM_CONV_AGAIN to a module. The correct action -for the application to take in response to receiving PAM_INCOMPLETE, -is to acquire the replies so that the next time the conversation -function is called it will be able to provide the desired -responses. And then recall pam_authenticate (pam_chauthtok) with the -same arguments. Libpam will arrange that the module stack is resumed -from the module that returned before. This functionality is required -for programs whose user interface is maintained by an event loop. ] - -#$$$ libpam <-> modules - -[This section will document the following pam_ and pam_sm_ calls: - -functions provided by libpam - - pam_set_data - pam_get_data - -functions provided to libpam by each module - - groups: - AUTHENTICATION - pam_sm_authenticate - pam_sm_setcred - ACCOUNT - pam_sm_acct_mgmt - SESSION - pam_sm_open_session - pam_sm_close_session - AUTHENTICATION TOKEN MANAGEMENT - pam_sm_chauthtok -] - -#$$$ The conversation function - -The server application, as part of its initialization of libpam, -provides a conversation function for use by modules and libpam. The -purpose of the conversation function is to enable direct communication -to the applicant ultimately via the client and selected agents. - -[ this section will contain a definition for the conversation - function, the conversation structure (appdata etc), and legitimate - return codes for the application supplied function. - - PAM_SUCCESS - ok conversation completed - PAM_CONV_ERR - conversation failed - PAM_CONV_AGAIN - application needs control to complete conv - PAM_CONV_RECONSIDER - application believes module should check if - it still needs to converse for this info - ] - -#$ Security considerations - -This document is devoted to standardizing authentication -infrastructure: everything in this document has implications for -security. - -#$ Contact - -The email list for discussing issues related to this document is -<pam-list@redhat.com>. - -#$ References - -[#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication - Modules (PAM)", October 1995 - -[#{PAM_STD_AGENTIDS}] Definitions for standard agents, "REGISTERED - AGENTS AND THEIR AGENT-ID'S", to be found here: - -## http://www.kernel.org/pub/linux/libs/pam/pre/doc/std-agent-ids.txt ## - -#$ Author's Address - -Andrew G. Morgan -Email: morgan@kernel.org - -## $Id$ ## diff --git a/doc/specs/formatter/.cvsignore b/doc/specs/formatter/.cvsignore deleted file mode 100644 index 8af8c897..00000000 --- a/doc/specs/formatter/.cvsignore +++ /dev/null @@ -1,3 +0,0 @@ -lex.yy.c -parse.tab.c -padout diff --git a/doc/specs/formatter/Makefile b/doc/specs/formatter/Makefile deleted file mode 100644 index d73258d7..00000000 --- a/doc/specs/formatter/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -LIBS=-lfl - -padout: parse.tab.o - $(CC) -o padout parse.tab.o $(LIBS) - -parse.tab.o: parse.tab.c lex.yy.c - $(CC) -c parse.tab.c - -parse.tab.c: parse.y - bison parse.y - -lex.yy.c: parse.lex - flex parse.lex - -clean: - rm -f parse.tab.o parse.tab.c lex.yy.c padout *~ core diff --git a/doc/specs/formatter/parse.lex b/doc/specs/formatter/parse.lex deleted file mode 100644 index 1d5c898e..00000000 --- a/doc/specs/formatter/parse.lex +++ /dev/null @@ -1,11 +0,0 @@ -%% - -\#[\$]+[a-zA-Z]*(\=[0-9]+)? return NEW_COUNTER; -\#\{[a-zA-Z][a-zA-Z0-9\_]*\} return LABEL; -\# return NO_INDENT; -\#\# return RIGHT; -\\\# return HASH; -[^\n] return CHAR; -[\n] return NEWLINE; - -%% diff --git a/doc/specs/formatter/parse.y b/doc/specs/formatter/parse.y deleted file mode 100644 index 6da47d17..00000000 --- a/doc/specs/formatter/parse.y +++ /dev/null @@ -1,293 +0,0 @@ - -%{ -#include <stdio.h> -#include <stdlib.h> -#include <string.h> - -#define MAXLINE 1000 -#define INDENT_STRING " " -#define PAPER_WIDTH 74 - - int indent=0; - int line=1; - char *last_label=NULL; - - extern void yyerror(const char *x); - extern char *get_label(const char *label); - extern void set_label(const char *label, const char *target); - char *new_counter(const char *key); - -#include "lex.yy.c" - -%} - -%union { - int def; - char *string; -} - -%token NEW_COUNTER LABEL HASH CHAR NEWLINE NO_INDENT RIGHT -%type <string> stuff text - -%start doc - -%% - -doc: -| doc NEWLINE { - printf("\n"); - ++line; -} -| doc stuff NEWLINE { - if (strlen($2) > (PAPER_WIDTH-(indent ? strlen(INDENT_STRING):0))) { - yyerror("line too long"); - } - printf("%s%s\n", indent ? INDENT_STRING:"", $2); - free($2); - indent = 1; - ++line; -} -| doc stuff RIGHT stuff NEWLINE { - char fixed[PAPER_WIDTH+1]; - int len; - - len = PAPER_WIDTH-(strlen($2)+strlen($4)); - - if (len >= 0) { - memset(fixed, ' ', len); - fixed[len] = '\0'; - } else { - yyerror("line too wide"); - fixed[0] = '\0'; - } - printf("%s%s%s\n", $2, fixed, $4); - free($2); - free($4); - indent = 1; - ++line; -} -| doc stuff RIGHT stuff RIGHT stuff NEWLINE { - char fixed[PAPER_WIDTH+1]; - int len, l; - - len = PAPER_WIDTH-(strlen($2)+strlen($4)); - - if (len < 0) { - len = 0; - yyerror("line too wide"); - } - - l = len/2; - memset(fixed, ' ', l); - fixed[l] = '\0'; - printf("%s%s%s", $2, fixed, $4); - free($2); - free($4); - - l = (len+1)/2; - memset(fixed, ' ', l); - fixed[l] = '\0'; - printf("%s%s\n", fixed, $6); - free($6); - - indent = 1; - ++line; -} -| doc stuff RIGHT stuff RIGHT stuff NEWLINE { - char fixed[PAPER_WIDTH+1]; - int len, l; - - len = PAPER_WIDTH-(strlen($2)+strlen($4)); - - if (len < 0) { - len = 0; - yyerror("line too wide"); - } - - l = len/2; - memset(fixed, ' ', l); - fixed[l] = '\0'; - printf("%s%s%s", $2, fixed, $4); - free($2); - free($4); - - l = (len+1)/2; - memset(fixed, ' ', l); - fixed[l] = '\0'; - printf("%s%s\n", fixed, $6); - free($6); - - indent = 1; - ++line; -} -; - -stuff: { - $$ = strdup(""); -} -| stuff text { - $$ = malloc(strlen($1)+strlen($2)+1); - sprintf($$,"%s%s", $1, $2); - free($1); - free($2); -} -; - -text: CHAR { - $$ = strdup(yytext); -} -| text CHAR { - $$ = malloc(strlen($1)+2); - sprintf($$,"%s%s", $1, yytext); - free($1); -} -| NO_INDENT { - $$ = strdup(""); - indent = 0; -} -| HASH { - $$ = strdup("#"); -} -| LABEL { - if (($$ = get_label(yytext)) == NULL) { - set_label(yytext, last_label); - $$ = strdup(""); - } -} -| NEW_COUNTER { - $$ = new_counter(yytext); -} -; - -%% - -typedef struct node_s { - struct node_s *left, *right; - const char *key; - char *value; -} *node_t; - -node_t label_root = NULL; -node_t counter_root = NULL; - -const char *find_key(node_t root, const char *key) -{ - while (root) { - int cmp = strcmp(key, root->key); - - if (cmp > 0) { - root = root->right; - } else if (cmp) { - root = root->left; - } else { - return root->value; - } - } - return NULL; -} - -node_t set_key(node_t root, const char *key, const char *value) -{ - if (root) { - int cmp = strcmp(key, root->key); - if (cmp > 0) { - root->right = set_key(root->right, key, value); - } else if (cmp) { - root->left = set_key(root->left, key, value); - } else { - free(root->value); - root->value = strdup(value); - } - } else { - root = malloc(sizeof(struct node_s)); - root->right = root->left = NULL; - root->key = strdup(key); - root->value = strdup(value); - } - return root; -} - -void yyerror(const char *x) -{ - fprintf(stderr, "line %d: %s\n", line, x); -} - -char *get_label(const char *label) -{ - const char *found = find_key(label_root, label); - - if (found) { - return strdup(found); - } - return NULL; -} - -void set_label(const char *label, const char *target) -{ - if (target == NULL) { - yyerror("no hanging value for label"); - target = "<??>"; - } - label_root = set_key(label_root, label, target); -} - -char *new_counter(const char *key) -{ - int i=0, j, ndollars = 0; - const char *old; - char *new; - - if (key[i++] != '#') { - yyerror("bad index"); - return strdup("<???>"); - } - - while (key[i] == '$') { - ++ndollars; - ++i; - } - - key += i; - old = find_key(counter_root, key); - new = malloc(20*ndollars); - - if (old) { - for (j=0; ndollars > 1 && old[j]; ) { - if (old[j++] == '.' && --ndollars <= 0) { - break; - } - } - if (j) { - strncpy(new, old, j); - } - if (old[j]) { - i = atoi(old+j); - } else { - new[j++] = '.'; - i = 0; - } - } else { - j=0; - while (--ndollars > 0) { - new[j++] = '0'; - new[j++] = '.'; - } - i = 0; - } - new[j] = '\0'; - sprintf(new+j, "%d", ++i); - - counter_root = set_key(counter_root, key, new); - - if (last_label) { - free(last_label); - } - last_label = strdup(new); - - return new; -} - -main() -{ - yyparse(); -} diff --git a/doc/specs/rfc86.0.txt b/doc/specs/rfc86.0.txt deleted file mode 100644 index 6dd5e6ea..00000000 --- a/doc/specs/rfc86.0.txt +++ /dev/null @@ -1,1851 +0,0 @@ - - - - - - - - - Open Software Foundation V. Samar (SunSoft) - Request For Comments: 86.0 R. Schemers (SunSoft) - October 1995 - - - - UNIFIED LOGIN WITH - PLUGGABLE AUTHENTICATION MODULES (PAM) - - - 1. INTRODUCTION - - Since low-level authentication mechanisms constantly evolve, it is - important to shield the high-level consumers of these mechanisms - (system-entry services and users) from such low-level changes. With - the Pluggable Authentication Module (PAM) framework, we can provide - pluggability for a variety of system-entry services -- not just - system authentication _per se_, but also for account, session and - password management. PAM's ability to _stack_ authentication modules - can be used to integrate `login' with different authentication - mechanisms such as RSA, DCE, and Kerberos, and thus unify login - mechanisms. The PAM framework can also provide easy integration of - smart cards into the system. - - Modular design and pluggability have become important for users who - want ease of use. In the PC hardware arena, no one wants to set the - interrupt vector numbers or resolve the addressing conflict between - various devices. In the software arena, people also want to be able - to replace components easily for easy customization, maintenance, and - upgrades. - - Authentication software deserves special attention because - authentication forms a very critical component of any secure computer - system. The authentication infrastructure and its components may - have to be modified or replaced either because some deficiencies have - been found in the current algorithms, or because sites want to - enforce a different security policy than what was provided by the - system vendor. The replacement and modification should be done in - such a way that the user is not affected by these changes. - - The solution has to address not just how the applications use the new - authentication mechanisms in a generic fashion, but also how the user - will be authenticated to these mechanisms in a generic way. The - former is addressed by GSS-API [Linn 93], while this RFC addresses - the later; these two efforts are complementary to each other. - - Since most system-entry services (for example, `login', `dtlogin', - `rlogin', `ftp', `rsh') may want to be independent of the specific - authentication mechanisms used by the machine, it is important that - there be a framework for _plugging_ in various mechanisms. This - requires that the system applications use a standard API to interact - - - - Samar, Schemers Page 1 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - with the authentication services. If these system-entry services - remain independent of the actual mechanism used on that machine, the - system administrator can install suitable authentication modules - without requiring changes to these applications. - - For any security system to be successful, it has to be easy to use. - In the case of authentication, the single most important ease-of-use - characteristic is that the user should not be required to learn about - various ways of authentication and remember multiple passwords. - Ideally, there should be one all-encompassing authentication system - where there is only one password, but for heterogeneous sites, - multiple authentication mechanisms have to co-exist. The problem of - integrating multiple authentication mechanisms such as Kerberos - [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor - 88], is also referred to as _integrated login_, or _unified login_ - problem. Even if the user has to use multiple authentication - mechanisms, the user should not be forced to type multiple passwords. - Furthermore, the user should be able to use the new network identity - without taking any further actions. The key here is in modular - integration of the network authentication technologies with `login' - and other system-entry services. - - In this RFC we discuss the architecture and design of pluggable - authentication modules. This design gives the capability to use - field-replaceable authentication modules along with unified login - capability. It thus provides for both _pluggability_ and _ease-of- - use_. - - The RFC is organized as follows. We first motivate the need for a - generic way to authenticate the user by various system-entry services - within the operating system. We describe the goals and constraints - of the design. This leads to the architecture, description of the - interfaces, and _stacking_ of modules to get unified login - functionality. We then describe our experience with the design, and - end with a description of future work. - - - 2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS - - An identification and authentication ("I&A") mechanism is used to - establish a user's identity the system (i.e., to a local machine's - operating system) and to other principals on the network. On a - typical UNIX system, there are various ports of entry into the - system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and - `telnet'. In all cases, the user has to be identified and - authenticated before granting appropriate access rights to the user. - The user identification and authentication for all these entry points - needs to be coordinated to ensure a secure system. - - In most of the current UNIX systems, the login mechanism is based - upon verification of the password using the modified DES algorithm. - - - - Samar, Schemers Page 2 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - The security of the implementation assumes that the password cannot - be guessed, and that the password does not go over the wire in the - clear. These assumptions, however, are not universally valid. - Various programs are now available freely on the Internet that can - run dictionary attack against the encrypted password. Further, some - of the network services (for example, `rlogin', `ftp', `telnet') send - the password over in clear, and there are "sniffer" programs freely - available to steal these passwords. The classical assumptions may be - acceptable on a trusted network, but in an open environment there is - a need to use more restrictive and stronger authentication - mechanisms. Examples of such mechanisms include Kerberos, RSA, - Diffie-Hellman, one-time password [Skey 94], and challenge-response - based smart card authentication systems. Since this list will - continue to evolve, it is important that the system-entry services do - not have hard-coded dependencies on any of these authentication - mechanisms. - - - 3. DESIGN GOALS - - The goals of the PAM framework are as follows: - - (a) The system administrator should be able to choose the default - authentication mechanism for the machine. This can range from - a simple password-based mechanism to a biometric or a smart - card based system. - - (b) It should be possible to configure the user authentication - mechanism on a per application basis. For example, a site may - require S/Key password authentication for `telnet' access, - while allowing machine `login' sessions with just UNIX password - authentication. - - (c) The framework should support the display requirements of the - applications. For example, for a graphical login session such - as `dtlogin', the user name and the password may have to be - entered in a new window. For networking system-entry - applications such as `ftp' and `telnet', the user name and - password has to be transmitted over the network to the client - machine. - - (d) It should be possible to configure multiple authentication - protocols for each of those applications. For example, one may - want the users to get authenticated by both Kerberos and RSA - authentication systems. - - (e) The system administrator should be able to _stack_ multiple - user authentication mechanisms such that the user is - authenticated with all authentication protocols without - retyping the password. - - - - - Samar, Schemers Page 3 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - (f) The architecture should allow for multiple passwords if - necessary to achieve higher security for users with specific - security requirements. - - (g) The system-entry services should not be required to change when - the underlying mechanism changes. This can be very useful for - third-party developers because they often do not have the - source code for these services. - - (h) The architecture should provide for a _pluggable_ model for - system authentication, as well as for other related tasks such - as password, account, and session management. - - (i) For backward-compatibility reasons, the PAM API should support - the authentication requirements of the current system-entry - services. - - There are certain issues that the PAM framework does not specifically - address: - - (a) We focus only on providing a generic scheme through which users - use passwords to establish their identities to the machine. - Once the identity is established, how the identity is - communicated to other interested parties is outside the scope - of this design. There are efforts underway at IETF [Linn 93] - to develop a Generic Security Services Application Interface - (GSSAPI) that can be used by applications for secure and - authenticated communication without knowing the underlying - mechanism. - - (b) The _single-signon_ problem of securely transferring the - identity of the caller to a remote site is not addressed. For - example, the problem of delegating credentials from the - `rlogin' client to the other machine without typing the - password is not addressed by our work. We also do not address - the problem of sending the passwords over the network in the - clear. - - (c) We do not address the source of information obtained from the - "`getXbyY()'" family of calls (e.g., `getpwnam()'). Different - operating systems address this problem differently. For - example, Solaris uses the name service switch (NSS) to - determine the source of information for the "`getXbyY()'" - calls. It is expected that data which is stored in multiple - sources (such as passwd entries in NIS+ and the DCE registry) - is kept in sync using the appropriate commands (such as - `passwd_export'). - - - - - - - - Samar, Schemers Page 4 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - 4. OVERVIEW OF THE PAM FRAMEWORK - - We propose that the goals listed above can be met through a framework - in which authentication modules can be _plugged_ independently of the - application. We call this the _Pluggable Authentication Modules_ - (PAM) framework. - - The core components of the PAM framework are the authentication - library API (the front end) and the authentication mechanism-specific - modules (the back end), connected through the Service Provider - Interface (SPI). Applications write to the PAM API, while the - authentication-system providers write to the PAM SPI and supply the - back end modules that are independent of the application. - - ftp telnet login (Applications) - | | | - | | | - +--------+--------+ - | - +-----+-----+ - | PAM API | <-- pam.conf file - +-----+-----+ - | - +--------+--------+ - UNIX Kerberos Smart Cards (Mechanisms) - - Figure 1: The Basic PAM Architecture - - Figure 1 illustrates the relationship between the application, the - PAM library, and the authentication modules. Three applications - (`login', `telnet' and `ftp') are shown which use the PAM - authentication interfaces. When an application makes a call to the - PAM API, it loads the appropriate authentication module as determined - by the configuration file, `pam.conf'. The request is forwarded to - the underlying authentication module (for example, UNIX password, - Kerberos, smart cards) to perform the specified operation. The PAM - layer then returns the response from the authentication module to the - application. - - PAM unifies system authentication and access control for the system, - and allows plugging of associated authentication modules through well - defined interfaces. The plugging can be defined through various - means, one of which uses a configuration file, such as the one in - Table 1. For each of the system applications, the file specifies the - authentication module that should be loaded. In the example below, - `login' uses the UNIX password module, while `ftp' and `telnet' use - the S/Key module. - - - - - - - - Samar, Schemers Page 5 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - Table 1: A Simplified View of a Sample PAM Configuration File. - - service module_path - ------- ----------- - login pam_unix.so - ftp pam_skey.so - telnet pam_skey.so - - Authentication configuration is only one aspect of this interface. - Other critical components include account management, session - management, and password management. For example, the `login' - program may want to verify not only the password but also whether the - account has aged or expired. Generic interfaces also need to be - provided so that the password can be changed according to the - requirements of the module. Furthermore, the application may want to - log information about the current session as determined by the - module. - - Not all applications or services may need all of the above - components, and not each authentication module may need to provide - support for all of the interfaces. For example, while `login' may - need access to all four components, `su' may need access to just the - authentication component. Some applications may use some specific - authentication and password management modules but share the account - and session management modules with others. - - This reasoning leads to a partitioning of the entire set of - interfaces into four areas of functionality: (1) authentication, (2) - account, (3) session, and (4) password. The concept of PAM was - extended to these functional areas by implementing each of them as a - separate pluggable module. - - Breaking the functionality into four modules helps the module - providers because they can use the system-provided libraries for the - modules that they are not changing. For example, if a supplier wants - to provide a better version of Kerberos, they can just provide that - new authentication and password module, and reuse the existing ones - for account and session. - - 4.1. Module Description - - More details on specific API's are described in Appendix A. A brief - description of four modules follows: - - (a) Authentication management: This set includes the - `pam_authenticate()' function to authenticate the user, and the - `pam_setcred()' interface to set, refresh or destroy the user - credentials. - - (b) Account management: This set includes the `pam_acct_mgmt()' - function to check whether the authenticated user should be - - - - Samar, Schemers Page 6 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - given access to his/her account. This function can implement - account expiration and access hour restrictions. - - (c) Session management: This set includes the `pam_open_session()' - and `pam_close_session()' functions for session management and - accounting. For example, the system may want to store the - total time for the session. - - (d) Password management: This set includes a function, - `pam_chauthtok()', to change the password. - - - 5. FRAMEWORK INTERFACES - - The PAM framework further provides a set of administrative interfaces - to support the above modules and to provide for application-module - communication. There is no corresponding service provider interface - (SPI) for such functions. - - 5.1. Administrative Interfaces - - Each set of PAM transactions starts with `pam_start()' and ends with - the `pam_end()' function. The interfaces `pam_get_item()' and - `pam_set_item()' are used to read and write the state information - associated with the PAM transaction. - - If there is any error with any of the PAM interfaces, the error - message can be printed with `pam_strerror()'. - - 5.2. Application-Module Communication - - During application initialization, certain data such as the user name - is saved in the PAM framework layer through `pam_start()' so that it - can be used by the underlying modules. The application can also pass - opaque data to the module which the modules will pass back while - communicating with the user. - - 5.3. User-Module Communication - - The `pam_start()' function also passes conversation function that has - to be used by the underlying modules to read and write module - specific authentication information. For example, these functions - can be used to prompt the user for the password in a way determined - by the application. PAM can thus be used by graphical, non- - graphical, or networked applications. - - - - - - - - - - Samar, Schemers Page 7 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - 5.4. Inter-Module Communication - - Though the modules are independent, they can share certain common - information about the authentication session such as user name, - service name, password, and conversation function through the - `pam_get_item()' and `pam_set_item()' interfaces. These API's can - also be used by the application to change the state information after - having called `pam_start()' once. - - 5.5. Module State Information - - The PAM service modules may want to keep certain module-specific - state information about the session. The interfaces `pam_get_data()' - and `pam_set_data()' can be used by the service modules to access and - update module-specific information as needed from the PAM handle. - The modules can also attach a cleanup function with the data. The - cleanup function is executed when `pam_end()' is called to indicate - the end of the current authentication activity. - - Since the PAM modules are loaded upon demand, there is no direct - module initialization support in the PAM framework. If there are - certain initialization tasks that the PAM service modules have to do, - they should be done upon the first invocation. However, if there are - certain clean-up tasks to be done when the authentication session - ends, the modules should use `pam_set_data()' to specify the clean-up - functions, which would be called when `pam_end()' is called by the - application. - - - 6. MODULE CONFIGURATION MANAGEMENT - - Table 2 shows an example of a configuration file `pam.conf' with - support for authentication, session, account, and password management - modules. `login' has three entries: one each for authentication - processing, session management and account management. Each entry - specifies the module name that should be loaded for the given module - type. In this example, the `ftp' service uses the authentication and - session modules. Note that all services here share the same session - management module, while having different authentication modules. - - - - - - - - - - - - - - - - Samar, Schemers Page 8 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - Table 2: Configuration File (pam.conf) with Different Modules - and Control Flow - - service module_type control_flag module_path options - ------- ----------- ------------ ----------- ------- - login auth required pam_unix_auth.so nowarn - login session required pam_unix_session.so - login account required pam_unix_account.so - ftp auth required pam_skey_auth.so debug - ftp session required pam_unix_session.so - telnet session required pam_unix_session.so - login password required pam_unix_passwd.so - passwd password required pam_unix_passwd.so - OTHER auth required pam_unix_auth.so - OTHER session required pam_unix_session.so - OTHER account required pam_unix_account.so - - The first field, _service_, denotes the service (for example, - `login', `passwd', `rlogin'). The name `OTHER' indicates the module - used by all other applications that have not been specified in this - file. This name can also be used if all services have the same - requirements. In the example, since all the services use the same - session module, we could have replaced those lines with a single - `OTHER' line. - - The second field, _module_type_, indicates the type of the PAM - functional module. It can be one of `auth', `account', `session', or - `password' modules. - - The third field, _control_flag_ determines the behavior of stacking - multiple modules by specifying whether any particular module is - _required_, _sufficient_, or _optional_. The next section describes - stacking in more detail. - - The fourth field, _module_path_, specifies the location of the - module. The PAM framework loads this module upon demand to invoke - the required function. - - The fifth field, _options_, is used by the PAM framework layer to - pass module specific options to the modules. It is up to the module - to parse and interpret the options. This field can be used by the - modules to turn on debugging or to pass any module specific - parameters such as a timeout value. It is also used to support - unified login as described below. The options field can be used by - the system administrator to fine-tune the PAM modules. - - If any of the fields are invalid, or if a module is not found, that - line is ignored and the error is logged as a critical error via - `syslog(3)'. If no entries are found for the given module type, then - the PAM framework returns an error to the application. - - - - - Samar, Schemers Page 9 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - 7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING - - In the world of heterogeneous systems, the system administrator often - has to deal with the problem of integrating multiple authentication - mechanisms. The user is often required to know about the - authentication command of the new authentication module (for example, - `kinit', `dce_login') after logging into the system. This is not - user-friendly because it forces people to remember to type the new - command and enter the new password. This functionality should be - invisible instead of burdening the user with it. - - There are two problems to be addressed here: - - (a) Supporting multiple authentication mechanisms. - - (b) Providing unified login in the presence of multiple mechanisms. - - In the previous section, we described how one could replace the - default authentication module with any other module of choice. Now - we demonstrate how the same model can be extended to provide support - for multiple modules. - - 7.1. Design for Stacked Modules - - One possibility was to provide hard-coded rules in `login' or other - applications requiring authentication services [Adamson 95]. But - this becomes very specific to the particular combination of - authentication protocols, and also requires the source code of the - application. Digital's Security Integration Architecture [SIA 95] - addresses this problem by specifying the same list of authentication - modules for all applications. Since requirements for various - applications can vary, it is essential that the configuration be on a - per-application basis. - - To support multiple authentication mechanisms, the PAM framework was - extended to support _stacking_. When any API is called, the back - ends for the stacked modules are invoked in the order listed, and the - result returned to the caller. In Figure 2, the authentication - service of `login' is stacked and the user is authenticated by UNIX, - Kerberos, and RSA authentication mechanisms. Note that in this - example, there is no stacking for session or account management - modules. - - - - - - - - - - - - - Samar, Schemers Page 10 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - login - | - +--------+--------+ - | | | - session auth account - | | | - +--+--+ +--+--+ +--+--+ - | PAM | | PAM | | PAM | - +--+--+ +--+--+ +--+--+ - | | | - UNIX UNIX UNIX - session auth account - | - Kerberos - auth - | - RSA - auth - - Figure 2: Stacking With the PAM Architecture - - Stacking is specified through additional entries in the configuration - file shown earlier. As shown in Table 2, for each application (such - as `login') the configuration file can specify multiple mechanisms - that have to be invoked in the specified order. When mechanisms - fail, the _control_flag_ decides which error should be returned to - the application. Since the user should not know which authentication - module failed when a bad password was typed, the PAM framework - continues to call other authentication modules on the stack even on - failure. The semantics of the control flag are as follows: - - (a) `required': With this flag, the module failure results in the - PAM framework returning the error to the caller _after_ - executing all other modules on the stack. For the function to - be able to return success to the application all `required' - modules have to report success. This flag is normally set when - authentication by this module is a _must_. - - (b) `optional': With this flag, the PAM framework ignores the - module failure and continues with the processing of the next - module in sequence. This flag is used when the user is allowed - to login even if that particular module has failed. - - (c) `sufficient': With this flag, if the module succeeds the PAM - framework returns success to the application immediately - without trying any other modules. For failure cases, the - _sufficient_ modules are treated as `optional'. - - Table 3 shows a sample configuration file that stacks the `login' - command. Here the user is authenticated by UNIX, Kerberos, and RSA - authentication services. The `required' key word for _control_flag_ - - - - Samar, Schemers Page 11 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - enforces that the user is allowed to login only if he/she is - authenticated by _both_ UNIX and Kerberos services. RSA - authentication is optional by virtue of the `optional' key word in - the _control_flag_ field. The user can still log in even if RSA - authentication fails. - - Table 3: PAM Configuration File with Support for Stacking - - service module_type control_flag module_path options - ------- ----------- ------------ ----------- ------- - login auth required pam_unix.so debug - login auth required pam_kerb.so use_mapped_pass - login auth optional pam_rsa.so use_first_pass - - Table 4 illustrates the use of the sufficient flag for the `rlogin' - service. The Berkeley `rlogin' protocol specifies that if the remote - host is trusted (as specified in the `/etc/hosts.equiv' file or in - the `.rhosts' file in the home directory of the user), then the - `rlogin' daemon should not require the user to type the password. If - this is not the case, then the user is required to type the password. - Instead of hard coding this policy in the `rlogin' daemon, this can - be expressed with the `pam.conf' file in Table 4. The PAM module - `pam_rhosts_auth.so.1' implements the `.rhosts' policy described - above. If a site administrator wants to enable remote login with - only passwords, then the first line should be deleted. - - Table 4: PAM Configuration File for the rlogin service - - service module_type control_flag module_path options - ------- ----------- ------------ ----------- ------- - rlogin auth sufficient pam_rhosts_auth.so - rlogin auth required pam_unix.so - - 7.2. Password-Mapping - - Multiple authentication mechanisms on a machine can lead to multiple - passwords that users have to remember. One attractive solution from - the ease-of-use viewpoint is to use the same password for all - mechanisms. This, however, can also weaken the security because if - that password were to be compromised in any of the multiple - mechanisms, all mechanisms would be compromised at the same time. - Furthermore, different authentication mechanisms may have their own - distinctive password requirements in regards to its length, allowed - characters, time interval between updates, aging, locking, and so - forth. These requirements make it problematic to use the same - password for multiple authentication mechanisms. - - The solution we propose, while not precluding use of the same - password for every mechanism, allows for a different password for - each mechanism through what we call _password-mapping_. This - basically means using the user's _primary_ password to encrypt the - - - - Samar, Schemers Page 12 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - user's other (_secondary_) passwords, and storing these encrypted - passwords in a place where they are available to the user. Once the - primary password is verified, the authentication modules would obtain - the other passwords for their own mechanisms by decrypting the - mechanism-specific encrypted password with the primary password, and - passing it to the authentication service. The security of this - design for password-mapping assumes that the primary password is the - user's strongest password, in terms of its unguessability (length, - type and mix of characters used, etc.). - - If there is any error in password-mapping, or if the mapping does not - exist, the user will be prompted for the password by each - authentication module. - - To support password-mapping, the PAM framework saves the primary - password and provides it to stacked authentication modules. The - password is cleared out before the `pam_authenticate' function - returns. - - How the password is encrypted depends completely on the module - implementation. The encrypted secondary password (also called a - "mapped password") can be stored in a trusted or untrusted place, - such as a smart card, a local file, or a directory service. If the - encrypted passwords are stored in an untrusted publicly accessible - place, this does provide an intruder with opportunities for potential - dictionary attack. - - Though password-mapping is voluntary, it is recommended that all - module providers add support for the following four mapping options: - - (a) `use_first_pass': Use the same password used by the first - mechanism that asked for a password. The module should not ask - for the password if the user cannot be authenticated by the - first password. This option is normally used when the system - administrator wants to enforce the same password across - multiple modules. - - (b) `try_first_pass': This is the same as `use_first_pass', except - that if the primary password is not valid, it should prompt the - user for the password. - - (c) `use_mapped_pass': Use the password-mapping scheme to get the - actual password for this module. One possible implementation - is to get the mapped-password using the XFN API [XFN 94], and - decrypt it with the primary password to get the module-specific - password. The module should not ask for the password if the - user cannot be authenticated by the first password. The XFN - API allows user-defined attributes (such as _mapped-password_) - to be stored in the _user-context_. Using the XFN API is - particularly attractive because support for the XFN may be - found on many systems in the future. - - - - Samar, Schemers Page 13 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - (d) `try_mapped_pass': This is the same as `use_mapped_pass', - except that if the primary password is not valid, it should - prompt the user for the password. - - When passwords get updated, the PAM framework stores both the old as - well as the new password to be able to inform other dependent - authentication modules about the change. Other modules can use this - information to update the encrypted password without forcing the user - to type the sequence of passwords again. The PAM framework clears - out the passwords before returning to the application. - - Table 3 illustrates how the same password can be used by `login' for - authenticating to the standard UNIX login, Kerberos and RSA services. - Once the user has been authenticated to the primary authentication - service (UNIX `login' in this example) with the primary password, the - option `use_mapped_pass' indicates to the Kerberos module that it - should use the primary password to decrypt the stored Kerberos - password and then use the Kerberos password to get the ticket for the - ticket-granting-service. After that succeeds, the option - `use_first_pass' indicates to the RSA module that instead of - prompting the user for a password, it should use the primary password - typed earlier for authenticating the user. Note that in this - scenario, the user has to enter the password just once. - - Note that if a one-time password scheme (e.g., S/Key) is used, - password mapping cannot apply. - - 7.3. Implications of Stacking on the PAM Design - - Because of the stacking capability of PAM, we have designed the PAM - API's to not return any data to the application, except status. If - this were not the case, it would be difficult for the PAM framework - to decide which module should return data to the application. When - there is any error, the application does not know which of the - modules failed. This behavior enables (even requires) the - application to be completely independent from the modules. - - Another design decision we have made is that PAM gives only the user - name to all the underlying PAM modules, hence it is the - responsibility of the PAM modules to convert the name to their own - internal format. For example, the Kerberos module may have to - convert the UNIX user name to a Kerberos principal name. - - Stacking also forces the modules to be designed such that they can - occur anywhere in the stack without any side-effects. - - Since modules such as the authentication and the password module are - very closely related, it is important they be configured in the same - order and with compatible options. - - - - - - Samar, Schemers Page 14 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - 8. INTEGRATION WITH SMART CARDS - - Many networking authentication protocols require possession of a long - key to establish the user identity. For ease-of-use reasons, that - long key is normally encrypted with the user's password so that the - user is not required to memorize it. However, weak passwords can be - compromised through a dictionary attack and thus undermine the - stronger network authentication mechanism. Furthermore, the - encrypted data is normally stored in a centrally accessible service - whose availability depends upon the reliability of the associated - service. Solutions have been proposed to use a pass-phrase or one- - time-password, but those are much longer than the regular eight - character passwords traditionally used with UNIX `login'. This makes - the solution user-unfriendly because it requires longer strings to be - remembered and typed. - - For most authentication protocol implementations, the trust boundary - is the local machine. This assumption may not be valid in cases - where the user is mobile and has to use publicly available networked - computers. In such cases, it is required that the clear text of the - key or the password never be made available to the machine. - - Smart cards solve the above problems by reducing password exposure by - supporting a _two factor_ authentication mechanism: the first with - the possession of the card, and the second with the knowledge of the - PIN associated with the card. Not only can the smart cards be a - secure repository of multiple passwords, they can also provide the - encryption and authentication functions such that the long (private) - key is never exposed outside the card. - - The PAM framework allows for integrating smart cards to the system by - providing a smart card specific module for authentication. - Furthermore, the unified login problem is simplified because the - multiple passwords for various authentication mechanisms can be - stored on the smart card itself. This can be enabled by adding a - suitable key-word such as `use_smart_card' in the _options_ field. - - - 9. SECURITY ISSUES - - It is important to understand the impact of PAM on the security of - any system so that the site-administrator can make an informed - decision. - - (a) Sharing of passwords with multiple authentication mechanisms. - - If there are multiple authentication modules, one possibility - is to use the same password for all of them. If the password - for any of the multiple authentication system is compromised, - the user's password in all systems would be compromised. If - this is a concern, then multiple passwords might be considered - - - - Samar, Schemers Page 15 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - at the cost of ease-of-use. - - (b) Password-mapping. - - This technique of encrypting all other passwords with the - primary password assumes that it is lot more difficult to crack - the primary password and that reasonable steps have been taken - to ensure limited availability of the encrypted primary - password. If this is not done, an intruder could target the - primary password as the first point of dictionary attack. If - one of the other modules provide stronger security than the - password based security, the site would be negating the strong - security by using password-mapping. If this is a concern, then - multiple passwords might be considered at the cost of ease-of- - use. If smart cards are used, they obviate the need for - password-mapping completely. - - (c) Security of the configuration file. - - Since the policy file dictates how the user is authenticated, - this file should be protected from unauthorized modifications. - - (d) Stacking various PAM modules. - - The system administrator should fully understand the - implications of stacking various modules that will be installed - on the system and their respective orders and interactions. - The composition of various authentication modules should be - carefully examined. The trusted computing base of the machine - now includes the PAM modules. - - - 10. EXPERIENCE WITH PAM - - The PAM framework was first added in Solaris 2.3 release as a private - internal interface. PAM is currently being used by several system - entry applications such as `login', `passwd', `su', `dtlogin', - `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init', - `sac', and `ttymon'. We have found that PAM provides an excellent - framework to encapsulate the authentication-related tasks for the - entire system. The Solaris 2.3 PAM API's were hence enhanced and - simplified to support stacking. - - PAM modules have been developed for UNIX, DCE, Kerberos, S/Key, - remote user authentication, and dialpass authentication. Other PAM - modules are under development, and integration with smart cards is - being planned. - - Some third parties have used the PAM interface to extend the security - mechanisms offered by the Solaris environment. - - - - - Samar, Schemers Page 16 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - The PAM API has been accepted by Common Desktop Environment (CDE) - vendors as the API to be used for integrating the graphical interface - for login, `dtlogin' with multiple authentication mechanisms. - - - 11. FUTURE WORK - - Amongst the various components of PAM, the password component needs - to be carefully examined to see whether the stacking semantics are - particularly applicable, and how PAM should deal with partial - failures when changing passwords. - - The _control_flag_ of the configuration file can be extended to - include other semantics. For example, if the error is "name service - not available", one may want to retry. It is also possible to offer - semantics of "return success if any of the modules return success". - - In an earlier section, we had mentioned integration of smart cards - with PAM. Though we feel that integration should be straight forward - from the PAM architecture point of view, there may be some issues - with implementation because the interfaces to the smart cards have - not yet been standardized. - - One possible extension to PAM is to allow the passing of module- - specific data between applications and PAM modules. For example, the - `login' program likes to build its new environment from a select list - of variables, yet the DCE module needs the `KRB5CCNAME' variable to - be exported to the child process. For now we have modified the - `login' program to explicitly export the `KRB5CCNAME' variable. - - Administrative tools are needed to help system administrators modify - `pam.conf', and perform sanity checks on it (i.e., a `pam_check' - utility). - - - 12. CONCLUSION - - The PAM framework and the module interfaces provide pluggability for - user authentication, as well as for account, session and password - management. The PAM architecture can be used by `login' and by all - other system-entry services, and thus ensure that all entry points - for the system have been secured. This architecture enables - replacement and modification of authentication modules in the field - to secure the system against the newly found weaknesses without - changing any of the system services. - - The PAM framework can be used to integrate `login' and `dtlogin' with - different authentication mechanisms such as RSA and Kerberos. - Multiple authentication systems can be accessed with the same - password. The PAM framework also provides easy integration of smart - cards into the system. - - - - Samar, Schemers Page 17 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - PAM provides complementary functionality to GSS-API, in that it - provides mechanisms through which the user gets authenticated to any - new system-level authentication service on the machine. GSS-API then - uses the credentials for authenticated and secure communications with - other application-level service entities on the network. - - - 13. ACKNOWLEDGEMENTS - - PAM development has spanned several release cycles at SunSoft. - Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and - implementation. Bill Shannon and Don Stephenson helped with the PAM - architecture. Rocky Wu prototyped stacking of multiple modules. - Paul Fronberg, Charlie Lai, and Roland Schemers made very significant - enhancements to the PAM interfaces and took the project to completion - within a very short time. Kathy Slattery wrote the PAM - documentation. John Perry integrated PAM within the CDE framework. - - - APPENDIX A. PAM API'S - - This appendix gives an informal description of the various interfaces - of PAM. Since the goal here is just for the reader to get a working - knowledge about the PAM interfaces, not all flags and options have - been fully defined and explained. The API's described here are - subject to change. - - The PAM Service Provider Interface is very similar to the PAM API, - except for one extra parameter to pass module-specific options to the - underlying modules. - - A.1. Framework Layer API's - - int - pam_start( - char *service_name, - char *user, - struct pam_conv *pam_conversation, - pam_handle_t **pamh - ); - - `pam_start()' is called to initiate an authentication transaction. - `pam_start()' takes as arguments the name of the service, the name of - the user to be authenticated, the address of the conversation - structure. `pamh' is later used as a handle for subsequent calls to - the PAM library. - - The PAM modules do not communicate directly with the user; instead - they rely on the application to perform all such interaction. The - application needs to provide the conversation functions, `conv()', - and associated application data pointers through a `pam_conv' - - - - Samar, Schemers Page 18 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - structure when it initiates an authentication transaction. The - module uses the `conv()' function to prompt the user for data, - display error messages, or text information. - - int - pam_end( - pam_handle_t *pamh, - int pam_status - ); - - `pam_end()' is called to terminate the PAM transaction as specified - by `pamh', and to free any storage area allocated by the PAM modules - with `pam_set_item()'. - - int - pam_set_item( - pam_handle_t *pamh, - int item_type, - void *item - ); - - int - pam_get_item( - pam_handle_t *pamh, - int item_type, - void **item); - - `pam_get_item()' and `pam_set_item()' allow the parameters specified - in the initial call to `pam_start()' to be read and updated. This is - useful when a particular parameter is not available when - `pam_start()' is called or must be modified after the initial call to - `pam_start()'. `pam_set_item()' is passed a pointer to the object, - `item', and its type, `item_type'. `pam_get_item()' is passed the - address of the pointer, `item', which is assigned the address of the - requested object. - - The `item_type' is one of the following: - - Table 5: Possible Values for Item_type - - Item Name Description - --------- ----------- - PAM_SERVICE The service name - PAM_USER The user name - PAM_TTY The tty name - PAM_RHOST The remote host name - PAM_CONV The pam_conv structure - PAM_AUTHTOK The authentication token (password) - PAM_OLDAUTHTOK The old authentication token - PAM_RUSER The remote user name - - - - - Samar, Schemers Page 19 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only - available to PAM modules and not to the applications. They are - explicitly cleared out by the framework before returning to the - application. - - char * - pam_strerror( - int errnum - ); - - `pam_strerror()' maps the error number to a PAM error message string, - and returns a pointer to that string. - - int - pam_set_data( - pam_handle_t *pamh, - char *module_data_name, - char *data, - (*cleanup)(pam_handle_t *pamh, char *data, - int error_status) - ); - - The `pam_set_data()' function stores module specific data within the - PAM handle. The `module_data_name' uniquely specifies the name to - which some data and cleanup callback function can be attached. The - cleanup function is called when `pam_end()' is invoked. - - int - pam_get_data( - pam_handle_t *pamh, - char *module_data_name, - void **datap - ); - - The `pam_get_data()' function obtains module-specific data from the - PAM handle stored previously by the `pam_get_data()' function. The - `module_data_name' uniquely specifies the name for which data has to - be obtained. This function is normally used to retrieve module - specific state information. - - A.2. Authentication API's - - int - pam_authenticate( - pam_handle_t *pamh, - int flags - ); - - The `pam_authenticate()' function is called to verify the identity of - the current user. The user is usually required to enter a password - or similar authentication token, depending upon the authentication - - - - Samar, Schemers Page 20 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - module configured with the system. The user in question is specified - by a prior call to `pam_start()', and is referenced by the - authentication handle, `pamh'. - - int - pam_setcred( - pam_handle_t *pamh, - int flags - ); - - The `pam_setcred()' function is called to set the credentials of the - current process associated with the authentication handle, `pamh'. - The actions that can be denoted through `flags' include credential - initialization, refresh, reinitialization and deletion. - - A.3. Account Management API - - int - pam_acct_mgmt( - pam_handle_t *pamh, - int flags - ); - - The function `pam_acct_mgmt()' is called to determine whether the - current user's account and password are valid. This typically - includes checking for password and account expiration, valid login - times, etc. The user in question is specified by a prior call to - `pam_start()', and is referenced by the authentication handle, - `pamh'. - - A.4. Session Management API's - - int - pam_open_session( - pam_handle_t *pamh, - int flags - ); - - `pam_open_session()' is called to inform the session modules that a - new session has been initialized. All programs which use PAM should - invoke `pam_open_session()' when beginning a new session. - - int - pam_close_session( - pam_handle_t *pamh, - int flags - ); - - Upon termination of this session, the `pam_close_session()' function - should be invoked to inform the underlying modules that the session - has terminated. - - - - Samar, Schemers Page 21 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - A.5. Password Management API's - - int - pam_chauthtok( - pam_handle_t *pamh, - int flags - ); - - `pam_chauthtok()' is called to change the authentication token - associated with the user referenced by the authentication handle - `pamh'. After the call, the authentication token of the user will be - changed in accordance with the authentication module configured on - the system. - - - APPENDIX B. SAMPLE PAM APPLICATION - - This appendix shows a sample `login' application which uses the PAM - API's. It is not meant to be a fully functional login program, as - some functionality has been left out in order to emphasize the use of - PAM API's. - - #include <security/pam_appl.h> - - static int login_conv(int num_msg, struct pam_message **msg, - struct pam_response **response, void *appdata_ptr); - - static struct pam_conv pam_conv = {login_conv, NULL}; - - static pam_handle_t *pamh; /* Authentication handle */ - - void - main(int argc, char *argv[], char **renvp) - { - - /* - * Call pam_start to initiate a PAM authentication operation - */ - - if ((pam_start("login", user_name, &pam_conv, &pamh)) - != PAM_SUCCESS) - login_exit(1); - - pam_set_item(pamh, PAM_TTY, ttyn); - pam_set_item(pamh, PAM_RHOST, remote_host); - - while (!authenticated && retry < MAX_RETRIES) { - status = pam_authenticate(pamh, 0); - authenticated = (status == PAM_SUCCESS); - } - - - - - Samar, Schemers Page 22 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - if (status != PAM_SUCCESS) { - fprintf(stderr,"error: %s\n", pam_strerror(status)); - login_exit(1); - } - - /* now check if the authenticated user is allowed to login. */ - - if ((status = pam_acct_mgmt(pamh, 0)) != PAM_SUCCESS) { - if (status == PAM_AUTHTOK_EXPIRED) { - status = pam_chauthtok(pamh, 0); - if (status != PAM_SUCCESS) - login_exit(1); - } else { - login_exit(1); - } - } - - /* - * call pam_open_session to open the authenticated session - * pam_close_session gets called by the process that - * cleans up the utmp entry (i.e., init) - */ - if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) { - login_exit(status); - } - - /* set up the process credentials */ - setgid(pwd->pw_gid); - - /* - * Initialize the supplementary group access list. - * This should be done before pam_setcred because - * the PAM modules might add groups during the pam_setcred call - */ - initgroups(user_name, pwd->pw_gid); - - status = pam_setcred(pamh, PAM_ESTABLISH_CRED); - if (status != PAM_SUCCESS) { - login_exit(status); - } - - /* set the real (and effective) UID */ - setuid(pwd->pw_uid); - - pam_end(pamh, PAM_SUCCESS); /* Done using PAM */ - - /* - * Add DCE/Kerberos cred name, if any. - * XXX - The module specific stuff should be removed from login - * program eventually. This is better placed in DCE module and - * will be once PAM has routines for "exporting" environment - - - - Samar, Schemers Page 23 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - * variables. - */ - krb5p = getenv("KRB5CCNAME"); - if (krb5p != NULL) { - ENVSTRNCAT(krb5ccname, krb5p); - envinit[basicenv++] = krb5ccname; - } - environ = envinit; /* Switch to the new environment. */ - exec_the_shell(); - - /* All done */ - } - - /* - * login_exit - Call exit() and terminate. - * This function is here for PAM so cleanup can - * be done before the process exits. - */ - static void - login_exit(int exit_code) - { - if (pamh) - pam_end(pamh, PAM_ABORT); - exit(exit_code); - /*NOTREACHED*/ - } - - /* - * login_conv(): - * This is the conv (conversation) function called from - * a PAM authentication module to print error messages - * or garner information from the user. - */ - - static int - login_conv(int num_msg, struct pam_message **msg, - struct pam_response **response, void *appdata_ptr) - { - - while (num_msg--) { - switch (m->msg_style) { - - case PAM_PROMPT_ECHO_OFF: - r->resp = strdup(getpass(m->msg)); - break; - - case PAM_PROMPT_ECHO_ON: - (void) fputs(m->msg, stdout); - r->resp = malloc(PAM_MAX_RESP_SIZE); - fgets(r->resp, PAM_MAX_RESP_SIZE, stdin); - /* add code here to remove \n from fputs */ - - - - Samar, Schemers Page 24 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - break; - - case PAM_ERROR_MSG: - (void) fputs(m->msg, stderr); - break; - - case PAM_TEXT_INFO: - (void) fputs(m->msg, stdout); - break; - - default: - /* add code here to log error message, etc */ - break; - } - } - return (PAM_SUCCESS); - } - - - APPENDIX C. DCE MODULE - - This appendix describes a sample implementation of a DCE PAM module. - In order to simplify the description, we do not address the issues - raised by password-mapping or stacking. The intent is to show which - DCE calls are being made by the DCE module. - - The `pam_sm_*()' functions implement the PAM SPI functions which are - called from the PAM API functions. - - C.1. DCE Authentication Management - - The algorithm for authenticating with DCE (not including error - checking, prompting for passwords, etc.) is as follows: - - pam_sm_authenticate() - { - sec_login_setup_identity(...); - pam_set_data(...); - sec_login_valid_and_cert_ident(...); - } - - pam_sm_setcred() - { - pam_get_data(...); - sec_login_set_context(...); - } - - The `pam_sm_authenticate()' function for DCE uses the - `pam_set_data()' and `pam_get_data()' functions to keep state (like - the `sec_login_handle_t' context) between calls. The following - cleanup function is also registered and gets called when `pam_end()' - - - - Samar, Schemers Page 25 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - is called: - - dce_cleanup() - { - if (/* PAM_SUCCESS and - sec_login_valid_and_cert_ident success */) { - sec_login_release_context(...); - } else { - sec_login_purge_context(...); - } - } - - If everything was successful we release the login context, but leave - the credentials file intact. If the status passed to `pam_end()' was - not `PAM_SUCCESS' (i.e., a required module failed) we purge the login - context which also removes the credentials file. - - C.2. DCE Account Management - - The algorithm for DCE account management is as follows: - - pam_sm_acct_mgmt() - { - pam_get_data(...); - sec_login_inquire_net_info(...); - /* check for expired password and account */ - sec_login_free_net_info(...); - } - - The `sec_login_inquire_net_info()' function is called to obtain - information about when the user's account and/or password are going - to expire. A warning message is displayed (using the conversation - function) if the user's account or password is going to expire in the - near future, or has expired. These warning messages can be disabled - using the `nowarn' option in the `pam.conf' file. - - C.3. DCE Session Management - - The DCE session management functions are currently empty. They could - be modified to optionally remove the DCE credentials file upon - logout, etc. - - C.4. DCE Password Management - - The algorithm for DCE password management is as follows: - - - - - - - - - - Samar, Schemers Page 26 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - pam_sm_chauthtok - { - sec_rgy_site_open(...); - sec_rgy_acct_lookup(...); - sec_rgy_acct_passwd(...); - sec_rgy_site_close(...); - } - - The `sec_rgy_acct_passwd()' function is called to change the user's - password in the DCE registry. - - - REFERENCES - - [Adamson 95] W. A. Adamson, J. Rees, and P. Honeyman, "Joining - Security Realms: A Single Login for Netware and - Kerberos", CITI Technical Report 95-1, Center for - Information Technology Integration, University of - Michigan, Ann Arbor, MI, February 1995. - - [Diffie 76] W. Diffie and M. E. Hellman, "New Directions in - Cryptography", IEEE Transactions on Information - Theory, November 1976. - - [Linn 93] J. Linn, "Generic Security Service Application - Programming Interface", Internet RFC 1508, 1509, 1993. - - [Rivest 78] R. L. Rivest, A. Shamir, and L. Adleman., "A Method - for Obtaining Digital Signatures and Pubic-key - Cryptosystems", Communications of the ACM, 21(2), - 1978. - - [SIA 95] "Digital UNIX Security", Digital Equipment - Corporation, Order Number AA-Q0R2C-TE, July 1995. - - [Skey 94] N. M. Haller, "The S/Key One-Time Password System", - ISOC Symposium on Network and Distributed Security, - 1994. - - [Steiner 88] J.G. Steiner, B. C. Neuman, and J. I. Schiller, - "Kerberos, An Authentication Service for Open Network - Systems", in Proceedings of the Winter USENIX - Conference, Dallas, Jan 1988. - - [Taylor 88] B. Taylor and D. Goldberg, "Secure Networking in the - Sun Environment", Sun Microsystems Technical Paper, - 1988. - - [XFN 94] "Federated Naming: the XFN Specifications", X/Open - Preliminary Specification, X/Open Document #P403, - ISBN:1-85912-045-8, X/Open Co. Ltd., July 1994. - - - - Samar, Schemers Page 27 - - - - - - - - OSF-RFC 86.0 PAM October 1995 - - - - AUTHOR'S ADDRESS - - Vipin Samar Internet email: vipin@eng.sun.com - SunSoft, Inc. Telephone: +1-415-336-1002 - 2550 Garcia Avenue - Mountain View, CA 94043 - USA - - Roland J. Schemers III Internet email: schemers@eng.sun.com - SunSoft, Inc. Telephone: +1-415-336-1035 - 2550 Garcia Avenue - Mountain View, CA 94043 - USA - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Samar, Schemers Page 28 - - - - - - diff --git a/doc/specs/std-agent-id.raw b/doc/specs/std-agent-id.raw deleted file mode 100644 index d5fbdd56..00000000 --- a/doc/specs/std-agent-id.raw +++ /dev/null @@ -1,95 +0,0 @@ -PAM working group ## A.G. Morgan - -## $Id$ ## - -## Pluggable Authentication Modules ## - -## REGISTERED AGENTS AND THEIR AGENT-ID'S ## - -#$ Purpose of this document - -#$$#{definition} Definition of an agent-id - -The most complete version of a "PAM agent-id" is contained in this -reference [#$R#{PAM_RFC2}]. A copy of a recent definition is -reproduced here for convenience. The reader is recommended to consult -reference [#{PAM_RFC2}] for definitions of other terms that are -used in this document. - -## -------------- ## - -The agent_id is a sequence of characters satisfying the following -regexp: - - /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/ - -and has a specific form for each independent agent. - -o Agent_ids that do not contain an at-sign (@) are to be considered as - representing some authentication mode that is a "public - standard". Registered names MUST NOT contain an at-sign (@). - -o Anyone can define additional agents by using names in the format - name@domainname, e.g. "ouragent@example.com". The part following - the at-sign MUST be a valid fully qualified internet domain name - [RFC-1034] controlled by the person or organization defining the - name. (Said another way, if you control the email address that - your agent has as an identifier, they you are entitled to use - this identifier.) It is up to each domain how it manages its local - namespace. - -## -------------- ## - -#$ Registered agent-id's - -The structure of this section is a single subsection for each -registered agent-id. This section includes a full definition of binary -prompts accepted by the agent and example responses of said -agent. Using the defining section alone, it should be possible for a -third party to create a conforming agent and modules that can -interoperate with other implementations of these objects. - -*$ "userpass" - the user+password agent - -Many legacy authentication systems are hardcoded to support one and -only one authentication method. Namely, - - username: joe - password: <secret> - -Indeed, this authentication method is often embedded into parts of the -transport protocol. The "user+password" agent with PAM agent-id: - - "userpass" - -Is intended to support this legacy authentication scheme. The protocol -for binary prompt exchange with this 'standard agent' is as follows: - -Case 1: module does not know the username, but expects the agent to - obtain this information and also the user's password: - - module: {LENGTH;PAM_BP_SELECT;userpass;'/'} - agent: {} - -Case 2: module has suggested username, but would like agent to confirm - it and gather password: - - module: {} - agent: {} - -Case 3: module knows username and will not permit the agent to change it: - - module: {} - agent: {} - -#$ References - -[#{PAM_RFC2}] Internet draft, "Pluggable Authentication Modules - (PAM)", available here: - -# http://linux.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt # - -#$ Author's Address - -Andrew G. Morgan -Email: morgan@kernel.org diff --git a/doc/txts/.cvsignore b/doc/txts/.cvsignore deleted file mode 100644 index f35c3921..00000000 --- a/doc/txts/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -pam*.txt diff --git a/doc/txts/README b/doc/txts/README deleted file mode 100644 index 540b09b5..00000000 --- a/doc/txts/README +++ /dev/null @@ -1,3 +0,0 @@ -$Id$ - -This is a directory for text versions of the pam documentation -- cgit v1.2.3