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