diff options
Diffstat (limited to 'contrib/libpam/doc')
53 files changed, 2612 insertions, 362 deletions
diff --git a/contrib/libpam/doc/CREDITS b/contrib/libpam/doc/CREDITS index 95ca2ab36e02..528032bbb8ae 100644 --- a/contrib/libpam/doc/CREDITS +++ b/contrib/libpam/doc/CREDITS @@ -1,29 +1,41 @@ <!-- an sgml list of people to credit for their contributions to Linux-PAM - $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $ + $Id: CREDITS,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ --> +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, diff --git a/contrib/libpam/doc/Makefile b/contrib/libpam/doc/Makefile index 866b408512df..8ff16077a82a 100644 --- a/contrib/libpam/doc/Makefile +++ b/contrib/libpam/doc/Makefile @@ -1,10 +1,13 @@ -### $Id: Makefile,v 1.9 1997/01/04 21:55:52 morgan Exp $ +### $Id: Makefile,v 1.3 2001/01/22 08:03:01 agmorgan Exp $ -TXTER=sgml2txt -HTMLER=sgml2html -# older distributions use, sgml2ps -PSER=sgml2latex -p +include ../Make.Rules + +# These two should probably be moved into autoconf... +DOCDIR=/usr/doc/Linux-PAM +MANDIR=/usr/man + +####################################################### FILES=pam pam_appl pam_modules FSRCS=pam.sgml pam_appl.sgml pam_modules.sgml @@ -26,36 +29,48 @@ 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 ; $(HTMLER) ../$$i ; \ + 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 ; $(TXTER) ../$$i ; cd .. ; \ + 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 -pam.sgml: pam_source.sgml MODULES-SGML - @sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' pam_source.sgml > pam.sgml +pam.sgml: pam_source.sgml MODULES-SGML CREDITS + @sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' pam_source.sgml | sed -e '/^<!\-\- insert\-file CREDITS \-\->/r CREDITS' > pam.sgml MODULES-SGML: $(MODULES) @echo 'Building module text from files in modules/*.sgml' @@ -67,11 +82,64 @@ MODULES-SGML: $(MODULES) 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 +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)/man{3,8} + 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: + 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) + rm -f $(PSFILES) ps/missfont.log rm -f MODULES-SGML pam.sgml + rm -f specs/draft-morgan-pam-current.txt + make -C specs/formatter clean diff --git a/contrib/libpam/doc/html/index.html b/contrib/libpam/doc/html/index.html index 91f990fc01e0..5cb1e0f0ebb4 100644 --- a/contrib/libpam/doc/html/index.html +++ b/contrib/libpam/doc/html/index.html @@ -17,5 +17,5 @@ currently not complete. However, in order of decreasing length: <hr> <p> -REVISION: <tt>$Id: index.html,v 1.4 1996/11/21 06:51:01 morgan Exp $</tt> +REVISION: <tt>$Id: index.html,v 1.1.1.1 2000/06/20 22:10:56 agmorgan Exp $</tt> </BODY> diff --git a/contrib/libpam/doc/man/pam.8 b/contrib/libpam/doc/man/pam.8 index 75384416f2cf..b814cebe2ec2 100644 --- a/contrib/libpam/doc/man/pam.8 +++ b/contrib/libpam/doc/man/pam.8 @@ -1,7 +1,7 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam.8,v 1.2 1997/02/15 18:37:27 morgan Exp $ -.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org> -.TH PAM 8 "1997 Feb 9" "Linux-PAM 0.56" "Linux-PAM Manual" +.\" $Id: pam.8,v 1.2 2001/01/20 23:47:07 agmorgan Exp $ +.\" Copyright (c) Andrew G. Morgan 1996-7,2001 <morgan@kernel.org> +.TH PAM 8 "2001 Jan 20" "Linux-PAM 0.74" "Linux-PAM Manual" .SH NAME Linux-PAM \- Pluggable Authentication Modules for Linux @@ -197,7 +197,14 @@ The meaning of each of these tokens was explained above. The third field, .BR control ", " indicates the behavior of the PAM-API should the module fail to -succeed in its authentication task. Valid +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 @@ -224,8 +231,97 @@ 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 the full filename of the PAM to be used by the application +- 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 @@ -238,19 +334,13 @@ documented for each individual module. .br .BR /etc/pam.d/ " - the" .BR Linux-PAM -configuration directory. If this directory is present, the +configuration directory. Generally, if this directory is present, the .B /etc/pam.conf file is ignored. .br -.BR /usr/lib/libpam.so.X " - the dynamic library" +.BR /lib/libpam.so.X " - the dynamic library" .br -.BR /usr/lib/security/*.so " - the PAMs - -.sp -Note, to conform to the Linux File-system standard, the libraries and -modules in your system may be located in -.BR /lib " and " /lib/security -respectively. +.BR /lib/security/*.so " - the PAMs .SH ERRORS Typically errors generated by the @@ -261,8 +351,8 @@ system of libraries, will be written to .SH "CONFORMING TO" DCE-RFC 86.0, October 1995. .br -Contains additional features, currently under consideration by the -DCE-RFC committee. +Contains additional features, but remains backwardly compatible with +this RFC. .SH BUGS .sp 2 @@ -273,7 +363,7 @@ None known. The three .BR Linux-PAM Guides, for -.BR "System administrators" ", " +.BR "system administrators" ", " .BR "module developers" ", " and .BR "application developers" ". " diff --git a/contrib/libpam/doc/man/pam.conf.8 b/contrib/libpam/doc/man/pam.conf.8 index ea2dd98bfc9f..d067b5596eab 100644 --- a/contrib/libpam/doc/man/pam.conf.8 +++ b/contrib/libpam/doc/man/pam.conf.8 @@ -1 +1 @@ -.so man8/pam.8 +.so pam.8 diff --git a/contrib/libpam/doc/man/pam.d.8 b/contrib/libpam/doc/man/pam.d.8 index ea2dd98bfc9f..d067b5596eab 100644 --- a/contrib/libpam/doc/man/pam.d.8 +++ b/contrib/libpam/doc/man/pam.d.8 @@ -1 +1 @@ -.so man8/pam.8 +.so pam.8 diff --git a/contrib/libpam/doc/man/pam_authenticate.3 b/contrib/libpam/doc/man/pam_authenticate.3 index f631c47286be..7383f5f06b40 100644 --- a/contrib/libpam/doc/man/pam_authenticate.3 +++ b/contrib/libpam/doc/man/pam_authenticate.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_authenticate.3,v 1.2 1997/02/15 18:39:59 morgan Exp $ +.\" $Id: pam_authenticate.3,v 1.1.1.1 2000/06/20 22:10:57 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net> .TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_chauthtok.3 b/contrib/libpam/doc/man/pam_chauthtok.3 index b0997d592893..a0466f0fccc6 100644 --- a/contrib/libpam/doc/man/pam_chauthtok.3 +++ b/contrib/libpam/doc/man/pam_chauthtok.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_chauthtok.3,v 1.2 1997/02/15 18:42:23 morgan Exp $ +.\" $Id: pam_chauthtok.3,v 1.1.1.1 2000/06/20 22:10:57 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> .TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_close_session.3 b/contrib/libpam/doc/man/pam_close_session.3 index c809a0e4f0d8..d851700cda02 100644 --- a/contrib/libpam/doc/man/pam_close_session.3 +++ b/contrib/libpam/doc/man/pam_close_session.3 @@ -1 +1 @@ -.so man3/pam_open_session.3 +.so pam_open_session.3 diff --git a/contrib/libpam/doc/man/pam_end.3 b/contrib/libpam/doc/man/pam_end.3 index 06fdabb9c462..de999f240cfb 100644 --- a/contrib/libpam/doc/man/pam_end.3 +++ b/contrib/libpam/doc/man/pam_end.3 @@ -1 +1 @@ -.so man3/pam_start.3 +.so pam_start.3 diff --git a/contrib/libpam/doc/man/pam_fail_delay.3 b/contrib/libpam/doc/man/pam_fail_delay.3 index 42bccd6b9258..3b72f3d98b42 100644 --- a/contrib/libpam/doc/man/pam_fail_delay.3 +++ b/contrib/libpam/doc/man/pam_fail_delay.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_fail_delay.3,v 1.2 1997/02/15 18:47:46 morgan Exp morgan $ +.\" $Id: pam_fail_delay.3,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> .TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_open_session.3 b/contrib/libpam/doc/man/pam_open_session.3 index 1b2dcf980bdb..53f6adf12c75 100644 --- a/contrib/libpam/doc/man/pam_open_session.3 +++ b/contrib/libpam/doc/man/pam_open_session.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_open_session.3,v 1.2 1997/02/15 18:49:02 morgan Exp $ +.\" $Id: pam_open_session.3,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> .TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_setcred.3 b/contrib/libpam/doc/man/pam_setcred.3 index 388a5d766703..ea251405ac7d 100644 --- a/contrib/libpam/doc/man/pam_setcred.3 +++ b/contrib/libpam/doc/man/pam_setcred.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_setcred.3,v 1.2 1997/02/15 18:50:49 morgan Exp morgan $ +.\" $Id: pam_setcred.3,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net> .TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_start.3 b/contrib/libpam/doc/man/pam_start.3 index 0299533b4f5e..a912cc754664 100644 --- a/contrib/libpam/doc/man/pam_start.3 +++ b/contrib/libpam/doc/man/pam_start.3 @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: pam_start.3,v 1.2 1997/02/15 18:51:54 morgan Exp $ +.\" $Id: pam_start.3,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net> .TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/man/pam_strerror.3 b/contrib/libpam/doc/man/pam_strerror.3 index 33b4fda4c31e..b2318f2884c7 100644 --- a/contrib/libpam/doc/man/pam_strerror.3 +++ b/contrib/libpam/doc/man/pam_strerror.3 @@ -1,8 +1,8 @@ .\" Hey Emacs! This file is -*- nroff -*- source. .\" ripped off from Rick Faith's getgroups man page -.\" $Id: pam_strerror.3,v 1.2 1997/02/15 18:53:04 morgan Exp $ -.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net> -.TH PAM_STRERROR 3 "1997 Feb 15" "Linux-PAM 0.56" "Programmers' Manual" +.\" $Id: pam_strerror.3,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ +.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org> +.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual" .SH NAME pam_strerror \- return a textual description of a Linux-PAM error @@ -14,14 +14,16 @@ or, .br .B #include <security/pam_modules.h> .sp -.BI "const char *pam_strerror(" int " pam_error); +.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");" .sp 2 .SH DESCRIPTION .B pam_strerror -This function returns a pointer to a line of text describing the +This function returns some text describing the .BR Linux-PAM -error passed as its sole argument. +error associated with the +.B pam_error +argument. .SH "RETURN VALUE" diff --git a/contrib/libpam/doc/man/template-man b/contrib/libpam/doc/man/template-man index a635c8bd8024..11e7a061504a 100644 --- a/contrib/libpam/doc/man/template-man +++ b/contrib/libpam/doc/man/template-man @@ -1,5 +1,5 @@ .\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id: template-man,v 1.1 1997/01/04 18:25:13 morgan Exp $ +.\" $Id: template-man,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> .TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual" .SH NAME diff --git a/contrib/libpam/doc/modules/README b/contrib/libpam/doc/modules/README index b97b2cd501b9..b6587f508c25 100644 --- a/contrib/libpam/doc/modules/README +++ b/contrib/libpam/doc/modules/README @@ -1,4 +1,4 @@ -$Id: README,v 1.2 1996/11/17 17:20:28 morgan Exp $ +$Id: README,v 1.1.1.1 2000/06/20 22:10:58 agmorgan Exp $ This directory contains a number of sgml sub-files. One for each documented module. They contain a description of each module and give diff --git a/contrib/libpam/doc/modules/module.sgml-template b/contrib/libpam/doc/modules/module.sgml-template index 53cd809f338d..3fffc754b047 100644 --- a/contrib/libpam/doc/modules/module.sgml-template +++ b/contrib/libpam/doc/modules/module.sgml-template @@ -1,9 +1,9 @@ <!-- - $Id: module.sgml-template,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: module.sgml-template,v 1.2 2001/02/11 07:52:56 agmorgan Exp $ This template file was written by Andrew G. Morgan - <morgan@parc.power.net> + <morgan@kernel.org> [ Text that should be deleted/replaced, is enclosed within diff --git a/contrib/libpam/doc/modules/pam_access.sgml b/contrib/libpam/doc/modules/pam_access.sgml new file mode 100644 index 000000000000..00c7ea169d00 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_access.sgml @@ -0,0 +1,108 @@ +<!-- + + pam_access module docs added by Tim Berger <timb@transmeta.com> + +--> + +<sect1> The access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +<tt>pam_access</tt> + + +<tag><bf>Author[s]:</bf></tag> + +Alexei Nogin <alexei@nogin.dnttm.ru> + +<tag><bf>Maintainer:</bf></tag> + +Author + +<tag><bf>Management groups provided:</bf></tag> + +account + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires a configuration file. By default +<tt>/etc/security/access.conf</tt> is used but this can be overridden. + +<tag><bf>Network aware:</bf></tag> + +Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of +the stdin file descriptor with <tt/ttyname()/. Standard +gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/ +calls. <bf/NIS/ is used for netgroup support. + +</descrip> + +<sect2>Overview of module + +<p> +Provides logdaemon style login access control. + +<sect2> Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt>accessfile=<it>/path/to/file.conf</it></tt> + +<tag><bf>Description:</bf></tag> + +This module provides logdaemon style login access control based on +login names and on host (or domain) names, internet addresses (or +network numbers), or on terminal line names in case of non-networked +logins. Diagnostics are reported through <tt/syslog(3)/. Wietse +Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with +several changes by A. Nogin. + +<p> +The behavior of this module can be modified with the following +arguments: +<itemize> + +<item><tt>accessfile=/path/to/file.conf</tt> - +indicate an alternative <em/access/ configuration file to override +the default. This can be useful when different services need different +access lists. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +Use of module is recommended, for example, on administrative machines +such as <bf/NIS/ servers and mail servers where you need several accounts +active but don't want them all to have login capability. + +For <tt>/etc/pam.d</tt> style configurations where your modules live +in <tt>/lib/security</tt>, start by adding the following line to +<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>, +<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>: + +<tscreen> +<verb> +account required /lib/security/pam_access.so +</verb> +</tscreen> + +Note that use of this module is not effective unless your system ignores +<tt>.rhosts</tt> files. See the the pam_rhosts_auth documentation. + +A sample <tt>access.conf</tt> configuration file is included with the +distribution. + +</descrip> diff --git a/contrib/libpam/doc/modules/pam_chroot.sgml b/contrib/libpam/doc/modules/pam_chroot.sgml index 7f8c4a39b642..2366880eabfc 100644 --- a/contrib/libpam/doc/modules/pam_chroot.sgml +++ b/contrib/libpam/doc/modules/pam_chroot.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_chroot.sgml,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: pam_chroot.sgml,v 1.1.1.1 2000/06/20 22:10:59 agmorgan Exp $ This file was written by Bruce Campbell <brucec@humbug.org.au> --> diff --git a/contrib/libpam/doc/modules/pam_cracklib.sgml b/contrib/libpam/doc/modules/pam_cracklib.sgml index 4700c2a04f03..810b261e83e9 100644 --- a/contrib/libpam/doc/modules/pam_cracklib.sgml +++ b/contrib/libpam/doc/modules/pam_cracklib.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_cracklib.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp morgan $ + $Id: pam_cracklib.sgml,v 1.3 2000/12/04 15:23:15 baggins Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com> @@ -48,10 +48,6 @@ Requires the system library <tt/libcrack/ and a system dictionary: <p> This module can be plugged into the <tt/password/ stack of a given application to provide some plug-in strength-checking for passwords. -(XXX - note this does not necessarily work with the pam_unix module, -although it is known to work with the pam_pwdb replacement for the -unix module -- see example and pam_pwdb write up for more -information). <p> This module works in the following manner: it first calls the @@ -70,23 +66,35 @@ Is the new password the the old one with only a change of case? <item> <bf/Similar/ - -Is the new password too much like the old one? This is controlled -by one argument, <tt/difok/ which is a number of characters that if -different between the old and new are enough to accept the new +Is the new password too much like the old one? This is primarily +controlled by one argument, <tt/difok/ which is a number of characters +that if different between the old and new are enough to accept the new password, this defaults to 10 or 1/2 the size of the new password whichever is smaller. -<item <bf/Simple/ - +To avoid the lockup associated with trying to change a long and +complicated password, <tt/difignore/ is available. This argument can +be used to specify the minimum length a new password needs to be +before the <tt/difok/ value is ignored. The default value for +<tt/difignore/ is 23. + + +<item> <bf/Simple/ - Is the new password too small? This is controlled by 5 arguments <tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and <tt/ocredit/. See the section on the arguments for the details of how these work and there defaults. -<item <bf/Rotated/ - +<item> <bf/Rotated/ - Is the new password a rotated version of the old password? +<item> <bf/Already used/ - + +Was the password used in the past? Previously used passwords are to +be found in /etc/security/opasswd. + </itemize> <p> @@ -113,6 +121,7 @@ share most of these characters with the old password. <tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/; <tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/; +<tt/use_authtok/; <tag><bf>Description:</bf></tag> @@ -204,14 +213,16 @@ character will count +1 towards meeting the current <tt/minlen/ value. The default for <tt/ocredit/ is 1 which is the recommended value for <tt/minlen/ less than 10. +<item> <tt/use_authtok/ - + +This argument is used to <em/force/ the module to not prompt the user +for a new password but use the one provided by the previously stacked +<tt/password/ module. + </itemize> <tag><bf>Examples/suggested usage:</bf></tag> -(At the time of writing, this module can only be stacked before the -<tt/pam_pwdb/ module. Cracklib strength checking may be compiled by -default into the <tt/pam_unix/ module.) - <p> For an example of the use of this module, we show how it may be stacked with the password component of <tt/pam_pwdb/: diff --git a/contrib/libpam/doc/modules/pam_deny.sgml b/contrib/libpam/doc/modules/pam_deny.sgml index 99f367156fe5..9fd0ea4358cd 100644 --- a/contrib/libpam/doc/modules/pam_deny.sgml +++ b/contrib/libpam/doc/modules/pam_deny.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_deny.sgml,v 1.3 1997/02/15 18:25:44 morgan Exp morgan $ + $Id: pam_deny.sgml,v 1.1.1.1 2000/06/20 22:11:00 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> diff --git a/contrib/libpam/doc/modules/pam_env.sgml b/contrib/libpam/doc/modules/pam_env.sgml index a62f4576f132..a6361cacc76a 100644 --- a/contrib/libpam/doc/modules/pam_env.sgml +++ b/contrib/libpam/doc/modules/pam_env.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_env.sgml,v 1.1 1997/04/05 06:50:42 morgan Exp $ + $Id: pam_env.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ This file was written by Dave Kinchlea <kinch@kinch.ark.com> Ed. AGM @@ -50,7 +50,8 @@ is the use of previously set environment variables as well as <descrip> <tag><bf>Recognized arguments:</bf></tag> -<tt/debug/; <tt/conffile=/<em/configuration-file-name/ +<tt/debug/; <tt/conffile=/<em/configuration-file-name/; +<tt/envfile/=<em/env-file-name/; <tt/readenv/=<em/0|1/ <tag><bf>Description:</bf></tag> This module allows you to (un)set arbitrary environment variables @@ -60,9 +61,9 @@ and/or <em/PAM_ITEM/s. <p> All is controlled via a configuration file (by default, <tt>/etc/security/pam_env.conf</tt> but can be overriden with -<tt>connfile</tt> argument). Each line starts with the variable name, +<tt>conffile</tt> argument). Each line starts with the variable name, there are then two possible options for each variable <bf>DEFAULT</bf> -and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows and administrator to +and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows an administrator to set the value of the variable to some default value, if none is supplied then the empty string is assumed. The <bf>OVERRIDE</bf> option tells pam_env that it should enter in its value (overriding the @@ -88,6 +89,12 @@ space is needed <bf>the full value must be delimited by the quotes and embedded or escaped quotes are not supported</bf>. <p> +This module can also parse a file with simple <tt>KEY=VAL</tt> pairs +on seperate lines (<tt>/etc/environment</tt> by default). You can +change the default file to parse, with the <em/envfile/ flag and turn +it on or off by setting the <em/readenv/ flag to 1 or 0 respectively. + +<p> The behavior of this module can be modified with one of the following flags: @@ -102,6 +109,15 @@ flags: the configuration file. This option overrides the default. You must supply a complete path + file name. +<item><tt/envfile=/<em/filename/ +- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL +pairs directly into the env. This option overrides the default. You must +supply a complete path + file name. + +<item><tt/readenv=/<em/0|1/ +- turns on or off the reading of the file specified by envfile (0 is off, +1 is on). By default this option is on. + </itemize> <tag><bf>Examples/suggested usage:</bf></tag> diff --git a/contrib/libpam/doc/modules/pam_filter.sgml b/contrib/libpam/doc/modules/pam_filter.sgml index 99f06ef01b64..a339be4e0e37 100644 --- a/contrib/libpam/doc/modules/pam_filter.sgml +++ b/contrib/libpam/doc/modules/pam_filter.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_filter.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_filter.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> @@ -100,8 +100,8 @@ the filter might expect. <p> Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the -precise time the that filter is to be run. To explain this concept it -will be useful to have read the Linux-PAM Module developer's +precise time that the filter is to be run. To understand this concept +it will be useful to have read the Linux-PAM Module developer's guide. Basically, for each management group there are up to two ways of calling the module's functions. diff --git a/contrib/libpam/doc/modules/pam_ftp.sgml b/contrib/libpam/doc/modules/pam_ftp.sgml index ca2e065d0122..81a2868dfed0 100644 --- a/contrib/libpam/doc/modules/pam_ftp.sgml +++ b/contrib/libpam/doc/modules/pam_ftp.sgml @@ -1,7 +1,7 @@ <!-- - $Id: pam_ftp.sgml,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: pam_ftp.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ - This file was written by Andrew G. Morgan <morgan@parc.power.net> + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> --> <sect1>Anonymous access module @@ -15,7 +15,7 @@ <tt/pam_ftp.so/ <tag><bf>Author:</bf></tag> -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@linux.kernel.org> <tag><bf>Maintainer:</bf></tag> Author. @@ -56,7 +56,7 @@ mode of access. This module intercepts the user's name and password. If the name is ``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up -at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/ +at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/ part; these pam-items being set accordingly. The username is set to ``<tt/ftp/''. In this case the module succeeds. Alternatively, the module sets the <tt/PAM_AUTHTOK/ item with the entered password and diff --git a/contrib/libpam/doc/modules/pam_group.sgml b/contrib/libpam/doc/modules/pam_group.sgml index 360edee06afb..517da4e9e2a7 100644 --- a/contrib/libpam/doc/modules/pam_group.sgml +++ b/contrib/libpam/doc/modules/pam_group.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_group.sgml,v 1.2 1997/01/04 20:50:10 morgan Exp $ + $Id: pam_group.sgml,v 1.1.1.1 2000/06/20 22:11:01 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> diff --git a/contrib/libpam/doc/modules/pam_issue.sgml b/contrib/libpam/doc/modules/pam_issue.sgml new file mode 100644 index 000000000000..1f617e3b870e --- /dev/null +++ b/contrib/libpam/doc/modules/pam_issue.sgml @@ -0,0 +1,120 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Add issue file to user prompt + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_issue/ + +<tag><bf>Author:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (pam_sm_authenticate) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module prepends the issue file (<em>/etc/issue</em> by default) when +prompting for a username. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/issue=issue-file-name/; <tt/noesc/; + +<tag><bf>Description:</bf></tag> +This module allows you to prepend an issue file to the username prompt. It +also by default parses escape codes in the issue file similar to some +common getty's (using \x format). +<p> +Recognized escapes: +<itemize> + +<item><tt/d/ +- current date + +<item><tt/s/ +- operating system name + +<item><tt/l/ +- name of this tty + +<item><tt/m/ +- architecture of this system (i686, sparc, powerpc, ...) + +<item><tt/n/ +- hostname of this system + +<item><tt/o/ +- domainname of this system + +<item><tt/r/ +- release number of the operation system (eg. 2.2.12) + +<item><tt/t/ +- current time + +<item><tt/u/ +- number of users currently logged in + +<item><tt/U/ +- same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1 +user" or "10 users" + +<item><tt/v/ +- version/build-date of the operating system (eg. "#3 Mon Aug 23 14:38:16 +EDT 1999" on Linux). + +</itemize> + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/issue/ +- the file to output if not using the default + +<item><tt/noesc/ +- turns off escape code parsing + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +login auth pam_issue.so issue=/etc/issue + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_krb4.sgml b/contrib/libpam/doc/modules/pam_krb4.sgml index edb87d1a0584..51a46522890c 100644 --- a/contrib/libpam/doc/modules/pam_krb4.sgml +++ b/contrib/libpam/doc/modules/pam_krb4.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_krb4.sgml,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: pam_krb4.sgml,v 1.1.1.1 2000/06/20 22:11:01 agmorgan Exp $ This file was written by Derrick J. Brashear <shadow@DEMENTIA.ORG> --> diff --git a/contrib/libpam/doc/modules/pam_lastlog.sgml b/contrib/libpam/doc/modules/pam_lastlog.sgml index 8c0e662c3cf9..451bfaa2fda6 100644 --- a/contrib/libpam/doc/modules/pam_lastlog.sgml +++ b/contrib/libpam/doc/modules/pam_lastlog.sgml @@ -1,7 +1,7 @@ <!-- - $Id: pam_mail.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_lastlog.sgml,v 1.2 2001/02/17 01:55:38 agmorgan Exp $ - This file was written by Andrew G. Morgan <morgan@parc.power.net> + This file was written by Andrew G. Morgan <morgan@kernel.org> --> <sect1>The last login module @@ -15,7 +15,7 @@ <tt/pam_lastlog/ <tag><bf>Author:</bf></tag> -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> <tag><bf>Maintainer:</bf></tag> Author @@ -30,7 +30,7 @@ auth <tag><bf>Clean code base:</bf></tag> <tag><bf>System dependencies:</bf></tag> -uses information contained in the <tt>/var/log/wtmp</tt> file. +uses information contained in the <tt>/var/log/lastlog</tt> file. <tag><bf>Network aware:</bf></tag> @@ -39,14 +39,14 @@ uses information contained in the <tt>/var/log/wtmp</tt> file. <sect2>Overview of module <p> -This session module maintains the <tt>/var/log/wtmp</tt> file. Adding +This session module maintains the <tt>/var/log/lastlog</tt> file. Adding an open entry when called via the <tt>pam_open_seesion()</tt> function and completing it when <tt>pam_close_session()</tt> is called. This module can also display a line of information about the last login of the user. If an application already performs these tasks, it is not necessary to use this module. -<sect2>Authentication component +<sect2>Session component <p> <descrip> @@ -61,7 +61,7 @@ necessary to use this module. This module can be used to provide a ``Last login on ...'' message. when the user logs into the system from what ever application uses the PAM libraries. In addition, the module maintains the -<tt>/var/log/wtmp</tt> file. +<tt>/var/log/lastlog</tt> file. <p> The behavior of this module can be modified with one of the following @@ -85,10 +85,10 @@ attempt. <item><tt/silent/ - neglect to inform the user about any previous login: just update -the <tt>/var/log/wtmp</tt> file. +the <tt>/var/log/lastlog</tt> file. <item><tt/never/ -- if the <tt>/var/log/wtmp</tt> file does not contain any old entries +- if the <tt>/var/log/lastlog</tt> file does not contain any old entries for the user, indicate that the user has never previously logged in with a ``welcome..." message. @@ -98,13 +98,13 @@ with a ``welcome..." message. This module can be used to indicate that the user has new mail when they <em/login/ to the system. Here is a sample entry for your -<tt>/etc/pam.conf</tt> file: +<tt>/etc/pam.d/XXX</tt> file: <tscreen> <verb> # -# do we have any mail? +# When were we last here? # -login session optional pam_lastlog.so +session optional pam_lastlog.so </verb> </tscreen> diff --git a/contrib/libpam/doc/modules/pam_limits.sgml b/contrib/libpam/doc/modules/pam_limits.sgml index 6b98ea64fcbd..c4bdb4df503e 100644 --- a/contrib/libpam/doc/modules/pam_limits.sgml +++ b/contrib/libpam/doc/modules/pam_limits.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_limits.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_limits.sgml,v 1.4 2001/03/29 04:21:16 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> from information compiled by Cristian Gafton (author of module) @@ -74,6 +74,12 @@ verbose logging to <tt/syslog(3)/. <item><tt>conf=/path/to/file.conf</tt> - indicate an alternative <em/limits/ configuration file to the default. +<item><tt/change_uid/ - +change real uid to the user for who the limits are set up. Use this +option if you have problems like login not forking a shell for user +who has no processes. Be warned that something else may break when +you do this. + </itemize> <tag><bf>Examples/suggested usage:</bf></tag> @@ -103,7 +109,7 @@ The fields listed above should be filled as follows...<newline> </itemize> <p> -<tt><type></tt> can have the two values: +<tt><type></tt> can have the three values: <itemize> <item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits @@ -116,6 +122,9 @@ by any pre-exisiting <em/hard/ limits. The values specified with this token can be thought of as <em/default/ values, for normal system usage. +<item> <tt/-/ for enforcing both <em/soft/ and <em/hard/ limits +together. + </itemize> <p> @@ -132,15 +141,22 @@ usage. <item><tt/nproc/ - max number of processes <item><tt/as/ - address space limit <item><tt/maxlogins/ - max number of logins for this user. +<item><tt/priority/ - the priority to run user process with </itemize> <p> -To completely disable limits for a user (or a group), a single dash -(-) will do (Example: ``<tt/bin -/'', ``<tt/@admin -/''). Please -remember that individual limits have priority over group limits, so if -you impose no limits for <tt/admin/ group, but one of the members in this -group have a limits line, the user will have its limits set according -to this line. +Note, if you specify a type of ``-'' but neglect to supply the +<tt/item/ and <tt/value/ fields then the module will never enforce any +limits on the corresponding user/group-members etc. . Note, the first +entry of the form which applies to the authenticating user will +override all other entries in the limits configuration file. In such +cases, the <tt/pam_limits/ module will always return <tt/PAM_SUCCESS/. + +<p> +In general, individual limits have priority over group limits, so if +you impose no limits for <tt/admin/ group, but one of the members in +this group have a limits line, the user will have its limits set +according to this line. <p> Also, please note that all limit settings are set <em/per login/. @@ -173,11 +189,11 @@ ftp hard nproc 0 </tscreen> Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource (see <tt/@faculty/) -- this establishes the <em/default/ and permitted -<em/extreme/ level of resources that the user can can obtain in a -given service-session. +<em/extreme/ level of resources that the user can obtain in a given +service-session. <p> -For the services that need resources limits (login for example) put a +For the services that need resources limits (login for example) put the following line in <tt>/etc/pam.conf</tt> as the last line for that service (usually after the pam_unix session line: <tscreen> diff --git a/contrib/libpam/doc/modules/pam_listfile.sgml b/contrib/libpam/doc/modules/pam_listfile.sgml index fe4a0d27cc2e..1284d1b6ab75 100644 --- a/contrib/libpam/doc/modules/pam_listfile.sgml +++ b/contrib/libpam/doc/modules/pam_listfile.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_listfile.sgml,v 1.3 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_listfile.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ This file was written by Michael K. Johnson <johnsonm@redhat.com> --> @@ -111,8 +111,8 @@ Note, users listed in <tt>/etc/ftpusers</tt> file are (counterintuitively) <bf/not/ allowed access to the ftp service. <p> -To allow login access only for certain users, you can use an -pam.conf entry like this: +To allow login access only for certain users, you can use a +<tt/pam.conf/ entry like this: <tscreen> <verb> # diff --git a/contrib/libpam/doc/modules/pam_mail.sgml b/contrib/libpam/doc/modules/pam_mail.sgml index 9a99f2064c36..65937a9f8dda 100644 --- a/contrib/libpam/doc/modules/pam_mail.sgml +++ b/contrib/libpam/doc/modules/pam_mail.sgml @@ -1,7 +1,7 @@ <!-- - $Id: pam_mail.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_mail.sgml,v 1.3 2001/03/19 01:46:41 agmorgan Exp $ - This file was written by Andrew G. Morgan <morgan@parc.power.net> + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> --> <sect1>The mail module @@ -15,13 +15,14 @@ <tt/pam_mail/ <tag><bf>Author:</bf></tag> -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@linux.kernel.org> <tag><bf>Maintainer:</bf></tag> Author <tag><bf>Management groups provided:</bf></tag> -auth +Authentication (credential) +Session (open) <tag><bf>Cryptographically sensitive:</bf></tag> @@ -42,14 +43,15 @@ Default mail directory <tt>/var/spool/mail/</tt> This module looks at the user's mail directory and indicates whether the user has any mail in it. -<sect2>Authentication component +<sect2>Session component <p> <descrip> <tag><bf>Recognized arguments:</bf></tag> -<tt/debug/; <tt/dir=/<em/direcory-name/; <tt/nopen/; <tt/close/; -<tt/noenv/; <tt/empty/ +<tt/debug/; <tt/dir=/<em/directory-name/; <tt/nopen/; <tt/close/; +<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/; +<tt/quiet/; <tag><bf>Description:</bf></tag> @@ -60,12 +62,6 @@ user's mail folder. This module also sets the <bf/Linux-PAM/ environment variable, <tt/MAIL/, to the user's mail directory. <p> -Although the module supplies functions for the authentication -management group of functions, it cannot be used to authenticate a -user; its authentication function instructs <tt/libpam/ to simply -ignore it when authenticating the user. - -<p> The behavior of this module can be modified with one of the following flags: @@ -97,6 +93,17 @@ the user's credentials are revoked. - indicate that the user's mail directory is empty if this is found to be the case. +<item><tt/hash=/<em/hashcount/ +- mail directory hash depth. For example, a <em/hashcount/ of 2 would +make the mailfile be <tt>/var/spool/mail/u/s/user</tt>. + +<item><tt/standard/ +- old style "You have..." format which doesn't show the mail spool being used. + this also implies "empty" + +<item><tt/quiet/ +- only report when there is new mail. + </itemize> <tag><bf>Examples/suggested usage:</bf></tag> @@ -109,16 +116,27 @@ they <em/login/ to the system. Here is a sample entry for your # # do we have any mail? # -login auth optional pam_mail.so +login session optional pam_mail.so </verb> </tscreen> <p> +Note, if the mail spool file (be it <tt>/var/spool/mail/$USER</tt> or +a pathname given with the <tt>dir=</tt> parameter) is a directory then +<tt>pam_mail</tt> assumes it is in the <it>Qmail Maildir</it> format. + +<p> Note, some applications may perform this function themselves. In such cases, this module is not necessary. </descrip> +<sect2>Authentication component + +<p> +Then authentication companent works the same as the session component, +except that everything is done during the <tt>pam_setcred()</tt> phase. + <!-- End of sgml insert for this module. --> diff --git a/contrib/libpam/doc/modules/pam_mkhomedir.sgml b/contrib/libpam/doc/modules/pam_mkhomedir.sgml new file mode 100644 index 000000000000..075e16f9fc05 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_mkhomedir.sgml @@ -0,0 +1,83 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Create home directories on initial login + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_mkhomedir/ + +<tag><bf>Author:</bf></tag> +Jason Gunthorpe <jgg@ualberta.ca> + +<tag><bf>Maintainer:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Management groups provided:</bf></tag> +Session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Creates home directories on the fly for authenticated users. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/; + +<tag><bf>Description:</bf></tag> +This module is useful for distributed systems where the user account is +managed in a central database (such as NIS, NIS+, or LDAP) and accessed +through miltiple systems. It frees the administrator from having to create +a default home directory on each of the systems by creating it upon the +first succesfully authenticated login of that user. The skeleton directory +(usually /etc/skel/) is used to copy default files and also set's a umask +for the creation. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/skel/ +- The skeleton directory for default files to copy to the new home directory. + +<item><tt/umask/ +- An octal for of the same format as you would pass to the shells umask command. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_motd.sgml b/contrib/libpam/doc/modules/pam_motd.sgml new file mode 100644 index 000000000000..8ddc63924e78 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_motd.sgml @@ -0,0 +1,77 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Output the motd file + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_motd/ + +<tag><bf>Author:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Session (open) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module outputs the motd file (<em>/etc/motd</em> by default) upon +successful login. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/motd=motd-file-name/; + +<tag><bf>Description:</bf></tag> +This module allows you to have arbitrary motd's (message of the day) +output after a succesful login. By default this file is <em>/etc/motd</em>, +but is configurable to any file. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/motd/ +- the file to output if not using the default. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +login session pam_motd.so motd=/etc/motd + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_nologin.sgml b/contrib/libpam/doc/modules/pam_nologin.sgml index de4b32a8efbd..963fa4282b4f 100644 --- a/contrib/libpam/doc/modules/pam_nologin.sgml +++ b/contrib/libpam/doc/modules/pam_nologin.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_nologin.sgml,v 1.2 1997/01/04 21:56:55 morgan Exp $ + $Id: pam_nologin.sgml,v 1.1.1.1 2000/06/20 22:11:02 agmorgan Exp $ This file was written by Michael K. Johnson <johnsonm@redhat.com> --> diff --git a/contrib/libpam/doc/modules/pam_permit.sgml b/contrib/libpam/doc/modules/pam_permit.sgml index 84df9fc1754f..2588110ddcd4 100644 --- a/contrib/libpam/doc/modules/pam_permit.sgml +++ b/contrib/libpam/doc/modules/pam_permit.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_permit.sgml,v 1.2 1997/02/15 18:20:12 morgan Exp $ + $Id: pam_permit.sgml,v 1.1.1.1 2000/06/20 22:11:02 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> diff --git a/contrib/libpam/doc/modules/pam_pwdb.sgml b/contrib/libpam/doc/modules/pam_pwdb.sgml index c9f7bff1124a..625572064bb2 100644 --- a/contrib/libpam/doc/modules/pam_pwdb.sgml +++ b/contrib/libpam/doc/modules/pam_pwdb.sgml @@ -1,7 +1,7 @@ <!-- - $Id: pam_pwdb.sgml,v 1.3 1997/04/05 06:50:42 morgan Exp morgan $ + $Id: pam_pwdb.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ - This file was written by Andrew G. Morgan <morgan@parc.power.net> + This file was written by Andrew G. Morgan <morgan@kernel.org> --> <sect1>The Password-Database module @@ -16,7 +16,7 @@ pam_pwdb <tag><bf>Author:</bf></tag> Cristian Gafton <gafton@redhat.com> <newline> -and Andrew G. Morgan <morgan@parc.power.net> +and Andrew G. Morgan <morgan@kernel.org> <tag><bf>Maintainer:</bf></tag> Authors. @@ -44,8 +44,8 @@ This module is a pluggable replacement for the <tt/pam_unix_../ modules. It uses the generic interface of the <em/Password Database/ library <tt><htmlurl -url="http://parc.power.net/morgan/libpwdb/index.html" -name="http://parc.power.net/morgan/libpwdb/index.html"></tt>. +url="http://linux.kernel.org/morgan/libpwdb/index.html" +name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>. <sect2>Account component @@ -101,7 +101,8 @@ login account required pam_pwdb.so <tt/use_first_pass/; <tt/try_first_pass/; <tt/nullok/; -<tt/nodelay/ +<tt/nodelay/; +<tt/likeauth/ <tag><bf>Description:</bf></tag> @@ -141,6 +142,12 @@ it. It is called transparently on behalf of the user by the authenticating component of this module. In this way it is possible for applications like <em>xlock</em> to work without being setuid-root. +<p> +The <tt>likeauth</tt> argument makes the module return the same value +when called as a credential setting module and an authentication +module. This will help libpam take a sane path through the auth +component of your configuration file. + <tag><bf>Examples/suggested usage:</bf></tag> The correct functionality of this module is dictated by having an diff --git a/contrib/libpam/doc/modules/pam_radius.sgml b/contrib/libpam/doc/modules/pam_radius.sgml index 4d5f39ab3422..8ebfa0a83592 100644 --- a/contrib/libpam/doc/modules/pam_radius.sgml +++ b/contrib/libpam/doc/modules/pam_radius.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_radius.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_radius.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ This file was written by Cristian Gafton <gafton@redhat.com> --> @@ -44,7 +44,7 @@ yes; this is a network module (independent of application). <p> This module is intended to provide the session service for users -autheticated with a RADIUS server. At the present stage, the only +authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an accounting server. @@ -60,7 +60,7 @@ server. <tag><bf>Description:</bf></tag> This module is intended to provide the session service for users -autheticated with a RADIUS server. At the present stage, the only +authenticated with a RADIUS server. At the present stage, the only option supported is the use of the RADIUS server as an <em/accounting/ server. diff --git a/contrib/libpam/doc/modules/pam_rhosts.sgml b/contrib/libpam/doc/modules/pam_rhosts.sgml index 91001022a2b0..520dd4271b88 100644 --- a/contrib/libpam/doc/modules/pam_rhosts.sgml +++ b/contrib/libpam/doc/modules/pam_rhosts.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_rhosts.sgml,v 1.4 1997/04/05 06:50:42 morgan Exp $ + $Id: pam_rhosts.sgml,v 1.1.1.1 2000/06/20 22:11:04 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> @@ -81,7 +81,8 @@ of independently probing the network connection for such information. <p> In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is -<em/ignored/. Instead, the superuser must have a correctly configured +<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option +should be used. Instead, the superuser must have a correctly configured personal configuration file. <p> @@ -103,6 +104,12 @@ fix this!) ignore the contents of the <tt>/etc/hosts.equiv</tt> file. <item> +<tt/hosts_equiv_rootok/ - +allow the use of <tt>/etc/hosts.equiv</tt> for superuser. Without this +option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account. +This option has no effect if the <tt>no_hosts_equiv</tt> option is used. + +<item> <tt/no_rhosts/ - ignore the contents of all user's personal configuration file <tt>~/.rhosts</tt>. diff --git a/contrib/libpam/doc/modules/pam_rootok.sgml b/contrib/libpam/doc/modules/pam_rootok.sgml index ff6aa86e34da..f7a7259c7652 100644 --- a/contrib/libpam/doc/modules/pam_rootok.sgml +++ b/contrib/libpam/doc/modules/pam_rootok.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_rootok.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_rootok.sgml,v 1.1.1.1 2000/06/20 22:11:04 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> diff --git a/contrib/libpam/doc/modules/pam_securetty.sgml b/contrib/libpam/doc/modules/pam_securetty.sgml index 276ae90435c2..fc89af23460a 100644 --- a/contrib/libpam/doc/modules/pam_securetty.sgml +++ b/contrib/libpam/doc/modules/pam_securetty.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_securetty.sgml,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: pam_securetty.sgml,v 1.1.1.1 2000/06/20 22:11:04 agmorgan Exp $ This file was written by Michael K. Johnson <johnsonm@redhat.com> --> diff --git a/contrib/libpam/doc/modules/pam_tally.sgml b/contrib/libpam/doc/modules/pam_tally.sgml new file mode 100644 index 000000000000..aca41bbde0f0 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_tally.sgml @@ -0,0 +1,191 @@ +<!-- + + $Id: pam_tally.sgml,v 1.1 2001/02/11 07:52:56 agmorgan Exp $ + + This template file was written by Andrew G. Morgan <morgan@kernel.org> + adapted from text provided by Tim Baverstock. +--> + +<sect1>The login counter (tallying) module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_tally + +<tag><bf>Author[s]:</bf></tag> +Tim Baverstock + +<tag><bf>Maintainer:</bf></tag> + +<tag><bf>Management groups provided:</bf></tag> +auth; account + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +A faillog file (default location /var/log/faillog) + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module maintains a count of attempted accesses, can reset count +on success, can deny access if too many attempts fail. + +<p> +pam_tally comes in two parts: <tt>pam_tally.so</tt> and +<tt>pam_tally</tt>. The former is the PAM module and the latter, a +stand-alone program. <tt>pam_tally</tt> is an (optional) application +which can be used to interrogate and manipulate the counter file. It +can display users' counts, set individual counts, or clear all +counts. Setting artificially high counts may be useful for blocking +users without changing their passwords. For example, one might find it +useful to clear all counts every midnight from a cron job. + +<p> +The counts file is organized as a binary-word array, indexed by +uid. You can probably make sense of it with <tt>od</tt>, if you don't +want to use the supplied appliction. + +<p> +Note, there are some outstanding issues with this module: +<tt>pam_tally</tt> is very dependant on <tt>getpw*()</tt> - a database +of usernames would be much more flexible; the `keep a count of current +logins' bit has been <tt>#ifdef</tt>'d out and you can only reset the +counter on successful authentication, for now. + +<sect3>Generic options accepted by both components +<p> +<itemize> +<item> <tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>): + if something weird happens, such as unable to open the file, how + should the module react? +<item> <tt>file=</tt><em>/where/to/keep/counts</em>: + specify the file location for the counts. + The default location is <tt>/var/log/faillog</tt>. +</itemize> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>); +<tt>file=</tt>/where/to/keep/counts; +<tt>no_magic_root</tt> + +<tag><bf>Description:</bf></tag> + +<p> +The authentication component of this module increments the attempted +login counter. + +<p> +<tag><bf>Examples/suggested usage:</bf></tag> + +<p> +The module argument <tt>no_magic_root</tt> is used to indicate that if +the module is invoked by a user with uid=0, then the counter is +incremented. The sys-admin should use this for daemon-launched +services, like <tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. For user +launched services, like <tt>su</tt>, this argument should be omitted. + +<p> +By way of more explanation, when a process already running as root +tries to access some service, the access is <em>magic</em>, and +bypasses <tt>pam_tally</tt>'s checks: this is handy for <tt>su</tt>ing +from root into an account otherwise blocked. However, for services +like <tt>telnet</tt> or <tt>login</tt>, which always effectively run +from the root account, root (ie everyone) shouldn't be granted this +magic status, and the flag `no_magic_root' should be set in this +situation, as noted in the summary above. + +</descrip> + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt>onerr=</tt>(<tt>succeed</tt>|<tt>fail</tt>); +<tt>file=</tt>/where/to/keep/counts; +<tt>deny=</tt><em>n</em>; +<tt>no_magic_root</tt>; +<tt>even_deny_root_account</tt>; +<tt>reset</tt>; +<tt>no_reset</tt>; +<tt>per_user</tt>; +<tt>no_lock_time</tt> + +<tag><bf>Description:</bf></tag> + +<p> +The account component can deny access and/or reset the attempts +counter. It also checks to make sure that the counts file is a plain +file and not world writable. + +<tag><bf>Examples/suggested usage:</bf></tag> + +<p> +The <tt>deny=</tt><em>n</em> option is used to deny access if tally +for this user exceeds <em>n</em>. The presence of +<tt>deny=</tt><em>n</em> changes the default for +<tt>reset</tt>/<tt>no_reset</tt> to <tt>reset</tt>, unless the user +trying to gain access is root and the <tt>no_magic_root</tt> option +has NOT been specified. + +<p> +The <tt>no_magic_root</tt> option ensures that access attempts by root +DON'T ignore deny. Use this for daemon-based stuff, like +<tt>telnet</tt>/<tt>rsh</tt>/<tt>login</tt>. + +<p> +The <tt>even_deny_root_account</tt> option is used to ensure that the +root account can become unavailable. <bf>Note</bf> that magic root +trying to gain root bypasses this, but normal users can be locked out. + +<p> +The <tt>reset</tt> option instructs the module to reset count to 0 on +successful entry, even for magic root. The <tt>no_reset</tt> option is +used to instruct the module to not reset the count on successful +entry. This is the default unless <tt>deny</tt> exists and the user +attempting access is NOT magic root. + +<p> +If <tt>/var/log/faillog</tt> contains a non-zero <tt>.fail_max</tt> +field for this user then the <tt>per_user</tt> module argument will +ensure that the module uses this value and not the global +<tt>deny=</tt><em>n</em> parameter. + +<p> +The <tt>no_lock_time</tt> option is for ensuring that the module does +not use the <tt>.fail_locktime</tt> field in /var/log/faillog for this +user. + +<p> +Normally, failed attempts to access root will <bf>NOT</bf> cause the +root account to become blocked, to prevent denial-of-service: if your +users aren't given shell accounts and root may only login via +<tt>su</tt> or at the machine console (not +<tt>telnet</tt>/<tt>rsh</tt>, etc), this is safe. If you really want +root to be blocked for some given service, use +<tt>even_deny_root_account</tt>. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_time.sgml b/contrib/libpam/doc/modules/pam_time.sgml index 0b3cddfcb44a..8889c4501dea 100644 --- a/contrib/libpam/doc/modules/pam_time.sgml +++ b/contrib/libpam/doc/modules/pam_time.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_time.sgml,v 1.2 1997/02/15 18:25:44 morgan Exp $ + $Id: pam_time.sgml,v 1.2 2001/03/19 01:46:41 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> @@ -142,7 +142,7 @@ Some examples of rules that can be placed in the <tt>/etc/security/time.conf</tt> configuration file are the following: <descrip> -<tag><tt>login ; tty* & ; !ttyp* ; !root ; !Al0000-2400</tt></tag> +<tag><tt>login ; tty* & !ttyp* ; !root ; !Al0000-2400</tt></tag> all users except for <tt/root/ are denied access to console-login at all times. diff --git a/contrib/libpam/doc/modules/pam_unix.sgml b/contrib/libpam/doc/modules/pam_unix.sgml new file mode 100644 index 000000000000..71cb07e32863 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_unix.sgml @@ -0,0 +1,288 @@ +<!-- + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> + + Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org> +--> + +<sect1>The Unix Password module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_unix + +<tag><bf>Author:</bf></tag> + +<tag><bf>Maintainer:</bf></tag> + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This is the standard Unix authentication module. It uses standard calls +from the system's libraries to retrieve and set account information as +well as authentication. Usually this is obtained from the /etc/passwd +and the /etc/shadow file as well if shadow is enabled. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/audit/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the accounting functions of this module +<tt/syslog(3)/ more information on its actions. (Remaining arguments +supported by the other functions of this module are silently ignored, +but others are logged as errors through <tt/syslog(3)/). The <tt/audit/ +argument causes even more logging. + +Based on the following <tt/shadow/ elements: +<tt/expire/; +<tt/last_change/; +<tt/max_change/; +<tt/min_change/; +<tt/warn_change/, +this module performs the task of establishing the status of the user's +account and password. In the case of the latter, it may offer advice +to the user on changing their password or, through the +<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until +they have established a new password. The entries listed above are +documented in the <em/GNU Libc/ info documents. Should the user's record +not contain one or more of these entries, the corresponding <em/shadow/ +check is not performed. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In its accounting mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Ensure users account and password are still active +# +login account required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/use_first_pass/; +<tt/try_first_pass/; +<tt/nullok/; +<tt/nodelay/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the authentication functions of this +module <tt/syslog(3)/ more information on its actions. The <tt/audit/ +causes even more information to be logged. + +<p> +The default action of this module is to not permit the user access to +a service if their <em/official/ password is blank. The <tt/nullok/ +argument overrides this default. + +<p> +When given the argument <tt/try_first_pass/, before prompting the user +for their password, the module first tries the previous stacked +<tt/auth/-module's password in case that satisfies this module as +well. The argument <tt/use_first_pass/ forces the module to use such a +recalled password and will never prompt the user - if no password is +available or the password is not appropriate, the user will be denied +access. + +<p> +The argument, <tt>nodelay</tt>, can be used to discourage the +authentication component from requesting a delay should the +authentication as a whole fail. The default action is for the module +to request a delay-on-failure of the order of one second. + +<p> +Remaining arguments, supported by the other functions of this module, +are silently ignored. Other arguments are logged as errors through +<tt/syslog(3)/. + +<p> +A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's +password when it is stored in a read protected database. This binary +is very simple and will only check the password of the user invoking +it. It is called transparently on behalf of the user by the +authenticating component of this module. In this way it is possible +for applications like <em>xlock</em> to work without being setuid-root. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The correct functionality of this module is dictated by having an +appropriate <tt>/etc/nsswitch.conf</tt> file, the user +databases specified there dictate the source of the authenticated +user's record. +<p> +In its authentication mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Authenticate the user +# +login auth required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/nullok/; +<tt/not_set_pass/; +<tt/use_authtok/; +<tt/try_first_pass/; +<tt/use_first_pass/; +<tt/md5/; +<tt/bigcrypt/; +<tt/shadow/; +<tt/nis/; +<tt/remember/ + +<tag><bf>Description:</bf></tag> + +This part of the <tt/pam_unix/ module performs the task of updating +the user's password. + +<p> +In the case of conventional unix databases (which store the password +encrypted) the <tt/md5/ argument is used to do the encryption with the +MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. +As an alternative to this, the <tt/bigcrypt/ argument can be used to +encrypt more than the first 8 characters of a password with DEC's +(Digital Equipment Cooperation) `C2' extension to the standard UNIX +<tt/crypt()/ algorithm. + +<p> +The <tt/nullok/ argument is used to permit the changing of a password +<em/from/ an empty one. Without this argument, empty passwords are +treated as account-locking ones. + +<p> +The argument <tt/use_first_pass/ is used to lock the choice of old and +new passwords to that dictated by the previously stacked <tt/password/ +module. The <tt/try_first_pass/ argument is used to avoid the user +having to re-enter an old password when <tt/pam_unix/ follows a module +that possibly shared the user's old password - if this old password is +not correct the user will be prompted for the correct one. The +argument <tt/use_authtok/ is used to <em/force/ this module to set the +new password to the one provided by the previously stacked +<tt/password/ module (this is used in an example of the stacking of +the <em/Cracklib/ module documented above). + +<p> +The <tt/not_set_pass/ argument is used to inform the module that it is +not to pay attention to/make available the old or new passwords from/to +other (stacked) password modules. + +<p> +The <tt/debug/ argument makes the password functions of this module +<tt/syslog(3)/ more information on its actions. Other arguments may be +logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes +even more information to be logged. + +<p> +With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC +for setting new passwords. + +<p> +The <tt/remember/ argument takes one value. This is the number of most +recent passwords to save for each user. These are saved in +<tt>/etc/security/opasswd</tt> in order to force password change history +and keep the user from alternating between the same password too frequently. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Standard usage: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_unix.so +</verb> +</tscreen> + +<p> +An example of the stacking of this module with respect to the +pluggable password checking module, <tt/pam_cracklib/: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_cracklib.so retry=3 minlen=6 difok=3 +passwd password required pam_unix.so use_authtok nullok md5 +</verb> +</tscreen> + +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No arguments are recognized by this module component. Its action is +simply to log the username and the service-type to +<tt/syslog(3)/. Messages are logged at the beginning and end of the +user's session. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of the session modules is straightforward: +<tscreen> +<verb> +# +# session opening and closing +# +login session required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_userdb.sgml b/contrib/libpam/doc/modules/pam_userdb.sgml new file mode 100644 index 000000000000..bdbf80b821d0 --- /dev/null +++ b/contrib/libpam/doc/modules/pam_userdb.sgml @@ -0,0 +1,112 @@ +<!-- + This file was written by Cristian Gafton <gafton@redhat.com> +--> + +<sect1>The userdb module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_userdb/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires Berkeley DB. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Look up users in a .db database and verify their password against +what is contained in that database. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/icase/; +<tt/dump/; +<tt/db=XXXX/; + +<tag><bf>Description:</bf></tag> + +This module is used to verify a username/password pair against values stored in +a Berkeley DB database. The database is indexed by the username, and the data +fields corresponding to the username keys are the passwords, in unencrypted form, +so caution must be exercised over the access rights to the DB database itself.. + +The module will read the password from the user using the conversation mechanism. If +you are using this module on top of another authetication module (like <tt/pam_pwdb/;) +then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module. + +<p> +The action of the module may be modified from this default by one or +more of the following flags in the <tt>/etc/pam.d/<service></tt> file. +<itemize> +<item> +<tt/debug/ - +Supply more debugging information to <tt/syslog(3)/. + +<item> +<tt/icase/ - +Perform the password comparisons case insensitive. + +<item> +<tt/dump/ - +dump all the entries in the database to the log (eek, +don't do this by default!) + +<item> +<tt/db=XXXX/ - +use the database found on pathname XXXX. Note that Berkeley DB usually adds the +needed filename extension for you, so you should use something like <tt>/etc/foodata</tt> +instead of <tt>/etc/foodata.db</tt>. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> +on most systems) that will accept for login users whose username/password pairs are +provided in the <tt>/tmp/dbtest.db</tt> file: + +<tscreen> +<verb> +#%PAM-1.0 +auth required pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed +auth sufficient pam_userdb.so icase db=/tmp/dbtest +auth required pam_pwdb.so shadow nullok try_first_pass +auth required pam_shells.so +account required pam_pwdb.so +session required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/contrib/libpam/doc/modules/pam_warn.sgml b/contrib/libpam/doc/modules/pam_warn.sgml index 6e81f187f694..af01740c2f98 100644 --- a/contrib/libpam/doc/modules/pam_warn.sgml +++ b/contrib/libpam/doc/modules/pam_warn.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_warn.sgml,v 1.1 1996/11/30 20:59:32 morgan Exp $ + $Id: pam_warn.sgml,v 1.1.1.1 2000/06/20 22:11:05 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> --> diff --git a/contrib/libpam/doc/modules/pam_wheel.sgml b/contrib/libpam/doc/modules/pam_wheel.sgml index 9139695fec84..bf19a9bab808 100644 --- a/contrib/libpam/doc/modules/pam_wheel.sgml +++ b/contrib/libpam/doc/modules/pam_wheel.sgml @@ -1,5 +1,5 @@ <!-- - $Id: pam_wheel.sgml,v 1.3 1997/02/15 18:25:44 morgan Exp morgan $ + $Id: pam_wheel.sgml,v 1.1.1.1 2000/06/20 22:11:05 agmorgan Exp $ This file was written by Andrew G. Morgan <morgan@parc.power.net> from notes provided by Cristian Gafton. @@ -56,10 +56,11 @@ Only permit root access to members of the wheel (<tt/gid=0/) group. <tag><bf>Description:</bf></tag> -This module is used to enforce the so-called wheel group. By default, -it permits root access to the system if the applicant user is a member -of the <tt/wheel/ group (better described as the group with group-id -<tt/0/). +This module is used to enforce the so-called <em/wheel/ group. By +default, it permits root access to the system if the applicant user is +a member of the <tt/wheel/ group (first, the module checks for the +existence of a '<tt/wheel/' group. Otherwise the module defines the +group with group-id <tt/0/ to be the <em/wheel/ group). <p> The action of the module may be modified from this default by one or @@ -70,7 +71,7 @@ more of the following flags in the <tt>/etc/pam.conf</tt> file. Supply more debugging information to <tt/syslog(3)/. <item> -<tt/use_id/ - +<tt/use_uid/ - This option modifies the behavior of the module by using the current <tt/uid/ of the process and not the <tt/getlogin(3)/ name of the user. This option is useful for being able to jump from one account to diff --git a/contrib/libpam/doc/pam_appl.sgml b/contrib/libpam/doc/pam_appl.sgml index 7c4170ae47ba..c32ee136b438 100644 --- a/contrib/libpam/doc/pam_appl.sgml +++ b/contrib/libpam/doc/pam_appl.sgml @@ -2,9 +2,9 @@ <!-- - $Id: pam_appl.sgml,v 1.16 1997/04/05 06:49:14 morgan Exp morgan $ + $Id: pam_appl.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $ - Copyright (C) Andrew G. Morgan 1996, 1997. All rights reserved. + Copyright (C) Andrew G. Morgan 1996-2001. All rights reserved. Redistribution and use in source (sgml) and binary (derived) forms, with or without modification, are permitted provided that the @@ -45,8 +45,8 @@ DAMAGE. <article> <title>The Linux-PAM Application Developers' Guide -<author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> -<date>DRAFT v0.63 1998/1/18 +<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> +<date>DRAFT v0.75 2001/03/18 <abstract> This manual documents what an application developer needs to know about the <bf>Linux-PAM</bf> library. It describes how an application @@ -71,7 +71,7 @@ information: <verb> #include <security/pam_appl.h> -cc -o application .... -lpam +cc -o application .... -lpam -ldl </verb> </tscreen> @@ -85,7 +85,7 @@ specific to the Linux-PAM distribution): ... #include <security/pam_misc.h> -cc -o application .... -lpam -lpam_misc +cc -o application .... -lpam -lpam_misc -ldl </verb> </tscreen> @@ -130,7 +130,7 @@ 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 +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. @@ -179,7 +179,7 @@ provided in a later section. For example, the conversation function may be called by the PAM library with a request to prompt the user for a password. Its job is to reformat the prompt request into a form that the client will -understand. In the case of <tt>ftpd</tt>, this will involve prefixing +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 @@ -218,9 +218,9 @@ PAM is also capable of setting and deleting the users credentials with the call <tt>pam_setcred()</tt>. This function should always be called after the user is authenticated and before service is offered to the user. By convention, this should be the last call to the PAM -library before service is given to the user. What exactly a -credential is, is not well defined. However, some examples are given -in the glossary below. +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> @@ -233,7 +233,7 @@ some guiding remarks for programmers. <sect1>What can be expected by the application <p> -Here we document those functions in the <bf/Linux-PAM/ library that +Below we document those functions in the <bf/Linux-PAM/ library that may be called from an application. <sect2>Initialization of Linux-PAM @@ -288,12 +288,16 @@ to cause a segmentation fault if accessed). <p> Under normal conditions the argument <tt/pam_status/ has the value -PAM_SUCCESS, but in the event of an unsuccessful service application -the approprite <bf/Linux-PAM/ error-return value should be used -here. -attempt its purpose is to be passed as an argument to the -module specific function <tt/cleanup()/ (see the <bf/Linux-PAM/ -<htmlurl url="pam_modules.html" name="Module Developers' Guide">). +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"> @@ -316,33 +320,41 @@ extern int pam_set_item(pam_handle_t *pamh, int item_type, <tag><tt/PAM_USER/</tag> The user name +<tag><tt/PAM_USER_PROMPT/</tag> + The string used when prompting for a user's name. The default +value for this string is ``Please enter username: ''. + <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 user's username + <tag><tt/PAM_RHOST/</tag> - The remote host name + The requesting hostname (the hostname of the machine from which + the <tt/PAM_RUSER/ is requesting service) <tag><tt/PAM_CONV/</tag> The conversation structure (see section <ref id="the-conversation-function" name="below">) -<tag><tt/PAM_RUSER/</tag> - The remote user name - -<tag><tt/PAM_USER_PROMPT/</tag> - The string used when prompting for a user's name. The default -value for this string is ``Please enter username: ''. +<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/, <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">). +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, @@ -350,13 +362,17 @@ 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> An attempt was made to replace the conversation structure with -a <tt/NULL/ value. + a <tt/NULL/ value. <tag><tt/PAM_BUF_ERR/</tag> The function ran out of memory making a copy of the item. <tag><tt/PAM_BAD_ITEM/</tag> - The application attempted to set an undefined item. + The application attempted to set an undefined or inaccessible + item. </descrip> <sect2>Getting PAM items @@ -375,9 +391,31 @@ This function is used to obtain the value of the indicated <tt/item_type/. Upon successful return, <tt/*item/ contains a pointer to the value of the corresponding item. Note, this is a pointer to the <em/actual/ data and should <em/not/ be <tt/free()/'ed or -over-written! A successful call is signaled by a return value of -<tt/PAM_SUCCESS/. If an attempt is made to get an undefined item, -<tt/PAM_BAD_ITEM/ is returned. +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"> @@ -395,6 +433,7 @@ 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> @@ -410,9 +449,9 @@ is returned to the application. When using this function the application programmer should check if it is available with, <tscreen> <verb> -#ifdef HAVE_PAM_FAIL_DELAY +#ifdef PAM_FAIL_DELAY .... -#endif /* HAVE_PAM_FAIL_DELAY */ +#endif /* PAM_FAIL_DELAY */ </verb> </tscreen> @@ -420,14 +459,14 @@ application programmer should check if it is available with, <p> Generally, an application requests that a user is authenticated by <bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or -<tt/pam_chauthtok()/. These functions calls each of the <em/stacked/ -authentication modules listed in the <tt>/etc/pam.conf</tt> file. As -directed by this file, one of more of the modules may fail causing the -<tt/pam_...()/ call to return an error. It is desirable for there to -also be a pause before the application continues. The principal reason -for such a delay is security: a delay acts to discourage <em/brute -force/ dictionary attacks primarily, but also helps hinder -<em/timed/ (covert channel) attacks. +<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 @@ -441,6 +480,34 @@ randomly distributed (by up to 25%) about this longest value. 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> @@ -502,7 +569,7 @@ extern int pam_setcred(pam_handle_t *pamh, int flags); <p> This function is used to set the module-specific credentials of the user. It is usually called after the user has been authenticated, -after the account management function has been called and after a +after the account management function has been called but before a session has been opened for the user. <p> @@ -583,7 +650,7 @@ this. In such cases, the user should be denied access until such time as they can update their password. <tag><tt/PAM_ACCT_EXPIRED/</tag> - The user is no longer permitted access to the system. + The user is no longer permitted to access the system. <tag><tt/PAM_AUTH_ERR/</tag> There was an authentication error. @@ -667,7 +734,7 @@ extern int pam_open_session(pam_handle_t *pamh, int flags); <p> This function is used to indicate that an authenticated session has -begun. It is used to inform the module that the user is currently in +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 @@ -694,14 +761,15 @@ extern int pam_close_session(pam_handle_t *pamh, int flags); <p> This function is used to indicate that an authenticated session has -ended. It is used to inform the module that the user is exiting a +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> -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/. +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 @@ -718,14 +786,6 @@ extern int pam_putenv(pam_handle_t *pamh, const char *name_value); </tscreen> <p> -<em> -Warning, the environment support in <bf/Linux-PAM/ is based solely -on a six line email from the developers at Sun. Its interface is -likely to be generally correct, however, the details are likely to be -changed as more information becomes available. -</em> - -<p> This function attempts to (re)set a <bf/Linux-PAM/ environment variable. The <tt/name_value/ argument is a single <tt/NUL/ terminated string of one of the following forms: @@ -746,7 +806,7 @@ setting. <tag>``<tt/NAME/''</tag> Without an `<tt/=/' the <tt/pam_putenv()/ function will delete the -correspoding variable from the <bf/Linux-PAM/ environment. +corresponding variable from the <bf/Linux-PAM/ environment. </descrip> @@ -927,7 +987,7 @@ to display some text. <p> Post Linux-PAM-0.59 (and in the interests of compatibility with -Sunsoft). The number of resposes is always equal to the <tt/num_msg/ +Sunsoft). 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 @@ -969,6 +1029,13 @@ 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 @@ -994,17 +1061,17 @@ library, or copy the structure contents to some safe area of memory before passing control to the <bf/Linux-PAM/ library. <p> -Two function classes that fall into this category are +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 <tt>/etc/pam.conf</tt> file, the application programmer should -<bf/avoid/ the temptation of choosing something related to +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 -- this should not be +application on a system under a different name and this should not be permitted to cause a security breach. <p> @@ -1019,14 +1086,14 @@ ln -s /target/application ./preferred_name and then <em/run/ <tt>./preferred_name</tt> <p> -By studying the <bf/Linux-PAM/ configuration file, -<tt>/etc/pam.conf</tt>, an attacker can choose the <tt/preferred_name/ -to be that of a service enjoying minimal protection; for example a -game which uses <bf/Linux-PAM/ to restrict access to certain hours of -the day. If the service-name were to be linked to the filename under -which the service was invoked, it is clear that the user is -effectively in the position of dictating which authentication scheme -the service uses. Needless to say, this is not a secure situation. +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 @@ -1051,16 +1118,40 @@ identity of the user once the service is granted. <p> The need for keeping tabs on these identities is clearly an issue of -security. Basically, the identity of the user requesting a service -should be the current <tt/uid/ (userid) of the running process; the -identity of the privilege granting user is the <tt/euid/ (effective -userid) of the running process; the identity of the user, under whose -name the service will be executed, is given by the contents of the -<tt/PAM_USER/ <tt/pam_get_item(2)/. - -<p> -In addition the identity of a remote user, requesting the service from -a distant location, will be placed in the <tt/PAM_RUSER/ item. +security. One convention that is actively used by some modules is +that the identity of the user requesting a service should be the +current <tt/uid/ (userid) of the running process; the identity of the +privilege granting user is the <tt/euid/ (effective userid) of the +running process; the identity of the user, under whose name the +service will be executed, is given by the contents of the +<tt/PAM_USER/ <tt/pam_get_item(3)/. + +<p> +For network-serving databases and other applications that provide +their own security model (independent of the OS kernel) the above +scheme is insufficient to identify the requesting user. + +<p> +A more portable solution to storing the identity of the requesting +user is to use the <tt/PAM_RUSER/ <tt/pam_get_item(3)/. The +application should supply this value before attempting to authenticate +the user with <tt/pam_authenticate()/. How well this name can be +trusted will ultimately be at the discretion of the local +administrator (who configures PAM for your application) and a selected +module may attempt to override the value where it can obtain more +reliable data. If an application is unable to determine the identity +of the requesting entity/user, it should not call <tt/pam_set_item(3)/ +to set <tt/PAM_RUSER/. + +<p> +In addition to the <tt/PAM_RUSER/ item, the application should supply +the <tt/PAM_RHOST/ (<em/requesting host/) item. As a general rule, the +following convention for its value can be assumed: <tt/<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 @@ -1072,6 +1163,13 @@ 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"> @@ -1242,7 +1340,7 @@ The following is extracted from an email. I'll tidy it up later. <p> The point of PAM is that the application is not supposed to have any -idea how the attatched authentication modules will choose to +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. @@ -1256,10 +1354,10 @@ point is that the retinal scanner is an ideal task for a "module". <p> While it is true that a pop-daemon program is designed with the POP -protocol in mind and no-one ever considered attatching a retinal +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 attatched to it. The point being that the "standard" +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 @@ -1280,7 +1378,7 @@ of the authentication procedure (how many passwords etc..) the exchange protocol (prefixes to prompts etc., numbers like 331 in the case of ftpd) and what is part of the service that the application delivers. PAM really needs to have total control in the -authentication "proceedure", the conversation function should only +authentication "procedure", the conversation function should only deal with reformatting user prompts and extracting responses from raw input. @@ -1459,30 +1557,41 @@ This document was written by Andrew G. Morgan <!-- insert credits here --> <!-- an sgml list of people to credit for their contributions to Linux-PAM - $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $ + $Id: pam_appl.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $ --> +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, @@ -1495,7 +1604,6 @@ 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 @@ -1512,7 +1620,7 @@ credited for all the good work they have done. <sect>Copyright information for this document <p> -Copyright (c) Andrew G. Morgan 1996, 1997. All rights reserved. +Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. <newline> Email: <tt><morgan@transmeta.com></tt> @@ -1562,6 +1670,6 @@ USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <p> -<tt>$Id: pam_appl.sgml,v 1.16 1997/04/05 06:49:14 morgan Exp morgan $</tt> +<tt>$Id: pam_appl.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $</tt> </article> diff --git a/contrib/libpam/doc/pam_modules.sgml b/contrib/libpam/doc/pam_modules.sgml index 418b09beafd3..609916c4470d 100644 --- a/contrib/libpam/doc/pam_modules.sgml +++ b/contrib/libpam/doc/pam_modules.sgml @@ -2,9 +2,9 @@ <!-- - $Id: pam_modules.sgml,v 1.19 1997/04/05 06:49:14 morgan Exp morgan $ + $Id: pam_modules.sgml,v 1.6 2001/02/22 04:58:51 agmorgan Exp $ - Copyright (c) Andrew G. Morgan 1996, 1997. All rights reserved. + Copyright (c) Andrew G. Morgan 1996-2001. All rights reserved. ** some sections, in this document, were contributed by other ** authors. They carry individual copyrights. @@ -48,8 +48,8 @@ DAMAGE. <article> <title>The Linux-PAM Module Writers' Guide -<author>Andrew G. Morgan, <tt>morgan@transmeta.com</tt> -<date>DRAFT v0.59 1997/10/17 +<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> +<date>DRAFT v0.75 2001/02/21 <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 @@ -68,7 +68,7 @@ programmer. #include <security/pam_modules.h> gcc -fPIC -c pam_module-name.c -ld -x --shared -o pam_module-name.so pam_module-name.o -lpam +ld -x --shared -o pam_module-name.so pam_module-name.o </verb> </tscreen> @@ -122,13 +122,11 @@ Setting data 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) - ); +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> @@ -159,16 +157,15 @@ module may choose to delete the ticket file (<em/authentication failure/) or leave it in place. <p> -(*This paragraph is currently under advisement with Sun*) The -<tt/error_status/ may have been logically OR'd with either of the +The <tt/error_status/ may have been logically OR'd with either of the following two values: <p> <descrip> <tag><tt/PAM_DATA_REPLACE/</tag> When a data item is being replaced (through a second call to -<tt/pam_set_data()/) this mask is used is used. Otherwise, the call is -assumed to be from <tt/pam_end()/. +<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 @@ -185,10 +182,9 @@ Getting data Synopsis: <tscreen> <verb> -extern int pam_get_data(const pam_handle_t *pamh - , const char *module_data_name - , const void **data - ); +extern int pam_get_data(const pam_handle_t *pamh, + const char *module_data_name, + const void **data); </verb> </tscreen> @@ -211,10 +207,9 @@ Setting items Synopsis: <tscreen> <verb> -extern int pam_set_item(pam_handle_t *pamh - , int item_type - , const void *item - ); +extern int pam_set_item(pam_handle_t *pamh, + int item_type, + const void *item); </verb> </tscreen> @@ -231,8 +226,8 @@ following two <tt/item_type/s: <descrip> <tag><tt/PAM_AUTHTOK/</tag> -The authentication token (password). This token should be ignored by -all module functions besides <tt/pam_sm_authenticate()/ and +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 @@ -262,10 +257,9 @@ Getting items Synopsis: <tscreen> <verb> -extern int pam_get_item(const pam_handle_t *pamh - , int item_type - , const void **item - ); +extern int pam_get_item(const pam_handle_t *pamh, + int item_type, + const void **item); </verb> </tscreen> @@ -346,10 +340,9 @@ The return values for this function are listed in the Synopsis: <tscreen> <verb> -extern int pam_get_user(pam_handle_t *pamh - , const char **user - , const char *prompt - ); +extern int pam_get_user(pam_handle_t *pamh, + const char **user, + const char *prompt); </verb> </tscreen> @@ -386,6 +379,27 @@ 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> @@ -397,7 +411,7 @@ extern int pam_putenv(pam_handle_t *pamh, const char *name_value); </tscreen> <p> -<bf/Linux-PAM/ (0.54+) comes equipped with a series of functions for +<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 @@ -515,23 +529,23 @@ is returned to the application. When using this function the module programmer should check if it is available with, <tscreen> <verb> -#ifdef HAVE_PAM_FAIL_DELAY +#ifdef PAM_FAIL_DELAY .... -#endif /* HAVE_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 calls each of the <em/stacked/ -authentication modules listed in the <tt>/etc/pam.conf</tt> file. As -directed by this file, one of more of the modules may fail causing the -<tt/pam_...()/ call to return an error. It is desirable for there to -also be a pause before the application continues. The principal reason -for such a delay is security: a delay acts to discourage <em/brute -force/ dictionary attacks primarily, but also helps hinder -<em/timed/ (covert channel) attacks. +<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 @@ -677,8 +691,9 @@ This function performs the task of altering the credentials of the user with respect to the corresponding authorization scheme. Generally, an authentication module may have access to more information about a user than their authentication token. This -function is used to append such information to the application. It -should only be called <em/after/ the user has been authenticated. +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 @@ -696,6 +711,28 @@ Permitted flags, one of which, may be logically OR'd with </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: @@ -710,6 +747,11 @@ errors: 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 @@ -953,6 +995,20 @@ 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 @@ -1238,13 +1294,22 @@ endif For some further examples, see the <tt>modules</tt> subdirectory of the current <bf/Linux-PAM/ distribution. -<p> <sect>An example module file <p> -<em> -perhaps this should point to a place in the file structure!? -</em> +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/cvsweb.cgi/Linux-PAM/modules/pam_permit/?cvsroot=pam" +name="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/Linux-PAM/modules/pam_permit/?cvsroot=pam" +></tt> +<item> A module that always fails: <tt><htmlurl +url="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/Linux-PAM/modules/pam_deny/?cvsroot=pam" +name="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/Linux-PAM/modules/pam_deny/?cvsroot=pam" +></tt> +</itemize> <sect>Files @@ -1314,33 +1379,41 @@ This document was written by Andrew G. Morgan <!-- insert credits here --> <!-- an sgml list of people to credit for their contributions to Linux-PAM + $Id: pam_modules.sgml,v 1.6 2001/02/22 04:58:51 agmorgan Exp $ --> -<!-- - an sgml list of people to credit for their contributions to Linux-PAM - $Id: CREDITS,v 1.4 1997/04/05 06:47:26 morgan Exp morgan $ - --> +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, @@ -1420,6 +1493,6 @@ USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <p> -<tt>$Id: pam_modules.sgml,v 1.19 1997/04/05 06:49:14 morgan Exp morgan $</tt> +<tt>$Id: pam_modules.sgml,v 1.6 2001/02/22 04:58:51 agmorgan Exp $</tt> </article> diff --git a/contrib/libpam/doc/pam_source.sgml b/contrib/libpam/doc/pam_source.sgml index 093998a0aad1..5e4be447bb32 100644 --- a/contrib/libpam/doc/pam_source.sgml +++ b/contrib/libpam/doc/pam_source.sgml @@ -2,9 +2,9 @@ <!-- - $Id: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $ + $Id: pam_source.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $ - Copyright (c) Andrew G. Morgan 1996,1997. All rights reserved. + Copyright (c) Andrew G. Morgan 1996-2001. All rights reserved. Redistribution and use in source (sgml) and binary (derived) forms, with or without modification, are permitted provided that the @@ -45,8 +45,8 @@ DAMAGE. <article> <title>The Linux-PAM System Administrators' Guide -<author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> -<date>DRAFT v0.59 1998/1/7 +<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> +<date>DRAFT v0.75 2001/03/18 <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 @@ -140,10 +140,10 @@ command shell (<em>bash, tcsh, zsh, etc.</em>) running with the identity of the user. <p> -Traditinally, the former step is achieved by the <em/login/ +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 the -so far as the system is concerned the user is who they claim to be. +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> @@ -215,12 +215,122 @@ configured authentication method. The <bf/Linux-PAM/ library (in the center) consults the contents of the PAM configuration file and loads the modules that are appropriate for application-X. These modules fall into one of four management groups (lower-center) and are stacked in -the order they appear in the configuaration file. These modules, when +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"> @@ -363,9 +473,13 @@ is not deemed as fatal to satisfying the application that this <item> <tt/optional/; as its name suggests, this <tt/control-flag/ marks the module as not being critical to the success or failure of -the user's application for service. However, in the absence of any -successes of previous or subsequent stacked modules this module will -determine the nature of the response to the application. +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> @@ -392,12 +506,12 @@ Here, <tt/valueI/ is one of the following <em/return values/: <tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/; <tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and <tt/default/. The last of these (<tt/default/) can be used to set the -action for those return values that are not set explicitly. +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 +<tt/reset/. A positive integer, <tt/J/, when specified as the action, can be used to indicate that the next <em/J/ modules of the current type will be skipped. In this way, the administrator can develop a moderately sophisticated stack of modules with a number of different @@ -405,9 +519,41 @@ paths of execution. Which path is taken can be determined by the reactions of individual modules. <p> -<bf>Note, at time of writing, this newer syntax is so new that I don't -want to write too much about it. Please play with this. Report all -the bugs and make suggestions for new actions (etc.).</bf> +<itemize> +<item><tt/ignore/ - when used with a stack of modules, the module's + return status will not contribute to the return code the application + obtains. +<item><tt/bad/ - this action indicates that the return code should be + thought of as indicative of the module failing. If this module is + the first in the stack to fail, its status value will be used for + that of the whole stack. +<item><tt/die/ - equivalent to <tt/bad/ with the side effect of + terminating the module stack and PAM immediately returning to the + application. +<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this + return code should contribute directly to the return code of the full + stack of modules. In other words, if the former state of the stack + would lead to a return of <tt/PAM_SUCCESS/, the module's return code + will override this value. Note, if the former state of the stack + holds some value that is indicative of a modules failure, this 'ok' + value will not be used to override that value. +<item><tt/done/ - equivalent to <tt/ok/ with the side effect of + terminating the module stack and PAM immediately returning to the + application. +<item><tt/reset/ - clear all memory of the state of the module stack and + start again with the next stacked module. +</itemize> + +<p> +Just to get a feel for the power of this new syntax, here is a taste +of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of +client plug-in agents was introduced. This is something that makes it +possible for PAM to support machine-machine authentication using the +transport protocol inherent to the client/server application. With +the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible +for an application to be configured to support binary prompts with +compliant clients, but to gracefully fall over into an alternative +authentication mode for older, legacy, applications. Flexible eh? <tag> <tt/module-path/</tag> @@ -431,7 +577,7 @@ next section. </descrip> <p> -Any line in (one of) the confiuration file(s), that is not formatted +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)/. @@ -453,10 +599,10 @@ configuration but not both. That is to say, if there is a <tt>/etc/pam.d/</tt> directory then libpam only uses the files contained in this directory. However, in the absence of the <tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is -used. The other mode (and the one currently supported by Red Hat 4.2) -is to use both <tt>/etc/pam.d/</tt> and <tt>/etc/pam.conf</tt> in -sequence. In this mode, entries in <tt>/etc/pam.d/</tt> override -those of <tt>/etc/pam.conf</tt>. +used. The other mode (and the one currently supported by Red Hat 4.2 +and higher) is to use both <tt>/etc/pam.d/</tt> and +<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in +<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>. The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of the <tt>/etc/pam.conf</tt> file and is made up of lines of the @@ -560,6 +706,20 @@ 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 @@ -681,17 +841,6 @@ module-argument, this instructs the UNIX authentication module that it is not to prompt for a password but rely one already having been obtained by the ftp module. -<p> -The standard UNIX modules, used above, are strongly tied to using the -default `<tt/libc/' user database functions (see for example, <tt/man -getpwent/). It is the opinion of the author that these functions are -not sufficently flexible to make full use of the power of -<bf/Linux-PAM/. For this reason, and as a small plug, I mention in -passing that there is a pluggable replacement for the <tt/pam_unix_../ -modules; <tt/pam_pwdb/. See the section below for a more complete -description. - - <sect>Security issues of Linux-PAM <p> @@ -801,6 +950,28 @@ 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> @@ -847,8 +1018,8 @@ files; the modules. PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request For Comments 86.0, October 1995. See this url: <tt><htmlurl -url="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt" -name="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt"></tt> +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> @@ -875,37 +1046,9 @@ and in such a way that they need not be distributed with Linux-PAM. <sect>Author/acknowledgments <p> -This document was written by Andrew G. Morgan (morgan@parc.power.net) +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: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $ - --> -Craig S. Bell, -Derrick J. Brashear, -Ben Buxton, -Oliver Crow, -Marc Ewing, -Cristian Gafton, -Eric Hester, -Eric Jacksch, -Michael K. Johnson, -David Kinchlea, -Elliot Lee, -Al Longyear, -Marek Michalkiewicz, -Aleph One, -Sean Reifschneider, -Eric Troan, -Theodore Ts'o, -Jeff Uphoff, -Ronald Wahl, -John Wilmes, -Joseph S. D. Yao -and -Alex O. Yuriev. - +<!-- insert-file CREDITS --> <p> Thanks are also due to Sun Microsystems, especially to Vipin Samar and @@ -921,18 +1064,15 @@ More PAM modules are being developed all the time. It is unlikely that this document will ever be truely up to date! <p> -Currently there is no documentation for PAM-aware applications. - -<p> This manual is unfinished. Only a partial list of people is credited for all the good work they have done. <sect>Copyright information for this document <p> -Copyright (c) Andrew G. Morgan 1996. All rights reserved. +Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. <newline> -Email: <tt><morgan@parc.power.net></tt> +Email: <tt><morgan@linux.kernel.org></tt> <p> Redistribution and use in source and binary forms, with or without @@ -980,6 +1120,6 @@ USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <p> -<tt>$Id: pam_source.sgml,v 1.5 1997/04/05 06:49:14 morgan Exp morgan $</tt> +<tt>$Id: pam_source.sgml,v 1.5 2001/03/19 01:46:41 agmorgan Exp $</tt> </article> diff --git a/contrib/libpam/doc/ps/README b/contrib/libpam/doc/ps/README index 6234e14f8f8e..5b24f9b52b3a 100644 --- a/contrib/libpam/doc/ps/README +++ b/contrib/libpam/doc/ps/README @@ -1,3 +1,3 @@ -$Id: README,v 1.1 1996/11/10 19:28:16 morgan Exp $ +$Id: README,v 1.1.1.1 2000/06/20 22:11:05 agmorgan Exp $ this is the directory for the postscipt documentation diff --git a/contrib/libpam/doc/specs/draft-morgan-pam.raw b/contrib/libpam/doc/specs/draft-morgan-pam.raw new file mode 100644 index 000000000000..dec3e566721d --- /dev/null +++ b/contrib/libpam/doc/specs/draft-morgan-pam.raw @@ -0,0 +1,702 @@ +PAM working group ## A.G. Morgan +Internet Draft: ## October 6, 1999 +Document: draft-morgan-pam-07.txt ## +Expires: June 13, 2000 ## +Obsoletes: draft-morgan-pam-06.txt## + +## Pluggable Authentication Modules ## + +#$ Status of this memo + +This document is an draft specification. The latest version of this +draft may be obtained from here: + + http://linux.kernel.org/pub/linux/libs/pam/pre/doc/ + +As + + Linux-PAM-'version'-docs.tar.gz + +It is also contained in the Linux-PAM tar ball. + +#$ Abstract + +This document is concerned with the definition of a general +infrastructure for module based authentication. The infrastructure is +named Pluggable Authentication Modules (PAM for short). + +#$ Introduction + +Computers are tools. They provide services to people and other +computers (collectively we shall call these _users_ entities). In +order to provide convenient, reliable and individual service to +different entities, it is common for entities to be labelled. Having +defined a label as referring to a some specific entity, the label is +used for the purpose of protecting and allocating data resources. + +All modern operating systems have a notion of labelled entities and +all modern operating systems face a common problem: how to +authenticate the association of a predefined label with applicant +entities. + +There are as many authentication methods as one might care to count. +None of them are perfect and none of them are invulnerable. In +general, any given authentication method becomes weaker over time. It +is common then for new authentication methods to be developed in +response to newly discovered weaknesses in the old authentication +methods. + +The problem with inventing new authentication methods is the fact that +old applications do not support them. This contributes to an inertia +that discourages the overhaul of weakly protected systems. Another +problem is that individuals (people) are frequently powerless to layer +the protective authentication around their systems. They are forced +to rely on single (lowest common denominator) authentication schemes +even in situations where this is far from appropriate. + +PAM, as discussed in this document, is a generalization of the +approach first introduced in [#$R#{OSF_RFC_PAM}]. In short, it is a +general framework of interfaces that abstract the process of +authentication. With PAM, a service provider can custom protect +individual services to the level that they deem is appropriate. + +PAM has nothing explicit to say about transport layer encryption. +Within the context of this document encryption and/or compression of +data exchanges are application specific (strictly between client and +server) and orthogonal to the process of authentication. + +#$ Definitions + +Here we pose the authentication problem as one of configuring defined +interfaces between two entities. + +#$$#{players} Players in the authentication process + +PAM reserves the following words to specify unique entities in the +authentication process: + + applicant + the entity (user) initiating an application for service + [PAM associates the PAM_RUSER _item_ with this requesting user]. + + arbitrator + the entity (user) under whose identity the service application + is negotiated and with whose authority service is granted. + + user + the entity (user) whose identity is being authenticated + [PAM associates the PAM_USER _item_ with this identity]. + + server + the application that provides service, or acts as an + authenticated gateway to the requested service. This + application is completely responsible for the server end of + the transport layer connecting the server to the client. + PAM makes no assumptions about how data is encapsulated for + exchanges between the server and the client, only that full + octet sequences can be freely exchanged without corruption. + + client + application providing the direct/primary interface to + applicant. This application is completely responsible + for the client end of the transport layer connecting the + server to the client. PAM makes no assumptions about how data + is encapsulated for exchanges between the server and the + client, only that full octet sequences can be freely + exchanged without corruption. + + module + authentication binary that provides server-side support for + some (arbitrary) authentication method. + + agent + authentication binary that provides client-side support for + some (arbitrary) authentication method. + +Here is a diagram to help orient the reader: + +## +-------+ +--------+ ## +## . . . . .| agent | .| module | ## +## . +-------+ .+--------+ ## +## V | . | ## +## . | V | ## +## +---------+ +-------+ . +------+ ## +## | | |libpamc| . |libpam| ## +## | | +-------+ . +------+ ## +## |applicant| | . | ## +## | | +--------+ +----------+ ## +## | |---| client |-----------| server | ## +## +---------+ +--------+ +----------+ ## + +Solid lines connecting the boxes represent two-way interaction. The +dotted-directed lines indicate an optional connection beteween the +plugin module (agent) and the server (applicant). In the case of the +module, this represents the module invoking the 'conversation' +callback function provided to libpam by the server application when it +inititializes the libpam library. In the case of the agent, this may +be some out-of-PAM API interaction (for example directly displaying a +dialog box under X). + +#$$ Defined Data Types + +In this draft, we define two composite data types, the text string and +the binary prompt. They are the data types used to communicate +authentication requests and responses. + +#$$$#{text_string} text string + +The text string is a simple sequence of non-NUL (NUL = 0x00) +octets. Terminated with a single NUL (0x00) octet. The character set +employed in the octet sequence may be negotiated out of band, but +defaults to utf-8. + +## --------------------------- ## +## [ character data | NUL ] ## +## [ octet sequence | 0x00 ] ## +## --------------------------- ## + +Within the rest of this text, PAM text strings are delimited with a +pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}. + +#$$$#{binary_prompt} binary prompt + +A binary prompt consists of a stream of octets arranged as follows: + +## ---------------------------------------- ## +## [ u32 | u8 | (length-5 octets) ] ## +## [ length | control | data ] ## +## ---------------------------------------- ## + +That is, a 32-bit unsigned integer in network byte order, a single +unsigned byte of control information and a sequence of octets of +length (length-5). The composition of the _data_ is context dependent +but is generally not a concern for either the server or the client. It +is very much the concern of modules and agents. + +For purposes of interoperability, we define the following control +characters as legal. + +## value symbol description ## +## ------------------------------------------------- ## +## 0x01 PAM_BPC_OK - continuation packet ## +## 0x02 PAM_BPC_SELECT - initialization packet ## +## 0x03 PAM_BPC_DONE - termination packet ## +## 0x04 PAM_BPC_FAIL - unable to execute ## + +The following control characters are only legal for exchanges between +an agent and a client (it is the responsibility of the client to +enforce this rule in the face of a rogue server): + +## 0x41 PAM_BPC_GETENV - obtain client env.var ## +## 0x42 PAM_BPC_PUTENV - set client env.var ## +## 0x43 PAM_BPC_TEXT - display message ## +## 0x44 PAM_BPC_ERROR - display error message ## +## 0x45 PAM_BPC_PROMPT - echo'd text prompt ## +## 0x46 PAM_BPC_PASS - non-echo'd text prompt## + +Note, length is always equal to the total length of the binary +prompt and represented by a network ordered unsigned 32 bit integer. + +#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts + +Binary prompts of control type PAM_BPC_SELECT have a defined +data part. It is composed of three elements: + + {agent_id;'/';data} + +The agent_id is a sequence of characters satisfying the following +regexp: + + /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/ + +and has a specific form for each independent agent. + +o Agent_ids that do not contain an at-sign (@) are reserved to be + assigned by IANA (Internet Assigned Numbers Authority). Names of + this format MUST NOT be used without first registering with IANA. + Registered names MUST NOT contain an at-sign (@). + +o Anyone can define additional agents by using names in the format + name@domainname, e.g. "ouragent@example.com". The part following + the at-sign MUST be a valid fully qualified internet domain name + [RFC-1034] controlled by the person or organization defining the + name. (Said another way, if you control the email address that + your agent has as an identifier, they you are entitled to use + this identifier.) It is up to each domain how it manages its local + namespace. + +The '/' character is a mandatory delimiter, indicating the end of the +agent_id. The trailing data is of a format specific to the agent with +the given agent_id. + + +#$$ Special cases + +In a previous section (#{players}) we identified the most general +selection of authentication participants. In the case of network +authentication, it is straightforward to ascribe identities to the +defined participants. However, there are also special (less general) +cases that we recognize here. + +The primary authentication step, when a user is directly introduced +into a computer system (log's on to a workstation) is a special case. +In this situation, the client and the server are generally one +application. Before authenticating such a user, the applicant is +formally unknown: PAM_RUSER is NULL. + +Some client-server implementations (telnet for example) provide +effective full tty connections. In these cases, the four simple text +string prompting cases (see below) can be handled as in the primary +login step. In other words, the server absorbs most of the overhead of +propagating authentication messages. In these cases, there is special +client/server support for handling binary prompts. + +#$ Defined interfaces for information flow + +Here, we discuss the information exchange interfaces between the +players in the authentication process. It should be understood that +the server side is responsible for driving the authentication of the +applicant. Notably, every request received by the client from the +server must be matched with a single response from the client to the +server. + +#$$#{applicant_client} Applicant <-> client + +Once the client is invoked, requests to the applicant entity are +initiated by the client application. General clients are able to make +the following requests directly to an applicant: + + echo text string + echo error text string + prompt with text string for echo'd text string input + prompt with text string for concealed text string input + +the nature of the interface provided by the client for the benefit of +the applicant entity is client specific and not defined by PAM. + +#$$#{client_agent} Client <-> agent + +In general, authentication schemes require more modes of exchange than +the four defined in the previous section (#{applicant_client}). This +provides a role for client-loadable agents. The client and agent +exchange binary-messages that can have one of the following forms: + + client -> agent + binary prompt agent expecting binary prompt reply to client + + agent -> client + binary prompt reply from agent to clients binary prompt + +Following the acceptance of a binary prompt by the agent, the agent +may attempt to exchange information with the client before returning +its binary prompt reply. Permitted exchanges are binary prompts of the +following types: + + agent -> client + set environment variable (A) + get environment variable (B) + echo text string (C) + echo error text string (D) + prompt for echo'd text string input (E) + prompt for concealed text string input (F) + +In response to these prompts, the client must legitimately respond +with a corresponding binary prompt reply. We list a complete set of +example exchanges, including each type of legitimate response (passes +and a single fail): + +## Type | Agent request | Client response ## +## --------------------------------------------------------------- ## +## (A) | {13;PAM_BPC_PUTENV;"FOO=BAR"} | {5;PAM_BPC_OK;} ## +## | {10;PAM_BPC_PUTENV;"FOO="} | {5;PAM_BPC_OK;} ## +## | {9;PAM_BPC_PUTENV;"FOO"} (*) | {5;PAM_BPC_OK;} ## +## | {9;PAM_BPC_PUTENV;"BAR"} (*) | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (B) | {10;PAM_BPC_GETENV;"TERM"} | {11;PAM_BPC_OK;"vt100"} ## +## | {9;PAM_BPC_GETENV;"FOO"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (C) | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_OK;} ## +## | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (D) | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_OK;} ## +## | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (E) | {13;PAM_BPC_PROMPT;"login: "} | {9;PAM_BPC_OK;"joe"} ## +## | {13;PAM_BPC_PROMPT;"login: "} | {6;PAM_BPC_OK;""} ## +## | {13;PAM_BPC_PROMPT;"login: "} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (F) | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"} ## +## | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""} ## +## | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;} ## + +(*) Used to attempt the removal of a pre-existing environment +variable. + +#$$ Client <-> server + +Once the client has established a connection with the server (the +nature of the transport protocol is not specified by PAM), the server +is responsible for driving the authentication process. + +General servers can request the following from the client: + + (to be forwarded by the client to the applicant) + echo text string + echo error text string + prompt for echo'd text string response + prompt for concealed text string response + + (to be forwarded by the client to the appropriate agent) + binary prompt for a binary prompt response + +Client side agents are required to process binary prompts. The +agents' binary prompt responses are returned to the server. + +#$$ Server <-> module + +Modules drive the authentication process. The server provides a +conversation function with which it encapsulates module-generated +requests and exchanges them with the client. Every message sent by a +module should be acknowledged. + +General conversation functions can support the following five +conversation requests: + + echo text string + echo error string + prompt for echo'd text string response + prompt for concealed text string response + binary prompt for binary prompt response + +The server is responsible for redirecting these requests to the +client. + +#$ C API for application interfaces (client and server) + +#$$ Applicant <-> client + +No API is defined for this interface. The interface is considered to +be specific to the client application. Example applications include +terminal login, (X)windows login, machine file transfer applications. + +All that is important is that the client application is able to +present the applicant with textual output and to receive textual +input from the applicant. The forms of textual exchange are listed +in an earlier section (#{applicant_client}). Other methods of +data input/output are better suited to being handled via an +authentication agent. + +#$$ Client <-> agent + +The client makes use of a general API for communicating with +agents. The client is not required to communicate directly with +available agents, instead a layer of abstraction (in the form of a +library: libpamc) takes care of loading and maintaining communication +with all requested agents. This layer of abstraction will choose which +agents to interact with based on the content of binary prompts it +receives that have the control type PAM_BPC_SELECT. + +#$$$ Client <-> libpamc + +#$$$$ Compilation information + +The C-header file provided for client-agent abstraction is included +with the following source line: + + \#include <security/pam_client.h> + +The library providing the corresponding client-agent abstraction +functions is, libpamc. + + cc .... -lpamc + +#$$$$ Initializing libpamc + +The libpamc library is initialized with a call to the following +function: + + pamc_handle_t pamc_start(void); + +This function is responsible for configuring the library and +registering the location of available agents. The location of the +available agents on the system is implementation specific. + +pamc_start() function returns NULL on failure. Otherwise, the return +value is a pointer to an opaque data type which provides a handle to +the libpamc library. On systems where threading is available, the +libpamc libraray is thread safe provided a single (pamc_handler_t *) +is used by each thread. + +#$$$$ Client (Applicant) selection of agents + +For the purpose of applicant and client review of available agents, +the following function is provided. + + char **pamc_list_agents(pamc_handle_t pch); + +This returns a list of pointers to the agent_id's of the agents which +are available on the system. The list is terminated by a NULL pointer. +It is the clients responsibility to free this memory area by calling +free() on each agent id and the block of agent_id pointers in the +result. + +PAM represents a server-driven authentication model, so by default +any available agent may be invoked in the authentication process. + +#$$$$$ Client demands agent + +If the client requires that a specific authentication agent is +satisfied during the authentication process, then the client should +call the following function, immediately after obtaining a +pamc_handle_t from pamc_start(). + + int pamc_load(pamc_handle_t pch, const char *agent_id); + +agent_id is a PAM text string (see section #{agent_ids}) and is not +suffixed with a '/' delimiter. The return value for this function is: + + PAM_BPC_TRUE - agent located and loaded. + PAM_BPC_FALSE - agent is not available. + +Note, although the agent is loaded, no data is fed to it. The agent's +opportunity to inform the client that it does not trust the server is +when the agent is shutdown. + +#$$$$$ Client marks agent as unusable + +The applicant might prefer that a named agent is marked as not +available. To do this, the client would invoke the following function +immediately after obtaining a pamc_handle_t from pam_start(). + + int pamc_disable(pamc_handle_t pch, const char *agent_id); + +here agent_id is a PAM text string containing an agent_id (section +#{agent_ids}). + +The return value for this function is: + + PAM_BPC_TRUE - agent is disabled. This is the response + independent of whether the agent is locally + available. + + PAM_BPC_FALSE - agent cannot be disabled (this may be because + it has already been invoked). + +#$$$$ Allocating and manipulating binary prompts + +All conversation between an client and an agent takes place with +respect to binary prompts. A binary prompt (see section #{binary_prompt}), is +obtained, resized and deleted via the following C-macro: + + CREATION of a binary prompt with control X1 and data length Y1: + + pamc_bp_t prompt = NULL; + PAM_BP_RENEW(&prompt, X1, Y1); + + REPLACEMENT of a binary prompt with a control X2 and data length Y2: + + PAM_BP_RENEW(&prompt, X2, Y2); + + DELETION of a binary prompt (the referenced prompt is scrubbed): + + PAM_BP_RENEW(&prompt, 0, 0); + +Note, the PAM_BP_RENEW macro always overwrites any prompt that you +call it with, deleting and liberating the old contents in a secure +fashion. Also note that PAM_BP_RENEW, when returning a prompt of data +size Y1>0, will always append a '\0' byte to the end of the prompt (at +data offset Y1). It is thus, by definition, acceptable to treat the +data contents of a binary packet as a text string (see #{text_string}). + + FILLING a binary prompt from a memory pointer U1 from offset O1 of + length L1: + + PAM_BP_FILL(prompt, O1, L1, U1); + + the CONTROL type for the packet can be obtained as follows: + + control = PAM_PB_CONTROL(prompt); + + the LENGTH of a data within the prompt (_excluding_ its header + information) can be obtained as follows: + + length = PAM_BP_LENGTH(prompt); + + the total SIZE of the prompt (_including_ its header information) + can be obtained as follows: + + size = PAM_BP_SIZE(prompt); + + EXTRACTING data from a binary prompt from offset O2 of length L2 to + a memory pointer U2: + + PAM_BP_EXTRACT(prompt, O2, L2, U2); + + If you require direct access to the raw prompt DATA, you should use + the following macro: + + __u8 *raw_data = PAM_BP_DATA(prompt); + +#$$$$ Client<->agent conversations + +All exchanges of binary prompts with agents are handled with the +single function: + + int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p); + +The return value for pamc_converse(...) is PAM_BPC_TRUE when there is +a response packet and PAM_BPC_FALSE when the client is unable to +handle the request represented by the original prompt. In this latter +case, *prompt_p is set to NULL. + +This function takes a binary prompt and returns a replacement binary +prompt that is either a request from an agent to be acted upon by the +client or the 'result' which should be forwarded to the server. In the +former case, the following macro will return 1 (PAM_BPC_TRUE) and in +all other cases, 0 (PAM_BPC_FALSE): + + PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt) + +Note, all non-NULL binary prompts returned by pamc_converse(...), are +terminated with a '\0', even when the full length of the prompt (as +returned by the agent) does not contain this delimiter. This is a +defined property of the PAM_BP_RENEW macro, and can be relied upon. + +Important security note: in certain implementations, agents are +implemented by executable binaries, which are transparently loaded and +managed by the PAM client library. To ensure there is never a leakage +of elevated privilege to an unprivileged agent, the client application +should go to some effort to lower its level of privilege. It remains +the responsibility of the applicant and the client to ensure that it +is not compromised by a rogue agent. + +#$$$$ Termination of agents + +When closing the authentication session and severing the connection +between a client and a selection of agents, the following function is +used: + + int pamc_end(pamc_handle_t *pch); + +Following a call to pamc_end, the pamc_handle_t will be invalid. + +The return value for this function is one of the following: + + PAM_BPC_TRUE - all invoked agents are content with + authentication (the server is _not_ judged + _un_trustworthy by any agent) + + PAM_BPC_FALSE - one or more agents were unsatisfied at + being terminated. In general, the client + should terminate its connection to the + server and indicate to the applicant that + the server is untrusted. + +#$$$ libpamc <-> agents + +The agents are manipulated from within libpamc. Each agent is an +executable in its own right. This permits the agent to have access to +sensitive data not accessible directly from the client. The mode of +communication between libpamc and an agent is through a pair of +pipes. The agent reads binary prompts (section #{binary_prompt}) +through its standard input file descriptor and writes response (to the +server) binary prompts and instruction binary prompts (instructions +for the client) through its standard output file descriptor. + +#$$ Client <-> server + +This interface is concerned with the exchange of text and binary +prompts between the client application and the server application. No +API is provided for this as it is considered specific to the transport +protocol shared by the client and the server. + +#$$ Server <-> modules + +The server makes use of a general API for communicating with +modules. The client is not required to communicate directly with +available modules. By abstracting the authentication interface, it +becomes possible for the local administrator to make a run time +decision about the authentication method adopted by the server. + +#$$$ Functions and definitions available to servers and modules + +[This section will document the following functions + + pam_set_item() + pam_get_item() + pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec) + pam_get_env(pam_handle_t *pamh, const char *varname) + pam_strerror(pam_handle_t *pamh, int pam_errno) +] + +#$$$ Server <-> libpam + +[This section will document the following pam_ calls: + + pam_start + pam_end + pam_authenticate (*) + pam_setcred + pam_acct_mgmt + pam_open_session + pam_close_session + pam_chauthtok (*) + +The asterisked functions may return PAM_INCOMPLETE. In such cases, the +application should be aware that the conversation function was called +and that it returned PAM_CONV_AGAIN to a module. The correct action +for the application to take in response to receiving PAM_INCOMPLETE, +is to acquire the replies so that the next time the conversation +function is called it will be able to provide the desired +responses. And then recall pam_authenticate (pam_chauthtok) with the +same arguments. Libpam will arrange that the module stack is resumed +from the module that returned before. This functionality is required +for programs whose user interface is maintained by an event loop. ] + +#$$$ libpam <-> modules + +[This section will document the following pam_ and pam_sm_ calls: + +functions provided by libpam + + pam_set_data + pam_get_data + +functions provided to libpam by each module + + groups: + AUTHENTICATION + pam_sm_authenticate + pam_sm_setcred + ACCOUNT + pam_sm_acct_mgmt + SESSION + pam_sm_open_session + pam_sm_close_session + AUTHENTICATION TOKEN MANAGEMENT + pam_sm_chauthtok +] + +#$ Security considerations + +This document is devoted to standardizing authentication +infrastructure: everything in this document has implications for +security. + +#$ Contact + +The email list for discussing issues related to this document is +<pam-list@redhat.com>. + +#$ References + +[#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication + Modules (PAM)", October 1995 + +#$ Author's Address + +Andrew G. Morgan +Email: morgan@ftp.kernel.org + +## $Id: draft-morgan-pam.raw,v 1.1.1.1 2000/06/20 22:11:07 agmorgan Exp $ ## + diff --git a/contrib/libpam/doc/txts/README b/contrib/libpam/doc/txts/README index b62bc2d7448a..f63820cffde0 100644 --- a/contrib/libpam/doc/txts/README +++ b/contrib/libpam/doc/txts/README @@ -1,3 +1,3 @@ -$Id: README,v 1.1 1996/11/10 19:18:06 morgan Exp $ +$Id: README,v 1.1.1.1 2000/06/20 22:11:12 agmorgan Exp $ This is a directory for text versions of the pam documentation |