Relevant BUGIDs:

Purpose of commit: new feature

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

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

        * configure.in: Check for text browser.
        * Make.xml.rules: Add rule to generate README from README.xml.

        * modules/pam_access/Makefile.am: Include Make.xml.rules.
        * modules/pam_access/README: Regenerated from README.xml.
        * modules/pam_access/README.xml: New.
        * modules/pam_access/access.conf: Extended by new examples.
        * modules/pam_access/access.conf.5: New, generated from xml file.
        * modules/pam_access/access.conf.5.xml: New.
        * modules/pam_access/pam_access.8: New, generated from xml file.
        * modules/pam_access/pam_access.8.xml: New.
        * modules/pam_access/pam_access.c: Add rules for IPv6 and
        netmasks.
        Based on patch from Mike Becher <Mike.Becher@lrz-muenchen.de>.

        * modules/pam_deny/Makefile.am: Include Make.xml.rules.
        * modules/pam_deny/pam_deny.8.xml: New.
        * modules/pam_deny/pam_deny.8: New, generated from xml file.
        * modules/pam_deny/README.xml: New.
        * modules/pam_deny/README: Regenerated from xml file.

        * modules/pam_cracklib/Makefile.am: Include Make.xml.rules.
        * modules/pam_cracklib/pam_cracklib.8.xml: New.
        * modules/pam_cracklib/pam_cracklib.8: New, generated from xml file.
        * modules/pam_cracklib/README.xml: New.
        * modules/pam_cracklib/README: Regenerated from xml file.

        * modules/pam_exec/Makefile.am: Add rule to generate README.
        * modules/pam_exec/README: Regenerated from xml file.
        * modules/pam_exec/pam_exec.8: Regenerated from xml file.
        * modules/pam_exec/pam_exec.8.xml: Syntax files.

4 files changed, 750 insertions, 29 deletions

diff --git a/modules/pam_cracklib/Makefile.am b/modules/pam_cracklib/Makefile.am
index c1f6a8f4..b5aeda1b 100644
--- a/modules/pam_cracklib/Makefile.am
+++ b/modules/pam_cracklib/Makefile.am
@@ -1,10 +1,13 @@
 #
-# Copyright (c) 2005 Thorsten Kukuk <kukuk@suse.de>
+# Copyright (c) 2005, 2006 Thorsten Kukuk <kukuk@suse.de>
 #
 
 CLEANFILES = *~
 
-EXTRA_DIST = README
+EXTRA_DIST = README README.xml $(MANS) $(XMLS)
+
+man_MANS = pam_cracklib.8
+man_XMLS = pam_cracklib.8.xml
 
 securelibdir = $(SECUREDIR)
 secureconfdir = $(SCONFIGDIR)
@@ -21,3 +24,13 @@ securelib_LTLIBRARIES = pam_cracklib.la
 endif
 
 pam_cracklib_la_LIBADD = @LIBCRACK@ @LIBCRYPT@
+
+if ENABLE_REGENERATE_MAN
+
+noinst_DATA = README
+
+README: pam_cracklib.8.xml
+
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_cracklib/README b/modules/pam_cracklib/README
index eea980eb..756b7f48 100644
--- a/modules/pam_cracklib/README
+++ b/modules/pam_cracklib/README
@@ -1,40 +1,212 @@
+pam_cracklib — PAM module to check the password against dictionary words
 
-pam_cracklib:
-	check the passwd against dictionary words.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-RECOGNIZED ARGUMENTS:
-	debug		verbose log
+DESCRIPTION
 
-	type=XXX	alter the message printed as a prompt to the user.
-			the message printed is in the form
-			"New XXX password: ".
-			Default XXX=UNIX
+This module can be plugged into the password stack of a given application to
+provide some plug-in strength-checking for passwords.
 
-	retry=N		Prompt user at most N times before returning with
-			error. Default N=1.
+The action of this module is to prompt the user for a password and check its
+strength against a system dictionary and a set of rules for identifying poor
+choices.
 
-	difok=N         How many characters can be the same in the new
-			password relative to the old
-	difignore=N	How many characters long should the password be
-			before we ignore difok.
+The first action is to prompt for a single password, check its strength and
+then, if it is considered strong, prompt for the password a second time (to
+verify that it was typed correctly on the first occasion). All being well, the
+password is passed on to subsequent modules to be installed as the new
+authentication token.
 
-	minlen=N	The minimum simplicity count for a good password.
+The strength checks works in the following manner: at first the Cracklib
+routine is called to check if the password is part of a dictionary; if this is
+not the case an additional set of strength checks is done. These checks are:
 
