Andrea Luzzardi
17 years ago
8 changed files with 245 additions and 225 deletions
Split View
Diff Options
-
+14 -8pam_usb/doc/CONFIGURATION
-
+0 -214pam_usb/doc/INSTALLATION
-
+227 -0pam_usb/doc/QUICKSTART
-
+3 -2pam_usb/doc/UPGRADING
-
BINpam_usb/doc/pamusb-agent.1.gz
-
BINpam_usb/doc/pamusb-check.1.gz
-
BINpam_usb/doc/pamusb-conf.1.gz
-
+1 -1pam_usb/utils/fetch_doc.rb
+ 14
- 8
pam_usb/doc/CONFIGURATION
View File
+ 0
- 214
pam_usb/doc/INSTALLATION
View File
| @ -1,214 +0,0 @@ | |||
| ====== Installation ====== | |||
| Before going ahead, be sure to follow the upgrading instructions if you're using | |||
| an older version of pam_usb. | |||
| ===== Requirements ===== | |||
| * Requirements for pam_usb and pusb_check: | |||
| * libpam | |||
| * libhal-storage | |||
| * libxml2 | |||
| * Requirements for pusb_hotplug and pusb_conf: | |||
| * python2.4 | |||
| * python-celementtree | |||
| * python-dbus | |||
| * python-gobject | |||
| ===== 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: Compile and install | |||
| $ make | |||
| # make install | |||
| ====== Configuring ====== | |||
| ===== Devices and Users ===== | |||
| * Copy the default configuration file to /etc/pusb/pusb.conf: | |||
| cp /etc/pusb/pusb.conf-dist /etc/pusb/pusb.conf | |||
| * Once you've connected your USB device to the computer, use pusb_conf to add it | |||
| to the configuration file: | |||
| # pusb_conf --add-device MyDevice | |||
| Name : MyDevice | |||
| Vendor : SanDisk Corp. | |||
| Model : Cruzer Titanium | |||
| Serial : SNDKXXXXXXXXXXXXXXXX | |||
| Volume UUID : 6F6B-42FC (/dev/sda1) | |||
| Save device to /etc/pusb/pusb.conf ? | |||
| [y/n] y | |||
| Done. | |||
| Note that MyDevice can be any arbitrary name you'd like. | |||
| If more devices are connected, pusb_conf will ask you which device you want to | |||
| use. | |||
| * Edit your /etc/pusb/pusb.conf config file to add the users: | |||
| <users> | |||
| <user id="root"> | |||
| <device>MyDevice</device> | |||
| </user> | |||
| <user id="scox"> | |||
| <device>MyDevice</device> | |||
| </user> | |||
| </users> | |||
| * In order to test if everything went fine, we're gonna use the pusb_check tool | |||
| which will simulate an authentication event. | |||
| # pusb_check -a -u root -s su | |||
| * Authentication request for user "root" (su) | |||
| * 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. | |||
| You don't need to setup the hotplugging feature as pam_usb.so and pusb_hotplug | |||
| are independent of each other. | |||
| * 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 pusb.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). | |||
| ===== Hotplug ===== | |||
| Hotplugging is a feature provided by pusb_hotplug that allows you to | |||
| automatically execute commands upon locking and unlocking events. Those events | |||
| are generated when you insert or remove your authentication device. | |||
| 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> | |||
| <hotplug event="lock">gnome-screensaver-command --lock</hotplug> | |||
| <hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug> | |||
| </user> | |||
| * KDE (kscreensaver): | |||
| <user id="scox"> | |||
| <device>MyDevice</device> | |||
| <hotplug event="lock">dcop kdesktop KScreensaverIface lock</hotplug> | |||
| <hotplug event="unlock">dcop kdesktop KScreensaverIface quit</hotplug> | |||
| </user> | |||
| You can also execute more commands by adding extra <hotplug> entries. | |||
| $ pusb_hotplug | |||
| pusb_hotplug[18329]: pusb_hotplug up and running. | |||
| pusb_hotplug[18329]: Watching device "MyDevice" for user "scox" | |||
| pusb_hotplug[18329]: Device "MyDevice" has been removed, locking down user | |||
| "scox"... | |||
| pusb_hotplug[18329]: Running "gnome-screensaver-command --lock" | |||
| pusb_hotplug[18329]: Locked. | |||
| pusb_hotplug[18329]: Device "MyDevice" has been inserted. Performing | |||
| verification... | |||
| pusb_hotplug[18329]: Executing "/usr/bin/pusb_check -q -c /etc/pusb/pusb.conf -u | |||
| scox -s pusb_hotplug -a" | |||
| pusb_hotplug[18329]: Authentication succeeded. Unlocking user "scox"... | |||
| pusb_hotplug[18329]: Running "gnome-screensaver-command --deactivate" | |||
| pusb_hotplug[18329]: Unlocked. | |||
| Depending on your desktop environment, you have to add pusb_hotplug to the list | |||
| of autostarted applications so it will be started automatically. | |||
| * GNOME: | |||
| - Open System -> Preferences -> Sessions | |||
| - Select Startup Programs and press Add | |||
| - Enter pusb_hotplug and press OK | |||
| - Press Close | |||
| * KDE: | |||
| - cd ~/.kde/Autostart | |||
| - ln -s /usr/bin/pusb_hotplug pusb_hotplug | |||
| ====== Troubleshooting ====== | |||
| ===== Log Analysis ===== | |||
| Both pam_usb.so and pusb_hotplug 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 | |||
| pusb_hotplug[25429]: Device "sandisk" has been inserted. Performing | |||
| verification... | |||
| pusb_hotplug[25429]: Executing "/usr/bin/pusb_check -q -c /etc/pusb/pusb.conf -u | |||
| scox -s pusb_hotplug -a" | |||
| pam_usb[25485]: Authentication request for user "scox" (pusb_hotplug) | |||
| pam_usb[25485]: Device "sandisk" is connected (good). | |||
| pam_usb[25485]: Access granted. | |||
| pusb_hotplug[25429]: Authentication succeeded. Unlocking user "scox"... | |||
| pusb_hotplug[25429]: Unlocked. | |||
| ===== Enabling debug ===== | |||
| Enabling debug messages may help you find out what's wrong. | |||
| To enable them, edit /etc/pusb/pusb.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 | |||
+ 227
- 0
pam_usb/doc/QUICKSTART
View File
| @ -0,0 +1,227 @@ | |||
| ====== Quickstart ====== | |||
| Before going ahead, make sure to follow the upgrading instructions if you're | |||
| using an older version of pam_usb. | |||
| ===== Installing ==== | |||
| ==== 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 and HAL. 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 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 | |||