pam_usb

The Pam_usb Project

Description

usbhotplug is a hotplug agent (coded in C and using the PAM API) that will automagically start a lock handler when the usb device is removed,
and an unlock handler when the usb device is plugged back in and authenticated through pam_usb.

The 2 default handlers included with usbhotplug will start or kill xlock when the usb device is added/removed.

In short as soon as you remove the usb device xlock will lock your system, and when you plug it back you'll get back to your desktop.

Unlocking the system is done after usbhotplug authenticated the usb device, so a wrong device won't unlock your system.

Those handlers are fully customizables (they are shell scripts executed by usbhotplug), so you can let your system do whatever you want on key remotion or addition+authentication.
All the authentication is done without user input but with the secret keys stored on the usb devie and the publics stored on the user's home.

Background

Before going ahead, I should introduce you to hotplug.
Hotplug can be divided into the parts: the kernel hotplug, and the userspace tools (linux-hotplug.sf.net).
The kernel hotplug will execute a handler for every hotplug event, which can be for example the userspace hotplug (linux-hotplug.sf.net) or our own handler (usbhotplug).

So here we have two situations:

Note that if you emerged pam_usb with Gentoo you can also skip the next section and jump to Configuring.

Setting up

Do NOT do this if you're already using hotplug (http://linux-hotplug.sf.net) as it will make it not work anymore (usbhotplug will work anyway).

To tell the kernel to execute our handler, you'll have to edit the sysctl option by writing:
sysctl -w kernel.hotplug=/usr/bin/usbhotplug
As soon as you reboot the kernel will forget this options. To make it permanent add kernel.hotplug=/usr/bin/usbhotplug into /etc/sysctl.conf.

Configuring

By default, usbhotplug is disabled. The configuration file is located at /etc/pam_usb/hotplug.conf. To enable it, set ENABLE=1.
The default handler usbhotplug will start is /etc/pam_usb/handlers/xlock.h. You may want to change it or not, the handler called by usbhotplug is just a shell script.
You can now test it by running ACTION=add PRODUCT=none usbhotplug block
If the test runned okay, that's it, you're done.
You can now remove your key and see the handler starting (xlock running), and as soon you plug the key back in the unlock handler will start (you'll get back to your desktop).
See the hotplug.conf file for more options.

Common problems