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