Debian Codegraph @

doc/man/pam_pwquality.8.pod

raw
1 =pod
2
3 =head1 NAME
4
5 pam_pwquality - PAM module to perform password quality checking
6
7 =head1 SYNOPSIS
8
9 B<pam_pwquality.so> [I<...>]
10
11 =head1 DESCRIPTION
12
13 This module can be plugged into the B<password> stack of a given service
14 to provide some plug-in strength-checking for passwords.
15 The code was originally based on pam_cracklib module and the module is
16 backwards compatible with its options.
17
18 The action of this module is to prompt the user for a password and check
19 its strength against a system dictionary and a set of rules for identifying
20 poor choices.
21
22 The first action is to prompt for a single password, check its strength
23 and then, if it is considered strong, prompt for the password a second time
24 (to verify that it was typed correctly on the first occasion). All being
25 well, the password is passed on to subsequent modules to be installed as the
26 new authentication token.
27
28 The checks for strength are:
29
30 =over 4
31
32 =item Palindrome
33
34 Is the new password a palindrome?
35
36 =item Case Change Only
37
38 Is the new password the same as the old one with only a change of case?
39
40 =item Similar
41
42 Is the new password too much like the old one? This is primarily controlled
43 by one argument, B<difok> which is a number of character changes (inserts,
44 removals, or replacements) between the old and new password that are enough
45 to accept the new password.
46
47 =item Simple
48
49 Is the new password too small? This is controlled by 6 arguments
50 B<minlen>, B<maxclassrepeat>, B<dcredit>, B<ucredit>, B<lcredit>,
51 and B<ocredit>. See the section on the arguments for the details of how
52 these work and there defaults.
53
54 =item Rotated
55
56 Is the new password a rotated version of the old password?
57
58 =item Same consecutive characters
59
60 Optional check for same consecutive characters.
61
62 =item Too long monotonic character sequence
63
64 Optional check for too long monotonic character sequence.
65
66 =item Contains user name
67
68 Check whether the password contains the user's name in some form.
69
70 =item Dictionary check
71
72 The I<Cracklib> routine is called to check if the password is part of
73 a dictionary.
74
75 =back
76
77 These checks are configurable either by use of the module arguments
78 or by modifying the F</etc/security/pwquality.conf> configuration file. The
79 module arguments override the settings in the configuration file.
80
81 =head1 OPTIONS
82
83 =over 4
84
85 =item B<debug>
86
87 This option makes the module write information to L<syslog(3)>
88 indicating the behavior of the module (this option does not write password
89 information to the log file).
90
91 =item B<authtok_type=>I<XXX>
92
93 The default action is for the module to use the following prompts when
94 requesting passwords: C<"New UNIX password: "> and
95 C<"Retype UNIX password: ">. The example word
96 I<UNIX> can be replaced with this option, by default it is empty.
97
98 =item B<retry=>I<N>
99
100 Prompt user at most I<N> times before returning with error. The default is
101 I<1>.
102
103 =item B<difok=>I<N>
104
105 This argument will change the default of I<1> for the number of changes in
106 the new password from the old password.
107
108 The special value of I<0> disables all checks of similarity of the new password
109 with the old password except the new password being exactly the same as
110 the old one.
111
112 =item B<minlen=>I<N>
113
114 The minimum acceptable size for the new password (plus one if credits are not
115 disabled which is the default). In addition to the number of characters in
116 the new password, credit (of +1 in length) is given for each different kind
117 of character (I<other>, I<upper>, I<lower> and I<digit>). The default for this
118 parameter is I<8>. Note that there is a pair of length limits also in
119 I<Cracklib>, which is used for dictionary checking, a "way too short" limit
120 of I<4> which is hard coded in and a build time defined limit (I<6>) that will
121 be checked without reference to B<minlen>.
122
123 =item B<dcredit=>I<N>
124
125 (N >= 0) This is the maximum credit for having digits in the new password.
126 If you have less than or I<N> digits, each digit will count +1 towards meeting
127 the current B<minlen> value. The default for B<dcredit> is I<0>
128 which means there is no bonus for digits in password.
129
130 (N < 0) This is the minimum number of digits that must be met for a new
131 password.
132
133 =item B<ucredit=>I<N>
134
135 (N >= 0) This is the maximum credit for having upper case letters in the new password.
136 If you have less than or I<N> upper case letters, each upper case letter will count +1 towards meeting
137 the current B<minlen> value. The default for B<ucredit> is I<0>
138 which means there is no bonus for upper case letters in password.
139
140 (N < 0) This is the minimum number of upper case letters that must be met for a new
141 password.
142
143 =item B<lcredit=>I<N>
144
145 (N >= 0) This is the maximum credit for having lower case letters in the new password.
146 If you have less than or I<N> lower case letters, each lower case letter will count +1 towards meeting
147 the current B<minlen> value. The default for B<lcredit> is I<0>
148 which means there is no bonus for lower case letters in password.
149
150 (N < 0) This is the minimum number of lower case letters that must be met for a new
151 password.
152
153 =item B<ocredit=>I<N>
154
155 (N >= 0) This is the maximum credit for having other characters in the new password.
156 If you have less than or I<N> other characters, each other character will count +1 towards meeting
157 the current B<minlen> value. The default for B<ocredit> is I<0>
158 which means there is no bonus for other characters in password.
159
160 (N < 0) This is the minimum number of other characters that must be met for a new
161 password.
162
163 =item B<minclass=>I<N>
164
165 The minimum number of required classes of characters for the new password.
166 The four classes are digits, upper and lower letters and other characters.
167 The difference to the B<credit> check is that a specific class if of
168 characters is not required. Instead I<N> out of four of the classes are
169 required. By default the check is disabled.
170
171 =item B<maxrepeat=>I<N>
172
173 Reject passwords which contain more than I<N> same consecutive characters.
174 The default is 0 which means that this check is disabled.
175
176 =item B<maxsequence=>I<N>
177
178 Reject passwords which contain monotonic character sequences longer than I<N>.
179 The default is 0 which means that this check is disabled.
180 Examples of such sequence are '12345' or 'fedcb'. Note that
181 most such passwords will not pass the simplicity check unless the sequence
182 is only a minor part of the password.
183
184 =item B<maxclassrepeat=>I<N>
185
186 Reject passwords which contain more than I<N> consecutive characters of the
187 same class. The default is 0 which means that this check is disabled.
188
189 =item B<gecoscheck=>I<N>
190
191 If nonzero, check whether the individual words longer than 3 characters
192 from the L<passwd(5)> GECOS field of the user are contained in the new
193 password. The default is 0 which means that this check is disabled.
194
195 =item B<dictcheck=>I<N>
196
197 If nonzero, check whether the password (with possible modifications)
198 matches a word in a dictionary. Currently the dictionary check is performed
199 using the I<cracklib> library. The default is 1 which means that this check
200 is enabled.
201
202 =item B<usercheck=>I<N>
203
204 If nonzero, check whether the password (with possible modifications)
205 contains the user name in some form. The default is 1 which means that
206 this check is enabled. It is not performed for user names shorter
207 than 3 characters.
208
209 =item B<usersubstr=>I<N>
210
211 If greater than 3 (due to the minimum length in usercheck), check whether the
212 password contains a substring of the user name of at least I<N> length in some form.
213 The default is 0, which means this check is disabled.
214
215 =item B<enforcing=>I<N>
216
217 If nonzero, reject the password if it fails the checks, otherwise
218 only print the warning. The default is 1 which means that the weak password
219 is rejected (for non-root users).
220
221 =item B<badwords=>I<< <list of words> >>
222
223 The words more than 3 characters long from this space separated list are
224 individually searched for and forbidden in the new password.
225 By default the list is empty which means that this check is disabled.
226
227 =item B<dictpath=>I</path/to/dict>
228
229 This options allows for specification of non-default path to the cracklib
230 dictionaries.
231
232 =item B<enforce_for_root>
233
234 The module will return error on failed check even if the user changing the
235 password is root. This option is off by default which means that just
236 the message about the failed check is printed but root can change
237 the password anyway. Note that root is not asked for an old password
238 so the checks that compare the old and new password are not performed.
239
240 =item B<local_users_only>
241
242 The module will not test the password quality for users that are not present
243 in the F</etc/passwd> file. The module still asks for the password so
244 the following modules in the stack can use the B<use_authtok> option.
245 This option is off by default.
246
247 =item B<use_authtok>
248
249 This argument is used to I<force> the module to not prompt the user for
250 a new password but use the one provided by the previously stacked
251 B<password> module.
252
253 =back
254
255 =head1 MODULE TYPES PROVIDED
256
257 Only the B<password> module type is provided.
258
259 =head1 RETURN VALUES
260
261 =over 4
262
263 =item PAM_SUCCESS
264
265 The new password passes all checks.
266
267 =item PAM_AUTHTOK_ERR
268
269 No new password was entered, the username could not be determined or the
270 new password fails the strength checks.
271
272 =item PAM_AUTHTOK_RECOVERY_ERR
273
274 The old password was not supplied by a previous stacked module or got not
275 requested from the user. The first error can happen if B<use_authtok>
276 is specified.
277
278 =item PAM_SERVICE_ERR
279
280 A internal error occurred.
281
282 =back
283
284 =head1 EXAMPLES
285
286 For an example of the use of this module, we show how it may be stacked
287 with the password component of L<pam_unix(8)>.
288
289 #
290 # These lines stack two password type modules. In this example the
291 # user is given 3 opportunities to enter a strong password. The
292 # "use_authtok" argument ensures that the pam_unix module does not
293 # prompt for a password, but instead uses the one provided by
294 # pam_pwquality.
295 #
296 password required pam_pwquality.so retry=3
297 password required pam_unix.so use_authtok
298
299 Another example is for the case that you want to use sha256 password
300 encryption:
301
302 #
303 # These lines allow modern systems to support passwords of at least 14
304 # bytes with extra credit of 2 for digits and 2 for others the new
305 # password must have at least three bytes that are not present in the
306 # old password
307 #
308 password required pam_pwquality.so \
309 difok=3 minlen=15 dcredit=2 ocredit=2
310 password required pam_unix.so use_authtok nullok sha256
311
312 And here is another example in case you don't want to use credits:
313
314 #
315 # These lines require the user to select a password with a minimum
316 # length of 8 and with at least 1 digit number, 1 upper case letter,
317 # and 1 other character
318 #
319 password required pam_pwquality.so \
320 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=0 minlen=8
321 password required pam_unix.so use_authtok nullok sha256
322
323 =head1 SEE ALSO
324
325 L<pwscore(1)>, L<pwquality.conf(5)>, L<pam_pwquality(8)>,
326 L<pam.conf(5)>, L<PAM(8)>
327
328 =head1 AUTHORS
329
330 Tomas Mraz <[email protected]>
331
332 Original author of B<pam_cracklib> module Cristian Gafton <[email protected]>