www.LinuxHowtos.org

PWQFILTER

Section: User Commands (1)
Index Return to Main Contents

BSD mandoc
Openwall Project

NAME

pwqfilter - Manage binary passphrase filter files

SYNOPSIS

[options ]

DESCRIPTION

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

Op Ar options works on arbitrary plain text strings or he-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, Op Ar options 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.
-tes-f-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

-optimiz-f-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%.
-optimiz-f-rat-a-hig-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

-pr-hashed

Look up or insert by he-encoded hashes, not plaintexts.

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

-has-md4

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

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

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

-has-ntl-cp1252

Hash assumed CP1252 encoding plaintexts with NTLM prior to lookup or insert, or specify that the pr-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 (no-)matching lines instead of the lines themselves.
-n ,-lin-number: Prefix each line with its number in the input stream.
-v ,-inver-match: Output or count no-matching lines.

GENERAL OPTIONS

-verbose: Output additional information.
-version: Output Op Ar options program version and exit.
-h ,-help: Output Op Ar options help text and exit.

EXIT STATUS

When looking up against an existing filter, Op Ar options 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, Op Ar options exits with 0 on success and 2 on error.

AUTHORS

Op Ar options and this manual page were written by Solar Designer.