contrib/openpam/doc/man/pam.3

   1 .\"-
   2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
   3 .\" Copyright (c) 2004-2011 Dag-Erling Smørgrav
   4 .\" All rights reserved.
   5 .\"
   6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   7 .\" Network Associates Laboratories, the Security Research Division of
   8 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
   9 .\" ("CBOSS"), as part of the DARPA CHATS research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. The name of the author may not be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\" $Id$
  36 .\"
  37 .Dd December 18, 2011
  38 .Dt PAM 3
  39 .Os
  40 .Sh NAME
  41 .Nm pam_acct_mgmt ,
  42 .Nm pam_authenticate ,
  43 .Nm pam_chauthtok ,
  44 .Nm pam_close_session ,
  45 .Nm pam_end ,
  46 .Nm pam_get_data ,
  47 .Nm pam_get_item ,
  48 .Nm pam_get_user ,
  49 .Nm pam_getenv ,
  50 .Nm pam_getenvlist ,
  51 .Nm pam_open_session ,
  52 .Nm pam_putenv ,
  53 .Nm pam_set_data ,
  54 .Nm pam_set_item ,
  55 .Nm pam_setcred ,
  56 .Nm pam_start ,
  57 .Nm pam_strerror
  58 .Nd Pluggable Authentication Modules Library
  59 .Sh LIBRARY
  60 .Lb libpam
  61 .Sh SYNOPSIS
  62 .In security/pam_appl.h
  63 .Ft "int"
  64 .Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
  65 .Ft "int"
  66 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
  67 .Ft "int"
  68 .Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
  69 .Ft "int"
  70 .Fn pam_close_session "pam_handle_t *pamh" "int flags"
  71 .Ft "int"
  72 .Fn pam_end "pam_handle_t *pamh" "int status"
  73 .Ft "int"
  74 .Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data"
  75 .Ft "int"
  76 .Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item"
  77 .Ft "int"
  78 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
  79 .Ft "const char *"
  80 .Fn pam_getenv "pam_handle_t *pamh" "const char *name"
  81 .Ft "char **"
  82 .Fn pam_getenvlist "pam_handle_t *pamh"
  83 .Ft "int"
  84 .Fn pam_open_session "pam_handle_t *pamh" "int flags"
  85 .Ft "int"
  86 .Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue"
  87 .Ft "int"
  88 .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)"
  89 .Ft "int"
  90 .Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item"
  91 .Ft "int"
  92 .Fn pam_setcred "pam_handle_t *pamh" "int flags"
  93 .Ft "int"
  94 .Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh"
  95 .Ft "const char *"
  96 .Fn pam_strerror "const pam_handle_t *pamh" "int error_number"
  97 .\"
  98 .\" $Id: pam.man 320 2006-02-16 20:33:19Z des $
  99 .\"
 100 .Sh DESCRIPTION
 101 The Pluggable Authentication Modules (PAM) library abstracts a number
 102 of common authentication-related operations and provides a framework
 103 for dynamically loaded modules that implement these operations in
 104 various ways.
 105 .Ss Terminology
 106 In PAM parlance, the application that uses PAM to authenticate a user
 107 is the server, and is identified for configuration purposes by a
 108 service name, which is often (but not necessarily) the program name.
 109 .Pp
 110 The user requesting authentication is called the applicant, while the
 111 user (usually, root) charged with verifying his identity and granting
 112 him the requested credentials is called the arbitrator.
 113 .Pp
 114 The sequence of operations the server goes through to authenticate a
 115 user and perform whatever task he requested is a PAM transaction; the
 116 context within which the server performs the requested task is called
 117 a session.
 118 .Pp
 119 The functionality embodied by PAM is divided into six primitives
 120 grouped into four facilities: authentication, account management,
 121 session management and password management.
 122 .Ss Conversation
 123 The PAM library expects the application to provide a conversation
 124 callback which it can use to communicate with the user.
 125 Some modules may use specialized conversation functions to communicate
 126 with special hardware such as cryptographic dongles or biometric
 127 devices.
 128 See
 129 .Xr pam_conv 3
 130 for details.
 131 .Ss Initialization and Cleanup
 132 The
 133 .Fn pam_start
 134 function initializes the PAM library and returns a handle which must
 135 be provided in all subsequent function calls.
 136 The transaction state is contained entirely within the structure
 137 identified by this handle, so it is possible to conduct multiple
 138 transactions in parallel.
 139 .Pp
 140 The
 141 .Fn pam_end
 142 function releases all resources associated with the specified context,
 143 and can be called at any time to terminate a PAM transaction.
 144 .Ss Storage
 145 The
 146 .Fn pam_set_item
 147 and
 148 .Fn pam_get_item
 149 functions set and retrieve a number of predefined items, including the
 150 service name, the names of the requesting and target users, the
 151 conversation function, and prompts.
 152 .Pp
 153 The
 154 .Fn pam_set_data
 155 and
 156 .Fn pam_get_data
 157 functions manage named chunks of free-form data, generally used by
 158 modules to store state from one invocation to another.
 159 .Ss Authentication
 160 There are two authentication primitives:
 161 .Fn pam_authenticate
 162 and
 163 .Fn pam_setcred .
 164 The former authenticates the user, while the latter manages his
 165 credentials.
 166 .Ss Account Management
 167 The
 168 .Fn pam_acct_mgmt
 169 function enforces policies such as password expiry, account expiry,
 170 time-of-day restrictions, and so forth.
 171 .Ss Session Management
 172 The
 173 .Fn pam_open_session
 174 and
 175 .Fn pam_close_session
 176 functions handle session setup and teardown.
 177 .Ss Password Management
 178 The
 179 .Fn pam_chauthtok
 180 function allows the server to change the user's password, either at
 181 the user's request or because the password has expired.
 182 .Ss Miscellaneous
 183 The
 184 .Fn pam_putenv ,
 185 .Fn pam_getenv
 186 and
 187 .Fn pam_getenvlist
 188 functions manage a private environment list in which modules can set
 189 environment variables they want the server to export during the
 190 session.
 191 .Pp
 192 The
 193 .Fn pam_strerror
 194 function returns a pointer to a string describing the specified PAM
 195 error code.
 196 .Sh RETURN VALUES
 197 The following return codes are defined by
 198 .In security/pam_constants.h :
 199 .Bl -tag -width 18n
 200 .It Bq Er PAM_ABORT
 201 General failure.
 202 .It Bq Er PAM_ACCT_EXPIRED
 203 User account has expired.
 204 .It Bq Er PAM_AUTHINFO_UNAVAIL
 205 Authentication information is unavailable.
 206 .It Bq Er PAM_AUTHTOK_DISABLE_AGING
 207 Authentication token aging disabled.
 208 .It Bq Er PAM_AUTHTOK_ERR
 209 Authentication token failure.
 210 .It Bq Er PAM_AUTHTOK_EXPIRED
 211 Password has expired.
 212 .It Bq Er PAM_AUTHTOK_LOCK_BUSY
 213 Authentication token lock busy.
 214 .It Bq Er PAM_AUTHTOK_RECOVERY_ERR
 215 Failed to recover old authentication token.
 216 .It Bq Er PAM_AUTH_ERR
 217 Authentication error.
 218 .It Bq Er PAM_BUF_ERR
 219 Memory buffer error.
 220 .It Bq Er PAM_CONV_ERR
 221 Conversation failure.
 222 .It Bq Er PAM_CRED_ERR
 223 Failed to set user credentials.
 224 .It Bq Er PAM_CRED_EXPIRED
 225 User credentials have expired.
 226 .It Bq Er PAM_CRED_INSUFFICIENT
 227 Insufficient credentials.
 228 .It Bq Er PAM_CRED_UNAVAIL
 229 Failed to retrieve user credentials.
 230 .It Bq Er PAM_DOMAIN_UNKNOWN
 231 Unknown authentication domain.
 232 .It Bq Er PAM_IGNORE
 233 Ignore this module.
 234 .It Bq Er PAM_MAXTRIES
 235 Maximum number of tries exceeded.
 236 .It Bq Er PAM_MODULE_UNKNOWN
 237 Unknown module type.
 238 .It Bq Er PAM_NEW_AUTHTOK_REQD
 239 New authentication token required.
 240 .It Bq Er PAM_NO_MODULE_DATA
 241 Module data not found.
 242 .It Bq Er PAM_OPEN_ERR
 243 Failed to load module.
 244 .It Bq Er PAM_PERM_DENIED
 245 Permission denied.
 246 .It Bq Er PAM_SERVICE_ERR
 247 Error in service module.
 248 .It Bq Er PAM_SESSION_ERR
 249 Session failure.
 250 .It Bq Er PAM_SUCCESS
 251 Success.
 252 .It Bq Er PAM_SYMBOL_ERR
 253 Invalid symbol.
 254 .It Bq Er PAM_SYSTEM_ERR
 255 System error.
 256 .It Bq Er PAM_TRY_AGAIN
 257 Try again.
 258 .It Bq Er PAM_USER_UNKNOWN
 259 Unknown user.
 260 .El
 261 .Sh SEE ALSO
 262 .Xr openpam 3 ,
 263 .Xr pam_acct_mgmt 3 ,
 264 .Xr pam_authenticate 3 ,
 265 .Xr pam_chauthtok 3 ,
 266 .Xr pam_close_session 3 ,
 267 .Xr pam_conv 3 ,
 268 .Xr pam_end 3 ,
 269 .Xr pam_get_data 3 ,
 270 .Xr pam_getenv 3 ,
 271 .Xr pam_getenvlist 3 ,
 272 .Xr pam_get_item 3 ,
 273 .Xr pam_get_user 3 ,
 274 .Xr pam_open_session 3 ,
 275 .Xr pam_putenv 3 ,
 276 .Xr pam_setcred 3 ,
 277 .Xr pam_set_data 3 ,
 278 .Xr pam_set_item 3 ,
 279 .Xr pam_start 3 ,
 280 .Xr pam_strerror 3
 281 .Sh STANDARDS
 282 .Rs
 283 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
 284 .%D "June 1997"
 285 .Re
 286 .Sh AUTHORS
 287 The OpenPAM library and this manual page were developed for the
 288 .Fx
 289 Project by ThinkSec AS and Network Associates Laboratories, the
 290 Security Research Division of Network Associates, Inc.\& under
 291 DARPA/SPAWAR contract N66001-01-C-8035
 292 .Pq Dq CBOSS ,
 293 as part of the DARPA CHATS research program.