1.\" Copyright (c) 2000-2003,2005,2008,2019,2020 Solar Designer 2.\" All rights reserved. 3.\" Copyright (c) 2001 Networks Associates Technology, Inc. 4.\" All rights reserved. 5.\" Copyright (c) 2009 Dmitry V. Levin 6.\" All rights reserved. 7.\" 8.\" Portions of this software were developed for the FreeBSD Project by 9.\" ThinkSec AS and NAI Labs, the Security Research Division of Network 10.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 11.\" ("CBOSS"), as part of the DARPA CHATS research program. 12.\" 13.\" Redistribution and use in source and binary forms, with or without 14.\" modification, are permitted provided that the following conditions 15.\" are met: 16.\" 1. Redistributions of source code must retain the above copyright 17.\" notice, this list of conditions and the following disclaimer. 18.\" 2. Redistributions in binary form must reproduce the above copyright 19.\" notice, this list of conditions and the following disclaimer in the 20.\" documentation and/or other materials provided with the distribution. 21.\" 3. The name of the author may not be used to endorse or promote 22.\" products derived from this software without specific prior written 23.\" permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.Dd March 10, 2021 38.Dt PASSWDQC.CONF 5 39.Os "Openwall Project" 40.Sh NAME 41.Nm passwdqc.conf 42.Nd libpasswdqc configuration file 43.Sh DESCRIPTION 44libpasswdqc is a simple password strength checking library. 45In addition to checking regular passwords, it offers support for 46passphrases and can provide randomly generated ones. 47A 48.Nm 49configuration file may be used to override default libpasswdqc settings. 50.Sh FORMAT 51A 52.Nm 53file consists of 0 or more lines of the following format: 54.Dl Ar option Ns = Ns Ar value 55.Pp 56Empty lines and lines beginning with 57.Dq Li # 58are ignored. 59Whitespace characters between the 60.Ar option , 61.Dq Li = , 62and 63.Ar value 64are not allowed. 65.Sh DIRECTIVE OPTIONS 66.Bl -tag -width indent 67.It Cm config Ns = Ns Ar FILE 68Load the specified configuration 69.Ar FILE 70in the 71.Cm passwdqc.conf 72format. 73This file may define any options described in this manual, 74including load of yet another configuration file, but loops are not allowed. 75.El 76.Sh PASSWORD QUALITY CONTROL OPTIONS 77.Bl -tag -width Ds 78.Sm off 79.It Xo 80.Cm min No = 81.Ar N0 , N1 , N2 , N3 , N4 82.Xc 83.Sm on 84.Pq default: min=disabled,24,11,8,7 85The minimum allowed password lengths for different kinds of 86passwords/passphrases. 87The keyword 88.Cm disabled 89can be used to 90disallow passwords of a given kind regardless of their length. 91Each subsequent number is required to be no larger than the preceding 92one. 93.Pp 94.Ar N0 95is used for passwords consisting of characters from one character 96class only. 97The character classes are: digits, lower-case letters, upper-case 98letters, and other characters. 99There is also a special class for 100.No non- Ns Tn ASCII 101characters, which could not be classified, but are assumed to be non-digits. 102.Pp 103.Ar N1 104is used for passwords consisting of characters from two character 105classes that do not meet the requirements for a passphrase. 106.Pp 107.Ar N2 108is used for passphrases. 109Note that besides meeting this length requirement, 110a passphrase must also consist of a sufficient number of words (see the 111.Cm passphrase 112option below). 113.Pp 114.Ar N3 115and 116.Ar N4 117are used for passwords consisting of characters from three 118and four character classes, respectively. 119.Pp 120When calculating the number of character classes, upper-case letters 121used as the first character and digits used as the last character of a 122password are not counted. 123.Pp 124In addition to being sufficiently long, passwords are required to 125contain enough different characters for the character classes and 126the minimum length they have been checked against. 127.Pp 128.It Cm max Ns = Ns Ar N 129.Pq default: Cm max Ns = Ns 72 130The maximum allowed password length. 131This can be used to prevent users from setting passwords that may be 132too long for some system services. 133The value 8 is treated specially: if 134.Cm max 135is set to 8, passwords longer than 8 characters will not be rejected, 136but will be truncated to 8 characters for the strength checks and the 137user will be warned. 138This is to be used with the traditional DES-based password hashes, 139which truncate the password at 8 characters. 140.Pp 141It is important that you do set 142.Cm max Ns = Ns 8 143if you are using the traditional 144hashes, or some weak passwords will pass the checks. 145.It Cm passphrase Ns = Ns Ar N 146.Pq default: Cm passphrase Ns = Ns 3 147The number of words required for a passphrase, or 0 to disable the 148support for user-chosen passphrases. 149.It Cm match Ns = Ns Ar N 150.Pq default: Cm match Ns = Ns 4 151The length of common substring required to conclude that a password is 152at least partially based on information found in a character string, 153or 0 to disable the substring search. 154Note that the password will not be rejected once a weak substring is 155found; it will instead be subjected to the usual strength requirements 156with the weak substring partially discounted. 157.Pp 158The substring search is case-insensitive and is able to detect and 159remove a common substring spelled backwards. 160.It Xo 161.Sm off 162.Cm similar No = Cm permit | deny 163.Sm on 164.Xc 165.Pq default: Cm similar Ns = Ns Cm deny 166Whether a new password is allowed to be similar to the old one. 167The passwords are considered to be similar when there is a sufficiently 168long common substring and the new password with the substring partially 169discounted would be weak. 170.It Cm wordlist Ns = Ns Ar FILE 171Deny passwords that are based on lines of the tiny external text 172.Ar FILE , 173which can reasonably be e.g. a list of a few thousand common passwords. 174Common dictionary words may also reasonably be included, especially in a 175local language other than English, or longer yet common English words. 176(passwdqc includes a list of a few thousand common English words of 177lengths from 3 to 6 built in. Any word list possibly specified with 178this option is used in addition to the built-in word list.) 179.Pp 180Substring matching and discounting will be used if the 181.Cm match 182setting 183above is non-zero. Please note that this is very inefficient, and isn't 184to be used with large wordlists. 185.It Cm denylist Ns = Ns Ar FILE 186Deny passwords or passphrases directly appearing in the tiny external text 187.Ar FILE . 188That file can reasonably be e.g. a list of common passwords if 189only a relaxed policy is desired and stricter checks are thus disabled 190(using their separate options). Such policy would only be somewhat 191effective against online/remote attacks, but not against offline attacks 192on hashed passwords. 193.It Cm filter Ns = Ns Ar FILE 194Deny passwords or passphrases directly appearing in a maybe huge binary 195filter 196.Ar FILE 197created with pwqfilter. This is very efficient, needing at 198most two random disk reads per query. A filter created from millions of 199leaked passwords can reasonably be used on top of passwdqc's other 200checks to further reduce the number of passing yet weak passwords 201without causing unreasonable inconvenience (as e.g. higher minimum 202lengths and character set requirements could). 203.It Xo 204.Sm off 205.Cm random No = Ar N 206.Op , Cm only 207.Sm on 208.Xc 209.Pq default: Cm random Ns = Ns 47 210The size of randomly-generated passphrases in bits (24 to 136), 211or 0 to disable this feature. 212Any passphrase that contains the offered randomly-generated string will be 213allowed regardless of other possible restrictions. 214.Pp 215The 216.Cm only 217modifier can be used to disallow user-chosen passwords. 218.El 219.Sh PAM MODULE OPTIONS 220.Bl -tag -width indent 221.It Xo 222.Sm off 223.Cm enforce No = Cm none | users | everyone 224.Sm on 225.Xc 226.Pq default: Cm enforce Ns = Ns Cm everyone 227The PAM module can be configured to warn of weak passwords only, but not 228actually enforce strong passwords. 229The 230.Cm users 231setting will enforce strong passwords for invocations by non-root users only. 232.It Cm non-unix 233Normally, the PAM module uses 234.Xr getpwnam 3 235to obtain the user's personal login information and use that during 236the password strength checks. 237This behavior can be disabled with the 238.Cm non-unix 239option. 240.It Cm retry Ns = Ns Ar N 241.Pq default: Cm retry Ns = Ns 3 242The number of times the PAM module will ask for a new password if the 243user fails to provide a sufficiently strong password and enter it twice 244the first time. 245.It Cm ask_oldauthtok Ns Op = Ns Cm update 246Ask for the old password as well. 247Normally, the PAM module leaves this task for subsequent modules. 248With no argument, the 249.Cm ask_oldauthtok 250option will cause the PAM module to ask for the old password during the 251preliminary check phase. If the 252.Cm ask_oldauthtok 253option is specified with the 254.Cm update 255argument, the PAM module will do that during the update phase. 256.It Cm check_oldauthtok 257This tells the PAM module to validate the old password before giving a 258new password prompt. 259Normally, this task is left for subsequent modules. 260.Pp 261The primary use for this option is when 262.Cm ask_oldauthtok Ns = Ns Cm update 263is also specified, in which case no other module gets a chance to ask 264for and validate the password. 265Of course, this will only work with 266.Ux 267passwords. 268.It Cm use_first_pass , use_authtok 269Use the new password obtained by other modules stacked before the PAM 270module. This disables user interaction within the PAM module. 271The only difference between 272.Cm use_first_pass 273and 274.Cm use_authtok 275is that the former is incompatible with 276.Cm ask_oldauthtok . 277.It Cm noaudit 278If audit is enabled at build time, the PAM module logs audit events once 279user tries to change their credentials. This option disables that audit 280logging. 281.El 282.Sh FILES 283.Pa /etc/passwdqc.conf 284(not read unless this suggested file location is specified with the 285.Cm config=/etc/passwdqc.conf 286option). 287.Sh SEE ALSO 288.Xr getpwnam 3 , 289.\".Xr libpasswdqc 3 , 290.Xr pam_passwdqc 8 . 291.Pp 292https://www.openwall.com/passwdqc/ 293.Sh AUTHORS 294The pam_passwdqc module was written for Openwall GNU/*/Linux by 295.An Solar Designer Aq solar at openwall.com . 296This manual page was derived from 297.Xr pam_passwdqc 8 . The latter, derived from the author's 298documentation, was written for the 299.Fx 300Project by 301ThinkSec AS and NAI Labs, the Security Research Division of Network 302Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 303.Pq Dq CBOSS , 304as part of the DARPA CHATS research program. 305