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     </funcsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1 id='pam_get_authtok-description'>
  34     <title>DESCRIPTION</title>
  35     <para>
  36       The <function>pam_get_authtok</function> function returns the
  37       cached authentication token, or prompts the user if no token is
  38       currently cached. It is intended for internal use by Linux-PAM and
  39       PAM service modules. Upon successful return,
  40       <emphasis>authtok</emphasis> contains a pointer to the value of the
  41       authentication token. Note, this is a pointer to the
  42       <emphasis>actual</emphasis> data and should
  43       <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
  44       over-written!
  45     </para>
  46     <para>
  47       The <emphasis>prompt</emphasis> argument specifies a prompt to use
  48       if no token is cached. If a NULL pointer
  49       is given, <function>pam_get_authtok</function> uses pre-defined prompts.
  50     </para>
  51     <para>
  52       The following values are supported for <emphasis>item</emphasis>:
  53     </para>
  54     <variablelist>
  55       <varlistentry>
  56         <term>PAM_AUTHTOK</term>
  57         <listitem>
  58           <para>
  59             Returns the current authentication token. Called from
  60             <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
  61             </citerefentry> <function>pam_get_authtok</function> will
  62             ask the user to confirm the new token by retyping it. If
  63             a prompt was specified, "Retype" will be used as prefix.
  64           </para>
  65         </listitem>
  66       </varlistentry>
  67       <varlistentry>
  68         <term>PAM_OLDAUTHTOK</term>
  69         <listitem>
  70           <para>
  71             Returns the previous authentication token when changing
  72             authentication tokens.
  73           </para>
  74         </listitem>
  75       </varlistentry>
  76     </variablelist>
  77   </refsect1>
  78
  79   <refsect1 id="pam_get_authtok-options">
  80     <title>OPTIONS</title>
  81     <para>
  82       <function>pam_get_authtok</function> honours the following module
  83       options:
  84     </para>
  85     <variablelist>
  86       <varlistentry>
  87         <term>
  88           <option>try_first_pass</option>
  89         </term>
  90         <listitem>
  91           <para>
  92             Before prompting the user for their password, the module first
  93             tries the previous stacked module's password in case that
  94             satisfies this module as well.
  95           </para>
  96         </listitem>
  97       </varlistentry>
  98       <varlistentry>
  99         <term>
 100           <option>use_first_pass</option>
 101         </term>
 102         <listitem>
 103           <para>
 104             The argument <option>use_first_pass</option> forces the module
 105             to use a previous stacked modules password and will never prompt
 106             the user - if no password is available or the password is not
 107             appropriate, the user will be denied access.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111        <varlistentry>
 112         <term>
 113           <option>use_authtok</option>
 114         </term>
 115         <listitem>
 116           <para>
 117             When password changing enforce the module to set the new
 118             token to the one provided by a previously stacked
 119             <option>password</option> module. If no token is available
 120             token changing will fail.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term>
 126           <option>authtok_type=<replaceable>XXX</replaceable></option>
 127         </term>
 128         <listitem>
 129           <para>
 130             The default action is for the module to use the
 131             following prompts when requesting passwords:
 132             "New UNIX password: " and "Retype UNIX password: ".
 133             The example word <emphasis>UNIX</emphasis> can
 134             be replaced with this option, by default it is empty.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138     </variablelist>
 139   </refsect1>
 140
 141
 142   <refsect1 id="pam_get_authtok-return_values">
 143     <title>RETURN VALUES</title>
 144     <variablelist>
 145       <varlistentry>
 146         <term>PAM_AUTH_ERR</term>
 147         <listitem>
 148            <para>
 149              Authentication token could not be retrieved.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153       <varlistentry>
 154         <term>PAM_AUTHTOK_ERR</term>
 155         <listitem>
 156            <para>
 157              New authentication could not be retrieved.
 158           </para>
 159         </listitem>
 160       </varlistentry>
 161       <varlistentry>
 162         <term>PAM_SUCCESS</term>
 163         <listitem>
 164            <para>
 165              Authentication token was successful retrieved.
 166           </para>
 167         </listitem>
 168       </varlistentry>
 169       <varlistentry>
 170         <term>PAM_SYSTEM_ERR</term>
 171         <listitem>
 172            <para>
 173              No space for an authentication token was provided.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177       <varlistentry>
 178         <term>PAM_TRY_AGAIN</term>
 179         <listitem>
 180            <para>
 181              New authentication tokens mismatch.
 182           </para>
 183         </listitem>
 184       </varlistentry>
 185     </variablelist>
 186   </refsect1>
 187
 188   <refsect1 id='pam_get_authtok-see_also'>
 189     <title>SEE ALSO</title>
 190     <para>
 191       <citerefentry>
 192         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 193       </citerefentry>
 194     </para>
 195   </refsect1>
 196
 197   <refsect1 id='pam_get_authtok-standards'>
 198     <title>STANDARDS</title>
 199     <para>
 200       The <function>pam_get_authtok</function> function is a Linux-PAM
 201       extensions.
 202     </para>
 203   </refsect1>
 204
 205 </refentry>