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