From 3d9903f3bb7e326b929217121c0e5c1a68173697 Mon Sep 17 00:00:00 2001 From: Andrea Luzzardi Date: Sun, 1 Apr 2007 20:13:47 +0000 Subject: [PATCH] Updated the documentation --- doc/CONFIGURATION | 22 ++-- doc/INSTALLATION | 214 --------------------------------------- doc/QUICKSTART | 227 ++++++++++++++++++++++++++++++++++++++++++ doc/UPGRADING | 5 +- doc/pamusb-agent.1.gz | Bin 564 -> 564 bytes doc/pamusb-check.1.gz | Bin 855 -> 855 bytes doc/pamusb-conf.1.gz | Bin 455 -> 452 bytes utils/fetch_doc.rb | 2 +- 8 files changed, 245 insertions(+), 225 deletions(-) delete mode 100644 doc/INSTALLATION create mode 100644 doc/QUICKSTART diff --git a/doc/CONFIGURATION b/doc/CONFIGURATION index 0b24fb7..da72e85 100644 --- a/doc/CONFIGURATION +++ b/doc/CONFIGURATION @@ -1,6 +1,9 @@ ====== Configuration ====== + + + ===== Introduction ===== * The configuration file is formatted in XML and subdivided in 4 sections: @@ -31,7 +34,7 @@ * 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 +located in /etc/pamusb.conf, but you can tell it to use a different file by using the -c option: # /etc/pam.d/common-auth @@ -39,8 +42,9 @@ 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 pam_usb's tools. For -instance, when calling pusb_hotplug: -pusb_hotplug -c /some/other/path.conf +instance, when calling pamusb-agent: +pamusb-agent -c /some/other/path.conf + @@ -62,9 +66,9 @@ 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 +| system_pad_directory | String | .pamusb | Relative path to the user's home used to store one time pads | -| device_pad_directory | String | .pusb | Relative path to the +| device_pad_directory | String | .pamusb | Relative path to the device used to store one time pads| * Example: @@ -124,6 +128,7 @@ SNDKXXXXXXXXXXXXXXXX | 6F6B-42FC + ===== Users ===== ^ Name ^ Type ^ Description ^ @@ -132,7 +137,7 @@ Example ^ | | device | Element | id of the device associated to the user | MyDevice | -| hotplug | Element | Hotplug commands, for use with pusb_hotplug | See +| agent | Element | Agent commands, for use with pamusb-agent | See below | * Example: @@ -163,6 +168,7 @@ beep-media-player --> + ===== Full example ===== This example demonstrates how to write a pam_usb configuration file and how to @@ -180,7 +186,7 @@ combine and override options. - + SanDisk Corp. Cruzer Titanium SNDKXXXXXXXXXXXXXXXX @@ -219,7 +225,7 @@ enabled. override the "quiet" option --> - + gnome-screensaver-command --lock gnome-screensaver-command --deactivate diff --git a/doc/INSTALLATION b/doc/INSTALLATION deleted file mode 100644 index a54822d..0000000 --- a/doc/INSTALLATION +++ /dev/null @@ -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-.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_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: - - - 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. - -* GNOME (gnome-screensaver): - - MyDevice - gnome-screensaver-command --lock - gnome-screensaver-command --deactivate - - -* KDE (kscreensaver): - - MyDevice - dcop kdesktop KScreensaverIface lock - dcop kdesktop KScreensaverIface quit - - - -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. - -* 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: - - - - -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: - - - - - - - -====== It works - What next ? ====== - -* Have a look at the configuration documentation diff --git a/doc/QUICKSTART b/doc/QUICKSTART new file mode 100644 index 0000000..d502914 --- /dev/null +++ b/doc/QUICKSTART @@ -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-.tar.gz +$ cd pam_usb- + +* 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): + + MyDevice + gnome-screensaver-command --lock + gnome-screensaver-command --deactivate + + +* KDE (kscreensaver): + + MyDevice + dcop kdesktop KScreensaverIface lock + dcop kdesktop KScreensaverIface quit + + +You can execute more commands by adding extra 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: + + + + +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: + + + + + + + +===== It works - What next ? ===== + +* Have a look at the configuration documentation diff --git a/doc/UPGRADING b/doc/UPGRADING index b03c776..270b15a 100644 --- a/doc/UPGRADING +++ b/doc/UPGRADING @@ -31,10 +31,11 @@ free to remove them: # rm -rf /media/usbdisk/.auth + ===== Remove configuration files ===== -As configuration files of pam_usb 0.4.0 aren't backward compatible and are -located under /etc/pusb, the old /etc/pam_usb is no more needed. +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 diff --git a/doc/pamusb-agent.1.gz b/doc/pamusb-agent.1.gz index c4e968d977c5553ffdbfbdfc646de59e3ee6cd83..6fad245b362fe80a8c5e9d5e289917d1081ca677 100644 GIT binary patch delta 16 XcmdnOvW10RzMF$1T1a3cyDk#|Bc%hD delta 16 XcmdnOvW10RzMF%?OPzlsyDk#|Bc}tI diff --git a/doc/pamusb-check.1.gz b/doc/pamusb-check.1.gz index 988145a090eca22f271b6bfe0a00f9ebc92af02c..898bd3c269d711d002a57598769a3de78c71bbb1 100644 GIT binary patch delta 16 Xcmcc4cAbq~zMF$1N=RTMdjK;4C^rNH delta 16 Xcmcc4cAbq~zMF%?OPzlsdjK;4C_n@U diff --git a/doc/pamusb-conf.1.gz b/doc/pamusb-conf.1.gz index 2ace335a59e7c39c1980b8bedd792e2e27bc28d2..b157065d9e127f50e78b7f7ffac4e6a9336f0feb 100644 GIT binary patch literal 452 zcmV;#0XzO5iwFo?5)eiJ18`w&b#r1ZV{dL|E-?UYl3#1vFcih#^(iiX+MrgGzU*Zi zbGotw*2L7#!&pmEt!rB#OGbaXr0l~_l9Mj!1_oP4y7!#>vuFl2?i?`h^uU~Gn3Q|y zP@!QCIXvyb?cCMC6ruGJMmBi+ls8(nFo&!djgT;#U%=ID_925TJY{kFxUCi$A+%b; zy12a|_wC}e@V+hc*y%AS5Eaq+;3l*Jr?pIV)sOY2tX37FswK2#16;pp6S~09Amw?F zaty17!*c2vgij-L{ZVC{=iZ`;x?%&uZ+O)?K8psAI}ejz9bO`3`Fc}b->u4ewORis zgRsC-Zs2G|rvfymA!a&a6siN);{hH`49>w;hpDiMgWRQ&`>i6SL>8i2RN)Hx4h)Xkq)GBLr$VgWT u>n481wq9=TNTIkv2H*Y53o~56N89M#m+*V$bE-}Enfw8q4X^b00ssJ#Kj7j3 literal 455 zcmV;&0XY62iwFoxCl5vd18`w&b#r1ZV{dL|E-?UYQeAJ`AQXM)S6umNlWLmuWiQ(_ zr>mAoYhu;T!_-z4HP<#028)j_srKUsIBA=15;Eq%x#!#iG=my<4w!d(U`{kl$~|MnDghx{bCvB5fNTf+?lVn2MbxG)gyzTES8ScX$se1hz ztRDtu_MltPV=QCo3GF3^iP%Kq)?%{Ki6>O=vX3U<1ILzm>1=3%oTF>b$KW}AlJSqH z8Yk&ZIy~wWoQG7Voqq_2YnYDv*W(dSAuP5(DpE>h!L3CVUZL;6;HXXVbqq7TpMeP( x1D3+NDZ*k~FE=-&P~0GcpZ@uo87|