pam - Pluggable Authentication Modules Library
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 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
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
The pam_setcred(3) function manages the user's
The pam_acct_mgmt(3) function is used to determine if the user'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
The pam_chauthtok(3) function is used to change the authentication token
for a given user on request or because the token has expired.
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.
The following return codes are known by PAM:
Critical error, immediate abort.
User account has expired.
Authentication service cannot retrieve authentication
Authentication token aging disabled.
Authentication token manipulation error.
Authentication token expired.
Authentication token lock busy.
Authentication information cannot be recovered.
Memory buffer error.
Failure setting user credentials.
User credentials expired.
Insufficient credentials to access authentication
Authentication service cannot retrieve user
The return value should be ignored by PAM dispatch.
Have exhausted maximum number of retries for
Module is unknown.
Authentication token is no longer valid; new one
No module specific data is present.
Failed to load module.
Error in service module.
Cannot make/remove an entry for the specified
Symbol not found.
Failed preliminary check by password service.
User not known to the underlying authentication
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.