Section (3) pam

Linux manual pages Section 3  


pam — Pluggable Authentication Modules Library


#include <security/pam_appl.h>
#include <security/pam_modules.h>
#include <security/pam_ext.h>


PAM is a system of libraries that handle the authentication tasks of applications (services) on the system. The library provides a stable general interface (Application Programming Interface - API) that privilege granting programs (such as login(1) and su(1)) defer to to perform standard authentication tasks.

Initialization and Cleanup

The pam_start(3) function creates the PAM context and initiates the PAM transaction. It is the first of the PAM functions that needs to be called by an application. The transaction state is contained entirely within the structure identified by this handle, so it is possible to have multiple transactions in parallel. But it is not possible to use the same handle for different transactions, a new one is needed for every new context.

The pam_end(3) function terminates the PAM transaction and is the last function an application should call in the PAM context. Upon return the handle pamh is no longer valid and all memory associated with it will be invalid. It can be called at any time to terminate a PAM transaction.


The pam_authenticate(3) function is used to authenticate the user. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print.

The pam_setcred(3) function manages the user_zsingle_quotesz_s credentials.

Account Management

The pam_acct_mgmt(3) function is used to determine if the user_zsingle_quotesz_s account is valid. It checks for authentication token and account expiration and verifies access restrictions. It is typically called after the user has been authenticated.

Password Management

The pam_chauthtok(3) function is used to change the authentication token for a given user on request or because the token has expired.

Session Management

The pam_open_session(3) function sets up a user session for a previously successful authenticated user. The session should later be terminated with a call to pam_close_session(3).


The PAM library uses an application-defined callback to allow a direct communication between a loaded module and the application. This callback is specified by the struct pam_conv passed to pam_start(3) at the start of the transaction. See pam_conv(3) for details.

Data Objects

The pam_set_item(3) and pam_get_item(3) functions allows applications and PAM service modules to set and retrieve PAM informations.

The pam_get_user(3) function is the preferred method to obtain the username.

The pam_set_data(3) and pam_get_data(3) functions allows PAM service modules to set and retrieve free-form data from one invocation to another.

Environment and Error Management

The pam_putenv(3), pam_getenv(3) and pam_getenvlist(3) functions are for maintaining a set of private environment variables.

The pam_strerror(3) function returns a pointer to a string describing the given PAM error code.


The following return codes are known by PAM:


Critical error, immediate abort.


User account has expired.


Authentication service cannot retrieve authentication info.


Authentication token aging disabled.


Authentication token manipulation error.


Authentication token expired.


Authentication token lock busy.


Authentication information cannot be recovered.


Authentication failure.


Memory buffer error.


Conversation failure.


Failure setting user credentials.


User credentials expired.


Insufficient credentials to access authentication data.


Authentication service cannot retrieve user credentials.


The return value should be ignored by PAM dispatch.


Have exhausted maximum number of retries for service.


Module is unknown.


Authentication token is no longer valid; new one required.


No module specific data is present.


Failed to load module.


Permission denied.


Error in service module.


Cannot make/remove an entry for the specified session.




Symbol not found.


System error.


Failed preliminary check by password service.


User not known to the underlying authentication module.


pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_close_session(3), pam_conv(3), pam_end(3), pam_get_data(3), pam_getenv(3), pam_getenvlist(3), pam_get_item(3), pam_get_user(3), pam_open_session(3), pam_putenv(3), pam_set_data(3), pam_set_item(3), pam_setcred(3), pam_start(3), pam_strerror(3)


The libpam interfaces are only thread-safe if each thread within the multithreaded application uses its own PAM handle.

See Linux-PAM copyright notice for more information.

Section (8) pam

Linux manual pages Section 8  


PAM, pam — Pluggable Authentication Modules for Linux


This manual is intended to offer a quick introduction to Linux-PAM. For more information the reader is directed to the Linux-PAM system administrators_zsingle_quotesz_ guide.

Linux-PAM is a system of libraries that handle the authentication tasks of applications (services) on the system. The library provides a stable general interface (Application Programming Interface - API) that privilege granting programs (such as login(1) and su(1)) defer to to perform standard authentication tasks.

The principal feature of the PAM approach is that the nature of the authentication is dynamically configurable. In other words, the system administrator is free to choose how individual service-providing applications will authenticate users. This dynamic configuration is set by the contents of the single Linux-PAM configuration file /etc/pam.conf. Alternatively, the configuration can be set by individual configuration files located in the /etc/pam.d/ directory. The presence of this directory will cause Linux-PAM to ignore /etc/pam.conf.

Vendor-supplied PAM configuration files might be installed in the system directory /usr/lib/pam.d/ instead of the machine configuration directory /etc/pam.d/. If no machine configuration file is found, the vendor-supplied file is used. All files in /etc/pam.d/ override files with the same name in /usr/lib/pam.d/.

From the point of view of the system administrator, for whom this manual is provided, it is not of primary importance to understand the internal behavior of the Linux-PAM library. The important point to recognize is that the configuration file(s) define the connection between applications (services) and the pluggable authentication modules (PAMs) that perform the actual authentication tasks.

Linux-PAM separates the tasks of authentication into four independent management groups: account management; authentication management; password management; and session management. (We highlight the abbreviations used for these groups in the configuration file.)

Simply put, these groups take care of different aspects of a typical user_zsingle_quotesz_s request for a restricted service:

account - provide account verification types of service: has the user_zsingle_quotesz_s password expired?; is this user permitted access to the requested service?

authentication - authenticate a user and set up user credentials. Typically this is via some challenge-response request that the user must satisfy: if you are who you claim to be please enter your password. Not all authentications are of this type, there exist hardware based authentication schemes (such as the use of smart-cards and biometric devices), with suitable modules, these may be substituted seamlessly for more standard approaches to authentication - such is the flexibility of Linux-PAM.

password - this group_zsingle_quotesz_s responsibility is the task of updating authentication mechanisms. Typically, such services are strongly coupled to those of the auth group. Some authentication mechanisms lend themselves well to being updated with such a function. Standard UN*X password-based access is the obvious example: please enter a replacement password.

session - this group of tasks cover things that should be done prior to a service being given and after it is withdrawn. Such tasks include the maintenance of audit trails and the mounting of the user_zsingle_quotesz_s home directory. The session management group is important as it provides both an opening and closing hook for modules to affect the services available to a user.



the configuration file


the Linux-PAM configuration directory. Generally, if this directory is present, the /etc/pam.conf file is ignored.


the Linux-PAM vendor configuration directory. Files in /etc/pam.d override files with the same name in this directory.


Typically errors generated by the Linux-PAM system of libraries, will be written to syslog(3).


DCE-RFC 86.0, October 1995. Contains additional features, but remains backwardly compatible with this RFC.


pam(3), pam_authenticate(3), pam_sm_setcred(3), pam_strerror(3), PAM(8)

See Linux-PAM copyright notice for more information.