granicus.if.org Git - linux-pam/blob - doc/man/pam_sm_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_sm_authenticate'>
   5   <refmeta>
   6     <refentrytitle>pam_sm_authenticate</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_sm_authenticate-name">
  12     <refname>pam_sm_authenticate</refname>
  13     <refpurpose>PAM service function for user authentication</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv id='pam_sm_authenticate-synopsis'>
  19     <funcsynopsis>
  20       <funcsynopsisinfo>#define PAM_SM_AUTH</funcsynopsisinfo>
  21       <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  22       <funcprototype>
  23         <funcdef>PAM_EXTERN int <function>pam_sm_authenticate</function></funcdef>
  24         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  25         <paramdef>int <parameter>flags</parameter></paramdef>
  26         <paramdef>int <parameter>argc</parameter></paramdef>
  27         <paramdef>const char **<parameter>argv</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32
  33   <refsect1 id='pam_sm_authenticate-description'>
  34     <title>DESCRIPTION</title>
  35     <para>
  36       The <function>pam_sm_authenticate</function> function is the service
  37       module's implementation of the
  38       <citerefentry>
  39         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
  40       </citerefentry> interface.
  41     </para>
  42     <para>
  43       This function performs the task of authenticating the user.
  44     </para>
  45     <para>
  46        Valid flags, which may be logically OR'd with
  47        <emphasis>PAM_SILENT</emphasis>, are:
  48     </para>
  49     <variablelist>
  50       <varlistentry>
  51         <term>PAM_SILENT</term>
  52         <listitem>
  53            <para>
  54              Do not emit any messages.
  55           </para>
  56         </listitem>
  57       </varlistentry>
  58       <varlistentry>
  59         <term>PAM_DISALLOW_NULL_AUTHTOK</term>
  60         <listitem>
  61           <para>
  62             Return <emphasis remap='B'>PAM_AUTH_ERR</emphasis> if the
  63             database of authentication tokens for this authentication
  64             mechanism has a <emphasis>NULL</emphasis> entry for the user.
  65             Without this flag, such a <emphasis>NULL</emphasis> token
  66             will lead to a success without the user being prompted.
  67           </para>
  68         </listitem>
  69       </varlistentry>
  70     </variablelist>
  71   </refsect1>
  72
  73   <refsect1 id="pam_sm_authenticate-return_values">
  74     <title>RETURN VALUES</title>
  75     <variablelist>
  76       <varlistentry>
  77         <term>PAM_AUTH_ERR</term>
  78         <listitem>
  79           <para>
  80             Authentication failure.
  81           </para>
  82         </listitem>
  83       </varlistentry>
  84       <varlistentry>
  85         <term>PAM_CRED_INSUFFICIENT</term>
  86         <listitem>
  87           <para>
  88             For some reason the application does not have sufficient
  89             credentials to authenticate the user.
  90           </para>
  91         </listitem>
  92       </varlistentry>
  93       <varlistentry>
  94         <term>PAM_AUTHINFO_UNAVAIL</term>
  95         <listitem>
  96           <para>
  97             The modules were not able to access the authentication
  98             information. This might be due to a network or hardware
  99             failure etc.
 100           </para>
 101         </listitem>
 102       </varlistentry>
 103       <varlistentry>
 104         <term>PAM_SUCCESS</term>
 105         <listitem>
 106            <para>
 107              The authentication token was successfully updated.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term>PAM_USER_UNKNOWN</term>
 113         <listitem>
 114           <para>
 115             The supplied username is not known to the authentication
 116             service.
 117           </para>
 118         </listitem>
 119       </varlistentry>
 120       <varlistentry>
 121         <term>PAM_MAXTRIES</term>
 122         <listitem>
 123           <para>
 124             One or more of the authentication modules has reached its
 125             limit of tries authenticating the user. Do not try again.
 126           </para>
 127         </listitem>
 128       </varlistentry>
 129     </variablelist>
 130   </refsect1>
 131
 132   <refsect1 id='pam_sm_authenticate-see_also'>
 133     <title>SEE ALSO</title>
 134     <para>
 135       <citerefentry>
 136         <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
 137       </citerefentry>,
 138       <citerefentry>
 139         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
 140       </citerefentry>,
 141       <citerefentry>
 142         <refentrytitle>pam_sm_setcred</refentrytitle><manvolnum>3</manvolnum>
 143       </citerefentry>,
 144       <citerefentry>
 145         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 146       </citerefentry>,
 147       <citerefentry>
 148         <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
 149       </citerefentry>
 150     </para>
 151   </refsect1>
 152 </refentry>