Relevant BUGIDs:

Purpose of commit: regression fix

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

2009-11-10  Thorsten Kukuk  <kukuk@suse.de>

        * doc/man/pam_get_authtok.3.xml: Document pam_get_authtok_noverify
        and pam_get_authtok_verify.

        * libpam/Makefile.am (libpam_la_LDFLAGS): Bump revesion of libpam.

        * libpam/pam_get_authtok.c (pam_get_authtok_internal): Renamed
        from pam_get_authtok, add flags argument, always check return
        values.

        * modules/pam_cracklib/pam_cracklib.c (pam_sm_chauthtok): Use
        pam_get_authtok_noverify and pam_get_authtok_verify.

        * libpam/include/security/pam_ext.h: Add prototypes for
        pam_get_authtok_noverify and pam_get_authtok_verify.

        * libpam/libpam.map: Add new pam_get_authtok_* functions.

4 files changed, 45 insertions, 1 deletions

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 9b229b16..dc2cf009 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -12,7 +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_authtok.3 pam_get_data.3 pam_get_item.3 pam_get_user.3 \
+	pam_get_authtok.3 pam_get_authtok_noverify.3 pam_get_authtok_verify.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 \
diff --git a/doc/man/pam_get_authtok.3.xml b/doc/man/pam_get_authtok.3.xml
index 0e816350..f2a1d6e9 100644
--- a/doc/man/pam_get_authtok.3.xml
+++ b/doc/man/pam_get_authtok.3.xml
@@ -27,6 +27,18 @@
         <paramdef>const char **<parameter>authtok</parameter></paramdef>
         <paramdef>const char *<parameter>prompt</parameter></paramdef>
       </funcprototype>
+      <funcprototype>
+        <funcdef>int <function>pam_get_authtok_noverify</function></funcdef>
+        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+        <paramdef>const char **<parameter>authtok</parameter></paramdef>
+        <paramdef>const char *<parameter>prompt</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+        <funcdef>int <function>pam_get_authtok_verify</function></funcdef>
+        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+        <paramdef>const char **<parameter>authtok</parameter></paramdef>
+        <paramdef>const char *<parameter>prompt</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -74,6 +86,35 @@
         </listitem>
       </varlistentry>
     </variablelist>
+    <para>
+      The <function>pam_get_authtok_noverify</function> function can
+      only be used for changing the password
+      (from <citerefentry>
+        <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>). It returns the cached
+      authentication token, or prompts the user if no token is
+      currently cached. The difference to <function>pam_get_authtok</function>
+      is, that this function does not ask a second time for the password
+      to verify it. 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 <function>pam_get_authtok_verify</function> function can
+      only be used to verify a password for mistypes gotten by
+     <citerefentry>
+        <refentrytitle>pam_get_authtok_noverify</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>. This function asks a second time for the password
+      and verify it with the password provided by <emphasis>authtok</emphasis>
+      argument. In case of an error, the value of <emphasis>authtok</emphasis>
+      is undefined. Else this argument will point to the
+      <emphasis>actual</emphasis> data and should
+      <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
+      over-written!
+    </para>
   </refsect1>
 
   <refsect1 id="pam_get_authtok-options">
diff --git a/doc/man/pam_get_authtok_noverify.3 b/doc/man/pam_get_authtok_noverify.3
new file mode 100644
index 00000000..a990dbc4
--- /dev/null
+++ b/doc/man/pam_get_authtok_noverify.3
@@ -0,0 +1 @@
+.so man3/pam_get_authtok.3
diff --git a/doc/man/pam_get_authtok_verify.3 b/doc/man/pam_get_authtok_verify.3
new file mode 100644
index 00000000..a990dbc4
--- /dev/null
+++ b/doc/man/pam_get_authtok_verify.3
@@ -0,0 +1 @@
+.so man3/pam_get_authtok.3