path: root/doc/man/pam_pwquality.8

.\" 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 originaly 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<list of words>\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 <tmraz@redhat\&.com>
Original author of pam_cracklib module Cristian Gafton <gafton@redhat\&.com>
.fi