1 files changed, 290 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..898b5fa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,290 @@
+# pam_bloom
+
+`pam_bloom` is a Linux PAM password module that rejects passwords
+found in one or more Bloom filters.
+
+It can be used to prevent users from choosing passwords found in known
+password lists such as RockYou, organization-specific password lists,
+or other administrator-provided dictionaries.
+
+The package includes:
+
+* `pam_bloom.so` — PAM module
+* `pam_bloom_create` — utility for creating Bloom filters from wordlists
+
+
+WARNING: This software modifies PAM configuration. There is always
+risk involved with re-configuring the system's authentication system
+such as locking legitimate users out. Administrators are responsible
+for testing their PAM configuration before deployment.
+
+## Requirements
+
+On Debian or Ubuntu, install the compiler, PAM development files, and
+other build tools:
+
+```sh
+sudo apt update
+sudo apt install build-essential libpam0g-dev
+```
+
+The Makefile also uses `dpkg-architecture` to determine Debian's
+multiarch PAM module directory. This is normally already available on
+Debian systems.
+
+## Build
+
+Clone or unpack the source and run:
+
+```sh
+make
+```
+
+This builds:
+
+```text
+pam_bloom.so
+pam_bloom_create
+```
+
+Install them with:
+
+```sh
+sudo make install
+```
+
+On a typical x86-64 Debian system this installs:
+
+```text
+/usr/bin/pam_bloom_create
+/usr/lib/x86_64-linux-gnu/security/pam_bloom.so
+/etc/security/pam_bloom/filters.d/
+```
+
+Finally, run `pam-auth-update` to enable `pam_bloom`:
+
+```sh
+sudo pam-auth-update
+```
+
+## Create a Bloom filter
+
+`pam_bloom_create` creates a Bloom filter from a wordlist:
+
+```sh
+pam_bloom_create WORDLIST OUTPUT NAME
+```
+
+For example:
+
+```sh
+pam_bloom_create rockyou.txt rockyou.bloom rockyou
+```
+
+The default false-positive rate is `0.001`.
+
+A different false-positive rate can be selected with `-p`:
+
+```sh
+pam_bloom_create -p 0.000001 rockyou.txt rockyou.bloom rockyou
+```
+
+Install the resulting filter:
+
+```sh
+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.
+
+## Configure PAM
+
+**Be careful when modifying PAM configuration. An incorrect PAM
+configuration can prevent authentication or password changes. Keep a
+root session open while testing changes.**
+
+On Debian and Ubuntu, edit:
+
+```text
+/etc/pam.d/common-password
+```
+
+Add `pam_bloom.so` before the `pam_unix.so` password entry.
+
+For example:
+
+```text
+password requisite pam_bloom.so
+password [success=1 default=ignore] pam_unix.so obscure yescrypt use_authtok
+password requisite pam_deny.so
+password required pam_permit.so
+```
+
+The important points are that `pam_bloom.so` runs before `pam_unix.so`
+and that `pam_unix.so` uses `use_authtok`.
+
+`pam_bloom` obtains the new password through PAM, checks it against
+the installed Bloom filters, and rejects it if a match is
+found. `pam_unix` then uses the same password token.
+
+## Test
+
+Change a test user's password normally:
+
+```sh
+passwd
+```
+
+Try selecting a password contained in one of the installed wordlists.
+
+`pam_bloom` should reject the password and identify the Bloom filter
+that matched it.
+
+A password that does not match any filter is passed on to the rest of
+the PAM password stack.
+
+## Custom filter directory
+
+The default filter directory is:
+
+```text
+/etc/security/pam_bloom/filters.d
+```
+
+A different directory can be configured with the PAM `dir=` option:
+
+```text
+password requisite pam_bloom.so dir=/srv/security/bloom
+```
+
+The directory and filter files must satisfy `pam_bloom`'s ownership
+and permission checks.
+
+## Included RockYou filter
+
+`pam_bloom` includes a pre-built Bloom filter generated from the
+RockYou password list:
+
+```text
+rockyou.txt.bloom
+```
+
+The supplied filter was created with a false-positive rate of:
+
+```text
+0.001
+```
+
+This filter is installed to
+`/etc/security/pam_bloom/filters.d/rockyou.txt.bloom` by default.
+
+Because this is a Bloom filter, there is a small probability of false
+positives. With the supplied filter, the configured false-positive
+probability is 0.001 (approximately 0.1%). In the 1 in 1000 chance
+that there is a false-positive, the user will simply have to choose
+another password.
+
+The original RockYou plaintext wordlist is not required at runtime.
+
+## Creating your own filters
+
+Additional Bloom filters can be created with:
+
+```sh
+pam_bloom_create WORDLIST OUTPUT NAME
+```
+
+For example:
+
+```sh
+pam_bloom_create passwords.txt passwords.bloom passwords
+```
+
+The default false-positive rate is `0.001`, the same value used for
+the supplied RockYou filter.
+
+A different false-positive rate can be selected with `-p`:
+
+```sh
+pam_bloom_create -p 0.000001 passwords.txt passwords.bloom passwords
+```
+
+Install the resulting filter by copying it into the filter directory:
+
+```sh
+sudo cp passwords.bloom /etc/security/pam_bloom/filters.d/
+```
+
+Multiple `.bloom` files may be installed at the same time. A password
+matching any installed filter is rejected.
+
+
+
+## Adding multiple filters
+
+Multiple filters can be installed simply by copying additional
+`.bloom` files into the filter directory:
+
+```text
+/etc/security/pam_bloom/filters.d/rockyou.bloom
+/etc/security/pam_bloom/filters.d/company.bloom
+/etc/security/pam_bloom/filters.d/banned-passwords.bloom
+```
+
+If the candidate password matches **any** filter, it is rejected.
+
+## Removing a filter
+
+Remove the corresponding `.bloom` file:
+
+```sh
+sudo rm /etc/security/pam_bloom/filters.d/rockyou.bloom
+```
+
+No rebuild of the PAM module is necessary.
+
+## Uninstall
+
+uninstall the binaries:
+
+```sh
+sudo make uninstall
+```
+
+`make uninstall` deliberately does not remove:
+
+```text
+/etc/security/pam_bloom/filters.d/
+```
+
+or any Bloom filters stored there. Administrator-created filters are
+preserved.
+
+Finally, update PAM configuration to remove `pam_bloom`:
+
+```sh
+sudo pam-auth-update
+```
+
+Alternatively, edit `/etc/pam.d/common-password` to remove `pam_bloom`
+
+## Security
+
+Bloom filters can produce false positives. The false-positive
+probability can be controlled when creating a filter with
+`pam_bloom_create -p`.
+
+The PAM module treats installed Bloom filters as trusted
+administrative data. Filter directories and files are checked for
+appropriate ownership and permissions before they are used.
+
+Malformed, inaccessible, or otherwise invalid filters cause the
+password check to fail closed rather than silently bypassing the
+password policy.
+
+## Murmur3
+
+The mmh3 implementation by Austin Appleby was referenced when
+implementing this. Appleby's implementation was released under the
+public domain.