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

Added the documentation to the SVN

Andrea Luzzardi 18 years ago
parent
497bbb5b40
commit
f25cf93c5e
6 changed files with 477 additions and 5 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +19
    -5
      Makefile
  2. +246
    -0
      doc/configuration
  3. +159
    -0
      doc/installation
  4. BIN
      doc/pusb_adm.1.gz
  5. BIN
      doc/pusb_hotplug.1.gz
  6. +53
    -0
      doc/upgrading

+ 19
- 5
Makefile View File

@ -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_*

+ 246
- 0
doc/configuration View File

@ -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:
<configuration>
<defaults>
<!-- default options -->
</defaults>
<devices>
<!-- devices definitions -->
</devices>
<users>
<!-- users definitions -->
</users>
<services>
<!-- services definitions -->
</services>
</configuration>
* 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:
<configuration>
<defaults>
<!-- Disable colored output by default -->
<option name="color_log">false</option>
<!-- Enable debug output -->
<option name="debug">true</option>
</defaults>
<users>
<user id="root">
<!-- Enable colored output for user "root" -->
<option name="color_log">true</option>
</user>
<user id="scox">
<!-- Disable debug output for user "scox" -->
<option name="debug">false</option>
</users>
<devices>
<device id="sandisk">
<!-- Wait 15 seconds instead of the default 10 seconds for the "sandisk"
device to be detected -->
<option name="probe_timeout">15</option>
</devices>
<services>
<service id="su">
<!-- Disable pamusb for "su" ("su" will ask for a password as usual) -->
<option name="enable">false<option>
</service>
</services>
</configuration>
===== 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:
<device id="MyDevice">
<vendor>SanDisk Corp.</vendor>
<model>Cruzer Titanium</model>
<serial>SNDKXXXXXXXXXXXXXXXX</serial>
<volume_uuid>6F6B-42FC</volume_uuid>
</device>
===== 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:
<user id="scox">
<device>MyDevice</device>
<!-- When the user "scox" removes the usb device, lock the screen and pause
beep-media-player -->
<hotplug event="lock">gnome-screensaver-command --lock</hotplug>
<hotplug event="lock">beep-media-player --pause</hotplug>
<!-- Resume operations when the usb device is plugged back and authenticated -->
<hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug>
<hotplug event="unlock">beep-media-player --play</hotplug>
</user>
===== Services =====
^ Name ^ Type ^ Description ^ Example ^
| id | Attribute | Name of the service | su |
<service id="su">
<!--
Here you can put service specific options such as "enable", "debug" etc.
See the options section of this document.
-->
</service>
===== Full example =====
This example demonstrates how to write a pamusb configuration file and how to
combine and override options.
<configuration>
<!-- Default options -->
<defaults>
<!-- Enable debug output by default-->
<option name="debug">true</option> -->
<!-- Disable one time pads by default -->
<option name="one_time_pad">false</option> -->
</defaults>
<!-- Device settings -->
<devices>
<device id="MyDevice">
<!-- This part was generated by pusb_adm -->
<vendor>SanDisk Corp.</vendor>
<model>Cruzer Titanium</model>
<serial>SNDKXXXXXXXXXXXXXXXX</serial>
<volume_uuid>6F6B-42FC</volume_uuid>
<!--
Override the debug option previously enabled by "defaults".
Everytime a user associated to that device tries to authenticate,
debugging will be disabled.
For other users using different devices, the debugging will still be
enabled.
-->
<option name="debug">disable</option>
</device>
</devices>
<!-- User settings -->
<users>
<!-- Authenticate user "root" with device "MyDevice". -->
<user id="root">
<device>MyDevice</device>
<!--
One time pads were disabled in the "defaults" section.
Now we want to enable them for the user "root" so we override the option:
-->
<option name="one_time_pad">true</option>
</user>
<!-- Authenticate user "scox" with device "MyDevice". -->
<user id="scox">
<device>MyDevice</device>
<!-- We want pamusb to work in quiet mode when authenticating "scox", so we
override the "quiet" option -->
<option name="quiet">true</option>
<!-- Hotplugging settings, used by pusb_hotplug -->
<hotplug event="lock">gnome-screensaver-command --lock</hotplug>
<hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug>
</user>
</users>
<!-- Services settings (e.g. gdm, su, sudo...) -->
<services>
<!-- Disable pamusb for gdm (a password will be asked as usual) -->
<service id="gdm">
<option name="enable">false</option>
</service>
<!--
We already disabled one time pads in the defaults section, but then
re-enabled them for the
user "root" in the users section.
Now we want to speed up console login for user root, so we simply override
again the one_time_pad option
for the "login" (console) service.
-->
<service id="login">
<option name="one_time_pad">false</option>
</service>
</services>
</configuration>
</code>

+ 159
- 0
doc/installation View File

@ -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-<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_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:
<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:
<user id="scox">
<device>MyDevice</device>
<hotplug event="lock">gnome-screensaver-command --lock</hotplug>
<hotplug event="unlock">gnome-screensaver-command --deactivate</hotplug>
</user>
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 <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.
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

BIN
doc/pusb_adm.1.gz View File


BIN
doc/pusb_hotplug.1.gz View File


+ 53
- 0
doc/upgrading View File

@ -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.

Write Preview
Loading…
Cancel
Save