summaryrefslogtreecommitdiff
path: root/Linux-PAM/doc/modules/pam_cracklib.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'Linux-PAM/doc/modules/pam_cracklib.sgml')
-rw-r--r--Linux-PAM/doc/modules/pam_cracklib.sgml304
1 files changed, 304 insertions, 0 deletions
diff --git a/Linux-PAM/doc/modules/pam_cracklib.sgml b/Linux-PAM/doc/modules/pam_cracklib.sgml
new file mode 100644
index 00000000..de1d5df2
--- /dev/null
+++ b/Linux-PAM/doc/modules/pam_cracklib.sgml
@@ -0,0 +1,304 @@
+<!--
+ $Id: pam_cracklib.sgml,v 1.1.1.2 2002/09/15 20:08:28 hartmans Exp $
+
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
+ long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com>
+-->
+
+<sect1>Cracklib pluggable password strength-checker
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+
+pam_cracklib
+
+<tag><bf>Author:</bf></tag>
+
+Cristian Gafton &lt;gafton@redhat.com&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+
+Author.
+
+<tag><bf>Management groups provided:</bf></tag>
+
+password
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+
+Requires the system library <tt/libcrack/ and a system dictionary:
+<tt>/usr/lib/cracklib_dict</tt>.
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module can be plugged into the <tt/password/ stack of a given
+application to provide some plug-in strength-checking for passwords.
+
+<p>
+This module works in the following manner: it first calls the
+<em>Cracklib</em> routine to check the strength of the password; if
+crack likes the password, the module does an additional set of
+strength checks. These checks are:
+<itemize>
+
+<item> <bf/Palindrome/ -
+
+Is the new password a palindrome of the old one?
+
+<item> <bf/Case Change Only/ -
+
+Is the new password the the old one with only a change of case?
+
+<item> <bf/Similar/ -
+
+Is the new password too much like the old one? This is primarily
+controlled by one argument, <tt/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, <tt/difignore/ is available. This argument can
+be used to specify the minimum length a new password needs to be
+before the <tt/difok/ value is ignored. The default value for
+<tt/difignore/ is 23.
+
+
+<item> <bf/Simple/ -
+
+Is the new password too small? This is controlled by 5 arguments
+<tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and
+<tt/ocredit/. See the section on the arguments for the details of how
+these work and there defaults.
+
+<item> <bf/Rotated/ -
+
+Is the new password a rotated version of the old password?
+
+<item> <bf/Already used/ -
+
+Was the password used in the past? Previously used passwords are to
+be found in /etc/security/opasswd.
+
+</itemize>
+
+<p>
+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.
+
+<sect2>Password component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+
+<tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/;
+<tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/;
+<tt/use_authtok/;
+
+<tag><bf>Description:</bf></tag>
+
+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.
+
+<p>
+The default 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.
+
+<p>
+The default action may be modified in a number of ways using the
+arguments recognized by the module:
+<itemize>
+
+<item> <tt/debug/ -
+
+this option makes the module write information to syslog(3) indicating
+the behavior of the module (this option does <bf/not/ write password
+information to the log file).
+
+<item> <tt/type=XXX/ -
+
+the default action is for the module to use the following prompts when
+requesting passwords: ``New UNIX password: '' and ``Retype UNIX
+password: ''. Using this option you can replace the word UNIX with
+<tt/XXX/.
+
+<item> <tt/retry=N/ -
+
+the default number of times this module will request a new password
+(for strength-checking) from the user is 1. Using this argument this
+can be increased to <tt/N/.
+
+<item> <tt/difok=N/ -
+
+This argument will change the default of 10 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.
+
+<item> <tt/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 (<em>other,
+upper, lower</em> and <em/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
+<em>Cracklib</em> 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 <tt>minlen</tt>. If you want to allow passwords as short
+as 5 characters you should either not use this module or recompile
+the crack library and then recompile this module.
+
+<item> <tt/dcredit=N/ -
+
+(N >= 0) This is the maximum credit for having digits in the new password. If
+you have less than or <tt/N/ digits, each digit will count +1 towards
+meeting the current <tt/minlen/ value. The default for <tt/dcredit/
+is 1 which is the recommended value for <tt/minlen/ less than 10.
+(N < 0) This is the minimum number of digits that must be met for a new
+password.
+
+<item> <tt/ucredit=N/ -
+
+(N >= 0) This is the maximum credit for having upper case letters in the new
+password. If you have less than or <tt/N/ upper case letters each
+letter will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/ucredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10. (N < 0) This is the minimum number of upper
+case letters that must be met for a new password.
+
+<item> <tt/lcredit=N/ -
+
+(N >= 0) This is the maximum credit for having lower case letters in the new
+password. If you have less than or <tt/N/ lower case letters, each
+letter will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/lcredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10. (N < 0) This is the minimum number of lower
+case letters that must be met for a new password.
+
+<item> <tt/ocredit=N/ -
+
+(N >= 0) This is the maximum credit for having other characters in the new
+password. If you have less than or <tt/N/ other characters, each
+character will count +1 towards meeting the current <tt/minlen/ value.
+The default for <tt/ocredit/ is 1 which is the recommended value for
+<tt/minlen/ less than 10. (N < 0) This is the minimum number of other
+characters that must be met for a new password.
+
+<item> <tt/use_authtok/ -
+
+This argument is used to <em/force/ the module to not prompt the user
+for a new password but use the one provided by the previously stacked
+<tt/password/ module.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+<p>
+For an example of the use of this module, we show how it may be
+stacked with the password component of <tt/pam_pwdb/:
+<tscreen>
+<verb>
+#
+# 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_pwdb 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_pwdb.so use_authtok
+</verb>
+</tscreen>
+
+<p>
+Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the
+case that you want to use md5 password encryption:
+<tscreen>
+<verb>
+#%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_pwdb.so use_authtok nullok md5
+</verb>
+</tscreen>
+
+<p>
+And here is another example in case you don't want to use credits:
+<tscreen>
+<verb>
+#%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
+</verb>
+</tscreen>
+
+<p>
+In this example we simply say that the password must have a minimum
+length of 8:
+<tscreen>
+<verb>
+#%PAM-1.0
+#
+# These lines require the user to select a password with a mimimum
+# length of 8. He gets no credits and he is not forced to use
+# digit numbers, upper case letters etc.
+#
+password required pam_cracklib.so \
+ dcredit=0 ucredit=0 ocredit=0 lcredit=0 minlen=8
+password required pam_pwdb.so use_authtok nullok md5
+</verb>
+</tscreen>
+
+</descrip>
+
+<!--
+End of sgml insert for this module.
+-->