diff options
Diffstat (limited to 'Linux-PAM/doc/modules/pam_cracklib.sgml')
| -rw-r--r-- | Linux-PAM/doc/modules/pam_cracklib.sgml | 304 |
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..d6fc0c56 --- /dev/null +++ b/Linux-PAM/doc/modules/pam_cracklib.sgml @@ -0,0 +1,304 @@ +<!-- + $Id: pam_cracklib.sgml,v 1.5 2001/12/08 18:56:47 agmorgan 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 <gafton@redhat.com> + +<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. +--> |