Debian Codegraph @

doc/man/pam_pwquality.8

raw
1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{\
60 . if \nF \{\
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{\
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\" ========================================================================
72 .\"
73 .IX Title "PAM_PWQUALITY 8"
74 .TH PAM_PWQUALITY 8 "2022-11-18" "Red Hat, Inc." "Linux-PAM Manual"
75 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
76 .\" way too many mistakes in technical documents.
77 .if n .ad l
78 .nh
79 .SH "NAME"
80 pam_pwquality \- PAM module to perform password quality checking
81 .SH "SYNOPSIS"
82 .IX Header "SYNOPSIS"
83 \&\fBpam_pwquality.so\fR [\fI...\fR]
84 .SH "DESCRIPTION"
85 .IX Header "DESCRIPTION"
86 This module can be plugged into the \fBpassword\fR stack of a given service
87 to provide some plug-in strength-checking for passwords.
88 The code was originally based on pam_cracklib module and the module is
89 backwards compatible with its options.
90 .PP
91 The action of this module is to prompt the user for a password and check
92 its strength against a system dictionary and a set of rules for identifying
93 poor choices.
94 .PP
95 The first action is to prompt for a single password, check its strength
96 and then, if it is considered strong, prompt for the password a second time
97 (to verify that it was typed correctly on the first occasion). All being
98 well, the password is passed on to subsequent modules to be installed as the
99 new authentication token.
100 .PP
101 The checks for strength are:
102 .IP "Palindrome" 4
103 .IX Item "Palindrome"
104 Is the new password a palindrome?
105 .IP "Case Change Only" 4
106 .IX Item "Case Change Only"
107 Is the new password the same as the old one with only a change of case?
108 .IP "Similar" 4
109 .IX Item "Similar"
110 Is the new password too much like the old one? This is primarily controlled
111 by one argument, \fBdifok\fR which is a number of character changes (inserts,
112 removals, or replacements) between the old and new password that are enough
113 to accept the new password.
114 .IP "Simple" 4
115 .IX Item "Simple"
116 Is the new password too small? This is controlled by 6 arguments
117 \&\fBminlen\fR, \fBmaxclassrepeat\fR, \fBdcredit\fR, \fBucredit\fR, \fBlcredit\fR,
118 and \fBocredit\fR. See the section on the arguments for the details of how
119 these work and there defaults.
120 .IP "Rotated" 4
121 .IX Item "Rotated"
122 Is the new password a rotated version of the old password?
123 .IP "Same consecutive characters" 4
124 .IX Item "Same consecutive characters"
125 Optional check for same consecutive characters.
126 .IP "Too long monotonic character sequence" 4
127 .IX Item "Too long monotonic character sequence"
128 Optional check for too long monotonic character sequence.
129 .IP "Contains user name" 4
130 .IX Item "Contains user name"
131 Check whether the password contains the user's name in some form.
132 .IP "Dictionary check" 4
133 .IX Item "Dictionary check"
134 The \fICracklib\fR routine is called to check if the password is part of
135 a dictionary.
136 .PP
137 These checks are configurable either by use of the module arguments
138 or by modifying the \fI/etc/security/pwquality.conf\fR configuration file. The
139 module arguments override the settings in the configuration file.
140 .SH "OPTIONS"
141 .IX Header "OPTIONS"
142 .IP "\fBdebug\fR" 4
143 .IX Item "debug"
144 This option makes the module write information to \fBsyslog\fR\|(3)
145 indicating the behavior of the module (this option does not write password
146 information to the log file).
147 .IP "\fBauthtok_type=\fR\fI\s-1XXX\s0\fR" 4
148 .IX Item "authtok_type=XXX"
149 The default action is for the module to use the following prompts when
150 requesting passwords: \f(CW"New UNIX password: "\fR and
151 \&\f(CW"Retype UNIX password: "\fR. The example word
152 \&\fI\s-1UNIX\s0\fR can be replaced with this option, by default it is empty.
153 .IP "\fBretry=\fR\fIN\fR" 4
154 .IX Item "retry=N"
155 Prompt user at most \fIN\fR times before returning with error. The default is
156 \&\fI1\fR.
157 .IP "\fBdifok=\fR\fIN\fR" 4
158 .IX Item "difok=N"
159 This argument will change the default of \fI1\fR for the number of changes in
160 the new password from the old password.
161 .Sp
162 The special value of \fI0\fR disables all checks of similarity of the new password
163 with the old password except the new password being exactly the same as
164 the old one.
165 .IP "\fBminlen=\fR\fIN\fR" 4
166 .IX Item "minlen=N"
167 The minimum acceptable size for the new password (plus one if credits are not
168 disabled which is the default). In addition to the number of characters in
169 the new password, credit (of +1 in length) is given for each different kind
170 of character (\fIother\fR, \fIupper\fR, \fIlower\fR and \fIdigit\fR). The default for this
171 parameter is \fI8\fR. Note that there is a pair of length limits also in
172 \&\fICracklib\fR, which is used for dictionary checking, a \*(L"way too short\*(R" limit
173 of \fI4\fR which is hard coded in and a build time defined limit (\fI6\fR) that will
174 be checked without reference to \fBminlen\fR.
175 .IP "\fBdcredit=\fR\fIN\fR" 4
176 .IX Item "dcredit=N"
177 (N >= 0) This is the maximum credit for having digits in the new password.
178 If you have less than or \fIN\fR digits, each digit will count +1 towards meeting
179 the current \fBminlen\fR value. The default for \fBdcredit\fR is \fI0\fR
180 which means there is no bonus for digits in password.
181 .Sp
182 (N < 0) This is the minimum number of digits that must be met for a new
183 password.
184 .IP "\fBucredit=\fR\fIN\fR" 4
185 .IX Item "ucredit=N"
186 (N >= 0) This is the maximum credit for having upper case letters in the new password.
187 If you have less than or \fIN\fR upper case letters, each upper case letter will count +1 towards meeting
188 the current \fBminlen\fR value. The default for \fBucredit\fR is \fI0\fR
189 which means there is no bonus for upper case letters in password.
190 .Sp
191 (N < 0) This is the minimum number of upper case letters that must be met for a new
192 password.
193 .IP "\fBlcredit=\fR\fIN\fR" 4
194 .IX Item "lcredit=N"
195 (N >= 0) This is the maximum credit for having lower case letters in the new password.
196 If you have less than or \fIN\fR lower case letters, each lower case letter will count +1 towards meeting
197 the current \fBminlen\fR value. The default for \fBlcredit\fR is \fI0\fR
198 which means there is no bonus for lower case letters in password.
199 .Sp
200 (N < 0) This is the minimum number of lower case letters that must be met for a new
201 password.
202 .IP "\fBocredit=\fR\fIN\fR" 4
203 .IX Item "ocredit=N"
204 (N >= 0) This is the maximum credit for having other characters in the new password.
205 If you have less than or \fIN\fR other characters, each other character will count +1 towards meeting
206 the current \fBminlen\fR value. The default for \fBocredit\fR is \fI0\fR
207 which means there is no bonus for other characters in password.
208 .Sp
209 (N < 0) This is the minimum number of other characters that must be met for a new
210 password.
211 .IP "\fBminclass=\fR\fIN\fR" 4
212 .IX Item "minclass=N"
213 The minimum number of required classes of characters for the new password.
214 The four classes are digits, upper and lower letters and other characters.
215 The difference to the \fBcredit\fR check is that a specific class if of
216 characters is not required. Instead \fIN\fR out of four of the classes are
217 required. By default the check is disabled.
218 .IP "\fBmaxrepeat=\fR\fIN\fR" 4
219 .IX Item "maxrepeat=N"
220 Reject passwords which contain more than \fIN\fR same consecutive characters.
221 The default is 0 which means that this check is disabled.
222 .IP "\fBmaxsequence=\fR\fIN\fR" 4
223 .IX Item "maxsequence=N"
224 Reject passwords which contain monotonic character sequences longer than \fIN\fR.
225 The default is 0 which means that this check is disabled.
226 Examples of such sequence are '12345' or 'fedcb'. Note that
227 most such passwords will not pass the simplicity check unless the sequence
228 is only a minor part of the password.
229 .IP "\fBmaxclassrepeat=\fR\fIN\fR" 4
230 .IX Item "maxclassrepeat=N"
231 Reject passwords which contain more than \fIN\fR consecutive characters of the
232 same class. The default is 0 which means that this check is disabled.
233 .IP "\fBgecoscheck=\fR\fIN\fR" 4
234 .IX Item "gecoscheck=N"
235 If nonzero, check whether the individual words longer than 3 characters
236 from the \fBpasswd\fR\|(5) \s-1GECOS\s0 field of the user are contained in the new
237 password. The default is 0 which means that this check is disabled.
238 .IP "\fBdictcheck=\fR\fIN\fR" 4
239 .IX Item "dictcheck=N"
240 If nonzero, check whether the password (with possible modifications)
241 matches a word in a dictionary. Currently the dictionary check is performed
242 using the \fIcracklib\fR library. The default is 1 which means that this check
243 is enabled.
244 .IP "\fBusercheck=\fR\fIN\fR" 4
245 .IX Item "usercheck=N"
246 If nonzero, check whether the password (with possible modifications)
247 contains the user name in some form. The default is 1 which means that
248 this check is enabled. It is not performed for user names shorter
249 than 3 characters.
250 .IP "\fBusersubstr=\fR\fIN\fR" 4
251 .IX Item "usersubstr=N"
252 If greater than 3 (due to the minimum length in usercheck), check whether the
253 password contains a substring of the user name of at least \fIN\fR length in some form.
254 The default is 0, which means this check is disabled.
255 .IP "\fBenforcing=\fR\fIN\fR" 4
256 .IX Item "enforcing=N"
257 If nonzero, reject the password if it fails the checks, otherwise
258 only print the warning. The default is 1 which means that the weak password
259 is rejected (for non-root users).
260 .IP "\fBbadwords=\fR\fI<list of words>\fR" 4
261 .IX Item "badwords=<list of words>"
262 The words more than 3 characters long from this space separated list are
263 individually searched for and forbidden in the new password.
264 By default the list is empty which means that this check is disabled.
265 .IP "\fBdictpath=\fR\fI/path/to/dict\fR" 4
266 .IX Item "dictpath=/path/to/dict"
267 This options allows for specification of non-default path to the cracklib
268 dictionaries.
269 .IP "\fBenforce_for_root\fR" 4
270 .IX Item "enforce_for_root"
271 The module will return error on failed check even if the user changing the
272 password is root. This option is off by default which means that just
273 the message about the failed check is printed but root can change
274 the password anyway. Note that root is not asked for an old password
275 so the checks that compare the old and new password are not performed.
276 .IP "\fBlocal_users_only\fR" 4
277 .IX Item "local_users_only"
278 The module will not test the password quality for users that are not present
279 in the \fI/etc/passwd\fR file. The module still asks for the password so
280 the following modules in the stack can use the \fBuse_authtok\fR option.
281 This option is off by default.
282 .IP "\fBuse_authtok\fR" 4
283 .IX Item "use_authtok"
284 This argument is used to \fIforce\fR the module to not prompt the user for
285 a new password but use the one provided by the previously stacked
286 \&\fBpassword\fR module.
287 .SH "MODULE TYPES PROVIDED"
288 .IX Header "MODULE TYPES PROVIDED"
289 Only the \fBpassword\fR module type is provided.
290 .SH "RETURN VALUES"
291 .IX Header "RETURN VALUES"
292 .IP "\s-1PAM_SUCCESS\s0" 4
293 .IX Item "PAM_SUCCESS"
294 The new password passes all checks.
295 .IP "\s-1PAM_AUTHTOK_ERR\s0" 4
296 .IX Item "PAM_AUTHTOK_ERR"
297 No new password was entered, the username could not be determined or the
298 new password fails the strength checks.
299 .IP "\s-1PAM_AUTHTOK_RECOVERY_ERR\s0" 4
300 .IX Item "PAM_AUTHTOK_RECOVERY_ERR"
301 The old password was not supplied by a previous stacked module or got not
302 requested from the user. The first error can happen if \fBuse_authtok\fR
303 is specified.
304 .IP "\s-1PAM_SERVICE_ERR\s0" 4
305 .IX Item "PAM_SERVICE_ERR"
306 A internal error occurred.
307 .SH "EXAMPLES"
308 .IX Header "EXAMPLES"
309 For an example of the use of this module, we show how it may be stacked
310 with the password component of \fBpam_unix\fR\|(8).
311 .PP
312 .Vb 9
313 \& #
314 \& # These lines stack two password type modules. In this example the
315 \& # user is given 3 opportunities to enter a strong password. The
316 \& # "use_authtok" argument ensures that the pam_unix module does not
317 \& # prompt for a password, but instead uses the one provided by
318 \& # pam_pwquality.
319 \& #
320 \& password required pam_pwquality.so retry=3
321 \& password required pam_unix.so use_authtok
322 .Ve
323 .PP
324 Another example is for the case that you want to use sha256 password
325 encryption:
326 .PP
327 .Vb 9
328 \& #
329 \& # These lines allow modern systems to support passwords of at least 14
330 \& # bytes with extra credit of 2 for digits and 2 for others the new
331 \& # password must have at least three bytes that are not present in the
332 \& # old password
333 \& #
334 \& password required pam_pwquality.so \e
335 \& difok=3 minlen=15 dcredit=2 ocredit=2
336 \& password required pam_unix.so use_authtok nullok sha256
337 .Ve
338 .PP
339 And here is another example in case you don't want to use credits:
340 .PP
341 .Vb 8
342 \& #
343 \& # These lines require the user to select a password with a minimum
344 \& # length of 8 and with at least 1 digit number, 1 upper case letter,
345 \& # and 1 other character
346 \& #
347 \& password required pam_pwquality.so \e
348 \& dcredit=\-1 ucredit=\-1 ocredit=\-1 lcredit=0 minlen=8
349 \& password required pam_unix.so use_authtok nullok sha256
350 .Ve
351 .SH "SEE ALSO"
352 .IX Header "SEE ALSO"
353 \&\fBpwscore\fR\|(1), \fBpwquality.conf\fR\|(5), \fBpam_pwquality\fR\|(8),
354 \&\fBpam.conf\fR\|(5), \s-1\fBPAM\s0\fR\|(8)
355 .SH "AUTHORS"
356 .IX Header "AUTHORS"
357 Tomas Mraz <[email protected]>
358 .PP
359 Original author of \fBpam_cracklib\fR module Cristian Gafton <[email protected]>