granicus.if.org Git - linux-pam/blob - doc/man/pam.3

   1 .\"     Title: pam
   2 .\"    Author:
   3 .\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
   4 .\"      Date: 06/19/2006
   5 .\"    Manual: Linux\-PAM Manual
   6 .\"    Source: Linux\-PAM Manual
   7 .\"
   8 .TH "PAM" "3" "06/19/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 pam \- Pluggable Authentication Modules Library
  15 .SH "SYNOPSIS"
  16 .sp
  17 .ft B
  18 .nf
  19 #include <security/pam_appl.h>
  20 .fi
  21 .ft
  22 .sp
  23 .ft B
  24 .nf
  25 #include <security/pam_modules.h>
  26 .fi
  27 .ft
  28 .sp
  29 .ft B
  30 .nf
  31 #include <security/pam_ext.h>
  32 .fi
  33 .ft
  34 .SH "DESCRIPTION"
  35 .PP
  36
  37 \fBPAM\fR
  38 is a system of libraries that handle the authentication tasks of applications (services) on the system. The library provides a stable general interface (Application Programming Interface \- API) that privilege granting programs (such as
  39 \fBlogin\fR(1)
  40 and
  41 \fBsu\fR(1)) defer to to perform standard authentication tasks.
  42 .SS "Initialization and Cleanup"
  43 .PP
  44 The
  45 \fBpam_start\fR(3)
  46 function creates the PAM context and initiates the PAM transaction. It is the first of the PAM functions that needs to be called by an application. The transaction state is contained entirely within the structure identified by this handle, so it is possible to have multiple transactions in parallel. But it is not possible to use the same handle for different transactions, a new one is needed for every new context.
  47 .PP
  48 The
  49 \fBpam_end\fR(3)
  50 function terminates the PAM transaction and is the last function an application should call in the PAM contenxt. Upon return the handle pamh is no longer valid and all memory associated with it will be invalid. It can be called at any time to terminate a PAM transaction.
  51 .\" end of SS subsection "Initialization and Cleanup"
  52 .SS "Authentication"
  53 .PP
  54 The
  55 \fBpam_authenticate\fR(3)
  56 function is used to authenticate the user. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print.
  57 .PP
  58 The
  59 \fBpam_setcred\fR(3)
  60 function manages the userscredentials.
  61 .\" end of SS subsection "Authentication"
  62 .SS "Account Management"
  63 .PP
  64 The
  65 \fBpam_acct_mgmt\fR(3)
  66 function is used to determine if the users account is valid. It checks for authentication token and account expiration and verifies access restrictions. It is typically called after the user has been authenticated.
  67 .\" end of SS subsection "Account Management"
  68 .SS "Password Management"
  69 .PP
  70 The
  71 \fBpam_chauthtok\fR(3)
  72 function is used to change the authentication token for a given user on request or because the token has expired.
  73 .\" end of SS subsection "Password Management"
  74 .SS "Session Management"
  75 .PP
  76 The
  77 \fBpam_open_session\fR(3)
  78 function sets up a user session for a previously successful authenticated user. The session should later be terminated with a call to
  79 \fBpam_close_session\fR(3).
  80 .\" end of SS subsection "Session Management"
  81 .SS "Conversation"
  82 .PP
  83 The PAM library uses an application\-defined callback to allow a direct communication between a loaded module and the application. This callback is specified by the
  84 \fIstruct pam_conv\fR
  85 passed to
  86 \fBpam_start\fR(3)
  87 at the start of the transaction. See
  88 \fBpam_conv\fR(3)
  89 for details.
  90 .\" end of SS subsection "Conversation"
  91 .SS "Data Objects"
  92 .PP
  93 The
  94 \fBpam_set_item\fR(3)
  95 and
  96 \fBpam_get_item\fR(3)
  97 functions allows applications and PAM service modules to set and retrieve PAM informations.
  98 .PP
  99 The
 100 \fBpam_set_data\fR(3)
 101 and
 102 \fBpam_get_data\fR(3)
 103 functions allows PAM service modules to set and retrieve free\-form data from one invocation to another.
 104 .\" end of SS subsection "Data Objects"
 105 .SS "Environment and Error Management"
 106 .PP
 107 The
 108 \fBpam_putenv\fR(3),
 109 \fBpam_getenv\fR(3)
 110 and
 111 \fBpam_getenvlist\fR(3)
 112 functions are for maintaining a set of private environment variables.
 113 .PP
 114 The
 115 \fBpam_strerror\fR(3)
 116 function returns a pointer to a string describing the given PAM error code.
 117 .\" end of SS subsection "Environment and Error Management"
 118 .SH "RETURN VALUES"
 119 .PP
 120 The following return codes are known by PAM:
 121 .TP 3n
 122 PAM_ABORT
 123 Critical error, immediate abort.
 124 .TP 3n
 125 PAM_ACCT_EXPIRED
 126 User account has expired.
 127 .TP 3n
 128 PAM_AUTHINFO_UNAVAIL
 129 Authentication service cannot retrieve authentication info.
 130 .TP 3n
 131 PAM_AUTHTOK_DISABLE_AGING
 132 Authentication token aging disabled.
 133 .TP 3n
 134 PAM_AUTHTOK_ERR
 135 Authentication token manipulation error.
 136 .TP 3n
 137 PAM_AUTHTOK_EXPIRED
 138 Authentication token expired.
 139 .TP 3n
 140 PAM_AUTHTOK_LOCK_BUSY
 141 Authentication token lock busy.
 142 .TP 3n
 143 PAM_AUTHTOK_RECOVERY_ERR
 144 Authentication information cannot be recovered.
 145 .TP 3n
 146 PAM_AUTH_ERR
 147 Authentication failure.
 148 .TP 3n
 149 PAM_BUF_ERR
 150 Memory buffer error.
 151 .TP 3n
 152 PAM_CONV_ERR
 153 Conversation failure.
 154 .TP 3n
 155 PAM_CRED_ERR
 156 Failure setting user credentials.
 157 .TP 3n
 158 PAM_CRED_EXPIRED
 159 User credentials expired.
 160 .TP 3n
 161 PAM_CRED_INSUFFICIENT
 162 Insufficient credentials to access authentication data.
 163 .TP 3n
 164 PAM_CRED_UNAVAIL
 165 Authentication service cannot retrieve user credentials.
 166 .TP 3n
 167 PAM_IGNORE
 168 The return value should be ignored by PAM dispatch.
 169 .TP 3n
 170 PAM_MAXTRIES
 171 Have exhausted maximum number of retries for service.
 172 .TP 3n
 173 PAM_MODULE_UNKNOWN
 174 Module is unknown.
 175 .TP 3n
 176 PAM_NEW_AUTHTOK_REQD
 177 Authentication token is no longer valid; new one required.
 178 .TP 3n
 179 PAM_NO_MODULE_DATA
 180 No module specific data is present.
 181 .TP 3n
 182 PAM_OPEN_ERR
 183 Failed to load module.
 184 .TP 3n
 185 PAM_PERM_DENIED
 186 Permission denied.
 187 .TP 3n
 188 PAM_SERVICE_ERR
 189 Error in service module.
 190 .TP 3n
 191 PAM_SESSION_ERR
 192 Cannot make/remove an entry for the specified session.
 193 .TP 3n
 194 PAM_SUCCESS
 195 Success.
 196 .TP 3n
 197 PAM_SYMBOL_ERR
 198 Symbol not found.
 199 .TP 3n
 200 PAM_SYSTEM_ERR
 201 System error.
 202 .TP 3n
 203 PAM_TRY_AGAIN
 204 Failed preliminary check by password service.
 205 .TP 3n
 206 PAM_USER_UNKNOWN
 207 User not known to the underlying authentication module.
 208 .SH "SEE ALSO"
 209 .PP
 210
 211 \fBpam_acct_mgmt\fR(3),
 212 \fBpam_authenticate\fR(3),
 213 \fBpam_chauthtok\fR(3),
 214 \fBpam_close_session\fR(3),
 215 \fBpam_conv\fR(3),
 216 \fBpam_end\fR(3),
 217 \fBpam_get_data\fR(3),
 218 \fBpam_getenv\fR(3),
 219 \fBpam_getenvlist\fR(3),
 220 \fBpam_get_item\fR(3),
 221 \fBpam_get_user\fR(3),
 222 \fBpam_open_session\fR(3),
 223 \fBpam_putenv\fR(3),
 224 \fBpam_set_data\fR(3),
 225 \fBpam_set_item\fR(3),
 226 \fBpam_setcred\fR(3),
 227 \fBpam_start\fR(3),
 228 \fBpam_strerror\fR(3)