.\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .de FN \fI\|\\$1\|\fP .. .TH PAM_PWQUALITY 8 "10 Nov 2011" "Red Hat, Inc." .SH NAME pam_pwquality \- PAM module to perform password quality checking .SH SYNOPSIS \fBpam_pwquality\&.so\fR [\fI\&.\&.\&.\fR] .SH DESCRIPTION .PP This module can be plugged into the \fIpassword\fR stack of a given service to provide some plug\-in strength\-checking for passwords\&. The code was originally based on pam_cracklib module and the module is backwards compatible with its options\&. .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 These checks are configurable either by use of the module arguments or by modifying the \fB/etc/security/pwquality.conf\fR configuration file. .PD .SH OPTIONS .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 changes in the new password 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 \&. Note that there is a pair of length limits also in \fICracklib\fR, which is used for dictionary checking, a "way too short" limit of 4 which is hard coded in and a build time defined limit (6) that will be checked without reference to \fBminlen\fR\&. .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 \fBgecoscheck=\fR\fB\fIN\fR\fR .RS 4 If nonzero, check whether the individual words longer than 3 characters from the \fBpasswd GECOS\fR field of the user are contained in the new password\&. The default is 0 which means that this check is disabled\&. .RE .PP \fBbadwords=\fR\fB\fI\fR\fR .RS 4 The words more than 3 characters long from this space separated list are individually searched for and forbidden in the new password\&. By default the list is empty which means that this check is disabled\&. .RE .PP \fBenforce_for_root\fR .RS 4 The module will return error on failed check even 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 \fBlocal_users_only\fR .RS 4 The module will not test the password quality for users that are not present in the \fI/etc/passwd\fR file\&. The module still asks for the password so the following modules in the stack can use the \fBuse_authtok\fR option\&. This option is off by default\&. .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 .PD .SH "MODULE TYPES PROVIDED" .PP Only the \fBpassword\fR module type is provided\&. .PD .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_pwquality\&. # passwd password required pam_pwquality\&.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_pwquality\&.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\'t 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_pwquality\&.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 .PD .SH "SEE ALSO" pwscore(1), pwquality.conf(5), pam_pwquality(8), pam.conf(5), PAM(8) .SH AUTHORS .nf Tomas Mraz Original author of pam_cracklib module Cristian Gafton .fi