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 ones. All features are optional and 5can 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 are a number of supported options, which can be used to modify the 19behavior of pam_passwdqc (defaults are given in square brackets): 20 21 config=FILE [] 22 23Load the specified configuration FILE, which must be in the 24passwdqc.conf format (described in the passwdqc.conf(5) manual page). 25This file may define any options described in here, including load of 26yet another configuration file, but loops are not allowed. 27 28 min=N0,N1,N2,N3,N4 [min=disabled,24,11,8,7] 29 30The minimum allowed password lengths for different kinds of passwords 31and passphrases. The keyword "disabled" can be used to disallow 32passwords of a given kind regardless of their length. Each subsequent 33number is required to be no larger than the preceding one. 34 35N0 is used for passwords consisting of characters from one character 36class only. The character classes are: digits, lower-case letters, 37upper-case letters, and other characters. There is also a special 38class for non-ASCII characters, which could not be classified, but are 39assumed to be non-digits. 40 41N1 is used for passwords consisting of characters from two character 42classes that do not meet the requirements for a passphrase. 43 44N2 is used for passphrases. Note that besides meeting this length 45requirement, a passphrase must also consist of a sufficient number of 46words (see the "passphrase" option below). 47 48N3 and N4 are used for passwords consisting of characters from three 49and four character classes, respectively. 50 51When calculating the number of character classes, upper-case letters 52used as the first character and digits used as the last character of a 53password are not counted. 54 55In addition to being sufficiently long, passwords are required to 56contain enough different characters for the character classes and 57the minimum length they have been checked against. 58 59 max=N [max=72] 60 61The maximum allowed password length. This can be used to prevent 62users from setting passwords that may be too long for some system 63services. 64 65The value 8 is treated specially: with max=8, passwords longer than 8 66characters will not be rejected, but will be truncated to 8 characters 67for the strength checks and the user will be warned. This is to be 68used with the traditional DES-based password hashes, which truncate 69the password at 8 characters. 70 71It is important that you do set max=8 if you are using the traditional 72hashes, or some weak passwords will pass the checks. 73 74 passphrase=N [passphrase=3] 75 76The number of words required for a passphrase, or 0 to disable the 77support for user-chosen passphrases. 78 79 match=N [match=4] 80 81The length of common substring required to conclude that a password is 82at least partially based on information found in a character string, 83or 0 to disable the substring search. Note that the password will not 84be rejected once a weak substring is found; it will instead be 85subjected to the usual strength requirements with the weak substring 86partially discounted. 87 88The substring search is case-insensitive and is able to detect and 89remove a common substring spelled backwards. 90 91 similar=permit|deny [similar=deny] 92 93Whether a new password is allowed to be similar to the old one. The 94passwords are considered to be similar when there is a sufficiently 95long common substring and the new password with the substring partially 96discounted would be weak. 97 98 wordlist=FILE [] 99 100Deny passwords that are based on lines of a tiny external text file, 101which can reasonably be e.g. a list of a few thousand common passwords. 102Common dictionary words may also reasonably be included, especially in a 103local language other than English, or longer yet common English words. 104(passwdqc includes a list of a few thousand common English words of 105lengths from 3 to 6 built in. Any word list possibly specified with 106this option is used in addition to the built-in word list.) 107 108Substring matching and discounting will be used if the "match" setting 109above is non-zero. Please note that this is very inefficient, and isn't 110to be used with large wordlists. 111 112 denylist=FILE [] 113 114Deny passwords or passphrases directly appearing in a tiny external text 115file. That file can reasonably be e.g. a list of common passwords if 116only a relaxed policy is desired and stricter checks are thus disabled 117(using their separate options). Such policy would only be somewhat 118effective against online/remote attacks, but not against offline attacks 119on hashed passwords. 120 121 filter=FILE [] 122 123Deny passwords or passphrases directly appearing in a maybe huge binary 124filter file created with pwqfilter. This is very efficient, needing at 125most two random disk reads per query. A filter created from millions of 126leaked passwords can reasonably be used on top of passwdqc's other 127checks to further reduce the number of passing yet weak passwords 128without causing unreasonable inconvenience (as e.g. higher minimum 129lengths and character set requirements could). 130 131 random=N[,only] [random=47] 132 133The size of randomly-generated passphrases in bits (24 to 136), or 0 to 134disable this feature. Any passphrase that contains the offered 135randomly-generated string will be allowed regardless of other possible 136restrictions. 137 138The "only" modifier can be used to disallow user-chosen passwords. 139 140 enforce=none|users|everyone [enforce=everyone] 141 142The module can be configured to warn of weak passwords only, but not 143actually enforce strong passwords. The "users" setting will enforce 144strong passwords for invocations by non-root users only. 145 146 non-unix [] 147 148Normally, the module uses getpwnam(3) to obtain the user's personal 149login information and use that during the password strength checks. 150This behavior can be disabled with the "non-unix" option. 151 152 retry=N [retry=3] 153 154The number of times the module will ask for a new password if the user 155fails to provide a sufficiently strong password and enter it twice the 156first time. 157 158 ask_oldauthtok[=update] [] 159 160Ask for the old password as well. Normally, pam_passwdqc leaves this 161task for subsequent modules. With no argument, the "ask_oldauthtok" 162option will cause pam_passwdqc to ask for the old password during the 163preliminary check phase. With "ask_oldauthtok=update", pam_passwdqc 164will do that during the update phase. 165 166 check_oldauthtok [] 167 168This tells pam_passwdqc to validate the old password before giving a 169new password prompt. Normally, this task is left for subsequent 170modules. 171 172The primary use for this option is when "ask_oldauthtok=update" is 173also specified, in which case no other module gets a chance to ask 174for and validate the password. Of course, this will only work with 175Unix passwords. 176 177 use_first_pass [] 178 use_authtok [] 179 180Use the new password obtained by modules stacked before pam_passwdqc. 181This disables user interaction within pam_passwdqc. With this module, 182the only difference between "use_first_pass" and "use_authtok" is that 183the former is incompatible with "ask_oldauthtok". 184 185 noaudit [] 186 187If audit is enabled at build time, the PAM module logs audit events once 188user tries to change their credentials. This option disables that audit 189logging. 190