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.
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.
13 .\" Redistribution and use in source and binary forms, with or without
14 .\" modification, are permitted provided that the following conditions
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
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
39 .Os "Openwall Project"
42 .Nd libpasswdqc configuration file
44 libpasswdqc is a simple password strength checking library.
45 In addition to checking regular passwords, it offers support for
46 passphrases and can provide randomly generated ones.
49 configuration file may be used to override default libpasswdqc settings.
53 file consists of 0 or more lines of the following format:
54 .Dl Ar option Ns = Ns Ar value
56 Empty lines and lines beginning with
59 Whitespace characters between the
66 .Bl -tag -width indent
67 .It Cm config Ns = Ns Ar FILE
68 Load the specified configuration
73 This file may define any options described in this manual,
74 including load of yet another configuration file, but loops are not allowed.
76 .Sh PASSWORD QUALITY CONTROL OPTIONS
81 .Ar N0 , N1 , N2 , N3 , N4
84 .Pq default: min=disabled,24,11,8,7
85 The minimum allowed password lengths for different kinds of
86 passwords/passphrases.
90 disallow passwords of a given kind regardless of their length.
91 Each subsequent number is required to be no larger than the preceding
95 is used for passwords consisting of characters from one character
97 The character classes are: digits, lower-case letters, upper-case
98 letters, and other characters.
99 There is also a special class for
101 characters, which could not be classified, but are assumed to be non-digits.
104 is used for passwords consisting of characters from two character
105 classes that do not meet the requirements for a passphrase.
108 is used for passphrases.
109 Note that besides meeting this length requirement,
110 a passphrase must also consist of a sufficient number of words (see the
117 are used for passwords consisting of characters from three
118 and four character classes, respectively.
120 When calculating the number of character classes, upper-case letters
121 used as the first character and digits used as the last character of a
122 password are not counted.
124 In addition to being sufficiently long, passwords are required to
125 contain enough different characters for the character classes and
126 the minimum length they have been checked against.
128 .It Cm max Ns = Ns Ar N
129 .Pq default: Cm max Ns = Ns 72
130 The maximum allowed password length.
131 This can be used to prevent users from setting passwords that may be
132 too long for some system services.
133 The value 8 is treated specially: if
135 is set to 8, passwords longer than 8 characters will not be rejected,
136 but will be truncated to 8 characters for the strength checks and the
138 This is to be used with the traditional DES-based password hashes,
139 which truncate the password at 8 characters.
141 It is important that you do set
143 if you are using the traditional
144 hashes, or some weak passwords will pass the checks.
145 .It Cm passphrase Ns = Ns Ar N
146 .Pq default: Cm passphrase Ns = Ns 3
147 The number of words required for a passphrase, or 0 to disable the
148 support for user-chosen passphrases.
149 .It Cm match Ns = Ns Ar N
150 .Pq default: Cm match Ns = Ns 4
151 The length of common substring required to conclude that a password is
152 at least partially based on information found in a character string,
153 or 0 to disable the substring search.
154 Note that the password will not be rejected once a weak substring is
155 found; it will instead be subjected to the usual strength requirements
156 with the weak substring partially discounted.
158 The substring search is case-insensitive and is able to detect and
159 remove a common substring spelled backwards.
162 .Cm similar No = Cm permit | deny
165 .Pq default: Cm similar Ns = Ns Cm deny
166 Whether a new password is allowed to be similar to the old one.
167 The passwords are considered to be similar when there is a sufficiently
168 long common substring and the new password with the substring partially
169 discounted would be weak.
170 .It Cm wordlist Ns = Ns Ar FILE
171 Deny passwords that are based on lines of the tiny external text
173 which can reasonably be e.g. a list of a few thousand common passwords.
174 Common dictionary words may also reasonably be included, especially in a
175 local language other than English, or longer yet common English words.
176 (passwdqc includes a list of a few thousand common English words of
177 lengths from 3 to 6 built in. Any word list possibly specified with
178 this option is used in addition to the built-in word list.)
180 Substring matching and discounting will be used if the
183 above is non-zero. Please note that this is very inefficient, and isn't
184 to be used with large wordlists.
185 .It Cm denylist Ns = Ns Ar FILE
186 Deny passwords or passphrases directly appearing in the tiny external text
188 That file can reasonably be e.g. a list of common passwords if
189 only a relaxed policy is desired and stricter checks are thus disabled
190 (using their separate options). Such policy would only be somewhat
191 effective against online/remote attacks, but not against offline attacks
193 .It Cm filter Ns = Ns Ar FILE
194 Deny passwords or passphrases directly appearing in a maybe huge binary
197 created with pwqfilter. This is very efficient, needing at
198 most two random disk reads per query. A filter created from millions of
199 leaked passwords can reasonably be used on top of passwdqc's other
200 checks to further reduce the number of passing yet weak passwords
201 without causing unreasonable inconvenience (as e.g. higher minimum
202 lengths and character set requirements could).
209 .Pq default: Cm random Ns = Ns 47
210 The size of randomly-generated passphrases in bits (24 to 136),
211 or 0 to disable this feature.
212 Any passphrase that contains the offered randomly-generated string will be
213 allowed regardless of other possible restrictions.
217 modifier can be used to disallow user-chosen passwords.
219 .Sh PAM MODULE OPTIONS
220 .Bl -tag -width indent
223 .Cm enforce No = Cm none | users | everyone
226 .Pq default: Cm enforce Ns = Ns Cm everyone
227 The PAM module can be configured to warn of weak passwords only, but not
228 actually enforce strong passwords.
231 setting will enforce strong passwords for invocations by non-root users only.
233 Normally, the PAM module uses
235 to obtain the user's personal login information and use that during
236 the password strength checks.
237 This behavior can be disabled with the
240 .It Cm retry Ns = Ns Ar N
241 .Pq default: Cm retry Ns = Ns 3
242 The number of times the PAM module will ask for a new password if the
243 user fails to provide a sufficiently strong password and enter it twice
245 .It Cm ask_oldauthtok Ns Op = Ns Cm update
246 Ask for the old password as well.
247 Normally, the PAM module leaves this task for subsequent modules.
248 With no argument, the
250 option will cause the PAM module to ask for the old password during the
251 preliminary check phase. If the
253 option is specified with the
255 argument, the PAM module will do that during the update phase.
256 .It Cm check_oldauthtok
257 This tells the PAM module to validate the old password before giving a
259 Normally, this task is left for subsequent modules.
261 The primary use for this option is when
262 .Cm ask_oldauthtok Ns = Ns Cm update
263 is also specified, in which case no other module gets a chance to ask
264 for and validate the password.
265 Of course, this will only work with
268 .It Cm use_first_pass , use_authtok
269 Use the new password obtained by other modules stacked before the PAM
270 module. This disables user interaction within the PAM module.
271 The only difference between
275 is that the former is incompatible with
278 If audit is enabled at build time, the PAM module logs audit events once
279 user tries to change their credentials. This option disables that audit
283 .Pa /etc/passwdqc.conf
284 (not read unless this suggested file location is specified with the
285 .Cm config=/etc/passwdqc.conf
289 .\".Xr libpasswdqc 3 ,
292 https://www.openwall.com/passwdqc/
294 The pam_passwdqc module was written for Openwall GNU/*/Linux by
295 .An Solar Designer Aq solar at openwall.com .
296 This manual page was derived from
297 .Xr pam_passwdqc 8 . The latter, derived from the author's
298 documentation, was written for the
301 ThinkSec AS and NAI Labs, the Security Research Division of Network
302 Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
304 as part of the DARPA CHATS research program.