contrib/openpam/doc/man/pam.3

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