1PWQCHECK(1)               BSD General Commands Manual              PWQCHECK(1)
2

NAME

4     pwqcheck — Check passphrase quality
5

SYNOPSIS

7     pwqcheck [options]
8

DESCRIPTION

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
13           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
17     There are a number of supported options, which can be used to control the
18     pwqcheck behavior.
19
20     pwqcheck prints OK on success.  Scripts invoking pwqcheck are suggested
21     to check for both a zero exit status and the OK line.
22

OPTIONS

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
31             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
37             N1 is used for passwords consisting of characters from two char‐
38             acter classes that do not meet the requirements for a passphrase.
39
40             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
44             N3 and N4 are used for passwords consisting of characters from
45             three and four character classes, respectively.
46
47             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
51             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
55     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
64             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
67     passphrase=N
68             (default: passphrase=3) The number of words required for a
69             passphrase.
70
71     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
80             The substring search is case-insensitive and is able to detect
81             and remove a common substring spelled backwards.
82
83     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
90     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
100             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
104     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
112     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
122     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
128     -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
134     -2      Read just 2 lines (new and old passphrases).
135
136     --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
150     --version
151             Output pwqcheck program version and exit.
152
153     -h, --help
154             Output pwqcheck help text and exit.
155

EXIT STATUS

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

FILES

164     /etc/passwdqc.conf (not read unless this suggested file location is spec‐
165     ified with the config=/etc/passwdqc.conf option).
166

SEE ALSO

168     pwqgen(1), libpasswdqc(3), passwd(5), passwdqc.conf(5), pam_passwdqc(8).
169
170     https://www.openwall.com/passwdqc/
171

AUTHORS

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.
178
179Openwall Project               December 30, 2020              Openwall Project
Impressum