Relevant BUGIDs:

Purpose of commit: cleanup

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

Merge manual pages and sgml docu as xml, update them.

2006-02-12  Thorsten Kukuk  <kukuk@thkukuk.de>

        * configure.in: Add doc/man/Makefile.
        * Make.xml.rules: Enable xincludes for manual pages.
        * doc/Makefile.am (EXRA_DIST): Remove manual pages.
        (SUBDIR): Add man subdirectory.
        * doc/man/Makefile.am: New.
        * doc/man/pam_acct_mgmt.3: New.
        * doc/man/pam_acct_mgmt.3.xml: New.
        * doc/man/pam_get_data.3: New.
        * doc/man/pam_get_data.3.xml: New.
        * doc/man/pam_set_data.3: New.
        * doc/man/pam_set_data.3.xml: New.
        * doc/man/pam.8.xml: New.
        * doc/man/pam.8: Regenerated from xml file.
        * doc/man/pam_authenticate.3.xml: New.
        * doc/man/pam_authenticate.3: Regenerated from xml file.
        * doc/man/pam_chauthtok.3.xml: New.
        * doc/man/pam_chauthtok.3: Regenerated from xml file.
        * doc/man/pam_close_session.3.xml: New.
        * doc/man/pam_close_session.3: Regenerated from xml file.
        * doc/man/pam_end.3.xml: New.
        * doc/man/pam_end.3: Regenerated from xml file.
        * doc/man/pam_fail_delay.3.xml: New.
        * doc/man/pam_fail_delay.3: Regenerated from xml file.
        * doc/man/pam_get_item.3.xml: New.
        * doc/man/pam_get_item.3: Regenerated from xml file.
        * doc/man/pam_item_types.inc.xml: New.
        * doc/man/pam_open_session.3.xml: New.
        * doc/man/pam_open_session.3: Regenerated from xml file.
        * doc/man/pam_set_item.3.xml: New.
        * doc/man/pam_set_item.3: Regenerated from xml file.
        * doc/man/pam_setcred.3.xml: New.
        * doc/man/pam_setcred.3: Regenerated from xml file.
        * doc/man/pam_start.3.xml: New.
        * doc/man/pam_start.3: Regenerated from xml file.
        * doc/man/pam_strerror.3.xml: New.
        * doc/man/pam_strerror.3: Regenerated from xml file.
        * doc/man/template-man: Removed.

1 files changed, 175 insertions, 0 deletions

diff --git a/doc/man/pam_fail_delay.3.xml b/doc/man/pam_fail_delay.3.xml
new file mode 100644
index 00000000..86d1fff4
--- /dev/null
+++ b/doc/man/pam_fail_delay.3.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!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_fail_delay">
+
+  <refmeta>
+    <refentrytitle>pam_fail_delay</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_fail_delay-name">
+    <refname>pam_fail_delay</refname>
+    <refpurpose>request a delay on failure</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv id="pam_fail_delay-synopsis">
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+      <funcprototype>
+        <funcdef>int <function>pam_fail_delay</function></funcdef>
+        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+        <paramdef>unsigned int <parameter>usec</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id='pam_fail_delay-description'>
+    <title>DESCRIPTION</title>
+    <para>
+      The <function>pam_fail_delay</function> function provides a
+      mechanism by which an application or module can suggest a minimum
+      delay of <emphasis>usec</emphasis> micro-seconds. The
+      function  keeps a record of the longest time requested with this
+      function. Should
+      <citerefentry>
+        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> fail, the failing return to the application is
+      delayed by an amount of time randomly distributed (by up to 25%)
+      about this longest value.
+    </para>
+    <para>
+      Independent of success, the delay time is reset to its zero
+      default value when the PAM service module returns control to
+      the application. The delay occurs <emphasis>after</emphasis> all
+      authentication modules have been called, but <emphasis>before</emphasis>
+      control is returned to the service application.
+    </para>
+    <para>
+      When using this function the application programmer should check if
+      it is available with:
+    </para>
+      <programlisting>
+#ifdef PAM_FAIL_DELAY
+    ....
+#endif /* PAM_FAIL_DELAY */
+      </programlisting>
+
+    <para>
+      For applications written with a single thread that are event
+      driven in nature, generating this delay may be undesirable.
+      Instead, the application may want to register the delay in some
+      other way. For example, in a single threaded server that serves
+      multiple authentication requests from a single event loop, the
+      application might want to simply mark a given connection as
+      blocked until an application timer expires. For this reason
+      the delay function can be changed with the
+      <emphasis>PAM_FAIL_DELAY</emphasis> item. It can be queried and
+      set with
+      <citerefentry>
+        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+      and
+      <citerefentry>
+        <refentrytitle>pam_set_item </refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>  respectively. The value used to set it should be
+      a function pointer of the following prototype:
+      <programlisting>
+void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
+      </programlisting>
+      The arguments being the <emphasis>retval</emphasis> return code
+      of the module stack, the <emphasis>usec_delay</emphasis>
+      micro-second delay that libpam is requesting and the
+      <emphasis>appdata_ptr</emphasis> that the application has associated
+      with the current <emphasis>pamh</emphasis>. This last value was set
+      by the application when it called
+      <citerefentry>
+        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> or explicitly with
+      <citerefentry>
+        <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+      Note, if PAM_FAIL_DELAY is unset (or set to NULL), then no delay
+      will be performed.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_fail_delay-rationale'>
+    <title>RATIONALE</title>
+    <para>
+      It is often possible to attack an authentication scheme by exploiting
+      the time it takes the scheme to deny access to an applicant user.  In
+      cases of <emphasis>short</emphasis> timeouts, it may prove possible
+      to attempt a <emphasis>brute force</emphasis> dictionary attack --
+      with an automated process, the attacker tries all possible passwords
+      to gain access to the system. In other cases, where individual
+      failures can take measurable amounts of time (indicating the nature
+      of the failure), an attacker can obtain useful information about the
+      authentication process. These latter attacks make use of procedural
+      delays that constitute a <emphasis>covert channel</emphasis>
+      of useful information.
+    </para>
+    <para>
+      To minimize the effectiveness of such attacks, it is desirable to
+      introduce a random delay in a failed authentication process.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_fail_delay-example'>
+    <title>EXAMPLE</title>
+    <para>
+      For example, a login application may require a failure delay of
+      roughly 3 seconds. It will contain the following code:
+    </para>
+    <programlisting>
+    pam_fail_delay (pamh, 3000000 /* micro-seconds */ );
+    pam_authenticate (pamh, 0);
+    </programlisting>
+
+    <para>
+      if the modules do not request a delay, the failure delay will be
+      between 2.25 and 3.75 seconds.
+    </para>
+
+    <para>
+      However, the modules, invoked in the authentication process, may
+      also request delays:
+    </para>
+
+    <programlisting>
+module #1:    pam_fail_delay (pamh, 2000000);
+module #2:    pam_fail_delay (pamh, 4000000);
+    </programlisting>
+
+    <para>
+      in this case, it is the largest requested value that is used to
+      compute the actual failed delay: here between 3 and 5 seconds.
+    </para>
+  </refsect1>
+
+<refsect1 id='return_value'><title>RETURN VALUE</title>
+<para>Following a successful call to
+<citerefentry><refentrytitle>pam_fail_delay</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <emphasis remap='B'>PAM_SUCCESS</emphasis>
+is returned.  All other returns should be considered serious failures.</para>
+
+</refsect1>
+
+  <refsect1 id='pam_fail_delay-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+</refentry>