pam.3 (2010 09)

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
system 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_get_data (3) and
pam_set_data (3)), functions to maintain state information (pam_get_item (3) and pam_set_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 authenti-
cation 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 parame-
ters 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
subsequent 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
application 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
credentials 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 3: September 2010 − 1 − Hewlett-Packard Company 1