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:
- Hotplug userspace tools are installed: During the make install pam_usb already installed a pamusb.hotplug agent
into /etc/hotplug.d/default/, so you don't have to bother about it. Jump to the Configuring section.
- Hotplug userspace tools are not installed: In this case, we want the
kernel to be aware that it must send hotplug
events to us. Follow the instructions as described in the next section Setting up
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
- bash: xlock: command not found: You are missing xlock, install it.
- xlock: unable to open display .: The handler isn't authorized to connect
to X. Use xhost to allow it (xhost + will allow every connection, use with caution).