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