Andrea Luzzardi
12 years ago
3 changed files with 1 additions and 297 deletions
Split 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. | |||