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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id='pam3'>
   5
   6   <refmeta>
   7     <refentrytitle>pam</refentrytitle>
   8     <manvolnum>3</manvolnum>
   9     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  10   </refmeta>
  11
  12   <refnamediv id='pam3-name'>
  13     <refname>pam</refname>
  14     <refpurpose>Pluggable Authentication Modules Library</refpurpose>
  15   </refnamediv>
  16
  17   <refsynopsisdiv id='pam3-synopsis'>
  18     <funcsynopsis>
  19       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  20       <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  21       <funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
  22    </funcsynopsis>
  23   </refsynopsisdiv>
  24
  25   <refsect1 id='pam3-description'>
  26     <title>DESCRIPTION</title>
  27     <para>
  28       <emphasis remap='B'>PAM</emphasis> is a system of libraries
  29       that handle the authentication tasks of applications (services)
  30       on the system. The library provides a stable general interface
  31       (Application Programming Interface - API) that privilege granting
  32       programs (such as
  33       <citerefentry>
  34         <refentrytitle>login</refentrytitle><manvolnum>1</manvolnum>
  35       </citerefentry> and <citerefentry>
  36         <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
  37       </citerefentry>)
  38       defer to to perform standard authentication tasks.
  39     </para>
  40
  41     <refsect2 id='pam3-initialization_and_cleanup'>
  42       <title>Initialization and Cleanup</title>
  43       <para>
  44         The
  45         <citerefentry>
  46           <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
  47         </citerefentry> function creates the PAM context and initiates the
  48         PAM transaction. It is the first of the PAM functions that needs to
  49         be called by an application. The transaction state is contained
  50         entirely within the structure identified by this handle, so it is
  51         possible to have multiple transactions in parallel. But it is not
  52         possible to use the same handle for different transactions, a new
  53         one is needed for every new context.
  54       </para>
  55       <para>
  56         The
  57         <citerefentry>
  58           <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
  59         </citerefentry> function terminates the PAM transaction and is the last
  60         function an application should call in the PAM context. Upon return
  61         the handle pamh is no longer valid and all memory associated with it
  62         will be invalid. It can be called at any time to terminate a PAM
  63         transaction.
  64       </para>
  65     </refsect2>
  66
  67     <refsect2 id='pam3-authentication'>
  68       <title>Authentication</title>
  69       <para>
  70         The
  71         <citerefentry>
  72           <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
  73         </citerefentry>
  74         function is used to
  75         authenticate the user. The user is required to provide an
  76         authentication token depending upon the authentication service,
  77         usually this is a password, but could also be a finger print.
  78       </para>
  79       <para>
  80         The
  81         <citerefentry>
  82           <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
  83         </citerefentry>
  84         function manages the userscredentials.
  85       </para>
  86     </refsect2>
  87
  88     <refsect2 id='pam3-account_management'>
  89       <title>Account Management</title>
  90       <para>
  91         The
  92         <citerefentry>
  93           <refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
  94         </citerefentry> function is used to determine if the users account is
  95         valid. It checks for authentication token and account expiration and
  96         verifies access restrictions. It is typically called after the user
  97         has been authenticated.
  98       </para>
  99     </refsect2>
 100
 101     <refsect2 id='pam3-password_management'>
 102       <title>Password Management</title>
 103       <para>
 104         The
 105         <citerefentry>
 106           <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 107         </citerefentry> function is used to change the authentication token
 108         for a given user on request or because the token has expired.
 109       </para>
 110     </refsect2>
 111
 112     <refsect2 id='pam3-session_management'>
 113       <title>Session Management</title>
 114       <para>
 115         The
 116         <citerefentry>
 117           <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
 118         </citerefentry> function sets up a user session for a previously
 119         successful authenticated user. The session should later be terminated
 120         with a call to
 121         <citerefentry>
 122           <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
 123         </citerefentry>.
 124       </para>
 125     </refsect2>
 126
 127     <refsect2 id='pam3-conversation'>
 128       <title>Conversation</title>
 129       <para>
 130         The PAM library uses an application-defined callback to allow
 131         a direct communication between a loaded module and the application.
 132         This callback is specified by the
 133         <emphasis>struct pam_conv</emphasis> passed to
 134         <citerefentry>
 135           <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
 136         </citerefentry> at the start of the transaction. See
 137         <citerefentry>
 138           <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
 139         </citerefentry>
 140         for details.
 141       </para>
 142     </refsect2>
 143
 144     <refsect2 id='pam3-data'>
 145       <title>Data Objects</title>
 146       <para>
 147         The
 148         <citerefentry>
 149           <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
 150         </citerefentry>
 151         and
 152         <citerefentry>
 153           <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 154         </citerefentry>
 155         functions allows applications and PAM service modules to set and
 156         retrieve PAM informations.
 157       </para>
 158       <para>
 159          The
 160         <citerefentry>
 161           <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
 162         </citerefentry>
 163         function is the preferred method to obtain the username.
 164       </para>
 165       <para>
 166         The
 167         <citerefentry>
 168           <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
 169         </citerefentry>
 170         and
 171         <citerefentry>
 172           <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
 173         </citerefentry>
 174         functions allows PAM service modules to set and retrieve free-form
 175         data from one invocation to another.
 176       </para>
 177     </refsect2>
 178
 179     <refsect2 id='pam3-miscellaneous'>
 180     <title>Environment and Error Management</title>
 181       <para>
 182         The
 183         <citerefentry>
 184           <refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
 185         </citerefentry>,
 186         <citerefentry>
 187           <refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
 188         </citerefentry> and
 189         <citerefentry>
 190           <refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
 191         </citerefentry>
 192         functions are for maintaining a set of private environment variables.
 193       </para>
 194
 195       <para>
 196         The
 197         <citerefentry>
 198           <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 199         </citerefentry> function returns a pointer to a string describing the
 200         given PAM error code.
 201       </para>
 202     </refsect2>
 203   </refsect1>
 204
 205   <refsect1 id='pam3-return_values'>
 206     <title>RETURN VALUES</title>
 207     <para>
 208       The following return codes are known by PAM:
 209     </para>
 210     <variablelist>
 211       <varlistentry>
 212         <term>PAM_ABORT</term>
 213         <listitem>
 214           <para>Critical error, immediate abort.</para>
 215         </listitem>
 216       </varlistentry>
 217       <varlistentry>
 218         <term>PAM_ACCT_EXPIRED</term>
 219         <listitem>
 220           <para>User account has expired.</para>
 221         </listitem>
 222       </varlistentry>
 223       <varlistentry>
 224         <term>PAM_AUTHINFO_UNAVAIL</term>
 225         <listitem>
 226           <para>
 227             Authentication service cannot retrieve authentication info.
 228           </para>
 229         </listitem>
 230       </varlistentry>
 231       <varlistentry>
 232         <term>PAM_AUTHTOK_DISABLE_AGING</term>
 233         <listitem>
 234           <para>Authentication token aging disabled.</para>
 235         </listitem>
 236       </varlistentry>
 237       <varlistentry>
 238         <term>PAM_AUTHTOK_ERR</term>
 239         <listitem>
 240           <para>Authentication token manipulation error.</para>
 241         </listitem>
 242       </varlistentry>
 243       <varlistentry>
 244         <term>PAM_AUTHTOK_EXPIRED</term>
 245         <listitem>
 246           <para>Authentication token expired.</para>
 247         </listitem>
 248       </varlistentry>
 249       <varlistentry>
 250         <term>PAM_AUTHTOK_LOCK_BUSY</term>
 251         <listitem>
 252           <para>Authentication token lock busy.</para>
 253         </listitem>
 254       </varlistentry>
 255       <varlistentry>
 256         <term>PAM_AUTHTOK_RECOVERY_ERR</term>
 257         <listitem>
 258           <para>Authentication information cannot be recovered.</para>
 259         </listitem>
 260       </varlistentry>
 261       <varlistentry>
 262         <term>PAM_AUTH_ERR</term>
 263         <listitem>
 264           <para>Authentication failure.</para>
 265         </listitem>
 266       </varlistentry>
 267       <varlistentry>
 268         <term>PAM_BUF_ERR</term>
 269         <listitem>
 270           <para>Memory buffer error.</para>
 271         </listitem>
 272       </varlistentry>
 273       <varlistentry>
 274         <term>PAM_CONV_ERR</term>
 275         <listitem>
 276           <para>Conversation failure.</para>
 277         </listitem>
 278       </varlistentry>
 279       <varlistentry>
 280         <term>PAM_CRED_ERR</term>
 281         <listitem>
 282           <para>Failure setting user credentials.</para>
 283         </listitem>
 284       </varlistentry>
 285       <varlistentry>
 286         <term>PAM_CRED_EXPIRED</term>
 287         <listitem>
 288           <para>User credentials expired.</para>
 289         </listitem>
 290       </varlistentry>
 291       <varlistentry>
 292         <term>PAM_CRED_INSUFFICIENT</term>
 293         <listitem>
 294           <para>Insufficient credentials to access authentication data.</para>
 295         </listitem>
 296       </varlistentry>
 297       <varlistentry>
 298         <term>PAM_CRED_UNAVAIL</term>
 299         <listitem>
 300           <para>Authentication service cannot retrieve user credentials.</para>
 301         </listitem>
 302       </varlistentry>
 303       <varlistentry>
 304         <term>PAM_IGNORE</term>
 305         <listitem>
 306           <para>The return value should be ignored by PAM dispatch.</para>
 307         </listitem>
 308       </varlistentry>
 309       <varlistentry>
 310         <term>PAM_MAXTRIES</term>
 311         <listitem>
 312           <para>Have exhausted maximum number of retries for service.</para>
 313         </listitem>
 314       </varlistentry>
 315       <varlistentry>
 316         <term>PAM_MODULE_UNKNOWN</term>
 317         <listitem>
 318           <para>Module is unknown.</para>
 319         </listitem>
 320       </varlistentry>
 321       <varlistentry>
 322         <term>PAM_NEW_AUTHTOK_REQD</term>
 323         <listitem>
 324           <para>
 325             Authentication token is no longer valid; new one required.
 326           </para>
 327         </listitem>
 328       </varlistentry>
 329       <varlistentry>
 330         <term>PAM_NO_MODULE_DATA</term>
 331         <listitem>
 332           <para>No module specific data is present.</para>
 333         </listitem>
 334       </varlistentry>
 335       <varlistentry>
 336         <term>PAM_OPEN_ERR</term>
 337         <listitem>
 338           <para>Failed to load module.</para>
 339         </listitem>
 340       </varlistentry>
 341       <varlistentry>
 342         <term>PAM_PERM_DENIED</term>
 343         <listitem>
 344           <para>Permission denied.</para>
 345         </listitem>
 346       </varlistentry>
 347       <varlistentry>
 348         <term>PAM_SERVICE_ERR</term>
 349         <listitem>
 350           <para>Error in service module.</para>
 351         </listitem>
 352       </varlistentry>
 353       <varlistentry>
 354         <term>PAM_SESSION_ERR</term>
 355         <listitem>
 356           <para>Cannot make/remove an entry for the specified session.</para>
 357         </listitem>
 358       </varlistentry>
 359       <varlistentry>
 360         <term>PAM_SUCCESS</term>
 361         <listitem>
 362           <para>Success.</para>
 363         </listitem>
 364       </varlistentry>
 365       <varlistentry>
 366         <term>PAM_SYMBOL_ERR</term>
 367         <listitem>
 368           <para>Symbol not found.</para>
 369         </listitem>
 370       </varlistentry>
 371       <varlistentry>
 372         <term>PAM_SYSTEM_ERR</term>
 373         <listitem>
 374           <para>System error.</para>
 375         </listitem>
 376       </varlistentry>
 377       <varlistentry>
 378         <term>PAM_TRY_AGAIN</term>
 379         <listitem>
 380           <para>Failed preliminary check by password service.</para>
 381         </listitem>
 382       </varlistentry>
 383       <varlistentry>
 384         <term>PAM_USER_UNKNOWN</term>
 385         <listitem>
 386           <para>User not known to the underlying authentication module.</para>
 387         </listitem>
 388       </varlistentry>
 389     </variablelist>
 390   </refsect1>
 391
 392   <refsect1 id='see_also'><title>SEE ALSO</title>
 393     <para>
 394       <citerefentry>
 395         <refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
 396       </citerefentry>, <citerefentry>
 397         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
 398       </citerefentry>, <citerefentry>
 399         <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 400       </citerefentry>, <citerefentry>
 401         <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
 402       </citerefentry>, <citerefentry>
 403         <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
 404       </citerefentry>, <citerefentry>
 405         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
 406       </citerefentry>, <citerefentry>
 407         <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
 408       </citerefentry>, <citerefentry>
 409         <refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
 410       </citerefentry>, <citerefentry>
 411         <refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
 412       </citerefentry>, <citerefentry>
 413         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 414       </citerefentry>, <citerefentry>
 415         <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
 416       </citerefentry>, <citerefentry>
 417         <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
 418       </citerefentry>, <citerefentry>
 419         <refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
 420       </citerefentry>, <citerefentry>
 421         <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
 422       </citerefentry>, <citerefentry>
 423         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
 424       </citerefentry>, <citerefentry>
 425         <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 426       </citerefentry>, <citerefentry>
 427         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
 428       </citerefentry>, <citerefentry>
 429         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 430       </citerefentry>
 431     </para>
 432   </refsect1>
 433   <refsect1 id='pam3-notes'><title>NOTES</title>
 434     <para>
 435       The <emphasis>libpam</emphasis> interfaces are only thread-safe if each
 436       thread within the multithreaded application uses its own PAM handle.
 437     </para>
 438   </refsect1>
 439 </refentry>