HP-UX Reference (11i v1 05/09) - 3 Library Functions N-Z (vol 7)

p
pam(3) pam(3)
NAME
PAM - Pluggable Authentication Module
SYNOPSIS
#include <security/pam_appl.h>
cc
[ flag ... ]file ...
-lpam [ library ... ]
DESCRIPTION
PAM gives system administrators the flexibility of choosing any authentication service available on the sys-
tem to perform authentication. The framework also allows new authentication 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 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 authentication.
Interface Overview
The PAM library interface consists of functions which can be grouped into five categories. The names for
all the authentication library functions start with
pam_.
The first category contains functions for establishing and terminating an authentication activity
(pam_start(3) and pam_end(3)), functions to maintain module specific data (pam_[sg]et_data(3)), functions
to maintain state information (pam_[sg]et_item(3)), and a function to return error status information
(pam_strerror(3)).
The second category contains functions to authenticate an individual user (pam_authenticate(3)) and to set
the credentials of the user (pam_setcred(3)).
The third category contains functions to do account management (pam_acct_mgmt(3)). This includes
checking for password aging and access-hour restrictions.
The fourth category contains functions to perform session management (pam_open_session(3) and
pam_close_session(3)) after access to the system has been granted.
The fifth category consists of functions to change authentication tokens pam_chauthtok(3). 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, even when using a smart card, because the PAM Framework retrieves the password from the
smart card.
All the
pam_*() interfaces are implemented through the library libpam. For each of the categories
listed above, excluding the first category pam_start(), pam_end(), pam_[sg]et_data()
,
pam_[sg]et_item()
, and pam_strerror()) there exists a dynamically loadable shared module
that provides the appropriate service layer functionality upon demand. The functional entry points in the
service layer start with the
pam_sm_ prefix. The only difference between the pam_sm_*()
interfaces
and their corresponding
pam_ interfaces is that all the
pam_sm_*() interfaces require extra parameters
to pass service specific options to the shared modules. Please refer to pam_sm(3) for an overview of the
PAM service module APIs.
Stateful Interface
A sequence of calls sharing a common set of state information is referred to as an authentication transac-
tion. An authentication transaction begins with a call to
pam_start() . pam_start() allocates space,
performs various initialization activities, and assigns a PAM authentication handle to be used for subse-
quent calls to the library.
After initiating an authentication transaction, applications can invoke pam_authenticate()
to
authenticate a particular user, and
pam_acct_mgmt() to perform system entry management (the appli-
cation may want to determine if the user’s password has expired).
If the user has been successfully authenticated, applications call pam_setcred()
to set any user creden-
tials associated with the authentication service. Within one authentication transaction (between
pam_start() and pam_end() ), all calls to the PAM interface should be made with the same authenti-
cation handle returned by pam_start() . This is necessary because certain service modules may store
module-specific data in the handle that is intended for use by other modules. For example, during the call
to pam_authenticate(), service modules may store data in the handle that is intended for use by
pam_setcred().
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−623