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