YubiHSM PAM module backend
Python
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README
yhsmpam.py

README

YHSMPAM

Copyright 2011 Google Inc.

YubiHSM for unix authentication.


Intro
=====
You can use YubiHSM to encrypt all your passwords using a key that's
only stored inside the YubiHSM. There is then no way to snarf
/etc/shadow and do offline password cracking.


Installation instructions
=========================

1. Set up your YubiHSM (if you haven't already)
-----------------------------------------------
(this is a quick rehash of chapter 8 of the YubiHSM reference manual)

Plug it in and run "minicom -D /dev/ttyACM0".

If the prompt is "HSM>" then it's already set up.

If the prompt is "WSAPI>" then it's in WSAPI mode. Run "hsm" and set
it up according to the instructions in chapter 8.4 of the YubiHSM
reference manual.

If you don't get a prompt at all, then unplug it and hold down the
configuration button while inserting it, and try again.


2. Set up a crypto key for YHSMPAM
----------------------------------
Go to the YubiHSM configuration mode (unplug, hold down config button
while re-inserting).

Run "minicom -D /dev/ttyACM0". You should get a "HSM>" prompt.

List your existing keys using "keylist". Either pick an existing key
number or generate a new using "keygen 8000 1 20" (to generate key
with handle 8000).

Type "exit" to make the YubiHSM go into HSM mode.


3. Configure YHSMPAM
--------------------
$ sudo mkdir -m 700 /etc/yhsmpam
$ sudo mkdir -m 700 /etc/yhsmpam/users
$ sudo tee /etc/yhsmpam/yhsmpam.conf > /dev/null
key_handle 8000
device /dev/ttyACM0
^D

If your YubiHSM is /dev/ttyACM0 then you can skip that in the
config. It's the default.

Mode 700 on the directories may prevent pam_externalpass from seeing
the user config files for some PAM-enabled programs such as su. A fix
is being worked on.


4. Set password for a test user
-------------------------------
First copy yhsmpam.py somewhere nice in your admin PATH, such as
/usr/local/sbin/yhsmpam (without .py). It will be used by the PAM
module, so don't put it in your home directory.

$ sudo yhsmpam set testuser
User password: secret


Verify that it was written:
$ sudo cat /etc/yhsmpam/users/testuser
071234002600 3821309218309821038213218392103213123123ee12312893182903


5. Test the password
--------------------
% sudo yhsmpam check testuser
User password: secret
Password correct


6. Install pam_externalpass
---------------------------
Compile and install pam_externalpass:
<https://github.com/ThomasHabets/pam_externalpass>

  git clone https://github.com/ThomasHabets/pam_externalpass.git
  cd pam_externalpass
  ./configure
  make
  make install


7. Configure PAM
----------------
Add this to /etc/pam.d/common-auth before the pam_unix line:
  auth sufficient /usr/local/lib/libpam_externalpass.so \
             exec=/usr/local/sbin/yhsmpam \
             prompt=HSM_Password:_ \
             userconf=/etc/yhsmpam/users/%u


8. Try logging in as the test user
----------------------------------
Use ssh, su or whatever. If you put the line in /etc/pam.d/common-auth
it should work for everything (except su, see above).