Fincer
/
pam_usb
mirror of https://github.com/Fincer/pam_usb
1
0
Fork 0
Code Issues 0 Releases 4 Wiki Activity
Browse Source

Updated the documentation

master
Andrea Luzzardi 17 years ago
parent
c8a894f17b
commit
43105e8d5a
8 changed files with 245 additions and 225 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +14
    -8
      pam_usb/doc/CONFIGURATION
  2. +0
    -214
      pam_usb/doc/INSTALLATION
  3. +227
    -0
      pam_usb/doc/QUICKSTART
  4. +3
    -2
      pam_usb/doc/UPGRADING
  5. BIN
      pam_usb/doc/pamusb-agent.1.gz
  6. BIN
      pam_usb/doc/pamusb-check.1.gz
  7. BIN
      pam_usb/doc/pamusb-conf.1.gz
  8. +1
    -1
      pam_usb/utils/fetch_doc.rb

+ 14
- 8
pam_usb/doc/CONFIGURATION View File

@ -1,6 +1,9 @@
====== Configuration ====== ====== Configuration ======
===== Introduction ===== ===== Introduction =====
* The configuration file is formatted in XML and subdivided in 4 sections: * The configuration file is formatted in XML and subdivided in 4 sections:
@ -31,7 +34,7 @@
* Location of the configuration file * Location of the configuration file
By default, pam_usb.so and its tools will look for 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: using the -c option:
# /etc/pam.d/common-auth # /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 auth required pam_unix.so nullok_secure
You will also have to use the -c option when calling pam_usb's tools. For 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 | hostname | String | Computer's hostname | Computer name. Must be
unique accross computers using the same device | 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 | 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| device used to store one time pads|
* Example: * Example:
@ -124,6 +128,7 @@ SNDKXXXXXXXXXXXXXXXX |
<volume_uuid>6F6B-42FC</volume_uuid> <volume_uuid>6F6B-42FC</volume_uuid>
</device> </device>
===== Users ===== ===== Users =====
^ Name ^ Type ^ Description ^ ^ Name ^ Type ^ Description ^
@ -132,7 +137,7 @@ Example ^
| |
| device | Element | id of the device associated to the user | | device | Element | id of the device associated to the user |
MyDevice | MyDevice |
| hotplug | Element | Hotplug commands, for use with pusb_hotplug | See
| agent | Element | Agent commands, for use with pamusb-agent | See
below | below |
* Example: * Example:
@ -163,6 +168,7 @@ beep-media-player -->
</service> </service>
===== Full example ===== ===== Full example =====
This example demonstrates how to write a pam_usb configuration file and how to This example demonstrates how to write a pam_usb configuration file and how to
@ -180,7 +186,7 @@ combine and override options.
<!-- Device settings --> <!-- Device settings -->
<devices> <devices>
<device id="MyDevice"> <device id="MyDevice">
<!-- This part was generated by pusb_conf -->
<!-- This part was generated by pamusb-conf -->
<vendor>SanDisk Corp.</vendor> <vendor>SanDisk Corp.</vendor>
<model>Cruzer Titanium</model> <model>Cruzer Titanium</model>
<serial>SNDKXXXXXXXXXXXXXXXX</serial> <serial>SNDKXXXXXXXXXXXXXXXX</serial>
@ -219,7 +225,7 @@ enabled.
override the "quiet" option --> override the "quiet" option -->
<option name="quiet">true</option> <option name="quiet">true</option>
<!-- Hotplugging settings, used by pusb_hotplug -->
<!-- Agent settings, used by pamusb-agent -->
<hotplug event="lock">gnome-screensaver-command --lock</hotplug> <hotplug event="lock">gnome-screensaver-command --lock</hotplug>
<hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug> <hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug>
</user> </user>


+ 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

+ 3
- 2
pam_usb/doc/UPGRADING View File

@ -31,10 +31,11 @@ free to remove them:
# rm -rf /media/usbdisk/.auth # rm -rf /media/usbdisk/.auth
===== Remove configuration files ===== ===== 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 # rm -rf /etc/pam_usb


BIN
pam_usb/doc/pamusb-agent.1.gz View File


BIN
pam_usb/doc/pamusb-check.1.gz View File


BIN
pam_usb/doc/pamusb-conf.1.gz View File


+ 1
- 1
pam_usb/utils/fetch_doc.rb View File

@ -10,7 +10,7 @@ require 'open-uri'
BASE_URI = 'http://www.pamusb.org/wiki/doc/' BASE_URI = 'http://www.pamusb.org/wiki/doc/'
DOC_PATH = '../doc/' DOC_PATH = '../doc/'
DOCS = [ 'installation', 'upgrading', 'configuration', 'faq' ]
DOCS = [ 'quickstart', 'upgrading', 'configuration', 'faq' ]
MANS = [ 'pamusb-check', 'pamusb-agent', 'pamusb-conf' ] MANS = [ 'pamusb-check', 'pamusb-agent', 'pamusb-conf' ]
REPLACE_LIST = [ REPLACE_LIST = [


Write Preview
Loading…
Cancel
Save