1PAM_PWQUALITY(8)               Linux-PAM Manual               PAM_PWQUALITY(8)
2
3
4

NAME

6       pam_pwquality - PAM module to perform password quality checking
7

SYNOPSIS

9       pam_pwquality.so [...]
10

DESCRIPTION

12       This module can be plugged into the password stack of a given service
13       to provide some plug-in strength-checking for passwords.  The code was
14       originally based on pam_cracklib module and the module is backwards
15       compatible with its options.
16
17       The action of this module is to prompt the user for a password and
18       check its strength against a system dictionary and a set of rules for
19       identifying poor choices.
20
21       The first action is to prompt for a single password, check its strength
22       and then, if it is considered strong, prompt for the password a second
23       time (to verify that it was typed correctly on the first occasion). All
24       being well, the password is passed on to subsequent modules to be
25       installed as the new authentication token.
26
27       The checks for strength are:
28
29       Palindrome
30           Is the new password a palindrome?
31
32       Case Change Only
33           Is the new password the the old one with only a change of case?
34
35       Similar
36           Is the new password too much like the old one? This is primarily
37           controlled by one argument, difok which is a number of character
38           changes (inserts, removals, or replacements) between the old and
39           new password that are enough to accept the new password.
40
41       Simple
42           Is the new password too small? This is controlled by 6 arguments
43           minlen, maxclassrepeat, dcredit, ucredit, lcredit, and ocredit. See
44           the section on the arguments for the details of how these work and
45           there defaults.
46
47       Rotated
48           Is the new password a rotated version of the old password?
49
50       Same consecutive characters
51           Optional check for same consecutive characters.
52
53       Too long monotonic character sequence
54           Optional check for too long monotonic character sequence.
55
56       Contains user name
57           Check whether the password contains the user's name in some form.
58
59       Dictionary check
60           The Cracklib routine is called to check if the password is part of
61           a dictionary.
62
63       These checks are configurable either by use of the module arguments or
64       by modifying the /etc/security/pwquality.conf configuration file. The
65       module arguments override the settings in the configuration file.
66

OPTIONS

68       debug
69           This option makes the module write information to syslog(3)
70           indicating the behavior of the module (this option does not write
71           password information to the log file).
72
73       authtok_type=XXX
74           The default action is for the module to use the following prompts
75           when requesting passwords: "New UNIX password: " and "Retype UNIX
76           password: ". The example word UNIX can be replaced with this
77           option, by default it is empty.
78
79       retry=N
80           Prompt user at most N times before returning with error. The
81           default is 1.
82
83       difok=N
84           This argument will change the default of 1 for the number of
85           changes in the new password from the old password.
86
87           The special value of 0 disables all checks of similarity of the new
88           password with the old password except the new password being
89           exactly the same as the old one.
90
91       minlen=N
92           The minimum acceptable size for the new password (plus one if
93           credits are not disabled which is the default). In addition to the
94           number of characters in the new password, credit (of +1 in length)
95           is given for each different kind of character (other, upper, lower
96           and digit). The default for this parameter is 8. Note that there is
97           a pair of length limits also in Cracklib, which is used for
98           dictionary checking, a "way too short" limit of 4 which is hard
99           coded in and a build time defined limit (6) that will be checked
100           without reference to minlen.
101
102       dcredit=N
103           (N >= 0) This is the maximum credit for having digits in the new
104           password.  If you have less than or N digits, each digit will count
105           +1 towards meeting the current minlen value. The default for
106           dcredit is 0 which means there is no bonus for digits in password.
107
108           (N < 0) This is the minimum number of digits that must be met for a
109           new password.
110
111       ucredit=N
112           (N >= 0) This is the maximum credit for having upper case letters
113           in the new password.  If you have less than or N upper case
114           letters, each upper case letter will count +1 towards meeting the
115           current minlen value. The default for ucredit is 0 which means
116           there is no bonus for upper case letters in password.
117
118           (N < 0) This is the minimum number of upper case letters that must
119           be met for a new password.
120
121       lcredit=N
122           (N >= 0) This is the maximum credit for having lower case letters
123           in the new password.  If you have less than or N lower case
124           letters, each lower case letter will count +1 towards meeting the
125           current minlen value. The default for lcredit is 0 which means
126           there is no bonus for lower case letters in password.
127
128           (N < 0) This is the minimum number of lower case letters that must
129           be met for a new password.
130
131       ocredit=N
132           (N >= 0) This is the maximum credit for having other characters in
133           the new password.  If you have less than or N other characters,
134           each other character will count +1 towards meeting the current
135           minlen value. The default for ocredit is 0 which means there is no
136           bonus for other characters in password.
137
138           (N < 0) This is the minimum number of other characters that must be
139           met for a new password.
140
141       minclass=N
142           The minimum number of required classes of characters for the new
143           password.  The four classes are digits, upper and lower letters and
144           other characters.  The difference to the credit check is that a
145           specific class if of characters is not required. Instead N out of
146           four of the classes are required. By default the check is disabled.
147
148       maxrepeat=N
149           Reject passwords which contain more than N same consecutive
150           characters.  The default is 0 which means that this check is
151           disabled.
152
153       maxsequence=N
154           Reject passwords which contain monotonic character sequences longer
155           than N.  The default is 0 which means that this check is disabled.
156           Examples of such sequence are '12345' or 'fedcb'. Note that most
157           such passwords will not pass the simplicity check unless the
158           sequence is only a minor part of the password.
159
160       maxclassrepeat=N
161           Reject passwords which contain more than N consecutive characters
162           of the same class. The default is 0 which means that this check is
163           disabled.
164
165       gecoscheck=N
166           If nonzero, check whether the individual words longer than 3
167           characters from the passwd(5) GECOS field of the user are contained
168           in the new password. The default is 0 which means that this check
169           is disabled.
170
171       dictcheck=N
172           If nonzero, check whether the password (with possible
173           modifications) matches a word in a dictionary. Currently the
174           dictionary check is performed using the cracklib library. The
175           default is 1 which means that this check is enabled.
176
177       usercheck=N
178           If nonzero, check whether the password (with possible
179           modifications) contains the user name in some form. The default is
180           1 which means that this check is enabled. It is not performed for
181           user names shorter than 3 characters.
182
183       usersubstr=N
184           If greater than 3 (due to the minimum length in usercheck), check
185           whether the password contains a substring of at least N length in
186           some form.  The default is 0, which means this check is disabled.
187
188       enforcing=N
189           If nonzero, reject the password if it fails the checks, otherwise
190           only print the warning. The default is 1 which means that the weak
191           password is rejected (for non-root users).
192
193       badwords=<list of words>
194           The words more than 3 characters long from this space separated
195           list are individually searched for and forbidden in the new
196           password.  By default the list is empty which means that this check
197           is disabled.
198
199       dictpath=/path/to/dict
200           This options allows for specification of non-default path to the
201           cracklib dictionaries.
202
203       enforce_for_root
204           The module will return error on failed check even if the user
205           changing the password is root. This option is off by default which
206           means that just the message about the failed check is printed but
207           root can change the password anyway. Note that root is not asked
208           for an old password so the checks that compare the old and new
209           password are not performed.
210
211       local_users_only
212           The module will not test the password quality for users that are
213           not present in the /etc/passwd file. The module still asks for the
214           password so the following modules in the stack can use the
215           use_authtok option.  This option is off by default.
216
217       use_authtok
218           This argument is used to force the module to not prompt the user
219           for a new password but use the one provided by the previously
220           stacked password module.
221

