pwqfilter(1)

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

NAME

4     pwqfilter — Manage binary passphrase filter files
5

SYNOPSIS

7     pwqfilter [options]
8

DESCRIPTION

10     The pwqfilter program searches, creates, or updates binary passphrase
11     filter files, which can also be used with pwqcheck(1) and
12     pam_passwdqc(8).  Input and/or output binary filter files are specified
13     via their corresponding command-line options, whereas passphrases to look
14     up or add, or their hashes, are read from standard input.
15
16     pwqfilter works on arbitrary plain text strings or hex-encoded hashes,
17     and thus can also be reused in lieu of grep(1) for many purposes unre‐
18     lated to passphrases and security.
19
20     For the binary filters, pwqfilter and thus the rest of passwdqc currently
21     use an improved cuckoo filter, which is a probabilistic data structure.
22     Occasional false positives are possible (fewer than 1 in a billion), but
23     false negatives are not.
24

MODE OPTIONS

26     --lookup
27             Look up plaintexts or hashes on standard input against an exist‐
28             ing filter.  This is the default mode.
29
30     --status
31             Report usage statistics for an existing filter.
32
33     --create=CAPACITY
34             Create a new filter with CAPACITY entries, reading the initial
35             set of plaintexts or hashes from standard input.
36
37             The currently implemented cuckoo filter has a typical maximum
38             load of around 98% (as long as there are no duplicate inputs and
39             the hashes are unbiased, or less otherwise).  The specified CA‐
40             PACITY should thus be higher than the maximum expected number of
41             entries by at least 2.04%.
42
43     --insert
44             Insert (add) entries into an existing filter, reading the plain‐
45             texts or hashes from standard input.
46
47     --test-fp-rate
48             Estimate the false positive rate (FP rate) of a filter.  This op‐
49             tion can be used on its own or along with another mode, in which
50             case the test is performed after that other mode's action.
51

OPTIMIZATION OPTIONS

53     These can be used with --create or --insert.
54
55     --optimize-fp-rate
56             Better than default FP rate at a cost of briefly slower inserts
57             after a load of 30% to 40% and then again after 60% to 70%.
58
59     --optimize-fp-rate-at-high-load
60             Better than default FP rate at load ~95% to 98%, a lot worse be‐
61             low ~90%.
62

INPUT AND OUTPUT OPTIONS

64     -f FILE, --filter=FILE
65             Read an existing filter from FILE
66
67     -o FILE, --output=FILE
68             Write a new or modified filter to FILE
69
70     --pre-hashed
71             Look up or insert by hex-encoded hashes, not plaintexts.
72
73             This option is later implied for further actions on filters cre‐
74             ated with it specified and no --hash-*, because pwqfilter has no
75             way to know what hash type such filters use.
76
77     --hash-md4
78             Hash plaintexts with MD4 prior to lookup or insert.  This is the
79             default for new filters.
80
81             When used with --pre-hashed, specify that the pre-hashing was
82             done with MD4.
83
84             Cuckoo filters' use of a hash function is non-cryptographic,
85             hence MD4's otherwise inadequate cryptographic security is irrel‐
86             evant.
87
88     --hash-ntlm-cp1252
89             Hash assumed CP1252 encoding plaintexts with NTLM prior to lookup
90             or insert, or specify that the pre-hashing was done that way
91             (e.g., like it was in a HIBP v7 download).
92

LOOKUP OUTPUT MODIFIER OPTIONS

94     These are similar to those of grep(1).
95
96     -c, --count
97             Output a count of (non-)matching lines instead of the lines them‐
98             selves.
99
100     -n, --line-number
101             Prefix each line with its number in the input stream.
102
103     -v, --invert-match
104             Output or count non-matching lines.
105

GENERAL OPTIONS

107     --verbose
108             Output additional information.
109
110     --version
111             Output pwqfilter program version and exit.
112
113     -h, --help
114             Output pwqfilter help text and exit.
115

EXIT STATUS

117     When looking up against an existing filter, pwqfilter exits with 0 if se‐
118     lected plaintexts or hashes are found, 1 if not found, or 2 on error.
119     These exit codes are compatible with those of grep(1).  In other modes,
120     pwqfilter exits with 0 on success and 2 on error.
121

AUTHORS

128     pwqfilter and this manual page were written by Solar Designer.
129
130Openwall Project               January 25, 2021               Openwall Project