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.

Openwall Project                                January 25, 2021                                    PWQFILTER(1)