contrib/openpam/doc/man/pam.3

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