-	dcredit=N
-	ucredit=N
-	lcredit=N
-	ocredit=N 	Weight, digits, upper, lower, other characters with
-			count N. Use these values to compute the
-			'unsimplicity' of the password.
+Palindrome
 
-	use_authtok	Get the proposed password from PAM_AUTHTOK
+    Is the new password a palindrome of the old one?
 
-	dictpath=<path> Path to the cracklib dictionaries.
+Case Change Only
 
+    Is the new password the the old one with only a change of case?
 
-MODULE SERVICES PROVIDED:
-	passwd		chauthtok
+Similar
 
-AUTHOR:
-	Cristian Gafton <gafton@redhat.com>
+    Is the new password too much like the old one? This is primarily controlled
+    by one argument, difok which is a number of characters that if different
+    between the old and new are enough to accept the new password, this
+    defaults to 10 or 1/2 the size of the new password whichever is smaller.
+
+    To avoid the lockup associated with trying to change a long and complicated
+    password, difignore is available. This argument can be used to specify the
+    minimum length a new password needs to be before the difok value is
+    ignored. The default value for difignore is 23.
+
+Simple
+
+    Is the new password too small? This is controlled by 5 arguments minlen,
+    dcredit, ucredit, lcredit, and ocredit. See the section on the arguments
+    for the details of how these work and there defaults.
+
+Rotated
+
+    Is the new password a rotated version of the old password?
+
+Already used
+
+    Was the password used in the past? Previously used passwords are to be
+    found in /etc/security/opasswd.
+
+This module with no arguments will work well for standard unix password
+encryption. With md5 encryption, passwords can be longer than 8 characters and
+the default settings for this module can make it hard for the user to choose a
+satisfactory new password. Notably, the requirement that the new password
+contain no more than 1/2 of the characters in the old password becomes a
+non-trivial constraint. For example, an old password of the form "the quick
+brown fox jumped over the lazy dogs" would be difficult to change... In
+addition, the default action is to allow passwords as small as 5 characters in
+length. For a md5 systems it can be a good idea to increase the required
+minimum size of a password. One can then allow more credit for different kinds
+of characters but accept that the new password may share most of these
+characters with the old password.
+
+OPTIONS
+
+debug
+
+    This option makes the module write information to syslog(3) indicating the
+    behavior of the module (this option does not write password information to
+    the log file).
+
+type=XXX
+
+    The default action is for the module to use the following prompts when
+    requesting passwords: "New UNIX password: " and "Retype UNIX password: ".
+    The default word UNIX can be replaced with this option.
+
+retry=N
+
+    Prompt user at most N times before returning with error. The default is 1
+
+difok=N
+
+    This argument will change the default of 5 for the number of characters in
+    the new password that must not be present in the old password. In addition,
+    if 1/2 of the characters in the new password are different then the new
+    password will be accepted anyway.
+
+difignore=N
+
+    How many characters should the password have before difok will be ignored.
+    The default is 23.
+
+minlen=N
+
+    The minimum acceptable size for the new password (plus one if credits are
+    not disabled which is the default). In addition to the number of characters
+    in the new password, credit (of +1 in length) is given for each different
+    kind of character (other, upper, lower and digit). The default for this
+    parameter is 9 which is good for a old style UNIX password all of the same
+    type of character but may be too low to exploit the added security of a md5
+    system. Note that there is a pair of length limits in Cracklib itself, a
+    "way too short" limit of 4 which is hard coded in and a defined limit (6)
+    that will be checked without reference to minlen. If you want to allow
+    passwords as short as 5 characters you should not use this module.
+
+dcredit=N
+
+    (N >= 0) This is the maximum credit for having digits in the new password.
+    If you have less than or N digits, each digit will count +1 towards meeting
+    the current minlen value. The default for dcredit is 1 which is the
+    recommended value for minlen less than 10.
+
+    (N < 0) This is the minimum number of digits that must be met for a new
+    password.
+
+ucredit=N
+
+    (N >= 0) This is the maximum credit for having upper case letters in the
+    new password. If you have less than or N upper case letters each letter
+    will count +1 towards meeting the current minlen value. The default for
+    ucredit is 1 which is the recommended value for minlen less than 10.
+
+    (N > 0) This is the minimum number of upper case letters that must be met
+    for a new password.
+
+lcredit=N
+
+    (N >= 0) This is the maximum credit for having lower case letters in the
+    new password. If you have less than or N lower case letters, each letter
+    will count +1 towards meeting the current minlen value. The default for
+    lcredit is 1 which is the recommended value for minlen less than 10.
+
+    (N < 0) This is the minimum number of lower case letters that must be met
+    for a new password.
+
+ocredit=N
+
+    (N >= 0) This is the maximum credit for having other characters in the new
+    password. If you have less than or N other characters, each character will
+    count +1 towards meeting the current minlen value. The default for ocredit
+    is 1 which is the recommended value for minlen less than 10.
+
+    (N < 0) This is the minimum number of other characters that must be met for
+    a new password.
+
+use_authtok
+
+    This argument is used to force the module to not prompt the user for a new
+    password but use the one provided by the previously stacked password
+    module.
+
+dictpath=/path/to/dict
+
+    Path to the cracklib dictionaries.
+
+EXAMPLES
+
+For an example of the use of this module, we show how it may be stacked with
+the password component of pam_unix(8)
+
+#
+# These lines stack two password type modules. In this example the
+# user is given 3 opportunities to enter a strong password. The
+# "use_authtok" argument ensures that the pam_unix module does not
+# prompt for a password, but instead uses the one provided by
+# pam_cracklib.
+#
+passwd  password required       pam_cracklib.so retry=3
+passwd  password required       pam_unix.so use_authtok
+
+
+Another example (in the /etc/pam.d/passwd format) is for the case that you want
+to use md5 password encryption:
+
+#%PAM-1.0
+#
+# These lines allow a md5 systems to support passwords of at least 14
+# bytes with extra credit of 2 for digits and 2 for others the new
+# password must have at least three bytes that are not present in the
+# old password
+#
+password  required pam_cracklib.so \
+               difok=3 minlen=15 dcredit= 2 ocredit=2
+password  required pam_unix.so use_authtok nullok md5
+
+
+And here is another example in case you don't want to use credits:
+
+#%PAM-1.0
+#
+# These lines require the user to select a password with a minimum
+# length of 8 and with at least 1 digit number, 1 upper case letter,
+# and 1 other character
+#
+password  required pam_cracklib.so \
+               dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
+password  required pam_pwdb.so use_authtok nullok md5
+
+
+AUTHOR
+
+pam_cracklib was written by Cristian Gafton <gafton@redhat.com>
 
