PAM Library Functions pamsm(3PAM)
NAME
pamsm - PAM Service Module APIs
SYNOPSIS
#include
#include
cc [ flag ...] file ... -lpam [ library ...]
DESCRIPTION
PAM gives system administrators the flexibility of choosing
any authentication service available on the system to per-
form authentication. The framework also allows new authenti-
cation service modules to be plugged in and made available
without modifying the applications.
The PAM framework, libpam, consists of an interface library
and multiple authentication service modules. The PAM inter-
face library is the layer that implements the Application
Programming Interface ( API ). The authentication service
modules are a set of dynamically loadable objects invoked by
the PAM API to provide a particular type of user authentica-
tion.
This manual page gives an overview of the PAM APIs for the
service modules, also called the Service Provider Interface
(PAM-SPI).
Interface Overview
The PAM service module interface consists of functions which
can be grouped into four categories. The names for all the
authentication library functions start with pamsm. The only
difference between the pam*() interfaces and their
corresponding pamsm*() interfaces is that all the
pamsm*() interfaces require extra parameters to pass
service-specific options to the shared modules. They are
otherwise identical.
The first category contains functions to authenticate an
individual user, pamsmauthenticate(3PAM), and to set the
credentials of the user, pamsmsetcred(3PAM). These back-
end functions implement the functionality of
pamauthenticate(3PAM) and pamsetcred(3PAM) respectively.
The second category contains the function to do account
management: pamsmacctmgmt(3PAM). This includes checking
for password aging and access-hour restrictions. This back-
end function implements the functionality of
SunOS 5.11 Last change: 16 Mar 2005 1
PAM Library Functions pamsm(3PAM)
pamacctmgmt(3PAM).
The third category contains the functions
pamsmopensession(3PAM) and pamsmclosesession(3PAM) to
perform session management after access to the system has
been granted. These back-end functions implement the func-
tionality of pamopensession(3PAM) and
pamclosesession(3PAM), respectively.
The fourth category consists a function to change authenti-
cation tokens pamsmchauthtok(3PAM). This back-end function
implements the functionality of pamchauthtok(3PAM).
Stateful Interface
A sequence of calls sharing a common set of state informa-
tion is referred to as an authentication transaction. An
authentication transaction begins with a call to
pamstart(). pamstart() allocates space, performs various
initialization activities, and assigns an authentication
handle to be used for subsequent calls to the library. Note
that the service modules do not get called or initialized
when pamstart() is called. The modules are loaded and the
symbols resolved upon first use of that function.
The PAM handle keeps certain information about the transac-
tion that can be accessed through the pamgetitem() API.
Though the modules can also use pamsetitem() to change any
of the item information, it is recommended that nothing be
changed except PAMAUTHTOK and PAMOLDAUTHTOK.
If the modules want to store any module specific state
information then they can use the pamsetdata(3PAM) func-
tion to store that information with the PAM handle. The data
should be stored with a name which is unique across all
modules and module types. For example,
SUNWPAMUNIXAUTHuserid can be used as a name by the UNIX
module to store information about the state of user's
authentication. Some modules use this technique to share
data across two different module types.
Also, during the call to pamauthenticate(), the UNIX module
may store the authentication status (success or reason for
failure) in the handle, using a unique name such as
SUNWSECURERPCDATA. This information is intended for use
by pamsetcred().
SunOS 5.11 Last change: 16 Mar 2005 2
PAM Library Functions pamsm(3PAM)
During the call to pamacctmgmt(), the account modules may
store data in the handle to indicate which passwords have
aged. This information is intended for use by
pamchauthtok().
The module can also store a cleanup function associated with
the data. The PAM framework calls this cleanup function,
when the application calls pamend() to close the transac-
tion.
Interaction with the User
The PAM service modules do not communicate directly with the
user; instead they rely on the application to perform all
such interactions. The application passes a pointer to the
function, conv(), along with any associated application data
pointers, through the pamconv structure when it initiates
an authentication transaction (by means of a call to
pamstart(). The service module will then use the function,
conv(), to prompt the user for data, output error messages,
and display text information. Refer to pamstart(3PAM) for
more information. The modules are responsible for the local-
ization of all messages to the user.
Conventions
By convention, applications that need to prompt for a user
name should call pamsetitem() and set the value of
PAMUSERPROMPT before calling pamauthenticate(). The ser-
vice module's pamsmauthenticate() function will then call
pamgetuser() to prompt for the user name. Note that cer-
tain PAM service modules (such as a smart card module) may
override the value of PAMUSERPROMPT and pass in their own
prompt.
Though the PAM framework enforces no rules about the
module's names, location, options and such, there are cer-
tain conventions that all module providers are expected to
follow.
By convention, the modules should be located in the
/usr/lib/security directory. Additional modules may be
located in /opt//lib. Architecture specific libraries
(for example, sparcv9 or amd64) are located in their respec-
tive subdirectories.
For every such module, there should be a corresponding
manual page in section 5 which should describe the
moduletype it supports, the functionality of the module,
along with the options it supports. The dependencies should
SunOS 5.11 Last change: 16 Mar 2005 3
PAM Library Functions pamsm(3PAM)
be clearly identified to the system administrator. For exam-
ple, it should be made clear whether this module is a
stand-alone module or depends upon the presence of some
other module. One should also specify whether this module
should come before or after some other module in the stack.
By convention, the modules should support the following
options:
debug Syslog debugging information at LOGDEBUG level.
Be careful as to not log any sensitive information
such as passwords.
nowarn Turn off warning messages such as "password is
about to expire."
If an unsupported option is passed to the modules, it should
syslog the error at LOGER level.
The permission bits on the service module should be set such
that it is not writable by either "group" or "other." The
service module should also be owned by root. The PAM frame-
work will not load the module if the above permission rules
are not followed.
ERORS
If there are any errors, the modules should log them using
syslog(3C) at the LOGER level.
RETURN VALUES
The PAM service module functions may return any of the PAM
error numbers specified in the specific man pages. It can
also return a PAMIGNORE error number to mean that the PAM
framework should ignore this module regardless of whether it
is required, optional or sufficient. This error number is
normally returned when the module does not contribute to the
decision being made by the PAM framework.
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
SunOS 5.11 Last change: 16 Mar 2005 4
PAM Library Functions pamsm(3PAM)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe with exceptions
SEE ALSO
pam(3PAM), pamauthenticate(3PAM), pamchauthtok(3PAM),
pamgetuser(3PAM), pamopensession(3PAM),
pamsetcred(3PAM), pamsetitem(3PAM),
pamsmauthenticate(3PAM), pamsmchauthtok(3PAM),
pamsmopensession(3PAM), pamsmsetcred(3PAM),
pamstart(3PAM), pamstrerror(3PAM), syslog(3C),
pam.conf(4), attributes(5), pamauthtokcheck(5),
pamauthtokget(5), pamauthtokstore(5), pamdhkeys(5),
pampasswdauth(5), pamunixaccount(5), pamunixauth(5),
pamunixsession(5)
NOTES
The interfaces in libpam are MT-Safe only if each thread
within the multithreaded application uses its own PAM han-
dle.
SunOS 5.11 Last change: 16 Mar 2005 5
|
