pam_usbauth 0.3

pam_usbauth is a module for PAM allowing end-users to locally authenticate via USB storage devices. USBAuth currently supports user-dependent authentication via password-hashing as well as one-time-password mechanisms, which make the verification process via USB-dongles much more secure. In addition, USBAuth comes with USB device serial checking support, so attackers wont be able to grab and copy your device easily (if this is the case, the device will be rejected).

Install instructions for Debian

1.Download the Debian package.
2.Install as root, by typing dpkg -i usbauth_0.2-1_i386.deb.
3.Use the program uapasswd for activating USBAuth. You may have a look at the manpage of uapasswd(1) for detailed instructions, but the following command will configure USBAuth for user root. The USB device is located at /dev/sda1:

uapasswd -u root -p mypassword -d /dev/sda1 -d /dev/sdb1 -w -o if you wish to use USB device ID binding, get the serial number of your USB storage device out of /proc/bus/usb/devices, and call:

uapasswd -u root -p mypassword -d /dev/sda1 -d /dev/sdb1 -w -o -s serial -c

4.Follow step 5, below .. (configuration of PAM to use pam_usbauth.so in /etc/pam.d/)

How shall I use it?

1. Download the source

2. Compile and install (both done via "make") as root (you need to have PAM development files and libraries, as well as OpenSSL installed)

3. Get a USB storage device. You can use every writeable USB-stick device, but Id recommend to make an extra partition, 1024k is more than enough. Be sure you know which device/partition this is (e.g. /dev/sda1). The selected partition doesnt need to be formated, the data will be in written RAW format onto the device - this means, you also dont have to mount it. Not now, and not when actually using pam_usbauth for authentication. Be aware, that you can still use all other partitions on the device for storage!

4. To generate the config file, call at least "./uapasswd -u username -p cleartextpassword -d /dev/sda1 -w". uapasswd must be called as root, because it needs to have write permissions either on the USB device, and on the config file in /etc. Check the manual page for more options, there are severl nice features available.

WARNING: The device which is given first, will be used for writing! Dont choose a device where real data is stored, like harddisks!

(4b. Alternatively, you can manually edit /etc/usbauth.conf; for syntax see this file)

5. Set up the applications you want to use with the module, changing the files for the programs youd like to use with usbauth in /etc/pam.d/. Normally, such files define something like:

auth sufficient pam_unix.so, or
auth -auth

Just comment this line, and write:

auth sufficient pam_usbauth.so

Id strongly recomment to accept a Unix-fallback, so you can still get access with your normal password:

auth sufficient pam_usbauth.so
auth sufficient pam_unix.so
auth required pam_deny.so

Please note that, as long as pam_usbauth is in alpha state, it may be more secure to use:

auth sufficient pam_unix.so
auth sufficient pam_usbauth.so
auth required pam_deny.so

Then, pam_unix (the standard passwort authentication) will be used at first. If you want to get authenticated via USB, just type a blank password and PAM will try the next module in queue. This makes sense, because if you are in the very unlikely situation to download an unstable source from SVN and pam_usbauth.so is corrupt, PAM may not switch to the next module (pam_unix) and youd be not able to use the application anymore if you havnt direct root access to /etc when doing this. However, this case has never been reported and should be very, very unlikely to happen.

(5b.) If you have used the -w switch, uapasswd has hopefully already written the data to your USB device. If not, save your key (or the hash value of your key; whatever is defined in /etc/usbauth.conf) in a plain text file with carriage-return/line-feet at the end, with the format "USBAUTH passwordhash", and call dd if=yourfile of=yourdevice. This will not work when uapasswd has been called with -o, using one time passwords.

pam_usbauth now comes with a daemon called usbauthd by SVN Rev20. USBAuthd recognizes if USB devices, which have a predefined serial at /etc/usbauth.conf, are plugged in or plugged out. In the config file, you may specify the following two options:

action plugin any_shell_command...
action plugout any_shell_command...

You may specify up to 10 commands for each, plugging in and plugging out events. This may be useful to automatically lock the screen if the USB device is plugged out, for example. However, any command can be binded to those events.

A sample configuration file including the new options, may be found here. Note: usbauthd is alpha, I didnt have the time yet to really test it out (but it cant harm your system, just relax).

Note: If you have something like action plugout xscreensaver-command -lock in your config file and it doesnt work, keep sure that the user who calls usbauthd has the permission to open up connections to X, otherwise the command will fail (but you wont get an error message).