granicus.if.org Git - linux-pam/blob - doc/man/pam_get_authtok.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
   5 <refentry id="pam_get_authtok">
   6
   7   <refmeta>
   8     <refentrytitle>pam_get_authtok</refentrytitle>
   9     <manvolnum>3</manvolnum>
  10     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_get_authtok-name">
  14     <refname>pam_get_authtok</refname>
  15     <refpurpose>get authentication token</refpurpose>
  16   </refnamediv>
  17
  18 <!-- body begins here -->
  19
  20   <refsynopsisdiv id="pam_get_authtok-synopsis">
  21     <funcsynopsis>
  22       <funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
  23       <funcprototype>
  24         <funcdef>int <function>pam_get_authtok</function></funcdef>
  25         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  26         <paramdef>int <parameter>item</parameter></paramdef>
  27         <paramdef>const char **<parameter>authtok</parameter></paramdef>
  28         <paramdef>const char *<parameter>prompt</parameter></paramdef>
  29       </funcprototype>
  30       <funcprototype>
  31         <funcdef>int <function>pam_get_authtok_noverify</function></funcdef>
  32         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  33         <paramdef>const char **<parameter>authtok</parameter></paramdef>
  34         <paramdef>const char *<parameter>prompt</parameter></paramdef>
  35       </funcprototype>
  36       <funcprototype>
  37         <funcdef>int <function>pam_get_authtok_verify</function></funcdef>
  38         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  39         <paramdef>const char **<parameter>authtok</parameter></paramdef>
  40         <paramdef>const char *<parameter>prompt</parameter></paramdef>
  41       </funcprototype>
  42     </funcsynopsis>
  43   </refsynopsisdiv>
  44
  45   <refsect1 id='pam_get_authtok-description'>
  46     <title>DESCRIPTION</title>
  47     <para>
  48       The <function>pam_get_authtok</function> function returns the
  49       cached authentication token, or prompts the user if no token is
  50       currently cached. It is intended for internal use by Linux-PAM and
  51       PAM service modules. Upon successful return,
  52       <emphasis>authtok</emphasis> contains a pointer to the value of the
  53       authentication token. Note, this is a pointer to the
  54       <emphasis>actual</emphasis> data and should
  55       <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
  56       over-written!
  57     </para>
  58     <para>
  59       The <emphasis>prompt</emphasis> argument specifies a prompt to use
  60       if no token is cached. If a NULL pointer
  61       is given, <function>pam_get_authtok</function> uses pre-defined prompts.
  62     </para>
  63     <para>
  64       The following values are supported for <emphasis>item</emphasis>:
  65     </para>
  66     <variablelist>
  67       <varlistentry>
  68         <term>PAM_AUTHTOK</term>
  69         <listitem>
  70           <para>
  71             Returns the current authentication token. Called from
  72             <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
  73             </citerefentry> <function>pam_get_authtok</function> will
  74             ask the user to confirm the new token by retyping it. If
  75             a prompt was specified, "Retype" will be used as prefix.
  76           </para>
  77         </listitem>
  78       </varlistentry>
  79       <varlistentry>
  80         <term>PAM_OLDAUTHTOK</term>
  81         <listitem>
  82           <para>
  83             Returns the previous authentication token when changing
  84             authentication tokens.
  85           </para>
  86         </listitem>
  87       </varlistentry>
  88     </variablelist>
  89     <para>
  90       The <function>pam_get_authtok_noverify</function> function can
  91       only be used for changing the password
  92       (from <citerefentry>
  93         <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
  94       </citerefentry>). It returns the cached
  95       authentication token, or prompts the user if no token is
  96       currently cached. The difference to <function>pam_get_authtok</function>
  97       is, that this function does not ask a second time for the password
  98       to verify it. Upon successful return, <emphasis>authtok</emphasis>
  99       contains a pointer to the value of the authentication token. Note,
 100       this is a pointer to the
 101       <emphasis>actual</emphasis> data and should
 102       <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
 103       over-written!
 104     </para>
 105     <para>
 106       The <function>pam_get_authtok_verify</function> function can
 107       only be used to verify a password for mistypes gotten by
 108      <citerefentry>
 109         <refentrytitle>pam_get_authtok_noverify</refentrytitle><manvolnum>3</manvolnum>
 110       </citerefentry>. This function asks a second time for the password
 111       and verify it with the password provided by <emphasis>authtok</emphasis>
 112       argument. In case of an error, the value of <emphasis>authtok</emphasis>
 113       is undefined. Else this argument will point to the
 114       <emphasis>actual</emphasis> data and should
 115       <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
 116       over-written!
 117     </para>
 118   </refsect1>
 119
 120   <refsect1 id="pam_get_authtok-options">
 121     <title>OPTIONS</title>
 122     <para>
 123       <function>pam_get_authtok</function> honours the following module
 124       options:
 125     </para>
 126     <variablelist>
 127       <varlistentry>
 128         <term>
 129           <option>try_first_pass</option>
 130         </term>
 131         <listitem>
 132           <para>
 133             Before prompting the user for their password, the module first
 134             tries the previous stacked module's password in case that
 135             satisfies this module as well.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139       <varlistentry>
 140         <term>
 141           <option>use_first_pass</option>
 142         </term>
 143         <listitem>
 144           <para>
 145             The argument <option>use_first_pass</option> forces the module
 146             to use a previous stacked modules password and will never prompt
 147             the user - if no password is available or the password is not
 148             appropriate, the user will be denied access.
 149           </para>
 150         </listitem>
 151       </varlistentry>
 152        <varlistentry>
 153         <term>
 154           <option>use_authtok</option>
 155         </term>
 156         <listitem>
 157           <para>
 158             When password changing enforce the module to set the new
 159             token to the one provided by a previously stacked
 160             <option>password</option> module. If no token is available
 161             token changing will fail.
 162           </para>
 163         </listitem>
 164       </varlistentry>
 165       <varlistentry>
 166         <term>
 167           <option>authtok_type=<replaceable>XXX</replaceable></option>
 168         </term>
 169         <listitem>
 170           <para>
 171             The default action is for the module to use the
 172             following prompts when requesting passwords:
 173             "New UNIX password: " and "Retype UNIX password: ".
 174             The example word <emphasis>UNIX</emphasis> can
 175             be replaced with this option, by default it is empty.
 176           </para>
 177         </listitem>
 178       </varlistentry>
 179     </variablelist>
 180   </refsect1>
 181
 182
 183   <refsect1 id="pam_get_authtok-return_values">
 184     <title>RETURN VALUES</title>
 185     <variablelist>
 186       <varlistentry>
 187         <term>PAM_AUTH_ERR</term>
 188         <listitem>
 189            <para>
 190              Authentication token could not be retrieved.
 191           </para>
 192         </listitem>
 193       </varlistentry>
 194       <varlistentry>
 195         <term>PAM_AUTHTOK_ERR</term>
 196         <listitem>
 197            <para>
 198              New authentication could not be retrieved.
 199           </para>
 200         </listitem>
 201       </varlistentry>
 202       <varlistentry>
 203         <term>PAM_SUCCESS</term>
 204         <listitem>
 205            <para>
 206              Authentication token was successfully retrieved.
 207           </para>
 208         </listitem>
 209       </varlistentry>
 210       <varlistentry>
 211         <term>PAM_SYSTEM_ERR</term>
 212         <listitem>
 213            <para>
 214              No space for an authentication token was provided.
 215           </para>
 216         </listitem>
 217       </varlistentry>
 218       <varlistentry>
 219         <term>PAM_TRY_AGAIN</term>
 220         <listitem>
 221            <para>
 222              New authentication tokens mismatch.
 223           </para>
 224         </listitem>
 225       </varlistentry>
 226     </variablelist>
 227   </refsect1>
 228
 229   <refsect1 id='pam_get_authtok-see_also'>
 230     <title>SEE ALSO</title>
 231     <para>
 232       <citerefentry>
 233         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 234       </citerefentry>
 235     </para>
 236   </refsect1>
 237
 238   <refsect1 id='pam_get_authtok-standards'>
 239     <title>STANDARDS</title>
 240     <para>
 241       The <function>pam_get_authtok</function> function is a Linux-PAM
 242       extensions.
 243     </para>
 244   </refsect1>
 245
 246 </refentry>