PAM Library Functions pam(3PAM)
NAME
pam - PAM (Pluggable Authentication Module)
SYNOPSIS
#include
cc [ flag... ] file ... -lpam [ library ... ]
DESCRIPTION
The PAM framework, libpam, consists of an interface library
and multiple authentication service modules. The PAM
interface library is the layer implementing 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. PAM gives system administrators the flexibility of
choosing any authentication service available on the system
to perform authentication. This framework also allows new
authentication service modules to be plugged in and made
available without modifying the applications.
Refer to Solaris Security for Developers Guide for informa-
tion about providing authentication, account management,
session management, and password management through PAM
modules.
Interface Overview
The PAM library interface consists of six categories of
functions, the names for which all start with the prefix
pam.
The first category contains functions for establishing and
terminating an authentication activity, which are
pamstart(3PAM) and pamend(3PAM). The functions
pamsetdata(3PAM) and pamgetdata(3PAM) maintain module
specific data. The functions pamsetitem(3PAM) and
pamgetitem(3PAM) maintain state information.
pamstrerror(3PAM) is the function that returns error status
information.
The second category contains the functions that authenticate
an individual user and set the credentials of the user,
pamauthenticate(3PAM) and pamsetcred(3PAM).
The third category of PAM interfaces is account management.
The function pamacctmgmt(3PAM) checks for password aging
and access-hour restrictions.
SunOS 5.11 Last change: 22 Feb 2005 1
PAM Library Functions pam(3PAM)
Category four contains the functions that perform session
management after access to the system has been granted. See
pamopensession(3PAM) and pamclosesession(3PAM)
The fifth category consists of the function that changes
authentication tokens, pamchauthtok(3PAM). An authentica-
tion token is the object used to verify the identity of the
user. In UNIX, an authentication token is a user's password.
The sixth category of functions can be used to set values
for PAM environment variables. See pamputenv(3PAM),
pamgetenv(3PAM), and pamgetenvlist(3PAM).
The pam*() interfaces are implemented through the library
libpam. For each of the categories listed above, excluding
categories one and six, dynamically loadable shared modules
exist that provides the appropriate service layer func-
tionality upon demand. The functional entry points in the
service layer start with the pamsm prefix. The only
difference between the pamsm*() interfaces and their
corresponding pam interfaces is that all the pamsm*()
interfaces require extra parameters to pass service-specific
options to the shared modules. Refer to pamsm(3PAM) for
an overview of the PAM service module APIs.
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 a PAM authentication
handle to be used for subsequent calls to the library.
After initiating an authentication transaction, applications
can invoke pamauthenticate() to authenticate a particular
user, and pamacctmgmt() to perform system entry manage-
ment. For example, the application may want to determine if
the user's password has expired.
If the user has been successfully authenticated, the appli-
cation calls pamsetcred() to set any user credentials asso-
ciated with the authentication service. Within one authenti-
cation transaction (between pamstart() and pamend()), all
calls to the PAM interface should be made with the same
authentication handle returned by pamstart(). This is
necessary because certain service modules may store module-
specific data in a handle that is intended for use by other
SunOS 5.11 Last change: 22 Feb 2005 2
PAM Library Functions pam(3PAM)
modules. For example, during the call to pamauthenticate(),
service modules may store data in the handle that is
intended for use by pamsetcred().
To perform session management, applications call
pamopensession(). Specifically, the system may want to
store the total time for the session. The function
pamclosesession() closes the current session.
When necessary, applications can call pamgetitem() and
pamsetitem() to access and to update specific authentica-
tion information. Such information may include the current
username.
To terminate an authentication transaction, the application
simply calls pamend(), which frees previously allocated
space used to store authentication information.
Application-Authentication Service Interactive Interface
The authentication service in PAM does not communicate
directly with the user; instead it relies 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 a pamconv structure to
the authentication service when it initiates an authentica-
tion transaction, via a call to pamstart(). The service
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.
Stacking Multiple Schemes
The PAM architecture enables authentication by multiple
authentication services through stacking. System entry
applications, such as login(1), stack multiple service
modules to authenticate users with multiple authentication
services. The order in which authentication service modules
are stacked is specified in the configuration file,
pam.conf(4). A system administrator determines this order-
ing, and also determines whether the same password can be
used for all authentication services.
Administrative Interface
The authentication library, /usr/lib/libpam.so.1, implements
the framework interface. Various authentication services are
implemented by their own loadable modules whose paths are
specified through the pam.conf(4) file.
RETURN VALUES
SunOS 5.11 Last change: 22 Feb 2005 3
PAM Library Functions pam(3PAM)
The PAM functions may return one of the following generic
values, or one of the values defined in the specific man
pages:
PAMSUCES The function returned successfully.
PAMOPENER dlopen() failed when dynamically loading
a service module.
PAMSYMBOLER Symbol not found.
PAMSERVICER Error in service module.
PAMSYSTEMER System error.
PAMBUFER Memory buffer error.
PAMCONVER Conversation failure.
PAMPERMDENIED Permission denied.
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level MT-Safe with exceptions
SEE ALSO
login(1), pamauthenticate(3PAM), pamchauthtok(3PAM),
pamopensession(3PAM), pamsetitem(3PAM),
pamsetcred(3PAM), pamsm(3PAM), pamstart(3PAM),
pamstrerror(3PAM), pam.conf(4), attributes(5)
Solaris Security for Developers Guide
SunOS 5.11 Last change: 22 Feb 2005 4
PAM Library Functions pam(3PAM)
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: 22 Feb 2005 5
|
