doc/man/pam.3

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