PAM
Section: Linux-PAM Manual (3)
Updated: 04/01/2016
Index
Return to Main Contents
NAME
pam - Pluggable Authentication Modules Library
SYNOPSIS
#include <security/pam_appl.h>
#include <security/pam_modules.h>
#include <security/pam_ext.h>
DESCRIPTION
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.
Authentication
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's credentials.
Account Management
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 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).
Conversation
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.
RETURN VALUES
The following return codes are known by PAM:
PAM_ABORT
-
Critical error, immediate abort.
PAM_ACCT_EXPIRED
-
User account has expired.
PAM_AUTHINFO_UNAVAIL
-
Authentication service cannot retrieve authentication info.
PAM_AUTHTOK_DISABLE_AGING
-
Authentication token aging disabled.
PAM_AUTHTOK_ERR
-
Authentication token manipulation error.
PAM_AUTHTOK_EXPIRED
-
Authentication token expired.
PAM_AUTHTOK_LOCK_BUSY
-
Authentication token lock busy.
PAM_AUTHTOK_RECOVERY_ERR
-
Authentication information cannot be recovered.
PAM_AUTH_ERR
-
Authentication failure.
PAM_BUF_ERR
-
Memory buffer error.
PAM_CONV_ERR
-
Conversation failure.
PAM_CRED_ERR
-
Failure setting user credentials.
PAM_CRED_EXPIRED
-
User credentials expired.
PAM_CRED_INSUFFICIENT
-
Insufficient credentials to access authentication data.
PAM_CRED_UNAVAIL
-
Authentication service cannot retrieve user credentials.
PAM_IGNORE
-
The return value should be ignored by PAM dispatch.
PAM_MAXTRIES
-
Have exhausted maximum number of retries for service.
PAM_MODULE_UNKNOWN
-
Module is unknown.
PAM_NEW_AUTHTOK_REQD
-
Authentication token is no longer valid; new one required.
PAM_NO_MODULE_DATA
-
No module specific data is present.
PAM_OPEN_ERR
-
Failed to load module.
PAM_PERM_DENIED
-
Permission denied.
PAM_SERVICE_ERR
-
Error in service module.
PAM_SESSION_ERR
-
Cannot make/remove an entry for the specified session.
PAM_SUCCESS
-
Success.
PAM_SYMBOL_ERR
-
Symbol not found.
PAM_SYSTEM_ERR
-
System error.
PAM_TRY_AGAIN
-
Failed preliminary check by password service.
PAM_USER_UNKNOWN
-
User not known to the underlying authentication module.
SEE ALSO
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)
NOTES
The
libpam
interfaces are only thread-safe if each thread within the multithreaded application uses its own PAM handle.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Initialization and Cleanup
-
- Authentication
-
- Account Management
-
- Password Management
-
- Session Management
-
- Conversation
-
- Data Objects
-
- Environment and Error Management
-
- RETURN VALUES
-
- SEE ALSO
-
- NOTES
-
|
|
- Running on 
-
:
: 