| 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]> |