From 1c48b44a8350424b2963cda36cb63b0ecc28ed43 Mon Sep 17 00:00:00 2001
From: Daniel Roberson <daniel@badoperation.net>
Date: Sun, 13 Sep 2026 08:47:28 -0700
Subject: add pam_bloom_check section

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 898b5fa..9b683fe 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,49 @@ sudo cp rockyou.bloom /etc/security/pam_bloom/filters.d/
 The PAM module checks every `.bloom` file in this directory. A
 password matching any installed filter is rejected.
 
+## Checking passwords from the command line
+
+`pam_bloom_check` provides a command-line interface to the same Bloom
+filter database used by the PAM module. It is intended for scripts and
+applications that do not use PAM for password changes.
+
+The password is read as a single line from standard input:
+
+```sh
+printf '%s\n' 'candidate-password' | pam_bloom_check
+```
+
+`pam_bloom_check` uses its exit status to report the result:
+
+| Exit status | Meaning                                          |
+| ----------- | ------------------------------------------------ |
+| `0`         | Password was not found in any filter             |
+| `1`         | Password matched a filter and should be rejected |
+| `2`         | An error occurred while checking the filters     |
+
+For example:
+
+```sh
+printf '%s\n' 'password123' | pam_bloom_check
+
+case $? in
+    0) echo "Password accepted" ;;
+    1) echo "Password rejected" ;;
+    *) echo "Unable to check password policy" ;;
+esac
+```
+
+Passwords are read from standard input rather than command line
+arguments so that they do not appear in the process argument list.
+
+The tool does not provide an interactive password prompt; programs
+that require interactive input should read the password without
+terminal echo and pass it to `pam_bloom_check` through standard input.
+
+This makes `pam_bloom_check` suitable for integrating the Bloom filter
+policy with password management tools that do not invoke PAM
+themselves.
+
 ## Configure PAM
 
 **Be careful when modifying PAM configuration. An incorrect PAM
-- 
cgit v1.2.3