diff options
Diffstat (limited to 'doc')
65 files changed, 12305 insertions, 0 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore new file mode 100644 index 00000000..7ac74f9d --- /dev/null +++ b/doc/.cvsignore @@ -0,0 +1,2 @@ +pam.sgml +MODULES-SGML diff --git a/doc/CREDITS b/doc/CREDITS new file mode 100644 index 00000000..059bb5f2 --- /dev/null +++ b/doc/CREDITS @@ -0,0 +1,48 @@ +<!-- + an sgml list of people to credit for their contributions to Linux-PAM + $Id$ + --> +Chris Adams, +Peter Allgeyer, +Tim Baverstock, +Tim Berger, +Craig S. Bell, +Derrick J. Brashear, +Ben Buxton, +Seth Chaiklin, +Oliver Crow, +Chris Dent, +Marc Ewing, +Cristian Gafton, +Emmanuel Galanos, +Brad M. Garcia, +Eric Hester, +Roger Hu, +Eric Jacksch, +Michael K. Johnson, +David Kinchlea, +Olaf Kirch, +Marcin Korzonek, +Stephen Langasek, +Nicolai Langfeldt, +Elliot Lee, +Luke Kenneth Casson Leighton, +Al Longyear, +Ingo Luetkebohle, +Marek Michalkiewicz, +Robert Milkowski, +Aleph One, +Martin Pool, +Sean Reifschneider, +Jan Rekorajski, +Erik Troan, +Theodore Ts'o, +Jeff Uphoff, +Myles Uyema, +Savochkin Andrey Vladimirovich, +Ronald Wahl, +David Wood, +John Wilmes, +Joseph S. D. Yao +and +Alex O. Yuriev. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..965f24b8 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,101 @@ + +### $Id$ + +TXTER=sgml2txt +HTMLER=sgml2html +# older distributions use, sgml2ps +# newer distributions than the one I use (AGM :^) need the following line: +#PSER=sgml2latex -o ps +# until I upgrade this is the default +PSER=sgml2latex -p + +FILES=pam pam_appl pam_modules +FSRCS=pam.sgml pam_appl.sgml pam_modules.sgml + +TEXTS=txts/pam.txt txts/pam_appl.txt txts/pam_modules.txt +HTMLS=html/pam.html html/pam_appl.html html/pam_modules.html +PSFILES=ps/pam.ps ps/pam_appl.ps ps/pam_modules.ps + +MODULES=$(shell ls modules/*.sgml) + +####################################################### + +dummy: + @echo "Making the documentation..." + @make all + +all: htmls texts postscript + +htmls: $(HTMLS) + +$(HTMLS) : $(FSRCS) + @for i in $(FILES) ; do \ + if [ ! -f "html/$$i.html" ] || [ "$$i.sgml" -nt "html/$$i.html" ]; \ + then \ + cd html ; $(HTMLER) ../$$i ; \ + if [ $$? -ne 0 ]; then exit 1 ; fi ; \ + cd .. ; \ + fi ; \ + done + +texts: $(TEXTS) + +$(TEXTS) : $(FSRCS) + @for i in $(FILES) ; do \ + if [ ! -f "txts/$$i.txt" ] \ + || [ "$$i.sgml" -nt "txts/$$i.txt" ]; then \ + cd txts ; $(TXTER) ../$$i ; cd .. ; \ + fi ; \ + done + +postscript: $(PSFILES) + +$(PSFILES): $(FSRCS) + @for i in $(FILES) ; do \ + if [ ! -f "ps/$$i.ps" ] || [ "$$i.sgml" -nt "ps/$$i.ps" ]; then \ + cd ps ; $(PSER) ../$$i ; cd .. ; \ + fi ; \ + done + +pam.sgml: pam_source.sgml MODULES-SGML + @sed -e '/^<!\-\- insert\-file MODULES\-SGML \-\->/r MODULES-SGML' pam_source.sgml > pam.sgml + +MODULES-SGML: $(MODULES) + @echo 'Building module text from files in modules/*.sgml' + @rm -f MODULES-SGML + @echo '<!-- modules included:' > MODULES-SGML + @ls modules/*.sgml >> MODULES-SGML + @echo ' and that is all -->' >> MODULES-SGML + @cat modules/*.sgml >> MODULES-SGML + +extraclean: clean + +DOCDIR=/usr/doc/Linux-PAM +MANDIR=/usr/man +install: all + mkdir -p $(FAKEROOT)$(DOCDIR)/{html,ps,text} + for file in txts/*.txt; do \ + install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/text ; \ + done + for file in ps/*.ps; do \ + install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/ps ; \ + done + for file in html/*.html; do \ + install -o root -g root -m 644 $$file $(FAKEROOT)$(DOCDIR)/html ; \ + done + mkdir -p $(FAKEROOT)$(MANDIR)/man{3,8} + for file in man/*.3 ; do \ + install -o root -g root -m 644 $$file $(FAKEROOT)$(MANDIR)/man3 ; \ + done + for file in man/*.8 ; do \ + install -o root -g root -m 644 $$file $(FAKEROOT)$(MANDIR)/man8 ; \ + done + +clean: + rm -f *~ *.bak + rm -f html/pam*.html + rm -f man/*~ + rm -f $(TEXTS) + rm -f $(PSFILES) + rm -f MODULES-SGML pam.sgml + diff --git a/doc/NOTES b/doc/NOTES new file mode 100644 index 00000000..b0f40d47 --- /dev/null +++ b/doc/NOTES @@ -0,0 +1,16 @@ +Things to be added: + +@ modules: +@ application: + + use of + 'user' = user to become, + 'uid' = user requesting service + 'euid' = privilege of current process. + +@ sysadmin: + + included modules: + behavior + non-included modules: + behavior/pointers. diff --git a/doc/figs/pam_orient.txt b/doc/figs/pam_orient.txt new file mode 100644 index 00000000..a8b745a1 --- /dev/null +++ b/doc/figs/pam_orient.txt @@ -0,0 +1,23 @@ + + + + +----------------+ + | application: X | + +----------------+ / +----------+ +================+ + | authentication-[---->--\--] Linux- |--<--| /etc/pam.conf | + | + [----<--/--] PAM | |================| + |[conversation()][--+ \ | | | X auth .. a.so | + +----------------+ | / +-n--n-----+ | X auth .. b.so | + | | | __| | | _____/ + | service user | A | | |____,-----' + | | | V A + +----------------+ +------|-----|---------+ -----+------+ + +---u-----u----+ | | | + | auth.... |--[ a ]--[ b ]--[ c ] + +--------------+ + | acct.... |--[ b ]--[ d ] + +--------------+ + | password |--[ b ]--[ c ] + +--------------+ + | session |--[ e ]--[ c ] + +--------------+
\ No newline at end of file diff --git a/doc/html/.cvsignore b/doc/html/.cvsignore new file mode 100644 index 00000000..3b358a3a --- /dev/null +++ b/doc/html/.cvsignore @@ -0,0 +1 @@ +pam*.html
\ No newline at end of file diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 00000000..1ffd7e38 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,21 @@ + +<HTML> +<HEAD> +<TITLE>Linux-PAM - Pluggable Authentication Modules for Linux</TITLE> +</HEAD> +<BODY> + +<p> +Here is the documentation for Linux-PAM. As you will see it is +currently not complete. However, in order of decreasing length: + +<ul> +<li> <a href="pam.html">The System Administrators' Guide</a> +<li> <a href="pam_modules.html">The Module Writers' Manual</a> +<li> <a href="pam_appl.html">The Application developers' Manual</a> +</ul> + +<hr> +<p> +REVISION: <tt>$Id$</tt> +</BODY> diff --git a/doc/man/pam.8 b/doc/man/pam.8 new file mode 100644 index 00000000..68280737 --- /dev/null +++ b/doc/man/pam.8 @@ -0,0 +1,279 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org> +.TH PAM 8 "1997 Feb 9" "Linux-PAM 0.56" "Linux-PAM Manual" +.SH NAME + +Linux-PAM \- Pluggable Authentication Modules for Linux + +.SH SYNOPSIS +.B /etc/pam.conf +.sp 2 +.SH DESCRIPTION + +This manual is intended to offer a quick introduction to +.BR Linux-PAM ". " +For more information the reader is directed to the +.BR "Linux-PAM system administrators' guide". + +.sp +.BR Linux-PAM +Is a system of libraries that handle the authentication tasks of +applications (services) on the system. The library provides a stable +general interface (Application Programming Interface - API) that +privilege granting programs (such as +.BR login "(1) " +and +.BR su "(1)) " +defer to to perform standard authentication tasks. + +.sp +The principal feature of the PAM approach is that the nature of the +authentication is dynamically configurable. In other words, the +system administrator is free to choose how individual +service-providing applications will authenticate users. This dynamic +configuration is set by the contents of the single +.BR Linux-PAM +configuration file +.BR /etc/pam.conf "." +Alternatively, the configuration can be set by individual +configuration files located in the +.B /etc/pam.d/ +directory. +.IB "The presence of this directory will cause " Linux-PAM " to ignore" +.BI /etc/pam.conf "." + +.sp +From the point of view of the system administrator, for whom this +manual is provided, it is not of primary importance to understand the +internal behavior of the +.BR Linux-PAM +library. The important point to recognize is that the configuration +file(s) +.I define +the connection between applications +.BR "" "(" services ")" +and the pluggable authentication modules +.BR "" "(" PAM "s)" +that perform the actual authentication tasks. + +.sp +.BR Linux-PAM +separates the tasks of +.I authentication +into four independent management groups: +.BR "account" " management; " +.BR "auth" "entication management; " +.BR "password" " management; " +and +.BR "session" " management." +(We highlight the abbreviations used for these groups in the +configuration file.) + +.sp +Simply put, these groups take care of different aspects of a typical +user's request for a restricted service: + +.sp +.BR account " - " +provide account verification types of service: has the user's password +expired?; is this user permitted access to the requested service? + +.br +.BR auth "entication - " +establish the user is who they claim to be. Typically this is via some +challenge-response request that the user must satisfy: if you are who +you claim to be please enter your password. Not all authentications +are of this type, there exist hardware based authentication schemes +(such as the use of smart-cards and biometric devices), with suitable +modules, these may be substituted seamlessly for more standard +approaches to authentication - such is the flexibility of +.BR Linux-PAM "." + +.br +.BR password " - " +this group's responsibility is the task of updating authentication +mechanisms. Typically, such services are strongly coupled to those of +the +.BR auth +group. Some authentication mechanisms lend themselves well to being +updated with such a function. Standard UN*X password-based access is +the obvious example: please enter a replacement password. + +.br +.BR session " - " +this group of tasks cover things that should be done prior to a +service being given and after it is withdrawn. Such tasks include the +maintenance of audit trails and the mounting of the user's home +directory. The +.BR session +management group is important as it provides both an opening and +closing hook for modules to affect the services available to a user. + +.SH The configuration file(s) + +When a +.BR Linux-PAM +aware privilege granting application is started, it activates its +attachment to the PAM-API. This activation performs a number of +tasks, the most important being the reading of the configuration file(s): +.BR /etc/pam.conf "." +Alternatively, this may be the contents of the +.BR /etc/pam.d/ +directory. + +These files list the +.BR PAM "s" +that will do the authentication tasks required by this service, and +the appropriate behavior of the PAM-API in the event that individual +.BR PAM "s " +fail. + +.sp +The syntax of the +.B /etc/pam.conf +configuration file is as follows. The file is made +up of a list of rules, each rule is typically placed on a single line, +but may be extended with an escaped end of line: `\\<LF>'. Comments +are preceded with `#' marks and extend to the next end of line. + +.sp +The format of each rule is a space separated collection of tokens, the +first three being case-insensitive: + +.sp +.br +.BR " service type control module-path module-arguments" + +.sp +The syntax of files contained in the +.B /etc/pam.d/ +directory, are identical except for the absence of any +.I service +field. In this case, the +.I service +is the name of the file in the +.B /etc/pam.d/ +directory. This filename must be in lower case. + +.sp +An important feature of +.BR Linux-PAM ", " +is that a number of rules may be +.I stacked +to combine the services of a number of PAMs for a given authentication +task. + +.sp +The +.BR service +is typically the familiar name of the corresponding application: +.BR login +and +.BR su +are good examples. The +.BR service "-name, " other ", " +is reserved for giving +.I default +rules. Only lines that mention the current service (or in the absence +of such, the +.BR other +entries) will be associated with the given service-application. + +.sp +The +.BR type +is the management group that the rule corresponds to. It is used to +specify which of the management groups the subsequent module is to +be associated with. Valid entries are: +.BR account "; " +.BR auth "; " +.BR password "; " +and +.BR session "." +The meaning of each of these tokens was explained above. + +.sp +The third field, +.BR control ", " +indicates the behavior of the PAM-API should the module fail to +succeed in its authentication task. Valid +.BR control +values are: +.BR requisite +- failure of such a PAM results in the immediate termination of the +authentication process; +.BR required +- failure of such a PAM will ultimately lead to the PAM-API returning +failure but only after the remaining +.I stacked +modules (for this +.BR service +and +.BR type ")" +have been invoked; +.BR sufficient +- success of such a module is enough to satisfy the authentication +requirements of the stack of modules (if a prior +.BR required +module has failed the success of this one is +.IR ignored "); " +.BR optional +- the success or failure of this module is only important if it is the +only module in the stack associated with this +.BR service "+" type "." + +.sp +.BR module-path +- this is the full filename of the PAM to be used by the application + +.sp +.BR module-arguments +- these are a space separated list of tokens that can be used to +modify the specific behavior of the given PAM. Such arguments will be +documented for each individual module. + +.SH "FILES" +.BR /etc/pam.conf " - the configuration file" +.br +.BR /etc/pam.d/ " - the" +.BR Linux-PAM +configuration directory. If this directory is present, the +.B /etc/pam.conf +file is ignored. +.br +.BR /usr/lib/libpam.so.X " - the dynamic library" +.br +.BR /usr/lib/security/*.so " - the PAMs + +.sp +Note, to conform to the Linux File-system standard, the libraries and +modules in your system may be located in +.BR /lib " and " /lib/security +respectively. + +.SH ERRORS +Typically errors generated by the +.BR Linux-PAM +system of libraries, will be written to +.BR syslog "(3)." + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. +.br +Contains additional features, currently under consideration by the +DCE-RFC committee. + +.SH BUGS +.sp 2 +None known. + +.SH "SEE ALSO" + +The three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam.conf.8 b/doc/man/pam.conf.8 new file mode 100644 index 00000000..ea2dd98b --- /dev/null +++ b/doc/man/pam.conf.8 @@ -0,0 +1 @@ +.so man8/pam.8 diff --git a/doc/man/pam.d.8 b/doc/man/pam.d.8 new file mode 100644 index 00000000..ea2dd98b --- /dev/null +++ b/doc/man/pam.d.8 @@ -0,0 +1 @@ +.so man8/pam.8 diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3 new file mode 100644 index 00000000..ba1bc52e --- /dev/null +++ b/doc/man/pam_authenticate.3 @@ -0,0 +1,91 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net> +.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual" +.SH NAME + +pam_authenticate \- authenticate a user + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.sp +.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");" +.sp 2 +.SH DESCRIPTION +.B pam_authenticate + +.br +Use this function to authenticate an applicant user. It is linked +.I dynamically +to the authentication modules by +.BR Linux-PAM ". " +It is the task of these module to perform such an authentication. The +specific nature of the authentication is not the concern of the +application. + +.br +Following successful completion, the +.BR name +of the authenticated user will be present in the +.BR Linux-PAM +item +.BR PAM_USER ". " +This item may be recovered with a call to +.BR pam_get_item "(3)." + +.br +The application developer should note that the modules may request +that the user enter their username via the conversation mechanism (see +.BR pam_start "(3))." +Should this be the case, the user-prompt string can be set via +the +.BR PAM_USER_PROMPT +item (see +.BR pam_set_item "(3))." + +.SH "RETURN VALUE" +On success +.BR PAM_SUCCESS +is returned. All other returns should be considered +authentication failures and will be +.I delayed +by an amount specified with prior calls to +.BR pam_fail_delay "(3). " +Specific failures that demand special attention are the following: +.TP +.B PAM_ABORT +the application should exit immediately. Of course, +.BR pam_end "(3)" +should be called first. + +.TP +.B PAM_MAXTRIES +the application has tried too many times to authenticate the +user, authentication should not be attempted again. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_start "(3), " +.BR pam_get_item "(3) " +.BR pam_fail_delay "(3) " +and +.BR pam_strerror "(3). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3 new file mode 100644 index 00000000..63904da3 --- /dev/null +++ b/doc/man/pam_chauthtok.3 @@ -0,0 +1,101 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> +.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" +.SH NAME + +pam_chauthtok \- updating authentication tokens + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.sp +.BI "int pam_chauthtok(pam_handle_t " *pamh ", int " flags ");" +.sp 2 +.SH DESCRIPTION +.B pam_chauthtok + +.br +Use this function to rejuvenate the authentication tokens (passwords +etc.) of an applicant user. + +.br +Note, the application should not pre-authenticate the user, as this is +performed (if required) by the +.BR Linux-PAM +framework. + +.br +The +.I flags +argument can +.I optionally +take the value, +.BR PAM_CHANGE_EXPIRED_AUTHTOK "." +In such cases the framework is only required to update those +authentication tokens that have expired. Without this argument, the +framework will attempt to obtain new tokens for all configured +authentication mechanisms. The details of the types and number of such +schemes should not concern the calling application. + +.SH RETURN VALUE +A successful return from this function will be indicated with +.BR PAM_SUCCESS "." + +.br +Specific errors of special interest when calling this function are + +.br +.BR PAM_AUTHTOK_ERROR +- a valid new token was not obtained + +.br +.BR PAM_AUTHTOK_RECOVERY_ERR +- old authentication token was not available + +.br +.BR PAM_AUTHTOK_LOCK_BUSY +- a resource needed to update the token was locked (try again later) + +.br +.BR PAM_AUTHTOK_DISABLE_AGING +- one or more of the authentication modules does not honor +authentication token aging + +.br +.BR PAM_TRY_AGAIN +- one or more authentication mechanism is not prepared to update a +token at this time + +.br +In general other return values may be returned. They should be treated +as indicating failure. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_start "(3), " +.BR pam_authenticate "(3), " +.BR pam_setcred "(3), " +.BR pam_get_item "(3), " +.BR pam_strerror "(3) " +and +.BR pam "(8)." + +.br +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3 new file mode 100644 index 00000000..c809a0e4 --- /dev/null +++ b/doc/man/pam_close_session.3 @@ -0,0 +1 @@ +.so man3/pam_open_session.3 diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3 new file mode 100644 index 00000000..06fdabb9 --- /dev/null +++ b/doc/man/pam_end.3 @@ -0,0 +1 @@ +.so man3/pam_start.3 diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3 new file mode 100644 index 00000000..f6cd238a --- /dev/null +++ b/doc/man/pam_fail_delay.3 @@ -0,0 +1,130 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> +.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual" +.SH NAME + +pam_fail_delay \- request a delay on failure + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.br +or, +.br +.B #include <security/pam_modules.h> +.sp +.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");" +.sp 2 +.SH DESCRIPTION +.br +It is often possible to attack an authentication scheme by exploiting +the time it takes the scheme to deny access to an applicant user. In +cases of +.I short +timeouts, it may prove possible to attempt a +.I brute force +dictionary attack -- with an automated process, the attacker tries all +possible passwords to gain access to the system. In other cases, +where individual failures can take measurable amounts of time +(indicating the nature of the failure), an attacker can obtain useful +information about the authentication process. These latter attacks +make use of procedural delays that constitute a +.I covert channel +of useful information. + +.br +To minimize the effectiveness of such attacks, it is desirable to +introduce a random delay in a failed authentication process. +.B Linux-PAM +provides such a facility. The delay occurs upon failure of the +.BR pam_authenticate "(3) " +and +.BR pam_chauthtok "(3) " +functions. It occurs +.I after +all authentication modules have been called, but +.I before +control is returned to the service application. + +.br +The function, +.BR pam_fail_delay "(3)," +is used to specify a required minimum for the length of the +failure-delay; the +.I usec +argument. This function can be called by the service application +and/or the authentication modules, both may have an interest in +delaying a reapplication for service by the user. The length of the +delay is computed at the time it is required. Its length is +pseudo-gausianly distributed about the +.I maximum +requested value; the resultant delay will differ by as much as 25% of +this maximum requested value (both up and down). + +.br +On return from +.BR pam_authenticate "(3) or " pam_chauthtok "(3)," +independent of success or failure, the new requested delay is reset to +its default value: zero. + +.SH EXAMPLE +.br +For example, a +.B login +application may require a failure delay of roughly 3 seconds. It will +contain the following code: +.sp +.br +.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );" +.br +.B " pam_authenticate(pamh, 0);" +.sp +.br +if the modules do not request a delay, the failure delay will be +between 2.25 and 3.75 seconds. + +.br +However, the modules, invoked in the authentication process, may +also request delays: +.sp +.br +.RB " (module #1) " "pam_fail_delay(pamh, 2000000);" +.sp +.br +.RB " (module #2) " "pam_fail_delay(pamh, 4000000);" +.sp +.br +in this case, it is the largest requested value that is used to +compute the actual failed delay: here between 3 and 5 seconds. + +.SH "RETURN VALUE" +Following a successful call to +.BR pam_fail_delay "(3), " PAM_SUCCESS +is returned. All other returns should be considered serious failures. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +Under consideration by the X/Open group for future inclusion in the +PAM RFC. 1996/1/10 + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_start "(3), " +.BR pam_get_item "(3) " +and +.BR pam_strerror "(3). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_open_session.3 b/doc/man/pam_open_session.3 new file mode 100644 index 00000000..4e63b5c4 --- /dev/null +++ b/doc/man/pam_open_session.3 @@ -0,0 +1,99 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> +.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" +.SH NAME + +pam_open/close_session \- PAM session management + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.sp +.BI "int pam_open_session(pam_handle_t " *pamh ", int " flags ");" +.sp +.BI "int pam_close_session(pam_handle_t " *pamh ", int " flags ");" +.sp 2 +.SH DESCRIPTION + +PAM provides management-hooks for the initialization and termination +of a session. + +.TP +.B pam_open_session +.br +Use this function to signal that an authenticated user session has +begun. It should be called only after the user is properly identified +and (where necessary) has been granted their credentials with +.BR pam_authenticate "(3)" +and +.BR pam_setcred "(3)" +respectively. + +.br +Some types of functions associated with session +initialization are logging for the purposes of system-audit and +mounting directories (the user's home directory for example). These +should not concern the application. It should be noted that the +.I effective +uid, +.BR geteuid "(2)," +of the application should be of sufficient privilege to perform such +tasks. + +.TP +.B pam_close_session +.br +Use this function to signal that a user session has +terminated. In general this function may not need to be located in the +same application as the initialization function, +.BR pam_open_session "." + +.br +Typically, this function will undo the actions of +.BR pam_open_session "." +That is, log audit information concerning the end of the user session +or unmount the user's home directory. Apart from having sufficient +privilege the details of the session termination should not concern +the calling application. It is good programming practice, however, to +cease acting on behalf of the user on returning from this call. + +.SH RETURN VALUE +A successful return from the session management functions will be +indicated with +.BR PAM_SUCCESS "." + +.br +The specific error indicating a failure to open or close a session is +.BR PAM_SESSION_ERR "." +In general other return values may be returned. They should be treated +as indicating failure. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +OSF-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_start "(3), " +.BR pam_authenticate "(3), " +.BR pam_setcred "(3), " +.BR pam_get_item "(3), " +.BR pam_strerror "(3) " +and +.BR pam "(3)." + +.br +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3 new file mode 100644 index 00000000..8c00fe71 --- /dev/null +++ b/doc/man/pam_setcred.3 @@ -0,0 +1,79 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net> +.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual" +.SH NAME + +pam_setcred \- set the credentials for the user + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.sp +.BI "int pam_setcred(pam_handle_t " *pamh ", int " flags ");" +.sp 2 +.SH DESCRIPTION +.B pam_setcred + +This function is used to establish, maintain and delete the +credentials of a user. It should be called after a user has been +authenticated and before a session is opened for the user (with +.BR pam_open_session "(3))." + +It should be noted that credentials come in many forms. Examples +include: group memberships; ticket-files; and Linux-PAM environment +variables. For this reason, it is important that the basic identity +of the user is established, by the application, prior to a call to +this function. For example, the default +.BR Linux-PAM +environment variables should be set and also +.BR initgroups "(2) " +(or equivalent) should have been performed. + +.SH "VALID FLAGS" +.TP +.BR PAM_ESTABLISH_CRED +initialize the credentials for the user. + +.TP +.BR PAM_DELETE_CRED +delete the user's credentials. + +.TP +.BR PAM_REINITIALIZE_CRED +delete and then initialize the user's credentials. + +.TP +.BR PAM_REFRESH_CRED +extend the lifetime of the existing credentials. + +.SH "RETURN VALUE" + +On success +.BR PAM_SUCCESS +is returned, all other return values should be treated as errors. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_authenticate "(3), " +.BR pam_strerror "(3)" +and +.BR pam_open_session "(3). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3 new file mode 100644 index 00000000..9c11fd73 --- /dev/null +++ b/doc/man/pam_start.3 @@ -0,0 +1,98 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net> +.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual" +.SH NAME + +pam_start, pam_end \- activating Linux-PAM + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.sp +.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");" +.sp +.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");" +.sp 2 +.SH DESCRIPTION +.TP +.B pam_start +Initialize the +.I Linux-PAM +library. Identifying the application with a particular +.IR service +name. The +.IR user "name" +can take the value +.IR NULL ", " +if not known at the time the interface is initialized. The +conversation structure is passed to the library via the +.IR conv +argument. (For a complete description of this and other structures +the reader is directed to the more verbose +.IR Linux-PAM +application developers' guide). Upon successful initialization, an +opaque pointer-handle for future access to the library is returned +through the contents of the +.IR pamh_p +pointer. + +.TP +.B pam_end +Terminate the +.B Linux-PAM +library. The service application associated with the +.IR pamh +handle, is terminated. The argument, +.IR pam_status ", " +passes the value most recently returned to the application from the +library; it indicates the manner in which the library should be +shutdown. Besides carrying a return value, this argument may be +logically OR'd with +.IR PAM_DATA_SILENT +to indicate that the module should not treat the call too +seriously. It is generally used to indicate that the current closing +of the library is in a +.IR fork "(2)ed" +process, and that the parent will take care of cleaning up things that +exist outside of the current process space (files etc.). + +.SH "RETURN VALUE" +.TP +.B pam_start +.TP +.B pam_end +On success, +.BR PAM_SUCCESS +is returned + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. +.sp +Note, the +.BR PAM_DATA_SILENT +flag is pending acceptance with the DCE (as of 1996/12/4). + +.SH BUGS +.sp 2 +None known. + +.SH "SEE ALSO" + +.BR fork "(2), " +.BR pam_authenticate "(3), " +.BR pam_acct_mgmt "(3), " +.BR pam_open_session "(3), " +and +.BR pam_chauthtok "(3)." + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3 new file mode 100644 index 00000000..01ee0635 --- /dev/null +++ b/doc/man/pam_strerror.3 @@ -0,0 +1,51 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" ripped off from Rick Faith's getgroups man page +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org> +.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual" +.SH NAME + +pam_strerror \- return a textual description of a Linux-PAM error + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.br +or, +.br +.B #include <security/pam_modules.h> +.sp +.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");" +.sp 2 +.SH DESCRIPTION +.B pam_strerror + +This function returns some text describing the +.BR Linux-PAM +error associated with the +.B pam_error +argument. + +.SH "RETURN VALUE" + +On success this function returns a description of the indicated +error. Should the function not recognize the error, ``Unknown +Linux-PAM error'' is returned. + +.SH "CONFORMING TO" +DCE-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +This function should be internationalized. + +.SH "SEE ALSO" + +.BR pam "(8). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/man/template-man b/doc/man/template-man new file mode 100644 index 00000000..b8159eb6 --- /dev/null +++ b/doc/man/template-man @@ -0,0 +1,52 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id$ +.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> +.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual" +.SH NAME + +function names \- brief summary of function + +.SH SYNOPSIS +.B #include <security/pam_????.h> +.sp +.BI "int pam_???(pam_handle_t " pamh ", int " flags); +.sp 2 +.SH DESCRIPTION +.TP +.B pam_??? +Here goes the +.I explanation +it may be quite +.IR long . +.TP +.SH "RETURN VALUE" +.B pam_??? +On success... +.BR PAM_SUCCESS +is returned +.TP +.SH ERRORS +May be translated to text with +.BR pam_strerror "(2). " + +.SH "CONFORMING TO" +.B pam_??? +DCE-RFC 86.0, October 1995. + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_??? "(2), " +and +.BR pam_??? "(2). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " diff --git a/doc/modules/README b/doc/modules/README new file mode 100644 index 00000000..df091939 --- /dev/null +++ b/doc/modules/README @@ -0,0 +1,13 @@ +$Id$ + +This directory contains a number of sgml sub-files. One for each +documented module. They contain a description of each module and give +some indication of its reliability. + +Additionally, there is a 'module.sgml-template' file which should be +used as a blank form for new module descriptions. + +Please feel free to submit amendments/comments etc. regarding these +files to: + + Andrew G. Morgan <morgan@parc.power.net> diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template new file mode 100644 index 00000000..d0b0e3c6 --- /dev/null +++ b/doc/modules/module.sgml-template @@ -0,0 +1,170 @@ +<!-- + + $Id$ + + This template file was written by Andrew G. Morgan + <morgan@parc.power.net> + +[ + Text that should be deleted/replaced, is enclosed within + '[' .. ']' + marks. For example, this text should be deleted! +] + +--> + +<sect1> [*Familiar full name of module*, eg. The "allow all" module.] + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +[ + insert the name of the module + + Blank is not permitted. +] + +<tag><bf>Author[s]:</bf></tag> + +[ + Insert author names here + + Blank is not permitted. If in doubt, put "unknown" if the + author wishes to remain anonymous, put "anonymous". +] + +<tag><bf>Maintainer:</bf></tag> + +[ + Insert names and date-begun of most recent maintainer. +] + +<tag><bf>Management groups provided:</bf></tag> + +[ + list the subset of four management groups supported by the + module. Choose from: account; authentication; password; + session. + + Blank entries are not permitted. Explicitly list all of the + management groups. In the future more may be added to libpam! +] + +<tag><bf>Cryptographically sensitive:</bf></tag> + +[ + Indicate whether this module contains code that can perform + reversible (strong) encryption. This field is primarily to + ensure that people redistributing it are not unwittingly + breaking laws... + + Modules may also require the presence of some local library + that performs the necessary encryption via some standard API. + In this case "uses API" can be included in this field. The + library in question should be added to the system requirements + below. + + Blank = no cryptography is used by module. +] + +<tag><bf>Security rating:</bf></tag> + +[ + Initially, this field should be left blank. If someone takes + it upon themselves to test the strength of the module, it can + later be filled. + + Blank = unknown. +] + +<tag><bf>Clean code base:</bf></tag> + +[ + This will probably be filled by the libpam maintainer. + It can be considered to be a public humiliation list. :*) + + I am of the opinion that "gcc -with_all_those_flags" is + trying to tell us something about whether the program + works as intended. Since there is currently no Security + evaluation procedure for modules IMHO this is not a + completely unreasonable indication (a lower bound anyway) + of the reliability of a module. + + This field would indicate the number and flavor of + warnings that gcc barfs up when trying to compile the + module as part of the tree. Is this too tyrannical? + + Blank = Linux-PAM maintainer has not tested it :) +] + +<tag><bf>System dependencies:</bf></tag> + +[ + here we list config files, dynamic libraries needed, system + resources, kernel options.. etc. + + Blank = nothing more than libc required. +] + +<tag><bf>Network aware:</bf></tag> + +[ + Does the module base its behavior on probing a network + connection? Does it expect to be protected by the + application? + + Blank = Ignorance of network. +] + +</descrip> + +<sect2>Overview of module + +[ + some text describing the intended actions of the module + general comments mainly (specifics in sections + below). +] + +[ + + [ now we have a <sect2> level subsection for each of the + management groups. Include as many as there are groups + listed above in the synopsis ] + +<sect2>[ Account | Authentication | Password | Session ] component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +[ + List the supported arguments (leave their description for the + description below. + + Blank = no arguments are read and nothing is logged to syslog + about any arguments that are passed. Note, this + behavior is contrary to the RFC! +] + +<tag><bf>Description:</bf></tag> + +[ + This component of the module performs the task of ... +] + +<tag><bf>Examples/suggested usage:</bf></tag> + +[ + Here we list some doos and don'ts for this module. +] + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_access.sgml b/doc/modules/pam_access.sgml new file mode 100644 index 00000000..e192d12e --- /dev/null +++ b/doc/modules/pam_access.sgml @@ -0,0 +1,93 @@ +<!-- + + pam_access module docs added by Tim Berger <timb@transmeta.com> + +--> + +<sect1> The access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +<tt>pam_access</tt> + + +<tag><bf>Author[s]:</bf></tag> + +Alexei Nogin <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 <tt>/etc/security/access.conf</tt> +<tag><bf>Network aware:</bf></tag> + +Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of +the stdin file descriptor with <tt/ttyname()/. Standard +gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/ +calls. <bf/NIS/ is used for netgroup support. + +</descrip> + +<sect2>Overview of module + +<p> +Provides logdaemon style login access control. + +<sect2> Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module provides logdaemon style login access control based on +login names and on host (or domain) names, internet addresses (or +network numbers), or on terminal line names in case of non-networked +logins. Diagnostics are reported through <tt/syslog(3)/. Wietse +Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with +several changes by A. Nogin. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Use of module is recommended, for example, on administrative machines +such as <bf/NIS/ servers and mail servers where you need several accounts +active but don't want them all to have login capability. + +For <tt>/etc/pam.d</tt> style configurations where your modules live +in <tt>/lib/security</tt>, start by adding the following line to +<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>, +<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>: + +<tscreen> +<verb> +account required /lib/security/pam_access.so +</verb> +</tscreen> + +Note that use of this module is not effective unless your system ignores +<tt>.rhosts</tt> files. See the the pam_rhosts_auth documentation. + +A sample <tt>access.conf</tt> configuration file is included with the +distribution. + +</descrip> + diff --git a/doc/modules/pam_chroot.sgml b/doc/modules/pam_chroot.sgml new file mode 100644 index 00000000..ec739c18 --- /dev/null +++ b/doc/modules/pam_chroot.sgml @@ -0,0 +1,86 @@ +<!-- + $Id$ + + This file was written by Bruce Campbell <brucec@humbug.org.au> +--> + +<sect1>Chroot + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_chroot/ + +<tag><bf>Author:</bf></tag> +Bruce Campbell <brucec@humbug.org.au> + +<tag><bf>Maintainer:</bf></tag> +Author; proposed on 20/11/96 - email for status + +<tag><bf>Management groups provided:</bf></tag> +account; session; authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Unwritten. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +Expects localhost. + +</descrip> + +<sect2>Overview of module + +<p> +This module is intended to provide a transparent wrapper around the +average user, one that puts them in a fake file-system (eg, their +'<tt>/</tt>' is really <tt>/some/where/else</tt>). + +<p> +Useful if you have several classes of users, and are slightly paranoid +about security. Can be used to limit who else users can see on the +system, and to limit the selection of programs they can run. + +<sect2>Account component: + +<p> +<em/Need more info here./ + +<sect2>Authentication component: + +<p> +<em/Need more info here./ + +<sect2>Session component: + +<p> +<em/Need more info here./ + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +Arguments and logging levels for the PAM version are being worked on. + +<tag><bf>Description:</bf></tag> + +<tag><bf>Examples/suggested usage:</bf></tag> +Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm', +'cp' and 'ed' in there is a bit... +<p> +Don't take it to extremes (eg, you can set up a separate environment for +each user, but its a big waste of your disk space.) + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml new file mode 100644 index 00000000..f5b2359a --- /dev/null +++ b/doc/modules/pam_cracklib.sgml @@ -0,0 +1,259 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com> +--> + +<sect1>Cracklib pluggable password strength-checker + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +pam_cracklib + +<tag><bf>Author:</bf></tag> + +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> + +Author. + +<tag><bf>Management groups provided:</bf></tag> + +password + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +Requires the system library <tt/libcrack/ and a system dictionary: +<tt>/usr/lib/cracklib_dict</tt>. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module can be plugged into the <tt/password/ stack of a given +application to provide some plug-in strength-checking for passwords. +(XXX - note this does not necessarily work with the pam_unix module, +although it is known to work with the pam_pwdb replacement for the +unix module -- see example and pam_pwdb write up for more +information). + +<p> +This module works in the following manner: it first calls the +<em>Cracklib</em> routine to check the strength of the password; if +crack likes the password, the module does an additional set of +strength checks. These checks are: +<itemize> + +<item> <bf/Palindrome/ - + +Is the new password a palindrome of the old one? + +<item> <bf/Case Change Only/ - + +Is the new password the the old one with only a change of case? + +<item> <bf/Similar/ - + +Is the new password too much like the old one? This is controlled +by one argument, <tt/difok/ which is a number of characters that if +different between the old and new are enough to accept the new +password, this defaults to 10 or 1/2 the size of the new password +whichever is smaller. + +<item> <bf/Simple/ - + +Is the new password too small? This is controlled by 5 arguments +<tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and +<tt/ocredit/. See the section on the arguments for the details of how +these work and there defaults. + +<item> <bf/Rotated/ - + +Is the new password a rotated version of the old password? + +<item> <bf/Already used/ - + +Was the password used in the past? Previously used passwords are to +be found in /etc/security/opasswd. + +</itemize> + +<p> +This module with no arguments will work well for standard unix +password encryption. With md5 encryption, passwords can be longer +than 8 characters and the default settings for this module can make it +hard for the user to choose a satisfactory new password. Notably, the +requirement that the new password contain no more than 1/2 of the +characters in the old password becomes a non-trivial constraint. For +example, an old password of the form "the quick brown fox jumped over +the lazy dogs" would be difficult to change... In addition, the +default action is to allow passwords as small as 5 characters in +length. For a md5 systems it can be a good idea to increase the +required minimum size of a password. One can then allow more credit +for different kinds of characters but accept that the new password may +share most of these characters with the old password. + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/; +<tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/; + +<tag><bf>Description:</bf></tag> + +The action of this module is to prompt the user for a password and +check its strength against a system dictionary and a set of rules for +identifying poor choices. + +<p> +The default action is to prompt for a single password, check its +strength and then, if it is considered strong, prompt for the password +a second time (to verify that it was typed correctly on the first +occasion). All being well, the password is passed on to subsequent +modules to be installed as the new authentication token. + +<p> +The default action may be modified in a number of ways using the +arguments recognized by the module: +<itemize> + +<item> <tt/debug/ - + +this option makes the module write information to syslog(3) indicating +the behavior of the module (this option does <bf/not/ write password +information to the log file). + +<item> <tt/type=XXX/ - + +the default action is for the module to use the following prompts when +requesting passwords: ``New UNIX password: '' and ``Retype UNIX +password: ''. Using this option you can replace the word UNIX with +<tt/XXX/. + +<item> <tt/retry=N/ - + +the default number of times this module will request a new password +(for strength-checking) from the user is 1. Using this argument this +can be increased to <tt/N/. + +<item> <tt/difok=N/ - + +This argument will change the default of 10 for the number of +characters in the new password that must not be present in the old +password. In addition, if 1/2 of the characters in the new password +are different then the new password will be accepted anyway. + +<item> <tt/minlen=N/ - + +The minimum acceptable size for the new password plus one. In +addition to the number of characters in the new password, credit (of ++1 in length) is given for each different kind of character (<em>other, +upper, lower</em> and <em/digit/). The default for this parameter is +9 which is good for a old style UNIX password all of the same type of +character but may be too low to exploit the added security of a md5 +system. Note that there is a pair of length limits in +<em>Cracklib</em> itself, a "way too short" limit of 4 which is hard +coded in and a defined limit (6) that will be checked without +reference to <tt>minlen</tt>. If you want to allow passwords as short +as 5 characters you should either not use this module or recompile +the crack library and then recompile this module. + +<item> <tt/dcredit=N/ - + +This is the maximum credit for having digits in the new password. If +you have less than or <tt/N/ digits, each digit will count +1 towards +meeting the current <tt/minlen/ value. The default for <tt/dcredit/ +is 1 which is the recommended value for <tt/minlen/ less than 10. + +<item> <tt/ucredit=N/ - + +This is the maximum credit for having upper case letters in the new +password. If you have less than or <tt/N/ upper case letters each +letter will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/ucredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +<item> <tt/lcredit=N/ - + +This is the maximum credit for having lower case letters in the new +password. If you have less than or <tt/N/ lower case letters, each +letter will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/lcredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +<item> <tt/ocredit=N/ - + +This is the maximum credit for having other characters in the new +password. If you have less than or <tt/N/ other characters, each +character will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/ocredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +(At the time of writing, this module can only be stacked before the +<tt/pam_pwdb/ module. Cracklib strength checking may be compiled by +default into the <tt/pam_unix/ module.) + +<p> +For an example of the use of this module, we show how it may be +stacked with the password component of <tt/pam_pwdb/: +<tscreen> +<verb> +# +# These lines stack two password type modules. In this example the +# user is given 3 opportunities to enter a strong password. The +# "use_authtok" argument ensures that the pam_pwdb module does not +# prompt for a password, but instead uses the one provided by +# pam_cracklib. +# +passwd password required pam_cracklib.so retry=3 +passwd password required pam_pwdb.so use_authtok +</verb> +</tscreen> + +<p> +Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the +case that you want to use md5 password encryption: +<tscreen> +<verb> +#%PAM-1.0 +# +# These lines allow a md5 systems to support passwords of at least 14 +# bytes with extra credit of 2 for digits and 2 for others the new +# password must have at least three bytes that are not present in the +# old password +# +password required pam_cracklib.so \ + difok=3 minlen=15 dcredit= 2 ocredit=2 +password required pam_pwdb.so use_authtok nullok md5 +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml new file mode 100644 index 00000000..6e1f2992 --- /dev/null +++ b/doc/modules/pam_deny.sgml @@ -0,0 +1,179 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The locking-out module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_deny + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +current <bf/Linux-PAM/ maintainer + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module can be used to deny access. It always indicates a failure +to the application through the PAM framework. As is commented in the +overview section <ref id="overview-section" name="above">, this module +might be suitable for using for default (the <tt/OTHER/) entries. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component does nothing other than return a failure. The +failure type is <tt/PAM_ACCT_EXPIRED/. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Stacking this module with type <tt/account/ will prevent the user from +gaining access to the system via applications that refer to +<bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/. + +<p> +The following example would make it impossible to login: +<tscreen> +<verb> +# +# add this line to your other login entries to disable all accounts +# +login account required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component does nothing other than return a failure. The failure +type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is +called (when the application tries to authenticate the user), and is +<tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/ +(to establish and set the credentials of the user -- it is unlikely +that this function will ever be called in practice). + +<tag><bf>Examples/suggested usage:</bf></tag> + +To deny access to default applications with this component of the +<tt/pam_deny/ module, you might include the following line in your +<bf/Linux-PAM/ configuration file: +<tscreen> +<verb> +# +# add this line to your existing OTHER entries to prevent +# authentication succeeding with default applications. +# +OTHER auth required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component of the module denies the user the opportunity to change +their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when +invoked. + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module should be used to prevent an application from updating the +applicant user's password. For example, to prevent <tt/login/ from +automatically prompting for a new password when the old one has +expired you should include the following line in your configuration +file: +<tscreen> +<verb> +# +# add this line to your other login entries to prevent the login +# application from being able to change the user's password. +# +login password required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This aspect of the module prevents an application from starting a +session on the host computer. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Together with another session module, that displays a message of the +day perhaps (XXX - such a module needs to be written), +this module can be used to block a user from starting a shell. Given +the presence of a <tt/pam_motd/ module, we might use the following +entries in the configuration file to inform the user it is system +time: +<tscreen> +<verb> +# +# An example to see how to configure login to refuse the user a +# session (politely) +# +login session required pam_motd.so \ + file=/etc/system_time +login session required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml new file mode 100644 index 00000000..8057b38d --- /dev/null +++ b/doc/modules/pam_env.sgml @@ -0,0 +1,141 @@ +<!-- + $Id$ + + This file was written by Dave Kinchlea <kinch@kinch.ark.com> + Ed. AGM +--> + +<sect1>Set/unset environment variables + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_env/ + +<tag><bf>Author:</bf></tag> +Dave Kinchlea <kinch@kinch.ark.com> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (setcred) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +<tt>/etc/security/pam_env.conf</tt> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module allows the (un)setting of environment variables. Supported +is the use of previously set environment variables as well as +<em>PAM_ITEM</em>s such as <tt>PAM_RHOST</tt>. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/conffile=/<em/configuration-file-name/; +<tt/envfile/=/<em/env-file-name/; <tt/readenv/=/<em/0|1/ + +<tag><bf>Description:</bf></tag> +This module allows you to (un)set arbitrary environment variables +using fixed strings, the value of previously set environment variables +and/or <em/PAM_ITEM/s. + +<p> +All is controlled via a configuration file (by default, +<tt>/etc/security/pam_env.conf</tt> but can be overriden with +<tt>connfile</tt> argument). Each line starts with the variable name, +there are then two possible options for each variable <bf>DEFAULT</bf> +and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows and administrator to +set the value of the variable to some default value, if none is +supplied then the empty string is assumed. The <bf>OVERRIDE</bf> +option tells pam_env that it should enter in its value (overriding the +default value) if there is one to use. <bf>OVERRIDE</bf> is not used, +<tt>""</tt> is assumed and no override will be done. + +<p> +<tscreen> +<verb> +VARIABLE [DEFAULT=[value]] [OVERRIDE=[value]] +</verb> +</tscreen> + +<p> +(Possibly non-existent) environment variables may be used in values +using the <tt>${string}</tt> syntax and (possibly +non-existent) <em/PAM_ITEM/s may be used in values using the +<tt>@{string}</tt> syntax. Both the <tt>$</tt> +and <tt>@</tt> characters can be backslash-escaped to be used +as literal values (as in <tt>\$</tt>. Double quotes may +be used in values (but not environment variable names) when white +space is needed <bf>the full value must be delimited by the quotes and +embedded or escaped quotes are not supported</bf>. + +<p> +This module can also parse a file with simple KEY=VAL pairs on seperate +lines (/etc/environment by default). You can change the default file to +parse, with the <em/envfile/ flag and turn it on or off by setting the +<em/readenv/ flag to 1 or 0 respectively. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/conffile=/<em/filename/ +- by default the file <tt>/etc/security/pam_env.conf</tt> is used as +the configuration file. This option overrides the default. You must +supply a complete path + file name. + +<item><tt/envfile=/<em/filename/ +- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL +pairs directly into the env. This option overrides the default. You must +supply a complete path + file name. + +<item><tt/readenv=/<em/0|1/ +- turns on or off the reading of the file specified by envfile (0 is off, +1 is on). By default this option is on. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +See sample <tt>pam_env.conf</tt> for more information and examples. + +</descrip> + +<!-- +End of sgml insert for this module. +--> + + + + + + + + + + diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml new file mode 100644 index 00000000..598279b8 --- /dev/null +++ b/doc/modules/pam_filter.sgml @@ -0,0 +1,150 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The filter module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +pam_filter + +<tag><bf>Author:</bf></tag> + +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> + +Author. + +<tag><bf>Management groups provided:</bf></tag> + +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +Not yet. + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +This module compiles cleanly on Linux based systems. + +<tag><bf>System dependencies:</bf></tag> + +To function it requires <em/filters/ to be installed on the system. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module was written to offer a plug-in alternative to programs +like ttysnoop (XXX - need a reference). Since writing a filter that +performs this function has not occurred, it is currently only a toy. +The single filter provided with the module simply transposes upper and +lower case letters in the input and output streams. (This can be very +annoying and is not kind to termcap based editors). + +<sect2>Account+Authentication+Password+Session components + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/ + +<tag><bf>Description:</bf></tag> + +Each component of the module has the potential to invoke the desired +filter. The filter is always <tt/execv(2)/d with the privilege of the +calling application and <bf/not/ that of the user. For this reason it +cannot usually be killed by the user without closing their session. + +<p> +The behavior of the module can be significantly altered by the +arguments passed to it in the <bf/Linux-PAM/ configuration file: +<itemize> +<item><tt/debug/ - + +this option increases the amount of information logged to +<tt/syslog(3)/ as the module is executed. + +<item><tt/new_term/ - + +the default action of the filter is to set the <tt/PAM_TTY/ item to +indicate the terminal that the user is using to connect to the +application. This argument indicates that the filter should set +<tt/PAM_TTY/ to the filtered pseudo-terminal. + +<item><tt/non_term/ - +don't try to set the <tt/PAM_TTY/ item. + +<item><tt/runX/ - + +in order that the module can invoke a filter it should know when to +invoke it. This argument is required to tell the filter when to do +this. The arguments that follow this one are respectively the full +pathname of the filter to be run and any command line arguments that +the filter might expect. + +<p> +Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the +precise time the that filter is to be run. To explain this concept it +will be useful to have read the Linux-PAM Module developer's +guide. Basically, for each management group there are up to two ways +of calling the module's functions. + +In the case of the <em/authentication/ and <em/session/ components +there are actually two separate functions. For the case of +authentication, these functions are <tt/_authenticate/ and +<tt/_setcred/ -- here <tt/run1/ means run the filter from the +<tt/_authenticate/ function and <tt/run2/ means run the filter from +<tt/_setcred/. In the case of the session modules, <tt/run1/ implies +that the filter is invoked at the <tt/_open_session/ stage, and +<tt/run2/ for <tt/_close_session/. + +<p> +For the case of the account component. Either <tt/run1/ or <tt/run2/ +may be used. + +<p> +For the case of the password component, <tt/run1/ is used to indicate +that the filter is run on the first occasion <tt/_chauthtok/ is run +(the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate +that the filter is run on the second occasion (the +<tt/PAM_UPDATE_AUTHTOK/ phase). + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +At the time of writing there is little real use to be made of this +module. For fun you might try adding the following line to your +login's configuration entries +<tscreen> +<verb> +# +# An example to see how to configure login to transpose upper and +# lower case letters once the user has logged in(!) +# +login session required pam_filter.so \ + run1 /usr/sbin/pam_filter/upperLOWER +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml new file mode 100644 index 00000000..3c26a5f0 --- /dev/null +++ b/doc/modules/pam_ftp.sgml @@ -0,0 +1,93 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>Anonymous access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_ftp.so/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +prompts for email address of user; easily spoofed (XXX - needs work) + +</descrip> + +<sect2>Overview of module + +<p> +The purpose of this module is to provide a pluggable anonymous ftp +mode of access. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/users=XXX,YYY,.../; +<tt/ignore/ + +<tag><bf>Description:</bf></tag> + +This module intercepts the user's name and password. If the name is +``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up +at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/ +part; these pam-items being set accordingly. The username is set to +``<tt/ftp/''. In this case the module succeeds. Alternatively, the +module sets the <tt/PAM_AUTHTOK/ item with the entered password and +fails. + +<p> +The behavior of the module can be modified with the following flags: +<itemize> +<item><tt/debug/ - +log more information to with <tt/syslog(3)/. + +<item><tt/users=XXX,YYY,.../ - +instead of ``<tt/ftp/'' or ``<tt/anonymous/'', provide anonymous login +to the comma separated list of users; ``<tt/XXX,YYY,.../''. Should the +applicant enter one of these usernames the returned username is set to +the first in the list; ``<tt/XXX/''. + +<item><tt/ignore/ - +pay no attention to the email address of the user (if supplied). + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +An example of the use of this module is provided in the configuration +file section <ref id="configuration" name="above">. With care, this +module could be used to provide new/temporary account anonymous +login. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml new file mode 100644 index 00000000..8251e3dd --- /dev/null +++ b/doc/modules/pam_group.sgml @@ -0,0 +1,108 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The group access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_group/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> +Sensitive to <em/setgid/ status of file-systems accessible to users. + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled +with or without <tt/libpwdb/. + +<tag><bf>Network aware:</bf></tag> +Only through correctly set <tt/PAM_TTY/ item. + +</descrip> + +<sect2>Overview of module + +<p> +This module provides group-settings based on the user's name and the +terminal they are requesting a given service from. It takes note of +the time of day. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module does not authenticate the user, but instead it grants +group memberships (in the credential setting phase of the +authentication module) to the user. Such memberships are based on the +service they are applying for. The group memberships are listed in +text form in the <tt>/etc/security/group.conf</tt> file. + +<tag><bf>Examples/suggested usage:</bf></tag> + +For this module to function correctly there must be a correctly +formatted <tt>/etc/security/groups.conf</tt> file present. The format +of this file is as follows. Group memberships are given based on the +service application satisfying any combination of lines in the +configuration file. Each line (barring comments which are preceded by +`<tt/#/' marks) has the following +syntax: +<tscreen> +<verb> +services ; ttys ; users ; times ; groups +</verb> +</tscreen> +Here the first four fields share the syntax of the <tt>pam_time</tt> +configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last +field, the <tt/groups/ field, is a comma (or space) separated list of +the text-names of a selection of groups. If the users application for +service satisfies the first four fields, the user is granted membership +of the listed groups. + +<p> +As stated in above this module's usefulness relies on the file-systems +accessible to the user. The point being that once granted the +membership of a group, the user may attempt to create a <em/setgid/ +binary with a restricted group ownership. Later, when the user is not +given membership to this group, they can recover group membership with +the precompiled binary. The reason that the file-systems that the user +has access to are so significant, is the fact that when a system is +mounted <em/nosuid/ the user is unable to create or execute such a +binary file. For this module to provide any level of security, all +file-systems that the user has write access to should be mounted +<em/nosuid/. + +<p> +The <tt>pam_group</tt> module fuctions in parallel with the +<tt>/etc/group</tt> file. If the user is granted any groups based on +the behavior of this module, they are granted <em>in addition</em> to +those entries <tt>/etc/group</tt> (or equivalent). + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_issue.sgml b/doc/modules/pam_issue.sgml new file mode 100644 index 00000000..1f617e3b --- /dev/null +++ b/doc/modules/pam_issue.sgml @@ -0,0 +1,120 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Add issue file to user prompt + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_issue/ + +<tag><bf>Author:</bf></tag> +Ben Collins <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/doc/modules/pam_krb4.sgml b/doc/modules/pam_krb4.sgml new file mode 100644 index 00000000..16ce8183 --- /dev/null +++ b/doc/modules/pam_krb4.sgml @@ -0,0 +1,126 @@ +<!-- + $Id$ + + This file was written by Derrick J. Brashear <shadow@DEMENTIA.ORG> +--> + +<sect1>The Kerberos 4 module. + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_krb4/ + +<tag><bf>Author:</bf></tag> +Derrick J. Brashear <shadow@dementia.org> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> +uses API + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +libraries - <tt/libkrb/, <tt/libdes/, <tt/libcom_err/, <tt/libkadm/; +and a set of Kerberos include files. + +<tag><bf>Network aware:</bf></tag> +Gets Kerberos ticket granting ticket via a Kerberos key distribution +center reached via the network. + +</descrip> + +<sect2>Overview of module + +<p> +This module provides an interface for doing Kerberos verification of a +user's password, getting the user a Kerberos ticket granting ticket +for use with the Kerberos ticket granting service, destroying the +user's tickets at logout time, and changing a Kerberos password. + +<sect2> Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component of the module currently sets the user's <tt/KRBTKFILE/ +environment variable (although there is currently no way to export +this), as well as deleting the user's ticket file upon logout (until +<tt/PAM_CRED_DELETE/ is supported by <em/login/). + +<tag><bf>Examples/suggested usage:</bf></tag> + +This part of the module won't be terribly useful until we can change +the environment from within a <tt/Linux-PAM/ module. + +</descrip> + +<sect2> Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/use_first_pass/; <tt/try_first_pass/ + +<tag><bf>Description:</bf></tag> + +This component of the module changes a user's Kerberos password +by first getting and using the user's old password to get +a session key for the password changing service, then sending +a new password to that service. + +<tag><bf>Examples/suggested usage:</bf></tag> + +This should only be used with a real Kerberos v4 <tt/kadmind/. It +cannot be used with an AFS kaserver unless special provisions are +made. Contact the module author for more information. + +</descrip> + +<sect2> Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/use_first_pass/; <tt/try_first_pass/ + +<tag><bf>Description:</bf></tag> + +This component of the module verifies a user's Kerberos password +by requesting a ticket granting ticket from the Kerberos server +and optionally using it to attempt to retrieve the local computer's +host key and verifying using the key file on the local machine if +one exists. + +It also writes out a ticket file for the user to use later, and +deletes the ticket file upon logout (not until <tt/PAM_CRED_DELETE/ +is called from <em/login/). + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used with a real Kerberos server using MIT +v4 Kerberos keys. The module or the system Kerberos libraries +may be modified to support AFS style Kerberos keys. Currently +this is not supported to avoid cryptography constraints. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_lastlog.sgml b/doc/modules/pam_lastlog.sgml new file mode 100644 index 00000000..2ade5baa --- /dev/null +++ b/doc/modules/pam_lastlog.sgml @@ -0,0 +1,119 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The last login module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_lastlog/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +auth + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +uses information contained in the <tt>/var/log/lastlog</tt> file. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This session module maintains the <tt>/var/log/lastlog</tt> file. Adding +an open entry when called via the <tt>pam_open_seesion()</tt> function +and completing it when <tt>pam_close_session()</tt> is called. This +module can also display a line of information about the last login of +the user. If an application already performs these tasks, it is not +necessary to use this module. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/nodate/; <tt/noterm/; <tt/nohost/; <tt/silent/; +<tt/never/ + +<tag><bf>Description:</bf></tag> + +<p> +This module can be used to provide a ``Last login on ...'' +message. when the user logs into the system from what ever application +uses the PAM libraries. In addition, the module maintains the +<tt>/var/log/lastlog</tt> file. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/nodate/ +- neglect to give the date of the last login when displaying +information about the last login on the system. + +<item><tt/noterm/ +- neglect to diplay the terminal name on which the last login was +attempt. + +<item><tt/nohost/ +- neglect to indicate from which host the last login was attempted. + +<item><tt/silent/ +- neglect to inform the user about any previous login: just update +the <tt>/var/log/lastlog</tt> file. + +<item><tt/never/ +- if the <tt>/var/log/lastlog</tt> file does not contain any old entries +for the user, indicate that the user has never previously logged in +with a ``welcome..." message. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used to indicate that the user has new mail when +they <em/login/ to the system. Here is a sample entry for your +<tt>/etc/pam.conf</tt> file: +<tscreen> +<verb> +# +# do we have any mail? +# +login session optional pam_lastlog.so +</verb> +</tscreen> + +<p> +Note, some applications may perform this function themselves. In such +cases, this module is not necessary. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_limits.sgml b/doc/modules/pam_limits.sgml new file mode 100644 index 00000000..f7a2245e --- /dev/null +++ b/doc/modules/pam_limits.sgml @@ -0,0 +1,197 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + from information compiled by Cristian Gafton (author of module) +--> + +<sect1>The resource limits module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_limits/ + +<tag><bf>Authors:</bf></tag> +Cristian Gafton <gafton@redhat.com> <newline> +Thanks are also due to Elliot Lee <sopwith@redhat.com> +for his comments on improving this module. + +<tag><bf>Maintainer:</bf></tag> +Cristian Gafton - 1996/11/20 + +<tag><bf>Management groups provided:</bf></tag> +session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +requires an <tt>/etc/security/limits.conf</tt> file and kernel support +for resource limits. Also uses the library, <tt/libpwdb/. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets +limits on the system resources that can be obtained in a +user-session. Its actions are dictated more explicitly through the +configuration file discussed below. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt>conf=/path/to/file.conf</tt> + +<tag><bf>Description:</bf></tag> + +Through the contents of the configuration file, +<tt>/etc/security/limits.conf</tt>, resource limits are placed on +users' sessions. Users of <tt/uid=0/ are not affected by this +restriction. + +<p> +The behavior of this module can be modified with the following +arguments: +<itemize> + +<item><tt/debug/ - +verbose logging to <tt/syslog(3)/. + +<item><tt>conf=/path/to/file.conf</tt> - +indicate an alternative <em/limits/ configuration file to the default. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +In order to use this module the system administrator must first create +a <em/root-only-readable/ file (default is +<tt>/etc/security/limits.conf</tt>). This file describes the resource +limits the superuser wishes to impose on users and groups. No limits +are imposed on <tt/uid=0/ accounts. + +<p> +Each line of the configuration file describes a limit for a user in +the form: +<tscreen> +<verb> +<domain> <type> <item> <value> +</verb> +</tscreen> + +<p> +The fields listed above should be filled as follows...<newline> +<tt><domain></tt> can be: +<itemize> +<item> a username +<item> a groupname, with <tt>@group</tt> syntax +<item> the wild-card <tt/*/, for default entry +</itemize> + +<p> +<tt><type></tt> can have the two values: +<itemize> + +<item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits +are set by the superuser and enforced by the Linux Kernel. The user +cannot raise his requirement of system resources above such values. + +<item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits +are ones that the user can move up or down within the permitted range +by any pre-exisiting <em/hard/ limits. The values specified with this +token can be thought of as <em/default/ values, for normal system +usage. + +</itemize> + +<p> +<tt><item></tt> can be one of the following: +<itemize> +<item><tt/core/ - limits the core file size (KB) +<item><tt/data/ - max data size (KB) +<item><tt/fsize/ - maximum filesize (KB) +<item><tt/memlock/ - max locked-in-memory address space (KB) +<item><tt/nofile/ - max number of open files +<item><tt/rss/ - max resident set size (KB) +<item><tt/stack/ - max stack size (KB) +<item><tt/cpu/ - max CPU time (MIN) +<item><tt/nproc/ - max number of processes +<item><tt/as/ - address space limit +<item><tt/maxlogins/ - max number of logins for this user. +<item><tt/priority/ - the priority to run user process with +</itemize> + +<p> +To completely disable limits for a user (or a group), a single dash +(-) will do (Example: ``<tt/bin -/'', ``<tt/@admin -/''). Please +remember that individual limits have priority over group limits, so if +you impose no limits for <tt/admin/ group, but one of the members in this +group have a limits line, the user will have its limits set according +to this line. + +<p> +Also, please note that all limit settings are set <em/per login/. +They are not global, nor are they permanent; existing only for the +duration of the session. + +<p> +In the <em/limits/ configuration file, the ``<tt/#/'' character +introduces a comment - after which the rest of the line is ignored. + +<p> +The <tt/pam_limits/ module does its best to report configuration +problems found in its configuration file via <tt/syslog(3)/. + +<p> +The following is an example configuration file: +<tscreen> +<verb> +# EXAMPLE /etc/security/limits.conf file: +# ======================================= +# <domain> <type> <item> <value> +* soft core 0 +* hard rss 10000 +@student hard nproc 20 +@faculty soft nproc 20 +@faculty hard nproc 50 +ftp hard nproc 0 +@student - maxlogins 4 +</verb> +</tscreen> +Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource +(see <tt/@faculty/) -- this establishes the <em/default/ and permitted +<em/extreme/ level of resources that the user can can obtain in a +given service-session. + +<p> +For the services that need resources limits (login for example) put a +the following line in <tt>/etc/pam.conf</tt> as the last line for that +service (usually after the pam_unix session line: +<tscreen> +<verb> +# +# Resource limits imposed on login sessions via pam_limits +# +login session required pam_limits.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml new file mode 100644 index 00000000..98589a3b --- /dev/null +++ b/doc/modules/pam_listfile.sgml @@ -0,0 +1,138 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The list-file module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_listfile/ + +<tag><bf>Author:</bf></tag> +Elliot Lee <tt><sopwith@cuc.edu></tt> + +<tag><bf>Maintainer:</bf></tag> +Red Hat Software:<newline> +Michael K. Johnson <johnsonm@redhat.com> 1996/11/18<newline> +(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +clean + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +The list-file module provides a way to deny or allow services based on +an arbitrary file. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt>onerr=succeed|fail</tt>; +<tt>sense=allow|deny</tt>; +<tt>file=</tt><it>filename</it>; +<tt>item=user|tty|rhost|ruser|group|shell</tt> +<tt>apply=user|@group</tt> + +<tag><bf>Description:</bf></tag> + +The module gets the item of the type specified -- <tt>user</tt> specifies +the username, <tt>PAM_USER</tt>; tty specifies the name of the terminal +over which the request has been made, <tt>PAM_TTY</tt>; rhost specifies +the name of the remote host (if any) from which the request was made, +<tt>PAM_RHOST</tt>; and ruser specifies the name of the remote user +(if available) who made the request, <tt>PAM_RUSER</tt> -- and looks for +an instance of that item in the file <it>filename</it>. <it>filename</it> +contains one line per item listed. If the item is found, then if +<tt>sense=allow</tt>, <tt>PAM_SUCCESS</tt> is returned, causing the +authorization request to succeed; else if <tt>sense=deny</tt>, +<tt>PAM_AUTH_ERR</tt> is returned, causing the authorization +request to fail. + +<p> +If an error is encountered (for instance, if <it>filename</it> +does not exist, or a poorly-constructed argument is encountered), +then if <tt>onerr=succeed</tt>, <tt>PAM_SUCCESS</tt> is returned, +otherwise if <tt>onerr=fail</tt>, <tt>PAM_AUTH_ERR</tt> or +<tt>PAM_SERVICE_ERR</tt> (as appropriate) will be returned. + +<p> +An additional argument, <tt>apply=</tt>, can be used to restrict the +application of the above to a specific user +(<tt>apply=</tt><em>username</em>) or a given group +(<tt>apply=@</tt><em>groupname</em>). This added restriction is only +meaningful when used with the <tt/tty/, <tt/rhost/ and <tt/shell/ +<em/items/. + +<p> +Besides this last one, all arguments should be specified; do not count +on any default behavior, as it is subject to change. + +<p> +No credentials are awarded by this module. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Classic ``ftpusers'' authentication can be implemented with this entry +in <tt>/etc/pam.conf</tt>: +<tscreen> +<verb> +# +# deny ftp-access to users listed in the /etc/ftpusers file +# +ftp auth required pam_listfile.so \ + onerr=succeed item=user sense=deny file=/etc/ftpusers +</verb> +</tscreen> +Note, users listed in <tt>/etc/ftpusers</tt> file are +(counterintuitively) <bf/not/ allowed access to the ftp service. + +<p> +To allow login access only for certain users, you can use an +pam.conf entry like this: +<tscreen> +<verb> +# +# permit login to users listed in /etc/loginusers +# +login auth required pam_listfile.so \ + onerr=fail item=user sense=allow file=/etc/loginusers +</verb> +</tscreen> + +<p> +For this example to work, all users who are allowed to use the login +service should be listed in the file <tt>/etc/loginusers</tt>. Unless +you are explicitly trying to lock out root, make sure that when you do +this, you leave a way for root to log in, either by listing root in +<tt>/etc/loginusers</tt>, or by listing a user who is able to <em/su/ +to the root account. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml new file mode 100644 index 00000000..064b9ffa --- /dev/null +++ b/doc/modules/pam_mail.sgml @@ -0,0 +1,137 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>The mail module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_mail/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (credential) +Session (open) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Default mail directory <tt>/var/spool/mail/</tt> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module looks at the user's mail directory and indicates +whether the user has any mail in it. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/dir=/<em/direcory-name/; <tt/nopen/; <tt/close/; +<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/; +<tt/quiet/; + +<tag><bf>Description:</bf></tag> + +This module provides the ``you have new mail'' service to the user. It +can be plugged into any application that has credential hooks. It gives a +single message indicating the <em/newness/ of any mail it finds in the +user's mail folder. This module also sets the <bf/Linux-PAM/ +environment variable, <tt/MAIL/, to the user's mail directory. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/dir=/<em/pathname/ +- look for the users' mail in an alternative directory given by +<em/pathname/. The default location for mail is +<tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is +prefixed by a `<tt/˜/', the directory is interpreted as +indicating a file in the user's home directory. + +<item><tt/nopen/ +- instruct the module to <em/not/ print any mail information when the +user's credentials are acquired. This flag is useful to get the <tt/MAIL/ +environment variable set, but to not display any information about it. + +<item><tt/close/ +- instruct the module to indicate if the user has any mail at the as +the user's credentials are revoked. + +<item><tt/noenv/ +- do not set the <tt/MAIL/ environment variable. + +<item><tt/empty/ +- indicate that the user's mail directory is empty if this is found to +be the case. + +<item><tt/hash=/<em/hashcount/ +- mail directory hash depth. For example, a <em/hashcount/ of 2 would +make the mailfile be <tt>/var/spool/mail/u/s/user</tt>. + +<item><tt/standard/ +- old style "You have..." format which doesn't show the mail spool being used. + this also implies "empty" + +<item><tt/quiet/ +- only report when there is new mail. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used to indicate that the user has new mail when +they <em/login/ to the system. Here is a sample entry for your +<tt>/etc/pam.conf</tt> file: +<tscreen> +<verb> +# +# do we have any mail? +# +login session optional pam_mail.so +</verb> +</tscreen> + +<p> +Note, some applications may perform this function themselves. In such +cases, this module is not necessary. + +</descrip> + +<sect2>Authentication compent + +<p> +Then authentication companent works the same as the session component, +expect that everything is done during the pam_setcred() phase. + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_mkhomedir.sgml b/doc/modules/pam_mkhomedir.sgml new file mode 100644 index 00000000..075e16f9 --- /dev/null +++ b/doc/modules/pam_mkhomedir.sgml @@ -0,0 +1,83 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Create home directories on initial login + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_mkhomedir/ + +<tag><bf>Author:</bf></tag> +Jason Gunthorpe <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/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml new file mode 100644 index 00000000..1f8fc393 --- /dev/null +++ b/doc/modules/pam_motd.sgml @@ -0,0 +1,77 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Output the motd file + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_motd/ + +<tag><bf>Author:</bf></tag> +Ben Collins <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 succesful +login. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/motd=motd-file-name/; + +<tag><bf>Description:</bf></tag> +This module allows you to have arbitrary motd's (message of the day) +output after a succesful login. By default this file is <em>/etc/motd</em>, +but is configurable to any file. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/motd/ +- the file to output if not using the default. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +login session pam_motd.so motd=/etc/motd + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml new file mode 100644 index 00000000..90564d89 --- /dev/null +++ b/doc/modules/pam_nologin.sgml @@ -0,0 +1,75 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The no-login module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_nologin/ + +<tag><bf>Author:</bf></tag> +Written by Michael K. Johnson <johnsonm@redhat.com><newline> +(based on code taken from a module written by Andrew G. Morgan +<morgan@parc.power.net>). + +<tag><bf>Maintainer:</bf></tag> +Michael K. Johnson <johnsonm@redhat.com> + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +1 warning about dropping const + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Provides standard Unix <em/nologin/ authentication. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Provides standard Unix <em/nologin/ authentication. If the file +<tt>/etc/nologin</tt> exists, only root is allowed to log in; other +users are turned away with an error message. All users (root or +otherwise) are shown the contents of <tt>/etc/nologin</tt>. + +<p> +If the file <tt>/etc/nologin</tt> does not exist, this module succeeds +silently. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In order to make this module effective, all login methods should +be secured by it. It should be used as a <tt>required</tt> +method listed before any <tt>sufficient</tt> methods in order to +get standard Unix nologin semantics. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml new file mode 100644 index 00000000..8b201b7c --- /dev/null +++ b/doc/modules/pam_permit.sgml @@ -0,0 +1,83 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The promiscuous module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_permit + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan, <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Linux-PAM maintainer. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> +VERY LOW. Use with extreme caution. + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is very dangerous. It should be used with extreme +caution. Its action is always to permit access. It does nothing else. + +<sect2>Account+Authentication+Password+Session components + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No matter what management group, the action of this module is to +simply return <tt/PAM_SUCCESS/ -- operation successful. + +<p> +In the case of authentication, the user's name will be acquired. Many +applications become confused if this name is unknown. + +<tag><bf>Examples/suggested usage:</bf></tag> + +It is seldom a good idea to use this module. However, it does have +some legitimate uses. For example, if the system-administrator wishes +to turn off the account management on a workstation, and at the same +time continue to allow logins, then she might use the following +configuration file entry for login: +<tscreen> +<verb> +# +# add this line to your other login entries to disable account +# management, but continue to permit users to log in... +# +login account required pam_permit.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml new file mode 100644 index 00000000..022cfe57 --- /dev/null +++ b/doc/modules/pam_pwdb.sgml @@ -0,0 +1,252 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>The Password-Database module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_pwdb + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> <newline> +and Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Authors. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires properly configured <tt/libpwdb/ + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is a pluggable replacement for the <tt/pam_unix_../ +modules. It uses the generic interface of the <em/Password Database/ +library +<tt><htmlurl +url="http://linux.kernel.org/morgan/libpwdb/index.html" +name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the accounting functions of this module +<tt/syslog(3)/ more information on its actions. (Remaining arguments +supported by the other functions of this module are silently ignored, +but others are logged as errors through <tt/syslog(3)/). + +Based on the following <tt/pwdb_element/s: +<tt/expire/; +<tt/last_change/; +<tt/max_change/; +<tt/defer_change/; +<tt/warn_change/, +this module performs the task of establishing the status of the user's +account and password. In the case of the latter, it may offer advice +to the user on changing their password or, through the +<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until +they have established a new password. The entries listed above are +documented in the <em/Password Database Library Guide/ (see pointer +above). Should the user's record not contain one or more of these +entries, the corresponding <em/shadow/ check is not performed. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In its accounting mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Ensure users account and password are still active +# +login account required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/use_first_pass/; +<tt/try_first_pass/; +<tt/nullok/; +<tt/nodelay/; +<tt/likeauth/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the authentication functions of this +module <tt/syslog(3)/ more information on its actions. + +<p> +The default action of this module is to not permit the user access to +a service if their <em/official/ password is blank. The <tt/nullok/ +argument overrides this default. + +<p> +When given the argument <tt/try_first_pass/, before prompting the user +for their password, the module first tries the previous stacked +<tt/auth/-module's password in case that satisfies this module as +well. The argument <tt/use_first_pass/ forces the module to use such a +recalled password and will never prompt the user - if no password is +available or the password is not appropriate, the user will be denied +access. + +<p> +The argument, <tt>nodelay</tt>, can be used to discourage the +authentication component from requesting a delay should the +authentication as a whole fail. The default action is for the module +to request a delay-on-failure of the order of one second. + +<p> +Remaining arguments, supported by the other functions of this module, +are silently ignored. Other arguments are logged as errors through +<tt/syslog(3)/. + +<p> +A helper binary, <tt>pwdb_chkpwd</tt>, is provided to check the user's +password when it is stored in a read protected database. This binary +is very simple and will only check the password of the user invoking +it. It is called transparently on behalf of the user by the +authenticating component of this module. In this way it is possible +for applications like <em>xlock</em> to work without being setuid-root. + +<p> +The <tt>likeauth</tt> argument makes the module return the same value +when called as a credential setting module and an authentication +module. This will help libpam take a sane path through the auth +component of your configuration file. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The correct functionality of this module is dictated by having an +appropriate <tt>/etc/pwdb.conf</tt> file, the user +databases specified there dictate the source of the authenticated +user's record. + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/; +<tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/; +<tt/shadow/; <tt/radius/; <tt/unix/ + +<tag><bf>Description:</bf></tag> + +This part of the <tt/pam_pwdb/ module performs the task of updating +the user's password. Thanks to the flexibility of <tt/libpwdb/ this +module is able to move the user's password from one database to +another, perhaps securing the user's database entry in a dynamic +manner (<em/this is very ALPHA code at the moment!/) - this is the +purpose of the <tt/shadow/, <tt/radius/ and <tt/unix/ arguments. + +<p> +In the case of conventional unix databases (which store the password +encrypted) the <tt/md5/ argument is used to do the encryption with the +MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. +As an alternative to this, the <tt/bigcrypt/ argument can be used to +encrypt more than the first 8 characters of a password with DEC's +(Digital Equipment Cooperation) `C2' extension to the standard UNIX +<tt/crypt()/ algorithm. + +<p> +The <tt/nullok/ module is used to permit the changing of a password +<em/from/ an empty one. Without this argument, empty passwords are +treated as account-locking ones. + +<p> +The argument <tt/use_first_pass/ is used to lock the choice of old and +new passwords to that dictated by the previously stacked <tt/password/ +module. The <tt/try_first_pass/ argument is used to avoid the user +having to re-enter an old password when <tt/pam_pwdb/ follows a module +that possibly shared the user's old password - if this old password is +not correct the user will be prompted for the correct one. The +argument <tt/use_authtok/ is used to <em/force/ this module to set the +new password to the one provided by the previously stacked +<tt/password/ module (this is used in an example of the stacking of +the <em/Cracklib/ module documented above). + +<p> +The <tt/not_set_pass/ argument is used to inform the module that it is +not to pay attention to/make available the old or new passwords from/to +other (stacked) password modules. + +<p> +The <tt/debug/ argument makes the password functions of this module +<tt/syslog(3)/ more information on its actions. Other arguments may be +logged as erroneous to <tt/syslog(3)/. + +<tag><bf>Examples/suggested usage:</bf></tag> + +An example of the stacking of this module with respect to the +pluggable password checking module, <tt/pam_cracklib/, is given in +that modules section above. +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No arguments are recognized by this module component. Its action is +simply to log the username and the service-type to +<tt/syslog(3)/. Messages are logged at the beginning and end of the +user's session. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of the session modules is straightforward: +<tscreen> +<verb> +# +# pwdb - unix like session opening and closing +# +login session required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml new file mode 100644 index 00000000..fb442ee3 --- /dev/null +++ b/doc/modules/pam_radius.sgml @@ -0,0 +1,117 @@ +<!-- + $Id$ + + This file was written by Cristian Gafton <gafton@redhat.com> +--> + +<sect1>The RADIUS session module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_radius/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +session + +<tag><bf>Cryptographically sensitive:</bf></tag> +This module does not deal with passwords + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +gcc reports 1 warning when compiling <tt>/usr/include/rpc/clnt.h</tt>. +Hey, is not my fault ! + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +yes; this is a network module (independent of application). + +</descrip> + +<sect2>Overview of module + +<p> +This module is intended to provide the session service for users +autheticated with a RADIUS server. At the present stage, the only +option supported is the use of the RADIUS server as an accounting +server. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/ - verbose logging to <tt/syslog(3)/. + +<tag><bf>Description:</bf></tag> + +This module is intended to provide the session service for users +autheticated with a RADIUS server. At the present stage, the only +option supported is the use of the RADIUS server as an <em/accounting/ +server. + +<p> +(There are few things which needs to be cleared out first in +the PAM project until one will be able to use this module and expect +it to magically start pppd in response to a RADIUS server command to +use PPP for this user, or to initiate a telnet connection to another +host, or to hang and call back the user using parameters provided in +the RADIUS server response. Most of these things are better suited for +the radius login application. I hope to make available Real Soon (tm) +patches for the login apps to make it work this way.) + +<p> +When opening a session, this module sends an ``Accounting-Start'' +message to the RADIUS server, which will log/update/whatever a +database for this user. On close, an ``Accounting-Stop'' message is +sent to the RADIUS server. + +<p> +This module has no other prerequisites for making it work. One can +install a RADIUS server just for fun and use it as a centralized +accounting server and forget about wtmp/last/sac etc. . + +<tag><bf>Examples/suggested usage:</bf></tag> + +For the services that need this module (<em/login/ for example) put +the following line in <tt>/etc/pam.conf</tt> as the last line for that +service (usually after the pam_unix session line): +<tscreen> +<verb> +login session required pam_radius.so +</verb> +</tscreen> +Replace <tt/login/ for each service you are using this module. + +<p> +This module make extensive use of the API provided in libpwdb +0.54preB or later. By default, it will read the radius server +configuration (hostname and secret) from <tt>/etc/raddb/server</tt>. +This is a default compiled into libpwdb, and curently there is no way to +modify this default without recompiling libpwdb. I am working on +extending the radius support from libpwdb to provide a possibility +to make this runtime-configurable. + +Also please note that libpwdb will require also the RADIUS +dictionary to be present (<tt>/etc/raddb/dictionary</tt>). + +</descrip> + +<!-- +End of sgml insert for this module. +--> + diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml new file mode 100644 index 00000000..00e55a9d --- /dev/null +++ b/doc/modules/pam_rhosts.sgml @@ -0,0 +1,164 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The rhosts module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_rhosts_auth/ + +<tag><bf>Author:</bf></tag> +Al Longyear <longyear@netcom.com> + +<tag><bf>Maintainer:</bf></tag> + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls. + +</descrip> + +<sect2>Overview of module + +<p> +This module performs the standard network authentication for services, +as used by traditional implementations of <em/rlogin/ and <em/rsh/ +etc. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/; +<tt/privategroup/; <tt/promiscuous/; <tt/suppress/ + +<tag><bf>Description:</bf></tag> + +The authentication mechanism of this module is based on the contents +of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in +<tt>#include <netdb.h></tt>) and <tt>~/.rhosts</tt>. Firstly, +hosts listed in the former file are treated as equivalent to the +localhost. Secondly, entries in the user's own copy of the latter file +is used to map "<tt/remote-host remote-user/" pairs to that user's +account on the current host. Access is granted to the user if their +host is present in <tt>/etc/hosts.equiv</tt> and their remote account +is identical to their local one, or if their remote account has an +entry in their personal configuration file. + +<p> +Some restrictions are applied to the attributes of the user's personal +configuration file: it must be a regular file (as defined by +<tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or +the user; it must not be writable by any user besides its owner. + +<p> +The module authenticates a remote user (internally specified by the +item <tt/PAM_RUSER/) connecting from the remote host (internally +specified by the item <tt/PAM_RHOST/). Accordingly, for applications +to be compatible this authentication module they must set these items +prior to calling <tt/pam_authenticate()/. The module is not capable +of independently probing the network connection for such information. + +<p> +In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is +<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option +should be used. Instead, the superuser must have a correctly configured +personal configuration file. + +<p> +The behavior of the module is modified by flags: +<itemize> +<item> +<tt/debug/ - +log more information to <tt/syslog(3)/. (XXX - actually, this module +does not do any logging currently, please volunteer to fix this!) + +<item> +<tt/no_warn/ - +do not give verbal warnings to the user about failures etc. (XXX - +this module currently does not issue any warnings, please volunteer to +fix this!) + +<item> +<tt/no_hosts_equiv/ - +ignore the contents of the <tt>/etc/hosts.equiv</tt> file. + +<item> +<tt/hosts_equiv_rootok/ - +allow the use of <tt>/etc/hosts.equiv</tt> for superuser. Without this +option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account. +This option has no effect if the <tt>no_hosts_equiv</tt> option is used. + +<item> +<tt/no_rhosts/ - +ignore the contents of all user's personal configuration file +<tt>~/.rhosts</tt>. + +<item> +<tt/privategroup/ - +normally, the <tt>~/.rhosts</tt> file must not be writable by anyone +other than its owner. This option overlooks group write access in the +case that the group owner of this file has the same name as the +user being authenticated. To lessen the security problems associated +with this option, the module also checks that the user is the only +member of their private group. + +<item> +<tt/promiscuous/ - +A host entry of `+' will lead to all hosts being granted +access. Without this option, '+' entries will be ignored. Note, that +the <tt/debug/ option will syslog a warning in this latter case. + +<item> +<tt/suppress/ - +This will prevent the module from <tt/syslog(3)/ing a warning message +when this authentication fails. This option is mostly for keeping +logs free of meaningless errors, in particular when the module is used +with the <tt/sufficient/ control flag. + +</itemize> +<tag><bf>Examples/suggested usage:</bf></tag> + +To allow users to login from trusted remote machines, you should try +adding the following line to your <tt>/etc/pam.conf</tt> file +<em/before/ the line that would otherwise prompt the user for a +password: +<tscreen> +<verb> +# +# No passwords required for users from hosts listed above. +# +login auth sufficient pam_rhosts_auth.so no_rhosts +</verb> +</tscreen> +Note, in this example, the system administrator has turned off all +<em/personal/ <em/rhosts/ configuration files. Also note, that this module +can be used to <em/only/ allow remote login from hosts specified in +the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the +above example with <tt/required/. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml new file mode 100644 index 00000000..e362a2a5 --- /dev/null +++ b/doc/modules/pam_rootok.sgml @@ -0,0 +1,85 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The root access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_rootok + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +<bf>Linux-PAM</bf> maintainer + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is for use in situations where the superuser wishes +to gain access to a service without having to enter a password. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/ + +<tag><bf>Description:</bf></tag> + +This module authenticates the user if their <tt/uid/ is <tt/0/. +Applications that are created <em/setuid/-root generally retain the +<tt/uid/ of the user but run with the authority of an enhanced +<em/effective-/<tt/uid/. It is the real <tt/uid/ that is checked. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In the case of the <tt/su/ application the historical usage is to +permit the superuser to adopt the identity of a lesser user without +the use of a password. To obtain this behavior under <tt/Linux-PAM/ +the following pair of lines are needed for the corresponding entry in +the configuration file: +<tscreen> +<verb> +# +# su authentication. Root is granted access by default. +# +su auth sufficient pam_rootok.so +su auth required pam_unix_auth.so +</verb> +</tscreen> + +<p> +Note. For programs that are run by the superuser (or started when the +system boots) this module should not be used to authenticate users. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_securetty.sgml b/doc/modules/pam_securetty.sgml new file mode 100644 index 00000000..ceb1358c --- /dev/null +++ b/doc/modules/pam_securetty.sgml @@ -0,0 +1,72 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The securetty module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_securetty/ + +<tag><bf>Author[s]:</bf></tag> +Elliot Lee <sopwith@cuc.edu> + +<tag><bf>Maintainer:</bf></tag> +Red Hat Software:<newline> +<em/currently/ Michael K. Johnson <johnsonm@redhat.com><newline> +(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +<tt>/etc/securetty</tt> file + +<tag><bf>Network aware:</bf></tag> + +Requires the application to fill in the <tt>PAM_TTY</tt> item +correctly in order to act meaningfully. + +</descrip> + +<sect2>Overview of module + +<p> +Provides standard Unix securetty checking. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Provides standard Unix securetty checking, which causes authentication +for root to fail unless <tt>PAM_TTY</tt> is set to a string listed in +the <tt>/etc/securetty</tt> file. For all other users, it succeeds. + +<tag><bf>Examples/suggested usage:</bf></tag> + +For canonical usage, should be listed as a <tt>required</tt> +authentication method before any <tt>sufficient</tt> authentication +methods. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml new file mode 100644 index 00000000..4104aad1 --- /dev/null +++ b/doc/modules/pam_time.sgml @@ -0,0 +1,166 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>Time control + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_time/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <tt><morgan@parc.power.net></tt> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +account + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires a configuration file <tt>/etc/security/time.conf</tt> + +<tag><bf>Network aware:</bf></tag> +Through the <tt/PAM_TTY/ item only + +</descrip> + +<sect2>Overview of module + +<p> +Running a well regulated system occasionally involves restricting +access to certain services in a selective manner. This module offers +some time control for access to services offered by a system. Its +actions are determined with a configuration file. This module can be +configured to deny access to (individual) users based on their name, +the time of day, the day of week, the service they are applying for +and their terminal from which they are making their request. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module bases its actions on the rules listed in its configuration +file: <tt>/etc/security/pam.conf</tt>. Each rule has the following +form, +<tscreen> +<em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/ +</tscreen> +In words, each rule occupies a line, terminated with a newline or the +beginning of a comment; a `<tt/#/'. It contains four fields separated +with semicolons, `<tt/;/'. The fields are as follows: + +<p> +<itemize> +<item><em/services/ - +a logic list of service names that are affected by this rule. + +<item><em/ttys/ - +a logic list of terminal names indicating those terminals covered by +the rule. + +<item><em/user/ - +a logic list of usernames to which this rule applies + +<p> +By a logic list we mean a sequence of tokens (associated with the +appropriate <tt/PAM_/ item), containing no more than one wildcard +character; `<tt/*/', and optionally prefixed with a negation operator; +`<tt/!/'. Such a sequence is concatenated with one of two logical +operators: <tt/&/ (logical AND) and <tt/|/ (logical OR). Two +examples are: <tt>!morgan&!root</tt>, indicating that this rule +does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and +<tt>tty*&!ttyp*</tt>, which indicates that the rule applies only +to console terminals but not pseudoterminals. + +<item><em/times/ - a logic list of times at which this rule +applies. The format of each element is a day/time-range. The days are +specified by a sequence of two character entries. For example, +<tt/MoTuSa/, indicates Monday Tuesday and Saturday. Note that +repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and +<tt/MoWk/ means all weekdays bar Monday. The two character +combinations accepted are, +<tscreen> +<verb> +Mo Tu We Th Fr Sa Su Wk Wd Al +</verb> +</tscreen> +The last two of these being <em/weekend/ days and <em/all 7 days/ of +the week respectively. + +<p> +The time range part is a pair of 24-hour times, <em/HHMM/, separated +by a hyphen -- indicating the start and finish time for the rule. If +the finsish time is smaller than the start time, it is assumed to +apply on the following day. For an example, <tt/Mo1800-0300/ indicates +that the permitted times are Monday night from 6pm to 3am the +following morning. + +</itemize> + +<p> +Note, that the given time restriction is only applied when the first +three fields are satisfied by a user's application for service. + +<p> +For convenience and readability a rule can be extended beyond a single +line with a `<tt>\</tt><em/newline/'. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of this module is initiated with an entry in the +<bf/Linux-PAM/ configuration file of the following type: +<tscreen> +<verb> +# +# apply pam_time accounting to login requests +# +login account required pam_time.so +</verb> +</tscreen> +where, here we are applying the module to the <em/login/ application. + +<p> +Some examples of rules that can be placed in the +<tt>/etc/security/time.conf</tt> configuration file are the following: +<descrip> + +<tag><tt>login ; tty* & ; !ttyp* ; !root ; !Al0000-2400</tt></tag> +all users except for <tt/root/ are denied access to console-login at +all times. + +<tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag> +games (configured to use Linux-PAM) are only to be accessed out of +working hours. This rule does not apply to the user <tt/waster/. + +</descrip> + +<p> +Note, currently there is no daemon enforcing the end of a session. +This needs to be remedied. + +<p> +Poorly formatted rules are logged as errors using <tt/syslog(3)/. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml new file mode 100644 index 00000000..792362ed --- /dev/null +++ b/doc/modules/pam_unix.sgml @@ -0,0 +1,289 @@ +<!-- + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> + + Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org> +--> + +<sect1>The Unix Password module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_unix + +<tag><bf>Author:</bf></tag> + +<tag><bf>Maintainer:</bf></tag> +Authors. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This is the standard Unix authentication module. It uses standard calls +from the system's libraries to retrieve and set account information as +well as authentication. Usually this is obtained from the /etc/passwd +and the /etc/shadow file aswell if shadow is enabled. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/audit/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the accounting functions of this module +<tt/syslog(3)/ more information on its actions. (Remaining arguments +supported by the other functions of this module are silently ignored, +but others are logged as errors through <tt/syslog(3)/). The <tt/audit/ +argument causes even more logging. + +Based on the following <tt/shadow/ elements: +<tt/expire/; +<tt/last_change/; +<tt/max_change/; +<tt/min_change/; +<tt/warn_change/, +this module performs the task of establishing the status of the user's +account and password. In the case of the latter, it may offer advice +to the user on changing their password or, through the +<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until +they have established a new password. The entries listed above are +documented in the <em/GNU Libc/ info documents. Should the user's record +not contain one or more of these entries, the corresponding <em/shadow/ +check is not performed. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In its accounting mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Ensure users account and password are still active +# +login account required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/use_first_pass/; +<tt/try_first_pass/; +<tt/nullok/; +<tt/nodelay/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the authentication functions of this +module <tt/syslog(3)/ more information on its actions. The <tt/audit/ +causes even more information to be logged. + +<p> +The default action of this module is to not permit the user access to +a service if their <em/official/ password is blank. The <tt/nullok/ +argument overrides this default. + +<p> +When given the argument <tt/try_first_pass/, before prompting the user +for their password, the module first tries the previous stacked +<tt/auth/-module's password in case that satisfies this module as +well. The argument <tt/use_first_pass/ forces the module to use such a +recalled password and will never prompt the user - if no password is +available or the password is not appropriate, the user will be denied +access. + +<p> +The argument, <tt>nodelay</tt>, can be used to discourage the +authentication component from requesting a delay should the +authentication as a whole fail. The default action is for the module +to request a delay-on-failure of the order of one second. + +<p> +Remaining arguments, supported by the other functions of this module, +are silently ignored. Other arguments are logged as errors through +<tt/syslog(3)/. + +<p> +A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's +password when it is stored in a read protected database. This binary +is very simple and will only check the password of the user invoking +it. It is called transparently on behalf of the user by the +authenticating component of this module. In this way it is possible +for applications like <em>xlock</em> to work without being setuid-root. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The correct functionality of this module is dictated by having an +appropriate <tt>/etc/nsswitch.conf</tt> file, the user +databases specified there dictate the source of the authenticated +user's record. +<p> +In its authentication mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Authenticate the user +# +login auth required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/nullok/; +<tt/not_set_pass/; +<tt/use_authtok/; +<tt/try_first_pass/; +<tt/use_first_pass/; +<tt/md5/; +<tt/bigcrypt/; +<tt/shadow/; +<tt/nis/; +<tt/remember/ + +<tag><bf>Description:</bf></tag> + +This part of the <tt/pam_unix/ module performs the task of updating +the user's password. + +<p> +In the case of conventional unix databases (which store the password +encrypted) the <tt/md5/ argument is used to do the encryption with the +MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. +As an alternative to this, the <tt/bigcrypt/ argument can be used to +encrypt more than the first 8 characters of a password with DEC's +(Digital Equipment Cooperation) `C2' extension to the standard UNIX +<tt/crypt()/ algorithm. + +<p> +The <tt/nullok/ argument is used to permit the changing of a password +<em/from/ an empty one. Without this argument, empty passwords are +treated as account-locking ones. + +<p> +The argument <tt/use_first_pass/ is used to lock the choice of old and +new passwords to that dictated by the previously stacked <tt/password/ +module. The <tt/try_first_pass/ argument is used to avoid the user +having to re-enter an old password when <tt/pam_unix/ follows a module +that possibly shared the user's old password - if this old password is +not correct the user will be prompted for the correct one. The +argument <tt/use_authtok/ is used to <em/force/ this module to set the +new password to the one provided by the previously stacked +<tt/password/ module (this is used in an example of the stacking of +the <em/Cracklib/ module documented above). + +<p> +The <tt/not_set_pass/ argument is used to inform the module that it is +not to pay attention to/make available the old or new passwords from/to +other (stacked) password modules. + +<p> +The <tt/debug/ argument makes the password functions of this module +<tt/syslog(3)/ more information on its actions. Other arguments may be +logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes +even more information to be logged. + +<p> +With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC +for setting new passwords. + +<p> +The <tt/remember/ argument takes one value. This is the number of most +recent passwords to save for each user. These are saved in +<tt>/etc/security/opasswd</tt> in order to force password change history +and keep the user from alternating between the same password too frequently. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Standard usage: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_unix.so +</verb> +</tscreen> + +<p> +An example of the stacking of this module with respect to the +pluggable password checking module, <tt/pam_cracklib/: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_cracklib.so retry=3 minlen=6 difok=3 +passwd password required pam_unix.so use_authtok nullok md5 +</verb> +</tscreen> + +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No arguments are recognized by this module component. Its action is +simply to log the username and the service-type to +<tt/syslog(3)/. Messages are logged at the beginning and end of the +user's session. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of the session modules is straightforward: +<tscreen> +<verb> +# +# session opening and closing +# +login session required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_userdb.sgml b/doc/modules/pam_userdb.sgml new file mode 100644 index 00000000..bdbf80b8 --- /dev/null +++ b/doc/modules/pam_userdb.sgml @@ -0,0 +1,112 @@ +<!-- + This file was written by Cristian Gafton <gafton@redhat.com> +--> + +<sect1>The userdb module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_userdb/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <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/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml new file mode 100644 index 00000000..2ca4cc82 --- /dev/null +++ b/doc/modules/pam_warn.sgml @@ -0,0 +1,67 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>Warning logger module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_warn/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication; password + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +logs information about the remote user and host (if pam-items are known) + +</descrip> + +<sect2>Overview of module + +<p> +This module is principally for logging information about a +proposed authentication or application to update a password. + +<sect2>Authentication+Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Log the service, terminal, user, remote user and remote host to +<tt/syslog(3)/. The items are not probed for, but instead obtained +from the standard pam-items. + +<tag><bf>Examples/suggested usage:</bf></tag> + +an example is provided in the configuration file section <ref +id="configuration" name="above">. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml new file mode 100644 index 00000000..1eb62743 --- /dev/null +++ b/doc/modules/pam_wheel.sgml @@ -0,0 +1,125 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + from notes provided by Cristian Gafton. +--> + +<sect1>The wheel module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_wheel/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <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 libpwdb. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Only permit root access to members of the wheel (<tt/gid=0/) group. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/use_uid/; +<tt/trust/; +<tt/deny/; +<tt/group=XXXX/ + +<tag><bf>Description:</bf></tag> + +This module is used to enforce the so-called <em/wheel/ group. By +default, it permits root access to the system if the applicant user is +a member of the <tt/wheel/ group (first, the module checks for the +existence of a '<tt/wheel/' group. Otherwise the module defines the +group with group-id <tt/0/ to be the <em/wheel/ group). + +<p> +The action of the module may be modified from this default by one or +more of the following flags in the <tt>/etc/pam.conf</tt> file. +<itemize> +<item> +<tt/debug/ - +Supply more debugging information to <tt/syslog(3)/. + +<item> +<tt/use_uid/ - +This option modifies the behavior of the module by using the current +<tt/uid/ of the process and not the <tt/getlogin(3)/ name of the user. +This option is useful for being able to jump from one account to +another, for example with 'su'. + +<item> +<tt/trust/ - +This option instructs the module to return <tt/PAM_SUCCESS/ should it +find the user applying for root privilege is a member of the wheel +group. The default action is to return <tt/PAM_IGNORE/ in this +situation. By using the <tt/trust/ option it is possible to arrange +for <tt/wheel/-group members to become root without typing a +password. <bf/USE WITH CARE/. + +<item> +<tt/deny/ - +This is used to reverse the logic of the module's behavior. +If the user is trying to get <tt/uid=0/ access and is a member of the wheel +group, deny access (for the wheel group, this is perhaps nonsense!): +it is intended for use in conjunction with the <tt/group=/ argument... + +<item> +<tt/group=XXXX/ - +Instead of checking the <tt/gid=0/ group, use the user's <tt/XXXX/ +group membership for the authentication. Here, <tt/XXXX/ is the name +of the group and <bf/not/ its numeric identifier. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +To restrict access to superuser status to the members of the +<tt/wheel/ group, use the following entries in your configuration +file: +<tscreen> +<verb> +# +# root gains access by default (rootok), only wheel members can +# become root (wheel) but Unix authenticate non-root applicants. +# +su auth sufficient pam_rootok.so +su auth required pam_wheel.so +su auth required pam_unix_auth.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml new file mode 100644 index 00000000..d1be8c15 --- /dev/null +++ b/doc/pam_appl.sgml @@ -0,0 +1,1643 @@ +<!doctype linuxdoc system> + +<!-- + + $Id$ + + Copyright (C) Andrew G. Morgan 1996-9. All rights reserved. + +Redistribution and use in source (sgml) and binary (derived) forms, +with or without modification, are permitted provided that the +following conditions are met: + +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +ALTERNATIVELY, this product may be distributed under the terms of the +GNU General Public License, in which case the provisions of the GNU +GPL are required INSTEAD OF the above restrictions. (This clause is +necessary due to a potential bad interaction between the GNU GPL and +the restrictions contained in a BSD-style copyright.) + +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + + --> + +<article> + +<title>The Linux-PAM Application Developers' Guide +<author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> +<date>DRAFT v0.71 1999/11/8 +<abstract> +This manual documents what an application developer needs to know +about the <bf>Linux-PAM</bf> library. It describes how an application +might use the <bf>Linux-PAM</bf> library to authenticate users. In +addition it contains a description of the funtions to be found in +<tt/libpam_misc/ library, that can be used in general applications. +Finally, it contains some comments on PAM related security issues for +the application developer. +</abstract> + +<toc> + +<sect>Introduction + +<sect1>Synopsis + +<p> +For general applications that wish to use the services provided by +<bf/Linux-PAM/ the following is a summary of the relevant linking +information: +<tscreen> +<verb> +#include <security/pam_appl.h> + +cc -o application .... -lpam -ldl +</verb> +</tscreen> + +<p> +In addition to <tt/libpam/, there is a library of miscellaneous +functions that make the job of writing <em/PAM-aware/ applications +easier (this library is not covered in the DCE-RFC for PAM and is +specific to the Linux-PAM distribution): +<tscreen> +<verb> +... +#include <security/pam_misc.h> + +cc -o application .... -lpam -lpam_misc -ldl +</verb> +</tscreen> + +<sect1> Description + +<p> +<bf>Linux-PAM</bf> (Pluggable Authentication Modules for Linux) is a +library that enables the local system administrator to choose how +individual applications authenticate users. For an overview of the +<bf>Linux-PAM</bf> library see the <bf/Linux-PAM/ System +Administrators' Guide. + +<p> +It is the purpose of the <bf>Linux-PAM</bf> project to liberate the +development of privilege granting software from the development of +secure and appropriate authentication schemes. This is accomplished +by providing a documented library of functions that an application may +use for all forms of user authentication management. This library +dynamically loads locally configured authentication modules that +actually perform the authentication tasks. + +<p> +From the perspective of an application developer the information +contained in the local configuration of the PAM library should not be +important. Indeed it is intended that an application treat the +functions documented here as a ``black box'' that will deal with all +aspects of user authentication. ``All aspects'' includes user +verification, account management, session initialization/termination +and also the resetting of passwords (<em/authentication tokens/). + +<sect>Overview + +<p> +Most service-giving applications are restricted. In other words, +their service is not available to all and every prospective client. +Instead, the applying client must jump through a number of hoops to +convince the serving application that they are authorized to obtain +service. + +The process of <em/authenticating/ a client is what PAM is designed to +manage. In addition to authentication, PAM provides account +management, credential management, session management and +authentication-token (password changing) management services. It is +important to realize when writing a PAM based application that these +services are provided in a manner that is <bf>transparent</bf> to the +the application. That is to say, when the application is written, no +assumptions can be made about <em>how</em> the client will be +authenticated. + +<p> +The process of authentication is performed by the PAM library via a +call to <tt>pam_authenticate()</tt>. The return value of this +function will indicate whether a named client (the <em>user</em>) has +been authenticated. If the PAM library needs to prompt the user for +any information, such as their <em>name</em> or a <em>password</em> +then it will do so. If the PAM library is configured to authenticate +the user using some silent protocol, it will do this too. (This +latter case might be via some hardware interface for example.) + +<p> +It is important to note that the application must leave all decisions +about when to prompt the user at the discretion of the PAM library. + +<p> +The PAM library, however, must work equally well for different styles +of application. Some applications, like the familiar <tt>login</tt> +and <tt>passwd</tt> are terminal based applications, exchanges of +information with the client in these cases is as plain text messages. +Graphically based applications, however, have a more sophisticated +interface. They generally interact with the user via specially +constructed dialogue boxes. Additionally, network based services +require that text messages exchanged with the client are specially +formatted for automated processing: one such example is <tt>ftpd</tt> +which prefixes each exchanged message with a numeric identifier. + +<p> +The presentation of simple requests to a client is thus something very +dependent on the protocol that the serving application will use. In +spite of the fact that PAM demands that it drives the whole +authentication process, it is not possible to leave such protocol +subtleties up to the PAM library. To overcome this potential problem, +the application provides the PAM library with a <em>conversation</em> +function. This function is called from <bf>within</bf> the PAM +library and enables the PAM to directly interact with the client. The +sorts of things that this conversation function must be able to do are +prompt the user with text and/or obtain textual input from the user +for processing by the PAM library. The details of this function are +provided in a later section. + +<p> +For example, the conversation function may be called by the PAM library +with a request to prompt the user for a password. Its job is to +reformat the prompt request into a form that the client will +understand. In the case of <tt>ftpd</tt>, this might involve prefixing +the string with the number <tt>331</tt> and sending the request over +the network to a connected client. The conversation function will +then obtain any reply and, after extracting the typed password, will +return this string of text to the PAM library. Similar concerns need +to be addressed in the case of an X-based graphical server. + +<p> +There are a number of issues that need to be addressed when one is +porting an existing application to become PAM compliant. A section +below has been devoted to this: Porting legacy applications. + +<p> +Besides authentication, PAM provides other forms of management. +Session management is provided with calls to +<tt>pam_open_session()</tt> and <tt>pam_close_session()</tt>. What +these functions actually do is up to the local administrator. But +typically, they could be used to log entry and exit from the system or +for mounting and unmounting the user's home directory. If an +application provides continuous service for a period of time, it +should probably call these functions, first open after the user is +authenticated and then close when the service is terminated. + +<p> +Account management is another area that an application developer +should include with a call to <tt/pam_acct_mgmt()/. This call will +perform checks on the good health of the user's account (has it +expired etc.). One of the things this function may check is whether +the user's authentication token has expired - in such a case the +application may choose to attempt to update it with a call to +<tt/pam_chauthtok()/, although some applications are not suited to +this task (<em>ftp</em> for example) and in this case the application +should deny access to the user. + +<p> +PAM is also capable of setting and deleting the users credentials with +the call <tt>pam_setcred()</tt>. This function should always be +called after the user is authenticated and before service is offered +to the user. By convention, this should be the last call to the PAM +library before service is given to the user. What exactly a +credential is, is not well defined. However, some examples are given +in the glossary below. + +<sect>The public interface to <bf>Linux-PAM</bf> + +<p> +Firstly, the relevant include file for the <bf>Linux-PAM</bf> library +is <tt><security/pam_appl.h></tt>. It contains the definitions +for a number of functions. After listing these functions, we collect +some guiding remarks for programmers. + +<sect1>What can be expected by the application + +<p> +Below we document those functions in the <bf/Linux-PAM/ library that +may be called from an application. + +<sect2>Initialization of Linux-PAM +<label id="pam-start-section"> + +<p> +<tscreen> +<verb> +extern int pam_start(const char *service_name, const char *user, + const struct pam_conv *pam_conversation, + pam_handle_t **pamh); +</verb> +</tscreen> + +<p> +This is the first of the <bf>Linux-PAM</bf> functions that must be +called by an application. It initializes the interface and reads the +system configuration file, <tt>/etc/pam.conf</tt> (see the +<bf/Linux-PAM/ System Administrators' Guide). Following a successful +return (<tt/PAM_SUCCESS/) the contents of <tt/*pamh/ is a handle that +provides continuity for successive calls to the <bf/Linux-PAM/ +library. The arguments expected by <tt/pam_start/ are as follows: the +<tt/service_name/ of the program, the <tt/user/name of the individual +to be authenticated, a pointer to an application-supplied +<tt/pam_conv/ structure and a pointer to a <tt/pam_handle_t/ +<em/pointer/. + +<p> +The <tt>pam_conv</tt> structure is discussed more fully in the section +<ref id="the-conversation-function" name="below">. The +<tt>pam_handle_t</tt> is a <em>blind</em> structure and the +application should not attempt to probe it directly for information. +Instead the <bf>Linux-PAM</bf> library provides the functions +<tt>pam_set_item</tt> and <tt>pam_get_item</tt>. These functions are +documented below. + +<sect2>Termination of the library +<label id="pam-end-section"> + +<p> +<tscreen> +<verb> +extern int pam_end(pam_handle_t *pamh, int pam_status); +</verb> +</tscreen> + +<p> +This function is the last function an application should call in the +<bf>Linux-PAM</bf> library. Upon return the handle <tt/pamh/ is no +longer valid and all memory associated with it will be invalid (likely +to cause a segmentation fault if accessed). + +<p> +Under normal conditions the argument <tt/pam_status/ has the value +PAM_SUCCESS, but in the event of an unsuccessful service application +the approprite <bf/Linux-PAM/ error-return value should be used +here. +attempt its purpose is to be passed as an argument to the +module specific function <tt/cleanup()/ (see the <bf/Linux-PAM/ +<htmlurl url="pam_modules.html" name="Module Developers' Guide">). + +<sect2>Setting PAM items +<label id="pam-set-item-section"> + +<p> +<tscreen> +<verb> +extern int pam_set_item(pam_handle_t *pamh, int item_type, + const void *item); +</verb> +</tscreen> + +<p>This function is used to (re)set the value of one of the following +<bf/item_type/s: + +<p><descrip> +<tag><tt/PAM_SERVICE/</tag> + The service name + +<tag><tt/PAM_USER/</tag> + The user name + +<tag><tt/PAM_TTY/</tag> + The terminal name: prefixed by <tt>/dev/</tt> if it is a +device file; for graphical, X-based, applications the value for this +item should be the <tt/$DISPLAY/ variable. + +<tag><tt/PAM_RHOST/</tag> + The remote host name + +<tag><tt/PAM_CONV/</tag> + The conversation structure (see section <ref +id="the-conversation-function" name="below">) + +<tag><tt/PAM_RUSER/</tag> + The remote user name + +<tag><tt/PAM_USER_PROMPT/</tag> + The string used when prompting for a user's name. The default +value for this string is ``Please enter username: ''. + +</descrip> + +<p> +For all <tt/item_type/s, other than <tt/PAM_CONV/, <tt/item/ is a +pointer to a <tt><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">). + +<p> +A successful call to this function returns <tt/PAM_SUCCESS/. However, +the application should expect one of the following errors: + +<p> +<descrip> +<tag><tt/PAM_PERM_DENIED/</tag> + An attempt was made to replace the conversation structure with +a <tt/NULL/ value. +<tag><tt/PAM_BUF_ERR/</tag> + The function ran out of memory making a copy of the item. +<tag><tt/PAM_BAD_ITEM/</tag> + The application attempted to set an undefined item. +</descrip> + +<sect2>Getting PAM items +<label id="pam-get-item-section"> + +<p> +<tscreen> +<verb> +extern int pam_get_item(const pam_handle_t *pamh, int item_type, + const void **item); +</verb> +</tscreen> + +<p> +This function is used to obtain the value of the indicated +<tt/item_type/. Upon successful return, <tt/*item/ contains a pointer +to the value of the corresponding item. Note, this is a pointer to +the <em/actual/ data and should <em/not/ be <tt/free()/'ed or +over-written! A successful call is signaled by a return value of +<tt/PAM_SUCCESS/. If an attempt is made to get an undefined item, +<tt/PAM_BAD_ITEM/ is returned. + +<sect2>Understanding errors +<label id="pam-strerror-section"> + +<p> +<tscreen> +<verb> +extern const char *pam_strerror(pam_handle_t *pamh, int errnum); +</verb> +</tscreen> + +<p> +This function returns some text describing the <bf>Linux-PAM</bf> +error associated with the argument <tt/errnum/. If the error is not +recognized ``<tt/Unknown Linux-PAM error/'' is returned. + +<sect2>Planning for delays + +<p> +<tscreen> +<verb> +extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec); +</verb> +</tscreen> + +<p> +This function is offered by <bf/Linux-PAM/ to facilitate time delays +following a failed call to <tt/pam_authenticate()/ and before control +is returned to the application. When using this function the +application programmer should check if it is available with, +<tscreen> +<verb> +#ifdef HAVE_PAM_FAIL_DELAY + .... +#endif /* HAVE_PAM_FAIL_DELAY */ +</verb> +</tscreen> + + +<p> +Generally, an application requests that a user is authenticated by +<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or +<tt/pam_chauthtok()/. These functions call each of the <em/stacked/ +authentication modules listed in the relevant <bf/Linux-PAM/ +configuration file. As directed by this file, one of more of the +modules may fail causing the <tt/pam_...()/ call to return an error. +It is desirable for there to also be a pause before the application +continues. The principal reason for such a delay is security: a delay +acts to discourage <em/brute force/ dictionary attacks primarily, but +also helps hinder <em/timed/ (covert channel) attacks. + +<p> +The <tt/pam_fail_delay()/ function provides the mechanism by which an +application or module can suggest a minimum delay (of <tt/micro_sec/ +<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time +requested with this function. Should <tt/pam_authenticate()/ fail, +the failing return to the application is delayed by an amount of time +randomly distributed (by up to 25%) about this longest value. + +<p> +Independent of success, the delay time is reset to its zero default +value when <bf/Linux-PAM/ returns control to the application. + +<p> +For applications written with a single thread that are event driven in +nature, <tt/libpam/ generating this dalay may be undesirable. Instead, +the application may want to register the delay in some other way. For +example, in a single threaded server that serves multiple +authentication requests from a single event loop, the application +might want to simply mark a given connection as blocked until an +application timer expires. For this reason, <bf/Linux-PAM/ supplies +the <tt/PAM_FAIL_DELAY/ item. It can be queried and set with +<tt/pam_get_item()/ and <tt/pam_set_item()/ respectively. The value +used to set it should be a function pointer of the following +prototype: + +<tscreen> +<verb> +void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr); +</verb> +</tscreen> + +The arguments being the <tt/retval/ return code of the module stack, +the <tt/usec_delay/ micro-second delay that libpam is requesting and +the <tt/appdata_ptr/ that the application has associated with the +current <tt/pamh/ (/tt/pam_handle_t/). This last value was set by the +application when it called <tt/pam_start/ or explicitly with +<tt/pam_set_item(... , PAM_CONV, ...)/. Note, if <tt/PAM_FAIL_DELAY/ +is unset (or set to <tt/NULL/), then <tt/libpam/ will perform any +delay. + +<sect2>Authenticating the user + +<p> +<tscreen> +<verb> +extern int pam_authenticate(pam_handle_t *pamh, int flags); +</verb> +</tscreen> + +<p> +This function serves as an interface to the authentication mechanisms +of the loaded modules. The single <em/optional/ flag, which may be +logically OR'd with <tt/PAM_SILENT/, takes the following value, + +<p><descrip> + +<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag> + Instruct the authentication modules to return +<tt/PAM_AUTH_ERR/ if the user does not have a registered +authorization token---it is set to <tt/NULL/ in the system database. +</descrip> + +<p> +The value returned by this function is one of the following: + +<p><descrip> + +<tag><tt/PAM_AUTH_ERR/</tag> + The user was not authenticated +<tag><tt/PAM_CRED_INSUFFICIENT/</tag> + For some reason the application does not have sufficient +credentials to authenticate the user. +<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag> + The modules were not able to access the authentication +information. This might be due to a network or hardware failure etc. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The supplied username is not known to the authentication +service +<tag><tt/PAM_MAXTRIES/</tag> + One or more of the authentication modules has reached its +limit of tries authenticating the user. Do not try again. + +</descrip> + +<p> +If one or more of the authentication modules fails to load, for +whatever reason, this function will return <tt/PAM_ABORT/. + +<sect2>Setting user credentials +<label id="pam-setcred-section"> + +<p> +<tscreen> +<verb> +extern int pam_setcred(pam_handle_t *pamh, int flags); +</verb> +</tscreen> + +<p> +This function is used to set the module-specific credentials of the +user. It is usually called after the user has been authenticated, +after the account management function has been called and after a +session has been opened for the user. + +<p> +A credential is something that the user possesses. It is some +property, such as a <em>Kerberos</em> ticket, or a supplementary group +membership that make up the uniqueness of a given user. On a Linux +(or UN*X system) the user's <tt>UID</tt> and <tt>GID</tt>'s are +credentials too. However, it has been decided that these properties +(along with the default supplementary groups of which the user is a +member) are credentials that should be set directly by the application +and not by PAM. + +<p> +This function simply calls the <tt/pam_sm_setcred/ functions of each +of the loaded modules. Valid <tt/flags/, any one of which, may be +logically OR'd with <tt/PAM_SILENT/, are: + +<p><descrip> +<tag><tt/PAM_ESTABLISH_CRED/</tag> + Set the credentials for the authentication service, +<tag><tt/PAM_DELETE_CRED/</tag> + Delete the credentials associated with the authentication service, +<tag><tt/PAM_REINITIALIZE_CRED/</tag> + Reinitialize the user credentials, and +<tag><tt/PAM_REFRESH_CRED/</tag> + Extend the lifetime of the user credentials. +</descrip> + +<p> +A successful return is signalled with <tt/PAM_SUCCESS/. Errors that +are especially relevant to this function are the following: + +<p><descrip> +<tag><tt/PAM_CRED_UNAVAIL/</tag> + A module cannot retrieve the user's credentials. +<tag><tt/PAM_CRED_EXPIRED/</tag> + The user's credentials have expired. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to an authentication module. +<tag><tt/PAM_CRED_ERR/</tag> + A module was unable to set the credentials of the user. +</descrip> + +<sect2>Account management + +<p> +<tscreen> +<verb> +extern int pam_acct_mgmt(pam_handle_t *pamh, int flags); +</verb> +</tscreen> + +<p> +This function is typically called after the user has been +authenticated. It establishes whether the user's account is healthy. +That is to say, whether the user's account is still active and whether +the user is permitted to gain access to the system at this time. +Valid flags, any one of which, may be logically OR'd with +<tt/PAM_SILENT/, and are the same as those applicable to the +<tt/flags/ argument of <tt/pam_authenticate/. + +<p> +This function simply calls the corresponding functions of each of the +loaded modules, as instructed by the configuration file, +<tt>/etc/pam.conf</tt>. + +<p> +The normal response from this function is <tt/PAM_SUCCESS/, however, +specific failures are indicated by the following error returns: + +<descrip> +<tag><tt/PAM_AUTHTOKEN_REQD/</tag> +The user <bf/is/ valid but their authentication token has +<em/expired/. The correct response to this return-value is to require +that the user satisfies the <tt/pam_chauthtok()/ function before +obtaining service. It may not be possible for some applications to do +this. In such cases, the user should be denied access until such time +as they can update their password. + +<tag><tt/PAM_ACCT_EXPIRED/</tag> + The user is no longer permitted access to the system. +<tag><tt/PAM_AUTH_ERR/</tag> + There was an authentication error. + +<tag><tt/PAM_PERM_DENIED/</tag> + The user is not permitted to gain access at this time. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to a module's account management +component. + +</descrip> + +<sect2>Updating authentication tokens +<label id="pam-chauthtok-section"> + +<p> +<tscreen> +<verb> +extern int pam_chauthtok(pam_handle_t *pamh, const int flags); +</verb> +</tscreen> + +<p> +This function is used to change the authentication token for a given +user (as indicated by the state associated with the handle, +<tt/pamh/). The following is a valid but optional flag which may be +logically OR'd with <tt/PAM_SILENT/, + +<descrip> +<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag> + This argument indicates to the modules that the users +authentication token (password) should only be changed if it has +expired. +</descrip> + +<p> +Note, if this argument is not passed, the application requires that +<em/all/ authentication tokens are to be changed. + +<p> +<tt/PAM_SUCCESS/ is the only successful return value, valid +error-returns are: + +<descrip> +<tag><tt/PAM_AUTHTOK_ERR/</tag> + A module was unable to obtain the new authentication token. + +<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag> + A module was unable to obtain the old authentication token. + +<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag> + One or more of the modules was unable to change the +authentication token since it is currently locked. + +<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag> + Authentication token aging has been disabled for at least one +of the modules. + +<tag><tt/PAM_PERM_DENIED/</tag> + Permission denied. + +<tag><tt/PAM_TRY_AGAIN/</tag> + Not all of the modules were in a position to update the +authentication token(s). In such a case none of the user's +authentication tokens are updated. + +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to the authentication token changing +service. + +</descrip> + +<sect2>Session initialization +<label id="pam-open-session-section"> + +<p> +<tscreen> +<verb> +extern int pam_open_session(pam_handle_t *pamh, int flags); +</verb> +</tscreen> + +<p> +This function is used to indicate that an authenticated session has +begun. It is used to inform the module that the user is currently in +a session. It should be possible for the <bf>Linux-PAM</bf> library +to open a session and close the same session (see section <ref +id="pam-close-session-section" name="below">) from different +applications. + +<p> +Currently, this function simply calls each of the corresponding +functions of the loaded modules. The only valid flag is +<tt/PAM_SILENT/ and this is, of course, <em/optional/. + +<p> +If any of the <em/required/ loaded modules are unable to open a +session for the user, this function will return <tt/PAM_SESSION_ERR/. + +<sect2>Terminating sessions +<label id="pam-close-session-section"> + +<p> +<tscreen> +<verb> +extern int pam_close_session(pam_handle_t *pamh, int flags); +</verb> +</tscreen> + +<p> +This function is used to indicate that an authenticated session has +ended. It is used to inform the module that the user is exiting a +session. It should be possible for the <bf>Linux-PAM</bf> library to +open a session and close the same session from different applications. + +<p> +Currently, this function simply calls each of the corresponding +functions of the loaded modules. The only valid flag is +<tt/PAM_SILENT/ and this is, of course, <em/optional/. + +<p> +If any of the <em/required/ loaded modules are unable to close a +session for the user, this function will return <tt/PAM_SESSION_ERR/. + +<sect2>Setting PAM environment variables +<label id="pam-putenv-section"> + +<p> +<tscreen> +<verb> +extern int pam_putenv(pam_handle_t *pamh, const char *name_value); +</verb> +</tscreen> + +<p> +<em> +Warning, the environment support in <bf/Linux-PAM/ is based solely +on a six line email from the developers at Sun. Its interface is +likely to be generally correct, however, the details are likely to be +changed as more information becomes available. +</em> + +<p> +This function attempts to (re)set a <bf/Linux-PAM/ environment +variable. The <tt/name_value/ argument is a single <tt/NUL/ terminated +string of one of the following forms: +<descrip> +<tag>``<tt/NAME=value of variable/''</tag> + +In this case the environment variable of the given <tt/NAME/ is set to +the indicated value: ``<tt/value of variable/''. If this variable is +already known, it is overwritten. Otherwise it is added to the +<bf/Linux-PAM/ environment. + +<tag>``<tt/NAME=/''</tag> + +This function sets the variable to an empty value. It is listed +separately to indicate that this is the correct way to achieve such a +setting. + +<tag>``<tt/NAME/''</tag> + +Without an `<tt/=/' the <tt/pam_putenv()/ function will delete the +correspoding variable from the <bf/Linux-PAM/ environment. + +</descrip> + +<p> +Success is indicated with a return value of <tt/PAM_SUCCESS/. Failure +is indicated by one of the following returns: + +<descrip> +<tag><tt/PAM_PERM_DENIED/</tag> + name given is a <tt/NULL/ pointer + +<tag><tt/PAM_BAD_ITEM/</tag> + variable requested (for deletion) is not currently set + +<tag><tt/PAM_ABORT/</tag> + the <bf/Linux-PAM/ handle, <tt/pamh/, is corrupt + +<tag><tt/PAM_BUF_ERR/</tag> + failed to allocate memory when attempting update + +</descrip> + +<sect2>Getting a PAM environment variable +<label id="pam-getenv-section"> + +<p> +<tscreen> +<verb> +extern const char *pam_getenv(pam_handle_t *pamh, const char *name); +</verb> +</tscreen> + +<p> +<em> +Warning, the environment support in <bf/Linux-PAM/ is based solely +on a six-line email from the developers at Sun. Its interface is +likely to be generally correct, however, the details are likely to be +changed as more information becomes available. +</em> + +<p> +Obtain the value of the indicated <bf/Linux-PAM/ environment +variable. On error, internal failure or the unavailability of the +given variable (unspecified), this function simply returns <tt/NULL/. + +<sect2>Getting the PAM environment +<label id="pam-getenvlist-section"> + +<p> +<tscreen> +<verb> +extern const char * const *pam_getenvlist(pam_handle_t *pamh); +</verb> +</tscreen> + +<p> +<em> +Warning, the environment support in <bf/Linux-PAM/ is based solely +on a six line email from the developers at Sun. Its interface is +likely to be generally correct, however, the details are likely to be +changed as more information becomes available. +</em> + +<p> +This function returns a pointer to the complete <tt/Linux-PAM/ +environment. It is a pointer to a <em/read-only/ list of +<em/read-only/ environment variables. It should be noted that this +memory will become invalid after a call to <tt/pam_end()/ (see the +section <ref id="pam-end-section" name="above">). If application +wishes to make use of this list after such a call, it should first +make a copy of all the set variables. (A function that performs such a +transcription is to be found in <tt/libpam_misc/.) + +<sect1>What is expected of an application + +<sect2>The conversation function +<label id="the-conversation-function"> + +<p> +An application must provide a ``conversation function''. It is used +for direct communication between a loaded module and the application +and will typically provide a means for the module to prompt the user +for a password etc. . The structure, <tt/pam_conv/, is defined by +including <tt><security/pam_appl.h></tt>; to be, + +<p> +<tscreen> +<verb> +struct pam_conv { + int (*conv)(int num_msg, + const struct pam_message **msg, + struct pam_response **resp, + void *appdata_ptr); + void *appdata_ptr; +}; +</verb> +</tscreen> + +<p> +It is initialized by the application before it is passed to the +library. The <em/contents/ of this structure are attached to the +<tt/*pamh/ handle. The point of this argument is to provide a +mechanism for any loaded module to interact directly with the +application program. This is why it is called a <em/conversation/ +structure. + +<p> +When a module calls the referenced <tt/conv()/ function, the argument +<tt/*appdata_ptr/ is set to the second element of this structure. + +<p> +The other arguments of a call to <tt/conv()/ concern the information +exchanged by module and application. That is to say, <tt/num_msg/ +holds the length of the array of pointers, <tt/msg/. After a +successful return, the pointer <tt/*resp/ points to an array of +<tt/pam_response/ structures, holding the application supplied text. +Note, <tt/*resp/ is an <tt/struct pam_response/ array and <em/not/ an +array of pointers. + +<p> +The message (from the module to the application) passing structure is +defined by <tt><security/pam_appl.h></tt> as: + +<p> +<tscreen> +<verb> +struct pam_message { + int msg_style; + const char *msg; +}; +</verb> +</tscreen> + +<p> +Valid choices for <tt/msg_style/ are: + +<p><descrip> +<tag><tt/PAM_PROMPT_ECHO_OFF/</tag> + Obtain a string without echoing any text +<tag><tt/PAM_PROMPT_ECHO_ON/</tag> + Obtain a string whilst echoing text +<tag><tt/PAM_ERROR_MSG/</tag> + Display an error +<tag><tt/PAM_TEXT_INFO/</tag> + Display some text. +</descrip> + +<p> +The point of having an array of messages is that it becomes possible +to pass a number of things to the application in a single call from +the module. It can also be convenient for the application that related +things come at once: a windows based application can then present a +single form with many messages/prompts on at once. + +<p> +The response (from the application to the module) passing structure is +defined by including <tt><security/pam_appl.h></tt> as: + +<p><tscreen><verb> +struct pam_response { + char *resp; + int resp_retcode; +}; +</verb></tscreen> + +<p> +Currently, there are no definitions for <tt/resp_retcode/ values; the +normal value is <tt/0/. + +<p> +Prior to the 0.59 release of Linux-PAM, the length of the returned +<tt/pam_response/ array was equal to the number of <em/prompts/ (types +<tt/PAM_PROMPT_ECHO_OFF/ and <tt/PAM_PROMPT_ECHO_ON/) in the +<tt/pam_message/ array with which the conversation function was +called. This meant that it was not always necessary for the module to +<tt/free(3)/ the responses if the conversation function was only used +to display some text. + +<p> +Post Linux-PAM-0.59 (and in the interests of compatibility with +Sunsoft). The number of resposes is always equal to the <tt/num_msg/ +conversation function argument. This is slightly easier to program +but does require that the response array is <tt/free(3)/'d after every +call to the conversation function. The index of the responses +corresponds directly to the prompt index in the <tt/pam_message/ +array. + +<p> +The maximum length of the <tt/pam_msg.msg/ and <tt/pam_response.resp/ +character strings is <tt/PAM_MAX_MSG_SIZE/. (This is not enforced by +Linux-PAM.) + +<p> +<tt/PAM_SUCCESS/ is the expected return value of this +function. However, should an error occur the application should not +set <tt/*resp/ but simply return <tt/PAM_CONV_ERR/. + +<p> +Note, if an application wishes to use two conversation functions, it +should activate the second with a call to <tt/pam_set_item()/. + +<p> +<bf>Notes:</bf> New item types are being added to the conversation +protocol. Currently Linux-PAM supports: <tt>PAM_BINARY_PROMPT</tt> +and <tt>PAM_BINARY_MSG</tt>. These two are intended for server-client +hidden information exchange and may be used as an interface for +maching-machine authentication. + +<sect1>Programming notes + +<p> +Note, all of the authentication service function calls accept the +token <tt/PAM_SILENT/, which instructs the modules to not send +messages to the application. This token can be logically OR'd with any +one of the permitted tokens specific to the individual function calls. +<tt/PAM_SILENT/ does not override the prompting of the user for +passwords etc., it only stops informative messages from being +generated. + +<sect>Security issues of <bf>Linux-PAM</bf> + +<p> +PAM, from the perspective of an application, is a convenient API for +authenticating users. PAM modules generally have no increased +privilege over that posessed by the application that is making use of +it. For this reason, the application must take ultimate responsibility +for protecting the environment in which PAM operates. + +<p> +A poorly (or maliciously) written application can defeat any +<bf/Linux-PAM/ module's authentication mechanisms by simply ignoring +it's return values. It is the applications task and responsibility to +grant privileges and access to services. The <bf/Linux-PAM/ library +simply assumes the responsibility of <em/authenticating/ the user; +ascertaining that the user <em/is/ who they say they are. Care should +be taken to anticipate all of the documented behavior of the +<bf/Linux-PAM/ library functions. A failure to do this will most +certainly lead to a future security breach. + +<sect1>Care about standard library calls + +<p> +In general, writers of authorization-granting applications should +assume that each module is likely to call any or <em/all/ `libc' +functions. For `libc' functions that return pointers to +static/dynamically allocated structures (ie. the library allocates the +memory and the user is not expected to `<tt/free()/' it) any module +call to this function is likely to corrupt a pointer previously +obtained by the application. The application programmer should either +re-call such a `libc' function after a call to the <bf/Linux-PAM/ +library, or copy the structure contents to some safe area of memory +before passing control to the <bf/Linux-PAM/ library. + +<p> +Two important function classes that fall into this category are +<tt>getpwnam(3)</tt> and <tt>syslog(3)</tt>. + +<sect1>Choice of a service name + +<p> +When picking the <em/service-name/ that corresponds to the first entry +in the <bf/Linux-PAM/ configuration file, the application programmer +should <bf/avoid/ the temptation of choosing something related to +<tt/argv[0]/. It is a trivial matter for any user to invoke any +application on a system under a different name and this should not be +permitted to cause a security breach. + +<p> +To invoke some <tt/target/ application by another name, the user may +symbolically link the target application with the desired name. To be +precise all the user need do is, +<tscreen> +<verb> +ln -s /target/application ./preferred_name +</verb> +</tscreen> +and then <em/run/ <tt>./preferred_name</tt> + +<p> +By studying the <bf/Linux-PAM/ configuration file(s), an attacker can +choose the <tt/preferred_name/ to be that of a service enjoying +minimal protection; for example a game which uses <bf/Linux-PAM/ to +restrict access to certain hours of the day. If the service-name were +to be linked to the filename under which the service was invoked, it +is clear that the user is effectively in the position of dictating +which authentication scheme the service uses. Needless to say, this +is not a secure situation. + +<p> +The conclusion is that the application developer should carefully +define the service-name of an application. The safest thing is to make +it a single hard-wired name. + +<sect1>The conversation function + +<p> +Care should be taken to ensure that the <tt/conv()/ function is +robust. Such a function is provided in the library <tt/libpam_misc/ +(see <ref id="libpam-misc-section" name="below">). + +<sect1>The identity of the user + +<p> +The <bf/Linux-PAM/ modules will need to determine the identity of the +user who requests a service, and the identity of the user who grants +the service. These two users will seldom be the same. Indeed there +is generally a third user identity to be considered, the new (assumed) +identity of the user once the service is granted. + +<p> +The need for keeping tabs on these identities is clearly an issue of +security. One convention that is actively used by some modules is +that the identity of the user requesting a service should be the +current <tt/uid/ (userid) of the running process; the identity of the +privilege granting user is the <tt/euid/ (effective userid) of the +running process; the identity of the user, under whose name the +service will be executed, is given by the contents of the +<tt/PAM_USER/ <tt/pam_get_item(3)/. + +<p> +For network-serving databases and other applications that provide +their own security model (independent of the OS kernel) the above +scheme is insufficient to identify the requesting user. + +<p> +A more portable solution to storing the identity of the requesting +user is to use the <tt/PAM_RUSER/ <tt/pam_get_item(3)/. The +application should supply this value before attempting to authenticate +the user with <tt/pam_authenticate()/. How well this name can be +trusted will ultimately be at the discretion of the local +administrator (who configures PAM for your application) and a selected +module may attempt to override the value where it can obtain more +reliable data. If an application is unable to determine the identity +of the requesting entity/user, it should not call <tt/pam_set_item(3)/ +to set <tt/PAM_RUSER/. + +<p> +In addition to the <tt/PAM_RUSER/ item, the application should supply +the <tt/PAM_RHOST/ (<em/requesting host/) item. As a general rule, the +following convention for its value can be assumed: <tt/<unset>/ += unknown; <tt/localhost/ = invoked directly from the local system; +<em/other.place.xyz/ = some component of the user's connection +originates from this remote/requesting host. At present, PAM has no +established convention for indicating whether the application supports +a trusted path to communication from this host. + +<sect1>Sufficient resources + +<p> +Care should be taken to ensure that the proper execution of an +application is not compromised by a lack of system resources. If an +application is unable to open sufficient files to perform its service, +it should fail gracefully, or request additional resources. +Specifically, the quantities manipulated by the <tt/setrlimit(2)/ +family of commands should be taken into consideration. + +<p> +This is also true of conversation prompts. The application should not +accept prompts of arbitrary length with out checking for resource +allocation failure and dealing with such extreme conditions gracefully +and in a mannor that preserves the PAM API. Such tolerance may be +especially important when attempting to track a malicious adversary. + +<sect>A library of miscellaneous helper functions +<label id="libpam-misc-section"> + +<p> +To aid the work of the application developer a library of +miscellaneous functions is provided. It is called <tt/libpam_misc/, +and contains functions for allocating memory (securely), a text based +conversation function, and routines for enhancing the standard +PAM-environment variable support. + +<sect1>Requirements + +<p> +The functions, structures and macros, made available by this library +can be defined by including <tt><security/pam_misc.h></tt>. It +should be noted that this library is specific to <bf/Linux-PAM/ and is +not referred to in the defining DCE-RFC (see <ref id="bibliography" +name="the bibliography">) below. + +<sect1>Functions supplied + +<sect2>Safe string duplication + +<p> +<tscreen> +<verb> +extern char *xstrdup(const char *s) +</verb> +</tscreen> +Return a duplicate copy of the <tt/NUL/ terminated string, +<tt/s/. <tt/NULL/ is returned if there is insufficient memory +available for the duplicate or if <tt/s=NULL/. + +<sect2>A text based conversation function + +<p> +<tscreen> +<verb> +extern int misc_conv(int num_msg, const struct pam_message **msgm, + struct pam_response **response, void *appdata_ptr); +</verb> +</tscreen> + +<p> +This is a function that will prompt the user with the appropriate +comments and obtain the appropriate inputs as directed by +authentication modules. + +<p> +In addition to simply slotting into the appropriate <tt/struct +pam_conv/, this function provides some time-out facilities. The +function exports five variables that can be used by an application +programmer to limit the amount of time this conversation function will +spend waiting for the user to type something. + +<p> +The five variables are as follows: +<descrip> +<tag><tt>extern time_t pam_misc_conv_warn_time;</tt></tag> + +This variable contains the <em/time/ (as returned by <tt/time()/) that +the user should be first warned that the clock is ticking. By default +it has the value <tt/0/, which indicates that no such warning will be +given. The application may set its value to sometime in the future, +but this should be done prior to passing control to the <bf/Linux-PAM/ +library. + +<tag><tt>extern const char *pam_misc_conv_warn_line;</tt></tag> + +Used in conjuction with <tt/pam_misc_conv_warn_time/, this variable is +a pointer to the string that will be displayed when it becomes time to +warn the user that the timeout is approaching. Its default value is +``..\a.Time is running out...\n'', but this can be changed +by the application prior to passing control to <bf/Linux-PAM/. + +<tag><tt>extern time_t pam_misc_conv_die_time;</tt></tag> + +This variable contains the <em/time/ (as returned by <tt/time()/) that +the conversation will time out. By default it has the value <tt/0/, +which indicates that the conversation function will not timeout. The +application may set its value to sometime in the future, this should +be done prior to passing control to the <bf/Linux-PAM/ library. + +<tag><tt>extern const char *pam_misc_conv_die_line;</tt></tag> + +Used in conjuction with <tt/pam_misc_conv_die_time/, this variable is +a pointer to the string that will be displayed when the conversation +times out. Its default value is ``..\a.Sorry, your time is +up!\n'', but this can be changed by the application prior to +passing control to <bf/Linux-PAM/. + +<tag><tt>extern int pam_misc_conv_died;</tt></tag> + +Following a return from the <bf/Linux-PAM/ libraray, the value of this +variable indicates whether the conversation has timed out. A value of +<tt/1/ indicates the time-out occurred. + +<tag><tt>extern int (*pam_binary_handler_fn)(const union pam_u_packet_p send, + union pam_u_packet_p *receive);</tt></tag> + +This function pointer is initialized to <tt/NULL/ but can be filled +with a function that provides machine-machine (hidden) message +exchange. It is intended for use with hidden authentication protocols +such as RSA or Diffie-Hellman key exchanges. (This is still under +development.) + +</descrip> + +<sect2>Transcribing an environment to that of Linux-PAM +<p> +<tscreen> +<verb> +extern int pam_misc_paste_env(pam_handle_t *pamh, + const char * const * user_env); +</verb> +</tscreen> + +This function takes the supplied list of environment pointers and +<em/uploads/ its contents to the <bf/Linux-PAM/ environment. Success +is indicated by <tt/PAM_SUCCESS/. + +<sect2>Saving the Linux-PAM environment for later use +<p> +<tscreen> +<verb> +extern char **pam_misc_copy_env(pam_handle_t *pamh); +</verb> +</tscreen> + +This function returns a pointer to a list of environment variables +that are a direct copy of the <bf/Linux-PAM/ environment. The memory +associated with these variables are the responsibility of the +application and should be liberated with a call to +<tt/pam_misc_drop_env()/. + +<sect2>Liberating a locally saved environment +<p> +<tscreen> +<verb> +extern char **pam_misc_drop_env(char **env); +</verb> +</tscreen> + +This function is defined to complement the <tt/pam_misc_copy_env()/ +function. It liberates the memory associated with <tt/env/, +<em/overwriting/ with <tt/0/ all memory before <tt/free()/ing it. + +<sect2>BSD like Linux-PAM environment variable setting +<p> +<tscreen> +<verb> +extern int pam_misc_setenv(pam_handle_t *pamh, const char *name, + const char *value, int readonly); +</verb> +</tscreen> + +This function performs a task equivalent to <tt/pam_putenv()/, its +syntax is, however, more like the BSD style function; <tt/setenv()/. +The <tt/name/ and <tt/value/ are concatenated with an ``<tt/=/'' to +form a <tt/name_value/ and passed to <tt/pam_putenv()/. If, however, +the <bf/Linux-PAM/ variable is already set, the replacement will only +be applied if the last argument, <tt/readonly/, is zero. + +<sect>Porting legacy applications + +<p> +The following is extracted from an email. I'll tidy it up later. + +<p> +The point of PAM is that the application is not supposed to have any +idea how the attatched authentication modules will choose to +authenticate the user. So all they can do is provide a conversation +function that will talk directly to the user(client) on the modules' +behalf. + +<p> +Consider the case that you plug a retinal scanner into the login +program. In this situation the user would be prompted: "please look +into the scanner". No username or password would be needed - all this +information could be deduced from the scan and a database lookup. The +point is that the retinal scanner is an ideal task for a "module". + +<p> +While it is true that a pop-daemon program is designed with the POP +protocol in mind and no-one ever considered attatching a retinal +scanner to it, it is also the case that the "clean" PAM'ification of +such a daemon would allow for the possibility of a scanner module +being be attatched to it. The point being that the "standard" +pop-authentication protocol(s) [which will be needed to satisfy +inflexible/legacy clients] would be supported by inserting an +appropriate pam_qpopper module(s). However, having rewritten popd +once in this way any new protocols can be implemented in-situ. + +<p> +One simple test of a ported application would be to insert the +<tt/pam_permit/ module and see if the application demands you type a +password... In such a case, <tt/xlock/ would fail to lock the +terminal - or would at best be a screen-saver, ftp would give password +free access to all etc.. Neither of these is a very secure thing to +do, but they do illustrate how much flexibility PAM puts in the hands +of the local admin. + +<p> +The key issue, in doing things correctly, is identifying what is part +of the authentication procedure (how many passwords etc..) the +exchange protocol (prefixes to prompts etc., numbers like 331 in the +case of ftpd) and what is part of the service that the application +delivers. PAM really needs to have total control in the +authentication "proceedure", the conversation function should only +deal with reformatting user prompts and extracting responses from raw +input. + +<sect>Glossary of PAM related terms + +<p> +The following are a list of terms used within this document. + +<p> +<descrip> + +<tag>Authentication token</tag> +Generally, this is a password. However, a user can authenticate +him/herself in a variety of ways. Updating the user's authentication +token thus corresponds to <em>refreshing</em> the object they use to +authenticate themself with the system. The word password is avoided +to keep open the possibility that the authentication involves a +retinal scan or other non-textual mode of challenge/response. + +<tag>Credentials</tag> +Having successfully authenticated the user, PAM is able to establish +certain characteristics/attributes of the user. These are termed +<em>credentials</em>. Examples of which are group memberships to +perform privileged tasks with, and <em>tickets</em> in the form of +environment variables etc. . Some user-credentials, such as the +user's UID and GID (plus default group memberships) are not deemed to +be PAM-credentials. It is the responsibility of the application to +grant these directly. + +</descrip> + +<sect>An example application + +<p> +To get a flavor of the way a <tt/Linux-PAM/ application is written we +include the following example. It prompts the user for their password +and indicates whether their account is valid on the standard output, +its return code also indicates the success (<tt/0/ for success; <tt/1/ +for failure). + +<p> +<tscreen> +<verb> +/* + This program was contributed by Shane Watts + [modifications by AGM] + + You need to add the following (or equivalent) to the /etc/pam.conf file. + # check authorization + check_user auth required /usr/lib/security/pam_unix_auth.so + check_user account required /usr/lib/security/pam_unix_acct.so + */ + +#include <security/pam_appl.h> +#include <security/pam_misc.h> +#include <stdio.h> + +static struct pam_conv conv = { + misc_conv, + NULL +}; + +int main(int argc, char *argv[]) +{ + pam_handle_t *pamh=NULL; + int retval; + const char *user="nobody"; + + if(argc == 2) { + user = argv[1]; + } + + if(argc > 2) { + fprintf(stderr, "Usage: check_user [username]\n"); + exit(1); + } + + retval = pam_start("check_user", user, &ero;conv, &ero;pamh); + + if (retval == PAM_SUCCESS) + retval = pam_authenticate(pamh, 0); /* is user really user? */ + + if (retval == PAM_SUCCESS) + retval = pam_acct_mgmt(pamh, 0); /* permitted access? */ + + /* This is where we have been authorized or not. */ + + if (retval == PAM_SUCCESS) { + fprintf(stdout, "Authenticated\n"); + } else { + fprintf(stdout, "Not Authenticated\n"); + } + + if (pam_end(pamh,retval) != PAM_SUCCESS) { /* close Linux-PAM */ + pamh = NULL; + fprintf(stderr, "check_user: failed to release authenticator\n"); + exit(1); + } + + return ( retval == PAM_SUCCESS ? 0:1 ); /* indicate success */ +} +</verb> +</tscreen> + +<sect>Files + +<p><descrip> + +<tag><tt>/usr/include/security/pam_appl.h</tt></tag> + +header file for <bf/Linux-PAM/ applications interface + +<tag><tt>/usr/include/security/pam_misc.h</tt></tag> + +header file for useful library functions for making applications +easier to write + +<tag><tt>/usr/lib/libpam.so.*</tt></tag> + +the shared library providing applications with access to +<bf/Linux-PAM/. + +<tag><tt>/etc/pam.conf</tt></tag> + +the <bf/Linux-PAM/ configuration file. + +<tag><tt>/usr/lib/security/pam_*.so</tt></tag> + +the primary location for <bf/Linux-PAM/ dynamically loadable object +files; the modules. + +</descrip> + +<sect>See also +<label id="bibliography"> + +<p><itemize> + +<item>The <bf/Linux-PAM/ +<htmlurl url="pam.html" name="System Administrators' Guide">. + +<item>The <bf/Linux-PAM/ +<htmlurl url="pam_modules.html" name="Module Writers' Guide">. + +<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH +PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request +For Comments 86.0, October 1995. + +</itemize> + +<sect>Notes + +<p> +I intend to put development comments here... like ``at the moment +this isn't actually supported''. At release time what ever is in +this section will be placed in the Bugs section below! :) + +<p> +<itemize> + +<item> <tt/pam_strerror()/ should be internationalized.... + +<item> +Note, the <tt/resp_retcode/ of struct <tt/pam_message/, has no +purpose at the moment. Ideas/suggestions welcome! + +<item> more security issues are required.... + +</itemize> + +<sect>Author/acknowledgments + +<p> +This document was written by Andrew G. Morgan +(morgan@transmeta.com) with many contributions from +<!-- insert credits here --> +<!-- + an sgml list of people to credit for their contributions to Linux-PAM + $Id$ + --> +Chris Adams, +Peter Allgeyer, +Tim Baverstock, +Tim Berger, +Craig S. Bell, +Derrick J. Brashear, +Ben Buxton, +Seth Chaiklin, +Oliver Crow, +Chris Dent, +Marc Ewing, +Cristian Gafton, +Emmanuel Galanos, +Brad M. Garcia, +Eric Hester, +Roger Hu, +Eric Jacksch, +Michael K. Johnson, +David Kinchlea, +Olaf Kirch, +Marcin Korzonek, +Stephen Langasek, +Nicolai Langfeldt, +Elliot Lee, +Luke Kenneth Casson Leighton, +Al Longyear, +Ingo Luetkebohle, +Marek Michalkiewicz, +Robert Milkowski, +Aleph One, +Martin Pool, +Sean Reifschneider, +Jan Rekorajski, +Erik Troan, +Theodore Ts'o, +Jeff Uphoff, +Myles Uyema, +Savochkin Andrey Vladimirovich, +Ronald Wahl, +David Wood, +John Wilmes, +Joseph S. D. Yao +and +Alex O. Yuriev. + +<p> +Thanks are also due to Sun Microsystems, especially to Vipin Samar and +Charlie Lai for their advice. At an early stage in the development of +<bf/Linux-PAM/, Sun graciously made the documentation for their +implementation of PAM available. This act greatly accelerated the +development of <bf/Linux-PAM/. + +<sect>Bugs/omissions + +<p> +This manual is hopelessly unfinished. Only a partial list of people is +credited for all the good work they have done. + +<sect>Copyright information for this document + +<p> +Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. +<newline> +Email: <tt><morgan@transmeta.com></tt> + +<p> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +<p> +<itemize> + +<item> +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +<item> +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +<item> +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +</itemize> + +<p> +<bf/Alternatively/, this product may be distributed under the terms of +the GNU General Public License (GPL), in which case the provisions of +the GNU GPL are required <bf/instead of/ the above restrictions. +(This clause is necessary due to a potential bad interaction between +the GNU GPL and the restrictions contained in a BSD-style copyright.) + +<p> +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + +<p> +<tt>$Id$</tt> + +</article> diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml new file mode 100644 index 00000000..e76e3d7a --- /dev/null +++ b/doc/pam_modules.sgml @@ -0,0 +1,1476 @@ +<!doctype linuxdoc system> + +<!-- + + $Id$ + + Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. + + ** some sections, in this document, were contributed by other + ** authors. They carry individual copyrights. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +ALTERNATIVELY, this product may be distributed under the terms of the +GNU General Public License, in which case the provisions of the GNU +GPL are required INSTEAD OF the above restrictions. (This clause is +necessary due to a potential bad interaction between the GNU GPL and +the restrictions contained in a BSD-style copyright.) + +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + + --> + +<article> + +<title>The Linux-PAM Module Writers' Guide +<author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> +<date>DRAFT v0.71 1999/11/8 +<abstract> +This manual documents what a programmer needs to know in order to +write a module that conforms to the <bf/Linux-PAM/ standard. It also +discusses some security issues from the point of view of the module +programmer. +</abstract> + +<toc> + +<sect>Introduction + +<sect1> Synopsis +<p> +<tscreen> +<verb> +#include <security/pam_modules.h> + +gcc -fPIC -c pam_module-name.c +ld -x --shared -o pam_module-name.so pam_module-name.o -lpam +</verb> +</tscreen> + +<sect1> Description + +<p> +<bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a +library that enables the local system administrator to choose how +individual applications authenticate users. For an overview of the +<bf/Linux-PAM/ library see the <bf/Linux-PAM/ System Administrators' +Guide. + +<p> +A <bf/Linux-PAM/ module is a single executable binary file that can be +loaded by the <bf/Linux-PAM/ interface library. This PAM library is +configured locally with a system file, <tt>/etc/pam.conf</tt>, to +authenticate a user request via the locally available authentication +modules. The modules themselves will usually be located in the +directory <tt>/usr/lib/security</tt> and take the form of dynamically +loadable object files (see dlopen(3)). Alternatively, the modules can +be statically linked into the <bf/Linux-PAM/ library; this is mostly to +allow <bf/Linux-PAM/ to be used on platforms without dynamic linking +available, but the two forms can be used together. It is the +<bf/Linux-PAM/ interface that is called by an application and it is +the responsibility of the library to locate, load and call the +appropriate functions in a <bf/Linux-PAM/-module. + +<p> +Except for the immediate purpose of interacting with the user +(entering a password etc..) the module should never call the +application directly. This exception requires a "conversation +mechanism" which is documented below. + +<sect>What can be expected by the module + +<p> +Here we list the interface that the conventions that all +<bf/Linux-PAM/ modules must adhere to. + +<sect1>Getting and setting <tt/PAM_ITEM/s and <em/data/ + +<p> +First, we cover what the module should expect from the <bf/Linux-PAM/ +library and a <bf/Linux-PAM/ <em/aware/ application. Essesntially this +is the <tt/libpam.*/ library. + +<sect2> +Setting data + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_set_data(pam_handle_t *pamh, + const char *module_data_name, + void *data, + void (*cleanup)(pam_handle_t *pamh, + void *data, int error_status) ); +</verb> +</tscreen> + +<p> +The modules may be dynamically loadable objects. In general such files +should not contain <tt/static/ variables. This and the subsequent +function provide a mechanism for a module to associate some data with +the handle <tt/pamh/. Typically a module will call the +<tt/pam_set_data()/ function to register some data under a (hopefully) +unique <tt/module_data_name/. The data is available for use by other +modules too but <em/not/ by an application. + +<p> +The function <tt/cleanup()/ is associated with the <tt/data/ and, if +non-<tt/NULL/, it is called when this data is over-written or +following a call to <tt/pam_end()/ (see the Linux-PAM Application +Developers' Guide). + +<p> +The <tt/error_status/ argument is used to indicate to the module the +sort of action it is to take in cleaning this data item. As an +example, Kerberos creates a ticket file during the authentication +phase, this file might be associated with a data item. When +<tt/pam_end()/ is called by the module, the <tt/error_status/ +carries the return value of the <tt/pam_authenticate()/ or other +<tt/libpam/ function as appropriate. Based on this value the Kerberos +module may choose to delete the ticket file (<em/authentication +failure/) or leave it in place. + +<p> +The <tt/error_status/ may have been logically OR'd with either of the +following two values: + +<p> +<descrip> +<tag><tt/PAM_DATA_REPLACE/</tag> + When a data item is being replaced (through a second call to +<tt/pam_set_data()/) this mask is used. Otherwise, the call is assumed +to be from <tt/pam_end()/. + +<tag><tt/PAM_DATA_SILENT/</tag> + Which indicates that the process would prefer to perform the +<tt/cleanup()/ quietly. That is, discourages logging/messages to the +user. + +</descrip> + + +<sect2> +Getting data + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_get_data(const pam_handle_t *pamh, + const char *module_data_name, + const void **data); +</verb> +</tscreen> + +<p> +This function together with the previous one provides a method of +associating module-specific data with the handle <tt/pamh/. A +successful call to <tt/pam_get_data/ will result in <tt/*data/ +pointing to the data associated with the <tt/module_data_name/. Note, +this data is <em/not/ a copy and should be treated as <em/constant/ +by the module. + +<p> +Note, if there is an entry but it has the value <tt/NULL/, then this +call returns <tt/PAM_NO_MODULE_DATA/. + +<sect2> +Setting items + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_set_item(pam_handle_t *pamh + , int item_type + , const void *item + ); +</verb> +</tscreen> + +<p> +This function is used to (re)set the value of one of the +<tt/item_type/s. The reader is urged to read the entry for this +function in the <bf/Linux-PAM/ application developers' manual. + +<p> +In addition to the <tt/item/s listed there, the module can set the +following two <tt/item_type/s: + +<p> +<descrip> +<tag><tt/PAM_AUTHTOK/</tag> + +The authentication token (password). This token should be ignored by +all module functions besides <tt/pam_sm_authenticate()/ and +<tt/pam_sm_chauthtok()/. In the former function it is used to pass the +most recent authentication token from one stacked module to +another. In the latter function the token is used for another +purpose. It contains the currently active authentication token. + +<tag><tt/PAM_OLDAUTHTOK/</tag> + +The old authentication token. This token should be ignored by all +module functions except <tt/pam_sm_chauthtok()/. + +</descrip> + +<p> +Both of these items are reset before returning to the application. +When resetting these items, the <bf/Linux-PAM/ library first writes +<tt/0/'s to the current tokens and then <tt/free()/'s the associated +memory. + +<p> +The return values for this function are listed in the +<bf>Linux-PAM</bf> Application Developers' Guide. + +<sect2> +Getting items + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_get_item(const pam_handle_t *pamh + , int item_type + , const void **item + ); +</verb> +</tscreen> + +<p> +This function is used to obtain the value of the specified +<tt/item_type/. It is better documented in the <bf/Linux-PAM/ +Application Developers' Guide. However, there are three things worth +stressing here: +<itemize> + +<item> +Generally, if the module wishes to obtain the name of the user, it +should not use this function, but instead perform a call to +<tt/pam_get_user()/ (see section <ref id="pam-get-user" +name="below">). + +<item> +The module is additionally privileged to read the authentication +tokens, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/ (see the section +above on <tt/pam_set_data()/). + +<item> +The module should <em/not/ <tt/free()/ or alter the data pointed to by +<tt/*item/ after a successful return from <tt/pam_get_item()/. This +pointer points directly at the data contained within the <tt/*pamh/ +structure. Should a module require that a change is made to the this +<tt/ITEM/ it should make the appropriate call to <tt/pam_set_item()/. +</itemize> + +<sect2>The <em/conversation/ mechanism + +<p> +Following the call <tt>pam_get_item(pamh,PAM_CONV,&item)</tt>, the +pointer <tt/item/ points to a <em/conversation/-function that provides +limited but direct access to the application. The purpose of this +function is to allow the module to prompt the user for their password +and pass other information in a manner consistent with the +application. For example, an X-windows based program might pop up a +dialog box to report a login failure. Just as the application should +not be concerned with the method of authentication, so the module +should not dictate the manner in which input (output) is +obtained from (presented to) to the user. + +<p> +The reader is strongly urged to read the more complete description of +the <tt/pam_conv/ structure, written from the perspective of the +application developer, in the <bf/Linux-PAM/ Application Developers' +Guide. + +<p> +The <tt/pam_response/ structure returned after a call to the +<tt/pam_conv/ function must be <tt/free()/'d by the module. Since the +call to the conversation function originates from the module, it is +clear that either this <tt/pam_response/ structure could be either +statically or dynamically (using <tt/malloc()/ etc.) allocated within +the application. Repeated calls to the conversation function would +likely overwrite static memory, so it is required that for a +successful return from the conversation function the memory for the +response structure is dynamically allocated by the application with +one of the <tt/malloc()/ family of commands and <em/must/ be +<tt/free()/'d by the module. + +<p> +If the <tt/pam_conv/ mechanism is used to enter authentication tokens, +the module should either pass the result to the <tt/pam_set_item()/ +library function, or copy it itself. In such a case, once the token +has been stored (by one of these methods or another one), the memory +returned by the application should be overwritten with <tt/0/'s, and +then <tt/free()/'d. + +<p> +The return values for this function are listed in the +<bf>Linux-PAM</bf> Application Developers' Guide. + +<sect2>Getting the name of a user<label id="pam-get-user"> + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_get_user(pam_handle_t *pamh, + const char **user, + const char *prompt); +</verb> +</tscreen> + +<p> +This is a <bf/Linux-PAM/ library function that returns the +(prospective) name of the user. To determine the username it does the +following things, in this order: +<itemize> + +<item> checks what <tt/pam_get_item(pamh, PAM_USER, ... );/ would have +returned. If this is not <tt/NULL/ this is what it returns. Otherwise, + +<item> obtains a username from the application via the <tt/pam_conv/ +mechanism, it prompts the user with the first non-<tt/NULL/ string in +the following list: +<itemize> + +<item> The <tt/prompt/ argument passed to the function +<item> What is returned by <tt/pam_get_item(pamh,PAM_USER_PROMPT, ... );/ +<item> The default prompt: ``Please enter username: '' + +</itemize> +</itemize> + +<p> +By whatever means the username is obtained, a pointer to it is +returned as the contents of <tt/*user/. Note, this memory should +<em/not/ be <tt/free()/'d by the module. Instead, it will be liberated +on the next call to <tt/pam_get_user()/, or by <tt/pam_end()/ when the +application ends its interaction with <bf/Linux-PAM/. + +<p> +Also, in addition, it should be noted that this function sets the +<tt/PAM_USER/ item that is associated with the <tt/pam_[gs]et_item()/ +function. + +<p> +The return value of this function is one of the following: +<itemize> + +<item> <tt/PAM_SUCCESS/ - username obtained. + +<item> <tt/PAM_CONV_AGAIN/ - converstation did not complete and the +caller is required to return control to the application, until such +time as the application has completed the conversation process. A +module calling <tt/pam_get_user()/ that obtains this return code, +should return <tt/PAM_INCOMPLETE/ and be prepared (when invoked the +next time) to recall <tt/pam_get_user()/ to fill in the user's name, +and then pick up where it left off as if nothing had happened. This +procedure is needed to support an event-driven application programming +model. + +<item> <tt/PAM_CONV_ERR/ - the conversation method supplied by the +application failed to obtain the username. + +</itemize> + +<sect2>Setting a Linux-PAM environment variable + +<p> +Synopsis: +<tscreen> +<verb> +extern int pam_putenv(pam_handle_t *pamh, const char *name_value); +</verb> +</tscreen> + +<p> +<bf/Linux-PAM/ (0.54+) comes equipped with a series of functions for +maintaining a set of <em/environment/ variables. The environment is +initialized by the call to <tt/pam_start()/ and is <bf/erased/ with a +call to <tt/pam_end()/. This <em/environment/ is associated with the +<tt/pam_handle_t/ pointer returned by the former call. + +<p> +The default environment is all but empty. It contains a single +<tt/NULL/ pointer, which is always required to terminate the +variable-list. The <tt/pam_putenv()/ function can be used to add a +new environment variable, replace an existing one, or delete an old +one. + +<p> +<itemize> +<item>Adding/replacing a variable<newline> + +To add or overwrite a <bf/Linux-PAM/ environment variable the value of +the argument <tt/name_value/, should be of the following form: +<tscreen> +<verb> +name_value="VARIABLE=VALUE OF VARIABLE" +</verb> +</tscreen> +Here, <tt/VARIABLE/ is the environment variable's name and what +follows the `<tt/=/' is its (new) value. (Note, that <tt/"VARIABLE="/ +is a valid value for <tt/name_value/, indicating that the variable is +set to <tt/""/.) + +<item> Deleting a variable<newline> + +To delete a <bf/Linux-PAM/ environment variable the value of +the argument <tt/name_value/, should be of the following form: +<tscreen> +<verb> +name_value="VARIABLE" +</verb> +</tscreen> +Here, <tt/VARIABLE/ is the environment variable's name and the absence +of an `<tt/=/' indicates that the variable should be removed. + +</itemize> + +<p> +In all cases <tt/PAM_SUCCESS/ indicates success. + +<sect2>Getting a Linux-PAM environment variable + +<p> +Synopsis: +<tscreen> +<verb> +extern const char *pam_getenv(pam_handle_t *pamh, const char *name); +</verb> +</tscreen> + +<p> +This function can be used to return the value of the given +variable. If the returned value is <tt/NULL/, the variable is not +known. + +<sect2>Listing the Linux-PAM environment + +<p> +Synopsis: +<tscreen> +<verb> +extern char * const *pam_getenvlist(pam_handle_t *pamh); +</verb> +</tscreen> + +<p> +This function returns a pointer to the entire <bf/Linux-PAM/ +environment array. At first sight the <em/type/ of the returned data +may appear a little confusing. It is basically a <em/read-only/ array +of character pointers, that lists the <tt/NULL/ terminated list of +environment variables set so far. + +<p> +Although, this is not a concern for the module programmer, we mention +here that an application should be careful to copy this entire array +before executing <tt/pam_end()/ otherwise all the variable information +will be lost. (There are functions in <tt/libpam_misc/ for this +purpose: <tt/pam_misc_copy_env()/ and <tt/pam_misc_drop_env()/.) + +<sect1>Other functions provided by <tt/libpam/ + +<sect2>Understanding errors + +<p> +<itemize> + +<item> +<tt>extern const char *pam_strerror(pam_handle_t *pamh, int errnum);</tt> + +<p> +This function returns some text describing the <bf/Linux-PAM/ error +associated with the argument <tt/errnum/. If the error is not +recognized <tt/``Unknown Linux-PAM error''/ is returned. + +</itemize> + +<sect2>Planning for delays + +<p> +<itemize> + +<item> +<tt>extern int pam_fail_delay(pam_handle_t *pamh, unsigned int +micro_sec)</tt> + +<p> +This function is offered by <bf/Linux-PAM/ to facilitate time delays +following a failed call to <tt/pam_authenticate()/ and before control +is returned to the application. When using this function the module +programmer should check if it is available with, +<tscreen> +<verb> +#ifdef HAVE_PAM_FAIL_DELAY + .... +#endif /* HAVE_PAM_FAIL_DELAY */ +</verb> +</tscreen> + +<p> +Generally, an application requests that a user is authenticated by +<bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or +<tt/pam_chauthtok()/. These functions call each of the <em/stacked/ +authentication modules listed in the <bf/Linux-PAM/ configuration +file. As directed by this file, one of more of the modules may fail +causing the <tt/pam_...()/ call to return an error. It is desirable +for there to also be a pause before the application continues. The +principal reason for such a delay is security: a delay acts to +discourage <em/brute force/ dictionary attacks primarily, but also +helps hinder <em/timed/ (cf. covert channel) attacks. + +<p> +The <tt/pam_fail_delay()/ function provides the mechanism by which an +application or module can suggest a minimum delay (of <tt/micro_sec/ +<em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time +requested with this function. Should <tt/pam_authenticate()/ fail, +the failing return to the application is delayed by an amount of time +randomly distributed (by up to 25%) about this longest value. + +<p> +Independent of success, the delay time is reset to its zero default +value when <bf/Linux-PAM/ returns control to the application. + +</itemize> + +<sect>What is expected of a module + +<p> +The module must supply a sub-set of the six functions listed +below. Together they define the function of a <bf/Linux-PAM +module/. Module developers are strongly urged to read the comments on +security that follow this list. + +<sect1> Overview + +<p> +The six module functions are grouped into four independent management +groups. These groups are as follows: <em/authentication/, +<em/account/, <em/session/ and <em/password/. To be properly defined, +a module must define all functions within at least one of these +groups. A single module may contain the necessary functions for +<em/all/ four groups. + +<sect2> Functional independence + +<p> +The independence of the four groups of service a module can offer +means that the module should allow for the possibility that any one of +these four services may legitimately be called in any order. Thus, the +module writer should consider the appropriateness of performing a +service without the prior success of some other part of the module. + +<p> +As an informative example, consider the possibility that an +application applies to change a user's authentication token, without +having first requested that <bf/Linux-PAM/ authenticate the user. In +some cases this may be deemed appropriate: when <tt/root/ wants to +change the authentication token of some lesser user. In other cases it +may not be appropriate: when <tt/joe/ maliciously wants to reset +<tt/alice/'s password; or when anyone other than the user themself +wishes to reset their <em/KERBEROS/ authentication token. A policy for +this action should be defined by any reasonable authentication scheme, +the module writer should consider this when implementing a given +module. + +<sect2> Minimizing administration problems + +<p> +To avoid system administration problems and the poor construction of a +<tt>/etc/pam.conf</tt> file, the module developer may define all +six of the following functions. For those functions that would not be +called, the module should return <tt/PAM_SERVICE_ERR/ and write an +appropriate message to the system log. When this action is deemed +inappropriate, the function would simply return <tt/PAM_IGNORE/. + +<sect2> Arguments supplied to the module + +<p> +The <tt/flags/ argument of each of the following functions can be +logically OR'd with <tt/PAM_SILENT/, which is used to inform the +module to not pass any <em/text/ (errors or warnings) to the +application. + +<p> +The <tt/argc/ and <tt/argv/ arguments are taken from the line +appropriate to this module---that is, with the <em/service_name/ +matching that of the application---in the configuration file (see the +<bf/Linux-PAM/ System Administrators' Guide). Together these two +parameters provide the number of arguments and an array of pointers to +the individual argument tokens. This will be familiar to C programmers +as the ubiquitous method of passing command arguments to the function +<tt/main()/. Note, however, that the first argument (<tt/argv[0]/) is +a true argument and <bf/not/ the name of the module. + +<sect1> Authentication management + +<p> +To be correctly initialized, <tt/PAM_SM_AUTH/ must be <tt/#define/'d +prior to including <tt><security/pam_modules.h></tt>. This will +ensure that the prototypes for static modules are properly declared. + +<p> +<itemize> + +<item> +<tt>PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags, +int argc, const char **argv);</tt> + +<p> +This function performs the task of authenticating the user. + +<p> +The <tt/flags/ argument can be a logically OR'd with <tt/PAM_SILENT/ +and optionally take the following value: + +<p><descrip> +<tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag> + return <tt/PAM_AUTH_ERR/ if the database of authentication +tokens for this authentication mechanism has a <tt/NULL/ entry for the +user. Without this flag, such a <tt/NULL/ token will lead to a success +without the user being prompted. +</descrip> + +<p> +Besides <tt/PAM_SUCCESS/ return values that can be sent by this +function are one of the following: + +<descrip> + +<tag><tt/PAM_AUTH_ERR/</tag> + The user was not authenticated +<tag><tt/PAM_CRED_INSUFFICIENT/</tag> + For some reason the application does not have sufficient +credentials to authenticate the user. +<tag><tt/PAM_AUTHINFO_UNAVAIL/</tag> + The modules were not able to access the authentication +information. This might be due to a network or hardware failure etc. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The supplied username is not known to the authentication +service +<tag><tt/PAM_MAXTRIES/</tag> + One or more of the authentication modules has reached its +limit of tries authenticating the user. Do not try again. + +</descrip> + +<item> +<tt>PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int +argc, const char **argv);</tt> + +<p> +This function performs the task of altering the credentials of the +user with respect to the corresponding authorization +scheme. Generally, an authentication module may have access to more +information about a user than their authentication token. This +function is used to make such information available to the +application. It should only be called <em/after/ the user has been +authenticated and after a session has been established. + +<p> +Permitted flags, one of which, may be logically OR'd with +<tt/PAM_SILENT/ are, + +<p><descrip> +<tag><tt/PAM_ESTABLISH_CRED/</tag> + Set the credentials for the authentication service, +<tag><tt/PAM_DELETE_CRED/</tag> + Delete the credentials associated with the authentication service, +<tag><tt/PAM_REINITIALIZE_CRED/</tag> + Reinitialize the user credentials, and +<tag><tt/PAM_REFRESH_CRED/</tag> + Extend the lifetime of the user credentials. +</descrip> + +<p> +Generally, the module should attempt to return the same error code as +<tt/pam_sm_authenticate/ did. This will preserve the logic followed +by libpam as it executes the stack of <em/authentication/ modules, +when the application calls <tt/pam_authenticate()/ and +<tt/pam_setcred()/. Failing to do this, will lead to much confudion +on the part of the System administrator. + +<p> +<bf>The following text is depreciated. Some thought needs to be given to +how the credential setting modules are supposed to be stacked...</bf> + +<p> +Besides <tt/PAM_SUCCESS/, the module may return one of the following +errors: + +<p><descrip> +<tag><tt/PAM_CRED_UNAVAIL/</tag> + This module cannot retrieve the user's credentials. +<tag><tt/PAM_CRED_EXPIRED/</tag> + The user's credentials have expired. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to this authentication module. +<tag><tt/PAM_CRED_ERR/</tag> + This module was unable to set the credentials of the user. +</descrip> + +</itemize> + +<sect1> Account management + +<p> +To be correctly initialized, <tt/PAM_SM_ACCOUNT/ must be +<tt/#define/'d prior to including <tt><security/pam_modules.h></tt>. +This will ensure that the prototype for a static module is properly +declared. + +<p> +<itemize> + +<item> +<tt>PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int +argc, const char **argv);</tt> + +<p> +This function performs the task of establishing whether the user is +permitted to gain access at this time. It should be understood that +the user has previously been validated by an authentication +module. This function checks for other things. Such things might be: +the time of day or the date, the terminal line, remote +hostname, etc. . + +<p> +This function may also determine things like the expiration on +passwords, and respond that the user change it before continuing. + +<p> +Valid flags, which may be logically OR'd with <tt/PAM_SILENT/, are the +same as those applicable to the <tt/flags/ argument of +<tt/pam_sm_authenticate/. + +<p> +This function may return one of the following errors, + +<descrip> + +<tag><tt/PAM_ACCT_EXPIRED/</tag> + The user is no longer permitted access to the system. +<tag><tt/PAM_AUTH_ERR/</tag> + There was an authentication error. +<tag><tt/PAM_AUTHTOKEN_REQD/</tag> + The user's authentication token has expired. Before calling +this function again the application will arrange for a new one to be +given. This will likely result in a call to <tt/pam_sm_chauthtok()/. +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to the module's account management +component. + +</descrip> + +</itemize> + +<sect1> Session management + +<p> +To be correctly initialized, <tt/PAM_SM_SESSION/ must be +<tt/#define/'d prior to including +<tt><security/pam_modules.h></tt>. This will ensure that the +prototypes for static modules are properly declared. + +<p> +The following two functions are defined to handle the +initialization/termination of a session. For example, at the beginning +of a session the module may wish to log a message with the system +regarding the user. Similarly, at the end of the session the module +would inform the system that the user's session has ended. + +<p> +It should be possible for sessions to be opened by one application and +closed by another. This either requires that the module uses only +information obtained from <tt/pam_get_item()/, or that information +regarding the session is stored in some way by the operating system +(in a file for example). + +<p> +<itemize> + +<item> +<tt>PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags, int +argc, const char **argv);</tt> + +<p> +This function is called to commence a session. The only valid, but +optional, flag is <tt/PAM_SILENT/. + +<p> +As a return value, <tt/PAM_SUCCESS/ signals success and +<tt/PAM_SESSION_ERR/ failure. + +<item> +<tt>PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags, int +argc, const char **argv);</tt> + +<p> +This function is called to terminate a session. The only valid, but +optional, flag is <tt/PAM_SILENT/. + +<p> +As a return value, <tt/PAM_SUCCESS/ signals success and +<tt/PAM_SESSION_ERR/ failure. + +</itemize> + +<sect1> Password management + +<p> +To be correctly initialized, <tt/PAM_SM_PASSWORD/ must be +<tt/#define/'d prior to including <tt><security/pam_modules.h></tt>. +This will ensure that the prototype for a static module is properly +declared. + +<p> +<itemize> + +<item> +<tt>PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int +argc, const char **argv);</tt> + +<p> +This function is used to (re-)set the authentication token of the +user. A valid flag, which may be logically OR'd with <tt/PAM_SILENT/, +can be built from the following list, + +<descrip> +<tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag> + This argument indicates to the module that the users +authentication token (password) should only be changed if it has +expired. This flag is optional and <em/must/ be combined with one of +the following two flags. Note, however, the following two options are +<em/mutually exclusive/. + +<tag><tt/PAM_PRELIM_CHECK/</tag> + This indicates that the modules are being probed as to their +ready status for altering the user's authentication token. If the +module requires access to another system over some network it should +attempt to verify it can connect to this system on receiving this +flag. If a module cannot establish it is ready to update the user's +authentication token it should return <tt/PAM_TRY_AGAIN/, this +information will be passed back to the application. + +<tag><tt/PAM_UPDATE_AUTHTOK/</tag> + This informs the module that this is the call it should change +the authorization tokens. If the flag is logically OR'd with +<tt/PAM_CHANGE_EXPIRED_AUTHTOK/, the token is only changed if it has +actually expired. + +</descrip> + +<p> +Note, the <bf/Linux-PAM/ library calls this function twice in +succession. The first time with <tt/PAM_PRELIM_CHECK/ and then, if the +module does not return <tt/PAM_TRY_AGAIN/, subsequently with +<tt/PAM_UPDATE_AUTHTOK/. It is only on the second call that the +authorization token is (possibly) changed. + +<p> +<tt/PAM_SUCCESS/ is the only successful return value, valid +error-returns are: + +<descrip> +<tag><tt/PAM_AUTHTOK_ERR/</tag> + The module was unable to obtain the new authentication token. + +<tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag> + The module was unable to obtain the old authentication token. + +<tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag> + Cannot change the authentication token since it is currently +locked. + +<tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag> + Authentication token aging has been disabled. + +<tag><tt/PAM_PERM_DENIED/</tag> + Permission denied. + +<tag><tt/PAM_TRY_AGAIN/</tag> + Preliminary check was unsuccessful. Signals an immediate return +to the application is desired. + +<tag><tt/PAM_USER_UNKNOWN/</tag> + The user is not known to the authentication token changing +service. + +</descrip> + +</itemize> + +<sect>Generic optional arguments + +<p> +Here we list the generic arguments that all modules can expect to +be passed. They are not mandatory, and their absence should be +accepted without comment by the module. + +<p> +<descrip> +<tag><tt/debug/</tag> + +Use the <tt/syslog(3)/ call to log debugging information to the system +log files. + +<tag><tt/no_warn/</tag> + +Instruct module to not give warning messages to the application. + +<tag><tt/use_first_pass/</tag> + +The module should not prompt the user for a password. Instead, it +should obtain the previously typed password (by a call to +<tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/ item), and use that. If +that doesn't work, then the user will not be authenticated. (This +option is intended for <tt/auth/ and <tt/passwd/ modules only). + +<tag><tt/try_first_pass/</tag> + +The module should attempt authentication with the previously typed +password (by a call to <tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/ +item). If that doesn't work, then the user is prompted for a +password. (This option is intended for <tt/auth/ modules only). + +<tag><tt/use_mapped_pass/</tag> + +<bf/WARNING:/ coding this functionality may cause the module writer to +break <em/local/ encryption laws. For example, in the U.S. there are +restrictions on the export computer code that is capable of strong +encryption. It has not been established whether this option is +affected by this law, but one might reasonably assume that it does +until told otherwise. For this reason, this option is not supported +by any of the modules distributed with <bf/Linux-PAM/. + +The intended function of this argument, however, is that the module +should take the existing authentication token from a previously +invoked module and use it as a key to retrieve the authentication +token for this module. For example, the module might create a strong +hash of the <tt/PAM_AUTHTOK/ item (established by a previously +executed module). Then, with logical-exclusive-or, use the result as a +<em/key/ to safely store/retrieve the authentication token for this +module in/from a local file <em/etc/. . + +<tag><tt/expose_account/</tag> + +<p> +In general the leakage of some information about user accounts is not +a secure policy for modules to adopt. Sometimes information such as +users names or home directories, or preferred shell, can be used to +attack a user's account. In some circumstances, however, this sort of +information is not deemed a threat: displaying a user's full name when +asking them for a password in a secured environment could also be +called being 'friendly'. The <tt/expose_account/ argument is a +standard module argument to encourage a module to be less discrete +about account information as it is deemed appropriate by the local +administrator. + +</descrip> + +<sect>Programming notes + +<p> +Here we collect some pointers for the module writer to bear in mind +when writing/developing a <bf/Linux-PAM/ compatible module. + +<sect1>Security issues for module creation + +<sect2>Sufficient resources + +<p> +Care should be taken to ensure that the proper execution of a module +is not compromised by a lack of system resources. If a module is +unable to open sufficient files to perform its task, it should fail +gracefully, or request additional resources. Specifically, the +quantities manipulated by the <tt/setrlimit(2)/ family of commands +should be taken into consideration. + +<sect2>Who's who? + +<p> +Generally, the module may wish to establish the identity of the user +requesting a service. This may not be the same as the username +returned by <tt/pam_get_user()/. Indeed, that is only going to be the +name of the user under whose identity the service will be given. This +is not necessarily the user that requests the service. + +<p> +In other words, user X runs a program that is setuid-Y, it grants the +user to have the permissions of Z. A specific example of this sort of +service request is the <em/su/ program: user <tt/joe/ executes +<em/su/ to become the user <em/jane/. In this situation X=<tt/joe/, +Y=<tt/root/ and Z=<tt/jane/. Clearly, it is important that the module +does not confuse these different users and grant an inappropriate +level of privilege. + +<p> +The following is the convention to be adhered to when juggling +user-identities. + +<p> +<itemize> +<item>X, the identity of the user invoking the service request. +This is the user identifier; returned by the function <tt/getuid(2)/. + +<item>Y, the privileged identity of the application used to grant the +requested service. This is the <em/effective/ user identifier; +returned by the function <tt/geteuid(2)/. + +<item>Z, the user under whose identity the service will be granted. +This is the username returned by <tt/pam_get_user(2)/ and also stored +in the <bf/Linux-PAM/ item, <tt/PAM_USER/. + +<item><bf/Linux-PAM/ has a place for an additional user identity that +a module may care to make use of. This is the <tt/PAM_RUSER/ item. +Generally, network sensitive modules/applications may wish to set/read +this item to establish the identity of the user requesting a service +from a remote location. + +</itemize> + +<p> +Note, if a module wishes to modify the identity of either the <tt/uid/ +or <tt/euid/ of the running process, it should take care to restore +the original values prior to returning control to the <bf/Linux-PAM/ +library. + +<sect2>Using the conversation function +<p> +Prior to calling the conversation function, the module should reset +the contents of the pointer that will return the applications +response. This is a good idea since the application may fail to fill +the pointer and the module should be in a position to notice! + +<p> +The module should be prepared for a failure from the conversation. The +generic error would be <tt/PAM_CONV_ERR/, but anything other than +<tt/PAM_SUCCESS/ should be treated as indicating failure. + +<sect2>Authentication tokens + +<p> +To ensure that the authentication tokens are not left lying around the +items, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/, are not available to +the application: they are defined in +<tt><security/pam_modules.h></tt>. This is ostensibly for +security reasons, but a maliciously programmed application will always +have access to all memory of the process, so it is only superficially +enforced. As a general rule the module should overwrite +authentication tokens as soon as they are no longer needed. +Especially before <tt/free()/'ing them. The <bf/Linux-PAM/ library is +required to do this when either of these authentication token items +are (re)set. + +<p> +Not to dwell too little on this concern; should the module store the +authentication tokens either as (automatic) function variables or +using <tt/pam_[gs]et_data()/ the associated memory should be +over-written explicitly before it is released. In the case of the +latter storage mechanism, the associated <tt/cleanup()/ function +should explicitly overwrite the <tt/*data/ before <tt/free()/'ing it: +for example, + +<tscreen> +<verb> +/* + * An example cleanup() function for releasing memory that was used to + * store a password. + */ + +int cleanup(pam_handle_t *pamh, void *data, int error_status) +{ + char *xx; + + if ((xx = data)) { + while (*xx) + *xx++ = '\0'; + free(data); + } + return PAM_SUCCESS; +} +</verb> +</tscreen> + +<sect1>Use of <tt/syslog(3)/ + +<p> +Only rarely should error information be directed to the user. Usually, +this is to be limited to ``<em/sorry you cannot login now/'' type +messages. Information concerning errors in the configuration file, +<tt>/etc/pam.conf</tt>, or due to some system failure encountered by +the module, should be written to <tt/syslog(3)/ with +<em/facility-type/ <tt/LOG_AUTHPRIV/. + +<p> +With a few exceptions, the level of logging is, at the discretion of +the module developer. Here is the recommended usage of different +logging levels: + +<p> +<itemize> + +<item> +As a general rule, errors encountered by a module should be logged at +the <tt/LOG_ERR/ level. However, information regarding an unrecognized +argument, passed to a module from an entry in the +<tt>/etc/pam.conf</tt> file, is <bf/required/ to be logged at the +<tt/LOG_ERR/ level. + +<item> +Debugging information, as activated by the <tt/debug/ argument to the +module in <tt>/etc/pam.conf</tt>, should be logged at the +<tt/LOG_DEBUG/ level. + +<item> +If a module discovers that its personal configuration file or some +system file it uses for information is corrupted or somehow unusable, +it should indicate this by logging messages at level, <tt/LOG_ALERT/. + +<item> +Shortages of system resources, such as a failure to manipulate a file +or <tt/malloc()/ failures should be logged at level <tt/LOG_CRIT/. + +<item> +Authentication failures, associated with an incorrectly typed password +should be logged at level, <tt/LOG_NOTICE/. + +</itemize> + +<sect1> Modules that require system libraries + +<p> +Writing a module is much like writing an application. You have to +provide the "conventional hooks" for it to work correctly, like +<tt>pam_sm_authenticate()</tt> etc., which would correspond to the +<tt/main()/ function in a normal function. + +<p> +Typically, the author may want to link against some standard system +libraries. As when one compiles a normal program, this can be done for +modules too: you simply append the <tt>-l</tt><em>XXX</em> arguments +for the desired libraries when you create the shared module object. To +make sure a module is linked to the <tt>lib<em>whatever</em>.so</tt> +library when it is <tt>dlopen()</tt>ed, try: +<tscreen> +<verb> +% gcc -shared -Xlinker -x -o pam_module.so pam_module.o -lwhatever +</verb> +</tscreen> + +<sect1> Added requirements for <em/statically/ loaded modules. + +<!-- + Copyright (C) Michael K. Johnson 1996. + Last modified: AGM 1996/5/31. + --> + +<p> +Modules may be statically linked into libpam. This should be true of +all the modules distributed with the basic <bf/Linux-PAM/ +distribution. To be statically linked, a module needs to export +information about the functions it contains in a manner that does not +clash with other modules. + +The extra code necessary to build a static module should be delimited +with <tt/#ifdef PAM_STATIC/ and <tt/#endif/. The static code should do +the following: +<itemize> +<item> Define a single structure, <tt/struct pam_module/, called +<tt>_pam_<it>modname</it>_modstruct</tt>, where +<tt><it>modname</it></tt> is the name of the module <bf/as used in the +filesystem/ but without the leading directory name (generally +<tt>/usr/lib/security/</tt> or the suffix (generally <tt/.so/). + +</itemize> + +<p> +As a simple example, consider the following module code which defines +a module that can be compiled to be <em/static/ or <em/dynamic/: + +<p> +<tscreen> +<verb> +#include <stdio.h> /* for NULL define */ + +#define PAM_SM_PASSWORD /* the only pam_sm_... function declared */ +#include <security/pam_modules.h> + +PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, + int argc, const char **argv) +{ + return PAM_SUCCESS; +} + +#ifdef PAM_STATIC /* for the case that this module is static */ + +struct pam_module _pam_modname_modstruct = { /* static module data */ + "pam_modname", + NULL, + NULL, + NULL, + NULL, + NULL, + pam_sm_chauthtok, +}; + +#endif /* end PAM_STATIC */ +</verb> +</tscreen> + +<p> +To be linked with <em/libpam/, staticly-linked modules must be built +from within the <tt>Linux-PAM-X.YY/modules/</tt> subdirectory of the +<bf/Linux-PAM/ source directory as part of a normal build of the +<bf/Linux-PAM/ system. + +The <em/Makefile/, for the module in question, must execute the +<tt/register_static/ shell script that is located in the +<tt>Linux-PAM-X.YY/modules/</tt> subdirectory. This is to ensure that +the module is properly registered with <em/libpam/. + +The <bf/two/ manditory arguments to <tt/register_static/ are the +title, and the pathname of the object file containing the module's +code. The pathname is specified relative to the +<tt>Linux-PAM-X.YY/modules</tt> directory. The pathname may be an +empty string---this is for the case that a single object file needs to +register more than one <tt/struct pam_module/. In such a case, exactly +one call to <tt/register_static/ must indicate the object file. + +<p> +Here is an example; a line in the <em/Makefile/ might look like this: +<tscreen> +<verb> +register: +ifdef STATIC + (cd ..; ./register_static pam_modname pam_modname/pam_modname.o) +endif +</verb> +</tscreen> + +For some further examples, see the <tt>modules</tt> subdirectory of +the current <bf/Linux-PAM/ distribution. + +<p> +<sect>An example module file + +<p> +<em> +perhaps this should point to a place in the file structure!? +</em> + +<sect>Files + +<p><descrip> + +<tag><tt>/usr/lib/libpam.so.*</tt></tag> + +the shared library providing applications with access to +<bf/Linux-PAM/. + +<tag><tt>/etc/pam.conf</tt></tag> + +the <bf/Linux-PAM/ configuration file. + +<tag><tt>/usr/lib/security/pam_*.so</tt></tag> + +the primary location for <bf/Linux-PAM/ dynamically loadable object +files; the modules. + +</descrip> + +<sect>See also + +<p><itemize> +<item>The <bf/Linux-PAM/ System Administrators' Guide. +<item>The <bf/Linux-PAM/ Application Writers' Guide. +<item> +V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE +AUTHENTICATION MODULES'', Open Software Foundation Request For +Comments 86.0, October 1995. +</itemize> + +<sect>Notes + +<p> +I intend to put development comments here... like ``at the moment +this isn't actually supported''. At release time what ever is in +this section will be placed in the Bugs section below! :) + +<p> +<itemize> +<item> +Perhaps we should keep a registry of data-names as used by +<tt/pam_[gs]et_data()/ so there are no unintentional problems due to +conflicts? + +<item> +<tt/pam_strerror()/ should be internationalized.... + +<item> +There has been some debate about whether <tt/initgroups()/ should be +in an application or in a module. It was settled by Sun who stated +that initgroups is an action of the <em/application/. The modules are +permitted to add additional groups, however. + +<item> +Refinements/futher suggestions to <tt/syslog(3)/ usage by modules are +needed. + +</itemize> + +<sect>Author/acknowledgments + +<p> +This document was written by Andrew G. Morgan +(<tt/morgan@transmeta.com/) with many contributions from +<!-- insert credits here --> +<!-- + an sgml list of people to credit for their contributions to Linux-PAM + $Id$ + --> +Chris Adams, +Peter Allgeyer, +Tim Baverstock, +Tim Berger, +Craig S. Bell, +Derrick J. Brashear, +Ben Buxton, +Seth Chaiklin, +Oliver Crow, +Chris Dent, +Marc Ewing, +Cristian Gafton, +Emmanuel Galanos, +Brad M. Garcia, +Eric Hester, +Roger Hu, +Eric Jacksch, +Michael K. Johnson, +David Kinchlea, +Olaf Kirch, +Marcin Korzonek, +Stephen Langasek, +Nicolai Langfeldt, +Elliot Lee, +Luke Kenneth Casson Leighton, +Al Longyear, +Ingo Luetkebohle, +Marek Michalkiewicz, +Robert Milkowski, +Aleph One, +Martin Pool, +Sean Reifschneider, +Jan Rekorajski, +Erik Troan, +Theodore Ts'o, +Jeff Uphoff, +Myles Uyema, +Savochkin Andrey Vladimirovich, +Ronald Wahl, +David Wood, +John Wilmes, +Joseph S. D. Yao +and +Alex O. Yuriev. + +<p> +Thanks are also due to Sun Microsystems, especially to Vipin Samar and +Charlie Lai for their advice. At an early stage in the development of +<bf/Linux-PAM/, Sun graciously made the documentation for their +implementation of PAM available. This act greatly accelerated the +development of <bf/Linux-PAM/. + +<sect>Bugs/omissions + +<p> +Few PAM modules currently exist. Few PAM-aware applications exist. +This document is hopelessly unfinished. Only a partial list of people is +credited for all the good work they have done. + +<sect>Copyright information for this document + +<p> +Copyright (c) Andrew G. Morgan 1996, 1997. All rights reserved. +<newline> +Email: <tt><morgan@transmeta.com></tt> + +<p> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +<p> +<itemize> + +<item> +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +<item> +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +<item> +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +</itemize> + +<p> +<bf/Alternatively/, this product may be distributed under the terms of +the GNU General Public License (GPL), in which case the provisions of +the GNU GPL are required <bf/instead of/ the above restrictions. +(This clause is necessary due to a potential bad interaction between +the GNU GPL and the restrictions contained in a BSD-style copyright.) + +<p> +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + +<p> +<tt>$Id$</tt> + +</article> diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml new file mode 100644 index 00000000..1c369403 --- /dev/null +++ b/doc/pam_source.sgml @@ -0,0 +1,1173 @@ +<!doctype linuxdoc system> + +<!-- + + $Id$ + + Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. + +Redistribution and use in source (sgml) and binary (derived) forms, +with or without modification, are permitted provided that the +following conditions are met: + +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +ALTERNATIVELY, this product may be distributed under the terms of the +GNU General Public License, in which case the provisions of the GNU +GPL are required INSTEAD OF the above restrictions. (This clause is +necessary due to a potential bad interaction between the GNU GPL and +the restrictions contained in a BSD-style copyright.) + +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + + --> + +<article> + +<title>The Linux-PAM System Administrators' Guide +<author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt> +<date>DRAFT v0.71 1999/11/8 +<abstract> +This manual documents what a system-administrator needs to know about +the <bf>Linux-PAM</bf> library. It covers the correct syntax of the +PAM configuration file and discusses strategies for maintaining a +secure system. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction + +<p><bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a +suite of shared libraries that enable the local system administrator +to choose how applications authenticate users. + +<p>In other words, without (rewriting and) recompiling a PAM-aware +application, it is possible to switch between the authentication +mechanism(s) it uses. Indeed, one may entirely upgrade the local +authentication system without touching the applications themselves. + +<p>Historically an application that has required a given user to be +authenticated, has had to be compiled to use a specific authentication +mechanism. For example, in the case of traditional UN*X systems, the +identity of the user is verified by the user entering a correct +password. This password, after being prefixed by a two character +``salt'', is encrypted (with crypt(3)). The user is then authenticated +if this encrypted password is identical to the second field of the +user's entry in the system password database (the <tt>/etc/passwd</tt> +file). On such systems, most if not all forms of privileges are +granted based on this single authentication scheme. Privilege comes in +the form of a personal user-identifier (<tt/uid/) and membership of +various groups. Services and applications are available based on the +personal and group identity of the user. Traditionally, group +membership has been assigned based on entries in the +<tt>/etc/group</tt> file. + +<p> +Unfortunately, increases in the speed of computers and the +widespread introduction of network based computing, have made once +secure authentication mechanisms, such as this, vulnerable to +attack. In the light of such realities, new methods of authentication +are continuously being developed. + +<p> +It is the purpose of the <bf/Linux-PAM/ project to separate the +development of privilege granting software from the development of +secure and appropriate authentication schemes. This is accomplished +by providing a library of functions that an application may use to +request that a user be authenticated. This PAM library is configured +locally with a system file, <tt>/etc/pam.conf</tt> (or a series of +configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a +user request via the locally available authentication modules. The +modules themselves will usually be located in the directory +<tt>/usr/lib/security</tt> and take the form of dynamically loadable +object files (see <tt/dlopen(3)/). + +<sect>Some comments on the text<label id="text-conventions"> + +<p> +Before proceeding to read the rest of this document, it should be +noted that the text assumes that certain files are placed in certain +directories. Where they have been specified, the conventions we adopt +here for locating these files are those of the relevant RFC (RFC-86.0, +see <ref id="see-also-sec" name="bibliography">). If you are using a +distribution of Linux (or some other operating system) that supports +PAM but chooses to distribute these files in a diferent way (Red Hat +is one such distribution), you should be careful when copying examples +directly from the text. + +<p> +As an example of the above, where it is explicit, the text assumes +that PAM loadable object files (the <em/modules/) are to be located in +the following directory: <tt>/usr/lib/security/</tt>. However, Red Hat +Linux, in agreement with the Linux File System Standard (the FSSTND), +places these files in <tt>/lib/security</tt>. Please be careful to +perform the necessary transcription when using the examples from the +text. + +<sect>Overview<label id="overview-section"> + +<p> +For the uninitiated, we begin by considering an example. We take an +application that grants some service to users; <em/login/ is one such +program. <em/Login/ does two things, it first establishes that the +requesting user is whom they claim to be and second provides them with +the requested service: in the case of <em/login/ the service is a +command shell (<em>bash, tcsh, zsh, etc.</em>) running with the +identity of the user. + +<p> +Traditinally, the former step is achieved by the <em/login/ +application prompting the user for a password and then verifying that +it agrees with that located on the system; hence verifying that the +so far as the system is concerned the user is who they claim to be. +This is the task that is delegated to <bf/Linux-PAM/. + +<p> +From the perspective of the application programmer (in this case the +person that wrote the <em/login/ application), <bf/Linux-PAM/ takes +care of this authentication task -- verifying the identity of the user. + +<p> +The flexibility of <bf/Linux-PAM/ is that <em/you/, the system +administrator, have the freedom to stipulate which authentication +scheme is to be used. You have the freedom to set the scheme for +any/all PAM-aware applications on your Linux system. That is, you can +authenticate from anything as naive as <em/simple trust/ +(<tt/pam_permit/) to something as paranoid as a combination of a +retinal scan, a voice print and a one-time password! + +<p> +To illustrate the flexibility you face, consider the following +situation: a system administrator (parent) wishes to improve the +mathematical ability of her users (children). She can configure their +favorite ``Shoot 'em up game'' (PAM-aware of course) to authenticate +them with a request for the product of a couple of random numbers less +than 12. It is clear that if the game is any good they will soon learn +their <em/multiplication tables/. As they mature, the authentication +can be upgraded to include (long) division! + +<p> +<bf/Linux-PAM/ deals with four separate types of (management) +task. These are: <em/authentication management/; <em/account +management/; <em/session management/; and <em/password management/. +The association of the preferred management scheme with the behavior +of an application is made with entries in the relevant <bf/Linux-PAM/ +configuration file. The management functions are performed by +<em/modules/ specified in the configuration file. The syntax for this +file is discussed in the section <ref id="configuration" +name="below">. + +<p> +Here is a figure that describes the overall organization of +<bf/Linux-PAM/. +<tscreen> +<verb> + +----------------+ + | application: X | + +----------------+ / +----------+ +================+ + | authentication-[---->--\--] Linux- |--<--| PAM config file| + | + [----<--/--] PAM | |================| + |[conversation()][--+ \ | | | X auth .. a.so | + +----------------+ | / +-n--n-----+ | X auth .. b.so | + | | | __| | | _____/ + | service user | A | | |____,-----' + | | | V A + +----------------+ +------|-----|---------+ -----+------+ + +---u-----u----+ | | | + | auth.... |--[ a ]--[ b ]--[ c ] + +--------------+ + | acct.... |--[ b ]--[ d ] + +--------------+ + | password |--[ b ]--[ c ] + +--------------+ + | session |--[ e ]--[ c ] + +--------------+ +</verb> +</tscreen> +By way of explanation, the left of the figure represents the +application; application X. Such an application interfaces with the +<bf/Linux-PAM/ library and knows none of the specifics of its +configured authentication method. The <bf/Linux-PAM/ library (in the +center) consults the contents of the PAM configuration file and loads +the modules that are appropriate for application-X. These modules fall +into one of four management groups (lower-center) and are stacked in +the order they appear in the configuaration file. These modules, when +called by <bf/Linux-PAM/, perform the various authentication tasks for +the application. Textual information, required from/or offered to the +user, can be exchanged through the use of the application-supplied +<em/conversation/ function. + +<sect1>Getting started + +<p> +The following text was contributed by Seth Chaiklin: +<tscreen> +<verb> +To this point, we have described how PAM should work in an +ideal world, in which all applications are coded properly. +However, at the present time (October 1998), this is far +from the case. Therefore, here are some practical considerations +in trying to use PAM in your system. + +Why bother, is it really worth all the trouble? + +If you running Linux as a single user system, or in an +environment where all the users are trusted, then there +is no real advantage for using PAM. +</verb> +</tscreen> + +<p> +<BF>Ed:</BF> there is actually an advantage since you can <em/dummy +down/ the authentication to the point where you don't have +any... Almost like Win95. +<p> +In a networked environment, it is clear that you need to think a +little more about how users etc., are authenticated:] + +<p> +<tscreen> +<verb> +If you are running Linux as a server, where several different +services are being provided (e.g., WWW with areas restricted by +password control, PPP), then there can be some real and interesting +value for PAM. In particular, through the use of modules, PAM can +enable a program to search through several different password +databases, even if that program is not explicitly coded for +that particular database. Here are some examples of the possibilities +that this enables. + + o Apache has a module that provides PAM services. Now + authentication + to use particular directories can be conducted by PAM, which + means that the range of modules that are available to PAM can + be used, including RADIUS, NIS, NCP (which means that Novell + password databases can be used). + + o pppd has a PAMified version (available from RedHat) Now it is + possible to use a series of databases to authenticate ppp users. + In addition to the normal Linux-based password databases (such + as /etc/passwd and /etc/shadow), you can use PAM modules to + authenticate against Novell password databases or NT-based + password databases. + + o The preceding two examples can be combined. Imagaine that the + persons in your office/department are already registered with a + username and password in a Novell or NT LAN. If you wanted to + use this database on your Linux server (for PPP access, for + web access, or even for normal shell access), you can use PAM + to authenticate against this existing database, rather than + maintain a separate database on both Linux and the LAN server. + + +Can I use PAM for any program that requires authentication? + +Yes and no. Yes, if you have access to the source code, and can +add the appropriate PAM functions. No, if you do not have access +to the source code, and the binary does not have the PAM functions +included. + +In other words, if a program is going to use PAM, then it has to +have PAM functions explicitly coded into the program. If they +are not, then it is not possible to use PAM. + +How can I tell whether a program has PAM coded into it or not? + +A quick-and-dirty (but not always reliable) method is to ldd +<programname> +If libpam and libpam_misc are not among the libraries that the program +uses, then it is not going to work with PAM. However, it is possible +that the libraries are included, but there are still problems, because +the PAM coding in the program does not work as it should. So a +more reliable method is to make the follow tests. + +In the /etc/pam.d directory, one needs to make a configuration file +for the program that one wants to run. The exact name of the +configuration +file is hard-coded into the program. Usually, it is the same name as +the +program, but not always. For sake of illustration, let's assume that +the program is named "pamprog" and the name of the configuration file +is /etc/pam.d/pamprog. + +In the /etc/pam.d/pamprog but the following two lines: + +auth required pam_permit.so +auth required pam_warn.so + + +Now try to use pamprog. The first line in the configuration file +says that all users are permitted. The second line will write a +warning to your syslog file (or whether you syslog is writing + +messages). If this test succeeds, then you know that you have +a program that can understand pam, and you can start the more +interesting work of deciding how to stack modules in your +/etc/pam.d/pamprog file. +</verb> +</tscreen> + +<sect>The Linux-PAM configuration file +<label id="configuration"> + +<p> +<bf/Linux-PAM/ is designed to provide the system administrator with a +great deal of flexibility in configuring the privilege granting +applications of their system. The local configuration of those aspects +of system security controlled by <tt/Linux-PAM/ is contained in one of +two places: either the single system file, <tt>/etc/pam.conf</tt>; or +the <tt>/etc/pam.d/</tt> directory. In this section we discuss the +correct syntax of and generic options respected by entries to these +files. + +<sect1>Configuration file syntax + +<p> +The reader should note that the <bf/Linux-PAM/ specific tokens in this +file are case <em/insensitive/. The module paths, however, are case +sensitive since they indicate a file's <em/name/ and reflect the case +dependence of typical Linux file-systems. The case-sensitivity of the +arguments to any given module is defined for each module in turn. + +<p> +In addition to the lines described below, there are two <em/special/ +characters provided for the convenience of the system administrator: +comments are preceded by a `<tt/#/' and extend to the +next end-of-line; also, module specification lines may be extended +with a `<tt/\/' escaped newline. + +<p> +A general configuration line of the <tt>/etc/pam.conf</tt> file has +the following form: +<tscreen> +<verb> +service-name module-type control-flag module-path arguments +</verb> +</tscreen> +Below, we explain the meaning of each of these tokens. The second (and +more recently adopted) way of configuring <bf/Linux-PAM/ is via the +contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained +the meaning of the above tokens, we will describe this method. + +<p> +<descrip> +<tag><tt/service-name/</tag> +The name of the service associated with this entry. Frequently the +service name is the conventional name of the given application. For +example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ . + +<p> +There is a special <tt/service-name/, reserved for defining a default +authentication mechanism. It has the name `<tt/OTHER/' and may be +specified in either lower or upper case characters. Note, when there +is a module specified for a named service, the `<tt/OTHER/' entries +are ignored. + +<tag><tt/module-type/</tag> +One of (currently) four types of module. The four types are as +follows: +<itemize> +<item> <tt/auth/; this module type provides two aspects of +authenticating the user. Firstly, it establishes that the user is who +they claim to be, by instructing the application to prompt the user +for a password or other means of identification. Secondly, the module +can grant <tt/group/ membership (independently of the +<tt>/etc/groups</tt> file discussed above) or other privileges through +its <em/credential/ granting properties. + +<item> <tt/account/; this module performs non-authentication based +account management. It is typically used to restrict/permit access to +a service based on the time of day, currently available system +resources (maximum number of users) or perhaps the location of the +applicant user---`<tt/root/' login only on the console. + +<item> <tt/session/; primarily, this module is associated with doing +things that need to be done for the user before/after they can be +given service. Such things include the logging of information +concerning the opening/closing of some data exchange with a user, +mounting directories, etc. . + +<item> <tt/password/; this last module type is required for updating the +authentication token associated with the user. Typically, there is one +module for each `challenge/response' based authentication (<tt/auth/) +module-type. + +</itemize> + +<tag><tt/control-flag/</tag> + +The control-flag is used to indicate how the PAM library will react to +the success or failure of the module it is associated with. Since +modules can be <em/stacked/ (modules of the same type execute in +series, one after another), the control-flags determine the relative +importance of each module. The application is not made aware of the +individual success or failure of modules listed in the +`<tt>/etc/pam.conf</tt>' file. Instead, it receives a summary +<em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library. +The order of execution of these modules is that of the entries in the +<tt>/etc/pam.conf</tt> file; earlier entries are executed before later +ones. As of Linux-PAM v0.60, this <em/control-flag/ can be defined +with one of two syntaxes. + +<p> +The simpler (and historical) syntax for the control-flag is a single +keyword defined to indicate the severity of concern associated with +the success or failure of a specific module. There are four such +keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and +<tt/optional/. + +<p> +The Linux-PAM library interprets these keywords in the following +manner: + +<itemize> + +<item> <tt/required/; this indicates that the success of the module is +required for the <tt/module-type/ facility to succeed. Failure of this +module will not be apparent to the user until all of the remaining +modules (of the same <tt/module-type/) have been executed. + +<item> <tt/requisite/; like <tt/required/, however, in the case that +such a module returns a failure, control is directly returned to the +application. The return value is that associated with the <em/first/ +<tt/required/ or <tt/requisite/ module to fail. Note, this flag can be +used to protect against the possibility of a user getting the +opportunity to enter a password over an unsafe medium. It is +conceivable that such behavior might inform an attacker of valid +accounts on a system. This possibility should be weighed against the +not insignificant concerns of exposing a sensitive password in a +hostile environment. + +<item> <tt/sufficient/; the success of this module is deemed +`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this +module-type has succeeded in its purpose. In the event that no +previous <tt/required/ module has failed, no more `<em/stacked/' +modules of this type are invoked. (Note, in this case subsequent +<tt/required/ modules are <bf/not/ invoked.). A failure of this module +is not deemed as fatal to satisfying the application that this +<tt/module-type/ has succeeded. + +<item> <tt/optional/; as its name suggests, this <tt/control-flag/ +marks the module as not being critical to the success or failure of +the user's application for service. In general, <bf/Linux-PAM/ +ignores such a module when determining if the module stack will +succeed or fail. However, in the absence of any definite successes or +failures of previous or subsequent stacked modules this module will +determine the nature of the response to the application. One example +of this latter case, is when the other modules return something like +<tt/PAM_IGNORE/. + +</itemize> + +<p> +The more elaborate (newer) syntax is much more specific and gives the +administrator a great deal of control over how the user is +authenticated. This form of the control flag is delimeted with square +brackets and consists of a series of <tt/value=action/ tokens: +<tscreen> +<verb> + [value1=action1 value2=action2 ...] +</verb> +</tscreen> + +<p> +Here, <tt/valueI/ is one of the following <em/return values/: +<tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/; +<tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/; +<tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/; +<tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/; +<tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/; +<tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/; +<tt/authtok_recover_err/; <tt/authtok_lock_busy/; +<tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/; +<tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and +<tt/default/. The last of these (<tt/default/) can be used to set the +action for those return values that are not explicitly defined. + +<p> +The <tt/actionI/ can be a positive integer or one of the following +tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and +<tt/reset/. A positive integer, <tt/J/, when specified as the action, +can be used to indicate that the next <em/J/ modules of the current +type will be skipped. In this way, the administrator can develop a +moderately sophisticated stack of modules with a number of different +paths of execution. Which path is taken can be determined by the +reactions of individual modules. + +<p> +<itemize> +<item><tt/ignore/ - when used with a stack of modules, the module's + return status will not contribute to the return code the application + obtains. +<item><tt/bad/ - this action indicates that the return code should be + thought of as indicative of the module failing. If this module is + the first in the stack to fail, its status value will be used for + that of the whole stack. +<item><tt/die/ - equivalent to <tt/bad/ with the side effect of + terminating the module stack and PAM immediately returning to the + application. +<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this + return code should contribute directly to the return code of the full + stack of modules. In other words, if the former state of the stack + would lead to a return of <tt/PAM_SUCCESS/, the module's return code + will override this value. Note, if the former state of the stack + holds some value that is indicative of a modules failure, this 'ok' + value will not be used to override that value. +<item><tt/done/ - equivalent to <tt/ok/ with the side effect of + terminating the module stack and PAM immediately returning to the + application. +<item><tt/reset/ - clear all memory of the state of the module stack and + start again with the next stacked module. +</itemize> + +<p> +Just to get a feel for the power of this new syntax, here is a taste +of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of +client plug-in agents was introduced. This is something that makes it +possible for PAM to support machine-machine authentication using the +transport protocol inherent to the client/server application. With +the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible +for an application to be configured to support binary prompts with +compliant clients, but to gracefully fall over into an alternative +authentication mode for older, legacy, applications. Flexible eh? + +<tag> <tt/module-path/</tag> + +The path-name of the dynamically loadable object file; <em/the +pluggable module/ itself. If the first character of the module path is +`<tt>/</tt>', it is assumed to be a complete path. If this is not the +case, the given module path is appended to the default module path: +<tt>/usr/lib/security</tt> (but see the notes <ref +id="text-conventions" name="above">). + +<tag> <tt/args/</tag> + +The <tt/args/ are a list of tokens that are passed to the module when +it is invoked. Much like arguments to a typical Linux shell command. +Generally, valid arguments are optional and are specific to any given +module. Invalid arguments are ignored by a module, however, when +encountering an invalid argument, the module is required to write an +error to <tt/syslog(3)/. For a list of <em/generic/ options see the +next section. + +</descrip> + +<p> +Any line in (one of) the confiuration file(s), that is not formatted +correctly, will generally tend (erring on the side of caution) to make +the authentication process fail. A corresponding error is written to +the system log files with a call to <tt/syslog(3)/. + +<sect1>Directory based configuration + +<p> +More flexible than the single configuration file, as of version 0.56, +it is possible to configure <tt>libpam</tt> via the contents of the +<tt>/etc/pam.d/</tt> directory. In this case the directory is filled +with files each of which has a filename equal to a service-name (in +lower-case): it is the personal configuration file for the named +service. + +<p> +<bf/Linux-PAM/ can be compiled in one of two modes. The preferred +mode uses either <tt>/etc/pam.d/</tt> or <tt>/etc/pam.conf</tt> +configuration but not both. That is to say, if there is a +<tt>/etc/pam.d/</tt> directory then libpam only uses the files +contained in this directory. However, in the absence of the +<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is +used. The other mode (and the one currently supported by Red Hat 4.2 +and higher) is to use both <tt>/etc/pam.d/</tt> and +<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in +<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>. + +The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of +the <tt>/etc/pam.conf</tt> file and is made up of lines of the +following form: +<tscreen> +<verb> +module-type control-flag module-path arguments +</verb> +</tscreen> +The only difference being that the <tt>service-name</tt> is not +present. The service-name is of course the name of the given +configuration file. For example, <tt>/etc/pam.d/login</tt> contains +the configuration for the <em>login</em> service. + +<p> +This method of configuration has a number of advantages over the +single file approach. We list them here to assist the reader in +deciding which scheme to adopt: + +<p> +<itemize> + +<item>A lower chance of misconfiguring an application. There is one +less field to mis-type when editing the configuration files by hand. + +<item>Easier to maintain. One application may be reconfigured without +risk of interfering with other applications on the system. + +<item>It is possible to symbolically link different services +configuration files to a single file. This makes it easier to keep the +system policy for access consistent across different applications. +(It should be noted, to conserve space, it is equally possible to +<em>hard</em> link a number of configuration files. However, care +should be taken when administering this arrangement as editing a hard +linked file is likely to break the link.) + +<item>A potential for quicker configuration file parsing. Only the +relevant entries are parsed when a service gets bound to its modules. + +<item>It is possible to limit read access to individual <bf/Linux-PAM/ +configuration files using the file protections of the filesystem. + +<item>Package management becomes simpler. Every time a new +application is installed, it can be accompanied by an +<tt>/etc/pam.d/</tt><em>xxxxxx</em> file. + +</itemize> + +<sect1>Generic optional arguments + +<p> +The following are optional arguments which are likely to be understood +by any module. Arguments (including these) are in general +<em/optional/. + +<p> +<descrip> +<tag><tt/debug/</tag> + +Use the <tt/syslog(3)/ call to log debugging information to the system +log files. + +<tag> <tt/no_warn/</tag> + +Instruct module to not give warning messages to the application. + +<tag> <tt/use_first_pass/</tag> + +The module should not prompt the user for a password. Instead, it +should obtain the previously typed password (from the preceding +<tt/auth/ module), and use that. If that doesn't work, then the user +will not be authenticated. (This option is intended for <tt/auth/ +and <tt/password/ modules only). + +<tag> <tt/try_first_pass/</tag> + +The module should attempt authentication with the previously typed +password (from the preceding <tt/auth/ module). If that doesn't work, +then the user is prompted for a password. (This option is intended for +<tt/auth/ modules only). + +<tag> <tt/use_mapped_pass/</tag> + +This argument is not currently supported by any of the modules in the +<bf/Linux-PAM/ distribution because of possible consequences +associated with U.S. encryption exporting restrictions. Within the +U.S., module developers are, of course, free to implement it (as are +developers in other countries). For compatibility reasons we describe +its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref +id="see-also-sec" name="bibliography"> for a pointer to this document. + +<p> +The <tt/use_mapped_pass/ argument instructs the module to take the +clear text authentication token entered by a previous module (that +requests such a token) and use it to generate an encryption/decryption +key with which to safely store/retrieve the authentication token +required for this module. In this way the user can enter a single +authentication token and be quietly authenticated by a number of +stacked modules. Obviously a convenient feature that necessarily +requires some reliably strong encryption to make it secure. +This argument is intended for the <tt/auth/ and <tt/password/ module +types only. + +<tag><tt/expose_account/</tag> + +<p> +In general the leakage of some information about user accounts is not +a secure policy for modules to adopt. Sometimes information such as +users names or home directories, or preferred shell, can be used to +attack a user's account. In some circumstances, however, this sort of +information is not deemed a threat: displaying a user's full name when +asking them for a password in a secured environment could also be +called being 'friendly'. The <tt/expose_account/ argument is a +standard module argument to encourage a module to be less discrete +about account information as it is deemed appropriate by the local +administrator. + +</descrip> + +<sect1>Example configuration file entries + +<p> +In this section, we give some examples of entries that can be present +in the <bf/Linux-PAM/ configuration file. As a first attempt at +configuring your system you could do worse than to implement these. + +<sect2>Default policy + +<p> +If a system is to be considered secure, it had better have a +reasonably secure `<tt/OTHER/' entry. The following is a paranoid +setting (which is not a bad place to start!): +<tscreen> +<verb> +# +# default; deny access +# +OTHER auth required /usr/lib/security/pam_deny.so +OTHER account required /usr/lib/security/pam_deny.so +OTHER password required /usr/lib/security/pam_deny.so +OTHER session required /usr/lib/security/pam_deny.so +</verb> +</tscreen> +Whilst fundamentally a secure default, this is not very sympathetic to +a misconfigured system. For example, such a system is vulnerable to +locking everyone out should the rest of the file become badly written. + +<p> +The module <tt/pam_deny/ (documented in a later section) is not very +sophisticated. For example, it logs no information when it is invoked +so unless the users of a system contact the administrator when failing +to execute a service application, the administrator may go for a long +while in ignorance of the fact that his system is misconfigured. + +<p> +The addition of the following line before those in the above example +would provide a suitable warning to the administrator. +<tscreen> +<verb> +# +# default; wake up! This application is not configured +# +OTHER auth required /usr/lib/security/pam_warn.so +OTHER password required /usr/lib/security/pam_warn.so +</verb> +</tscreen> +Having two ``<tt/OTHER auth/'' lines is an example of stacking. + +<p> +On a system that uses the <tt>/etc/pam.d/</tt> configuration, the +corresponding default setup would be achieved with the following file: +<tscreen> +<verb> +# +# default configuration: /etc/pam.d/other +# +auth required /usr/lib/security/pam_warn.so +auth required /usr/lib/security/pam_deny.so +account required /usr/lib/security/pam_deny.so +password required /usr/lib/security/pam_warn.so +password required /usr/lib/security/pam_deny.so +session required /usr/lib/security/pam_deny.so +</verb> +</tscreen> +This is the only explicit example we give for an <tt>/etc/pam.d/</tt> +file. In general, it should be clear how to transpose the remaining +examples to this configuration scheme. + +<p> +On a less sensitive computer, one on which the system administrator +wishes to remain ignorant of much of the power of <tt/Linux-PAM/, the +following selection of lines (in <tt>/etc/pam.conf</tt>) is likely to +mimic the historically familiar Linux setup. +<tscreen> +<verb> +# +# default; standard UNIX access +# +OTHER auth required /usr/lib/security/pam_unix_auth.so +OTHER account required /usr/lib/security/pam_unix_acct.so +OTHER password required /usr/lib/security/pam_unix_passwd.so +OTHER session required /usr/lib/security/pam_unix_session.so +</verb> +</tscreen> +In general this will provide a starting place for most applications. +Unfortunately, most is not all. One application that might require +additional lines is <em/ftpd/ if you wish to enable +<em/anonymous-ftp/. + +<p> +To enable anonymous-ftp, the following lines might be used to replace +the default (<tt/OTHER/) ones. (<bf/*WARNING*/ as of 1996/12/28 this +does not work correctly with any ftpd. Consequently, this description +may be subject to change or the application will be fixed.) +<tscreen> +<verb> +# +# ftpd; add ftp-specifics. These lines enable anonymous ftp over +# standard UNIX access (the listfile entry blocks access to +# users listed in /etc/ftpusers) +# +ftpd auth sufficient /usr/lib/security/pam_ftp.so +ftpd auth required /usr/lib/security/pam_unix_auth.so use_first_pass +ftpd auth required /usr/lib/security/pam_listfile.so \ + onerr=succeed item=user sense=deny file=/etc/ftpusers +</verb> +</tscreen> +Note, the second line is necessary since the default entries are +ignored by a service application (here <em/ftpd/) if there are +<em/any/ entries in <tt>/etc/pam.conf</tt> for that specified service. +Again, this is an example of authentication module stacking. Note the +use of the <tt/sufficient/ control-flag. It says that ``if this module +authenticates the user, ignore the subsequent <tt/auth/ +modules''. Also note the use of the ``<tt/use_first_pass/'' +module-argument, this instructs the UNIX authentication module that it +is not to prompt for a password but rely one already having been +obtained by the ftp module. + +<sect>Security issues of Linux-PAM + +<p> +This section will discuss good practices for using Linux-PAM in a +secure manner. <em>It is currently sadly lacking...suggestions are +welcome!</em> + +<sect1>If something goes wrong + +<p> +<bf/Linux-PAM/ has the potential to seriously change the security of +your system. You can choose to have no security or absolute security +(no access permitted). In general, <bf/Linux-PAM/ errs towards the +latter. Any number of configuration errors can dissable access to +your system partially, or completely. + +<p> +The most dramatic problem that is likely to be encountered when +configuring <bf/Linux-PAM/ is that of <em>deleting</em> the +configuration file(s): <tt>/etc/pam.d/*</tt> and/or +<tt>/etc/pam.conf</tt>. This will lock you out of your own system! + +<p> +To recover, your best bet is to reboot the system in single user mode +and set about correcting things from there. The following has been +<em>adapted</em> from a life-saving email on the subject from David +Wood: +<verb> +> What the hell do I do now? + +OK, don't panic. The first thing you have to realize is that +this happens to 50% of users who ever do anything with PAM. +It happened here, not once, not twice, but three times, all +different, and in the end, the solution was the same every +time. + +First, I hope you installed LILO with a delay. If you can, +reboot, hit shift or tab or something and type: + + LILO boot: linux single + +(Replace 'linux' with 'name-of-your-normal-linux-image'). +This will let you in without logging in. Ever wondered how +easy it is to break into a linux machine from the console? +Now you know. + +If you can't do that, then get yourself a bootkernel floppy +and a root disk a-la slackware's rescue.gz. (Red Hat's +installation disks can be used in this mode too.) + +In either case, the point is to get back your root prompt. + +Second, I'm going to assume that you haven't completely +nuked your pam installation - just your configuration files. +Here's how you make your configs nice again: + + cd /etc + mv pam.conf pam.conf.orig + mv pam.d pam.d.orig + mkdir pam.d + cd pam.d + +and then use vi to create a file called "other" in this +directory. It should contain the following four lines: + + auth required pam_unix_auth.so + account required pam_unix_acct.so + password required pam_unix_passwd.so + session required pam_unix_session.so + +Now you have the simplest possible PAM configuration that +will work the way you're used to. Everything should +magically start to work again. Try it out by hitting ALT-F2 +and logging in on another virtual console. If it doesn't +work, you have bigger problems, or you've mistyped +something. One of the wonders of this system (seriously, +perhaps) is that if you mistype anything in the conf files, +you usually get no error reporting of any kind on the +console - just some entries in the log file. So look there! +(Try 'tail /var/log/messages'.) + +From here you can go back and get a real configuration +going, hopefully after you've tested it first on a machine +you don't care about screwing up. :/ + +Some pointers (to make everything "right" with Red Hat...): + + Install the newest pam, pamconfig, and pwdb from the + redhat current directory, and do it all on the same + command line with rpm... + + rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-* + + Then make sure you install (or reinstall) the newest + version of libc, util-linux, wuftp, and NetKit. For + kicks you might try installing the newest versions of + the affected x apps, like xlock, but I haven't gotten + those to work at all yet. + +</verb> + +<sect1>Avoid having a weak `other' configuration + +<p> +It is not a good thing to have a weak default (<tt/OTHER/) entry. +This service is the default configuration for all PAM aware +applications and if it is weak, your system is likely to be vulnerable +to attack. + +<p> +Here is a sample "other" configuration file. The <em/pam_deny/ module will +deny access and the <em/pam_warn/ module will send a syslog message to +<tt/auth.notice/: + +<p> +<tscreen> +<verb> +# +# The PAM configuration file for the `other' service +# +auth required pam_deny.so +auth required pam_warn.so +account required pam_deny.so +account required pam_warn.so +password required pam_deny.so +password required pam_warn.so +session required pam_deny.so +session required pam_warn.so +</verb> +</tscreen> + +<sect>A reference guide for available modules + +<p> +Here, we collect together some descriptions of the various modules +available for <bf/Linux-PAM/. In general these modules should be +freely available. Where this is not the case, it will be indicated. + +<p> +Also please note the comments contained in the section <ref +id="text-conventions" name="on text conventions above"> when copying +the examples listed below. + +<!-- insert-file MODULES-SGML --> + +<sect>Files + +<p><descrip> + +<tag><tt>/usr/lib/libpam.so.*</tt></tag> + +the shared library providing applications with access to +<bf/Linux-PAM/. + +<tag><tt>/etc/pam.conf</tt></tag> + +the <bf/Linux-PAM/ configuration file. + +<tag><tt>/usr/lib/security/pam_*.so</tt></tag> + +the primary location for <bf/Linux-PAM/ dynamically loadable object +files; the modules. + +</descrip> + +<sect>See also<label id="see-also-sec"> + +<p><itemize> + +<item>The <bf/Linux-PAM/ Application Writers' Guide. + +<item>The <bf/Linux-PAM/ Module Writers' Guide. + +<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH +PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request +For Comments 86.0, October 1995. See this url: +<tt><htmlurl +url="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt" +name="http://www.pilgrim.umass.edu/pub/osf_dce/RFC/rfc86.0.txt"></tt> + +</itemize> + +<sect>Notes + +<p> +I intend to put development comments here... like ``at the moment +this isn't actually supported''. At release time what ever is in +this section will be placed in the Bugs section below! :) + +<p> +Are we going to be able to support the <tt/use_mapped_pass/ module +argument? Anyone know a cheap (free) good lawyer?! + +<p> +<itemize> +<item> +This issue may go away, as Sun have investigated adding a new +management group for mappings. In this way, libpam would have mapping +modules that could securely store passwords using strong cryptography +and in such a way that they need not be distributed with Linux-PAM. +</itemize> + +<sect>Author/acknowledgments + +<p> +This document was written by Andrew G. Morgan (morgan@linux.kernel.org) +with many contributions from +<!-- insert credits here --> +<!-- + an sgml list of people to credit for their contributions to Linux-PAM + $Id$ + --> +Chris Adams, +Peter Allgeyer, +Tim Baverstock, +Tim Berger, +Craig S. Bell, +Derrick J. Brashear, +Ben Buxton, +Seth Chaiklin, +Oliver Crow, +Chris Dent, +Marc Ewing, +Cristian Gafton, +Emmanuel Galanos, +Brad M. Garcia, +Eric Hester, +Roger Hu, +Eric Jacksch, +Michael K. Johnson, +David Kinchlea, +Olaf Kirch, +Marcin Korzonek, +Stephen Langasek, +Nicolai Langfeldt, +Elliot Lee, +Luke Kenneth Casson Leighton, +Al Longyear, +Ingo Luetkebohle, +Marek Michalkiewicz, +Robert Milkowski, +Aleph One, +Martin Pool, +Sean Reifschneider, +Jan Rekorajski, +Erik Troan, +Theodore Ts'o, +Jeff Uphoff, +Myles Uyema, +Savochkin Andrey Vladimirovich, +Ronald Wahl, +David Wood, +John Wilmes, +Joseph S. D. Yao +and +Alex O. Yuriev. + +<p> +Thanks are also due to Sun Microsystems, especially to Vipin Samar and +Charlie Lai for their advice. At an early stage in the development of +<bf/Linux-PAM/, Sun graciously made the documentation for their +implementation of PAM available. This act greatly accelerated the +development of <bf/Linux-PAM/. + +<sect>Bugs/omissions + +<p> +More PAM modules are being developed all the time. It is unlikely that +this document will ever be truely up to date! + +<p> +This manual is unfinished. Only a partial list of people is credited +for all the good work they have done. + +<sect>Copyright information for this document + +<p> +Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. +<newline> +Email: <tt><morgan@linux.kernel.org></tt> + +<p> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +<p> +<itemize> + +<item> +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +<item> +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +<item> +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + +</itemize> + +<p> +<bf/Alternatively/, this product may be distributed under the terms of +the GNU General Public License (GPL), in which case the provisions of +the GNU GPL are required <bf/instead of/ the above restrictions. +(This clause is necessary due to a potential bad interaction between +the GNU GPL and the restrictions contained in a BSD-style copyright.) + +<p> +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. + +<p> +<tt>$Id$</tt> + +</article> diff --git a/doc/ps/.cvsignore b/doc/ps/.cvsignore new file mode 100644 index 00000000..8d83f2d0 --- /dev/null +++ b/doc/ps/.cvsignore @@ -0,0 +1 @@ +pam*.ps
\ No newline at end of file diff --git a/doc/ps/README b/doc/ps/README new file mode 100644 index 00000000..3122478b --- /dev/null +++ b/doc/ps/README @@ -0,0 +1,3 @@ +$Id$ + +this is the directory for the postscipt documentation diff --git a/doc/ps/missfont.log b/doc/ps/missfont.log new file mode 100644 index 00000000..162c37a8 --- /dev/null +++ b/doc/ps/missfont.log @@ -0,0 +1,36 @@ +MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmr10 600 600 1+0/600 ljfour +MakeTeXPK cmtt10 600 600 1+0/600 ljfour +MakeTeXPK cmss10 600 600 1+0/600 ljfour +MakeTeXPK cmbx10 600 600 1+0/600 ljfour +MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmti10 600 600 1+0/600 ljfour +MakeTeXPK cmtt9 600 600 1+0/600 ljfour +MakeTeXPK cmbx12 600 600 1+0/600 ljfour +MakeTeXPK cmsy10 600 600 1+0/600 ljfour +MakeTeXPK cmmi10 600 600 1+0/600 ljfour +MakeTeXPK cmti9 600 600 1+0/600 ljfour +MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmr10 600 600 1+0/600 ljfour +MakeTeXPK cmtt10 600 600 1+0/600 ljfour +MakeTeXPK cmss10 600 600 1+0/600 ljfour +MakeTeXPK cmbx10 600 600 1+0/600 ljfour +MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmbx12 600 600 1+0/600 ljfour +MakeTeXPK cmtt9 600 600 1+0/600 ljfour +MakeTeXPK cmti10 600 600 1+0/600 ljfour +MakeTeXPK cmmi10 600 600 1+0/600 ljfour +MakeTeXPK cmsy10 600 600 1+0/600 ljfour +MakeTeXPK cmss17 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmr10 600 600 1+0/600 ljfour +MakeTeXPK cmtt10 600 600 1+0/600 ljfour +MakeTeXPK cmss10 600 600 1+0/600 ljfour +MakeTeXPK cmbx10 600 600 1+0/600 ljfour +MakeTeXPK cmbx12 720 600 magstep\(1.0\) ljfour +MakeTeXPK cmti10 600 600 1+0/600 ljfour +MakeTeXPK cmbx12 600 600 1+0/600 ljfour +MakeTeXPK cmtt9 600 600 1+0/600 ljfour +MakeTeXPK cmtt12 600 600 1+0/600 ljfour +MakeTeXPK cmti12 600 600 1+0/600 ljfour +MakeTeXPK cmsy10 600 600 1+0/600 ljfour +MakeTeXPK cmmi10 600 600 1+0/600 ljfour diff --git a/doc/specs/.cvsignore b/doc/specs/.cvsignore new file mode 100644 index 00000000..d564ba7e --- /dev/null +++ b/doc/specs/.cvsignore @@ -0,0 +1 @@ +draft-morgan-pam-*.txt diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw new file mode 100644 index 00000000..46db0013 --- /dev/null +++ b/doc/specs/draft-morgan-pam.raw @@ -0,0 +1,702 @@ +PAM working group ## A.G. Morgan +Internet Draft: ## October 6, 1999 +Document: draft-morgan-pam-07.txt ## +Expires: June 13, 2000 ## +Obsoletes: draft-morgan-pam-06.txt## + +## Pluggable Authentication Modules ## + +#$ Status of this memo + +This document is an draft specification. The latest version of this +draft may be obtained from here: + + http://linux.kernel.org/pub/linux/libs/pam/pre/doc/ + +As + + Linux-PAM-'version'-docs.tar.gz + +It is also contained in the Linux-PAM tar ball. + +#$ Abstract + +This document is concerned with the definition of a general +infrastructure for module based authentication. The infrastructure is +named Pluggable Authentication Modules (PAM for short). + +#$ Introduction + +Computers are tools. They provide services to people and other +computers (collectively we shall call these _users_ entities). In +order to provide convenient, reliable and individual service to +different entities, it is common for entities to be labelled. Having +defined a label as referring to a some specific entity, the label is +used for the purpose of protecting and allocating data resources. + +All modern operating systems have a notion of labelled entities and +all modern operating systems face a common problem: how to +authenticate the association of a predefined label with applicant +entities. + +There are as many authentication methods as one might care to count. +None of them are perfect and none of them are invulnerable. In +general, any given authentication method becomes weaker over time. It +is common then for new authentication methods to be developed in +response to newly discovered weaknesses in the old authentication +methods. + +The problem with inventing new authentication methods is the fact that +old applications do not support them. This contributes to an inertia +that discourages the overhaul of weakly protected systems. Another +problem is that individuals (people) are frequently powerless to layer +the protective authentication around their systems. They are forced +to rely on single (lowest common denominator) authentication schemes +even in situations where this is far from appropriate. + +PAM, as discussed in this document, is a generalization of the +approach first introduced in [#$R#{OSF_RFC_PAM}]. In short, it is a +general framework of interfaces that abstract the process of +authentication. With PAM, a service provider can custom protect +individual services to the level that they deem is appropriate. + +PAM has nothing explicit to say about transport layer encryption. +Within the context of this document encryption and/or compression of +data exchanges are application specific (strictly between client and +server) and orthogonal to the process of authentication. + +#$ Definitions + +Here we pose the authentication problem as one of configuring defined +interfaces between two entities. + +#$$#{players} Players in the authentication process + +PAM reserves the following words to specify unique entities in the +authentication process: + + applicant + the entity (user) initiating an application for service + [PAM associates the PAM_RUSER _item_ with this requesting user]. + + arbitrator + the entity (user) under whose identity the service application + is negotiated and with whose authority service is granted. + + user + the entity (user) whose identity is being authenticated + [PAM associates the PAM_USER _item_ with this identity]. + + server + the application that provides service, or acts as an + authenticated gateway to the requested service. This + application is completely responsible for the server end of + the transport layer connecting the server to the client. + PAM makes no assumptions about how data is encapsulated for + exchanges between the server and the client, only that full + octet sequences can be freely exchanged without corruption. + + client + application providing the direct/primary interface to + applicant. This application is completely responsible + for the client end of the transport layer connecting the + server to the client. PAM makes no assumptions about how data + is encapsulated for exchanges between the server and the + client, only that full octet sequences can be freely + exchanged without corruption. + + module + authentication binary that provides server-side support for + some (arbitrary) authentication method. + + agent + authentication binary that provides client-side support for + some (arbitrary) authentication method. + +Here is a diagram to help orient the reader: + +## +-------+ +--------+ ## +## . . . . .| agent | .| module | ## +## . +-------+ .+--------+ ## +## V | . | ## +## . | V | ## +## +---------+ +-------+ . +------+ ## +## | | |libpamc| . |libpam| ## +## | | +-------+ . +------+ ## +## |applicant| | . | ## +## | | +--------+ +----------+ ## +## | |---| client |-----------| server | ## +## +---------+ +--------+ +----------+ ## + +Solid lines connecting the boxes represent two-way interaction. The +dotted-directed lines indicate an optional connection beteween the +plugin module (agent) and the server (applicant). In the case of the +module, this represents the module invoking the 'conversation' +callback function provided to libpam by the server application when it +inititializes the libpam library. In the case of the agent, this may +be some out-of-PAM API interaction (for example directly displaying a +dialog box under X). + +#$$ Defined Data Types + +In this draft, we define two composite data types, the text string and +the binary prompt. They are the data types used to communicate +authentication requests and responses. + +#$$$#{text_string} text string + +The text string is a simple sequence of non-NUL (NUL = 0x00) +octets. Terminated with a single NUL (0x00) octet. The character set +employed in the octet sequence may be negotiated out of band, but +defaults to utf-8. + +## --------------------------- ## +## [ character data | NUL ] ## +## [ octet sequence | 0x00 ] ## +## --------------------------- ## + +Within the rest of this text, PAM text strings are delimited with a +pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}. + +#$$$#{binary_prompt} binary prompt + +A binary prompt consists of a stream of octets arranged as follows: + +## ---------------------------------------- ## +## [ u32 | u8 | (length-5 octets) ] ## +## [ length | control | data ] ## +## ---------------------------------------- ## + +That is, a 32-bit unsigned integer in network byte order, a single +unsigned byte of control information and a sequence of octets of +length (length-5). The composition of the _data_ is context dependent +but is generally not a concern for either the server or the client. It +is very much the concern of modules and agents. + +For purposes of interoperability, we define the following control +characters as legal. + +## value symbol description ## +## ------------------------------------------------- ## +## 0x01 PAM_BPC_OK - continuation packet ## +## 0x02 PAM_BPC_SELECT - initialization packet ## +## 0x03 PAM_BPC_DONE - termination packet ## +## 0x04 PAM_BPC_FAIL - unable to execute ## + +The following control characters are only legal for exchanges between +an agent and a client (it is the responsibility of the client to +enforce this rule in the face of a rogue server): + +## 0x41 PAM_BPC_GETENV - obtain client env.var ## +## 0x42 PAM_BPC_PUTENV - set client env.var ## +## 0x43 PAM_BPC_TEXT - display message ## +## 0x44 PAM_BPC_ERROR - display error message ## +## 0x45 PAM_BPC_PROMPT - echo'd text prompt ## +## 0x46 PAM_BPC_PASS - non-echo'd text prompt## + +Note, length is always equal to the total length of the binary +prompt and represented by a network ordered unsigned 32 bit integer. + +#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts + +Binary prompts of control type PAM_BPC_SELECT have a defined +data part. It is composed of three elements: + + {agent_id;'/';data} + +The agent_id is a sequence of characters satisfying the following +regexp: + + /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/ + +and has a specific form for each independent agent. + +o Agent_ids that do not contain an at-sign (@) are reserved to be + assigned by IANA (Internet Assigned Numbers Authority). Names of + this format MUST NOT be used without first registering with IANA. + Registered names MUST NOT contain an at-sign (@). + +o Anyone can define additional agents by using names in the format + name@domainname, e.g. "ouragent@example.com". The part following + the at-sign MUST be a valid fully qualified internet domain name + [RFC-1034] controlled by the person or organization defining the + name. (Said another way, if you control the email address that + your agent has as an identifier, they you are entitled to use + this identifier.) It is up to each domain how it manages its local + namespace. + +The '/' character is a mandatory delimiter, indicating the end of the +agent_id. The trailing data is of a format specific to the agent with +the given agent_id. + + +#$$ Special cases + +In a previous section (#{players}) we identified the most general +selection of authentication participants. In the case of network +authentication, it is straightforward to ascribe identities to the +defined participants. However, there are also special (less general) +cases that we recognize here. + +The primary authentication step, when a user is directly introduced +into a computer system (log's on to a workstation) is a special case. +In this situation, the client and the server are generally one +application. Before authenticating such a user, the applicant is +formally unknown: PAM_RUSER is NULL. + +Some client-server implementations (telnet for example) provide +effective full tty connections. In these cases, the four simple text +string prompting cases (see below) can be handled as in the primary +login step. In other words, the server absorbs most of the overhead of +propagating authentication messages. In these cases, there is special +client/server support for handling binary prompts. + +#$ Defined interfaces for information flow + +Here, we discuss the information exchange interfaces between the +players in the authentication process. It should be understood that +the server side is responsible for driving the authentication of the +applicant. Notably, every request received by the client from the +server must be matched with a single response from the client to the +server. + +#$$#{applicant_client} Applicant <-> client + +Once the client is invoked, requests to the applicant entity are +initiated by the client application. General clients are able to make +the following requests directly to an applicant: + + echo text string + echo error text string + prompt with text string for echo'd text string input + prompt with text string for concealed text string input + +the nature of the interface provided by the client for the benefit of +the applicant entity is client specific and not defined by PAM. + +#$$#{client_agent} Client <-> agent + +In general, authentication schemes require more modes of exchange than +the four defined in the previous section (#{applicant_client}). This +provides a role for client-loadable agents. The client and agent +exchange binary-messages that can have one of the following forms: + + client -> agent + binary prompt agent expecting binary prompt reply to client + + agent -> client + binary prompt reply from agent to clients binary prompt + +Following the acceptance of a binary prompt by the agent, the agent +may attempt to exchange information with the client before returning +its binary prompt reply. Permitted exchanges are binary prompts of the +following types: + + agent -> client + set environment variable (A) + get environment variable (B) + echo text string (C) + echo error text string (D) + prompt for echo'd text string input (E) + prompt for concealed text string input (F) + +In response to these prompts, the client must legitimately respond +with a corresponding binary prompt reply. We list a complete set of +example exchanges, including each type of legitimate response (passes +and a single fail): + +## Type | Agent request | Client response ## +## --------------------------------------------------------------- ## +## (A) | {13;PAM_BPC_PUTENV;"FOO=BAR"} | {5;PAM_BPC_OK;} ## +## | {10;PAM_BPC_PUTENV;"FOO="} | {5;PAM_BPC_OK;} ## +## | {9;PAM_BPC_PUTENV;"FOO"} (*) | {5;PAM_BPC_OK;} ## +## | {9;PAM_BPC_PUTENV;"BAR"} (*) | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (B) | {10;PAM_BPC_GETENV;"TERM"} | {11;PAM_BPC_OK;"vt100"} ## +## | {9;PAM_BPC_GETENV;"FOO"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (C) | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_OK;} ## +## | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (D) | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_OK;} ## +## | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (E) | {13;PAM_BPC_PROMPT;"login: "} | {9;PAM_BPC_OK;"joe"} ## +## | {13;PAM_BPC_PROMPT;"login: "} | {6;PAM_BPC_OK;""} ## +## | {13;PAM_BPC_PROMPT;"login: "} | {5;PAM_BPC_FAIL;} ## +## --------------------------------------------------------------- ## +## (F) | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"} ## +## | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""} ## +## | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;} ## + +(*) Used to attempt the removal of a pre-existing environment +variable. + +#$$ Client <-> server + +Once the client has established a connection with the server (the +nature of the transport protocol is not specified by PAM), the server +is responsible for driving the authentication process. + +General servers can request the following from the client: + + (to be forwarded by the client to the applicant) + echo text string + echo error text string + prompt for echo'd text string response + prompt for concealed text string response + + (to be forwarded by the client to the appropriate agent) + binary prompt for a binary prompt response + +Client side agents are required to process binary prompts. The +agents' binary prompt responses are returned to the server. + +#$$ Server <-> module + +Modules drive the authentication process. The server provides a +conversation function with which it encapsulates module-generated +requests and exchanges them with the client. Every message sent by a +module should be acknowledged. + +General conversation functions can support the following five +conversation requests: + + echo text string + echo error string + prompt for echo'd text string response + prompt for concealed text string response + binary prompt for binary prompt response + +The server is responsible for redirecting these requests to the +client. + +#$ C API for application interfaces (client and server) + +#$$ Applicant <-> client + +No API is defined for this interface. The interface is considered to +be specific to the client application. Example applications include +terminal login, (X)windows login, machine file transfer applications. + +All that is important is that the client application is able to +present the applicant with textual output and to receive textual +input from the applicant. The forms of textual exchange are listed +in an earlier section (#{applicant_client}). Other methods of +data input/output are better suited to being handled via an +authentication agent. + +#$$ Client <-> agent + +The client makes use of a general API for communicating with +agents. The client is not required to communicate directly with +available agents, instead a layer of abstraction (in the form of a +library: libpamc) takes care of loading and maintaining communication +with all requested agents. This layer of abstraction will choose which +agents to interact with based on the content of binary prompts it +receives that have the control type PAM_BPC_SELECT. + +#$$$ Client <-> libpamc + +#$$$$ Compilation information + +The C-header file provided for client-agent abstraction is included +with the following source line: + + \#include <security/pam_client.h> + +The library providing the corresponding client-agent abstraction +functions is, libpamc. + + cc .... -lpamc + +#$$$$ Initializing libpamc + +The libpamc library is initialized with a call to the following +function: + + pamc_handle_t pamc_start(void); + +This function is responsible for configuring the library and +registering the location of available agents. The location of the +available agents on the system is implementation specific. + +pamc_start() function returns NULL on failure. Otherwise, the return +value is a pointer to an opaque data type which provides a handle to +the libpamc library. On systems where threading is available, the +libpamc libraray is thread safe provided a single (pamc_handler_t *) +is used by each thread. + +#$$$$ Client (Applicant) selection of agents + +For the purpose of applicant and client review of available agents, +the following function is provided. + + char **pamc_list_agents(pamc_handle_t pch); + +This returns a list of pointers to the agent_id's of the agents which +are available on the system. The list is terminated by a NULL pointer. +It is the clients responsibility to free this memory area by calling +free() on each agent id and the block of agent_id pointers in the +result. + +PAM represents a server-driven authentication model, so by default +any available agent may be invoked in the authentication process. + +#$$$$$ Client demands agent + +If the client requires that a specific authentication agent is +satisfied during the authentication process, then the client should +call the following function, immediately after obtaining a +pamc_handle_t from pamc_start(). + + int pamc_load(pamc_handle_t pch, const char *agent_id); + +agent_id is a PAM text string (see section #{agent_ids}) and is not +suffixed with a '/' delimiter. The return value for this function is: + + PAM_BPC_TRUE - agent located and loaded. + PAM_BPC_FALSE - agent is not available. + +Note, although the agent is loaded, no data is fed to it. The agent's +opportunity to inform the client that it does not trust the server is +when the agent is shutdown. + +#$$$$$ Client marks agent as unusable + +The applicant might prefer that a named agent is marked as not +available. To do this, the client would invoke the following function +immediately after obtaining a pamc_handle_t from pam_start(). + + int pamc_disable(pamc_handle_t pch, const char *agent_id); + +here agent_id is a PAM text string containing an agent_id (section +#{agent_ids}). + +The return value for this function is: + + PAM_BPC_TRUE - agent is disabled. This is the response + independent of whether the agent is locally + available. + + PAM_BPC_FALSE - agent cannot be disabled (this may be because + it has already been invoked). + +#$$$$ Allocating and manipulating binary prompts + +All conversation between an client and an agent takes place with +respect to binary prompts. A binary prompt (see section #{binary_prompt}), is +obtained, resized and deleted via the following C-macro: + + CREATION of a binary prompt with control X1 and data length Y1: + + pamc_bp_t prompt = NULL; + PAM_BP_RENEW(&prompt, X1, Y1); + + REPLACEMENT of a binary prompt with a control X2 and data length Y2: + + PAM_BP_RENEW(&prompt, X2, Y2); + + DELETION of a binary prompt (the referenced prompt is scrubbed): + + PAM_BP_RENEW(&prompt, 0, 0); + +Note, the PAM_BP_RENEW macro always overwrites any prompt that you +call it with, deleting and liberating the old contents in a secure +fashion. Also note that PAM_BP_RENEW, when returning a prompt of data +size Y1>0, will always append a '\0' byte to the end of the prompt (at +data offset Y1). It is thus, by definition, acceptable to treat the +data contents of a binary packet as a text string (see #{text_string}). + + FILLING a binary prompt from a memory pointer U1 from offset O1 of + length L1: + + PAM_BP_FILL(prompt, O1, L1, U1); + + the CONTROL type for the packet can be obtained as follows: + + control = PAM_PB_CONTROL(prompt); + + the LENGTH of a data within the prompt (_excluding_ its header + information) can be obtained as follows: + + length = PAM_BP_LENGTH(prompt); + + the total SIZE of the prompt (_including_ its header information) + can be obtained as follows: + + size = PAM_BP_SIZE(prompt); + + EXTRACTING data from a binary prompt from offset O2 of length L2 to + a memory pointer U2: + + PAM_BP_EXTRACT(prompt, O2, L2, U2); + + If you require direct access to the raw prompt DATA, you should use + the following macro: + + __u8 *raw_data = PAM_BP_DATA(prompt); + +#$$$$ Client<->agent conversations + +All exchanges of binary prompts with agents are handled with the +single function: + + int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p); + +The return value for pamc_converse(...) is PAM_BPC_TRUE when there is +a response packet and PAM_BPC_FALSE when the client is unable to +handle the request represented by the original prompt. In this latter +case, *prompt_p is set to NULL. + +This function takes a binary prompt and returns a replacement binary +prompt that is either a request from an agent to be acted upon by the +client or the 'result' which should be forwarded to the server. In the +former case, the following macro will return 1 (PAM_BPC_TRUE) and in +all other cases, 0 (PAM_BPC_FALSE): + + PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt) + +Note, all non-NULL binary prompts returned by pamc_converse(...), are +terminated with a '\0', even when the full length of the prompt (as +returned by the agent) does not contain this delimiter. This is a +defined property of the PAM_BP_RENEW macro, and can be relied upon. + +Important security note: in certain implementations, agents are +implemented by executable binaries, which are transparently loaded and +managed by the PAM client library. To ensure there is never a leakage +of elevated privilege to an unprivileged agent, the client application +should go to some effort to lower its level of privilege. It remains +the responsibility of the applicant and the client to ensure that it +is not compromised by a rogue agent. + +#$$$$ Termination of agents + +When closing the authentication session and severing the connection +between a client and a selection of agents, the following function is +used: + + int pamc_end(pamc_handle_t *pch); + +Following a call to pamc_end, the pamc_handle_t will be invalid. + +The return value for this function is one of the following: + + PAM_BPC_TRUE - all invoked agents are content with + authentication (the server is _not_ judged + _un_trustworthy by any agent) + + PAM_BPC_FALSE - one or more agents were unsatisfied at + being terminated. In general, the client + should terminate its connection to the + server and indicate to the applicant that + the server is untrusted. + +#$$$ libpamc <-> agents + +The agents are manipulated from within libpamc. Each agent is an +executable in its own right. This permits the agent to have access to +sensitive data not accessible directly from the client. The mode of +communication between libpamc and an agent is through a pair of +pipes. The agent reads binary prompts (section #{binary_prompt}) +through its standard input file descriptor and writes response (to the +server) binary prompts and instruction binary prompts (instructions +for the client) through its standard output file descriptor. + +#$$ Client <-> server + +This interface is concerned with the exchange of text and binary +prompts between the client application and the server application. No +API is provided for this as it is considered specific to the transport +protocol shared by the client and the server. + +#$$ Server <-> modules + +The server makes use of a general API for communicating with +modules. The client is not required to communicate directly with +available modules. By abstracting the authentication interface, it +becomes possible for the local administrator to make a run time +decision about the authentication method adopted by the server. + +#$$$ Functions and definitions available to servers and modules + +[This section will document the following functions + + pam_set_item() + pam_get_item() + pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec) + pam_get_env(pam_handle_t *pamh, const char *varname) + pam_strerror(pam_handle_t *pamh, int pam_errno) +] + +#$$$ Server <-> libpam + +[This section will document the following pam_ calls: + + pam_start + pam_end + pam_authenticate (*) + pam_setcred + pam_acct_mgmt + pam_open_session + pam_close_session + pam_chauthtok (*) + +The asterisked functions may return PAM_INCOMPLETE. In such cases, the +application should be aware that the conversation function was called +and that it returned PAM_CONV_AGAIN to a module. The correct action +for the application to take in response to receiving PAM_INCOMPLETE, +is to acquire the replies so that the next time the conversation +function is called it will be able to provide the desired +responses. And then recall pam_authenticate (pam_chauthtok) with the +same arguments. Libpam will arrange that the module stack is resumed +from the module that returned before. This functionality is required +for programs whose user interface is maintained by an event loop. ] + +#$$$ libpam <-> modules + +[This section will document the following pam_ and pam_sm_ calls: + +functions provided by libpam + + pam_set_data + pam_get_data + +functions provided to libpam by each module + + groups: + AUTHENTICATION + pam_sm_authenticate + pam_sm_setcred + ACCOUNT + pam_sm_acct_mgmt + SESSION + pam_sm_open_session + pam_sm_close_session + AUTHENTICATION TOKEN MANAGEMENT + pam_sm_chauthtok +] + +#$ Security considerations + +This document is devoted to standardizing authentication +infrastructure: everything in this document has implications for +security. + +#$ Contact + +The email list for discussing issues related to this document is +<pam-list@redhat.com>. + +#$ References + +[#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication + Modules (PAM)", October 1995 + +#$ Author's Address + +Andrew G. Morgan +Email: morgan@ftp.kernel.org + +## $Id$ ## + diff --git a/doc/specs/formatter/.cvsignore b/doc/specs/formatter/.cvsignore new file mode 100644 index 00000000..8af8c897 --- /dev/null +++ b/doc/specs/formatter/.cvsignore @@ -0,0 +1,3 @@ +lex.yy.c +parse.tab.c +padout diff --git a/doc/specs/formatter/Makefile b/doc/specs/formatter/Makefile new file mode 100644 index 00000000..d73258d7 --- /dev/null +++ b/doc/specs/formatter/Makefile @@ -0,0 +1,16 @@ +LIBS=-lfl + +padout: parse.tab.o + $(CC) -o padout parse.tab.o $(LIBS) + +parse.tab.o: parse.tab.c lex.yy.c + $(CC) -c parse.tab.c + +parse.tab.c: parse.y + bison parse.y + +lex.yy.c: parse.lex + flex parse.lex + +clean: + rm -f parse.tab.o parse.tab.c lex.yy.c padout *~ core diff --git a/doc/specs/formatter/parse.lex b/doc/specs/formatter/parse.lex new file mode 100644 index 00000000..1d5c898e --- /dev/null +++ b/doc/specs/formatter/parse.lex @@ -0,0 +1,11 @@ +%% + +\#[\$]+[a-zA-Z]*(\=[0-9]+)? return NEW_COUNTER; +\#\{[a-zA-Z][a-zA-Z0-9\_]*\} return LABEL; +\# return NO_INDENT; +\#\# return RIGHT; +\\\# return HASH; +[^\n] return CHAR; +[\n] return NEWLINE; + +%% diff --git a/doc/specs/formatter/parse.y b/doc/specs/formatter/parse.y new file mode 100644 index 00000000..6da47d17 --- /dev/null +++ b/doc/specs/formatter/parse.y @@ -0,0 +1,293 @@ + +%{ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +#define MAXLINE 1000 +#define INDENT_STRING " " +#define PAPER_WIDTH 74 + + int indent=0; + int line=1; + char *last_label=NULL; + + extern void yyerror(const char *x); + extern char *get_label(const char *label); + extern void set_label(const char *label, const char *target); + char *new_counter(const char *key); + +#include "lex.yy.c" + +%} + +%union { + int def; + char *string; +} + +%token NEW_COUNTER LABEL HASH CHAR NEWLINE NO_INDENT RIGHT +%type <string> stuff text + +%start doc + +%% + +doc: +| doc NEWLINE { + printf("\n"); + ++line; +} +| doc stuff NEWLINE { + if (strlen($2) > (PAPER_WIDTH-(indent ? strlen(INDENT_STRING):0))) { + yyerror("line too long"); + } + printf("%s%s\n", indent ? INDENT_STRING:"", $2); + free($2); + indent = 1; + ++line; +} +| doc stuff RIGHT stuff NEWLINE { + char fixed[PAPER_WIDTH+1]; + int len; + + len = PAPER_WIDTH-(strlen($2)+strlen($4)); + + if (len >= 0) { + memset(fixed, ' ', len); + fixed[len] = '\0'; + } else { + yyerror("line too wide"); + fixed[0] = '\0'; + } + printf("%s%s%s\n", $2, fixed, $4); + free($2); + free($4); + indent = 1; + ++line; +} +| doc stuff RIGHT stuff RIGHT stuff NEWLINE { + char fixed[PAPER_WIDTH+1]; + int len, l; + + len = PAPER_WIDTH-(strlen($2)+strlen($4)); + + if (len < 0) { + len = 0; + yyerror("line too wide"); + } + + l = len/2; + memset(fixed, ' ', l); + fixed[l] = '\0'; + printf("%s%s%s", $2, fixed, $4); + free($2); + free($4); + + l = (len+1)/2; + memset(fixed, ' ', l); + fixed[l] = '\0'; + printf("%s%s\n", fixed, $6); + free($6); + + indent = 1; + ++line; +} +| doc stuff RIGHT stuff RIGHT stuff NEWLINE { + char fixed[PAPER_WIDTH+1]; + int len, l; + + len = PAPER_WIDTH-(strlen($2)+strlen($4)); + + if (len < 0) { + len = 0; + yyerror("line too wide"); + } + + l = len/2; + memset(fixed, ' ', l); + fixed[l] = '\0'; + printf("%s%s%s", $2, fixed, $4); + free($2); + free($4); + + l = (len+1)/2; + memset(fixed, ' ', l); + fixed[l] = '\0'; + printf("%s%s\n", fixed, $6); + free($6); + + indent = 1; + ++line; +} +; + +stuff: { + $$ = strdup(""); +} +| stuff text { + $$ = malloc(strlen($1)+strlen($2)+1); + sprintf($$,"%s%s", $1, $2); + free($1); + free($2); +} +; + +text: CHAR { + $$ = strdup(yytext); +} +| text CHAR { + $$ = malloc(strlen($1)+2); + sprintf($$,"%s%s", $1, yytext); + free($1); +} +| NO_INDENT { + $$ = strdup(""); + indent = 0; +} +| HASH { + $$ = strdup("#"); +} +| LABEL { + if (($$ = get_label(yytext)) == NULL) { + set_label(yytext, last_label); + $$ = strdup(""); + } +} +| NEW_COUNTER { + $$ = new_counter(yytext); +} +; + +%% + +typedef struct node_s { + struct node_s *left, *right; + const char *key; + char *value; +} *node_t; + +node_t label_root = NULL; +node_t counter_root = NULL; + +const char *find_key(node_t root, const char *key) +{ + while (root) { + int cmp = strcmp(key, root->key); + + if (cmp > 0) { + root = root->right; + } else if (cmp) { + root = root->left; + } else { + return root->value; + } + } + return NULL; +} + +node_t set_key(node_t root, const char *key, const char *value) +{ + if (root) { + int cmp = strcmp(key, root->key); + if (cmp > 0) { + root->right = set_key(root->right, key, value); + } else if (cmp) { + root->left = set_key(root->left, key, value); + } else { + free(root->value); + root->value = strdup(value); + } + } else { + root = malloc(sizeof(struct node_s)); + root->right = root->left = NULL; + root->key = strdup(key); + root->value = strdup(value); + } + return root; +} + +void yyerror(const char *x) +{ + fprintf(stderr, "line %d: %s\n", line, x); +} + +char *get_label(const char *label) +{ + const char *found = find_key(label_root, label); + + if (found) { + return strdup(found); + } + return NULL; +} + +void set_label(const char *label, const char *target) +{ + if (target == NULL) { + yyerror("no hanging value for label"); + target = "<??>"; + } + label_root = set_key(label_root, label, target); +} + +char *new_counter(const char *key) +{ + int i=0, j, ndollars = 0; + const char *old; + char *new; + + if (key[i++] != '#') { + yyerror("bad index"); + return strdup("<???>"); + } + + while (key[i] == '$') { + ++ndollars; + ++i; + } + + key += i; + old = find_key(counter_root, key); + new = malloc(20*ndollars); + + if (old) { + for (j=0; ndollars > 1 && old[j]; ) { + if (old[j++] == '.' && --ndollars <= 0) { + break; + } + } + if (j) { + strncpy(new, old, j); + } + if (old[j]) { + i = atoi(old+j); + } else { + new[j++] = '.'; + i = 0; + } + } else { + j=0; + while (--ndollars > 0) { + new[j++] = '0'; + new[j++] = '.'; + } + i = 0; + } + new[j] = '\0'; + sprintf(new+j, "%d", ++i); + + counter_root = set_key(counter_root, key, new); + + if (last_label) { + free(last_label); + } + last_label = strdup(new); + + return new; +} + +main() +{ + yyparse(); +} diff --git a/doc/specs/rfc86.0.txt b/doc/specs/rfc86.0.txt new file mode 100644 index 00000000..6dd5e6ea --- /dev/null +++ b/doc/specs/rfc86.0.txt @@ -0,0 +1,1851 @@ + + + + + + + + + Open Software Foundation V. Samar (SunSoft) + Request For Comments: 86.0 R. Schemers (SunSoft) + October 1995 + + + + UNIFIED LOGIN WITH + PLUGGABLE AUTHENTICATION MODULES (PAM) + + + 1. INTRODUCTION + + Since low-level authentication mechanisms constantly evolve, it is + important to shield the high-level consumers of these mechanisms + (system-entry services and users) from such low-level changes. With + the Pluggable Authentication Module (PAM) framework, we can provide + pluggability for a variety of system-entry services -- not just + system authentication _per se_, but also for account, session and + password management. PAM's ability to _stack_ authentication modules + can be used to integrate `login' with different authentication + mechanisms such as RSA, DCE, and Kerberos, and thus unify login + mechanisms. The PAM framework can also provide easy integration of + smart cards into the system. + + Modular design and pluggability have become important for users who + want ease of use. In the PC hardware arena, no one wants to set the + interrupt vector numbers or resolve the addressing conflict between + various devices. In the software arena, people also want to be able + to replace components easily for easy customization, maintenance, and + upgrades. + + Authentication software deserves special attention because + authentication forms a very critical component of any secure computer + system. The authentication infrastructure and its components may + have to be modified or replaced either because some deficiencies have + been found in the current algorithms, or because sites want to + enforce a different security policy than what was provided by the + system vendor. The replacement and modification should be done in + such a way that the user is not affected by these changes. + + The solution has to address not just how the applications use the new + authentication mechanisms in a generic fashion, but also how the user + will be authenticated to these mechanisms in a generic way. The + former is addressed by GSS-API [Linn 93], while this RFC addresses + the later; these two efforts are complementary to each other. + + Since most system-entry services (for example, `login', `dtlogin', + `rlogin', `ftp', `rsh') may want to be independent of the specific + authentication mechanisms used by the machine, it is important that + there be a framework for _plugging_ in various mechanisms. This + requires that the system applications use a standard API to interact + + + + Samar, Schemers Page 1 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + with the authentication services. If these system-entry services + remain independent of the actual mechanism used on that machine, the + system administrator can install suitable authentication modules + without requiring changes to these applications. + + For any security system to be successful, it has to be easy to use. + In the case of authentication, the single most important ease-of-use + characteristic is that the user should not be required to learn about + various ways of authentication and remember multiple passwords. + Ideally, there should be one all-encompassing authentication system + where there is only one password, but for heterogeneous sites, + multiple authentication mechanisms have to co-exist. The problem of + integrating multiple authentication mechanisms such as Kerberos + [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor + 88], is also referred to as _integrated login_, or _unified login_ + problem. Even if the user has to use multiple authentication + mechanisms, the user should not be forced to type multiple passwords. + Furthermore, the user should be able to use the new network identity + without taking any further actions. The key here is in modular + integration of the network authentication technologies with `login' + and other system-entry services. + + In this RFC we discuss the architecture and design of pluggable + authentication modules. This design gives the capability to use + field-replaceable authentication modules along with unified login + capability. It thus provides for both _pluggability_ and _ease-of- + use_. + + The RFC is organized as follows. We first motivate the need for a + generic way to authenticate the user by various system-entry services + within the operating system. We describe the goals and constraints + of the design. This leads to the architecture, description of the + interfaces, and _stacking_ of modules to get unified login + functionality. We then describe our experience with the design, and + end with a description of future work. + + + 2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS + + An identification and authentication ("I&A") mechanism is used to + establish a user's identity the system (i.e., to a local machine's + operating system) and to other principals on the network. On a + typical UNIX system, there are various ports of entry into the + system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and + `telnet'. In all cases, the user has to be identified and + authenticated before granting appropriate access rights to the user. + The user identification and authentication for all these entry points + needs to be coordinated to ensure a secure system. + + In most of the current UNIX systems, the login mechanism is based + upon verification of the password using the modified DES algorithm. + + + + Samar, Schemers Page 2 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + The security of the implementation assumes that the password cannot + be guessed, and that the password does not go over the wire in the + clear. These assumptions, however, are not universally valid. + Various programs are now available freely on the Internet that can + run dictionary attack against the encrypted password. Further, some + of the network services (for example, `rlogin', `ftp', `telnet') send + the password over in clear, and there are "sniffer" programs freely + available to steal these passwords. The classical assumptions may be + acceptable on a trusted network, but in an open environment there is + a need to use more restrictive and stronger authentication + mechanisms. Examples of such mechanisms include Kerberos, RSA, + Diffie-Hellman, one-time password [Skey 94], and challenge-response + based smart card authentication systems. Since this list will + continue to evolve, it is important that the system-entry services do + not have hard-coded dependencies on any of these authentication + mechanisms. + + + 3. DESIGN GOALS + + The goals of the PAM framework are as follows: + + (a) The system administrator should be able to choose the default + authentication mechanism for the machine. This can range from + a simple password-based mechanism to a biometric or a smart + card based system. + + (b) It should be possible to configure the user authentication + mechanism on a per application basis. For example, a site may + require S/Key password authentication for `telnet' access, + while allowing machine `login' sessions with just UNIX password + authentication. + + (c) The framework should support the display requirements of the + applications. For example, for a graphical login session such + as `dtlogin', the user name and the password may have to be + entered in a new window. For networking system-entry + applications such as `ftp' and `telnet', the user name and + password has to be transmitted over the network to the client + machine. + + (d) It should be possible to configure multiple authentication + protocols for each of those applications. For example, one may + want the users to get authenticated by both Kerberos and RSA + authentication systems. + + (e) The system administrator should be able to _stack_ multiple + user authentication mechanisms such that the user is + authenticated with all authentication protocols without + retyping the password. + + + + + Samar, Schemers Page 3 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + (f) The architecture should allow for multiple passwords if + necessary to achieve higher security for users with specific + security requirements. + + (g) The system-entry services should not be required to change when + the underlying mechanism changes. This can be very useful for + third-party developers because they often do not have the + source code for these services. + + (h) The architecture should provide for a _pluggable_ model for + system authentication, as well as for other related tasks such + as password, account, and session management. + + (i) For backward-compatibility reasons, the PAM API should support + the authentication requirements of the current system-entry + services. + + There are certain issues that the PAM framework does not specifically + address: + + (a) We focus only on providing a generic scheme through which users + use passwords to establish their identities to the machine. + Once the identity is established, how the identity is + communicated to other interested parties is outside the scope + of this design. There are efforts underway at IETF [Linn 93] + to develop a Generic Security Services Application Interface + (GSSAPI) that can be used by applications for secure and + authenticated communication without knowing the underlying + mechanism. + + (b) The _single-signon_ problem of securely transferring the + identity of the caller to a remote site is not addressed. For + example, the problem of delegating credentials from the + `rlogin' client to the other machine without typing the + password is not addressed by our work. We also do not address + the problem of sending the passwords over the network in the + clear. + + (c) We do not address the source of information obtained from the + "`getXbyY()'" family of calls (e.g., `getpwnam()'). Different + operating systems address this problem differently. For + example, Solaris uses the name service switch (NSS) to + determine the source of information for the "`getXbyY()'" + calls. It is expected that data which is stored in multiple + sources (such as passwd entries in NIS+ and the DCE registry) + is kept in sync using the appropriate commands (such as + `passwd_export'). + + + + + + + + Samar, Schemers Page 4 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + 4. OVERVIEW OF THE PAM FRAMEWORK + + We propose that the goals listed above can be met through a framework + in which authentication modules can be _plugged_ independently of the + application. We call this the _Pluggable Authentication Modules_ + (PAM) framework. + + The core components of the PAM framework are the authentication + library API (the front end) and the authentication mechanism-specific + modules (the back end), connected through the Service Provider + Interface (SPI). Applications write to the PAM API, while the + authentication-system providers write to the PAM SPI and supply the + back end modules that are independent of the application. + + ftp telnet login (Applications) + | | | + | | | + +--------+--------+ + | + +-----+-----+ + | PAM API | <-- pam.conf file + +-----+-----+ + | + +--------+--------+ + UNIX Kerberos Smart Cards (Mechanisms) + + Figure 1: The Basic PAM Architecture + + Figure 1 illustrates the relationship between the application, the + PAM library, and the authentication modules. Three applications + (`login', `telnet' and `ftp') are shown which use the PAM + authentication interfaces. When an application makes a call to the + PAM API, it loads the appropriate authentication module as determined + by the configuration file, `pam.conf'. The request is forwarded to + the underlying authentication module (for example, UNIX password, + Kerberos, smart cards) to perform the specified operation. The PAM + layer then returns the response from the authentication module to the + application. + + PAM unifies system authentication and access control for the system, + and allows plugging of associated authentication modules through well + defined interfaces. The plugging can be defined through various + means, one of which uses a configuration file, such as the one in + Table 1. For each of the system applications, the file specifies the + authentication module that should be loaded. In the example below, + `login' uses the UNIX password module, while `ftp' and `telnet' use + the S/Key module. + + + + + + + + Samar, Schemers Page 5 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + Table 1: A Simplified View of a Sample PAM Configuration File. + + service module_path + ------- ----------- + login pam_unix.so + ftp pam_skey.so + telnet pam_skey.so + + Authentication configuration is only one aspect of this interface. + Other critical components include account management, session + management, and password management. For example, the `login' + program may want to verify not only the password but also whether the + account has aged or expired. Generic interfaces also need to be + provided so that the password can be changed according to the + requirements of the module. Furthermore, the application may want to + log information about the current session as determined by the + module. + + Not all applications or services may need all of the above + components, and not each authentication module may need to provide + support for all of the interfaces. For example, while `login' may + need access to all four components, `su' may need access to just the + authentication component. Some applications may use some specific + authentication and password management modules but share the account + and session management modules with others. + + This reasoning leads to a partitioning of the entire set of + interfaces into four areas of functionality: (1) authentication, (2) + account, (3) session, and (4) password. The concept of PAM was + extended to these functional areas by implementing each of them as a + separate pluggable module. + + Breaking the functionality into four modules helps the module + providers because they can use the system-provided libraries for the + modules that they are not changing. For example, if a supplier wants + to provide a better version of Kerberos, they can just provide that + new authentication and password module, and reuse the existing ones + for account and session. + + 4.1. Module Description + + More details on specific API's are described in Appendix A. A brief + description of four modules follows: + + (a) Authentication management: This set includes the + `pam_authenticate()' function to authenticate the user, and the + `pam_setcred()' interface to set, refresh or destroy the user + credentials. + + (b) Account management: This set includes the `pam_acct_mgmt()' + function to check whether the authenticated user should be + + + + Samar, Schemers Page 6 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + given access to his/her account. This function can implement + account expiration and access hour restrictions. + + (c) Session management: This set includes the `pam_open_session()' + and `pam_close_session()' functions for session management and + accounting. For example, the system may want to store the + total time for the session. + + (d) Password management: This set includes a function, + `pam_chauthtok()', to change the password. + + + 5. FRAMEWORK INTERFACES + + The PAM framework further provides a set of administrative interfaces + to support the above modules and to provide for application-module + communication. There is no corresponding service provider interface + (SPI) for such functions. + + 5.1. Administrative Interfaces + + Each set of PAM transactions starts with `pam_start()' and ends with + the `pam_end()' function. The interfaces `pam_get_item()' and + `pam_set_item()' are used to read and write the state information + associated with the PAM transaction. + + If there is any error with any of the PAM interfaces, the error + message can be printed with `pam_strerror()'. + + 5.2. Application-Module Communication + + During application initialization, certain data such as the user name + is saved in the PAM framework layer through `pam_start()' so that it + can be used by the underlying modules. The application can also pass + opaque data to the module which the modules will pass back while + communicating with the user. + + 5.3. User-Module Communication + + The `pam_start()' function also passes conversation function that has + to be used by the underlying modules to read and write module + specific authentication information. For example, these functions + can be used to prompt the user for the password in a way determined + by the application. PAM can thus be used by graphical, non- + graphical, or networked applications. + + + + + + + + + + Samar, Schemers Page 7 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + 5.4. Inter-Module Communication + + Though the modules are independent, they can share certain common + information about the authentication session such as user name, + service name, password, and conversation function through the + `pam_get_item()' and `pam_set_item()' interfaces. These API's can + also be used by the application to change the state information after + having called `pam_start()' once. + + 5.5. Module State Information + + The PAM service modules may want to keep certain module-specific + state information about the session. The interfaces `pam_get_data()' + and `pam_set_data()' can be used by the service modules to access and + update module-specific information as needed from the PAM handle. + The modules can also attach a cleanup function with the data. The + cleanup function is executed when `pam_end()' is called to indicate + the end of the current authentication activity. + + Since the PAM modules are loaded upon demand, there is no direct + module initialization support in the PAM framework. If there are + certain initialization tasks that the PAM service modules have to do, + they should be done upon the first invocation. However, if there are + certain clean-up tasks to be done when the authentication session + ends, the modules should use `pam_set_data()' to specify the clean-up + functions, which would be called when `pam_end()' is called by the + application. + + + 6. MODULE CONFIGURATION MANAGEMENT + + Table 2 shows an example of a configuration file `pam.conf' with + support for authentication, session, account, and password management + modules. `login' has three entries: one each for authentication + processing, session management and account management. Each entry + specifies the module name that should be loaded for the given module + type. In this example, the `ftp' service uses the authentication and + session modules. Note that all services here share the same session + management module, while having different authentication modules. + + + + + + + + + + + + + + + + Samar, Schemers Page 8 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + Table 2: Configuration File (pam.conf) with Different Modules + and Control Flow + + service module_type control_flag module_path options + ------- ----------- ------------ ----------- ------- + login auth required pam_unix_auth.so nowarn + login session required pam_unix_session.so + login account required pam_unix_account.so + ftp auth required pam_skey_auth.so debug + ftp session required pam_unix_session.so + telnet session required pam_unix_session.so + login password required pam_unix_passwd.so + passwd password required pam_unix_passwd.so + OTHER auth required pam_unix_auth.so + OTHER session required pam_unix_session.so + OTHER account required pam_unix_account.so + + The first field, _service_, denotes the service (for example, + `login', `passwd', `rlogin'). The name `OTHER' indicates the module + used by all other applications that have not been specified in this + file. This name can also be used if all services have the same + requirements. In the example, since all the services use the same + session module, we could have replaced those lines with a single + `OTHER' line. + + The second field, _module_type_, indicates the type of the PAM + functional module. It can be one of `auth', `account', `session', or + `password' modules. + + The third field, _control_flag_ determines the behavior of stacking + multiple modules by specifying whether any particular module is + _required_, _sufficient_, or _optional_. The next section describes + stacking in more detail. + + The fourth field, _module_path_, specifies the location of the + module. The PAM framework loads this module upon demand to invoke + the required function. + + The fifth field, _options_, is used by the PAM framework layer to + pass module specific options to the modules. It is up to the module + to parse and interpret the options. This field can be used by the + modules to turn on debugging or to pass any module specific + parameters such as a timeout value. It is also used to support + unified login as described below. The options field can be used by + the system administrator to fine-tune the PAM modules. + + If any of the fields are invalid, or if a module is not found, that + line is ignored and the error is logged as a critical error via + `syslog(3)'. If no entries are found for the given module type, then + the PAM framework returns an error to the application. + + + + + Samar, Schemers Page 9 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + 7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING + + In the world of heterogeneous systems, the system administrator often + has to deal with the problem of integrating multiple authentication + mechanisms. The user is often required to know about the + authentication command of the new authentication module (for example, + `kinit', `dce_login') after logging into the system. This is not + user-friendly because it forces people to remember to type the new + command and enter the new password. This functionality should be + invisible instead of burdening the user with it. + + There are two problems to be addressed here: + + (a) Supporting multiple authentication mechanisms. + + (b) Providing unified login in the presence of multiple mechanisms. + + In the previous section, we described how one could replace the + default authentication module with any other module of choice. Now + we demonstrate how the same model can be extended to provide support + for multiple modules. + + 7.1. Design for Stacked Modules + + One possibility was to provide hard-coded rules in `login' or other + applications requiring authentication services [Adamson 95]. But + this becomes very specific to the particular combination of + authentication protocols, and also requires the source code of the + application. Digital's Security Integration Architecture [SIA 95] + addresses this problem by specifying the same list of authentication + modules for all applications. Since requirements for various + applications can vary, it is essential that the configuration be on a + per-application basis. + + To support multiple authentication mechanisms, the PAM framework was + extended to support _stacking_. When any API is called, the back + ends for the stacked modules are invoked in the order listed, and the + result returned to the caller. In Figure 2, the authentication + service of `login' is stacked and the user is authenticated by UNIX, + Kerberos, and RSA authentication mechanisms. Note that in this + example, there is no stacking for session or account management + modules. + + + + + + + + + + + + + Samar, Schemers Page 10 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + login + | + +--------+--------+ + | | | + session auth account + | | | + +--+--+ +--+--+ +--+--+ + | PAM | | PAM | | PAM | + +--+--+ +--+--+ +--+--+ + | | | + UNIX UNIX UNIX + session auth account + | + Kerberos + auth + | + RSA + auth + + Figure 2: Stacking With the PAM Architecture + + Stacking is specified through additional entries in the configuration + file shown earlier. As shown in Table 2, for each application (such + as `login') the configuration file can specify multiple mechanisms + that have to be invoked in the specified order. When mechanisms + fail, the _control_flag_ decides which error should be returned to + the application. Since the user should not know which authentication + module failed when a bad password was typed, the PAM framework + continues to call other authentication modules on the stack even on + failure. The semantics of the control flag are as follows: + + (a) `required': With this flag, the module failure results in the + PAM framework returning the error to the caller _after_ + executing all other modules on the stack. For the function to + be able to return success to the application all `required' + modules have to report success. This flag is normally set when + authentication by this module is a _must_. + + (b) `optional': With this flag, the PAM framework ignores the + module failure and continues with the processing of the next + module in sequence. This flag is used when the user is allowed + to login even if that particular module has failed. + + (c) `sufficient': With this flag, if the module succeeds the PAM + framework returns success to the application immediately + without trying any other modules. For failure cases, the + _sufficient_ modules are treated as `optional'. + + Table 3 shows a sample configuration file that stacks the `login' + command. Here the user is authenticated by UNIX, Kerberos, and RSA + authentication services. The `required' key word for _control_flag_ + + + + Samar, Schemers Page 11 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + enforces that the user is allowed to login only if he/she is + authenticated by _both_ UNIX and Kerberos services. RSA + authentication is optional by virtue of the `optional' key word in + the _control_flag_ field. The user can still log in even if RSA + authentication fails. + + Table 3: PAM Configuration File with Support for Stacking + + service module_type control_flag module_path options + ------- ----------- ------------ ----------- ------- + login auth required pam_unix.so debug + login auth required pam_kerb.so use_mapped_pass + login auth optional pam_rsa.so use_first_pass + + Table 4 illustrates the use of the sufficient flag for the `rlogin' + service. The Berkeley `rlogin' protocol specifies that if the remote + host is trusted (as specified in the `/etc/hosts.equiv' file or in + the `.rhosts' file in the home directory of the user), then the + `rlogin' daemon should not require the user to type the password. If + this is not the case, then the user is required to type the password. + Instead of hard coding this policy in the `rlogin' daemon, this can + be expressed with the `pam.conf' file in Table 4. The PAM module + `pam_rhosts_auth.so.1' implements the `.rhosts' policy described + above. If a site administrator wants to enable remote login with + only passwords, then the first line should be deleted. + + Table 4: PAM Configuration File for the rlogin service + + service module_type control_flag module_path options + ------- ----------- ------------ ----------- ------- + rlogin auth sufficient pam_rhosts_auth.so + rlogin auth required pam_unix.so + + 7.2. Password-Mapping + + Multiple authentication mechanisms on a machine can lead to multiple + passwords that users have to remember. One attractive solution from + the ease-of-use viewpoint is to use the same password for all + mechanisms. This, however, can also weaken the security because if + that password were to be compromised in any of the multiple + mechanisms, all mechanisms would be compromised at the same time. + Furthermore, different authentication mechanisms may have their own + distinctive password requirements in regards to its length, allowed + characters, time interval between updates, aging, locking, and so + forth. These requirements make it problematic to use the same + password for multiple authentication mechanisms. + + The solution we propose, while not precluding use of the same + password for every mechanism, allows for a different password for + each mechanism through what we call _password-mapping_. This + basically means using the user's _primary_ password to encrypt the + + + + Samar, Schemers Page 12 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + user's other (_secondary_) passwords, and storing these encrypted + passwords in a place where they are available to the user. Once the + primary password is verified, the authentication modules would obtain + the other passwords for their own mechanisms by decrypting the + mechanism-specific encrypted password with the primary password, and + passing it to the authentication service. The security of this + design for password-mapping assumes that the primary password is the + user's strongest password, in terms of its unguessability (length, + type and mix of characters used, etc.). + + If there is any error in password-mapping, or if the mapping does not + exist, the user will be prompted for the password by each + authentication module. + + To support password-mapping, the PAM framework saves the primary + password and provides it to stacked authentication modules. The + password is cleared out before the `pam_authenticate' function + returns. + + How the password is encrypted depends completely on the module + implementation. The encrypted secondary password (also called a + "mapped password") can be stored in a trusted or untrusted place, + such as a smart card, a local file, or a directory service. If the + encrypted passwords are stored in an untrusted publicly accessible + place, this does provide an intruder with opportunities for potential + dictionary attack. + + Though password-mapping is voluntary, it is recommended that all + module providers add support for the following four mapping options: + + (a) `use_first_pass': Use the same password used by the first + mechanism that asked for a password. The module should not ask + for the password if the user cannot be authenticated by the + first password. This option is normally used when the system + administrator wants to enforce the same password across + multiple modules. + + (b) `try_first_pass': This is the same as `use_first_pass', except + that if the primary password is not valid, it should prompt the + user for the password. + + (c) `use_mapped_pass': Use the password-mapping scheme to get the + actual password for this module. One possible implementation + is to get the mapped-password using the XFN API [XFN 94], and + decrypt it with the primary password to get the module-specific + password. The module should not ask for the password if the + user cannot be authenticated by the first password. The XFN + API allows user-defined attributes (such as _mapped-password_) + to be stored in the _user-context_. Using the XFN API is + particularly attractive because support for the XFN may be + found on many systems in the future. + + + + Samar, Schemers Page 13 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + (d) `try_mapped_pass': This is the same as `use_mapped_pass', + except that if the primary password is not valid, it should + prompt the user for the password. + + When passwords get updated, the PAM framework stores both the old as + well as the new password to be able to inform other dependent + authentication modules about the change. Other modules can use this + information to update the encrypted password without forcing the user + to type the sequence of passwords again. The PAM framework clears + out the passwords before returning to the application. + + Table 3 illustrates how the same password can be used by `login' for + authenticating to the standard UNIX login, Kerberos and RSA services. + Once the user has been authenticated to the primary authentication + service (UNIX `login' in this example) with the primary password, the + option `use_mapped_pass' indicates to the Kerberos module that it + should use the primary password to decrypt the stored Kerberos + password and then use the Kerberos password to get the ticket for the + ticket-granting-service. After that succeeds, the option + `use_first_pass' indicates to the RSA module that instead of + prompting the user for a password, it should use the primary password + typed earlier for authenticating the user. Note that in this + scenario, the user has to enter the password just once. + + Note that if a one-time password scheme (e.g., S/Key) is used, + password mapping cannot apply. + + 7.3. Implications of Stacking on the PAM Design + + Because of the stacking capability of PAM, we have designed the PAM + API's to not return any data to the application, except status. If + this were not the case, it would be difficult for the PAM framework + to decide which module should return data to the application. When + there is any error, the application does not know which of the + modules failed. This behavior enables (even requires) the + application to be completely independent from the modules. + + Another design decision we have made is that PAM gives only the user + name to all the underlying PAM modules, hence it is the + responsibility of the PAM modules to convert the name to their own + internal format. For example, the Kerberos module may have to + convert the UNIX user name to a Kerberos principal name. + + Stacking also forces the modules to be designed such that they can + occur anywhere in the stack without any side-effects. + + Since modules such as the authentication and the password module are + very closely related, it is important they be configured in the same + order and with compatible options. + + + + + + Samar, Schemers Page 14 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + 8. INTEGRATION WITH SMART CARDS + + Many networking authentication protocols require possession of a long + key to establish the user identity. For ease-of-use reasons, that + long key is normally encrypted with the user's password so that the + user is not required to memorize it. However, weak passwords can be + compromised through a dictionary attack and thus undermine the + stronger network authentication mechanism. Furthermore, the + encrypted data is normally stored in a centrally accessible service + whose availability depends upon the reliability of the associated + service. Solutions have been proposed to use a pass-phrase or one- + time-password, but those are much longer than the regular eight + character passwords traditionally used with UNIX `login'. This makes + the solution user-unfriendly because it requires longer strings to be + remembered and typed. + + For most authentication protocol implementations, the trust boundary + is the local machine. This assumption may not be valid in cases + where the user is mobile and has to use publicly available networked + computers. In such cases, it is required that the clear text of the + key or the password never be made available to the machine. + + Smart cards solve the above problems by reducing password exposure by + supporting a _two factor_ authentication mechanism: the first with + the possession of the card, and the second with the knowledge of the + PIN associated with the card. Not only can the smart cards be a + secure repository of multiple passwords, they can also provide the + encryption and authentication functions such that the long (private) + key is never exposed outside the card. + + The PAM framework allows for integrating smart cards to the system by + providing a smart card specific module for authentication. + Furthermore, the unified login problem is simplified because the + multiple passwords for various authentication mechanisms can be + stored on the smart card itself. This can be enabled by adding a + suitable key-word such as `use_smart_card' in the _options_ field. + + + 9. SECURITY ISSUES + + It is important to understand the impact of PAM on the security of + any system so that the site-administrator can make an informed + decision. + + (a) Sharing of passwords with multiple authentication mechanisms. + + If there are multiple authentication modules, one possibility + is to use the same password for all of them. If the password + for any of the multiple authentication system is compromised, + the user's password in all systems would be compromised. If + this is a concern, then multiple passwords might be considered + + + + Samar, Schemers Page 15 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + at the cost of ease-of-use. + + (b) Password-mapping. + + This technique of encrypting all other passwords with the + primary password assumes that it is lot more difficult to crack + the primary password and that reasonable steps have been taken + to ensure limited availability of the encrypted primary + password. If this is not done, an intruder could target the + primary password as the first point of dictionary attack. If + one of the other modules provide stronger security than the + password based security, the site would be negating the strong + security by using password-mapping. If this is a concern, then + multiple passwords might be considered at the cost of ease-of- + use. If smart cards are used, they obviate the need for + password-mapping completely. + + (c) Security of the configuration file. + + Since the policy file dictates how the user is authenticated, + this file should be protected from unauthorized modifications. + + (d) Stacking various PAM modules. + + The system administrator should fully understand the + implications of stacking various modules that will be installed + on the system and their respective orders and interactions. + The composition of various authentication modules should be + carefully examined. The trusted computing base of the machine + now includes the PAM modules. + + + 10. EXPERIENCE WITH PAM + + The PAM framework was first added in Solaris 2.3 release as a private + internal interface. PAM is currently being used by several system + entry applications such as `login', `passwd', `su', `dtlogin', + `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init', + `sac', and `ttymon'. We have found that PAM provides an excellent + framework to encapsulate the authentication-related tasks for the + entire system. The Solaris 2.3 PAM API's were hence enhanced and + simplified to support stacking. + + PAM modules have been developed for UNIX, DCE, Kerberos, S/Key, + remote user authentication, and dialpass authentication. Other PAM + modules are under development, and integration with smart cards is + being planned. + + Some third parties have used the PAM interface to extend the security + mechanisms offered by the Solaris environment. + + + + + Samar, Schemers Page 16 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + The PAM API has been accepted by Common Desktop Environment (CDE) + vendors as the API to be used for integrating the graphical interface + for login, `dtlogin' with multiple authentication mechanisms. + + + 11. FUTURE WORK + + Amongst the various components of PAM, the password component needs + to be carefully examined to see whether the stacking semantics are + particularly applicable, and how PAM should deal with partial + failures when changing passwords. + + The _control_flag_ of the configuration file can be extended to + include other semantics. For example, if the error is "name service + not available", one may want to retry. It is also possible to offer + semantics of "return success if any of the modules return success". + + In an earlier section, we had mentioned integration of smart cards + with PAM. Though we feel that integration should be straight forward + from the PAM architecture point of view, there may be some issues + with implementation because the interfaces to the smart cards have + not yet been standardized. + + One possible extension to PAM is to allow the passing of module- + specific data between applications and PAM modules. For example, the + `login' program likes to build its new environment from a select list + of variables, yet the DCE module needs the `KRB5CCNAME' variable to + be exported to the child process. For now we have modified the + `login' program to explicitly export the `KRB5CCNAME' variable. + + Administrative tools are needed to help system administrators modify + `pam.conf', and perform sanity checks on it (i.e., a `pam_check' + utility). + + + 12. CONCLUSION + + The PAM framework and the module interfaces provide pluggability for + user authentication, as well as for account, session and password + management. The PAM architecture can be used by `login' and by all + other system-entry services, and thus ensure that all entry points + for the system have been secured. This architecture enables + replacement and modification of authentication modules in the field + to secure the system against the newly found weaknesses without + changing any of the system services. + + The PAM framework can be used to integrate `login' and `dtlogin' with + different authentication mechanisms such as RSA and Kerberos. + Multiple authentication systems can be accessed with the same + password. The PAM framework also provides easy integration of smart + cards into the system. + + + + Samar, Schemers Page 17 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + PAM provides complementary functionality to GSS-API, in that it + provides mechanisms through which the user gets authenticated to any + new system-level authentication service on the machine. GSS-API then + uses the credentials for authenticated and secure communications with + other application-level service entities on the network. + + + 13. ACKNOWLEDGEMENTS + + PAM development has spanned several release cycles at SunSoft. + Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and + implementation. Bill Shannon and Don Stephenson helped with the PAM + architecture. Rocky Wu prototyped stacking of multiple modules. + Paul Fronberg, Charlie Lai, and Roland Schemers made very significant + enhancements to the PAM interfaces and took the project to completion + within a very short time. Kathy Slattery wrote the PAM + documentation. John Perry integrated PAM within the CDE framework. + + + APPENDIX A. PAM API'S + + This appendix gives an informal description of the various interfaces + of PAM. Since the goal here is just for the reader to get a working + knowledge about the PAM interfaces, not all flags and options have + been fully defined and explained. The API's described here are + subject to change. + + The PAM Service Provider Interface is very similar to the PAM API, + except for one extra parameter to pass module-specific options to the + underlying modules. + + A.1. Framework Layer API's + + int + pam_start( + char *service_name, + char *user, + struct pam_conv *pam_conversation, + pam_handle_t **pamh + ); + + `pam_start()' is called to initiate an authentication transaction. + `pam_start()' takes as arguments the name of the service, the name of + the user to be authenticated, the address of the conversation + structure. `pamh' is later used as a handle for subsequent calls to + the PAM library. + + The PAM modules do not communicate directly with the user; instead + they rely on the application to perform all such interaction. The + application needs to provide the conversation functions, `conv()', + and associated application data pointers through a `pam_conv' + + + + Samar, Schemers Page 18 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + structure when it initiates an authentication transaction. The + module uses the `conv()' function to prompt the user for data, + display error messages, or text information. + + int + pam_end( + pam_handle_t *pamh, + int pam_status + ); + + `pam_end()' is called to terminate the PAM transaction as specified + by `pamh', and to free any storage area allocated by the PAM modules + with `pam_set_item()'. + + int + pam_set_item( + pam_handle_t *pamh, + int item_type, + void *item + ); + + int + pam_get_item( + pam_handle_t *pamh, + int item_type, + void **item); + + `pam_get_item()' and `pam_set_item()' allow the parameters specified + in the initial call to `pam_start()' to be read and updated. This is + useful when a particular parameter is not available when + `pam_start()' is called or must be modified after the initial call to + `pam_start()'. `pam_set_item()' is passed a pointer to the object, + `item', and its type, `item_type'. `pam_get_item()' is passed the + address of the pointer, `item', which is assigned the address of the + requested object. + + The `item_type' is one of the following: + + Table 5: Possible Values for Item_type + + Item Name Description + --------- ----------- + PAM_SERVICE The service name + PAM_USER The user name + PAM_TTY The tty name + PAM_RHOST The remote host name + PAM_CONV The pam_conv structure + PAM_AUTHTOK The authentication token (password) + PAM_OLDAUTHTOK The old authentication token + PAM_RUSER The remote user name + + + + + Samar, Schemers Page 19 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only + available to PAM modules and not to the applications. They are + explicitly cleared out by the framework before returning to the + application. + + char * + pam_strerror( + int errnum + ); + + `pam_strerror()' maps the error number to a PAM error message string, + and returns a pointer to that string. + + int + pam_set_data( + pam_handle_t *pamh, + char *module_data_name, + char *data, + (*cleanup)(pam_handle_t *pamh, char *data, + int error_status) + ); + + The `pam_set_data()' function stores module specific data within the + PAM handle. The `module_data_name' uniquely specifies the name to + which some data and cleanup callback function can be attached. The + cleanup function is called when `pam_end()' is invoked. + + int + pam_get_data( + pam_handle_t *pamh, + char *module_data_name, + void **datap + ); + + The `pam_get_data()' function obtains module-specific data from the + PAM handle stored previously by the `pam_get_data()' function. The + `module_data_name' uniquely specifies the name for which data has to + be obtained. This function is normally used to retrieve module + specific state information. + + A.2. Authentication API's + + int + pam_authenticate( + pam_handle_t *pamh, + int flags + ); + + The `pam_authenticate()' function is called to verify the identity of + the current user. The user is usually required to enter a password + or similar authentication token, depending upon the authentication + + + + Samar, Schemers Page 20 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + module configured with the system. The user in question is specified + by a prior call to `pam_start()', and is referenced by the + authentication handle, `pamh'. + + int + pam_setcred( + pam_handle_t *pamh, + int flags + ); + + The `pam_setcred()' function is called to set the credentials of the + current process associated with the authentication handle, `pamh'. + The actions that can be denoted through `flags' include credential + initialization, refresh, reinitialization and deletion. + + A.3. Account Management API + + int + pam_acct_mgmt( + pam_handle_t *pamh, + int flags + ); + + The function `pam_acct_mgmt()' is called to determine whether the + current user's account and password are valid. This typically + includes checking for password and account expiration, valid login + times, etc. The user in question is specified by a prior call to + `pam_start()', and is referenced by the authentication handle, + `pamh'. + + A.4. Session Management API's + + int + pam_open_session( + pam_handle_t *pamh, + int flags + ); + + `pam_open_session()' is called to inform the session modules that a + new session has been initialized. All programs which use PAM should + invoke `pam_open_session()' when beginning a new session. + + int + pam_close_session( + pam_handle_t *pamh, + int flags + ); + + Upon termination of this session, the `pam_close_session()' function + should be invoked to inform the underlying modules that the session + has terminated. + + + + Samar, Schemers Page 21 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + A.5. Password Management API's + + int + pam_chauthtok( + pam_handle_t *pamh, + int flags + ); + + `pam_chauthtok()' is called to change the authentication token + associated with the user referenced by the authentication handle + `pamh'. After the call, the authentication token of the user will be + changed in accordance with the authentication module configured on + the system. + + + APPENDIX B. SAMPLE PAM APPLICATION + + This appendix shows a sample `login' application which uses the PAM + API's. It is not meant to be a fully functional login program, as + some functionality has been left out in order to emphasize the use of + PAM API's. + + #include <security/pam_appl.h> + + static int login_conv(int num_msg, struct pam_message **msg, + struct pam_response **response, void *appdata_ptr); + + static struct pam_conv pam_conv = {login_conv, NULL}; + + static pam_handle_t *pamh; /* Authentication handle */ + + void + main(int argc, char *argv[], char **renvp) + { + + /* + * Call pam_start to initiate a PAM authentication operation + */ + + if ((pam_start("login", user_name, &pam_conv, &pamh)) + != PAM_SUCCESS) + login_exit(1); + + pam_set_item(pamh, PAM_TTY, ttyn); + pam_set_item(pamh, PAM_RHOST, remote_host); + + while (!authenticated && retry < MAX_RETRIES) { + status = pam_authenticate(pamh, 0); + authenticated = (status == PAM_SUCCESS); + } + + + + + Samar, Schemers Page 22 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + if (status != PAM_SUCCESS) { + fprintf(stderr,"error: %s\n", pam_strerror(status)); + login_exit(1); + } + + /* now check if the authenticated user is allowed to login. */ + + if ((status = pam_acct_mgmt(pamh, 0)) != PAM_SUCCESS) { + if (status == PAM_AUTHTOK_EXPIRED) { + status = pam_chauthtok(pamh, 0); + if (status != PAM_SUCCESS) + login_exit(1); + } else { + login_exit(1); + } + } + + /* + * call pam_open_session to open the authenticated session + * pam_close_session gets called by the process that + * cleans up the utmp entry (i.e., init) + */ + if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) { + login_exit(status); + } + + /* set up the process credentials */ + setgid(pwd->pw_gid); + + /* + * Initialize the supplementary group access list. + * This should be done before pam_setcred because + * the PAM modules might add groups during the pam_setcred call + */ + initgroups(user_name, pwd->pw_gid); + + status = pam_setcred(pamh, PAM_ESTABLISH_CRED); + if (status != PAM_SUCCESS) { + login_exit(status); + } + + /* set the real (and effective) UID */ + setuid(pwd->pw_uid); + + pam_end(pamh, PAM_SUCCESS); /* Done using PAM */ + + /* + * Add DCE/Kerberos cred name, if any. + * XXX - The module specific stuff should be removed from login + * program eventually. This is better placed in DCE module and + * will be once PAM has routines for "exporting" environment + + + + Samar, Schemers Page 23 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + * variables. + */ + krb5p = getenv("KRB5CCNAME"); + if (krb5p != NULL) { + ENVSTRNCAT(krb5ccname, krb5p); + envinit[basicenv++] = krb5ccname; + } + environ = envinit; /* Switch to the new environment. */ + exec_the_shell(); + + /* All done */ + } + + /* + * login_exit - Call exit() and terminate. + * This function is here for PAM so cleanup can + * be done before the process exits. + */ + static void + login_exit(int exit_code) + { + if (pamh) + pam_end(pamh, PAM_ABORT); + exit(exit_code); + /*NOTREACHED*/ + } + + /* + * login_conv(): + * This is the conv (conversation) function called from + * a PAM authentication module to print error messages + * or garner information from the user. + */ + + static int + login_conv(int num_msg, struct pam_message **msg, + struct pam_response **response, void *appdata_ptr) + { + + while (num_msg--) { + switch (m->msg_style) { + + case PAM_PROMPT_ECHO_OFF: + r->resp = strdup(getpass(m->msg)); + break; + + case PAM_PROMPT_ECHO_ON: + (void) fputs(m->msg, stdout); + r->resp = malloc(PAM_MAX_RESP_SIZE); + fgets(r->resp, PAM_MAX_RESP_SIZE, stdin); + /* add code here to remove \n from fputs */ + + + + Samar, Schemers Page 24 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + break; + + case PAM_ERROR_MSG: + (void) fputs(m->msg, stderr); + break; + + case PAM_TEXT_INFO: + (void) fputs(m->msg, stdout); + break; + + default: + /* add code here to log error message, etc */ + break; + } + } + return (PAM_SUCCESS); + } + + + APPENDIX C. DCE MODULE + + This appendix describes a sample implementation of a DCE PAM module. + In order to simplify the description, we do not address the issues + raised by password-mapping or stacking. The intent is to show which + DCE calls are being made by the DCE module. + + The `pam_sm_*()' functions implement the PAM SPI functions which are + called from the PAM API functions. + + C.1. DCE Authentication Management + + The algorithm for authenticating with DCE (not including error + checking, prompting for passwords, etc.) is as follows: + + pam_sm_authenticate() + { + sec_login_setup_identity(...); + pam_set_data(...); + sec_login_valid_and_cert_ident(...); + } + + pam_sm_setcred() + { + pam_get_data(...); + sec_login_set_context(...); + } + + The `pam_sm_authenticate()' function for DCE uses the + `pam_set_data()' and `pam_get_data()' functions to keep state (like + the `sec_login_handle_t' context) between calls. The following + cleanup function is also registered and gets called when `pam_end()' + + + + Samar, Schemers Page 25 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + is called: + + dce_cleanup() + { + if (/* PAM_SUCCESS and + sec_login_valid_and_cert_ident success */) { + sec_login_release_context(...); + } else { + sec_login_purge_context(...); + } + } + + If everything was successful we release the login context, but leave + the credentials file intact. If the status passed to `pam_end()' was + not `PAM_SUCCESS' (i.e., a required module failed) we purge the login + context which also removes the credentials file. + + C.2. DCE Account Management + + The algorithm for DCE account management is as follows: + + pam_sm_acct_mgmt() + { + pam_get_data(...); + sec_login_inquire_net_info(...); + /* check for expired password and account */ + sec_login_free_net_info(...); + } + + The `sec_login_inquire_net_info()' function is called to obtain + information about when the user's account and/or password are going + to expire. A warning message is displayed (using the conversation + function) if the user's account or password is going to expire in the + near future, or has expired. These warning messages can be disabled + using the `nowarn' option in the `pam.conf' file. + + C.3. DCE Session Management + + The DCE session management functions are currently empty. They could + be modified to optionally remove the DCE credentials file upon + logout, etc. + + C.4. DCE Password Management + + The algorithm for DCE password management is as follows: + + + + + + + + + + Samar, Schemers Page 26 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + pam_sm_chauthtok + { + sec_rgy_site_open(...); + sec_rgy_acct_lookup(...); + sec_rgy_acct_passwd(...); + sec_rgy_site_close(...); + } + + The `sec_rgy_acct_passwd()' function is called to change the user's + password in the DCE registry. + + + REFERENCES + + [Adamson 95] W. A. Adamson, J. Rees, and P. Honeyman, "Joining + Security Realms: A Single Login for Netware and + Kerberos", CITI Technical Report 95-1, Center for + Information Technology Integration, University of + Michigan, Ann Arbor, MI, February 1995. + + [Diffie 76] W. Diffie and M. E. Hellman, "New Directions in + Cryptography", IEEE Transactions on Information + Theory, November 1976. + + [Linn 93] J. Linn, "Generic Security Service Application + Programming Interface", Internet RFC 1508, 1509, 1993. + + [Rivest 78] R. L. Rivest, A. Shamir, and L. Adleman., "A Method + for Obtaining Digital Signatures and Pubic-key + Cryptosystems", Communications of the ACM, 21(2), + 1978. + + [SIA 95] "Digital UNIX Security", Digital Equipment + Corporation, Order Number AA-Q0R2C-TE, July 1995. + + [Skey 94] N. M. Haller, "The S/Key One-Time Password System", + ISOC Symposium on Network and Distributed Security, + 1994. + + [Steiner 88] J.G. Steiner, B. C. Neuman, and J. I. Schiller, + "Kerberos, An Authentication Service for Open Network + Systems", in Proceedings of the Winter USENIX + Conference, Dallas, Jan 1988. + + [Taylor 88] B. Taylor and D. Goldberg, "Secure Networking in the + Sun Environment", Sun Microsystems Technical Paper, + 1988. + + [XFN 94] "Federated Naming: the XFN Specifications", X/Open + Preliminary Specification, X/Open Document #P403, + ISBN:1-85912-045-8, X/Open Co. Ltd., July 1994. + + + + Samar, Schemers Page 27 + + + + + + + + OSF-RFC 86.0 PAM October 1995 + + + + AUTHOR'S ADDRESS + + Vipin Samar Internet email: vipin@eng.sun.com + SunSoft, Inc. Telephone: +1-415-336-1002 + 2550 Garcia Avenue + Mountain View, CA 94043 + USA + + Roland J. Schemers III Internet email: schemers@eng.sun.com + SunSoft, Inc. Telephone: +1-415-336-1035 + 2550 Garcia Avenue + Mountain View, CA 94043 + USA + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Samar, Schemers Page 28 + + + + + + diff --git a/doc/txts/.cvsignore b/doc/txts/.cvsignore new file mode 100644 index 00000000..f35c3921 --- /dev/null +++ b/doc/txts/.cvsignore @@ -0,0 +1 @@ +pam*.txt diff --git a/doc/txts/README b/doc/txts/README new file mode 100644 index 00000000..540b09b5 --- /dev/null +++ b/doc/txts/README @@ -0,0 +1,3 @@ +$Id$ + +This is a directory for text versions of the pam documentation |