pam(3PAM)

Name

Synopsis

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 authentication. 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.

The fifth category consists of the function that changes authentication tokens, pam_chauthtok(3PAM). An authentication token is the object used
to verify the identity of the user. In UNIX, an authentication token is a user's password.

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 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. Refer to pam_sm(3PAM) for an overview of the PAM service
module APIs.

The pam_eval(3PAM) function can be used by the functions in categories two through five listed above to cause PAM to evaluate a supplied PAM configuration
file for the current service.

Stateful Interface

A sequence of calls sharing a common set of state information is referred to as an authentication transaction. 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. For example, the application may want to determine if the user's password
has expired.

If the user has been successfully authenticated, the application calls 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 authentication handle returned by pam_start(). This is necessary because certain service modules may store module-specific data in a 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().

To perform session management, applications call pam_open_session(). Specifically, the system may want to store the total time for the session. The function pam_close_session() closes the current session.

When necessary, applications can call pam_get_item() and pam_set_item() to access and to update specific authentication information. Such information may include the current username.

To terminate an authentication transaction, the application simply calls pam_end(), 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 pam_conv structure to the authentication service when it initiates an authentication transaction, via a call to pam_start(). The service will then use the function, conv(), to prompt the user for data, output
error messages, and display text information. Refer to pam_start(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(5) or the per-service files in /etc/pam.d/. A system administrator determines this ordering, 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(5) file or the per-service files in /etc/pam.d/.

Return Values

The PAM functions may return one of the following generic values, or one of the values defined in the specific man pages: