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