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.