diff --git a/README.md b/README.md index b2e1760..36e1d77 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,211 @@ Tools * `pamusb-conf`: configuration helper. * `pamusb-check`: integrate pam\_usb's authentication engine within your scripts or applications. +Installing +========== + +pam_usb is included in most Linux distributions out there. + +If you happen to run Ubuntu or Debian, run: + + # apt-get install libpam-usb pamusb-tools + +Compiling from source +--------------------- + +Before proceeding, make sure all dependencies are installed: libxml2, pam, udisks and pmount are installed + + $ make + # make install + +Configuring +=========== + +By default, pam_usb will read its configuration from `/etc/pamusb.conf` + +For most operations, you can use ``pamusb-conf`` which will take care of generating the configuration for you. + +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. + +Next, configure users you want to be able to authenticate with pam_usb: + + # 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. + +Check the configuration +----------------------- + +You can run `pamusb-check` anytime to check if everything is correctly worked. +This tool will simulate an authentication request (requires your device to be connected, otherwise it will fail). + + # 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. + + +Setting up the PAM module +------------------------- + +To add pam_usb into the system authentication process, we need to edit `/etc/pam.d/common-auth` + + NOTE: If you are using RedHat or Fedora this file can be known as /etc/pam/system-auth. + +Your default PAM common-auth configuration should include the following line: + + auth required pam_unix.so nullok_secure + +This is a current standard which uses passwords to authenticate a user. + +Alter your /etc/pam.d/common-auth configuration to: + + auth sufficient pam_usb.so + auth required pam_unix.so nullok_secure + +The `suffient` keyword means that if pam_usb allows the authentication, then no password will be asked. +If the authentication fails, then the default password-based authentication will be used as fallback. + +If you change it to `required`, it means that *both* the USB flash drive and the password will be required to grant +access to the system. + +At this point, you should be able to authenticate with the relevant USB device plugged-in. + + 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. + +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. + +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: + + + + + +You can enable debug messages only for a specific user, device or service. + + + + + + +