MODULE TYPES PROVIDED

223       Only the password module type is provided.
224

RETURN VALUES

226       PAM_SUCCESS
227           The new password passes all checks.
228
229       PAM_AUTHTOK_ERR
230           No new password was entered, the username could not be determined
231           or the new password fails the strength checks.
232
233       PAM_AUTHTOK_RECOVERY_ERR
234           The old password was not supplied by a previous stacked module or
235           got not requested from the user. The first error can happen if
236           use_authtok is specified.
237
238       PAM_SERVICE_ERR
239           A internal error occurred.
240

EXAMPLES

242       For an example of the use of this module, we show how it may be stacked
243       with the password component of pam_unix(8).
244
245        #
246        # These lines stack two password type modules. In this example the
247        # user is given 3 opportunities to enter a strong password. The
248        # "use_authtok" argument ensures that the pam_unix module does not
249        # prompt for a password, but instead uses the one provided by
250        # pam_pwquality.
251        #
252        password required pam_pwquality.so retry=3
253        password required pam_unix.so use_authtok
254
255       Another example is for the case that you want to use sha256 password
256       encryption:
257
258        #
259        # These lines allow modern systems to support passwords of at least 14
260        # bytes with extra credit of 2 for digits and 2 for others the new
261        # password must have at least three bytes that are not present in the
262        # old password
263        #
264        password required pam_pwquality.so \
265                      difok=3 minlen=15 dcredit=2 ocredit=2
266        password required pam_unix.so use_authtok nullok sha256
267
268       And here is another example in case you don't want to use credits:
269
270        #
271        # These lines require the user to select a password with a minimum
272        # length of 8 and with at least 1 digit number, 1 upper case letter,
273        # and 1 other character
274        #
275        password required pam_pwquality.so \
276                      dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
277        password required pam_unix.so use_authtok nullok sha256
278

SEE ALSO

280       pwscore(1), pwquality.conf(5), pam_pwquality(8), pam.conf(5), PAM(8)
281

AUTHORS

283       Tomas Mraz <tmraz@redhat.com>
284
285       Original author of pam_cracklib module Cristian Gafton
286       <gafton@redhat.com>
287
288
289
290Red Hat, Inc.                     2020-08-03                  PAM_PWQUALITY(8)
Impressum