OpenPAM/OpenPAM
OpenPAM
/
OpenPAM
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Split the summar page in two (one for the standard API, one for 

extensions).  Also add a page about the conversation system, and
remove that information from the pam_start page.

Sponsored by:	DARPA, NAI Labs


git-svn-id: svn+ssh://svn.openpam.org/svn/openpam/trunk@153 185d5e19-27fe-0310-9dcf-9bff6b9f3609
This commit is contained in:
Dag-Erling Smørgrav 2002-05-28 00:58:47 +00:00
parent 6caa430884
commit f414e56812
7 changed files with 412 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
MANIFEST
View File

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

105
doc/man/Makefile
View File

@ -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 <bsd.prog.mk>

12
doc/man/openpam.man Normal file
View File

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

98
doc/man/pam.man Normal file
View File

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

182
doc/man/pam_conv.3 Normal file
View File

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

11
lib/pam_start.c
View File

@ -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 <stdlib.h>
@ -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

81
misc/gendoc.pl
View File

@ -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 (<STDIN>) {
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);