1.\" Generated by gendoc.pl 2.Dd September 12, 2014 3.Dt PAM 3 4.Os 5.Sh NAME 6.Nd Pluggable Authentication Modules Library 7.Sh LIBRARY 8.Lb libpam 9.Sh SYNOPSIS 10.In security/pam_appl.h 11.\" 12.\" $Id: pam.man 648 2013-03-05 17:54:27Z des $ 13.\" 14.Sh DESCRIPTION 15The Pluggable Authentication Modules (PAM) library abstracts a number 16of common authentication-related operations and provides a framework 17for dynamically loaded modules that implement these operations in 18various ways. 19.Ss Terminology 20In PAM parlance, the application that uses PAM to authenticate a user 21is the server, and is identified for configuration purposes by a 22service name, which is often (but not necessarily) the program name. 23.Pp 24The user requesting authentication is called the applicant, while the 25user (usually, root) charged with verifying his identity and granting 26him the requested credentials is called the arbitrator. 27.Pp 28The sequence of operations the server goes through to authenticate a 29user and perform whatever task he requested is a PAM transaction; the 30context within which the server performs the requested task is called 31a session. 32.Pp 33The functionality embodied by PAM is divided into six primitives 34grouped into four facilities: authentication, account management, 35session management and password management. 36.Ss Conversation 37The PAM library expects the application to provide a conversation 38callback which it can use to communicate with the user. 39Some modules may use specialized conversation functions to communicate 40with special hardware such as cryptographic dongles or biometric 41devices. 42See 43.Xr pam_conv 3 44for details. 45.Ss Initialization and Cleanup 46The 47.Fn pam_start 48function initializes the PAM library and returns a handle which must 49be provided in all subsequent function calls. 50The transaction state is contained entirely within the structure 51identified by this handle, so it is possible to conduct multiple 52transactions in parallel. 53.Pp 54The 55.Fn pam_end 56function releases all resources associated with the specified context, 57and can be called at any time to terminate a PAM transaction. 58.Ss Storage 59The 60.Fn pam_set_item 61and 62.Fn pam_get_item 63functions set and retrieve a number of predefined items, including the 64service name, the names of the requesting and target users, the 65conversation function, and prompts. 66.Pp 67The 68.Fn pam_set_data 69and 70.Fn pam_get_data 71functions manage named chunks of free-form data, generally used by 72modules to store state from one invocation to another. 73.Ss Authentication 74There are two authentication primitives: 75.Fn pam_authenticate 76and 77.Fn pam_setcred . 78The former authenticates the user, while the latter manages his 79credentials. 80.Ss Account Management 81The 82.Fn pam_acct_mgmt 83function enforces policies such as password expiry, account expiry, 84time-of-day restrictions, and so forth. 85.Ss Session Management 86The 87.Fn pam_open_session 88and 89.Fn pam_close_session 90functions handle session setup and teardown. 91.Ss Password Management 92The 93.Fn pam_chauthtok 94function allows the server to change the user's password, either at 95the user's request or because the password has expired. 96.Ss Miscellaneous 97The 98.Fn pam_putenv , 99.Fn pam_getenv 100and 101.Fn pam_getenvlist 102functions manage a private environment list in which modules can set 103environment variables they want the server to export during the 104session. 105.Pp 106The 107.Fn pam_strerror 108function returns a pointer to a string describing the specified PAM 109error code. 110.Sh RETURN VALUES 111The following return codes are defined by 112.In security/pam_constants.h : 113.Bl -tag -width 18n 114.It Bq Er PAM_ABORT 115General failure. 116.It Bq Er PAM_ACCT_EXPIRED 117User account has expired. 118.It Bq Er PAM_AUTHINFO_UNAVAIL 119Authentication information is unavailable. 120.It Bq Er PAM_AUTHTOK_DISABLE_AGING 121Authentication token aging disabled. 122.It Bq Er PAM_AUTHTOK_ERR 123Authentication token failure. 124.It Bq Er PAM_AUTHTOK_EXPIRED 125Password has expired. 126.It Bq Er PAM_AUTHTOK_LOCK_BUSY 127Authentication token lock busy. 128.It Bq Er PAM_AUTHTOK_RECOVERY_ERR 129Failed to recover old authentication token. 130.It Bq Er PAM_AUTH_ERR 131Authentication error. 132.It Bq Er PAM_BUF_ERR 133Memory buffer error. 134.It Bq Er PAM_CONV_ERR 135Conversation failure. 136.It Bq Er PAM_CRED_ERR 137Failed to set user credentials. 138.It Bq Er PAM_CRED_EXPIRED 139User credentials have expired. 140.It Bq Er PAM_CRED_INSUFFICIENT 141Insufficient credentials. 142.It Bq Er PAM_CRED_UNAVAIL 143Failed to retrieve user credentials. 144.It Bq Er PAM_DOMAIN_UNKNOWN 145Unknown authentication domain. 146.It Bq Er PAM_IGNORE 147Ignore this module. 148.It Bq Er PAM_MAXTRIES 149Maximum number of tries exceeded. 150.It Bq Er PAM_MODULE_UNKNOWN 151Unknown module type. 152.It Bq Er PAM_NEW_AUTHTOK_REQD 153New authentication token required. 154.It Bq Er PAM_NO_MODULE_DATA 155Module data not found. 156.It Bq Er PAM_OPEN_ERR 157Failed to load module. 158.It Bq Er PAM_PERM_DENIED 159Permission denied. 160.It Bq Er PAM_SERVICE_ERR 161Error in service module. 162.It Bq Er PAM_SESSION_ERR 163Session failure. 164.It Bq Er PAM_SUCCESS 165Success. 166.It Bq Er PAM_SYMBOL_ERR 167Invalid symbol. 168.It Bq Er PAM_SYSTEM_ERR 169System error. 170.It Bq Er PAM_TRY_AGAIN 171Try again. 172.It Bq Er PAM_USER_UNKNOWN 173Unknown user. 174.El 175.Sh SEE ALSO 176.Xr openpam 3 , 177.Xr pam_conv 3 178.Sh STANDARDS 179.Rs 180.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" 181.%D "June 1997" 182.Re 183.Sh AUTHORS 184The OpenPAM library and this manual page were developed for the 185.Fx 186Project by ThinkSec AS and Network Associates Laboratories, the 187Security Research Division of Network Associates, Inc.\& under 188DARPA/SPAWAR contract N66001-01-C-8035 189.Pq Dq CBOSS , 190as part of the DARPA CHATS research program. 191.Pp 192The OpenPAM library is maintained by 193.An Dag-Erling Sm\(/orgrav Aq des@des.no . 194