NAME

     pwqfilter — Manage binary passphrase filter files

SYNOPSIS

     pwqfilter [options]

DESCRIPTION

     The pwqfilter program searches, creates, or updates binary passphrase filter files, which
     can also be used with pwqcheck(1) and pam_passwdqc(8).  Input and/or output binary filter
     files are specified via their corresponding command-line options, whereas passphrases to
     look up or add, or their hashes, are read from standard input.

     pwqfilter works on arbitrary plain text strings or hex-encoded hashes, and thus can also be
     reused in lieu of grep(1) for many purposes unrelated to passphrases and security.

     For the binary filters, pwqfilter and thus the rest of passwdqc currently use an improved
     cuckoo filter, which is a probabilistic data structure.  Occasional false positives are
     possible (fewer than 1 in a billion), but false negatives are not.

MODE OPTIONS

     --lookup
             Look up plaintexts or hashes on standard input against an existing filter.  This is
             the default mode.

     --status
             Report usage statistics for an existing filter.

     --create=CAPACITY
             Create a new filter with CAPACITY entries, reading the initial set of plaintexts or
             hashes from standard input.

             The currently implemented cuckoo filter has a typical maximum load of around 98% (as
             long as there are no duplicate inputs and the hashes are unbiased, or less
             otherwise).  The specified CAPACITY should thus be higher than the maximum expected
             number of entries by at least 2.04%.

     --insert
             Insert (add) entries into an existing filter, reading the plaintexts or hashes from
             standard input.

     --test-fp-rate
             Estimate the false positive rate (FP rate) of a filter.  This option can be used on
             its own or along with another mode, in which case the test is performed after that
             other mode's action.

OPTIMIZATION OPTIONS

     These can be used with --create or --insert.

     --optimize-fp-rate
             Better than default FP rate at a cost of briefly slower inserts after a load of 30%
             to 40% and then again after 60% to 70%.

     --optimize-fp-rate-at-high-load
             Better than default FP rate at load ~95% to 98%, a lot worse below ~90%.

INPUT AND OUTPUT OPTIONS

     -f FILE, --filter=FILE
             Read an existing filter from FILE

     -o FILE, --output=FILE
             Write a new or modified filter to FILE

     --pre-hashed
             Look up or insert by hex-encoded hashes, not plaintexts.

             This option is later implied for further actions on filters created with it
             specified and no --hash-*, because pwqfilter has no way to know what hash type such
             filters use.

     --hash-md4
             Hash plaintexts with MD4 prior to lookup or insert.  This is the default for new
             filters.

             When used with --pre-hashed, specify that the pre-hashing was done with MD4.

             Cuckoo filters' use of a hash function is non-cryptographic, hence MD4's otherwise
             inadequate cryptographic security is irrelevant.

     --hash-ntlm-cp1252
             Hash assumed CP1252 encoding plaintexts with NTLM prior to lookup or insert, or
             specify that the pre-hashing was done that way (e.g., like it was in a HIBP v7
             download).

LOOKUP OUTPUT MODIFIER OPTIONS

     These are similar to those of grep(1).

     -c, --count
             Output a count of (non-)matching lines instead of the lines themselves.

     -n, --line-number
             Prefix each line with its number in the input stream.

     -v, --invert-match
             Output or count non-matching lines.

GENERAL OPTIONS

     --verbose
             Output additional information.

     --version
             Output pwqfilter program version and exit.

     -h, --help
             Output pwqfilter help text and exit.

EXIT STATUS

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

SEE ALSO

     grep(1), pwqcheck(1), passwdqc.conf(5), pam_passwdqc(8).

     https://www.openwall.com/passwdqc/

AUTHORS

     pwqfilter and this manual page were written by Solar Designer.