PWQFILTER(1)

💖 PWQFILTER 💖

okay bestie, so <rainbow>pwqfilter</rainbow> is a thing you can run from the shell, and it lives in section 1 of the manual (that's the "General Commands Manual" zone, the one for actual commands you type). She's a little ✨binary passphrase filter file✨ manager and she is, no exaggeration, that girl.

---

🌸 SYNOPSIS 🌸

pwqfilter [options]

that's it. that's the whole vibe. she takes options, she reads your input from stdin, she serves. 💅

---

🦋 DESCRIPTION 🦋

so <pink>pwqfilter</pink> searches, creates, or updates binary passphrase filter files — and those same files can also be used with pwqcheck(1) and pam_passwdqc(8). group project energy fr.

You tell her which input and/or output binary filter files you want via their matching command-line options. Meanwhile the passphrases you wanna look up or add — or their hashes — get read from standard input. That's the deal. 🫶

Here's the cute part: <purple>pwqfilter</purple> works on arbitrary plain text strings or hex-encoded hashes, which means you can absolutely reuse her in place of grep(1) for tons of stuff that has nothing to do with passphrases or security. Not me using a security tool for my little grep side quest 😭 iconic behaviour honestly.

Now for the binary filters themselves: <pink>pwqfilter</pink> — and therefore the rest of passwdqc — currently uses an improved cuckoo filter, which is a probabilistic data structure. And yes that means:

⚠️ Occasional false positives are possible (fewer than 1 in a billion), but false negatives are not. So she might say "yes bestie I found it" when she didn't (rare!!), but she will never, ever hide something from you. 💀

---

👑 MODE OPTIONS 👑

• --lookup — Look up plaintexts or hashes from standard input against an existing filter. This is the default mode, so if you just run her with no mode, this is what you get. no notes. ✨
• --status — Report usage statistics for an existing filter. Receipts, basically. 🧾
• --create=CAPACITY — Create a brand new filter with CAPACITY entries, reading the initial set of plaintexts or hashes from standard input.

Real talk though: 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. So your specified CAPACITY should be higher than the maximum expected number of entries by at least 2.04%. Do the math, bestie, don't set yourself up. 🎀

• --insert — Insert (add) entries into an existing filter, reading the plaintexts or hashes from standard input. sliding into her DMs, functionally.
• --test-fp-rate — Estimate the false positive rate (FP rate) of a filter. You can use this one on its own or alongside another mode — in which case the test runs after that other mode's action. multitasking queen. 💅

---

🌈 OPTIMIZATION OPTIONS 🌈

These can be used with --create or --insert. glow-up options, basically.

• --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%. short-term sacrifice, long-term slay. ✨
• --optimize-fp-rate-at-high-load — Better than default FP rate at load ~95% to 98%, but a lot worse below ~90%. she's built for the top, not the middle, and she's not sorry. 🔥

---

🎀 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.

heads up: this option is later implied for further actions on filters that were created with it specified and no --hash-*, because <pink>pwqfilter</pink> has no way to know what hash type such filters use. she's not psychic bestie, she's just honest. 🙈

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

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

And about MD4 being, uh, cryptographically ancient? Cuckoo filters' use of a hash function is non-cryptographic, hence MD4's otherwise inadequate cryptographic security is irrelevant. so she's fine. she's literally fine. 💅

• --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). very specific, very valid. 🌸

---

✨ LOOKUP OUTPUT MODIFIER OPTIONS ✨

These are similar to those of grep(1), so if you already know grep you're gonna feel so at home.

• -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. she's a yapper when you ask her to be. 🗣️
• --version — Output <pink>pwqfilter</pink> program version and exit.
• -h, --help — Output <pink>pwqfilter</pink> help text and exit.

---

💀 EXIT STATUS 💀

When looking up against an existing filter, <pink>pwqfilter</pink> exits with:

• 0 if selected plaintexts or hashes are found 🎉
• 1 if not found 😔
• 2 on error 💀

These exit codes are compatible with those of grep(1) — matching besties, periodt.

In all other modes, <pink>pwqfilter</pink> 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. king behaviour, we love to see it. 👑

---

and that's the whole page bestie!! this one's from the Openwall Project, dated January 25, 2021 — so go forth, filter those passphrases, and remember: no false negatives, only vibes. 💖✨🎀🦋🌸💅