Andrea Luzzardi
12 years ago
3 changed files with 1 additions and 297 deletions
Unified View
Diff Options
-
+1 -1Makefile
-
+0 -238doc/QUICKSTART
-
+0 -58doc/UPGRADING
+ 1
- 1
Makefile
View File
+ 0
- 238
doc/QUICKSTART
View File
| @ -1,238 +0,0 @@ | |||||
| ====== Quickstart ====== | |||||
| Before going ahead, make sure to follow the upgrading instructions if you're | |||||
| using a version of pam_usb prior to 0.4.0. | |||||
| ===== Installing ==== | |||||
| ==== Gentoo Linux ==== | |||||
| # emerge -av pam_usb | |||||
| ==== Ubuntu and Debian ==== | |||||
| # apt-get install libpam-usb pamusb-tools | |||||
| ==== 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, udisks 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 git ==== | |||||
| If you want to use the development version, you can fetch the sources from | |||||
| GitHub | |||||
| $ git clone git:github.com/aluzzardi/pam_usb.git | |||||
| ===== 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 | |||||
+ 0
- 58
doc/UPGRADING
View File
| @ -1,58 +0,0 @@ | |||||
| ====== Upgrading ====== | |||||
| If you're already using a pam_usb version prior to 0.4.0, you will have to | |||||
| remove the older version before installing. | |||||
| You do not have to do this if you're already using >=0.4.0. | |||||
| ===== Remove pam_usb.so from pam.d ===== | |||||
| $ grep -r pam_usb.so /etc/pam.d | |||||
| /etc/pam.d/su:auth sufficient pam_usb.so | |||||
| /etc/pam.d/gdm:auth sufficient pam_usb.so | |||||
| [...] | |||||
| Edit every matching file and remove the pam_usb.so lines. | |||||
| At the end of the operation, there shouldn't be any file contanining a reference | |||||
| to pam_usb.so: | |||||
| $ grep -r pam_usb /etc/pam.d | |||||
| $ | |||||
| ===== Remove .auth directories ===== | |||||
| Older versions of pam_usb used to create .auth directories in both the device | |||||
| and the user's home directory. Those directories aren't used anymore, so feel | |||||
| free to remove them: | |||||
| # rm -rf /root/.auth | |||||
| # rm -rf /home/scox/.auth | |||||
| # rm -rf /media/usbdisk/.auth | |||||
| ===== Remove configuration files ===== | |||||
| As configuration files of pam_usb 0.4.0 aren't backward compatible, the old | |||||
| /etc/pam_usb is no more needed. | |||||
| # rm -rf /etc/pam_usb | |||||
| ===== Deinstall pam_usb ===== | |||||
| If you installed the old pam_usb version using your operating system's package | |||||
| manager, then remove it by the same mean. | |||||
| Otherwise, you can remove it by hand by performing the following instructions: | |||||
| # rm -f /usr/bin/usbadm /usr/share/man/usbadm.1.gz | |||||
| # rm -f /usr/bin/usbhotplug /etc/hotplug.d/default/pamusb.hotplug | |||||
| /etc/pam.d/usbhotplug | |||||
| # rm -f /lib/security/pam_usb.so | |||||
| ===== Next ===== | |||||
| Go aheand and install the new version. | |||||