1PAM_PWQUALITY(8) Linux-PAM Manual PAM_PWQUALITY(8)
2
6 pam_pwquality - PAM module to perform password quality checking
7
9 pam_pwquality.so [...]
10
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 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 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 The checks for strength are:
28 Palindrome
30 Is the new password a palindrome?
31 Case Change Only
33 Is the new password the same as the old one with only a change of
34 case?
35 Similar
37 Is the new password too much like the old one? This is primarily
38 controlled by one argument, difok which is a number of character
39 changes (inserts, removals, or replacements) between the old and
40 new password that are enough to accept the new password.
41 Simple
43 Is the new password too small? This is controlled by 6 arguments
44 minlen, maxclassrepeat, dcredit, ucredit, lcredit, and ocredit. See
45 the section on the arguments for the details of how these work and
46 there defaults.
47 Rotated
49 Is the new password a rotated version of the old password?
50 Same consecutive characters
52 Optional check for same consecutive characters.
53 Too long monotonic character sequence
55 Optional check for too long monotonic character sequence.
56 Contains user name
58 Check whether the password contains the user's name in some form.
59 Dictionary check
61 The Cracklib routine is called to check if the password is part of
62 a dictionary.
63 These checks are configurable either by use of the module arguments or
65 by modifying the /etc/security/pwquality.conf configuration file. The
66 module arguments override the settings in the configuration file.
67
69 debug
70 This option makes the module write information to syslog(3)
71 indicating the behavior of the module (this option does not write
72 password information to the log file).
73 authtok_type=XXX
75 The default action is for the module to use the following prompts
76 when requesting passwords: "New UNIX password: " and "Retype UNIX
77 password: ". The example word UNIX can be replaced with this
78 option, by default it is empty.
79 retry=N
81 Prompt user at most N times before returning with error. The
82 default is 1.
83 difok=N
85 This argument will change the default of 1 for the number of
86 changes in the new password from the old password.
87 The special value of 0 disables all checks of similarity of the new
89 password with the old password except the new password being
90 exactly the same as the old one.
91 minlen=N
93 The minimum acceptable size for the new password (plus one if
94 credits are not disabled which is the default). In addition to the
95 number of characters in the new password, credit (of +1 in length)
96 is given for each different kind of character (other, upper, lower
97 and digit). The default for this parameter is 8. Note that there is
98 a pair of length limits also in Cracklib, which is used for
99 dictionary checking, a "way too short" limit of 4 which is hard
100 coded in and a build time defined limit (6) that will be checked
101 without reference to minlen.
102 dcredit=N
104 (N >= 0) This is the maximum credit for having digits in the new
105 password. If you have less than or N digits, each digit will count
106 +1 towards meeting the current minlen value. The default for
107 dcredit is 0 which means there is no bonus for digits in password.
108 (N < 0) This is the minimum number of digits that must be met for a
110 new password.
111 ucredit=N
113 (N >= 0) This is the maximum credit for having upper case letters
114 in the new password. If you have less than or N upper case
115 letters, each upper case letter will count +1 towards meeting the
116 current minlen value. The default for ucredit is 0 which means
117 there is no bonus for upper case letters in password.
118 (N < 0) This is the minimum number of upper case letters that must
120 be met for a new password.
121 lcredit=N
123 (N >= 0) This is the maximum credit for having lower case letters
124 in the new password. If you have less than or N lower case
125 letters, each lower case letter will count +1 towards meeting the
126 current minlen value. The default for lcredit is 0 which means
127 there is no bonus for lower case letters in password.
128 (N < 0) This is the minimum number of lower case letters that must
130 be met for a new password.
131 ocredit=N
133 (N >= 0) This is the maximum credit for having other characters in
134 the new password. If you have less than or N other characters,
135 each other character will count +1 towards meeting the current
136 minlen value. The default for ocredit is 0 which means there is no
137 bonus for other characters in password.
138 (N < 0) This is the minimum number of other characters that must be
140 met for a new password.
141 minclass=N
143 The minimum number of required classes of characters for the new
144 password. The four classes are digits, upper and lower letters and
145 other characters. The difference to the credit check is that a
146 specific class if of characters is not required. Instead N out of
147 four of the classes are required. By default the check is disabled.
148 maxrepeat=N
150 Reject passwords which contain more than N same consecutive
151 characters. The default is 0 which means that this check is
152 disabled.
153 maxsequence=N
155 Reject passwords which contain monotonic character sequences longer
156 than N. The default is 0 which means that this check is disabled.
157 Examples of such sequence are '12345' or 'fedcb'. Note that most
158 such passwords will not pass the simplicity check unless the
159 sequence is only a minor part of the password.
160 maxclassrepeat=N
162 Reject passwords which contain more than N consecutive characters
163 of the same class. The default is 0 which means that this check is
164 disabled.
165 gecoscheck=N
167 If nonzero, check whether the individual words longer than 3
168 characters from the passwd(5) GECOS field of the user are contained
169 in the new password. The default is 0 which means that this check
170 is disabled.
171 dictcheck=N
173 If nonzero, check whether the password (with possible
174 modifications) matches a word in a dictionary. Currently the
175 dictionary check is performed using the cracklib library. The
176 default is 1 which means that this check is enabled.
177 usercheck=N
179 If nonzero, check whether the password (with possible
180 modifications) contains the user name in some form. The default is
181 1 which means that this check is enabled. It is not performed for
182 user names shorter than 3 characters.
183 usersubstr=N
185 If greater than 3 (due to the minimum length in usercheck), check
186 whether the password contains a substring of the user name of at
187 least N length in some form. The default is 0, which means this
188 check is disabled.
189 enforcing=N
191 If nonzero, reject the password if it fails the checks, otherwise
192 only print the warning. The default is 1 which means that the weak
193 password is rejected (for non-root users).
194 badwords=<list of words>
196 The words more than 3 characters long from this space separated
197 list are individually searched for and forbidden in the new
198 password. By default the list is empty which means that this check
199 is disabled.
200 dictpath=/path/to/dict
202 This options allows for specification of non-default path to the
203 cracklib dictionaries.
204 enforce_for_root
206 The module will return error on failed check even if the user
207 changing the password is root. This option is off by default which
208 means that just the message about the failed check is printed but
209 root can change the password anyway. Note that root is not asked
210 for an old password so the checks that compare the old and new
211 password are not performed.
212 local_users_only
214 The module will not test the password quality for users that are
215 not present in the /etc/passwd file. The module still asks for the
216 password so the following modules in the stack can use the
217 use_authtok option. This option is off by default.
218 use_authtok
220 This argument is used to force the module to not prompt the user
221 for a new password but use the one provided by the previously
222 stacked password module.
223
225 Only the password module type is provided.
226
228 PAM_SUCCESS
229 The new password passes all checks.
230 PAM_AUTHTOK_ERR
232 No new password was entered, the username could not be determined
233 or the new password fails the strength checks.
234 PAM_AUTHTOK_RECOVERY_ERR
236 The old password was not supplied by a previous stacked module or
237 got not requested from the user. The first error can happen if
238 use_authtok is specified.
239 PAM_SERVICE_ERR
241 A internal error occurred.
242
244 For an example of the use of this module, we show how it may be stacked
245 with the password component of pam_unix(8).
246 #
248 # These lines stack two password type modules. In this example the
249 # user is given 3 opportunities to enter a strong password. The
250 # "use_authtok" argument ensures that the pam_unix module does not
251 # prompt for a password, but instead uses the one provided by
252 # pam_pwquality.
253 #
254 password required pam_pwquality.so retry=3
255 password required pam_unix.so use_authtok
256 Another example is for the case that you want to use sha256 password
258 encryption:
259 #
261 # These lines allow modern systems to support passwords of at least 14
262 # bytes with extra credit of 2 for digits and 2 for others the new
263 # password must have at least three bytes that are not present in the
264 # old password
265 #
266 password required pam_pwquality.so \
267 difok=3 minlen=15 dcredit=2 ocredit=2
268 password required pam_unix.so use_authtok nullok sha256
269 And here is another example in case you don't want to use credits:
271 #
273 # These lines require the user to select a password with a minimum
274 # length of 8 and with at least 1 digit number, 1 upper case letter,
275 # and 1 other character
276 #
277 password required pam_pwquality.so \
278 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
279 password required pam_unix.so use_authtok nullok sha256
280
282 pwscore(1), pwquality.conf(5), pam_pwquality(8), pam.conf(5), PAM(8)
283
285 Tomas Mraz <tmraz@redhat.com>
286 Original author of pam_cracklib module Cristian Gafton
288 <gafton@redhat.com>
289Red Hat, Inc. 2022-11-18 PAM_PWQUALITY(8)