From f70ce379de6261733dc71279c76fc76a210285e1 Mon Sep 17 00:00:00 2001 From: Daniel Roberson Date: Sun, 13 Sep 2026 07:44:32 -0700 Subject: initial commit --- README.md | 290 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 README.md (limited to 'README.md') 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. -- cgit v1.2.3