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