1.Sh DESCRIPTION 2The Pluggable Authentication Modules (PAM) library abstracts a number 3of common authentication-related operations and provides a framework 4for dynamically loaded modules that implement these operations in 5various ways. 6.Ss Terminology 7In PAM parlance, the application that uses PAM to authenticate a user 8is the server, and is identified for configuration purposes by a 9service name, which is often (but not necessarily) the program name. 10.Pp 11The user requesting authentication is called the applicant, while the 12user (usually, root) charged with verifying his identity and granting 13him the requested credentials is called the arbitrator. 14.Pp 15The sequence of operations the server goes through to authenticate a 16user and perform whatever task he requested is a PAM transaction; the 17context within which the server performs the requested task is called 18a session. 19.Pp 20The functionality embodied by PAM is divided into six primitives 21grouped into four facilities: authentication, account management, 22session management and password management. 23.Ss Conversation 24The PAM library expects the application to provide a conversation 25callback which it can use to communicate with the user. 26Some modules may use specialized conversation functions to communicate 27with special hardware such as cryptographic dongles or biometric 28devices. 29See 30.Xr pam_conv 3 31for details. 32.Ss Initialization and Cleanup 33The 34.Fn pam_start 35function initializes the PAM library and returns a handle which must 36be provided in all subsequent function calls. 37The transaction state is contained entirely within the structure 38identified by this handle, so it is possible to conduct multiple 39transactions in parallel. 40.Pp 41The 42.Fn pam_end 43function releases all resources associated with the specified context, 44and can be called at any time to terminate a PAM transaction. 45.Ss Storage 46The 47.Fn pam_set_item 48and 49.Fn pam_get_item 50functions set and retrieve a number of predefined items, including the 51service name, the names of the requesting and target users, the 52conversation function, and prompts. 53.Pp 54The 55.Fn pam_set_data 56and 57.Fn pam_get_data 58functions manage named chunks of free-form data, generally used by 59modules to store state from one invocation to another. 60.Ss Authentication 61There are two authentication primitives: 62.Fn pam_authenticate 63and 64.Fn pam_setcred . 65The former authenticates the user, while the latter manages his 66credentials. 67.Ss Account Management 68The 69.Fn pam_acct_mgmt 70function enforces policies such as password expiry, account expiry, 71time-of-day restrictions, and so forth. 72.Ss Session Management 73The 74.Fn pam_open_session 75and 76.Fn pam_close_session 77functions handle session setup and teardown. 78.Ss Password Management 79The 80.Fn pam_chauthtok 81function allows the server to change the user's password, either at 82the user's request or because the password has expired. 83.Ss Miscellaneous 84The 85.Fn pam_putenv , 86.Fn pam_getenv 87and 88.Fn pam_getenvlist 89functions manage a private environment list in which modules can set 90environment variables they want the server to export during the 91session. 92.Pp 93The 94.Fn pam_strerror 95function returns a pointer to a string describing the specified PAM 96error code. 97