summaryrefslogtreecommitdiff
path: root/modules/pam_cracklib/pam_cracklib.8
diff options
context:
space:
mode:
Diffstat (limited to 'modules/pam_cracklib/pam_cracklib.8')
-rw-r--r--modules/pam_cracklib/pam_cracklib.8363
1 files changed, 363 insertions, 0 deletions
diff --git a/modules/pam_cracklib/pam_cracklib.8 b/modules/pam_cracklib/pam_cracklib.8
new file mode 100644
index 00000000..9727e294
--- /dev/null
+++ b/modules/pam_cracklib/pam_cracklib.8
@@ -0,0 +1,363 @@
+'\" t
+.\" Title: pam_cracklib
+.\" Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 06/18/2013
+.\" Manual: Linux-PAM Manual
+.\" Source: Linux-PAM Manual
+.\" Language: English
+.\"
+.TH "PAM_CRACKLIB" "8" "06/18/2013" "Linux-PAM Manual" "Linux\-PAM Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+pam_cracklib \- PAM module to check the password against dictionary words
+.SH "SYNOPSIS"
+.HP \w'\fBpam_cracklib\&.so\fR\ 'u
+\fBpam_cracklib\&.so\fR [\fI\&.\&.\&.\fR]
+.SH "DESCRIPTION"
+.PP
+This module can be plugged into the
+\fIpassword\fR
+stack of a given application to provide some plug\-in strength\-checking for passwords\&.
+.PP
+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\&.
+.PP
+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\&.
+.PP
+The strength checks works in the following manner: at first the
+\fBCracklib\fR
+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:
+.PP
+Palindrome
+.RS 4
+Is the new password a palindrome?
+.RE
+.PP
+Case Change Only
+.RS 4
+Is the new password the the old one with only a change of case?
+.RE
+.PP
+Similar
+.RS 4
+Is the new password too much like the old one? This is primarily controlled by one argument,
+\fBdifok\fR
+which is a number of character changes (inserts, removals, or replacements) between the old and new password that are enough to accept the new password\&. This defaults to 5 changes\&.
+.RE
+.PP
+Simple
+.RS 4
+Is the new password too small? This is controlled by 6 arguments
+\fBminlen\fR,
+\fBmaxclassrepeat\fR,
+\fBdcredit\fR,
+\fBucredit\fR,
+\fBlcredit\fR, and
+\fBocredit\fR\&. See the section on the arguments for the details of how these work and there defaults\&.
+.RE
+.PP
+Rotated
+.RS 4
+Is the new password a rotated version of the old password?
+.RE
+.PP
+Same consecutive characters
+.RS 4
+Optional check for same consecutive characters\&.
+.RE
+.PP
+Too long monotonic character sequence
+.RS 4
+Optional check for too long monotonic character sequence\&.
+.RE
+.PP
+Contains user name
+.RS 4
+Optional check whether the password contains the user\*(Aqs name in some form\&.
+.RE
+.PP
+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\&.
+.SH "OPTIONS"
+.PP
+.PP
+\fBdebug\fR
+.RS 4
+This option makes the module write information to
+\fBsyslog\fR(3)
+indicating the behavior of the module (this option does not write password information to the log file)\&.
+.RE
+.PP
+\fBauthtok_type=\fR\fB\fIXXX\fR\fR
+.RS 4
+The default action is for the module to use the following prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: "\&. The example word
+\fIUNIX\fR
+can be replaced with this option, by default it is empty\&.
+.RE
+.PP
+\fBretry=\fR\fB\fIN\fR\fR
+.RS 4
+Prompt user at most
+\fIN\fR
+times before returning with error\&. The default is
+\fI1\fR\&.
+.RE
+.PP
+\fBdifok=\fR\fB\fIN\fR\fR
+.RS 4
+This argument will change the default of
+\fI5\fR
+for the number of character changes in the new password that differentiate it from the old password\&.
+.RE
+.PP
+\fBminlen=\fR\fB\fIN\fR\fR
+.RS 4
+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 (\fIother\fR,
+\fIupper\fR,
+\fIlower\fR
+and
+\fIdigit\fR)\&. The default for this parameter is
+\fI9\fR
+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
+\fICracklib\fR
+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
+\fBminlen\fR\&. If you want to allow passwords as short as 5 characters you should not use this module\&.
+.RE
+.PP
+\fBdcredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having digits in the new password\&. If you have less than or
+\fIN\fR
+digits, each digit will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBdcredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of digits that must be met for a new password\&.
+.RE
+.PP
+\fBucredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having upper case letters in the new password\&. If you have less than or
+\fIN\fR
+upper case letters each letter will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBucredit\fR
+is
+\fI1\fR
+which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of upper case letters that must be met for a new password\&.
+.RE
+.PP
+\fBlcredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having lower case letters in the new password\&. If you have less than or
+\fIN\fR
+lower case letters, each letter will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBlcredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of lower case letters that must be met for a new password\&.
+.RE
+.PP
+\fBocredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having other characters in the new password\&. If you have less than or
+\fIN\fR
+other characters, each character will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBocredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of other characters that must be met for a new password\&.
+.RE
+.PP
+\fBminclass=\fR\fB\fIN\fR\fR
+.RS 4
+The minimum number of required classes of characters for the new password\&. The default number is zero\&. The four classes are digits, upper and lower letters and other characters\&. The difference to the
+\fBcredit\fR
+check is that a specific class if of characters is not required\&. Instead
+\fIN\fR
+out of four of the classes are required\&.
+.RE
+.PP
+\fBmaxrepeat=\fR\fB\fIN\fR\fR
+.RS 4
+Reject passwords which contain more than N same consecutive characters\&. The default is 0 which means that this check is disabled\&.
+.RE
+.PP
+\fBmaxsequence=\fR\fB\fIN\fR\fR
+.RS 4
+Reject passwords which contain monotonic character sequences longer than N\&. The default is 0 which means that this check is disabled\&. Examples of such sequence are \*(Aq12345\*(Aq or \*(Aqfedcb\*(Aq\&. Note that most such passwords will not pass the simplicity check unless the sequence is only a minor part of the password\&.
+.RE
+.PP
+\fBmaxclassrepeat=\fR\fB\fIN\fR\fR
+.RS 4
+Reject passwords which contain more than N consecutive characters of the same class\&. The default is 0 which means that this check is disabled\&.
+.RE
+.PP
+\fBreject_username\fR
+.RS 4
+Check whether the name of the user in straight or reversed form is contained in the new password\&. If it is found the new password is rejected\&.
+.RE
+.PP
+\fBgecoscheck\fR
+.RS 4
+Check whether the words from the GECOS field (usualy full name of the user) longer than 3 characters in straight or reversed form are contained in the new password\&. If any such word is found the new password is rejected\&.
+.RE
+.PP
+\fBenforce_for_root\fR
+.RS 4
+The module will return error on failed check also if the user changing the password is root\&. This option is off by default which means that just the message about the failed check is printed but root can change the password anyway\&. Note that root is not asked for an old password so the checks that compare the old and new password are not performed\&.
+.RE
+.PP
+\fBuse_authtok\fR
+.RS 4
+This argument is used to
+\fIforce\fR
+the module to not prompt the user for a new password but use the one provided by the previously stacked
+\fIpassword\fR
+module\&.
+.RE
+.PP
+\fBdictpath=\fR\fB\fI/path/to/dict\fR\fR
+.RS 4
+Path to the cracklib dictionaries\&.
+.RE
+.SH "MODULE TYPES PROVIDED"
+.PP
+Only the
+\fBpassword\fR
+module type is provided\&.
+.SH "RETURN VALUES"
+.PP
+.PP
+PAM_SUCCESS
+.RS 4
+The new password passes all checks\&.
+.RE
+.PP
+PAM_AUTHTOK_ERR
+.RS 4
+No new password was entered, the username could not be determined or the new password fails the strength checks\&.
+.RE
+.PP
+PAM_AUTHTOK_RECOVERY_ERR
+.RS 4
+The old password was not supplied by a previous stacked module or got not requested from the user\&. The first error can happen if
+\fBuse_authtok\fR
+is specified\&.
+.RE
+.PP
+PAM_SERVICE_ERR
+.RS 4
+A internal error occurred\&.
+.RE
+.SH "EXAMPLES"
+.PP
+For an example of the use of this module, we show how it may be stacked with the password component of
+\fBpam_unix\fR(8)
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#
+# 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
+
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Another example (in the
+/etc/pam\&.d/passwd
+format) is for the case that you want to use md5 password encryption:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#%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 \e
+ difok=3 minlen=15 dcredit= 2 ocredit=2
+password required pam_unix\&.so use_authtok nullok md5
+
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+And here is another example in case you don\*(Aqt want to use credits:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#%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 \e
+ dcredit=\-1 ucredit=\-1 ocredit=\-1 lcredit=0 minlen=8
+password required pam_unix\&.so use_authtok nullok md5
+
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "SEE ALSO"
+.PP
+\fBpam.conf\fR(5),
+\fBpam.d\fR(5),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_cracklib was written by Cristian Gafton <gafton@redhat\&.com>