|
|
====== Quickstart ======
|
|
|
|
|
|
Before going ahead, make sure to follow the upgrading instructions if you're
|
|
|
using an older version of pam_usb.
|
|
|
|
|
|
===== Installing ====
|
|
|
|
|
|
|
|
|
==== Installing from sources ====
|
|
|
* Step 1: Download the latest release
|
|
|
* Step 2: Unpack the distribution tarball
|
|
|
|
|
|
$ tar -zxvf pam_usb-<version>.tar.gz
|
|
|
$ cd pam_usb-<version>
|
|
|
|
|
|
* Step 3: Make sure that you have installed the required dependencies
|
|
|
|
|
|
pam_usb depends on libxml2, PAM and HAL. pam_usb's tools (pamusb-agent,
|
|
|
pamusb-conf) depends on python, python-celementtree and python-gobject.
|
|
|
|
|
|
* Step 3: Compile and install
|
|
|
|
|
|
$ make
|
|
|
# make install
|
|
|
|
|
|
==== Installing from Subversion ====
|
|
|
|
|
|
If you want to use the development version, you can fetch the sources from
|
|
|
subversion
|
|
|
$ svn co https:pamusb.svn.sourceforge.net/svnroot/pamusb/trunk/pam_usb
|
|
|
|
|
|
===== Setting up =====
|
|
|
|
|
|
|
|
|
|
|
|
==== Devices and Users ====
|
|
|
|
|
|
* Once you've connected your USB device to the computer, use pamusb-conf to add
|
|
|
it to the configuration file:
|
|
|
|
|
|
# pamusb-conf --add-device MyDevice
|
|
|
Please select the device you wish to add.
|
|
|
* Using "SanDisk Corp. Cruzer Titanium (SNDKXXXXXXXXXXXXXXXX)" (only option)
|
|
|
Which volume would you like to use for storing data ?
|
|
|
* Using "/dev/sda1 (UUID: <6F6B-42FC>)" (only option)
|
|
|
Name : MyDevice
|
|
|
Vendor : SanDisk Corp.
|
|
|
Model : Cruzer Titanium
|
|
|
Serial : SNDKXXXXXXXXXXXXXXXX
|
|
|
Volume UUID : 6F6B-42FC (/dev/sda1)
|
|
|
Save to /etc/pamusb.conf ?
|
|
|
[Y/n] y
|
|
|
Done.
|
|
|
|
|
|
Note that MyDevice can be any arbitrary name you'd like. Also, you can add as
|
|
|
many devices as you want.
|
|
|
|
|
|
* Users
|
|
|
|
|
|
Now that we have added the devices, we have to configure the users.
|
|
|
|
|
|
# pamusb-conf --add-user root
|
|
|
Which device would you like to use for authentication ?
|
|
|
* Using "MyDevice" (only option)
|
|
|
User : root
|
|
|
Device : MyDevice
|
|
|
Save to /etc/pamusb.conf ?
|
|
|
[Y/n] y
|
|
|
Done.
|
|
|
|
|
|
Repeat this step for every other username you'd like to use pam_usb with (e.g.
|
|
|
pamusb-conf --add-user MyUsername).
|
|
|
|
|
|
* In order to check if everything went fine, we are going to use the
|
|
|
pamusb-check tool which will simulate an authentication event.
|
|
|
|
|
|
# pamusb-check root
|
|
|
* Authentication request for user "root" (pamusb-check)
|
|
|
* Device "MyDevice" is connected (good).
|
|
|
* Performing one time pad verification...
|
|
|
* Verification match, updating one time pads...
|
|
|
* Access granted.
|
|
|
|
|
|
|
|
|
|
|
|
==== PAM Module ====
|
|
|
|
|
|
The PAM module pam_usb.so is used to let applications authenticate you using
|
|
|
your USB device instead of asking your password. The default password-based
|
|
|
authentication will be used as fallback if the device authentication goes wrong.
|
|
|
|
|
|
* Depending on the operating system you're using, you have to tell PAM to use
|
|
|
pam_usb.so as default authentication method. There should be a file named
|
|
|
either common-auth (Gentoo) under /etc/pam.d/. If you do NOT have neither of
|
|
|
those files, you'll have to edit each pam.d service file you want to use (e.g.
|
|
|
/etc/pam.d/su, /etc/pam.d/gdm and so on).
|
|
|
|
|
|
* Locate the following line on /etc/pam.d/common-auth or /etc/pam.d/system-auth:
|
|
|
|
|
|
auth required pam_unix.so nullok_secure
|
|
|
|
|
|
* And change it to look something like that:
|
|
|
|
|
|
auth sufficient pam_usb.so
|
|
|
auth required pam_unix.so nullok_secure
|
|
|
|
|
|
* You should now be able to authenticate the users configured in pamusb.conf
|
|
|
using your USB device:
|
|
|
|
|
|
scox $ su
|
|
|
* pam_usb v.SVN
|
|
|
* Authentication request for user "root" (su)
|
|
|
* Device "MyDevice" is connected (good).
|
|
|
* Performing one time pad verification...
|
|
|
* Verification match, updating one time pads...
|
|
|
* Access granted.
|
|
|
|
|
|
* Try to authenticate to a different application. pam_usb.so should work with
|
|
|
any application using xscreensaver and many more).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
==== Agent ====
|
|
|
|
|
|
The pam_usb agent (pamusb-agent) allows you to automatically execute commands
|
|
|
upon locking and unlocking events. Those events are generated when you insert or
|
|
|
remove your authentication device.
|
|
|
To configure the commands, you have to edit pam_usb's configuration file
|
|
|
(/etc/pamusb.conf) and add agent entries into your user section.
|
|
|
|
|
|
For instance, you could automatically start your screensaver as soon as you
|
|
|
remove the device, and deactivate it when you plug the device back.
|
|
|
|
|
|
* GNOME (gnome-screensaver):
|
|
|
<user id="scox">
|
|
|
<device>MyDevice</device>
|
|
|
<agent event="lock">gnome-screensaver-command --lock</agent>
|
|
|
<agent event="unlock">gnome-screensaver-command --deactivate</agent>
|
|
|
</user>
|
|
|
|
|
|
* KDE (kscreensaver):
|
|
|
<user id="scox">
|
|
|
<device>MyDevice</device>
|
|
|
<agent event="lock">dcop kdesktop KScreensaverIface lock</agent>
|
|
|
<agent event="unlock">dcop kdesktop KScreensaverIface quit</agent>
|
|
|
</user>
|
|
|
|
|
|
You can execute more commands by adding extra <agent> entries.
|
|
|
|
|
|
|
|
|
$ pamusb-agent
|
|
|
pamusb-agent[18329]: pamusb-agent up and running.
|
|
|
pamusb-agent[18329]: Watching device "MyDevice" for user "scox"
|
|
|
pamusb-agent[18329]: Device "MyDevice" has been removed, locking down user
|
|
|
"scox"...
|
|
|
pamusb-agent[18329]: Running "gnome-screensaver-command --lock"
|
|
|
pamusb-agent[18329]: Locked.
|
|
|
pamusb-agent[18329]: Device "MyDevice" has been inserted. Performing
|
|
|
verification...
|
|
|
pamusb-agent[18329]: Executing "/usr/bin/pamusb-check --quiet
|
|
|
--config=/etc/pamusb.conf --service=pamusb-agent scox"
|
|
|
pamusb-agent[18329]: Authentication succeeded. Unlocking user "scox"...
|
|
|
pamusb-agent[18329]: Running "gnome-screensaver-command --deactivate"
|
|
|
pamusb-agent[18329]: Unlocked.
|
|
|
|
|
|
Depending on your desktop environment, you have to add pamusb-agent to the list
|
|
|
of autostarted applications so it will be started automatically.
|
|
|
|
|
|
* GNOME:
|
|
|
- Open System -> Preferences -> Sessions
|
|
|
- Select Startup Programs and press Add
|
|
|
- Enter pamusb-agent and press OK
|
|
|
- Press Close
|
|
|
|
|
|
* KDE:
|
|
|
- cd ~/.kde/Autostart
|
|
|
- ln -s /usr/bin/pamusb-agent pamusb-agent
|
|
|
|
|
|
===== Troubleshooting =====
|
|
|
|
|
|
|
|
|
==== Log Analysis ====
|
|
|
|
|
|
Both pam_usb.so and pamusb-agent use the syslog facility to log authentication
|
|
|
attempts.
|
|
|
This can be useful for GUI-driven applications (for instance GDM) where you
|
|
|
don't get to see console output.
|
|
|
Messages are logged with the AUTH facility, they are usually written to
|
|
|
/var/log/auth.log but may vary
|
|
|
depending on the operating system you're using.
|
|
|
|
|
|
# tail -f /var/log/auth.log
|
|
|
pamusb-agent[25429]: Device "sandisk" has been inserted. Performing
|
|
|
verification...
|
|
|
pamusb-agent[25429]: Executing "/usr/bin/pamusb-check --quiet
|
|
|
--config=/etc/pamusb.conf --service=pamusb-agent scox"
|
|
|
pam_usb[25485]: Authentication request for user "scox" (pamusb-agent)
|
|
|
pam_usb[25485]: Device "sandisk" is connected (good).
|
|
|
pam_usb[25485]: Access granted.
|
|
|
pamusb-agent[25429]: Authentication succeeded. Unlocking user "scox"...
|
|
|
pamusb-agent[25429]: Unlocked.
|
|
|
|
|
|
|
|
|
==== Enabling debug ====
|
|
|
|
|
|
Enabling debug messages may help you find out what's wrong.
|
|
|
|
|
|
To enable them, edit /etc/pamusb.conf and set the following option:
|
|
|
<defaults>
|
|
|
<option name="debug">true</option>
|
|
|
</defaults>
|
|
|
|
|
|
If you wish, you could enable debug messages only for a specific user, device or
|
|
|
service.
|
|
|
For instance, if you want to enable debug messages only for the sudo service,
|
|
|
you could do the following:
|
|
|
|
|
|
<services>
|
|
|
<service id="sudo">
|
|
|
<option name="debug">true</option>
|
|
|
</service>
|
|
|
</services>
|
|
|
|
|
|
===== It works - What next ? =====
|
|
|
|
|
|
* Have a look at the configuration documentation
|