diff --git a/pam_usb/Makefile b/pam_usb/Makefile index 7247335..c5e688c 100644 --- a/pam_usb/Makefile +++ b/pam_usb/Makefile @@ -36,6 +36,18 @@ PUSB_ADM := tools/pusb_adm PUSB_HOTPLUG := tools/pusb_hotplug TOOLS_DEST := $(DESTDIR)/usr/bin +# Conf +CONFS := doc/pusb.conf-dist +CONFS_DEST := $(DESTDIR)/etc/pusb + +# Doc +DOCS := doc/installation doc/configuration doc/upgrading +DOCS_DEST := $(DESTDIR)/usr/share/doc/pamusb + +# Man +MANS := doc/pusb_adm.1.gz doc/pusb_hotplug.1.gz +MANS_DEST := $(DESTDIR)/usr/share/man/man1 + # Binaries RM := rm INSTALL := install @@ -60,13 +72,15 @@ clean : $(RM) -f $(PAM_USB) $(PUSB_CHECK) $(OBJS) $(PUSB_CHECK_OBJS) $(PAM_USB_OBJS) install : all - $(MKDIR) -p /etc/pusb + $(MKDIR) -p $(CONFS_DEST) $(DOCS_DEST) $(INSTALL) -m644 $(PAM_USB) $(PAM_USB_DEST) - $(INSTALL) -m755 $(PUSB_CHECK) $(TOOLS_DEST) - $(INSTALL) -m755 $(PUSB_ADM) $(TOOLS_DEST) - $(INSTALL) -m755 $(PUSB_HOTPLUG) $(TOOLS_DEST) - $(INSTALL) -m644 doc/pusb.conf-dist /etc/pusb + $(INSTALL) -m755 $(PUSB_CHECK) $(PUSB_ADM) $(PUSB_HOTPLUG) $(TOOLS_DEST) + $(INSTALL) -m644 $(CONFS) $(CONFS_DEST) + $(INSTALL) -m644 $(DOCS) $(DOCS_DEST) + $(INSTALL) -m644 $(MANS) $(MANS_DEST) deinstall : $(RM) -f $(PAM_USB_DEST)/$(PAM_USB) $(RM) -f $(TOOLS_DEST)/$(PUSB_CHECK) $(TOOLS_DEST)/$(PUSB_ADM) $(TOOLS_DEST)/$(PUSB_HOTPLUG) + $(RM) -rf $(DOCS_DEST) + $(RM) -f $(MANS_DEST)/pusb_* diff --git a/pam_usb/doc/configuration b/pam_usb/doc/configuration new file mode 100644 index 0000000..1a381a6 --- /dev/null +++ b/pam_usb/doc/configuration @@ -0,0 +1,246 @@ +====== Configuration ====== + +===== Introduction ===== + +* The configuration file is formatted in XML and subdivided in 4 sections: + - Default options, shared among every device, user and service + - Devices declaration and settings + - Users declaration and settings + - Services declaration and settings + +* The syntax is the following: + + + + + + + + + + + + + + + + + + +* Location of the configuration file + +By default, pam_usb.so and its tools will look for the configuration file +located in /etc/pusb/pusb.conf, but you can tell it to use a different file by +using the -c option: + +# /etc/pam.d/common-auth +auth sufficient pam_usb.so -c /some/other/path.conf +auth required pam_unix.so nullok_secure + +You will also have to use the -c option when calling pamusb's tools. For +instance, when calling pusb_hotplug: +pusb_hotplug -c /some/other/path.conf + +===== Options ===== + +^ Name ^ Type ^ Default value ^ Description ^ +| enable | Boolean | true | Enable pamusb +| +| debug | Boolean | false | Enable debug messages +| +| quiet | Boolean | false | Quiet mode (no verbose +output) | +| color_log | Boolean | true | Enable colored output +| +| one_time_pad | Boolean | true | Enable the use of one +time pads | +| probe_timeout | Integer | 10 | Time (in seconds) to +wait for the volume to be detected| +| hostname | String | Computer's hostname | Computer name. Must be +unique accross computers using the same device | + +| system_pad_directory | String | .pusb | Relative path to the +user's home used to store one time pads | +| device_pad_directory | String | .pusb | Relative path to the +device used to store one time pads| + +* Example: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +===== Devices ===== + +^ Name ^ Type ^ Description ^ +Example ^ +| id | Attribute | Arbitrary device name | +MyDevice | +| vendor | Element | device's vendor name | +SanDisk Corp. | +| model | Element | device's model name | +Cruzer Titanium | +| serial | Element | serial number of the device | +SNDKXXXXXXXXXXXXXXXX | +| volume_uuid | Element | UUID of the device's volume used to store pads | +6F6B-42FC | + + +* Example: + + +SanDisk Corp. +Cruzer Titanium +SNDKXXXXXXXXXXXXXXXX +6F6B-42FC + + +===== Users ===== + +^ Name ^ Type ^ Description ^ +Example ^ +| id | Attribute | Login of the user | root +| +| device | Element | id of the device associated to the user | +MyDevice | +| hotplug | Element | Hotplug commands, for use with pusb_hotplug | See +below | + +* Example: + + +MyDevice + + +gnome-screensaver-command --lock +beep-media-player --pause + + +gnome-screensaver-command --deactivate +beep-media-player --play + + +===== Services ===== + +^ Name ^ Type ^ Description ^ Example ^ +| id | Attribute | Name of the service | su | + + + + + +===== Full example ===== + +This example demonstrates how to write a pamusb configuration file and how to +combine and override options. + + + + + + --> + + --> + + + + + + + SanDisk Corp. + Cruzer Titanium + SNDKXXXXXXXXXXXXXXXX + 6F6B-42FC + + + + + + + + + + + + MyDevice + + + + + + + + MyDevice + + + + + + gnome-screensaver-command --lock + gnome-screensaver-command --deactivate + + + + + + + + + + + + + + + + + + diff --git a/pam_usb/doc/installation b/pam_usb/doc/installation new file mode 100644 index 0000000..4990768 --- /dev/null +++ b/pam_usb/doc/installation @@ -0,0 +1,159 @@ +====== Installation ====== + +Before going ahead, be sure to follow the upgrading instructions if you're using +an older version of pamusb. + +===== Requirements ===== +* Requirements for pam_usb and pusb_check: + * libhal-storage + * libxml2 + +* Requirements for pusb_hotplug and pusb_adm: + * 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-.tar.gz +$ cd pam_usb- + +* 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_adm to add it +to the configuration file: + +# pusb_adm --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_adm will ask you which device you want to +use. + +* Edit your /etc/pusb/pusb.conf config file to add the users: + + + MyDevice + + + + MyDevice + + + +* 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: + + + MyDevice + gnome-screensaver-command --lock + gnome-screensaver-command --deactivate + + +Replace gnome-screensaver-command --lock and gnome-screensaver-command --unlock +with any command you want to execute. You can also execute more commands by +adding extra 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. +For instance, with GNOME: + +- Open System -> Preferences -> Sessions +- Select Startup Programs and press Add +- Enter pusb_hotplug and press OK +- Press Close + +====== It works - What next ? ====== + +* Have a look at the configuration documentation diff --git a/pam_usb/doc/pusb_adm.1.gz b/pam_usb/doc/pusb_adm.1.gz new file mode 100644 index 0000000..c2a03ae Binary files /dev/null and b/pam_usb/doc/pusb_adm.1.gz differ diff --git a/pam_usb/doc/pusb_hotplug.1.gz b/pam_usb/doc/pusb_hotplug.1.gz new file mode 100644 index 0000000..3626116 Binary files /dev/null and b/pam_usb/doc/pusb_hotplug.1.gz differ diff --git a/pam_usb/doc/upgrading b/pam_usb/doc/upgrading new file mode 100644 index 0000000..4715456 --- /dev/null +++ b/pam_usb/doc/upgrading @@ -0,0 +1,53 @@ +====== Upgrading ====== + +If you're already using a pamusb 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 or Subversion. + +===== 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 pamusb 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 pamusb 0.4.0 aren't backward compatible and are +located under /etc/pusb, the old /etc/pam_usb is no more needed. + +# rm -rf /etc/pam_usb + +===== Deinstall pamusb ===== + +If you installed the old pamusb 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.