Finally found time to fiddle around with the fingerprint reader, and getting it to work was easier than I thought. The HowTo in the ThinkWiki was very helpful, as usual.
There are 4 components to make the whole thing work:
Just installe the downloaded .deb file with
dpkg -i dpkg -i bioapi_1.2.3_i386.deb
Ignore the warning about not finding /usr/lib/libqtpwbsp.so, it's not fatal.
The software comes in a zip file, so
apt-get install unzip
if you haven't got it installed already. Then create a new directory and change into it, then unpack and install the driver:
mkdir fingerprint-driver
cd fingerprint-driver
unzip -q /path/to/the/downloaded/UPEK_BSP_file.zip
sh install.sh
It's necessary to use a patch from http://badcode.de/downloads/fingerprint.patch to make the pam module work, I also attached the fingerprint.patch file below in case it vanishes from the current URL.
Otherwise the installation is straightforward with the usual 3 steps ./configure, make and make install: (make sure you have libpam-dev or specifically libpam0g-dev installed)
tar -xjf /path/to/the/downloaded/pam_bioapi-0.2.1.tar.bz2
cd pam_bioapi-0.2.1/
patch -p0 < /path/to/the/downloaded/fingerprint.patch
./configure
make
make install
Since the BioAPI framework could work with various biometric devices each and every one of them has a unique serial number (a long hexadecimal number) called Module ID. The process of gathering sample fingerprints and the PAM configuration both need the Module ID of your fingerprint reader. You can print the ID in the needed format with the following rather ugly command:
BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: \(.\{9\}\)\(.\{4\}\)\(.\{4\}\)\(.\{4\}\)\(.*\)/\1-\2-\3-\4-\5/gp}"The result, in my case {5550454b-2054-464d-2f45-535320425350} (check if your ID differs and change accordingly in the following steps), is needed in several places. First create a directory in /etc/bioapi1.10/pam with that name, e.g. with
mkdir -p /etc/bioapi1.10/pam/{5550454b-2054-464d-2f45-535320425350}Into that directory the files containing the sample fingerprints (one file per user, with .bir as extension) need to be copied. Creating these files is done using the Sample program that comes with the UPEK software (in the NonGUI_Sample subdirectory), which needs to be made executable first. Then run it (from the current directory with ./Sample), choose "enroll" and enter a valid username. You'll then be prompted to collect 3 fingerprints. Once you're done, choose "quit" and look into the current directory. It should contain a .bir-file for the username you just entered. Copy that file into the directory created in the last step. E.g. for the user spiney:
cd /path/to/fingerprint-driver/NonGUI_SampleRepeat for each user you want to use the fingerprint reader with.
chmod a+x Sample
./Sample
cp spiney.bir /etc/bioapi1.10/pam/{5550454b-2054-464d-2f45-535320425350}
The next and final step is to configure services to use the pam_bioapi module as authentication source. For each PAM-aware service there's a configuration file in /etc/pam.d/ plus the fallback configuration file called common-auth which you could use to enable the reader system-wide. I just enabled it for gdm (the Gnome Display Manager, i.e. the graphical login) and login (for the text consoles) by adding the following line before the line with @include common-auth:
auth sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/Note: by using the complete path to the pam_bioapi.so module it's not necessary to copy it to /lib/security.
After that logging in using the fingerprint reader should work for configured services. If not, check /var/log/auth.log for any pam-related error messages.
For PAM-aware applications like xscreensaver which are run as normal user without root privileges it's necessary to change the permissions on two files so that files can be read and written:
echo /proc/bus/usb/`lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`
Either set to permissions on both to world read/writeable (pass 666 to chmod, probably ok security-wise since notebooks are single user systems in most cases) or assign a special group to them and give it write permission, and then add all users that should be able to use the fingerprint reader to that group. In my case I used the group adm, because my normal user was already member in it (I do like to read log files without changing to root). So I did the following
chgrp adm /var/log/BSP.log
chmod g+rw /var/log/BSP.log
DEVICE=/proc/bus/usb/`lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`
chgrp adm $DEVICE
chmod g+rw $DEVICE
Since you have to set the permissions on the proc entry every time you boot (or come back from suspend/hibernation), it's best to put the last three lines into some shell script that gets run every time you boot.
Now also non-root users can use the fingerprint reader. The only application at the moment that comes to mind and is PAM-capable is xscreensaver. It needs a patch from http://nax.hn.org/pub/bioapi/xscreensaver-4.22_alternativeAuth.diff by Josef Hajas so that you are first asked to swipe your finger and it falls only back to password authentication when that fails. You can either get the source code from the xscreensaver website, but if you run Debian sid you can also download my patched xscreensaver package (built from the current source from Debian via apt-get source) which is attached below. I'll try to keep them updated whenever there's a new version in Debian until the patch makes it into the xscreensaver source code upstream. But I disclaim all warranties regarding that package, so beware!
Now just change /etc/pam.d/xscreensaver to
#
# /etc/pam.d/xscreensaver - PAM behavior for xscreensaver
#
auth sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/
@include common-auth
and add the following option
alternativeAuth: True
to your ~/.xscreensaver configuration file, restart xscreensaver and you're set. Lock the screen, press a key and there should be the window telling you to swipe your finger over the reader.
Again, if it doesn't work, take a look into /var/log/auth.log and check those file permissions.
Since the original patch was sometimes confusing to the user (see Brice Goglin's comment below) I tried to come up with a different approach: use a different PAM configuration for xscreensaver when using the alternativeAuth option.
Below is the patch (xscreensaver-4.23_fingerprint.patch) and also an updated version of the package for Debian sid (xscreensaver_4.23-3fingerprint_i386.deb). To use it, follow the instructions above, but instead of modifying /etc/pam.d/xscreensaver (if you did already, remove the bioapi line again), create a new file /etc/pam.d/xscreensaver-alternative with the following content:
#
# /etc/pam.d/xscreensaver-alternative - PAM behavior for xscreensaver
# when running with alternativeAuth
#
auth sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/
Again, I disclaim all warranties regarding the patch and the package, so beware!