1PWQCHECK(1) BSD General Commands Manual PWQCHECK(1)
2
4 pwqcheck — Check passphrase quality
5
7 pwqcheck [options]
8
10 The pwqcheck program checks passphrase quality using the libpasswdqc li‐
11 brary. By default, it expects to read 3 lines from standard input:
12 first line is a new password,
14 second line is an old password, and
15 third line is either an existing account name or a passwd(5) entry.
16 There are a number of supported options, which can be used to control the
18 pwqcheck behavior.
19 pwqcheck prints OK on success. Scripts invoking pwqcheck are suggested
21 to check for both a zero exit status and the OK line.
22
24 min=N0,N1,N2,N3,N4
25 (default: min=disabled,24,11,8,7) The minimum allowed password
26 lengths for different kinds of passwords/passphrases. The key‐
27 word disabled can be used to disallow passwords of a given kind
28 regardless of their length. Each subsequent number is required
29 to be no larger than the preceding one.
30 N0 is used for passwords consisting of characters from one char‐
32 acter class only. The character classes are: digits, lower-case
33 letters, upper-case letters, and other characters. There is also
34 a special class for non-ASCII characters, which could not be
35 classified, but are assumed to be non-digits.
36 N1 is used for passwords consisting of characters from two char‐
38 acter classes that do not meet the requirements for a passphrase.
39 N2 is used for passphrases. Note that besides meeting this
41 length requirement, a passphrase must also consist of a suffi‐
42 cient number of words (see the passphrase option below).
43 N3 and N4 are used for passwords consisting of characters from
45 three and four character classes, respectively.
46 When calculating the number of character classes, upper-case let‐
48 ters used as the first character and digits used as the last
49 character of a password are not counted.
50 In addition to being sufficiently long, passwords are required to
52 contain enough different characters for the character classes and
53 the minimum length they have been checked against.
54 max=N (default: max=72) The maximum allowed password length. This can
56 be used to prevent users from setting passwords that may be too
57 long for some system services. The value 8 is treated specially:
58 if max is set to 8, passwords longer than 8 characters will not
59 be rejected, but will be truncated to 8 characters for the
60 strength checks and the user will be warned. This is to be used
61 with the traditional DES-based password hashes, which truncate
62 the password at 8 characters.
63 It is important that you do set max=8 if you are using the tradi‐
65 tional hashes, or some weak passwords will pass the checks.
66 passphrase=N
68 (default: passphrase=3) The number of words required for a
69 passphrase.
70 match=N
72 (default: match=4) The length of common substring required to
73 conclude that a password is at least partially based on informa‐
74 tion found in a character string, or 0 to disable the substring
75 search. Note that the password will not be rejected once a weak
76 substring is found; it will instead be subjected to the usual
77 strength requirements with the weak substring partially dis‐
78 counted.
79 The substring search is case-insensitive and is able to detect
81 and remove a common substring spelled backwards.
82 similar=permit|deny
84 (default: similar=deny) Whether a new password is allowed to be
85 similar to the old one. The passwords are considered to be simi‐
86 lar when there is a sufficiently long common substring and the
87 new password with the substring partially discounted would be
88 weak.
89 wordlist=FILE
91 Deny passwords that are based on lines of the tiny external text
92 FILE, which can reasonably be e.g. a list of a few thousand com‐
93 mon passwords. Common dictionary words may also reasonably be
94 included, especially in a local language other than English, or
95 longer yet common English words. (passwdqc includes a list of a
96 few thousand common English words of lengths from 3 to 6 built
97 in. Any word list possibly specified with this option is used in
98 addition to the built-in word list.)
99 Substring matching and discounting will be used if the match set‐
101 ting above is non-zero. Please note that this is very ineffi‐
102 cient, and isn't to be used with large wordlists.
103 denylist=FILE
105 Deny passwords or passphrases directly appearing in the tiny ex‐
106 ternal text FILE. That file can reasonably be e.g. a list of
107 common passwords if only a relaxed policy is desired and stricter
108 checks are thus disabled (using their separate options). Such
109 policy would only be somewhat effective against online/remote at‐
110 tacks, but not against offline attacks on hashed passwords.
111 filter=FILE
113 Deny passwords or passphrases directly appearing in a maybe huge
114 binary filter FILE created with pwqfilter. This is very effi‐
115 cient, needing at most two random disk reads per query. A filter
116 created from millions of leaked passwords can reasonably be used
117 on top of passwdqc's other checks to further reduce the number of
118 passing yet weak passwords without causing unreasonable inconve‐
119 nience (as e.g. higher minimum lengths and character set require‐
120 ments could).
121 config=FILE
123 Load config FILE in the passwdqc.conf format. This file may de‐
124 fine any options described in passwdqc.conf(5), but only the min,
125 max, passphrase, match, and config options are honored by
126 pwqcheck.
127 -1 Read just 1 line (new passphrase). This is needed to use
129 pwqcheck as the passwordcheck program on OpenBSD - e.g., with
130 ":passwordcheck=/usr/bin/pwqcheck -1:\" (without the quotes, but
131 with the trailing backslash) in the "default" section in
132 /etc/login.conf.
133 -2 Read just 2 lines (new and old passphrases).
135 --multi
137 Check multiple passphrases (until EOF). This option may be used
138 on its own or along with the -1 or -2 options. pwqcheck will
139 read 1, 2, or 3 lines and will output one line per passphrase to
140 check. The lines will start with either OK or a message explain‐
141 ing why the passphrase did not pass the checks, followed by a
142 colon and a space, and finally followed by the passphrase. The
143 explanatory message is guaranteed to not include a colon. With
144 this option, the exit status of pwqcheck depends solely on
145 whether there were any errors preventing the strength of
146 passphrases from being fully checked or not. A primary use for
147 this option is to test different policies and/or different ver‐
148 sions of passwdqc on large passphrase lists.
149 --version
151 Output pwqcheck program version and exit.
152 -h, --help
154 Output pwqcheck help text and exit.
155
157 pwqcheck exits with non-zero status when it encounters invalid config
158 file, invalid option, invalid parameter value, invalid data in standard
159 input, and in any case when it fails to check passphrase strength. With‐
160 out the --multi option, pwqcheck also exits with non-zero status when it
161 detects a weak passphrase.
162
164 /etc/passwdqc.conf (not read unless this suggested file location is spec‐
165 ified with the config=/etc/passwdqc.conf option).
166
168 pwqgen(1), libpasswdqc(3), passwd(5), passwdqc.conf(5), pam_passwdqc(8).
169 https://www.openwall.com/passwdqc/
171
173 The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar De‐
174 signer. The pwqcheck program was originally written for ALT GNU/*/Linux
175 by Dmitry V. Levin, indirectly reusing code from pam_passwdqc (via lib‐
176 passwdqc). This manual page (derived from the pam_passwdqc documenta‐
177 tion) was written for Openwall GNU/*/Linux by Dmitry V. Levin.
178Openwall Project December 30, 2020 Openwall Project