====== Quickstart ====== Before going ahead, make sure to follow the [[doc:upgrading|upgrading]] instructions if you're using a version of //pam_usb// prior to 0.4.0. ===== Installing ==== ==== Gentoo Linux ==== pam_usb 0.4.1 is currently keyword masked (//~arch//) on [[http://www.gentoo.org/|Gentoo]], so you'll have to unmask it before installing: # echo "sys-auth/pam_usb" >> /etc/portage/package.keywords # emerge -av ">=sys-auth/pam_usb-0.4.1" ==== Debian GNU/Linux ==== pam_usb is [[http://packages.qa.debian.org/libp/libpam-usb.html|available]] on Debian testing (lenny) and unstable (sid). # apt-get install libpam-usb pamusb-tools ==== Installing from sources ==== * **Step 1:** Download the [[http://sourceforge.net/project/showfiles.php?group_id=127530|latest release]] * **Step 2:** Unpack the distribution tarball $ tar -zxvf pam_usb-.tar.gz $ cd pam_usb- * **Step 3:** Make sure that you have installed the required dependencies //pam_usb// depends on //libxml2//, //PAM//, //HAL// and //pmount//. //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 [[http://www.kernel.org/pub/linux/libs/pam/|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** ([[http://www.ubuntu.com/|Ubuntu]], [[http://www.debian.org/|Debian]]) or **system-auth** ([[http://www.gentoo.org/|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 [[http://www.kernel.org/pub/linux/libs/pam/|PAM]] (about any application asking for a password including //su//, //sudo//, [[http://www.gnome.org/projects/gdm/|GDM]], [[http://developer.kde.org/~ossi/sw/kdm.html|KDM]], [[http://www.jwz.org/xscreensaver/|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): MyDevice gnome-screensaver-command --lock gnome-screensaver-command --deactivate * KDE (kscreensaver): MyDevice dcop kdesktop KScreensaverIface lock dcop kdesktop KScreensaverIface quit You can execute more commands by adding extra //// 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. * [[http://www.gnome.org/|GNOME]]: - Open //System// -> //Preferences// -> //Sessions// - Select //Startup Programs// and press //Add// - Enter //pamusb-agent// and press //OK// - Press //Close// * [[http://www.kde.org/|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: 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: ===== It works - What next ? ===== * Have a look at the [[doc:configuration|configuration documentation]]