116d0e647SPeter Avalospam_passwdqc is a simple password strength checking module for 216d0e647SPeter AvalosPAM-aware password changing programs, such as passwd(1). In addition 316d0e647SPeter Avalosto checking regular passwords, it offers support for passphrases and 416d0e647SPeter Avaloscan provide randomly generated ones. All features are optional and 516d0e647SPeter Avaloscan be (re-)configured without rebuilding. 616d0e647SPeter Avalos 716d0e647SPeter AvalosThis module should be stacked before your usual password changing 816d0e647SPeter Avalosmodule (such as pam_unix or pam_pwdb) in the password management group 916d0e647SPeter Avalos(the "password" lines in /etc/pam.d/passwd or /etc/pam.conf). The 1016d0e647SPeter Avalospassword changing module should then be told to use the provided new 1116d0e647SPeter Avalosauthentication token (new password) rather than request it from the 1216d0e647SPeter Avalosuser. There's usually the "use_authtok" option to do that. If your 1316d0e647SPeter Avalospassword changing module lacks the "use_authtok" option or its prompts 1416d0e647SPeter Avalosare inconsistent with pam_passwdqc's, you may tell pam_passwdqc to ask 1516d0e647SPeter Avalosfor the old password as well, with "ask_oldauthtok". In that case the 1616d0e647SPeter Avalosoption to use with the password changing module is "use_first_pass". 1716d0e647SPeter Avalos 18*8c117293SSascha WildnerThere are a number of supported options, which can be used to modify the 1916d0e647SPeter Avalosbehavior of pam_passwdqc (defaults are given in square brackets): 2016d0e647SPeter Avalos 21*8c117293SSascha Wildner config=FILE [] 22*8c117293SSascha Wildner 23*8c117293SSascha WildnerLoad the specified configuration FILE, which must be in the 24*8c117293SSascha Wildnerpasswdqc.conf format (described in the passwdqc.conf(5) manual page). 25*8c117293SSascha WildnerThis file may define any options described in here, including load of 26*8c117293SSascha Wildneryet another configuration file, but loops are not allowed. 27*8c117293SSascha Wildner 2816d0e647SPeter Avalos min=N0,N1,N2,N3,N4 [min=disabled,24,11,8,7] 2916d0e647SPeter Avalos 3016d0e647SPeter AvalosThe minimum allowed password lengths for different kinds of passwords 3116d0e647SPeter Avalosand passphrases. The keyword "disabled" can be used to disallow 3216d0e647SPeter Avalospasswords of a given kind regardless of their length. Each subsequent 3316d0e647SPeter Avalosnumber is required to be no larger than the preceding one. 3416d0e647SPeter Avalos 3516d0e647SPeter AvalosN0 is used for passwords consisting of characters from one character 3616d0e647SPeter Avalosclass only. The character classes are: digits, lower-case letters, 3716d0e647SPeter Avalosupper-case letters, and other characters. There is also a special 3816d0e647SPeter Avalosclass for non-ASCII characters, which could not be classified, but are 3916d0e647SPeter Avalosassumed to be non-digits. 4016d0e647SPeter Avalos 4116d0e647SPeter AvalosN1 is used for passwords consisting of characters from two character 4216d0e647SPeter Avalosclasses that do not meet the requirements for a passphrase. 4316d0e647SPeter Avalos 4416d0e647SPeter AvalosN2 is used for passphrases. Note that besides meeting this length 4516d0e647SPeter Avalosrequirement, a passphrase must also consist of a sufficient number of 4616d0e647SPeter Avaloswords (see the "passphrase" option below). 4716d0e647SPeter Avalos 4816d0e647SPeter AvalosN3 and N4 are used for passwords consisting of characters from three 4916d0e647SPeter Avalosand four character classes, respectively. 5016d0e647SPeter Avalos 5116d0e647SPeter AvalosWhen calculating the number of character classes, upper-case letters 5216d0e647SPeter Avalosused as the first character and digits used as the last character of a 5316d0e647SPeter Avalospassword are not counted. 5416d0e647SPeter Avalos 5516d0e647SPeter AvalosIn addition to being sufficiently long, passwords are required to 5616d0e647SPeter Avaloscontain enough different characters for the character classes and 5716d0e647SPeter Avalosthe minimum length they have been checked against. 5816d0e647SPeter Avalos 59*8c117293SSascha Wildner max=N [max=72] 6016d0e647SPeter Avalos 6116d0e647SPeter AvalosThe maximum allowed password length. This can be used to prevent 6216d0e647SPeter Avalosusers from setting passwords that may be too long for some system 6316d0e647SPeter Avalosservices. 6416d0e647SPeter Avalos 6516d0e647SPeter AvalosThe value 8 is treated specially: with max=8, passwords longer than 8 6616d0e647SPeter Avaloscharacters will not be rejected, but will be truncated to 8 characters 6716d0e647SPeter Avalosfor the strength checks and the user will be warned. This is to be 6816d0e647SPeter Avalosused with the traditional DES-based password hashes, which truncate 6916d0e647SPeter Avalosthe password at 8 characters. 7016d0e647SPeter Avalos 7116d0e647SPeter AvalosIt is important that you do set max=8 if you are using the traditional 7216d0e647SPeter Avaloshashes, or some weak passwords will pass the checks. 7316d0e647SPeter Avalos 7416d0e647SPeter Avalos passphrase=N [passphrase=3] 7516d0e647SPeter Avalos 7616d0e647SPeter AvalosThe number of words required for a passphrase, or 0 to disable the 7716d0e647SPeter Avalossupport for user-chosen passphrases. 7816d0e647SPeter Avalos 7916d0e647SPeter Avalos match=N [match=4] 8016d0e647SPeter Avalos 8116d0e647SPeter AvalosThe length of common substring required to conclude that a password is 8216d0e647SPeter Avalosat least partially based on information found in a character string, 8316d0e647SPeter Avalosor 0 to disable the substring search. Note that the password will not 8416d0e647SPeter Avalosbe rejected once a weak substring is found; it will instead be 8516d0e647SPeter Avalossubjected to the usual strength requirements with the weak substring 86*8c117293SSascha Wildnerpartially discounted. 8716d0e647SPeter Avalos 8816d0e647SPeter AvalosThe substring search is case-insensitive and is able to detect and 8916d0e647SPeter Avalosremove a common substring spelled backwards. 9016d0e647SPeter Avalos 9116d0e647SPeter Avalos similar=permit|deny [similar=deny] 9216d0e647SPeter Avalos 9316d0e647SPeter AvalosWhether a new password is allowed to be similar to the old one. The 9416d0e647SPeter Avalospasswords are considered to be similar when there is a sufficiently 95*8c117293SSascha Wildnerlong common substring and the new password with the substring partially 96*8c117293SSascha Wildnerdiscounted would be weak. 9716d0e647SPeter Avalos 98*8c117293SSascha Wildner wordlist=FILE [] 9916d0e647SPeter Avalos 100*8c117293SSascha WildnerDeny passwords that are based on lines of a tiny external text file, 101*8c117293SSascha Wildnerwhich can reasonably be e.g. a list of a few thousand common passwords. 102*8c117293SSascha WildnerCommon dictionary words may also reasonably be included, especially in a 103*8c117293SSascha Wildnerlocal language other than English, or longer yet common English words. 104*8c117293SSascha Wildner(passwdqc includes a list of a few thousand common English words of 105*8c117293SSascha Wildnerlengths from 3 to 6 built in. Any word list possibly specified with 106*8c117293SSascha Wildnerthis option is used in addition to the built-in word list.) 107*8c117293SSascha Wildner 108*8c117293SSascha WildnerSubstring matching and discounting will be used if the "match" setting 109*8c117293SSascha Wildnerabove is non-zero. Please note that this is very inefficient, and isn't 110*8c117293SSascha Wildnerto be used with large wordlists. 111*8c117293SSascha Wildner 112*8c117293SSascha Wildner denylist=FILE [] 113*8c117293SSascha Wildner 114*8c117293SSascha WildnerDeny passwords or passphrases directly appearing in a tiny external text 115*8c117293SSascha Wildnerfile. That file can reasonably be e.g. a list of common passwords if 116*8c117293SSascha Wildneronly a relaxed policy is desired and stricter checks are thus disabled 117*8c117293SSascha Wildner(using their separate options). Such policy would only be somewhat 118*8c117293SSascha Wildnereffective against online/remote attacks, but not against offline attacks 119*8c117293SSascha Wildneron hashed passwords. 120*8c117293SSascha Wildner 121*8c117293SSascha Wildner filter=FILE [] 122*8c117293SSascha Wildner 123*8c117293SSascha WildnerDeny passwords or passphrases directly appearing in a maybe huge binary 124*8c117293SSascha Wildnerfilter file created with pwqfilter. This is very efficient, needing at 125*8c117293SSascha Wildnermost two random disk reads per query. A filter created from millions of 126*8c117293SSascha Wildnerleaked passwords can reasonably be used on top of passwdqc's other 127*8c117293SSascha Wildnerchecks to further reduce the number of passing yet weak passwords 128*8c117293SSascha Wildnerwithout causing unreasonable inconvenience (as e.g. higher minimum 129*8c117293SSascha Wildnerlengths and character set requirements could). 130*8c117293SSascha Wildner 131*8c117293SSascha Wildner random=N[,only] [random=47] 132*8c117293SSascha Wildner 133*8c117293SSascha WildnerThe size of randomly-generated passphrases in bits (24 to 136), or 0 to 13416d0e647SPeter Avalosdisable this feature. Any passphrase that contains the offered 13516d0e647SPeter Avalosrandomly-generated string will be allowed regardless of other possible 13616d0e647SPeter Avalosrestrictions. 13716d0e647SPeter Avalos 13816d0e647SPeter AvalosThe "only" modifier can be used to disallow user-chosen passwords. 13916d0e647SPeter Avalos 14016d0e647SPeter Avalos enforce=none|users|everyone [enforce=everyone] 14116d0e647SPeter Avalos 14216d0e647SPeter AvalosThe module can be configured to warn of weak passwords only, but not 14316d0e647SPeter Avalosactually enforce strong passwords. The "users" setting will enforce 14416d0e647SPeter Avalosstrong passwords for invocations by non-root users only. 14516d0e647SPeter Avalos 14616d0e647SPeter Avalos non-unix [] 14716d0e647SPeter Avalos 14816d0e647SPeter AvalosNormally, the module uses getpwnam(3) to obtain the user's personal 14916d0e647SPeter Avaloslogin information and use that during the password strength checks. 15016d0e647SPeter AvalosThis behavior can be disabled with the "non-unix" option. 15116d0e647SPeter Avalos 15216d0e647SPeter Avalos retry=N [retry=3] 15316d0e647SPeter Avalos 15416d0e647SPeter AvalosThe number of times the module will ask for a new password if the user 15516d0e647SPeter Avalosfails to provide a sufficiently strong password and enter it twice the 15616d0e647SPeter Avalosfirst time. 15716d0e647SPeter Avalos 15816d0e647SPeter Avalos ask_oldauthtok[=update] [] 15916d0e647SPeter Avalos 16016d0e647SPeter AvalosAsk for the old password as well. Normally, pam_passwdqc leaves this 16116d0e647SPeter Avalostask for subsequent modules. With no argument, the "ask_oldauthtok" 16216d0e647SPeter Avalosoption will cause pam_passwdqc to ask for the old password during the 16316d0e647SPeter Avalospreliminary check phase. With "ask_oldauthtok=update", pam_passwdqc 16416d0e647SPeter Avaloswill do that during the update phase. 16516d0e647SPeter Avalos 16616d0e647SPeter Avalos check_oldauthtok [] 16716d0e647SPeter Avalos 16816d0e647SPeter AvalosThis tells pam_passwdqc to validate the old password before giving a 16916d0e647SPeter Avalosnew password prompt. Normally, this task is left for subsequent 17016d0e647SPeter Avalosmodules. 17116d0e647SPeter Avalos 17216d0e647SPeter AvalosThe primary use for this option is when "ask_oldauthtok=update" is 17316d0e647SPeter Avalosalso specified, in which case no other module gets a chance to ask 17416d0e647SPeter Avalosfor and validate the password. Of course, this will only work with 17516d0e647SPeter AvalosUnix passwords. 17616d0e647SPeter Avalos 17716d0e647SPeter Avalos use_first_pass [] 17816d0e647SPeter Avalos use_authtok [] 17916d0e647SPeter Avalos 18016d0e647SPeter AvalosUse the new password obtained by modules stacked before pam_passwdqc. 18116d0e647SPeter AvalosThis disables user interaction within pam_passwdqc. With this module, 18216d0e647SPeter Avalosthe only difference between "use_first_pass" and "use_authtok" is that 18316d0e647SPeter Avalosthe former is incompatible with "ask_oldauthtok". 18416d0e647SPeter Avalos 185*8c117293SSascha Wildner noaudit [] 18616d0e647SPeter Avalos 187*8c117293SSascha WildnerIf audit is enabled at build time, the PAM module logs audit events once 188*8c117293SSascha Wildneruser tries to change their credentials. This option disables that audit 189*8c117293SSascha Wildnerlogging. 190