1pam_passwdqc is a simple password strength checking module for 2PAM-aware password changing programs, such as passwd(1). In addition 3to checking regular passwords, it offers support for passphrases and 4can provide randomly generated passwords. All features are optional 5and can be (re-)configured without rebuilding. 6 7This module should be stacked before your usual password changing 8module (such as pam_unix or pam_pwdb) in the password management group 9(the "password" lines in /etc/pam.d/passwd or /etc/pam.conf). The 10password changing module should then be told to use the provided new 11authentication token (new password) rather than request it from the 12user. There's usually the "use_authtok" option to do that. If your 13password changing module lacks the "use_authtok" option or its prompts 14are inconsistent with pam_passwdqc's, you may tell pam_passwdqc to ask 15for the old password as well, with "ask_oldauthtok". In that case the 16option to use with the password changing module is "use_first_pass". 17 18There's a number of supported options which can be used to modify the 19behavior of pam_passwdqc (defaults are given in square brackets): 20 21 min=N0,N1,N2,N3,N4 [min=disabled,24,12,8,7] 22 23The minimum allowed password lengths, separately for different kinds 24of passwords/passphrases. The special word "disabled" can be used to 25disallow passwords of a given kind regardless of their length. Each 26subsequent number is required to be no larger than the preceding one. 27 28N0 is used for passwords consisting of characters from one character 29class only. (The character classes are: digits, lower-case letters, 30upper-case letters, and other characters. There's also the special 31class for non-ASCII characters which couldn't be classified, but are 32assumed to be non-digits.) 33 34N1 is used for passwords consisting of characters from two character 35classes, which don't meet the requirements for a passphrase. 36 37N2 is used for passphrases. A passphrase must consist of sufficient 38words (see the "passphrase" option, below). 39 40N3 and N4 are used for passwords consisting of characters from three 41and four character classes, respectively. 42 43When calculating the number of character classes, upper-case letters 44used as the first character and digits used as the last character of a 45password are not counted. 46 47In addition to being sufficiently long, passwords are required to 48contain enough different characters for the character classes and 49the minimum length they've been checked against. 50 51 max=N [max=40] 52 53The maximum allowed password length. This can be used to prevent 54users from setting passwords which may be too long for some system 55services. 56 57The value 8 is treated specially. Passwords longer than 8 characters 58will not be rejected, but will be truncated to 8 characters for the 59strength checks and the user will be warned. This is to be used with 60the traditional crypt(3) password hashes. 61 62It is important that you do set max=8 if you're using the traditional 63hashes, or some weak passwords will pass the checks. 64 65 passphrase=N [passphrase=3] 66 67The number of words required for a passphrase, or 0 to disable the 68support for passphrases. 69 70 match=N [match=4] 71 72The length of common substring required to conclude that a password is 73at least partially based on information found in a character string, 74or 0 to disable the substring search. Note that the password will not 75be rejected once a weak substring is found. Instead, the password 76will be subjected to the usual strength requirements with the weak 77substring removed. 78 79The substring search is case-insensitive and is able to detect and 80remove a common substring spelled backwards. 81 82 similar=permit|deny [similar=deny] 83 84Whether a new password is allowed to be similar to the old one. The 85passwords are considered to be similar when there's a sufficiently 86long common substring and the new password with the substring removed 87would be weak. 88 89 random=N[,only] [random=42] 90 91The size of randomly-generated passwords in bits, or 0 to disable this 92feature. Passwords that contain the offered randomly-generated string 93will be allowed regardless of other possible restrictions. 94 95The "only" modifier can be used to disallow user-chosen passwords. 96 97 enforce=none|users|everyone [enforce=everyone] 98 99The module can be configured to warn of weak passwords only, but not 100actually enforce strong passwords. The "users" setting will enforce 101strong passwords for non-root users only. 102 103 non-unix [] 104 105By default, the module uses getpwnam(3) to obtain the user's personal 106login information and use that during the password strength checks. 107This behavior can be disabled with "non-unix". 108 109 retry=N [retry=3] 110 111The number of times the module will ask for a new password if the user 112fails to provide a sufficiently strong password and enter it twice the 113first time. 114 115 ask_oldauthtok[=update] [] 116 117Ask for the old password as well. Normally, pam_passwdqc leaves this 118task for the password changing module. A simple "ask_oldauthtok" will 119cause pam_passwdqc to ask for the old password during the preliminary 120check phase. With "ask_oldauthtok=update", pam_passwdqc will do that 121during the update phase. 122 123 check_oldauthtok [] 124 125This tells pam_passwdqc to validate the old password before giving a 126new password prompt. Normally, this task is left for the password 127changing module. 128 129The primary use for this option is with "ask_oldauthtok=update" in 130which case no other modules have a chance to run and validate the 131password between the prompts. Of course, this will only work with 132Unix passwords. 133 134 use_first_pass [] 135 use_authtok [] 136 137Use the new password obtained by modules stacked before pam_passwdqc. 138This disables user interaction within pam_passwdqc. With this module, 139the only difference between "use_first_pass" and "use_authtok" is that 140the former is incompatible with "ask_oldauthtok". 141 142-- 143Solar Designer <solar@openwall.com> 144