.Dd September 12, 2014 .Dt PAM 3 .Os .Sh NAME .Nd Pluggable Authentication Modules Library .Sh LIBRARY .Lb libpam .Sh SYNOPSIS n security/pam_appl.h
$Id: pam.man 648 2013-03-05 17:54:27Z des $
.Sh DESCRIPTION The Pluggable Authentication Modules (PAM) library abstracts a number of common authentication-related operations and provides a framework for dynamically loaded modules that implement these operations in various ways. .Ss Terminology In PAM parlance, the application that uses PAM to authenticate a user is the server, and is identified for configuration purposes by a service name, which is often (but not necessarily) the program name.
p The user requesting authentication is called the applicant, while the user (usually, root) charged with verifying his identity and granting him the requested credentials is called the arbitrator.
p The sequence of operations the server goes through to authenticate a user and perform whatever task he requested is a PAM transaction; the context within which the server performs the requested task is called a session.
p The functionality embodied by PAM is divided into six primitives grouped into four facilities: authentication, account management, session management and password management. .Ss Conversation The PAM library expects the application to provide a conversation callback which it can use to communicate with the user. Some modules may use specialized conversation functions to communicate with special hardware such as cryptographic dongles or biometric devices. See .Xr pam_conv 3 for details. .Ss Initialization and Cleanup The .Fn pam_start function initializes the PAM library and returns a handle which must be provided in all subsequent function calls. The transaction state is contained entirely within the structure identified by this handle, so it is possible to conduct multiple transactions in parallel.
p The .Fn pam_end function releases all resources associated with the specified context, and can be called at any time to terminate a PAM transaction. .Ss Storage The .Fn pam_set_item and .Fn pam_get_item functions set and retrieve a number of predefined items, including the service name, the names of the requesting and target users, the conversation function, and prompts.
p The .Fn pam_set_data and .Fn pam_get_data functions manage named chunks of free-form data, generally used by modules to store state from one invocation to another. .Ss Authentication There are two authentication primitives: .Fn pam_authenticate and .Fn pam_setcred . The former authenticates the user, while the latter manages his credentials. .Ss Account Management The .Fn pam_acct_mgmt function enforces policies such as password expiry, account expiry, time-of-day restrictions, and so forth. .Ss Session Management The .Fn pam_open_session and .Fn pam_close_session functions handle session setup and teardown. .Ss Password Management The .Fn pam_chauthtok function allows the server to change the user's password, either at the user's request or because the password has expired. .Ss Miscellaneous The .Fn pam_putenv , .Fn pam_getenv and .Fn pam_getenvlist functions manage a private environment list in which modules can set environment variables they want the server to export during the session.
p The .Fn pam_strerror function returns a pointer to a string describing the specified PAM error code. .Sh RETURN VALUES The following return codes are defined by n security/pam_constants.h : l -tag -width 18n t Bq Er PAM_ABORT General failure. t Bq Er PAM_ACCT_EXPIRED User account has expired. t Bq Er PAM_AUTHINFO_UNAVAIL Authentication information is unavailable. t Bq Er PAM_AUTHTOK_DISABLE_AGING Authentication token aging disabled. t Bq Er PAM_AUTHTOK_ERR Authentication token failure. t Bq Er PAM_AUTHTOK_EXPIRED Password has expired. t Bq Er PAM_AUTHTOK_LOCK_BUSY Authentication token lock busy. t Bq Er PAM_AUTHTOK_RECOVERY_ERR Failed to recover old authentication token. t Bq Er PAM_AUTH_ERR Authentication error. t Bq Er PAM_BUF_ERR Memory buffer error. t Bq Er PAM_CONV_ERR Conversation failure. t Bq Er PAM_CRED_ERR Failed to set user credentials. t Bq Er PAM_CRED_EXPIRED User credentials have expired. t Bq Er PAM_CRED_INSUFFICIENT Insufficient credentials. t Bq Er PAM_CRED_UNAVAIL Failed to retrieve user credentials. t Bq Er PAM_DOMAIN_UNKNOWN Unknown authentication domain. t Bq Er PAM_IGNORE Ignore this module. t Bq Er PAM_MAXTRIES Maximum number of tries exceeded. t Bq Er PAM_MODULE_UNKNOWN Unknown module type. t Bq Er PAM_NEW_AUTHTOK_REQD New authentication token required. t Bq Er PAM_NO_MODULE_DATA Module data not found. t Bq Er PAM_OPEN_ERR Failed to load module. t Bq Er PAM_PERM_DENIED Permission denied. t Bq Er PAM_SERVICE_ERR Error in service module. t Bq Er PAM_SESSION_ERR Session failure. t Bq Er PAM_SUCCESS Success. t Bq Er PAM_SYMBOL_ERR Invalid symbol. t Bq Er PAM_SYSTEM_ERR System error. t Bq Er PAM_TRY_AGAIN Try again. t Bq Er PAM_USER_UNKNOWN Unknown user. .El .Sh SEE ALSO .Xr openpam 3 , .Xr pam_conv 3 .Sh STANDARDS .Rs .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" .%D "June 1997" .Re .Sh AUTHORS The OpenPAM library and this manual page were developed for the .Fx Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
q Dq CBOSS , as part of the DARPA CHATS research program.
p The OpenPAM library is maintained by .An Dag-Erling Sm\(/orgrav Aq des@des.no .