Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------

2008-12-03  Thorsten Kukuk  <kukuk@suse.de>

        * doc/man/Makefile.am: Add pam_get_authtok.3.xml.
        * doc/man/pam_get_authtok.3.xml: New.
        * libpam/Makefile.am: Add pam_get_authtok.c.
        * libpam/libpam.map: Export pam_get_authtok.
        * libpam/pam_get_authtok.c: New.
        * libpam/pam_private.h: Add mod_argc and mod_argv to pam_handle.
        * libpam_include/security/pam_ext.h: Add pam_get_authtok
        prototype.
        * modules/pam_cracklib/pam_cracklib.c: Use pam_get_authtok.
        * modules/pam_pwhistory/pam_pwhistory.c: Likewise.
        * po/POTFILES.in: Add libpam/pam_get_authtok.c.
        * xtests/tst-pam_cracklib1.c: Adjust error codes.

        * modules/pam_timestamp/Makefile.am: Remove hmactest.c from
        EXTRA_DIST.

        * po/*.po: Regenerated.

3 files changed, 196 insertions, 4 deletions

diff --git a/doc/man/.cvsignore b/doc/man/.cvsignore
index d1987738..cc2afe9b 100644
--- a/doc/man/.cvsignore
+++ b/doc/man/.cvsignore
@@ -18,6 +18,7 @@ pam_fail_delay.3
 pam_get_data.3
 pam_getenv.3
 pam_getenvlist.3
+pam_get_authtok.3
 pam_get_item.3
 pam_get_user.3
 pam_info.3
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 52e5caab..9b229b16 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -12,8 +12,8 @@ man_MANS = pam.3 PAM.8 pam.8 pam.conf.5 pam.d.5 \
 	pam_chauthtok.3 pam_close_session.3 pam_conv.3 \
 	pam_end.3 pam_error.3 \
 	pam_fail_delay.3 pam_xauth_data.3 \
-	pam_get_data.3 pam_get_item.3 pam_get_user.3 pam_getenv.3 \
-	pam_getenvlist.3 \
+	pam_get_authtok.3 pam_get_data.3 pam_get_item.3 pam_get_user.3 \
+	pam_getenv.3 pam_getenvlist.3 \
 	pam_info.3 \
 	pam_open_session.3 \
 	pam_prompt.3 pam_putenv.3 \
@@ -29,8 +29,8 @@ XMLS = pam.3.xml pam.8.xml \
 	pam_chauthtok.3.xml pam_close_session.3.xml pam_conv.3.xml \
 	pam_end.3.xml pam_error.3.xml \
 	pam_fail_delay.3.xml pam_xauth_data.3 \
-	pam_get_data.3.xml pam_get_item.3.xml pam_get_user.3.xml \
-	pam_getenv.3.xml pam_getenvlist.3.xml \
+	pam_get_authtok.3.xml pam_get_data.3.xml pam_get_item.3.xml \
+	pam_get_user.3.xml pam_getenv.3.xml pam_getenvlist.3.xml \
         pam_info.3.xml \
 	pam_open_session.3.xml \
 	pam_prompt.3.xml pam_putenv.3.xml \
diff --git a/doc/man/pam_get_authtok.3.xml b/doc/man/pam_get_authtok.3.xml
new file mode 100644
index 00000000..bac30be9
--- /dev/null
+++ b/doc/man/pam_get_authtok.3.xml
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<refentry id="pam_get_authtok">
+
+  <refmeta>
+    <refentrytitle>pam_get_authtok</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_get_authtok-name">
+    <refname>pam_get_authtok</refname>
+    <refpurpose>get authentication token</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv id="pam_get_authtok-synopsis">
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
+      <funcprototype>
+        <funcdef>int <function>pam_get_authtok</function></funcdef>
+        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+        <paramdef>int <parameter>item</parameter></paramdef>
+        <paramdef>const char **<parameter>authtok</parameter></paramdef>
+        <paramdef>const char *<parameter>prompt</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id='pam_get_authtok-description'>
+    <title>DESCRIPTION</title>
+    <para>
+      The <function>pam_get_authtok</function> function returns the
+      cached authentication token, or prompts the user if no token is
+      currently cached. It is intended for internal use by Linux-PAM and
+      PAM service modules. Upon successful return,
+      <emphasis>authtok</emphasis> contains a pointer to the value of the
+      authentication token. Note, this is a pointer to the
+      <emphasis>actual</emphasis> data and should
+      <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
+      over-written!
+    </para>
+    <para>
+      The <emphasis>prompt</emphasis> argument specifies a prompt to use
+      if no token is cached. If a NULL pointer
+      is given, <function>pam_get_authtok</function> uses pre-defined prompts.
+    </para>
+    <para>
+      The following values are supported for <emphasis>item</emphasis>:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_AUTHTOK</term>
+        <listitem>
+          <para>
+            Returns the current authentication token. Called from
+            <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry> <function>pam_get_authtok</function> will
+            ask the user to confirm the new token by retyping it. If
+            a prompt was specified, "Retype" will be used as prefix.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_OLDAUTHTOK</term>
+        <listitem>
+          <para>
+            Returns the previous authentication token when changing
+            authentication tokens.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_get_authtok-options">
+    <title>OPTIONS</title>
+    <para>
+      <function>pam_get_authtok</function> honours the following module
+      options:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>try_first_pass</option>
+        </term>
+        <listitem>
+          <para>
+            Before prompting the user for their password, the module first
+            tries the previous stacked module's password in case that
+            satisfies this module as well.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>use_first_pass</option>
+        </term>
+        <listitem>
+          <para>
+            The argument <option>use_first_pass</option> forces the module
+            to use a previous stacked modules password and will never prompt
+            the user - if no password is available or the password is not
+            appropriate, the user will be denied access.
+          </para>
+        </listitem>
+      </varlistentry>
+       <varlistentry>
+        <term>
+          <option>use_authtok</option>
+        </term>
+        <listitem>
+          <para>
+            When password changing enforce the module to set the new
+            token to the one provided by a previously stacked
+            <option>password</option> module. If no token is available
+            token changing will fail.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+
+  <refsect1 id="pam_get_authtok-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_AUTH_ERR</term>
+        <listitem>
+           <para>
+             Authentication token could not be retrieved.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_AUTHTOK_ERR</term>
+        <listitem>
+           <para>
+             New authentication could not be retrieved.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             Authentication token was successful retrieved.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SYSTEM_ERR</term>
+        <listitem>
+           <para>
+             No space for an authentication token was provided.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_TRY_AGAIN</term>
+        <listitem>
+           <para>
+             New authentication tokens mismatch.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_get_authtok-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_get_authtok-standards'>
+    <title>STANDARDS</title>
+    <para>
+      The <function>pam_get_authtok</function> function is a Linux-PAM
+      extensions.
+    </para>
+  </refsect1>
+
+</refentry>