pam(3)pam(3)NAME
PAM - Pluggable Authentication Module
SYNOPSIS
[flag]... file..." [library]...
DESCRIPTION
PAM gives system administrators the flexibility of choosing any authen‐
tication 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, consists of an interface library and multiple
authentication service modules. The PAM interface library is the layer
implementing the Application Programming Interface (API). The authen‐
tication service modules are a set of dynamically loadable objects
invoked by the PAM API to provide a particular type of user authentica‐
tion.
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
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 sys‐
tem has been granted.
The fifth category consists of functions to change authentication
tokens pam_chauthtok(3). An authentication 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 Frame‐
work retrieves the password from the smart card.
All the interfaces are implemented through the library For each of the
categories listed above, excluding the first category and there exists
a dynamically loadable shared module that provides the appropriate ser‐
vice layer functionality upon demand. The functional entry points in
the service layer start with the prefix. The only difference between
the interfaces and their corresponding interfaces is that all the
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 transaction. An authentication trans‐
action begins with a call to allocates space, performs various initial‐
ization activities, and assigns a PAM authentication handle to be used
for subsequent calls to the library.
After initiating an authentication transaction, applications can invoke
to authenticate a particular user, and to perform system entry manage‐
ment (the application may want to determine if the user's password has
expired).
If the user has been successfully authenticated, applications call to
set any user credentials associated with the authentication service.
Within one authentication transaction (between and all calls to the PAM
interface should be made with the same authentication handle returned
by 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 service modules may store data in the
handle that is intended for use by
To perform session management, applications call For example, the sys‐
tem may want to store the total time for the session. The function
closes the current session.
When necessary, applications can call and to access and update specific
authentication information. Such information may include the current
username.
To terminate an authentication transaction, the application simply
calls which frees previously allocated space used to store authentica‐
tion 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, along
with any associated application data pointers, through a structure to
the authentication service when it initiates an authentication transac‐
tion (via a call to The service will then use the function, to prompt
the user for data, output error messages, and display text information.
Refer to pam_start(3) 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 ordering, and also
determines whether the same password can be used for all authentication
services.
Administrative Interface
Various authentication services are implemented by their own loadable
modules whose paths are specified through the pam.conf(4) file.
User configuration
The system administrator can determine a policy by user. These are
specified in the configuration files: pam.conf(4), pam_user.conf(4).
APPLICATION USAGE
All the interfaces implemented in the PAM framework, are thread-safe.
A cancellation point may occur while a thread is executing any of these
interfaces. They are not cancel-safe, async-cancel-safe, nor async-
signal-safe. However, system administrators should be aware that the
and interfaces invoke the corresponding interfaces implemented in the
dynamically loadable modules specified in the configuration file,
pam.conf(4). Therefore, the thread-safety of these interfaces depends
on the implementation of the service module. Refer to module specific
man pages such as pam_unix(5) for this information.
RETURN VALUE
The PAM functions may return one of the following generic values, or
one of the values defined in the specific man pages:
Successful function return.
Failure in dynamically loading a service module.
Symbol not found.
Error in service module.
System error.
Memory buffer error.
Conversation failure.
Permission denied.
WARNINGS
Please note that all the PAM APIs and the data structures are subject
to change without notice.
SEE ALSOpam_authenticate(3), pam_open_session(3), pam_chauthtok(3),
pam_set_item(3), pam_setcred(3), pam_sm(3), pam_start(3), pam_str‐
error(3), pam.conf(4), pam_user.conf(4).
pam(3)