Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/skx/pam_pwnd

A PAM module to test passwords against previous leaks at haveibeenpwned.com
https://github.com/skx/pam_pwnd

haveibeenpwned linux pam pam-module security ssh sudo

Last synced: about 2 months ago
JSON representation

A PAM module to test passwords against previous leaks at haveibeenpwned.com

Awesome Lists containing this project

README 

        
[![license](https://img.shields.io/github/license/skx/pam_pwnd.svg)](https://github.com/skx/pam_pwnd/blob/master/LICENSE)

[![Release](https://img.shields.io/github/release/skx/pam_pwnd.svg)](https://github.com/skx/pam_pwnd/releases/latest)



# pam_pwnd



This repository contains a simple PAM module for testing whether a

password being used for authentication has been listed in the

[have I been pwned](https://haveibeenpwned.com/) database.



Note that in the documentation here we focus upon ensuring that a password used for `sudo` has not been compromised, but PAM-modules can be used for many purposes, from handling SSH-access, to permitting HTTP-based authentication.  There is nothing `sudo`-specific about our code so this module can be useful in many contexts.



## Sponsorship



The development of this module was sponsored by three individuals who made charitable donations.  (Anonymous primarily because I didn't ask for permission to name them publicly.)



If you wish to "sponsor this" software, and be listed here, just [email me](https://steve.kemp.fi/) a receipt of your donation.  I support the [RNLI](https://en.wikipedia.org/wiki/Royal_National_Lifeboat_Institution), but feel free to pick whatever charity you wish.



The code is released under the [BSD-license](LICENSE) so you can fork it, improve it, use it, and enjoy it!  Feel free to report bugs, or feature-suggestions on the [issue-page](https://github.com/skx/pam_pwnd/issues).



## Compilation



These are the dependencies I expect you would need for compiling the project:



* For fetching a remote URI we use `libcurl`:

  * `apt-get install libcurl4-gnutls-dev`

* For compiling PAM modules you'll need the appropriate development package:

  * `apt-get install libpam0g-dev`



Assuming you have the dependencies installed then compilation should only require a simple `make`:



    $ make

    gcc -fPIC -c pam_pwnd.c -lpam -lpam_misc -lpamc

    gcc -fPIC -c pwn_chk.c  -lcurl

    gcc -fPIC -c sha1.c

    ld -x --shared -o pam_pwnd.so pam_pwnd.o pwn_chk.o sha1.o -lcurl -lpam -lpam_misc -lpamc



For completeness you can also run the basic test-cases included in the repository, but note that to do that you will require network-access:



    $ make test

    ./pam_test

    ..



(This might be an issue if you run the tests as part of a build-process upon a CI/CD system which doesn't permit outgoing network access.)



## Installation & Configuration



Once you have compiled the code you should copy the resulting file `pam_pwnd.so` to the appropriate PAM-directory upon your system.  In my case that means running this command:



    sudo install pam_pwnd.so  /lib/x86_64-linux-gnu/security/



The final step is to enable the module, by editing the appropriate PAM configuration file.



In my case I'm using SSH keys for authentication, and I'm only concerned with ensuring that no known-bad passwords are used with `sudo`.  I append the following line to `/etc/pamd.d/sudo`:



    auth   required   pam_pwnd.so  try_first_pass



The complete file, on an Ubuntu system, might then look like this:



      #%PAM-1.0

      session    required   pam_env.so readenv=1 user_readenv=0

      session    required   pam_env.so readenv=1 envfile=/etc/default/locale user_readenv=0

      @include common-auth

      @include common-account

      @include common-session-noninteractive

      auth   required   pam_pwnd.so  try_first_pass



Upon the "stretch" release of Debian GNU/Linux the file has these contents:



      #%PAM-1.0



      @include common-auth

      @include common-account

      @include common-session-noninteractive

      auth   required   pam_pwnd.so  try_first_pass



Regardless of what your file looks like, once you've added the reference to `pam_pwnd.so`, you should then be ready to test the module hasn't broken your system by reseting the `sudo` cache, and re-authenticating:



     frodo ~ $ sudo -k

     frodo ~ $ sudo su -

     [sudo] password for skx:

     root@frodo:~#



Assuming nothing is broken you should:



* Be prompted for your password.

  * Only once.

* Receive your root-prompt.

* See the results of the module logged to syslog.



If things are horribly broken, such that you get segfaults or failures from _this_ module then you will probably be unable to run `sudo` to fix them, so for the duration of any installation you should ensure you have an open terminal/connection with `root` privileges.



The module will log its results to syslog, search for `pam_pwnd` to see them.



## Security Notes



The code makes a single outgoing HTTP-request for each authentication

request:



* The outgoing request contains the first five characters of your __hashed__ password.

   * i.e. If you password is "secret" it is first hashed to `e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4`.

   * Then an outgoing request is made with the characters `e5e9f`.



If the API-lookup request fails then we default to failing-open, allowing the authentication to proceed.   (We assume other modules will actually validate the password, if we allowed a failure to invoke the API we'd deny all PAM-based operations in the event your DNS, networking, or similar things were broken.)



There are zero memory allocations in this module, which should ensure that we don't leak anything.  Instead we generate a single temporary file to hold the results of our HTTP-response, and that temporary file is cleaned up after use.



## Testing Notes



There is a simple test-driver included in this project which exercises some of

the code, it is not designed to be a complete test-case, nor to perform exhaustive testing.



If you're planning to submit pull-requests that change the code you should ensure the tests pass even with your additions:



    $ make test



## Feedback



Bug reports welcome.



Steve

--