diff --git a/modules/pam_cracklib/README.xml b/modules/pam_cracklib/README.xml
new file mode 100644
index 00000000..c4a7b54c
--- /dev/null
+++ b/modules/pam_cracklib/README.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamaccess SYSTEM "pam_cracklib.8.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_cracklib.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_cracklib-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_cracklib.8.xml" xpointer='xpointer(//refsect1[@id = "pam_cracklib-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_cracklib.8.xml" xpointer='xpointer(//refsect1[@id = "pam_cracklib-options"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_cracklib.8.xml" xpointer='xpointer(//refsect1[@id = "pam_cracklib-examples"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_cracklib.8.xml" xpointer='xpointer(//refsect1[@id = "pam_cracklib-author"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_cracklib/pam_cracklib.8.xml b/modules/pam_cracklib/pam_cracklib.8.xml
new file mode 100644
index 00000000..74c66e09
--- /dev/null
+++ b/modules/pam_cracklib/pam_cracklib.8.xml
@@ -0,0 +1,495 @@
+<?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_cracklib">
+
+  <refmeta>
+    <refentrytitle>pam_cracklib</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_cracklib-name">
+    <refname>pam_cracklib</refname>
+    <refpurpose>PAM module to check the password against dictionary words</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_cracklib-cmdsynopsis">
+      <command>pam_cracklib.so</command>
+      <arg choice="opt">
+        <replaceable>...</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_cracklib-description">
+
+    <title>DESCRIPTION</title>
+
+    <para>
+      This module can be plugged into the <emphasis>password</emphasis> stack of
+      a given application to provide some plug-in strength-checking for passwords.
+    </para>
+
+    <para>
+      The action of this module is to prompt the user for a password and
+      check its strength against a system dictionary and a set of rules for
+      identifying poor choices.
+    </para>
+
+    <para>
+      The first action is to prompt for a single password, check its
+      strength and then, if it is considered strong, prompt for the password
+      a second time (to verify that it was typed correctly on the first
+      occasion). All being well, the password is passed on to subsequent
+      modules to be installed as the new authentication token.
+    </para>
+
+    <para>
+      The strength checks works in the following manner: at first the
+      <function>Cracklib</function> routine is called to check if the password
+      is part of a dictionary; if this is not the case an additional set of
+      strength checks is done. These checks are:
+    </para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Palindrome</term>
+        <listitem>
+          <para>
+            Is the new password a palindrome of the old one?
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Case Change Only</term>
+        <listitem>
+          <para>
+            Is the new password the the old one with  only a change of case?
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Similar</term>
+        <listitem>
+          <para>
+            Is the new password too much like the old one?
+            This is primarily controlled by one argument,
+            <option>difok</option> which is a number of characters
+            that if different between the old and new are enough to accept
+            the new password, this defaults to 10 or 1/2 the size of the
+            new password whichever is smaller.
+          </para>
+          <para>
+            To avoid the lockup associated with trying to change a long and
+            complicated password, <option>difignore</option> is available.
+            This argument can be used to specify the minimum length a new
+            password needs to be before the <option>difok</option> value is
+            ignored. The default value for <option>difignore</option> is 23.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Simple</term>
+        <listitem>
+          <para>
+             Is the new password too small?
+             This is controlled by 5 arguments <option>minlen</option>,
+             <option>dcredit</option>, <option>ucredit</option>,
+             <option>lcredit</option>, and <option>ocredit</option>. See the section
+             on the arguments for the details of how these work and there defaults.
+           </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Rotated</term>
+        <listitem>
+          <para>
+            Is the new password a rotated version of the old password?
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Already used</term>
+        <listitem>
+          <para>
+            Was the password used in the past? Previously used passwords
+            are to be found in <filename>/etc/security/opasswd</filename>.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <para>
+      This module with no arguments will work well for standard unix
+      password encryption.  With md5 encryption, passwords can be longer
+      than 8 characters and the default settings for this module can make it
+      hard for the user to choose a satisfactory new password.  Notably, the
+      requirement that the new password contain no more than 1/2 of the
+      characters in the old password becomes a non-trivial constraint.  For
+      example, an old password of the form "the quick brown fox jumped over
+      the lazy dogs" would be difficult to change...  In addition, the
+      default action is to allow passwords as small as 5 characters in
+      length.  For a md5 systems it can be a good idea to increase the
+      required minimum size of a password.  One can then allow more credit
+      for different kinds of characters but accept that the new password may
+      share most of these characters with the old password.
+    </para>
+
+  </refsect1>
+
+  <refsect1 id="pam_cracklib-options">
+
+    <title>OPTIONS</title>
+    <para>
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <option>debug</option>
+          </term>
+          <listitem>
+            <para>
+              This option makes the module write information to
+              <citerefentry>
+                <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+              </citerefentry>
+              indicating the behavior of the module (this option does
+              not write password information to the log file).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>type=<replaceable>XXX</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              The default action is for the module to use the
+              following prompts when requesting passwords:
+              "New UNIX password: " and "Retype UNIX password: ".
+              The default word <emphasis>UNIX</emphasis> can
+              be replaced with this option.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>retry=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              Prompt user at most <replaceable>N</replaceable> times
+              before returning with error. The default is
+              <emphasis>1</emphasis>
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>difok=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              This argument will change the default of
+              <emphasis>5</emphasis> for the number of characters in
+              the new password that must not be present in the old
+              password. In addition, if 1/2 of the characters in the
+              new password are different then the new password will
+              be accepted anyway.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>difignore=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              How many characters should the password have before
+              difok will be ignored. The default is
+              <emphasis>23</emphasis>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>minlen=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              The minimum acceptable size for the new password (plus
+              one if credits are not disabled which is the default).
+              In addition to the number of characters in the new password,
+              credit (of +1 in length) is given for each different kind
+              of character (<emphasis>other</emphasis>,
+              <emphasis>upper</emphasis>, <emphasis>lower</emphasis> and
+              <emphasis>digit</emphasis>). The default for this parameter
+              is <emphasis>9</emphasis> which is good for a old style UNIX
+              password all of the same type of character but may be too low
+              to exploit the added security of a md5 system.  Note that
+              there is a pair of length limits in
+              <emphasis>Cracklib</emphasis> itself, a "way too short" limit
+              of 4 which is hard coded in and a defined limit (6) that will
+              be checked without reference to <option>minlen</option>.
+              If you want to allow passwords as short as 5 characters you
+              should not use this module.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>dcredit=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              (N &gt;= 0) This is the maximum credit for having digits in
+              the new password. If you have less than or
+              <replaceable>N</replaceable>
+              digits, each digit will count +1 towards meeting the current
+              <option>minlen</option> value. The default for
+              <option>dcredit</option> is 1 which is the recommended
+              value for <option>minlen</option> less than 10.
+            </para>
+            <para>
+              (N &lt; 0) This is the minimum number of digits that must
+              be met for a new password.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>ucredit=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              (N &gt;= 0) This is the maximum credit for having upper
+              case letters in the new password.  If you have less than
+              or <replaceable>N</replaceable> upper case letters each
+              letter will count +1 towards meeting the current
+              <option>minlen</option> value. The default for
+              <option>ucredit</option> is <emphasis>1</emphasis> which
+              is the recommended value for <option>minlen</option> less
+              than 10.
+            </para>
+            <para>
+              (N &gt; 0) This is the minimum number of upper
+              case letters that must be met for a new password.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>lcredit=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              (N &gt;= 0) This is the maximum credit for having
+              lower case letters in the new password. If you have
+              less than or <replaceable>N</replaceable> lower case
+              letters, each letter will count +1 towards meeting the
+              current <option>minlen</option> value. The default for
+              <option>lcredit</option> is 1 which is the recommended
+              value for <option>minlen</option> less than 10.
+            </para>
+            <para>
+             (N &lt; 0) This is the minimum number of lower
+             case letters that must be met for a new password.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>ocredit=<replaceable>N</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              (N &gt;= 0) This is the maximum credit for having other
+              characters in the new password. If you have less than or
+              <replaceable>N</replaceable> other characters, each
+              character will count +1 towards meeting the current
+              <option>minlen</option> value. The default for
+              <option>ocredit</option> is 1 which is the recommended
+              value for <option>minlen</option> less than 10.
+            </para>
+            <para>
+              (N &lt; 0) This is the minimum number of other
+              characters that must be met for a new password.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>use_authtok</option>
+          </term>
+          <listitem>
+            <para>
+              This argument is used to <emphasis>force</emphasis> the
+              module to not prompt the user for a new password but use
+              the one provided by the previously stacked
+              <emphasis>password</emphasis> module.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>dictpath=<replaceable>/path/to/dict</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              Path to the cracklib dictionaries.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_cracklib-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      Only he <option>password</option> service is supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_cracklib-return_values'>
+    <title>RETURN VALUES</title>
+    <para>
+      <variablelist>
+
+        <varlistentry>
+          <term>PAM_SUCCESS</term>
+          <listitem>
+            <para>
+              The new password passes all checks.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>PAM_AUTHTOK_ERR</term>
+          <listitem>
+            <para>
+              No new password was entered,
+              the username could not be determined or the new
+              password fails the strength checks.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>PAM_AUTHTOK_RECOVERY_ERR</term>
+          <listitem>
+            <para>
+              The old password was not supplied by a previous stackked
+              module or got not requested from the user.
+              The first error can happen if <option>use_authtok</option>
+              is specified.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>PAM_SERVICE_ERR</term>
+          <listitem>
+            <para>
+              A internal error occured.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_cracklib-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      For an example of the use of this module, we show how it may be
+      stacked with the password component of
+      <citerefentry>
+        <refentrytitle>pam_unix</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+      <programlisting>
+#
+# These lines stack two password type modules. In this example the
+# user is given 3 opportunities to enter a strong password. The
+# "use_authtok" argument ensures that the pam_unix module does not
+# prompt for a password, but instead uses the one provided by
+# pam_cracklib.
+#
+passwd  password required       pam_cracklib.so retry=3
+passwd  password required       pam_unix.so use_authtok
+      </programlisting>
+    </para>
+
+    <para>
+      Another example (in the <filename>/etc/pam.d/passwd</filename> format)
+      is for the case that you want to use md5 password encryption:
+      <programlisting>
+#%PAM-1.0
+#
+# These lines allow a md5 systems to support passwords of at least 14
+# bytes with extra credit of 2 for digits and 2 for others the new
+# password must have at least three bytes that are not present in the
+# old password
+#
+password  required pam_cracklib.so \
+               difok=3 minlen=15 dcredit= 2 ocredit=2
+password  required pam_unix.so use_authtok nullok md5
+      </programlisting>
+    </para>
+
+    <para>
+      And here is another example in case you don't want to use credits:
+      <programlisting>
+#%PAM-1.0
+#
+# These lines require the user to select a password with a minimum
+# length of 8 and with at least 1 digit number, 1 upper case letter,
+# and 1 other character
+#
+password  required pam_cracklib.so \
+               dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
+password  required pam_pwdb.so use_authtok nullok md5
+      </programlisting>
+    </para>
+
+  </refsect1>
+
+  <refsect1 id='pam_cracklib-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_cracklib-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_cracklib was written by Cristian Gafton &lt;gafton@redhat.com&gt;
+      </para>
+  </refsect1>
+
+</refentry>