granicus.if.org Git - linux-pam/blob - doc/man/pam_authenticate.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='pam_authenticate'>
   5   <refmeta>
   6     <refentrytitle>pam_authenticate</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_authenticate-name">
  12     <refname>pam_authenticate</refname>
  13     <refpurpose>account authentication</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv>
  19     <funcsynopsis id='pam_authenticate-synopsis'>
  20       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  21       <funcprototype>
  22         <funcdef>int <function>pam_authenticate</function></funcdef>
  23         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  24         <paramdef>int <parameter>flags</parameter></paramdef>
  25       </funcprototype>
  26     </funcsynopsis>
  27   </refsynopsisdiv>
  28
  29
  30   <refsect1 id='pam_authenticate-description'>
  31     <title>DESCRIPTION</title>
  32     <para>
  33       The <function>pam_authenticate</function> function is used to
  34       authenticate the user. The user is required to provide an
  35       authentication token depending upon the authentication service,
  36       usually this is a password, but could also be a finger print.
  37     </para>
  38     <para>
  39       The PAM service module may request that the user enter their
  40       username vio the the conversation mechanism (see
  41       <citerefentry>
  42         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
  43       </citerefentry> and
  44       <citerefentry>
  45         <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
  46       </citerefentry>). The name of the authenticated user
  47        will be present in the PAM item PAM_USER. This item may be
  48        recovered with a call to
  49       <citerefentry>
  50         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
  51       </citerefentry>.
  52     </para>
  53     <para>
  54       The <emphasis>pamh</emphasis> argument is an authentication
  55       handle obtained by a prior call to pam_start().
  56       The flags argument is the binary or of zero or more of the
  57       following values:
  58     </para>
  59     <variablelist>
  60       <varlistentry>
  61         <term>PAM_SILENT</term>
  62         <listitem>
  63            <para>
  64              Do not emit any messages.
  65           </para>
  66         </listitem>
  67       </varlistentry>
  68       <varlistentry>
  69         <term>PAM_DISALLOW_NULL_AUTHTOK</term>
  70         <listitem>
  71           <para>
  72             The PAM module service should return PAM_AUTH_ERR
  73             if the user does not have a registered authentication token.
  74           </para>
  75         </listitem>
  76       </varlistentry>
  77     </variablelist>
  78   </refsect1>
  79
  80   <refsect1 id="pam_authenticate-return_values">
  81     <title>RETURN VALUES</title>
  82     <variablelist>
  83       <varlistentry>
  84         <term>PAM_ABORT</term>
  85         <listitem>
  86           <para>
  87             The application should exit immediately after calling
  88             <citerefentry>
  89               <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
  90             </citerefentry> first.
  91           </para>
  92         </listitem>
  93       </varlistentry>
  94       <varlistentry>
  95         <term>PAM_AUTH_ERR</term>
  96         <listitem>
  97           <para>
  98             The user was not authenticated.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102       <varlistentry>
 103         <term>PAM_CRED_INSUFFICIENT</term>
 104         <listitem>
 105           <para>
 106             For some reason the application does not have sufficient
 107             credentials to authenticate the user.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term>PAM_AUTHINFO_UNVAIL</term>
 113         <listitem>
 114           <para>
 115             The modules were not able to access the authentication
 116             information. This might be due to a network or hardware
 117             failure etc.
 118           </para>
 119         </listitem>
 120       </varlistentry>
 121       <varlistentry>
 122         <term>PAM_MAXTRIES</term>
 123         <listitem>
 124           <para>
 125             One or more of the authentication modules has reached its
 126             limit of tries authenticating the user. Do not try again.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130       <varlistentry>
 131         <term>PAM_SUCCESS</term>
 132         <listitem>
 133            <para>
 134              The user was successfully authenticated.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138       <varlistentry>
 139         <term>PAM_USER_UNKNOWN</term>
 140         <listitem>
 141           <para>
 142             User unknown to authentication service.
 143           </para>
 144         </listitem>
 145       </varlistentry>
 146     </variablelist>
 147   </refsect1>
 148
 149   <refsect1 id='pam_authenticate-see_also'>
 150     <title>SEE ALSO</title>
 151     <para>
 152       <citerefentry>
 153         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
 154       </citerefentry>,
 155       <citerefentry>
 156         <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 157       </citerefentry>,
 158       <citerefentry>
 159         <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 160       </citerefentry>,
 161       <citerefentry>
 162         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 163       </citerefentry>,
 164       <citerefentry>
 165         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 166       </citerefentry>
 167     </para>
 168   </refsect1>
 169 </refentry>