path: root/modules/pam_cracklib/pam_cracklib.8

.\"     Title: pam_cracklib
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
.\"      Date: 06/16/2009
.\"    Manual: Linux-PAM Manual
.\"    Source: Linux-PAM Manual
.\"  Language: English
.\"
.TH "PAM_CRACKLIB" "8" "06/16/2009" "Linux-PAM Manual" "Linux\-PAM Manual"
.\" -----------------------------------------------------------------
.\" * (re)Define some macros
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" toupper - uppercase a string (locale-aware)
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de toupper
.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
\\$*
.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH-xref - format a cross-reference to an SH section
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de SH-xref
.ie n \{\
.\}
.toupper \\$*
.el \{\
\\$*
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SH - level-one heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SH
.\" put an extra blank line of space above the head in non-TTY output
.if t \{\
.sp 1
.\}
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[an-margin]u
.ti 0
.HTML-TAG ".NH \\n[an-level]"
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
\." make the size of the head bigger
.ps +3
.ft B
.ne (2v + 1u)
.ie n \{\
.\" if n (TTY output), use uppercase
.toupper \\$*
.\}
.el \{\
.nr an-break-flag 0
.\" if not n (not TTY), use normal case (not uppercase)
\\$1
.in \\n[an-margin]u
.ti 0
.\" if not n (not TTY), put a border/line under subheading
.sp -.6
\l'\n(.lu'
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" SS - level-two heading that works better for non-TTY output
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de1 SS
.sp \\n[PD]u
.nr an-level 1
.set-an-margin
.nr an-prevailing-indent \\n[IN]
.fi
.in \\n[IN]u
.ti \\n[SN]u
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.ps \\n[PS-SS]u
\." make the size of the head bigger
.ps +2
.ft B
.ne (2v + 1u)
.if \\n[.$] \&\\$*
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BB/BE - put background/screen (filled box) around block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BB
.if t \{\
.sp -.5
.br
.in +2n
.ll -2n
.gcolor red
.di BX
.\}
..
.de EB
.if t \{\
.if "\\$2"adjust-for-leading-newline" \{\
.sp -1
.\}
.br
.di
.in
.ll
.gcolor
.nr BW \\n(.lu-\\n(.i
.nr BH \\n(dn+.5v
.ne \\n(BHu+.5v
.ie "\\$2"adjust-for-leading-newline" \{\
\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.el \{\
\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
.\}
.in 0
.sp -.5v
.nf
.BX
.in
.sp .5v
.fi
.\}
..
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" BM/EM - put colored marker in margin next to block of text
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.de BM
.if t \{\
.br
.ll -2n
.gcolor red
.di BX
.\}
..
.de EM
.if t \{\
.br
.di
.ll
.gcolor
.nr BH \\n(dn
.ne \\n(BHu
\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
.in 0
.nf
.BX
.in
.fi
.\}
..
.\" -----------------------------------------------------------------
.\" * 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"
.fam C
.HP \w'\fBpam_cracklib\&.so\fR\ 'u
\fBpam_cracklib\&.so\fR [\fI\&.\&.\&.\fR]
.fam
.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 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\&.
.sp
To avoid the lockup associated with trying to change a long and complicated password,
\fBdifignore\fR
is available\&. This argument can be used to specify the minimum length a new password needs to be before the
\fBdifok\fR
value is ignored\&. The default value for
\fBdifignore\fR
is 23\&.
.RE
.PP
Simple
.RS 4
Is the new password too small? This is controlled by 5 arguments
\fBminlen\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
Contains user name
.RS 4
Optional check whether the password contains the user\'s 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 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\&.
.RE
.PP
\fBdifignore=\fR\fB\fIN\fR\fR
.RS 4
How many characters should the password have before difok will be ignored\&. The default is
\fI23\fR\&.
.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
\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
\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
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

#
# 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
      
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
Another example (in the
\FC/etc/pam\&.d/passwd\F[]
format) is for the case that you want to use md5 password encryption:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

#%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
      
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.if n \{\
.RE
.\}
.PP
And here is another example in case you don\'t want to use credits:
.sp
.if n \{\
.RS 4
.\}
.fam C
.ps -1
.nf
.if t \{\
.sp -1
.\}
.BB lightgray adjust-for-leading-newline
.sp -1

#%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
      
.EB lightgray adjust-for-leading-newline
.if t \{\
.sp 1
.\}
.fi
.fam
.ps +1
.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>