Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------
2008-11-28  Tomas Mraz <t8m@centrum.cz>

        * modules/pam_tally2/pam_tally2.c (tally_check): Fix info format
        to be the same as in pam_tally.

        * configure.in: Add modules/pam_timestamp/Makefile.
        * doc/sag/Linux-PAM_SAG.xml: Include pam_timestamp.xml.
        * doc/sag/pam_timestamp.xml: New.
        * libpam/pam_static_modules.h: Add pam_timestamp static struct.
        * modules/Makefile.am: Add pam_timestamp directory.
        * modules/pam_timestamp/Makefile.am: New.
        * modules/pam_timestamp/README.xml: New.
        * modules/pam_timestamp/hmacsha1.h: New.
        * modules/pam_timestamp/sha1.h: New.
        * modules/pam_timestamp/pam_timestamp.8.xml: New.
        * modules/pam_timestamp/pam_timestamp_check.8.xml: New.
        * modules/pam_timestamp/pam_timestamp.c: New.
        * modules/pam_timestamp/pam_timestamp_check.c: New.
        * modules/pam_timestamp/hmacfile.c: New.
        * modules/pam_timestamp/hmacsha1.c: New.
        * modules/pam_timestamp/sha1.c: New.
        * modules/pam_timestamp/tst-pam_timestamp: New.
        * po/POTFILES.in: Add pam_timestamp sources.
        * po/*.po: Regenerate.
        * po/cs.po: Updated translations.

1 files changed, 208 insertions, 0 deletions

diff --git a/modules/pam_timestamp/pam_timestamp_check.8.xml b/modules/pam_timestamp/pam_timestamp_check.8.xml
new file mode 100644
index 00000000..85484a06
--- /dev/null
+++ b/modules/pam_timestamp/pam_timestamp_check.8.xml
@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_timestamp_check">
+
+  <refmeta>
+    <refentrytitle>pam_timestamp_check</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_timestamp_check-name">
+    <refname>pam_timestamp_check</refname>
+    <refpurpose>Check to see if the default timestamp is valid</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_timestamp_check-cmdsynopsis">
+      <command>pam_timestamp_check</command>
+      <arg choice="opt">
+	-k
+      </arg>
+      <arg choice="opt">
+        -d
+      </arg>
+      <arg choice="opt">
+        <replaceable>target_user</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_timestamp_check-description">
+
+    <title>DESCRIPTION</title>
+
+    <para>
+      With no arguments <command>pam_timestamp_check</command> will check to
+see if the default timestamp is valid, or optionally remove it.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_timestamp_check-options">
+
+    <title>OPTIONS</title>
+    <variablelist>
+      <varlistentry>
+         <term>
+            <option>-k</option>
+         </term>
+         <listitem>
+            <para>
+               Instead of checking the validity of a timestamp, remove it.
+               This is analogous to sudo's <emphasis>-k</emphasis> option.
+            </para>
+         </listitem>
+      </varlistentry>
+      <varlistentry>
+         <term>
+            <option>-d</option>
+         </term>
+         <listitem>
+            <para>
+               Instead of returning validity using an exit status,
+               loop indefinitely, polling regularly and printing the status on
+               standard output.
+            </para>
+         </listitem>
+      </varlistentry>
+      <varlistentry>
+         <term>
+            <option><replaceable>target_user</replaceable></option>
+         </term>
+         <listitem>
+            <para>
+               By default <command>pam_timestamp_check</command> checks or removes
+               timestamps generated by <emphasis>pam_timestamp</emphasis> when
+               the user authenticates as herself. When the user authenticates as a
+               different user, the name of the timestamp file changes to
+               accomodate this. <replaceable>target_user</replaceable> allows
+               to specify this user name.
+            </para>
+         </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_timestamp_check-return_values'>
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>
+            The timestamp is valid.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>2</term>
+        <listitem>
+          <para>
+            The binary is not setuid root.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>3</term>
+        <listitem>
+          <para>
+            Invalid invocation.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>4</term>
+        <listitem>
+          <para>
+            User is unknown.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>5</term>
+        <listitem>
+          <para>
+            Permissions error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>6</term>
+        <listitem>
+          <para>
+            Invalid controlling tty.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>7</term>
+        <listitem>
+          <para>
+            Timestamp is not valid.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_timestamp-notes'>
+    <title>NOTES</title>
+    <para>
+      Users can get confused when they are not always asked for passwords when
+running a given program. Some users reflexively begin typing information before
+noticing that it is not being asked for.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_timestamp-examples'>
+    <title>EXAMPLES</title>
+    <programlisting>
+auth sufficient pam_timestamp.so verbose
+auth required   pam_unix.so
+
+session required pam_unix.so
+session optional pam_timestamp.so
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id="pam_timestamp-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/var/run/sudo/...</filename></term>
+        <listitem>
+          <para>timestamp files and directories</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_timestamp-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>pam_timestamp_check</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_timestamp-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_tally was written by Nalin Dahyabhai.
+      </para>
+  </refsect1>
+
+</refentry>
+