diff --git a/MANIFEST b/MANIFEST index 54f2846..c94f0c3 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1,5 +1,5 @@ # -# $P4: //depot/projects/openpam/MANIFEST#10 $ +# $P4: //depot/projects/openpam/MANIFEST#11 $ # CREDITS HISTORY @@ -15,6 +15,7 @@ bin/su/su.c doc/Makefile doc/man/Makefile doc/man/openpam.3 +doc/man/openpam.man doc/man/openpam_borrow_cred.3 doc/man/openpam_free_data.3 doc/man/openpam_get_option.3 @@ -23,10 +24,13 @@ doc/man/openpam_nullconv.3 doc/man/openpam_restore_cred.3 doc/man/openpam_set_option.3 doc/man/openpam_ttyconv.3 +doc/man/pam.3 +doc/man/pam.man doc/man/pam_acct_mgmt.3 doc/man/pam_authenticate.3 doc/man/pam_chauthtok.3 doc/man/pam_close_session.3 +doc/man/pam_conv.3 doc/man/pam_end.3 doc/man/pam_error.3 doc/man/pam_get_authtok.3 diff --git a/doc/man/Makefile b/doc/man/Makefile index e9f254a..9c97388 100644 --- a/doc/man/Makefile +++ b/doc/man/Makefile @@ -31,64 +31,75 @@ # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # -# $P4: //depot/projects/openpam/doc/man/Makefile#9 $ +# $P4: //depot/projects/openpam/doc/man/Makefile#10 $ # GENDOC = ${.CURDIR}/../../misc/gendoc.pl -CMAN = -CMAN += openpam_borrow_cred.3 -CMAN += openpam_free_data.3 -CMAN += openpam_get_option.3 -CMAN += openpam_log.3 -CMAN += openpam_nullconv.3 -CMAN += openpam_restore_cred.3 -CMAN += openpam_set_option.3 -CMAN += openpam_ttyconv.3 -CMAN += pam_acct_mgmt.3 -CMAN += pam_authenticate.3 -CMAN += pam_chauthtok.3 -CMAN += pam_close_session.3 -CMAN += pam_end.3 -CMAN += pam_error.3 -CMAN += pam_get_authtok.3 -CMAN += pam_get_data.3 -CMAN += pam_get_item.3 -CMAN += pam_get_user.3 -CMAN += pam_getenv.3 -CMAN += pam_getenvlist.3 -CMAN += pam_info.3 -CMAN += pam_open_session.3 -CMAN += pam_prompt.3 -CMAN += pam_putenv.3 -CMAN += pam_set_data.3 -CMAN += pam_set_item.3 -CMAN += pam_setcred.3 -CMAN += pam_setenv.3 -CMAN += pam_sm_acct_mgmt.3 -CMAN += pam_sm_authenticate.3 -CMAN += pam_sm_chauthtok.3 -CMAN += pam_sm_close_session.3 -CMAN += pam_sm_open_session.3 -CMAN += pam_sm_setcred.3 -CMAN += pam_start.3 -CMAN += pam_strerror.3 -CMAN += pam_verror.3 -CMAN += pam_vinfo.3 -CMAN += pam_vprompt.3 +# Standard PAM API +PMAN = +PMAN += pam_acct_mgmt.3 +PMAN += pam_authenticate.3 +PMAN += pam_chauthtok.3 +PMAN += pam_close_session.3 +PMAN += pam_end.3 +PMAN += pam_get_data.3 +PMAN += pam_get_item.3 +PMAN += pam_get_user.3 +PMAN += pam_getenv.3 +PMAN += pam_getenvlist.3 +PMAN += pam_open_session.3 +PMAN += pam_putenv.3 +PMAN += pam_set_data.3 +PMAN += pam_set_item.3 +PMAN += pam_setcred.3 +PMAN += pam_start.3 +PMAN += pam_strerror.3 -MAN = ${CMAN} +# Standard module API +MMAN = +MMAN += pam_sm_acct_mgmt.3 +MMAN += pam_sm_authenticate.3 +MMAN += pam_sm_chauthtok.3 +MMAN += pam_sm_close_session.3 +MMAN += pam_sm_open_session.3 +MMAN += pam_sm_setcred.3 + +# OpenPAM extensions +OMAN = +OMAN += openpam_borrow_cred.3 +OMAN += openpam_free_data.3 +OMAN += openpam_get_option.3 +OMAN += openpam_log.3 +OMAN += openpam_nullconv.3 +OMAN += openpam_restore_cred.3 +OMAN += openpam_set_option.3 +OMAN += openpam_ttyconv.3 +OMAN += pam_error.3 +OMAN += pam_get_authtok.3 +OMAN += pam_info.3 +OMAN += pam_prompt.3 +OMAN += pam_setenv.3 +OMAN += pam_verror.3 +OMAN += pam_vinfo.3 +OMAN += pam_vprompt.3 + +MAN = ${PMAN} ${OMAN} ${MMAN} MAN += openpam.3 -MLINKS = openpam.3 pam.3 +MAN += pam.3 +MAN += pam_conv.3 -CLEANFILES += ${CMAN} openpam.3 +CLEANFILES += ${PMAN} ${OMAN} ${MMAN} openpam.3 pam.3 -.for man in ${CMAN} +.for man in ${PMAN} ${OMAN} ${MMAN} ${man}: ${.CURDIR}/../../lib/${man:R}.c ${GENDOC} perl -w ${GENDOC} ${.CURDIR}/../../lib/${man:R}.c .endfor -openpam.3: ${CMAN} ${GENDOC} - perl -w ${GENDOC} -s ${CMAN} +openpam.3: ${OMAN} ${GENDOC} openpam.man + perl -w ${GENDOC} -o ${OMAN} <${.CURDIR}/openpam.man + +pam.3: ${PMAN} ${GENDOC} pam.man + perl -w ${GENDOC} -p ${PMAN} <${.CURDIR}/pam.man .include diff --git a/doc/man/openpam.man b/doc/man/openpam.man new file mode 100644 index 0000000..a781967 --- /dev/null +++ b/doc/man/openpam.man @@ -0,0 +1,12 @@ +.\" +.\" $P4: //depot/projects/openpam/doc/man/openpam.man#1 $ +.\" +.Sh DESCRIPTION +These functions are OpenPAM extensions to the PAM API. Those named +.Fn pam_* +are, in the author's opinion, logical and necessary extensions to the +standard API, while those named +.Fn openpam_* +are either simple convenience functions, or functions intimately tied +to OpenPAM implementation details, and therefore not well suited to +standardization. diff --git a/doc/man/pam.man b/doc/man/pam.man new file mode 100644 index 0000000..b14a7b8 --- /dev/null +++ b/doc/man/pam.man @@ -0,0 +1,98 @@ +.\" +.\" $P4: //depot/projects/openpam/doc/man/pam.man#1 $ +.\" +.Sh DESCRIPTION +The Pluggable Authentication Modules (PAM) library abstracts a number +of common authentication-related operations and provides a framework +for dynamically loaded modules that implement these operations in +various ways. +.Ss Terminology +In PAM parlance, the application that uses PAM to authenticate a user +is the server, and is identified for configuration purposes by a +service name, which is often (but not necessarily) the program name. +.Pp +The user requesting authentication is called the applicant, while the +user (usually, root) charged with verifying his identity and granting +him the requested credentials is called the arbitrator. +.Pp +The sequence of operations the server goes through to authenticate a +user and perform whatever task he requested is a PAM transaction; the +context within which the server performs the requested task is called +a session. +.Pp +The functionality embodied by PAM is divided into six primitives +grouped into four facilities: authentication, account management, +session management and password management. +.Ss Conversation +The PAM library expects the application to provide a conversation +callback which it can use to communicate with the user. +Some modules may use specialized conversation functions to communicate +with special hardware such as cryptographic dongles or biometric +devices. +See +.Xr pam_conv 3 +for details. +.Ss Initialization And Cleanup +The +.Fn pam_start +function initializes the PAM library and returns a handle which must +be provided in all subsequent function calls. +The transaction state is contained entirely within the structure +identified by this handle, so it is possible to conduct multiple +transactions in parallel. +.Pp +The +.Fn pam_end +function releases all resources associated with the specified context, +and can be called at any time to terminate a PAM transaction. +.Ss Storage +The +.Fn pam_set_item +and +.Fn pam_get_item +functions set and retrieve a number of predefined items, including the +service name, the names of the requesting and target users, the +conversation function, and prompts. +.Pp +The +.Fn pam_set_data +and +.Fn pam_get_data +manage named chunks of free-form data, generally used by modules to +store state from one invocation to another. +.Ss Authentication +There are two authentication primitives: +.Fn pam_authenticate +and +.Fn pam_setcred . +The former authenticates the user, while the latter manages his +credentials. +.Ss Account Management +The +.Fn pam_acct_mgmt +function enforces policies such as password expiry, account expiry, +time-of-day restrictions, and so forth. +.Ss Session Management +The +.Fn pam_open_session +and +.Fn pam_close_session +handle session setup and teardown. +.Ss Password Management +The +.Fn pam_chauthtok +function allows the server to change the user's password, either at +the user's request or because the password has expired. +.Ss Miscellaneous +The +.Fn pam_putenv , +.Fn pam_getenv +and +.Fn pam_getenvlist +manage a private environment list in which modules can set environment +variables they want the server to export during the session. +.Pp +The +.Fn pam_strerror +function returns a pointer to a string describing a the specified PAM +error code. diff --git a/doc/man/pam_conv.3 b/doc/man/pam_conv.3 new file mode 100644 index 0000000..bd22b3b --- /dev/null +++ b/doc/man/pam_conv.3 @@ -0,0 +1,182 @@ +.\"- +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by ThinkSec AS and +.\" NAI Labs, the Security Research Division of Network Associates, Inc. +.\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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. +.\" +.\" $P4: //depot/projects/openpam/doc/man/pam_conv.3#1 $ +.\" +.Dd May 27, 2002 +.Dt PAM_CONV 3 +.Os +.Sh NAME +.Nm pam_conv +.Nd PAM conversation system +.Sh LIBRARY +.Lb libpam +.Sh SYNOPSIS +.In security/pam_appl.h +.Bd -literal +struct pam_message { + int msg_style; + char *msg; +}; + +struct pam_response { + char *resp; + int resp_retcode; +}; + +struct pam_conv { + int (*conv)(int, const struct pam_message **, + struct pam_response **, void *); + void *appdata_ptr; +}; +.Ed +.Sh DESCRIPTION +The PAM library uses an application-defined callback to communicate +with the user. +This callback is specified by the +.Vt struct pam_conv +passed to +.Fn pam_start +at the start of the transaction. +It is also possible to set or change the conversation function at any +point during a PAM transaction by changing the value of the +.Dv PAM_CONV +item. +.Pp +The conversation function's first argument specifies the number of +messages (up to +.Dv PAM_NUM_MSG ) +to process. +The second argument is a pointer to a contiguous array of +.Vt struct pam_message +containing the actual messages. +.Pp +Each message can have one of four types, specified by the +.Va msg_style +member of +.Vt struct pam_message : +.Bl -tag -width 18n +.It Dv PAM_PROMPT_ECHO_OFF +Display a prompt and accept the user's response without echoing it to +the terminal. +This is commonly used for passwords. +.It Dv PAM_PROMPT_ECHO_ON +Display a prompt and accept the user's response, echoing it to the +terminal. +This is commonly used for login names and one-time passphrases. +.It Dv PAM_ERROR_MSG +Display an error message. +.It Dv PAM_TEXT_INFO +Display an informational message. +.El +.Pp +In each case, the prompt or message to display is pointed to by the +.Va msg +member of +.Vt struct pam_message . +It can be up to +.Dv PAM_MAX_MSG_SIZE +characters long, including the terminating NUL. +.Pp +On success, the conversation function should allocate and fill a +contiguous array of +.Vt struct pam_response , +one for each message that was passed in. +A pointer to the user's response to each message (or +.Dv NULL +in the case of informational or error messages) should be stored in +the +.Va resp +member of the corresponding +.Vt struct pam_response . +Each response can be up to +.Dv PAM_MAX_RESP_SIZE +characters long, including the terminating NUL. +.Pp +The +.Va resp_retcode +member of +.Vt struct pam_response +is unused and should be set to zero. +.Pp +The conversation function should store a pointer to this array in the +location pointed to by its third argument. +It is the caller's responsibility to release both this array and the +responses themselves, using +.Xr free 3 . +It is the conversation function's responsibility to ensure that it is +legal to do so. +.Pp +The +.Va appdata_ptr +member of +.Vt struct pam_conv +is passed unmodified to the conversation function as its fourth and +final argument. +.Pp +On failure, the conversation function should release any resources it +has allocated, and return one of the predefined PAM error codes. +.Sh RETURN VALUES +The conversation function should return one of the following values: +.Bl -tag -width 18n +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_SYSTEM_ERR +System error. +.El +.Sh SEE ALSO +.Xr openpam_ttyconv 3 , +.Xr openpam_nullconv 3 , +.Xr pam 3 , +.Xr pam_error 3 , +.Xr pam_get_item 3 , +.Xr pam_info 3 , +.Xr pam_prompt 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The OpenPAM library and this manual page were developed for the +FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research +Division of Network Associates, Inc. under DARPA/SPAWAR contract +N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/lib/pam_start.c b/lib/pam_start.c index c1b301d..726a54e 100644 --- a/lib/pam_start.c +++ b/lib/pam_start.c @@ -31,7 +31,7 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * $P4: //depot/projects/openpam/lib/pam_start.c#14 $ + * $P4: //depot/projects/openpam/lib/pam_start.c#15 $ */ #include @@ -98,14 +98,7 @@ pam_start(const char *service, * It is stored in the =PAM_USER item in the created context. * * The =pam_conv argument points to a =struct pam_conv describing the - * conversation function to use. - * This structure is defined as follows: - * - * struct pam_conv { - * int (*conv)(int, const struct pam_message **, - * struct pam_response **, void *); - * void *appdata_ptr; - * }; + * conversation function to use; see =pam_conv for details. * * >pam_get_item * >pam_set_item diff --git a/misc/gendoc.pl b/misc/gendoc.pl index 97e546d..e0310f5 100644 --- a/misc/gendoc.pl +++ b/misc/gendoc.pl @@ -32,7 +32,7 @@ # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # -# $P4: //depot/projects/openpam/misc/gendoc.pl#15 $ +# $P4: //depot/projects/openpam/misc/gendoc.pl#16 $ # use strict; @@ -455,51 +455,77 @@ sub readproto($) { } } -sub gensummary() { +sub gensummary($) { + my $page = shift; # Which page to produce local *FILE; + my $upage; my $func; + my %xref; - sysopen(FILE, "openpam.3", O_RDWR|O_CREAT|O_TRUNC) - or die("openpam.3: $!\n"); + sysopen(FILE, "$page.3", O_RDWR|O_CREAT|O_TRUNC) + or die("$page.3: $!\n"); + $upage = uc($page); print FILE "$COPYRIGHT .Dd $TODAY -.Dt PAM 3 +.Dt $upage 3 .Os .Sh NAME "; - foreach $func (sort(keys(%FUNCTIONS))) { - print FILE ".Nm $FUNCTIONS{$func}->{'Nm'}\n"; + my @funcs = sort(keys(%FUNCTIONS)); + while ($func = shift(@funcs)) { + print FILE ".Nm $FUNCTIONS{$func}->{'Nm'}"; + print FILE " ," + if (@funcs); + print FILE "\n"; } print FILE ".Nd Pluggable Authentication Modules Library .Sh LIBRARY .Lb libpam -.Sh SYNOPSIS -.In security/pam_appl.h -"; +.Sh SYNOPSIS\n"; + if ($page eq 'pam') { + print FILE ".In security/pam_appl.h\n"; + } else { + print FILE ".In security/openpam.h\n"; + } foreach $func (sort(keys(%FUNCTIONS))) { print FILE ".Ft $FUNCTIONS{$func}->{'Ft'}\n"; print FILE ".Fn $FUNCTIONS{$func}->{'Fn'}\n"; } - print FILE ".Sh DESCRIPTION -.Sh RETURN VALUES -The following return codes are defined in the -.In security/pam_constants.h -header: + while () { + if (m/^\.Xr (\S+)\s*(\d)\s*$/) { + $xref{$1} = $2; + } + print FILE $_; + } + + if ($page eq 'pam') { + print FILE ".Sh RETURN VALUES +The following return codes are defined by +.Aq Pa security/pam_constants.h : .Bl -tag -width 18n "; - foreach (sort(keys(%PAMERR))) { - print FILE ".It Bq Er $_\n$PAMERR{$_}.\n"; + foreach (sort(keys(%PAMERR))) { + print FILE ".It Bq Er $_\n$PAMERR{$_}.\n"; + } + print FILE ".El\n"; } - print FILE ".El -.Sh SEE ALSO + print FILE ".Sh SEE ALSO "; - foreach $func (sort(keys(%FUNCTIONS))) { - print FILE ".Xr $func 3 ,\n"; + print FILE ".Xr openpam 3\n" + if ($page eq 'pam'); + foreach $func (keys(%FUNCTIONS)) { + $xref{$func} = 3; } - print FILE ".Xr pam.conf 5 -.Sh STANDARDS + my @refs = sort(keys(%xref)); + while ($_ = shift(@refs)) { + print FILE ".Xr $_ $xref{$_}"; + print FILE " ," + if (@refs); + print FILE "\n"; + } + print FILE ".Sh STANDARDS .Rs .%T \"X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules\" .%D \"June 1997\" @@ -525,14 +551,17 @@ MAIN:{ my %opts; usage() - unless (@ARGV && getopts("s", \%opts)); + unless (@ARGV && getopts("op", \%opts)); $TODAY = strftime("%B %e, %Y", localtime(time())); $TODAY =~ s,\s+, ,g; - if ($opts{'s'}) { + if ($opts{'o'} || $opts{'p'}) { foreach my $fn (@ARGV) { readproto($fn); } - gensummary(); + gensummary('openpam') + if ($opts{'o'}); + gensummary('pam') + if ($opts{'p'}); } else { foreach my $fn (@ARGV) { my $func = parse_source($fn);