add pam_bloom_check section

1 files changed, 43 insertions, 0 deletions

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