diff --git a/README.md b/README.md index 5609cf2..0ad6903 100644 --- a/README.md +++ b/README.md @@ -23,229 +23,9 @@ 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 - -Gentoo (You may need to unmask `sys-auth/pam_usb` or use `--automask-write`): - - # emerge pam_usb - -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): - -```xml - - MyDevice - gnome-screensaver-command --lock - gnome-screensaver-command --deactivate - -``` - -KDE (kscreensaver): - -```xml - - 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 - -Configuration Reference ------------------------ - -There are many more options available to fine tune pam_usb. - -Check out the [configuration reference](https://github.com/aluzzardi/pam_usb/blob/master/doc/CONFIGURATION.md). - -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: - -```xml - - - -``` -You can enable debug messages only for a specific user, device or service. - -```xml - - - - - -``` +Getting Started +---------------- +* [Install](https://wiki.github.com/aluzzardi/pam_usb/Install) pam_usb on your system +* Read the [Getting Started Guide](https://wiki.github.com/aluzzardi/pam_usb/Getting-Started) +* Have a look at the [Configuration File Reference](https://wiki.github.com/aluzzardi/pam_usb/Configuration) +* Problem? See the [Troubleshooting Guide](https://wiki.github.com/aluzzardi/pam_usb/Troubleshooting)